@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/examples/durable-buyer-writes/worker.ts

@@ -0,0 +1,240 @@
+#!/usr/bin/env tsx
+
+import { randomUUID } from 'node:crypto';
+
+import { ADCP_VERSION, TaskExecutor, type AgentConfig, type TaskResult, type WebhookHandlerRequest } from '@adcp/sdk';
+
+import {
+  STORE_NAMES,
+  assertSameAuthorization,
+  createDurableAgent,
+  DEFAULT_CONTINUATION_CLAIM_SECONDS,
+  PostgresOperationLedger,
+  TERMINAL_TASK_STATUSES,
+  type DurableBuyerDependencies,
+} from './caller.js';
+
+type PolledTask = Awaited<ReturnType<TaskExecutor['getTaskStatus']>>;
+
+function registeredCallbackUrl(template: string, taskType: string, sellerId: string, operationId: string): string {
+  return template
+    .replaceAll('{task_type}', taskType)
+    .replaceAll('{agent_id}', sellerId)
+    .replaceAll('{operation_id}', operationId);
+}
+
+export interface WebhookResponse {
+  status(code: number): { json(body: unknown): void };
+  writeHead(code: number, headers: Record<string, string>): void;
+  end(body: string): void;
+}
+
+function sendStaticError(response: WebhookResponse, status: number, message: string): void {
+  response.status(status).json({ error: message });
+}
+
+/**
+ * Fresh callback process. Route parameters are trusted only as lookup keys;
+ * the SDK then verifies them against the durable registration and signature.
+ */
+export async function receiveTaskWebhook(
+  dependencies: DurableBuyerDependencies,
+  request: WebhookHandlerRequest,
+  response: WebhookResponse
+): Promise<void> {
+  const sellerId = request.params?.['agent_id'];
+  const taskType = request.params?.['task_type'];
+  const operationId = request.params?.['operation_id'];
+  if (!sellerId || !taskType || !operationId) {
+    sendStaticError(response, 400, 'Invalid callback route.');
+    return;
+  }
+  if (taskType !== 'buy_products') {
+    sendStaticError(response, 404, 'Callback route not found.');
+    return;
+  }
+
+  const ledger = new PostgresOperationLedger(dependencies.pool);
+  const operation = await ledger.getBySdkOperation(sellerId, operationId);
+  if (!operation) {
+    sendStaticError(response, 404, 'Callback route not found.');
+    return;
+  }
+  const session = await dependencies.resolveSellerSession(operation);
+  if (!session) {
+    sendStaticError(response, 404, 'Callback route not found.');
+    return;
+  }
+  try {
+    assertSameAuthorization(operation, session);
+  } catch {
+    sendStaticError(response, 404, 'Callback route not found.');
+    return;
+  }
+  const seller = await createDurableAgent(dependencies, ledger, session);
+  const handler = seller.createWebhookHandler({
+    getTaskType: () => taskType,
+    getOperationId: () => operationId,
+    getRequestMethod: () => request.method,
+    // Construct from server-owned configuration, never Host/X-Forwarded-*.
+    getRequestUrl: () => registeredCallbackUrl(dependencies.callbackUrlTemplate, taskType, sellerId, operationId),
+  });
+  await handler(request, response);
+}
+
+/** Fresh polling process used when no callback arrives. */
+export async function recoverByPolling(
+  dependencies: DurableBuyerDependencies,
+  logicalOperationId: string,
+  signal?: AbortSignal
+): Promise<PolledTask> {
+  const ledger = new PostgresOperationLedger(dependencies.pool);
+  const operation = await ledger.get(logicalOperationId);
+  if (!operation) throw new Error('Unknown durable operation.');
+  const session = await dependencies.resolveSellerSession(operation);
+  if (!session) throw new Error('The durable operation is no longer authorized.');
+  assertSameAuthorization(operation, session);
+  if (!operation.sellerTaskId) throw new Error('The operation has no seller task handle to poll.');
+  const seller: AgentConfig = {
+    id: session.sellerId,
+    name: session.sellerId,
+    agent_uri: session.sellerUrl,
+    protocol: session.sellerProtocol,
+    auth_token: session.authToken,
+  };
+  const task = await new TaskExecutor({ adcpVersion: ADCP_VERSION }).getTaskStatus(
+    seller,
+    operation.sellerTaskId,
+    undefined,
+    signal
+  );
+  await ledger.observe(
+    logicalOperationId,
+    task.status === 'cancelled' ? 'canceled' : task.status,
+    task.result,
+    operation.sellerTaskId
+  );
+  return task;
+}
+
+/**
+ * Fresh A2A continuation process. The injected DeferredTaskStorage must be the
+ * same atomic, encrypted-at-rest store used by the caller. MCP pauses and A2A
+ * pauses without native continuation identity are intentionally nonresumable.
+ */
+export async function resumePendingInput(
+  dependencies: DurableBuyerDependencies,
+  logicalOperationId: string,
+  input: unknown
+): Promise<TaskResult<unknown>> {
+  const ledger = new PostgresOperationLedger(dependencies.pool);
+  const operation = await ledger.get(logicalOperationId);
+  if (!operation) throw new Error('Unknown durable operation.');
+  const session = await dependencies.resolveSellerSession(operation);
+  if (!session) throw new Error('The durable operation is no longer authorized.');
+  assertSameAuthorization(operation, session);
+  if (!operation.deferredToken) throw new Error('The operation has no resumable deferred token.');
+  const seller = await createDurableAgent(dependencies, ledger, session);
+  const claimSeconds = dependencies.continuationClaimSeconds ?? DEFAULT_CONTINUATION_CLAIM_SECONDS;
+  const claimToken = await ledger.claimContinuation(logicalOperationId, claimSeconds);
+  let renewalFailure: unknown;
+  let renewal: Promise<void> | undefined;
+  const renewalTimer = setInterval(
+    () => {
+      if (renewal) return;
+      renewal = ledger
+        .renewContinuationClaim(logicalOperationId, claimToken, claimSeconds)
+        .catch(error => {
+          renewalFailure = error;
+        })
+        .finally(() => {
+          renewal = undefined;
+        });
+    },
+    Math.floor((claimSeconds * 1000) / 3)
+  );
+  renewalTimer.unref();
+  try {
+    const result = await seller.resumeDeferredTask<unknown>(operation.deferredToken, input);
+    clearInterval(renewalTimer);
+    await renewal;
+    if (renewalFailure) throw renewalFailure;
+    await ledger.observeByLogicalOperation(logicalOperationId, result, claimToken);
+    return result;
+  } finally {
+    clearInterval(renewalTimer);
+    await renewal;
+    await ledger.releaseContinuationClaim(logicalOperationId, claimToken);
+  }
+}
+
+export interface Publication {
+  logicalOperationId: string;
+  terminalFingerprint: string;
+  payload: unknown;
+}
+
+/**
+ * Publish one host outbox row. The downstream sink must atomically deduplicate
+ * logicalOperationId. That closes the unavoidable crash-after-send/before-ACK
+ * window without pretending a database and an external sink share a transaction.
+ */
+export async function publishOne(
+  dependencies: DurableBuyerDependencies,
+  publishIdempotently: (publication: Publication) => Promise<void>
+): Promise<boolean> {
+  const claimToken = randomUUID();
+  const claimed = await dependencies.pool.query(
+    `WITH candidate AS (
+       SELECT deployment_namespace, logical_operation_id
+       FROM ${STORE_NAMES.publications}
+       WHERE deployment_namespace = $1 AND published_at IS NULL
+         AND (claim_expires_at IS NULL OR claim_expires_at <= clock_timestamp())
+       ORDER BY updated_at
+       FOR UPDATE SKIP LOCKED
+       LIMIT 1
+     )
+     UPDATE ${STORE_NAMES.publications} AS publication
+     SET claim_token = $2,
+         claim_expires_at = clock_timestamp() + INTERVAL '60 seconds',
+         attempts = attempts + 1,
+         updated_at = clock_timestamp()
+     FROM candidate
+     WHERE publication.deployment_namespace = candidate.deployment_namespace
+       AND publication.logical_operation_id = candidate.logical_operation_id
+     RETURNING publication.logical_operation_id, publication.terminal_fingerprint, publication.payload`,
+    [STORE_NAMES.deployment, claimToken]
+  );
+  const row = claimed.rows[0];
+  if (!row) return false;
+  const publication: Publication = {
+    logicalOperationId: String(row.logical_operation_id),
+    terminalFingerprint: String(row.terminal_fingerprint),
+    payload: row.payload,
+  };
+  try {
+    await publishIdempotently(publication);
+    const acknowledged = await dependencies.pool.query(
+      `UPDATE ${STORE_NAMES.publications}
+       SET published_at = clock_timestamp(), claim_token = NULL,
+           claim_expires_at = NULL, updated_at = clock_timestamp()
+       WHERE deployment_namespace = $1 AND logical_operation_id = $2
+         AND claim_token = $3 AND published_at IS NULL`,
+      [STORE_NAMES.deployment, publication.logicalOperationId, claimToken]
+    );
+    if (acknowledged.rowCount !== 1) throw new Error('Publication lease was lost before acknowledgement.');
+    return true;
+  } catch (error) {
+    await dependencies.pool.query(
+      `UPDATE ${STORE_NAMES.publications}
+       SET claim_token = NULL, claim_expires_at = NULL, updated_at = clock_timestamp()
+       WHERE deployment_namespace = $1 AND logical_operation_id = $2 AND claim_token = $3`,
+      [STORE_NAMES.deployment, publication.logicalOperationId, claimToken]
+    );
+    throw error;
+  }
+}
+
+export function isTerminalTask(task: PolledTask): boolean {
+  return TERMINAL_TASK_STATUSES.has(task.status === 'cancelled' ? 'canceled' : task.status);
+}

package/examples/reliable-reporting-service/README.md

@@ -0,0 +1,100 @@
+# Adapter-first Reliable Reporting Core
+
+This is the minimal production assembly. The provider adapter returns only
+real upstream results: `null` means not ready, `[]` is an observed zero-row
+period, and a populated response carries the provider's rows and temporal
+evidence. It never manufactures fallback delivery.
+
+```ts
+import { Pool } from 'pg';
+import { createAdcpServerFromPlatform } from '@adcp/sdk/server';
+import { PostgresReportingLedgerStore } from '@adcp/sdk/reporting/ledger';
+import { createReliableReportingService, type ReliableReportingAdapterV1 } from '@adcp/sdk/reporting/service';
+
+// Your provider integration owns these immutable declarations and the real
+// bounded API read. The fetch context contains only durable, non-secret
+// routing IDs; derive OAuth/bearer credentials inside the provider client.
+const providerAdapter: ReliableReportingAdapterV1 = {
+  sourceOffering: provider.reportingSourceOffering,
+  deliveryOffering: provider.reportingDeliveryOffering,
+  fetchSlice: (request, context) =>
+    provider.fetchReportingSlice(request, {
+      signal: context.signal,
+      networkId: String(context.sourceScope.network_id),
+    }),
+};
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const reporting = createReliableReportingService({
+  store: new PostgresReportingLedgerStore(pool, {
+    acknowledgeIsolatedDatabase: true,
+  }),
+  adapters: { provider: providerAdapter },
+  contact: { name: 'Reporting operations', email: 'reporting@example.com' },
+  automatedRecoveryWindowSeconds: 86_400,
+  statusRetentionDays: 90, // enforce the same or longer retention in the ledger database
+  resolveSource: account => ({
+    adapterId: 'provider',
+    sourceScope: { network_id: account.ctx_metadata.provider.networkId },
+    sourceTimezone: account.ctx_metadata.provider.timezone,
+  }),
+  resolveCurrency: account => account.ctx_metadata.provider.currency,
+  // Authorization boundary: the constituents this account may report on, read
+  // from your booking system rather than echoed from the buyer's declaration.
+  resolveCoverage: async account => ({
+    constituents: await bookings.authorizedReportingConstituents(account.id),
+  }),
+  resolveConsumerId: ctx => {
+    if (!ctx.agent) throw new Error('Authenticated buyer-agent registry required');
+    return ctx.agent.agent_url;
+  },
+});
+
+await pool.query(reporting.setup.migrations[0]);
+const installedPlatform = reporting.install(platform);
+const server = createAdcpServerFromPlatform(installedPlatform, serverOptions);
+
+// Pick exactly one operational ownership model.
+reporting.start({
+  intervalMilliseconds: 60_000,
+  deploymentWide: true,
+  maxObligationsPerAccount: 500,
+  maxWorkerIterationsPerAccount: 100,
+  onError: error => operations.capture(error),
+});
+
+process.once('SIGTERM', async () => {
+  await reporting.stop();
+  await pool.end();
+});
+```
+
+For tenant-partitioned scheduling, replace `deploymentWide: true` with
+`accountIds: () => tenantDirectory.reportingAccountIds()`. A resolver must
+return an array; it can never fall back to a deployment-wide scan, and an
+empty or missing account ID is refused rather than widened. One account's
+failed cycle reaches `onError` without skipping the accounts behind it. Configure an
+authenticated `agentRegistry` before using the `ctx.agent` consumer identity
+shown above.
+
+`platform.accounts.upsert` must be installed: it is the native
+`sync_accounts` implementation advertised by the Core capability. Its
+authenticated reporting-configuration path calls `installConfiguration` as
+shown below.
+
+During authenticated `sync_accounts` handling, validate the requested
+offering and resolve its media-buy/package denominator, then call:
+
+```ts
+const frozen = await reporting.installConfiguration(resolvedConfiguration, {
+  account: ctx.account,
+});
+```
+
+`resolvedConfiguration` contains reporting semantics only: no account identity,
+source scope, source contract, timezone, currency, `constituents`, or
+`mediaBuyIds`. The denominator comes from `resolveCoverage`, so a buyer cannot
+name another buyer's media buys on a shared upstream network. The service derives those only from the already-resolved account.
+See [the ledger guide](../../docs/guides/REPORTING-LEDGER.md) for the complete
+input shape, per-account scheduling, migration from manual wiring, and the
+conformance helper.

package/examples/seller-3.2-starter.ts

@@ -1,7 +1,7 @@
 // prettier-ignore
 import { AdcpError, createAdcpServerFromPlatform, createIdempotencyStore, createInMemoryTaskRegistry,
-  definePlatform, memoryBackend, proposalTermsDigest, resolveTargetingInput, serve, verifyApiKey,
-  type BuyProductsPayload, type GetMediaBuysPayload, type ListProductsPayload } from '@adcp/sdk/server';
+  definePlatform, memoryBackend, proposalTermsDigest, serve, verifyApiKey, type BuyProductsPayload,
+  type GetMediaBuysPayload, type ListProductsPayload } from '@adcp/sdk/server';
 const TOKEN = process.env.ADCP_AUTH_TOKEN;
 if (!TOKEN) throw new Error('Set ADCP_AUTH_TOKEN before starting the seller');
 const ACCOUNT_ID = process.env.ADCP_ACCOUNT_ID;
@@ -80,12 +80,11 @@ const platform = definePlatform({
           for (const field of ['measurement_terms', 'performance_standards'] as const) {
             if (purchase[field] !== undefined && !sameTerms(purchase[field], published[field])) throw new AdcpError('TERMS_REJECTED', { message: `${field} must match the published product terms` });
           }
-          // `purchase.targeting_overlay` is a request-only Targeting Input, so a
-          // dimension may be `null` to suppress a product default. The accepted
-          // proposal is a strict snapshot that must not carry clear commands.
-          const targetingOverlay = resolveTargetingInput(purchase.targeting_overlay);
-          return { ...purchase, pricing, ...published, start_time: resolvedStart, end_time: req.end_time,
-            ...(targetingOverlay ? { targeting_overlay: targetingOverlay } : { targeting_overlay: undefined }) };
+          // Build the supported effective snapshot. Request-only targeting clear
+          // commands cannot be copied into accepted terms; overlays were rejected above.
+          return { product_id: purchase.product_id, pricing_option_id: purchase.pricing_option_id,
+            budget: purchase.budget, ...(purchase.context !== undefined && { context: purchase.context }),
+            pricing, ...published, start_time: resolvedStart, end_time: req.end_time };
         }),
         ...(req.total_budget && { total_budget: req.total_budget }),
         ...(req.invoice_recipient && { invoice_recipient: req.invoice_recipient }),

package/examples/targeting-input-existing-platform.ts

@@ -0,0 +1,153 @@
+/**
+ * Existing-platform targeting boundary for AdCP 3.2.
+ *
+ * Mutation input is a command shape: omitted dimensions are unchanged, `null`
+ * clears, and a value replaces. Provider state and AdCP readback are strict
+ * state shapes, so they never retain or return a `null` command.
+ */
+
+import {
+  applyTargetingInput,
+  hasTargetingClears,
+  type BuyProductsRequest,
+  type ControlMediaBuyRequest,
+  type ResolvedTargetingInput,
+} from '@adcp/sdk';
+
+type ProductPurchase = BuyProductsRequest['purchases'][number];
+type PackageControl = NonNullable<ControlMediaBuyRequest['packages']>[number];
+
+/** Canonical request shapes; derive these instead of copying generated types. */
+export type CreateTargetingInput = ProductPurchase['targeting_overlay'];
+export type UpdateTargetingInput = PackageControl['targeting_overlay'];
+export type AcceptedTargeting = ResolvedTargetingInput<NonNullable<CreateTargetingInput>>;
+
+type ProviderTargetingField = 'countryCodes' | 'metroCodes' | 'languageCodes' | 'keywordTargets' | 'negativeKeywords';
+
+/** One concrete translation into an existing provider's mutation language. */
+export type ProviderTargetingOperation =
+  | { kind: 'set'; field: ProviderTargetingField; value: unknown }
+  | { kind: 'clear'; field: ProviderTargetingField };
+
+export interface ExistingProviderClient {
+  /**
+   * Atomically applies the exact supplied values or rejects the whole call;
+   * omitted dimensions never appear. If a provider normalizes accepted values,
+   * change this seam to return its canonical readback and persist that instead.
+   */
+  applyPackageTargeting(packageId: string, operations: readonly ProviderTargetingOperation[]): Promise<void>;
+}
+
+export interface ExistingTargetingStore {
+  readAcceptedTargeting(packageId: string): Promise<AcceptedTargeting | undefined>;
+  /** Persist only after the provider accepted the replacement. */
+  saveAcceptedTargeting(packageId: string, targeting: AcceptedTargeting | undefined): Promise<void>;
+}
+
+export class UnsupportedTargetingClearError extends Error {
+  readonly field: string;
+
+  constructor(field: string) {
+    super(`The provider cannot clear targeting dimension ${field}`);
+    this.name = 'UnsupportedTargetingClearError';
+    this.field = field;
+  }
+}
+
+export class UnsupportedTargetingDimensionError extends Error {
+  readonly field: string;
+
+  constructor(field: string) {
+    super(`The provider adapter does not translate targeting dimension ${field}`);
+    this.name = 'UnsupportedTargetingDimensionError';
+    this.field = field;
+  }
+}
+
+const PROVIDER_FIELD_BY_DIMENSION: Readonly<Record<string, ProviderTargetingField>> = {
+  geo_countries: 'countryCodes',
+  geo_metros: 'metroCodes',
+  language: 'languageCodes',
+  keyword_targets: 'keywordTargets',
+  negative_keywords: 'negativeKeywords',
+};
+
+/**
+ * Preserve nullable commands while translating to provider operations. Add a
+ * provider mapping here before advertising support for another dimension.
+ */
+export function toProviderTargetingOperations(
+  input: object | undefined,
+  clearableDimensions: ReadonlySet<string>,
+  fieldPrefix: string
+): ProviderTargetingOperation[] {
+  if (input === undefined) return [];
+
+  const operations: ProviderTargetingOperation[] = [];
+  for (const [dimension, value] of Object.entries(input)) {
+    if (value === undefined) continue;
+    const field = PROVIDER_FIELD_BY_DIMENSION[dimension];
+    if (!field) throw new UnsupportedTargetingDimensionError(`${fieldPrefix}.${dimension}`);
+    if (value === null) {
+      if (!clearableDimensions.has(dimension)) {
+        throw new UnsupportedTargetingClearError(`${fieldPrefix}.${dimension}`);
+      }
+      operations.push({ kind: 'clear', field });
+    } else {
+      operations.push({ kind: 'set', field, value });
+    }
+  }
+  return operations;
+}
+
+/**
+ * Thin orchestration around application-owned provider and durable-store
+ * adapters. The outer control handler must serialize/CAS the read-provider-save
+ * block using the request revision. A production store should also reconcile a
+ * provider success if its subsequent local commit fails.
+ */
+export class ExistingPlatformTargeting {
+  constructor(
+    private readonly provider: ExistingProviderClient,
+    private readonly store: ExistingTargetingStore,
+    /** Dimensions that both product policy and the provider allow clearing. */
+    private readonly clearableDimensions: ReadonlySet<string>
+  ) {}
+
+  async create(
+    packageId: string,
+    configuredProductTargeting: AcceptedTargeting | undefined,
+    input: CreateTargetingInput
+  ): Promise<AcceptedTargeting | undefined> {
+    const operations = toProviderTargetingOperations(input, this.clearableDimensions, 'purchases[].targeting_overlay');
+    if (operations.length > 0) await this.provider.applyPackageTargeting(packageId, operations);
+
+    // Start with the selected product's strict defaults: omission inherits a
+    // default, null suppresses it, and a value replaces it. The provider has
+    // now executed every explicit command, so this result is safe to persist.
+    const accepted = applyTargetingInput(configuredProductTargeting, input);
+    await this.store.saveAcceptedTargeting(packageId, accepted);
+    return accepted;
+  }
+
+  async update(packageId: string, input: UpdateTargetingInput): Promise<AcceptedTargeting | undefined> {
+    const prior = await this.store.readAcceptedTargeting(packageId);
+
+    // Omitted targeting is a true no-op: do not call the provider or rewrite
+    // durable state. This differs from an explicit `null` inside the overlay.
+    if (input === undefined) return prior;
+
+    const operations = toProviderTargetingOperations(input, this.clearableDimensions, 'packages[].targeting_overlay');
+    if (operations.length > 0) await this.provider.applyPackageTargeting(packageId, operations);
+    const accepted = applyTargetingInput(prior, input);
+    await this.store.saveAcceptedTargeting(packageId, accepted);
+    return accepted;
+  }
+
+  /** AdCP response handlers read this strict state; no request command leaks. */
+  async readback(packageId: string): Promise<AcceptedTargeting | undefined> {
+    const targeting = await this.store.readAcceptedTargeting(packageId);
+    if (hasTargetingClears(targeting)) throw new Error('Durable targeting state contains a request-only clear command');
+    return targeting;
+  }
+}