@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,
});

// @smrt(...) — NOT @TenantScoped (shared catalog; see Tenancy section)
class AdDeliveryTier extends SmrtObject {
  name: string
  priority: number          // 1=highest, 2, 3...
  pricingModel: 'fixed' | 'cpm' | 'cpc' | 'cpa'  // PricingModel enum
  description?: string
}

// @smrt(...) — NOT @TenantScoped (IAB industry standard; see Tenancy section)
class AdFormat extends SmrtObject {
  name: string              // e.g. 'Leaderboard', 'Medium Rectangle'
  width: number
  height: number
  formatType: 'banner' | 'native' | 'video'  // AdFormatType enum
  description?: string
}

// @smrt({ tableStrategy: 'sti', ... }) + @TenantScoped({ mode: 'optional' })
class AdGroup extends SmrtObject {
  name: string
  tierId: string            // @foreignKey('AdDeliveryTier')
  contractId: string        // @crossPackageRef to smrt-commerce Contract
  verticalSlug: string      // tag slug from smrt-tags
  status: 'draft' | 'active' | 'paused' | 'completed'  // AdGroupStatus
  dailyBudget: number = 0.0  // DECIMAL
  totalBudget: number = 0.0  // DECIMAL
  startDate: Date | null
  endDate: Date | null

  // JSON fields with getter/setter helpers (no schema validation on targeting rules)
  setTargeting(rules: Record<string, any>): void
  getTargeting(): Record<string, any>
  setZoneIds(ids: string[]): void   // plain string IDs → smrt-properties zones
  getZoneIds(): string[]
}

// @smrt({ tableStrategy: 'sti', ... }) + @TenantScoped({ mode: 'optional' })
class AdVariation extends SmrtObject {
  groupId: string           // @foreignKey('AdGroup')
  formatId: string          // @foreignKey('AdFormat')
  name: string
  clickUrl: string          // Click destination URL
  altText: string           // Accessibility alt text
  weight: number = 1        // Relative weight for A/B (2 = 2x more likely than 1)
  impressions: number = 0   // Denormalized count (eventually consistent)
  clicks: number = 0        // Denormalized count (eventually consistent)
  status: 'draft' | 'active' | 'paused'  // AdVariationStatus
  assetId: string           // @crossPackageRef → smrt-assets Asset
}

// @smrt({ tableStrategy: 'sti', api: { include: ['create', 'list'] }, mcp: { include: ['create'] }, cli: false })
// + @TenantScoped({ mode: 'optional' })
class AdEvent extends SmrtObject {
  variationId: string       // @foreignKey('AdVariation')
  zoneId: string            // @crossPackageRef → smrt-properties Zone
  siteId: string            // denormalized from Zone for query efficiency
  eventType: 'impression' | 'click' | 'conversion'  // AdEventType
  timestamp: Date
  metadata: string          // JSON (IP, user agent, referrer, etc.)
  // immutable: no update or delete in API/MCP
}

// 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,
});