@adcp/sdk 5.25.1 → 6.1.0

package/examples/decisioning-platform-broadcast-tv.ts

@@ -0,0 +1,300 @@
+/**
+ * BroadcastTvSeller — worked example for `sales-broadcast-tv`.
+ *
+ * Broadcast linear TV is the canonical HITL case: a media buy isn't real
+ * until the trafficker confirms inventory holds and the plan clears
+ * standards & practices. Buyers don't get a `media_buy_id` until the
+ * trafficker accepts; the unified hybrid shape projects this directly:
+ *
+ *   - `getProducts` — sync catalog read of the affiliate's standing
+ *     inventory packages (no trafficker review for catalog reads). Brief-
+ *     based proposal generation is a separate verb (`request_proposal`,
+ *     adcp#3407) and rides on a status-change channel, not on
+ *     `get_products`.
+ *   - `createMediaBuy(req, ctx)` — returns `ctx.handoffToTask(fn)` for
+ *     trafficker review + IO sign-off (hours to days). The handoff fn
+ *     does the actual work and returns the wire `Success` arm when the
+ *     trafficker accepts; `throw AdcpError` becomes the terminal error.
+ *   - `syncCreatives(creatives, ctx)` — returns `ctx.handoffToTask(fn)`
+ *     for the standards-and-practices review (24-48 hour SLA in
+ *     production; demo uses `standardsReviewMs`).
+ *
+ * Lifecycle changes after acceptance (plan goes from `pending_start` →
+ * `active` → `completed` over the campaign window) flow via
+ * `publishStatusChange`.
+ *
+ * @see `skills/build-decisioning-platform/SKILL.md`
+ */
+
+import {
+  AdcpError,
+  publishStatusChange,
+  type DecisioningPlatform,
+  type SalesPlatform,
+  type AccountStore,
+  type SyncCreativesRow,
+} from '@adcp/sdk/server';
+import type {
+  GetProductsRequest,
+  GetProductsResponse,
+  CreateMediaBuyRequest,
+  CreateMediaBuySuccess,
+  UpdateMediaBuyRequest,
+  UpdateMediaBuySuccess,
+  GetMediaBuyDeliveryRequest,
+  GetMediaBuyDeliveryResponse,
+  CreativeAsset,
+  AccountReference,
+} from '@adcp/sdk/types';
+
+// ---------------------------------------------------------------------------
+// BroadcastTvSeller config + state
+// ---------------------------------------------------------------------------
+
+export interface BroadcastTvConfig {
+  /** Affiliate the trafficker IO desk maps to (e.g., 'WCBS'). */
+  affiliateId: string;
+  /** Simulated trafficker review duration (ms). */
+  trafficReviewMs: number;
+  /** Simulated S&P review duration (ms). */
+  standardsReviewMs: number;
+  /** Day-of-week and hour the schedule "activates" relative to start_time. */
+  activationOffsetMs: number;
+}
+
+interface BroadcastTvMeta {
+  agency_buyer_id: string;
+  affiliate_advertiser_id: string;
+  [key: string]: unknown;
+}
+
+type BroadcastBuy = CreateMediaBuySuccess & { daypart?: string };
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export class BroadcastTvSeller implements DecisioningPlatform<BroadcastTvConfig, BroadcastTvMeta> {
+  private mediaBuys = new Map<string, BroadcastBuy>();
+
+  capabilities = {
+    specialisms: ['sales-broadcast-tv'] as const,
+    creative_agents: [{ agent_url: 'https://example.com/broadcast-creative-agent/mcp' }],
+    channels: ['linear_tv'] as const,
+    pricingModels: ['cpm'] as const,
+    config: {
+      affiliateId: 'WCBS',
+      trafficReviewMs: 100,
+      standardsReviewMs: 80,
+      activationOffsetMs: 50,
+    } satisfies BroadcastTvConfig,
+  };
+
+  statusMappers = {};
+
+  accounts: AccountStore<BroadcastTvMeta> = {
+    resolve: async (ref: AccountReference) => {
+      const id = 'account_id' in ref ? ref.account_id : 'broadcast_acc_1';
+      return {
+        id,
+        name: `Broadcast TV — ${id}`,
+        status: 'active',
+        operator: 'broadcast.example.com',
+        ctx_metadata: { agency_buyer_id: 'agc_42', affiliate_advertiser_id: 'aff_99' },
+        authInfo: { kind: 'api_key' },
+      };
+    },
+  };
+
+  sales: SalesPlatform<BroadcastTvMeta> = {
+    /**
+     * Sync catalog read. Returns the affiliate's standing packages —
+     * primetime daypart, sports tentpoles, etc. Brief-based proposal
+     * generation is a separate verb the spec is consolidating
+     * (adcp#3407 `request_proposal`); proposal-mode adopters surface
+     * the eventual products via `publishStatusChange` on
+     * `resource_type: 'proposal'`.
+     */
+    getProducts: async (req: GetProductsRequest): Promise<GetProductsResponse> => {
+      const promotedOffering = (req as { promoted_offering?: string }).promoted_offering ?? '';
+      if (/political|cannabis|gambling/i.test(promotedOffering)) {
+        throw new AdcpError('POLICY_VIOLATION', {
+          recovery: 'terminal',
+          message: 'Affiliate does not carry this category under FCC + station policy',
+          field: 'promoted_offering',
+          details: { affiliate: this.capabilities.config.affiliateId },
+        });
+      }
+
+      return {
+        products: [
+          {
+            product_id: 'prod_primetime_30s',
+            name: 'Primetime 30s — M-F 8-11pm',
+            description: 'Local broadcast primetime, :30 spots',
+            format_ids: [{ id: 'video_30s', agent_url: 'https://example.com/broadcast-creative-agent/mcp' }],
+            delivery_type: 'guaranteed',
+            publisher_properties: [{ publisher_domain: 'broadcast.example.com', selection_type: 'all' }],
+            reporting_capabilities: {
+              available_reporting_frequencies: ['daily'],
+              expected_delay_minutes: 240,
+              timezone: 'UTC',
+              supports_webhooks: false,
+              available_metrics: [],
+              date_range_support: 'date_range',
+            },
+            pricing_options: [
+              {
+                pricing_option_id: 'cpm_42_00',
+                pricing_model: 'cpm',
+                fixed_price: 42.0,
+                currency: 'USD',
+                min_spend_per_package: 5_000,
+              },
+            ],
+          },
+        ],
+      };
+    },
+
+    /**
+     * Hybrid HITL: trafficker review + IO sign-off. Buyer sees `submitted`
+     * envelope with `task_id` immediately; the framework runs the handoff
+     * fn in background. Trafficker accepts → handoff returns the wire
+     * `Success` arm with `media_buy_id`; trafficker rejects → handoff
+     * throws `AdcpError`, framework surfaces terminal error.
+     *
+     * Pre-flight runs sync (rejects bad budgets before allocating a task
+     * id). Lifecycle after acceptance flows via `publishStatusChange`.
+     */
+    createMediaBuy: (req, ctx) => {
+      // Pre-flight runs sync regardless of path
+      const errors = this.preflight(req);
+      if (errors.length > 0) {
+        throw new AdcpError('INVALID_REQUEST', {
+          recovery: 'correctable',
+          message: errors[0]!.message,
+          field: errors[0]!.field,
+          details: { errors },
+        });
+      }
+
+      return Promise.resolve(
+        ctx.handoffToTask(async taskCtx => {
+          void taskCtx; // taskCtx.id available if you need to log it
+          // Trafficker review window
+          await new Promise(r => setTimeout(r, this.capabilities.config.trafficReviewMs));
+
+          const buyId = `mb_${this.capabilities.config.affiliateId}_${Date.now()}`;
+          const buy: BroadcastBuy = {
+            media_buy_id: buyId,
+            status: 'pending_start',
+            confirmed_at: new Date().toISOString(),
+            revision: 1,
+            daypart: 'primetime',
+            packages: [],
+          };
+          this.mediaBuys.set(buyId, buy);
+
+          // After acceptance, the broadcast traffic system controls the
+          // campaign window. Schedule the post-acceptance status-change.
+          const account = (req as { account?: { account_id?: string } }).account;
+          const accountId = account?.account_id ?? 'broadcast_acc_1';
+          setTimeout(() => {
+            buy.status = 'active';
+            publishStatusChange({
+              account_id: accountId,
+              resource_type: 'media_buy',
+              resource_id: buyId,
+              payload: { status: 'active', activated_at: new Date().toISOString() },
+            });
+          }, this.capabilities.config.activationOffsetMs).unref?.();
+
+          return buy;
+        })
+      );
+    },
+
+    updateMediaBuy: async (buyId: string, patch: UpdateMediaBuyRequest): Promise<UpdateMediaBuySuccess> => {
+      const existing = this.mediaBuys.get(buyId);
+      if (!existing) {
+        throw new AdcpError('MEDIA_BUY_NOT_FOUND', {
+          recovery: 'terminal',
+          message: `media buy ${buyId} not found`,
+          field: 'media_buy_id',
+        });
+      }
+      // Broadcast: pause = preempt the schedule; canceled is irreversible
+      // (cannot reactivate without a fresh IO).
+      if (patch.paused === true) existing.status = 'paused';
+      if (patch.paused === false && existing.status === 'paused') existing.status = 'active';
+      return { media_buy_id: existing.media_buy_id, status: existing.status, revision: existing.revision };
+    },
+
+    /**
+     * Hybrid HITL S&P review: every spot goes through standards-and-
+     * practices before it can air. 24-48 hour SLA in production. Returns
+     * `ctx.handoffToTask(fn)` so the buyer sees the submitted envelope
+     * immediately and the review runs in background.
+     */
+    syncCreatives: (creatives, ctx) =>
+      Promise.resolve(
+        ctx.handoffToTask(async taskCtx => {
+          void taskCtx;
+          await new Promise(r => setTimeout(r, this.capabilities.config.standardsReviewMs));
+          // Mock policy: anything tagged "political" rejects; rest approve.
+          return creatives.map(c => {
+            const id = (c as { creative_id?: string }).creative_id ?? `cr_${Math.random()}`;
+            const tags = ((c as { tags?: string[] }).tags ?? []).map(t => t.toLowerCase());
+            if (tags.includes('political')) {
+              return {
+                creative_id: id,
+                action: 'failed',
+                status: 'rejected',
+                errors: [
+                  {
+                    code: 'CREATIVE_REJECTED',
+                    message: 'Political ads require FCC disclosure file + station GM sign-off',
+                  },
+                ],
+              } satisfies SyncCreativesRow;
+            }
+            return { creative_id: id, action: 'created', status: 'approved' } satisfies SyncCreativesRow;
+          });
+        })
+      ),
+
+    getMediaBuyDelivery: async (filter: GetMediaBuyDeliveryRequest): Promise<GetMediaBuyDeliveryResponse> => {
+      return {
+        currency: 'USD',
+        reporting_period: {
+          start: filter.start_date ?? '2026-04-01',
+          end: filter.end_date ?? '2026-04-30',
+        },
+        media_buy_deliveries: [],
+      };
+    },
+
+    // Required on SalesPlatform — write-only adopters return an empty array.
+    // This affiliate doesn't enumerate buys via this surface (push-channel
+    // delivery via webhooks); the empty array is truthful.
+    getMediaBuys: async () => ({ media_buys: [] }),
+  };
+
+  private preflight(req: CreateMediaBuyRequest): { code: string; recovery: string; message: string; field: string }[] {
+    const errors = [];
+    const totalBudget =
+      typeof req.total_budget === 'number'
+        ? req.total_budget
+        : ((req.total_budget as { amount?: number })?.amount ?? 0);
+    if (totalBudget < 5_000) {
+      errors.push({
+        code: 'BUDGET_TOO_LOW',
+        recovery: 'correctable',
+        message: 'Broadcast minimum is $5,000 per IO',
+        field: 'total_budget',
+      });
+    }
+    return errors;
+  }
+}

package/examples/decisioning-platform-identity-graph.ts

@@ -0,0 +1,214 @@
+/**
+ * IdentityGraphProvider — worked example for `audience-sync`.
+ *
+ * Identity-graph providers (the category covers vendors like LiveRamp,
+ * Oracle Data Cloud, Salesforce CDP, Neustar) have a long-tail
+ * activation pipeline: ingest → match → activate to destinations. Match
+ * takes 5-30 minutes; activation per destination takes hours. Buyers
+ * can't usefully wait synchronously, but they DO want immediate
+ * confirmation that the audience was accepted and to know when it's
+ * ready.
+ *
+ * This sample is generic — no real provider's API or branding is
+ * implied; the latencies and stages are illustrative. The shape adapters
+ * use is:
+ *
+ *   - Sync `syncAudiences` returns per-audience rows with the *current*
+ *     wire status (`processing` is fine — the buyer's audience_id is
+ *     now known and they can subscribe for updates).
+ *   - `publishStatusChange({ resource_type: 'audience', ... })` fires from
+ *     the match-pipeline + activation-pipeline as each audience reaches
+ *     internal stages `matched` → `activating` → `active`.
+ *
+ * `AdcpError` for buyer-fixable rejection (`REFERENCE_NOT_FOUND`,
+ * insufficient identifiers, etc.).
+ *
+ * @see `skills/build-decisioning-platform/SKILL.md`
+ */
+
+import { publishStatusChange, type DecisioningPlatform, type AccountStore } from '@adcp/sdk/server';
+import type { AudiencePlatform, Audience, AudienceStatus, SyncAudiencesRow } from '@adcp/sdk/server';
+import type { AccountReference } from '@adcp/sdk/types';
+
+// ---------------------------------------------------------------------------
+// Config + state
+// ---------------------------------------------------------------------------
+
+export interface IdentityGraphConfig {
+  /** Minimum identifier count before activation; audiences below this reject. */
+  minIdentifiers: number;
+  /** Identity-graph match latency (ms). */
+  matchLatencyMs: number;
+  /** Per-destination activation latency (ms). */
+  activationLatencyMs: number;
+  /** Default match rate the demo simulates. */
+  defaultMatchRate: number;
+}
+
+interface IdentityGraphMeta {
+  graph_id: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Internal lifecycle stages — richer than the wire `AudienceStatus` enum
+ * (`'processing' | 'ready' | 'too_small'`). The internal stages flow
+ * through `publishStatusChange.payload` (freeform JSON) so buyers
+ * subscribed to the bus see `matched_count`, `match_rate`, and the
+ * stage transitions. The wire-shaped `pollAudienceStatuses` collapses
+ * back to the spec enum.
+ */
+type IdentityGraphStage = 'matching' | 'matched' | 'activating' | 'active' | 'failed';
+
+function toWireStatus(stage: IdentityGraphStage): AudienceStatus {
+  switch (stage) {
+    case 'active':
+      return 'ready';
+    case 'failed':
+      return 'too_small';
+    default:
+      return 'processing';
+  }
+}
+
+type AudienceState = {
+  audience_id: string;
+  stage: IdentityGraphStage;
+  matched_count?: number;
+  match_rate?: number;
+};
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+export class IdentityGraphProvider implements DecisioningPlatform<IdentityGraphConfig, IdentityGraphMeta> {
+  private audienceState = new Map<string, AudienceState>();
+
+  capabilities = {
+    specialisms: ['audience-sync'] as const,
+    creative_agents: [],
+    channels: [] as const,
+    pricingModels: ['cpm'] as const,
+    config: {
+      minIdentifiers: 100,
+      matchLatencyMs: 60,
+      activationLatencyMs: 80,
+      defaultMatchRate: 0.42,
+    } satisfies IdentityGraphConfig,
+  };
+
+  statusMappers = {};
+
+  accounts: AccountStore<IdentityGraphMeta> = {
+    resolve: async (ref: AccountReference) => {
+      const id = 'account_id' in ref ? ref.account_id : 'idg_acc_1';
+      return {
+        id,
+        name: `IdentityGraph — ${id}`,
+        status: 'active',
+        operator: 'identity-graph.example.com',
+        ctx_metadata: { graph_id: 'IG-12345' },
+        authInfo: { kind: 'api_key' },
+      };
+    },
+  };
+
+  audiences: AudiencePlatform<IdentityGraphMeta> = {
+    /**
+     * Sync acknowledgment: return current state for each audience. Match
+     * pipeline + activation pipeline run in background and emit
+     * publishStatusChange events as each audience progresses through the
+     * richer internal stages (`matching` → `matched` → `activating` →
+     * `active`). Buyers subscribed to the status-change bus see the full
+     * lifecycle; buyers polling `pollAudienceStatuses` see the wire-flat
+     * `processing | ready | too_small`.
+     */
+    syncAudiences: async (audiences: Audience[]): Promise<SyncAudiencesRow[]> => {
+      const results: SyncAudiencesRow[] = [];
+      const accountId = 'idg_acc_1';
+
+      for (const aud of audiences) {
+        const audienceId = (aud as { audience_id?: string }).audience_id ?? `aud_${Math.random()}`;
+        const identifiers = ((aud as { identifiers?: unknown[] }).identifiers ?? []) as unknown[];
+
+        if (identifiers.length < this.capabilities.config.minIdentifiers) {
+          this.audienceState.set(audienceId, { audience_id: audienceId, stage: 'failed' });
+          results.push({
+            audience_id: audienceId,
+            action: 'failed',
+            status: 'too_small',
+          });
+          continue;
+        }
+
+        const isUpdate = this.audienceState.has(audienceId);
+        const initial: AudienceState = { audience_id: audienceId, stage: 'matching' };
+        this.audienceState.set(audienceId, initial);
+
+        // Schedule match → matched
+        setTimeout(() => {
+          const matched = Math.floor(identifiers.length * this.capabilities.config.defaultMatchRate);
+          const next: AudienceState = {
+            audience_id: audienceId,
+            stage: 'matched',
+            matched_count: matched,
+            match_rate: this.capabilities.config.defaultMatchRate,
+          };
+          this.audienceState.set(audienceId, next);
+          publishStatusChange({
+            account_id: accountId,
+            resource_type: 'audience',
+            resource_id: audienceId,
+            payload: {
+              stage: 'matched',
+              status: 'processing',
+              matched_count: matched,
+              match_rate: this.capabilities.config.defaultMatchRate,
+            },
+          });
+
+          // Schedule matched → activating → active
+          setTimeout(() => {
+            this.audienceState.set(audienceId, { ...next, stage: 'activating' });
+            publishStatusChange({
+              account_id: accountId,
+              resource_type: 'audience',
+              resource_id: audienceId,
+              payload: { stage: 'activating', status: 'processing' },
+            });
+
+            setTimeout(() => {
+              this.audienceState.set(audienceId, { ...next, stage: 'active' });
+              publishStatusChange({
+                account_id: accountId,
+                resource_type: 'audience',
+                resource_id: audienceId,
+                payload: { stage: 'active', status: 'ready' },
+              });
+            }, this.capabilities.config.activationLatencyMs).unref?.();
+          }, 10).unref?.();
+        }, this.capabilities.config.matchLatencyMs).unref?.();
+
+        results.push({
+          audience_id: audienceId,
+          action: isUpdate ? 'updated' : 'created',
+          status: 'processing',
+          matched_count: 0,
+          effective_match_rate: 0,
+        });
+      }
+
+      return results;
+    },
+
+    pollAudienceStatuses: async (audienceIds): Promise<Map<string, AudienceStatus>> => {
+      const out = new Map<string, AudienceStatus>();
+      for (const audienceId of audienceIds) {
+        const state = this.audienceState.get(audienceId);
+        if (state) out.set(audienceId, toWireStatus(state.stage));
+      }
+      return out;
+    },
+  };
+}