@adcp/sdk 14.1.0 → 14.3.0

package/dist/lib/wholesale-feed-sync/mirror.mjs

@@ -0,0 +1,322 @@
+import { isDeepStrictEqual } from "node:util";
+import { randomUUID } from "node:crypto";
+import { parseWholesaleFeedWebhookNotification } from "./webhook-notification.mjs";
+class InMemoryWholesaleFeedMirrorStore {
+  /** Fail closed at capacity rather than evicting receipts inside the delivery retry window. */
+  constructor(maxWebhookReceipts = 1e4) {
+    this.maxWebhookReceipts = maxWebhookReceipts;
+    if (!Number.isSafeInteger(maxWebhookReceipts) || maxWebhookReceipts < 1)
+      throw new Error("maxWebhookReceipts must be a positive integer.");
+  }
+  maxWebhookReceipts;
+  records = /* @__PURE__ */ new Map();
+  receipts = /* @__PURE__ */ new Map();
+  receiptCount = 0;
+  async hasWebhookReceipt(scope, idempotencyKey) {
+    return this.receipts.get(this.key(scope))?.has(idempotencyKey) ?? false;
+  }
+  key(scope) {
+    return JSON.stringify([scope.agentUrl, scope.accountKey, scope.entity]);
+  }
+  async read(scope) {
+    return structuredClone(this.records.get(this.key(scope)) ?? { revision: 0, items: [], cacheScope: "public" });
+  }
+  /** Seed a detached record when restoring a shell snapshot. */
+  restore(scope, snapshot) {
+    this.records.set(this.key(scope), structuredClone(snapshot));
+  }
+  async commit(scope, expectedRevision, change) {
+    const key = this.key(scope);
+    const prior = this.records.get(key) ?? { revision: 0, items: [], cacheScope: "public" };
+    if (prior.revision !== expectedRevision) return false;
+    const items = new Map(prior.items.map((item) => [itemId(scope.entity, item), item]));
+    for (const id of change.deletes) items.delete(id);
+    for (const item of change.upserts) items.set(itemId(scope.entity, item), structuredClone(item));
+    const { upserts: _upserts, deletes: _deletes, webhookReceipt, ...metadata } = change;
+    const next = {
+      ...prior,
+      ...structuredClone(metadata),
+      revision: prior.revision + 1,
+      items: [...items.values()],
+      error: void 0
+    };
+    if (webhookReceipt) {
+      const receipts = this.receipts.get(key) ?? /* @__PURE__ */ new Set();
+      if (!receipts.has(webhookReceipt.idempotencyKey)) {
+        if (this.receiptCount >= this.maxWebhookReceipts)
+          throw new Error("Webhook receipt capacity reached; use durable storage or increase maxWebhookReceipts.");
+        receipts.add(webhookReceipt.idempotencyKey);
+        ++this.receiptCount;
+      }
+      this.receipts.set(key, receipts);
+    }
+    this.records.set(key, next);
+    return true;
+  }
+  async recordError(scope, expectedRevision, error) {
+    const key = this.key(scope);
+    const prior = this.records.get(key) ?? { revision: 0, items: [], cacheScope: "public" };
+    if (prior.revision !== expectedRevision) return false;
+    this.records.set(key, { ...prior, revision: prior.revision + 1, error: structuredClone(error) });
+    return true;
+  }
+}
+async function refreshWholesaleFeed(options) {
+  return refreshMirror(options);
+}
+async function refreshMirror(options, receipt, expectedWebhookVersion) {
+  options = { ...options, scope: structuredClone(options.scope), account: structuredClone(options.account) };
+  const { store, scope, client } = options;
+  const previous = await store.read(scope);
+  if (options.isCurrent && !options.isCurrent()) return { outcome: "superseded" };
+  let cursor;
+  const cursors = /* @__PURE__ */ new Set();
+  const items = /* @__PURE__ */ new Map();
+  let wholesaleFeedVersion;
+  let pricingVersion;
+  let cacheScope = previous.cacheScope;
+  let unchanged = false;
+  let page = 0;
+  try {
+    do {
+      if (++page > 1e4) throw new Error("Wholesale feed pagination exceeded its page limit.");
+      const params = {
+        ...scope.entity === "product" ? { buying_mode: "wholesale" } : { discovery_mode: "wholesale" },
+        pagination: { max_results: 100, ...cursor && { cursor } },
+        ...options.account && { account: options.account },
+        ...!cursor && options.conditional !== false && previous.wholesaleFeedVersion && {
+          if_wholesale_feed_version: previous.wholesaleFeedVersion,
+          ...previous.pricingVersion && { if_pricing_version: previous.pricingVersion }
+        }
+      };
+      const result = await (scope.entity === "product" ? client.getProducts(params) : client.getSignals(params));
+      if (options.isCurrent && !options.isCurrent()) return { outcome: "superseded" };
+      if (result.success === false || result.status !== void 0 && !["completed", "success"].includes(result.status)) {
+        throw Object.assign(new Error(result.error ?? "Wholesale feed refresh failed."), {
+          adcpError: result.adcpError
+        });
+      }
+      const body = result.data;
+      if (!body) throw new Error("Wholesale feed did not return a completed catalog.");
+      if (body.unchanged) {
+        if (cursor || !("if_wholesale_feed_version" in params) || body.wholesale_feed_version !== previous.wholesaleFeedVersion || "if_pricing_version" in params && body.pricing_version !== previous.pricingVersion || body.cache_scope !== void 0 && body.cache_scope !== previous.cacheScope) {
+          throw new Error("Wholesale feed unchanged response must match both requested version tokens.");
+        }
+        unchanged = true;
+      }
+      if (page > 1 && (body.wholesale_feed_version !== void 0 && body.wholesale_feed_version !== wholesaleFeedVersion || body.pricing_version !== void 0 && body.pricing_version !== pricingVersion || (body.cache_scope ?? cacheScope) !== cacheScope)) {
+        throw new Error("Wholesale feed versions changed during pagination.");
+      }
+      wholesaleFeedVersion = body.wholesale_feed_version ?? wholesaleFeedVersion;
+      pricingVersion = body.pricing_version ?? pricingVersion;
+      cacheScope = body.cache_scope ?? cacheScope;
+      if (unchanged) break;
+      const rows = scope.entity === "product" ? body.products : body.signals;
+      if (!Array.isArray(rows)) throw new Error("Wholesale feed response is missing its catalog rows.");
+      for (const item of rows) {
+        const id = itemId(scope.entity, item);
+        if (!id) throw new Error("Wholesale feed row is missing its entity id.");
+        items.set(id, item);
+      }
+      cursor = body.pagination?.has_more ? body.pagination.cursor : void 0;
+      if (body.pagination?.has_more && (!cursor || cursors.has(cursor)))
+        throw new Error("Wholesale feed pagination did not advance.");
+      if (cursor) cursors.add(cursor);
+    } while (cursor);
+    if (receipt && expectedWebhookVersion !== void 0 && wholesaleFeedVersion === previous.wholesaleFeedVersion && wholesaleFeedVersion !== expectedWebhookVersion)
+      throw new Error("Wholesale repair has not observed the webhook version; retry delivery.");
+  } catch (cause) {
+    if (options.isCurrent && !options.isCurrent()) return { outcome: "superseded" };
+    const errorCause = cause instanceof Error ? cause : new Error(String(cause));
+    const error = cause?.adcpError ?? {
+      code: "SERVICE_UNAVAILABLE",
+      recovery: "transient",
+      message: "Wholesale feed refresh failed.",
+      synthetic: true
+    };
+    if (!await store.recordError(scope, previous.revision, error)) return { outcome: "superseded" };
+    return { outcome: "degraded", error, cause: errorCause };
+  }
+  const nextItems = unchanged ? previous.items : [...items.values()];
+  const next = {
+    ...previous,
+    items: nextItems,
+    wholesaleFeedVersion,
+    pricingVersion,
+    cacheScope,
+    lastSyncedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    revision: previous.revision + 1,
+    error: void 0,
+    ...receipt && {
+      lastWebhookEventId: latestEventId(previous.lastWebhookEventId, receipt.eventId),
+      lastWebhookIdempotencyKey: receipt.idempotencyKey
+    }
+  };
+  const change = rowDiff(scope.entity, previous.items, nextItems);
+  if (options.isCurrent && !options.isCurrent()) return { outcome: "superseded" };
+  if (!await store.commit(scope, previous.revision, {
+    ...change,
+    wholesaleFeedVersion,
+    pricingVersion,
+    cacheScope,
+    lastSyncedAt: next.lastSyncedAt,
+    ...receipt && {
+      webhookReceipt: receipt,
+      lastWebhookEventId: next.lastWebhookEventId,
+      lastWebhookIdempotencyKey: receipt.idempotencyKey
+    }
+  }))
+    return { outcome: "superseded" };
+  return unchanged ? { outcome: "unchanged", snapshot: next } : {
+    outcome: "applied",
+    snapshot: next,
+    diff: diffWholesaleFeed(scope.entity, previous.items, nextItems, cacheScope, true)
+  };
+}
+async function applyWholesaleFeedWebhook(options) {
+  options = {
+    ...options,
+    scope: structuredClone(options.scope),
+    account: structuredClone(options.account),
+    webhookScope: structuredClone(options.webhookScope),
+    webhook: structuredClone(options.webhook)
+  };
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const outcome = await applyWebhookOnce(options);
+    if (outcome.outcome !== "superseded" || options.isCurrent && !options.isCurrent()) return outcome;
+  }
+  return { outcome: "superseded" };
+}
+async function applyWebhookOnce(options) {
+  const { webhook, scope, store } = options;
+  parseWholesaleFeedWebhookNotification(webhook);
+  const event = webhook.event;
+  if (!event || webhook.notification_type !== event.event_type || webhook.notification_id !== event.event_id)
+    throw new Error("Wholesale webhook event identity does not match its envelope.");
+  const entity = event.event_type === "wholesale_feed.bulk_change" ? event.payload.affected_entity_type : event.event_type.startsWith("product.") ? "product" : event.event_type.startsWith("signal.") ? "signal" : void 0;
+  if (entity !== scope.entity) throw new Error("Wholesale webhook entity does not match this mirror.");
+  const accountId = options.webhookScope?.accountId ?? (options.account && "account_id" in options.account ? options.account.account_id : void 0);
+  if (!accountId) throw new Error("Wholesale webhook application requires an expected account_id.");
+  if (webhook.account_id !== accountId || options.webhookScope?.subscriberId && options.webhookScope.subscriberId !== webhook.subscriber_id)
+    throw new Error("Wholesale webhook subscription does not match this mirror.");
+  const applies = event.payload.applies_to;
+  if (applies?.scope && applies.scope !== webhook.cache_scope || webhook.cache_scope === "account" && applies?.account_ids && !applies.account_ids.includes(accountId))
+    throw new Error("Wholesale webhook cache scope does not match this mirror.");
+  const previous = await store.read(scope);
+  if (await store.hasWebhookReceipt(scope, webhook.idempotency_key) || previous.lastWebhookEventId === event.event_id)
+    return { outcome: "unchanged", snapshot: previous };
+  if (previous.cacheScope !== webhook.cache_scope)
+    return refreshMirror(
+      { ...options, conditional: false },
+      { eventId: event.event_id, idempotencyKey: webhook.idempotency_key },
+      webhook.wholesale_feed_version
+    );
+  const stale = previous.lastWebhookEventId && isUuidV7(event.event_id) && isUuidV7(previous.lastWebhookEventId) && event.event_id.toLowerCase() <= previous.lastWebhookEventId.toLowerCase();
+  if (event.event_type === "wholesale_feed.bulk_change" || stale || !previous.wholesaleFeedVersion || webhook.previous_wholesale_feed_version !== previous.wholesaleFeedVersion) {
+    return refreshMirror(
+      options,
+      { eventId: event.event_id, idempotencyKey: webhook.idempotency_key },
+      stale ? void 0 : webhook.wholesale_feed_version
+    );
+  }
+  const items = applyWholesaleFeedEvent(scope.entity, previous.items, event);
+  if (!items)
+    return refreshMirror(
+      options,
+      { eventId: event.event_id, idempotencyKey: webhook.idempotency_key },
+      webhook.wholesale_feed_version
+    );
+  const next = {
+    ...previous,
+    items,
+    revision: previous.revision + 1,
+    wholesaleFeedVersion: webhook.wholesale_feed_version,
+    cacheScope: webhook.cache_scope,
+    lastSyncedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    lastWebhookEventId: event.event_id,
+    lastWebhookIdempotencyKey: webhook.idempotency_key,
+    error: void 0
+  };
+  if (options.isCurrent && !options.isCurrent()) return { outcome: "superseded" };
+  if (!await store.commit(scope, previous.revision, {
+    ...rowDiff(scope.entity, previous.items, items),
+    wholesaleFeedVersion: next.wholesaleFeedVersion,
+    pricingVersion: next.pricingVersion,
+    cacheScope: next.cacheScope,
+    lastSyncedAt: next.lastSyncedAt,
+    lastWebhookEventId: event.event_id,
+    lastWebhookIdempotencyKey: webhook.idempotency_key,
+    webhookReceipt: { eventId: event.event_id, idempotencyKey: webhook.idempotency_key }
+  }))
+    return { outcome: "superseded" };
+  return { outcome: "applied", snapshot: next, diff: [event] };
+}
+function applyWholesaleFeedEvent(entity, previous, event) {
+  const items = new Map(previous.map((item) => [itemId(entity, item), item]));
+  const payload = event.payload;
+  const id = entity === "product" ? payload.product_id : payload.signal_agent_segment_id;
+  if (!id) return void 0;
+  if (event.event_type.endsWith(".removed")) items.delete(id);
+  else if (event.event_type.endsWith(".priced")) {
+    const prior = items.get(id);
+    if (!prior || !Array.isArray(payload.pricing_options)) return void 0;
+    items.set(id, { ...prior, pricing_options: payload.pricing_options });
+  } else {
+    const item = entity === "product" ? payload.product : payload.signal;
+    if (!item || itemId(entity, item) !== id) return void 0;
+    items.set(id, item);
+  }
+  return [...items.values()];
+}
+function diffWholesaleFeed(entity, previous, next, cacheScope, includeAllChanges = false) {
+  const before = new Map(previous.map((item) => [itemId(entity, item), item]));
+  const after = new Map(next.map((item) => [itemId(entity, item), item]));
+  const events = [];
+  const emit = (id, action, data) => events.push({
+    event_id: randomUUID(),
+    event_type: `${entity}.${action}`,
+    entity_type: entity,
+    entity_id: id,
+    created_at: (/* @__PURE__ */ new Date()).toISOString(),
+    payload: {
+      [entity === "product" ? "product_id" : "signal_agent_segment_id"]: id,
+      ...data,
+      applies_to: { scope: cacheScope }
+    }
+  });
+  for (const [id, item] of after) {
+    const prior = before.get(id);
+    if (!prior) emit(id, "created", { [entity]: item });
+    else if (!isDeepStrictEqual(prior.pricing_options, item.pricing_options)) {
+      emit(id, "priced", { pricing_options: item.pricing_options ?? [] });
+      if (includeAllChanges && !isDeepStrictEqual({ ...prior, pricing_options: item.pricing_options }, item))
+        emit(id, "updated", { [entity]: item });
+    } else if (!isDeepStrictEqual(prior, item)) emit(id, "updated", { [entity]: item });
+  }
+  for (const id of before.keys()) if (!after.has(id)) emit(id, "removed", {});
+  return events;
+}
+function itemId(entity, item) {
+  return entity === "product" ? item.product_id : item.signal_agent_segment_id;
+}
+function rowDiff(entity, previous, next) {
+  const before = new Map(previous.map((item) => [itemId(entity, item), item]));
+  const ids = new Set(next.map((item) => itemId(entity, item)));
+  return {
+    upserts: next.filter((item) => !isDeepStrictEqual(before.get(itemId(entity, item)), item)),
+    deletes: [...before.keys()].filter((id) => !ids.has(id))
+  };
+}
+function isUuidV7(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function latestEventId(previous, next) {
+  return previous && isUuidV7(previous) && (!isUuidV7(next) || previous.toLowerCase() >= next.toLowerCase()) ? previous : next;
+}
+export {
+  InMemoryWholesaleFeedMirrorStore,
+  applyWholesaleFeedEvent,
+  applyWholesaleFeedWebhook,
+  diffWholesaleFeed,
+  refreshWholesaleFeed
+};

package/dist/lib/wholesale-feed-sync/sync.d.mts

@@ -4,12 +4,8 @@ import type { WholesaleFeedSyncConfig, WholesaleFeedSyncEvents, WholesaleFeedSyn
 type Product = LegacyWholesaleProduct;
 type Signal = LegacyWholesaleSignal;
 /**
- * In-memory mirror of an AdCP agent's wholesale product and signal feeds.
- *
- * Discovers the agent's wholesale-feed capabilities at `start()`, picks the
- * highest-capability sync strategy the agent supports, and maintains a
- * local index for zero-latency lookups. Falls back gracefully to manual
- * bootstrap when the agent does not advertise conditional-fetch tokens.
+ * In-memory wholesale product/signal mirror. `start()` discovers capabilities;
+ * versioned sellers use auto-poll, others require manual refresh.
  *
  * @example
  * ```ts
@@ -63,11 +59,10 @@ export declare class WholesaleFeedSync extends EventEmitter<WholesaleFeedSyncEve
     private probeTimer;
     private capabilityTimer;
     private lifecycleEpoch;
+    private mirrorRevision;
     /**
-     * Read-only view of the in-memory product index. The `mode` reflects the
-     * sync strategy for product events specifically — in mixed-capability
-     * agents (products-feed + signals-wholesale-only, or vice versa) this
-     * may differ from `signals.mode`.
+     * Product index view. `mode` identifies the product sync strategy and may
+     * differ from `signals.mode` for agents with mixed feed capabilities.
      */
     readonly products: {
         list: () => Product[];
@@ -86,30 +81,17 @@ export declare class WholesaleFeedSync extends EventEmitter<WholesaleFeedSyncEve
         readonly mode: WholesaleFeedSyncMode;
         _mode: WholesaleFeedSyncMode;
         /**
-         * `true` when the agent supports `discovery_mode: 'wholesale'` on
-         * `get_signals` (i.e., signals are browsable). When `false`, the
-         * agent only supports brief-mode discovery — `signals.list()` will
-         * be empty until adopters call into the agent with their own briefs.
+         * True when `get_signals` supports `discovery_mode: 'wholesale'`.
+         * Otherwise `list()` is empty; use client brief discovery instead.
          */
         queryable: boolean;
     };
-    /**
-     * One-shot console warning when adopters call `signals.list()` or
-     * `signals.search()` against an agent that doesn't support wholesale
-     * signal enumeration. Without this, empty results read as "no signals
-     * match" rather than "the agent doesn't browse, only briefs."
-     */
     private warnIfSignalsNotQueryable;
     constructor(config: WholesaleFeedSyncConfig);
     /**
-     * Probe the agent's capabilities, pick a sync mode, and bootstrap the
-     * in-memory replica via wholesale enumeration. In `'auto-poll'` mode
-     * starts the conditional wholesale-feed version probe loop.
-     *
-     * Safe to call repeatedly — concurrent calls await the in-flight
-     * bootstrap and return when it completes (no duplicate bootstrap, no
-     * silent drop). Sequential calls re-probe capabilities and re-bootstrap,
-     * equivalent to calling `refresh()` after a mode upgrade.
+     * Discover capabilities, bootstrap the mirror, and schedule auto-poll probes
+     * for versioned sellers. Concurrent calls share the bootstrap; sequential
+     * calls re-probe capabilities and refresh the mirror.
      */
     start(): Promise<void>;
     private startInner;
@@ -139,11 +121,12 @@ export declare class WholesaleFeedSync extends EventEmitter<WholesaleFeedSyncEve
     get lastSyncedAt(): Date | undefined;
     get lastEventAt(): Date | undefined;
     private resolveMode;
+    private bootstrapWithRetries;
     private bootstrap;
     private handleBootstrapFailure;
-    /** Returns `true` when the seller short-circuited with `unchanged: true`. */
     private bootstrapProducts;
     private bootstrapSignals;
+    private bootstrapFeed;
     private recoverFromBulkChange;
     private recoverFromVersionMismatch;
     private scheduleProbe;

package/dist/lib/wholesale-feed-sync/sync.d.ts

@@ -4,12 +4,8 @@ import type { WholesaleFeedSyncConfig, WholesaleFeedSyncEvents, WholesaleFeedSyn
 type Product = LegacyWholesaleProduct;
 type Signal = LegacyWholesaleSignal;
 /**
- * In-memory mirror of an AdCP agent's wholesale product and signal feeds.
- *
- * Discovers the agent's wholesale-feed capabilities at `start()`, picks the
- * highest-capability sync strategy the agent supports, and maintains a
- * local index for zero-latency lookups. Falls back gracefully to manual
- * bootstrap when the agent does not advertise conditional-fetch tokens.
+ * In-memory wholesale product/signal mirror. `start()` discovers capabilities;
+ * versioned sellers use auto-poll, others require manual refresh.
  *
  * @example
  * ```ts
@@ -63,11 +59,10 @@ export declare class WholesaleFeedSync extends EventEmitter<WholesaleFeedSyncEve
     private probeTimer;
     private capabilityTimer;
     private lifecycleEpoch;
+    private mirrorRevision;
     /**
-     * Read-only view of the in-memory product index. The `mode` reflects the
-     * sync strategy for product events specifically — in mixed-capability
-     * agents (products-feed + signals-wholesale-only, or vice versa) this
-     * may differ from `signals.mode`.
+     * Product index view. `mode` identifies the product sync strategy and may
+     * differ from `signals.mode` for agents with mixed feed capabilities.
      */
     readonly products: {
         list: () => Product[];
@@ -86,30 +81,17 @@ export declare class WholesaleFeedSync extends EventEmitter<WholesaleFeedSyncEve
         readonly mode: WholesaleFeedSyncMode;
         _mode: WholesaleFeedSyncMode;
         /**
-         * `true` when the agent supports `discovery_mode: 'wholesale'` on
-         * `get_signals` (i.e., signals are browsable). When `false`, the
-         * agent only supports brief-mode discovery — `signals.list()` will
-         * be empty until adopters call into the agent with their own briefs.
+         * True when `get_signals` supports `discovery_mode: 'wholesale'`.
+         * Otherwise `list()` is empty; use client brief discovery instead.
          */
         queryable: boolean;
     };
-    /**
-     * One-shot console warning when adopters call `signals.list()` or
-     * `signals.search()` against an agent that doesn't support wholesale
-     * signal enumeration. Without this, empty results read as "no signals
-     * match" rather than "the agent doesn't browse, only briefs."
-     */
     private warnIfSignalsNotQueryable;
     constructor(config: WholesaleFeedSyncConfig);
     /**
-     * Probe the agent's capabilities, pick a sync mode, and bootstrap the
-     * in-memory replica via wholesale enumeration. In `'auto-poll'` mode
-     * starts the conditional wholesale-feed version probe loop.
-     *
-     * Safe to call repeatedly — concurrent calls await the in-flight
-     * bootstrap and return when it completes (no duplicate bootstrap, no
-     * silent drop). Sequential calls re-probe capabilities and re-bootstrap,
-     * equivalent to calling `refresh()` after a mode upgrade.
+     * Discover capabilities, bootstrap the mirror, and schedule auto-poll probes
+     * for versioned sellers. Concurrent calls share the bootstrap; sequential
+     * calls re-probe capabilities and refresh the mirror.
      */
     start(): Promise<void>;
     private startInner;
@@ -139,11 +121,12 @@ export declare class WholesaleFeedSync extends EventEmitter<WholesaleFeedSyncEve
     get lastSyncedAt(): Date | undefined;
     get lastEventAt(): Date | undefined;
     private resolveMode;
+    private bootstrapWithRetries;
     private bootstrap;
     private handleBootstrapFailure;
-    /** Returns `true` when the seller short-circuited with `unchanged: true`. */
     private bootstrapProducts;
     private bootstrapSignals;
+    private bootstrapFeed;
     private recoverFromBulkChange;
     private recoverFromVersionMismatch;
     private scheduleProbe;