@happyvertical/smrt-ads

npm install @happyvertical/smrt-ads

import {
  AdDeliveryTier, AdDeliveryTierCollection,
  AdGroup, AdGroupCollection,
  AdVariation, AdVariationCollection,
  AdEvent, AdEventCollection,
  AdEventType, PricingModel, AdGroupStatus
} from '@happyvertical/smrt-ads';

// Define delivery tiers (lower priority number = served first)
const tiers = new AdDeliveryTierCollection(db);
const sponsorship = await tiers.create({
  name: 'Sponsorship',
  priority: 1,
  pricingModel: PricingModel.FIXED,
});

const standard = await tiers.create({
  name: 'Standard',
  priority: 2,
  pricingModel: PricingModel.CPM,
});

// Create an ad group with targeting and budget
const groups = new AdGroupCollection(db);
const group = await groups.create({
  name: 'Holiday Campaign',
  tierId: sponsorship.id,
  contractId: 'contract-uuid',     // plain string FK to smrt-commerce
  status: AdGroupStatus.ACTIVE,
  dailyBudget: 100.00,
  totalBudget: 3000.00,
  startDate: new Date('2025-06-01'),
  endDate: new Date('2025-08-31'),
});
group.setTargeting({ device: 'desktop', geo: 'US' });
group.setZoneIds(['zone-1', 'zone-2']);  // FK to smrt-properties zones
await group.save();

// Add variations with relative weights for A/B testing
// weight=2 is selected 2x more often than weight=1
const variations = new AdVariationCollection(db);
const varA = await variations.create({
  groupId: group.id,
  name: 'Version A - Blue CTA',
  weight: 2,
  status: 'active',
});

// Track an immutable event (create-only, no update/delete)
const events = new AdEventCollection(db);
await events.create({
  variationId: varA.id,
  zoneId: 'zone-uuid',
  siteId: 'site-uuid',
  eventType: AdEventType.IMPRESSION,
});

class AdDeliveryTier extends SmrtObject {
  name: string
  priority: number          // 1=highest, 2, 3...
  pricingModel: 'fixed' | 'cpm' | 'cpc' | 'cpa'  // PricingModel enum
  description?: string
}

class AdGroup extends SmrtObject {
  name: string
  tierId: string            // FK to AdDeliveryTier
  contractId: string        // FK to Contract (smrt-commerce, plain string)
  status: 'draft' | 'active' | 'paused' | 'completed'  // AdGroupStatus
  dailyBudget: number = 0.0  // DECIMAL
  totalBudget: number = 0.0  // DECIMAL
  startDate: Date
  endDate: Date

  // JSON fields with getter/setter helpers
  setTargeting(rules: Record<string, any>): void
  getTargeting(): Record<string, any>
  setZoneIds(ids: string[]): void   // FK to Zone[] (smrt-properties)
  getZoneIds(): string[]
}

class AdVariation extends SmrtObject {
  groupId: string
  name: string
  weight: number = 0        // Relative weight for A/B (2 = 2x more likely than 1)
  impressions: number = 0   // Denormalized count
  clicks: number = 0        // Denormalized count
  status: 'draft' | 'active' | 'paused'  // AdVariationStatus
}

// Ad selection algorithm
async function selectAd(zoneId: string) {
  // 1. Find eligible groups for zone
  const eligibleGroups = await groups.findEligibleForZone(zoneId);
  // Filters: ACTIVE, in date range, has zoneId

  // 2. Sort by tier priority (1 first)
  eligibleGroups.sort((a, b) =>
    tierMap[a.tierName].priority - tierMap[b.tierName].priority
  );

  // 3. Select first group with available variations
  for (const group of eligibleGroups) {
    const variation = await variations.selectByWeight(group.id);
    if (variation) return variation;
  }

  return null; // No ads available
}

// Weighted selection (A/B testing)
const selected = await variations.selectByWeight(groupId);
// Weight 70 vs 30 = 70% chance of first variation

// Track events (immutable -- create only)
await events.create({
  eventType: AdEventType.IMPRESSION,
  variationId: variation.id,
  zoneId: zoneId,
  siteId: propertyId,
});

await events.create({
  eventType: AdEventType.CLICK,
  variationId: variation.id,
  zoneId: zoneId,
  siteId: propertyId,
});