@happyvertical/smrt-ads

Advertising delivery and tracking models for the s-m-r-t framework. Supports priority-based ad group delivery with a tier waterfall, IAB ad formats, weighted A/B variation testing, and immutable event tracking.

Installation

pnpm add @happyvertical/smrt-ads

Usage

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 = await AdDeliveryTierCollection.create({ 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 = await AdGroupCollection.create({ db });
const group = await groups.create({
  name: 'Holiday Campaign',
  tierId: sponsorship.id,
  contractId: 'contract-uuid',
  status: AdGroupStatus.ACTIVE,
  dailyBudget: 100.00,
  totalBudget: 3000.00,
  startDate: new Date('2024-06-01'),
  endDate: new Date('2024-08-31'),
});
group.setTargeting({ device: 'desktop', geo: 'US' });
group.setZoneIds(['zone-1', 'zone-2']);
await group.save();

// Add variations with weights for A/B testing
// weight=2 is selected 2x more often than weight=1
const variations = await AdVariationCollection.create({ 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 = await AdEventCollection.create({ db });
await events.create({
  variationId: varA.id,
  zoneId: 'zone-uuid',
  siteId: 'site-uuid',
  eventType: AdEventType.IMPRESSION,
});

Delivery Tier Waterfall

Ads are selected by tier priority (lower number = higher priority):

1. Sponsorship (priority 1) -- guaranteed premium placements, FIXED pricing
2. Standard (priority 2) -- regular programmatic ads, CPM pricing
3. House (priority 3) -- self-promotional fallback ads

Within a tier, variations are selected by relative weight. A variation with weight: 2 is twice as likely to be chosen as one with weight: 1.

API

Models

Export	Description
AdDeliveryTier	Priority tier for waterfall delivery (name, priority, pricingModel)
AdFormat	IAB standard ad dimensions (width, height, formatType: banner/native/video)
AdGroup	Campaign with targeting rules, budget, zone restrictions, and date range
AdVariation	Creative variant within a group with weight for A/B distribution. Denormalized impressions/clicks counts
AdEvent	Immutable tracking event (impression/click/conversion). Create-only -- no update/delete. cli: false (high-volume)

Collections

AdDeliveryTierCollection, AdFormatCollection, AdGroupCollection, AdVariationCollection, AdEventCollection

Enums

Export	Values
AdEventType	impression, click, conversion
AdFormatType	banner, native, video
AdGroupStatus	draft, active, paused, completed
AdVariationStatus	draft, active, paused
PricingModel	fixed, cpm, cpc, cpa

Dependencies

• @happyvertical/smrt-core -- ORM and code generation
• @happyvertical/smrt-tenancy -- multi-tenant scoping (optional on AdGroup, AdVariation, AdEvent)
• Peer: @happyvertical/smrt-assets, @happyvertical/smrt-commerce, @happyvertical/smrt-properties, @happyvertical/smrt-tags

Contributor guide

See AGENTS.md for package architecture, invariants, validation, and contributor guidance.