@adcp/sdk 14.0.0 → 14.1.0

package/dist/lib/wholesale-feed-sync/sync.js

@@ -25,6 +25,7 @@ var import_node_events = require("node:events");
 var import_node_util = require("node:util");
 var import_node_crypto = require("node:crypto");
 var import_webhook_notification = require('./webhook-notification.js');
+const bootstrapReadFailures = /* @__PURE__ */ new WeakSet();
 const DEFAULT_PROBE_INTERVAL_MS = 6e5;
 const DEFAULT_CAPABILITY_REFRESH_INTERVAL_MS = 864e5;
 const DEFAULT_PERSISTENCE_TIMEOUT_MS = 3e4;
@@ -172,12 +173,13 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
     const epoch = this.lifecycleEpoch;
     if (!await this.restorePersistedState(epoch)) return;
     if (!await this.resolveMode(epoch)) return;
-    if (!await this.bootstrap({ epoch })) return;
-    if (this._mode === "auto-poll") {
-      this.scheduleProbe(epoch);
-    }
-    if (this.capabilityRefreshIntervalMs > 0) {
-      this.scheduleCapabilityRefresh(epoch);
+    try {
+      await this.bootstrap({ epoch });
+    } finally {
+      if (this.isLifecycleCurrent(epoch)) {
+        if (this._mode === "auto-poll") this.scheduleProbe(epoch);
+        if (this.capabilityRefreshIntervalMs > 0) this.scheduleCapabilityRefresh(epoch);
+      }
     }
   }
   /** Stop all background activity. Preserves in-memory state and version tokens. */
@@ -187,7 +189,8 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
     if (this.capabilityTimer) clearTimeout(this.capabilityTimer);
     this.probeTimer = null;
     this.capabilityTimer = null;
-    if (this._state === "syncing" || this._state === "bootstrapping") this.setState("idle");
+    if (this._state === "syncing" || this._state === "bootstrapping" || this._state === "degraded")
+      this.setState("idle");
   }
   /**
    * Stop, clear all indexes and version tokens. Call `start()` again to
@@ -220,7 +223,7 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
   async refresh() {
     const epoch = this.lifecycleEpoch;
     this.emit("resyncing", { reason: "manual" });
-    await this.bootstrap({ emitDiffs: true, epoch });
+    await this.bootstrap({ emitDiffs: true, epoch, propagateFailure: true });
   }
   /**
    * Apply one legacy-view account-level wholesale feed webhook to the local mirror.
@@ -279,8 +282,10 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
       try {
         if (!await this.recoverFromBulkChange(event, epoch)) return;
       } catch (err) {
-        await this.markWebhookProcessed(dedupeKey, eventDedupeKey);
-        this.rememberLastWebhookEventId(event.event_id);
+        if (!(err instanceof Error && bootstrapReadFailures.has(err))) {
+          await this.markWebhookProcessed(dedupeKey, eventDedupeKey);
+          this.rememberLastWebhookEventId(event.event_id);
+        }
         throw err;
       }
       await this.markWebhookProcessed(dedupeKey, eventDedupeKey);
@@ -351,6 +356,8 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
     const epoch = options.epoch ?? this.lifecycleEpoch;
     if (!this.isLifecycleCurrent(epoch)) return false;
     this.setState("bootstrapping");
+    const previousLastSyncedAt = this._lastSyncedAt;
+    let reportedFailure;
     try {
       const previousProducts = new Map(this.productIndex);
       const previousSignals = new Map(this.signalIndex);
@@ -364,10 +371,32 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
       if (refreshProducts) {
         productResult = await this.bootstrapProducts(epoch);
         if (productResult.cancelled) return false;
+        if (productResult.failure) {
+          const failure = productResult.failure;
+          reportedFailure = failure.error;
+          this.handleBootstrapFailure(failure);
+          if (options.propagateFailure) {
+            bootstrapReadFailures.add(failure.error);
+            if (failure.adcpError) Object.assign(failure.error, { adcpError: failure.adcpError });
+            throw failure.error;
+          }
+          return false;
+        }
       }
       if (refreshSignals) {
         signalResult = await this.bootstrapSignals(epoch);
         if (signalResult.cancelled) return false;
+        if (signalResult.failure) {
+          const failure = signalResult.failure;
+          reportedFailure = failure.error;
+          this.handleBootstrapFailure(failure);
+          if (options.propagateFailure) {
+            bootstrapReadFailures.add(failure.error);
+            if (failure.adcpError) Object.assign(failure.error, { adcpError: failure.adcpError });
+            throw failure.error;
+          }
+          return false;
+        }
       }
       if (!this.isLifecycleCurrent(epoch)) return false;
       if (refreshProducts && productResult) {
@@ -401,13 +430,22 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
       return true;
     } catch (err) {
       if (!this.isLifecycleCurrent(epoch)) return false;
-      this.setState("error");
+      if (err === reportedFailure) throw err;
+      this._lastSyncedAt = previousLastSyncedAt;
+      this.setState(this._lastSyncedAt ? "degraded" : "error");
       const error = err instanceof Error ? err : new Error(String(err));
       this.errorHandler?.(error);
-      this.emit("error", { error });
+      if (this.listenerCount("error") > 0) this.emit("error", { error });
+      if (options.propagateFailure) bootstrapReadFailures.add(error);
       throw error;
     }
   }
+  handleBootstrapFailure(failure) {
+    this.setState(this._lastSyncedAt ? "degraded" : "error");
+    this.errorHandler?.(failure.error);
+    if (this.listenerCount("error") > 0) this.emit("error", failure);
+    return false;
+  }
   /** Returns `true` when the seller short-circuited with `unchanged: true`. */
   async bootstrapProducts(epoch) {
     let cursor;
@@ -425,8 +463,24 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
       }
       const result = await this.client.getProducts(params);
       if (!this.isLifecycleCurrent(epoch)) return { cancelled: true, unchanged: false, items: into, metadata };
+      if (result.success === false || result.status !== void 0 && result.status !== "completed" && result.status !== "success") {
+        return {
+          cancelled: false,
+          unchanged: false,
+          items: into,
+          metadata,
+          failure: { error: new Error(result.error ?? "Product bootstrap failed"), adcpError: result.adcpError }
+        };
+      }
       const body = result.data;
-      if (!body) return { cancelled: false, unchanged: false, items: into, metadata };
+      if (!body)
+        return {
+          cancelled: false,
+          unchanged: false,
+          items: into,
+          metadata,
+          failure: { error: new Error("Product bootstrap did not return a completed catalog") }
+        };
       if (body.unchanged) {
         metadata = mergeFeedMetadata(metadata, body);
         return { cancelled: false, unchanged: true, items: into, metadata };
@@ -457,8 +511,24 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
       }
       const result = await this.client.getSignals(params);
       if (!this.isLifecycleCurrent(epoch)) return { cancelled: true, unchanged: false, items: into, metadata };
+      if (result.success === false || result.status !== void 0 && result.status !== "completed" && result.status !== "success") {
+        return {
+          cancelled: false,
+          unchanged: false,
+          items: into,
+          metadata,
+          failure: { error: new Error(result.error ?? "Signal bootstrap failed"), adcpError: result.adcpError }
+        };
+      }
       const body = result.data;
-      if (!body) return { cancelled: false, unchanged: false, items: into, metadata };
+      if (!body)
+        return {
+          cancelled: false,
+          unchanged: false,
+          items: into,
+          metadata,
+          failure: { error: new Error("Signal bootstrap did not return a completed catalog") }
+        };
       if (body.unchanged) {
         metadata = mergeFeedMetadata(metadata, body);
         return { cancelled: false, unchanged: true, items: into, metadata };
@@ -482,13 +552,13 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
       );
     }
     const entities = affected === "product" ? "products" : "signals";
-    return this.bootstrap({ emitDiffs: true, entities, epoch });
+    return this.bootstrap({ emitDiffs: true, entities, epoch, propagateFailure: true });
   }
   async recoverFromVersionMismatch(event, epoch = this.lifecycleEpoch) {
     this.emit("resyncing", { reason: "version_mismatch" });
     const beforeVersion = this.currentWholesaleFeedVersionForEvent(event);
     for (let attempt = 1; attempt <= VERSION_MISMATCH_RECOVERY_ATTEMPTS; attempt++) {
-      const recovered = await this.bootstrap({ emitDiffs: true, epoch });
+      const recovered = await this.bootstrap({ emitDiffs: true, epoch, propagateFailure: true });
       if (!recovered) return false;
       const afterVersion = this.currentWholesaleFeedVersionForEvent(event);
       if (afterVersion !== beforeVersion) return true;
@@ -510,11 +580,12 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
       await this.probeVersion(epoch);
     } catch (err) {
       if (!this.isLifecycleCurrent(epoch)) return;
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.emit("error", { error });
-      this.errorHandler?.(error);
+      if (this._state !== "degraded" && this._state !== "error") {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.handleBootstrapFailure({ error });
+      }
     }
-    if (this.isLifecycleCurrent(epoch) && this._state === "syncing" && this._mode === "auto-poll") {
+    if (this.isLifecycleCurrent(epoch) && (this._state === "syncing" || this._state === "degraded" || this._state === "error") && this._mode === "auto-poll") {
       this.scheduleProbe(epoch);
     }
   }
@@ -541,7 +612,7 @@ class WholesaleFeedSync extends import_node_events.EventEmitter {
       this.emit("error", { error });
       this.errorHandler?.(error);
     }
-    if (this.isLifecycleCurrent(epoch) && this._state === "syncing" && this.capabilityRefreshIntervalMs > 0) {
+    if (this.isLifecycleCurrent(epoch) && (this._state === "syncing" || this._state === "degraded" || this._state === "error") && this.capabilityRefreshIntervalMs > 0) {
       this.scheduleCapabilityRefresh(epoch);
     }
   }

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

@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
 import { isDeepStrictEqual } from "node:util";
 import { randomUUID } from "node:crypto";
 import { assertLegacyWholesaleFeedRepresentation } from "./webhook-notification.mjs";
+const bootstrapReadFailures = /* @__PURE__ */ new WeakSet();
 const DEFAULT_PROBE_INTERVAL_MS = 6e5;
 const DEFAULT_CAPABILITY_REFRESH_INTERVAL_MS = 864e5;
 const DEFAULT_PERSISTENCE_TIMEOUT_MS = 3e4;
@@ -149,12 +150,13 @@ class WholesaleFeedSync extends EventEmitter {
     const epoch = this.lifecycleEpoch;
     if (!await this.restorePersistedState(epoch)) return;
     if (!await this.resolveMode(epoch)) return;
-    if (!await this.bootstrap({ epoch })) return;
-    if (this._mode === "auto-poll") {
-      this.scheduleProbe(epoch);
-    }
-    if (this.capabilityRefreshIntervalMs > 0) {
-      this.scheduleCapabilityRefresh(epoch);
+    try {
+      await this.bootstrap({ epoch });
+    } finally {
+      if (this.isLifecycleCurrent(epoch)) {
+        if (this._mode === "auto-poll") this.scheduleProbe(epoch);
+        if (this.capabilityRefreshIntervalMs > 0) this.scheduleCapabilityRefresh(epoch);
+      }
     }
   }
   /** Stop all background activity. Preserves in-memory state and version tokens. */
@@ -164,7 +166,8 @@ class WholesaleFeedSync extends EventEmitter {
     if (this.capabilityTimer) clearTimeout(this.capabilityTimer);
     this.probeTimer = null;
     this.capabilityTimer = null;
-    if (this._state === "syncing" || this._state === "bootstrapping") this.setState("idle");
+    if (this._state === "syncing" || this._state === "bootstrapping" || this._state === "degraded")
+      this.setState("idle");
   }
   /**
    * Stop, clear all indexes and version tokens. Call `start()` again to
@@ -197,7 +200,7 @@ class WholesaleFeedSync extends EventEmitter {
   async refresh() {
     const epoch = this.lifecycleEpoch;
     this.emit("resyncing", { reason: "manual" });
-    await this.bootstrap({ emitDiffs: true, epoch });
+    await this.bootstrap({ emitDiffs: true, epoch, propagateFailure: true });
   }
   /**
    * Apply one legacy-view account-level wholesale feed webhook to the local mirror.
@@ -256,8 +259,10 @@ class WholesaleFeedSync extends EventEmitter {
       try {
         if (!await this.recoverFromBulkChange(event, epoch)) return;
       } catch (err) {
-        await this.markWebhookProcessed(dedupeKey, eventDedupeKey);
-        this.rememberLastWebhookEventId(event.event_id);
+        if (!(err instanceof Error && bootstrapReadFailures.has(err))) {
+          await this.markWebhookProcessed(dedupeKey, eventDedupeKey);
+          this.rememberLastWebhookEventId(event.event_id);
+        }
         throw err;
       }
       await this.markWebhookProcessed(dedupeKey, eventDedupeKey);
@@ -328,6 +333,8 @@ class WholesaleFeedSync extends EventEmitter {
     const epoch = options.epoch ?? this.lifecycleEpoch;
     if (!this.isLifecycleCurrent(epoch)) return false;
     this.setState("bootstrapping");
+    const previousLastSyncedAt = this._lastSyncedAt;
+    let reportedFailure;
     try {
       const previousProducts = new Map(this.productIndex);
       const previousSignals = new Map(this.signalIndex);
@@ -341,10 +348,32 @@ class WholesaleFeedSync extends EventEmitter {
       if (refreshProducts) {
         productResult = await this.bootstrapProducts(epoch);
         if (productResult.cancelled) return false;
+        if (productResult.failure) {
+          const failure = productResult.failure;
+          reportedFailure = failure.error;
+          this.handleBootstrapFailure(failure);
+          if (options.propagateFailure) {
+            bootstrapReadFailures.add(failure.error);
+            if (failure.adcpError) Object.assign(failure.error, { adcpError: failure.adcpError });
+            throw failure.error;
+          }
+          return false;
+        }
       }
       if (refreshSignals) {
         signalResult = await this.bootstrapSignals(epoch);
         if (signalResult.cancelled) return false;
+        if (signalResult.failure) {
+          const failure = signalResult.failure;
+          reportedFailure = failure.error;
+          this.handleBootstrapFailure(failure);
+          if (options.propagateFailure) {
+            bootstrapReadFailures.add(failure.error);
+            if (failure.adcpError) Object.assign(failure.error, { adcpError: failure.adcpError });
+            throw failure.error;
+          }
+          return false;
+        }
       }
       if (!this.isLifecycleCurrent(epoch)) return false;
       if (refreshProducts && productResult) {
@@ -378,13 +407,22 @@ class WholesaleFeedSync extends EventEmitter {
       return true;
     } catch (err) {
       if (!this.isLifecycleCurrent(epoch)) return false;
-      this.setState("error");
+      if (err === reportedFailure) throw err;
+      this._lastSyncedAt = previousLastSyncedAt;
+      this.setState(this._lastSyncedAt ? "degraded" : "error");
       const error = err instanceof Error ? err : new Error(String(err));
       this.errorHandler?.(error);
-      this.emit("error", { error });
+      if (this.listenerCount("error") > 0) this.emit("error", { error });
+      if (options.propagateFailure) bootstrapReadFailures.add(error);
       throw error;
     }
   }
+  handleBootstrapFailure(failure) {
+    this.setState(this._lastSyncedAt ? "degraded" : "error");
+    this.errorHandler?.(failure.error);
+    if (this.listenerCount("error") > 0) this.emit("error", failure);
+    return false;
+  }
   /** Returns `true` when the seller short-circuited with `unchanged: true`. */
   async bootstrapProducts(epoch) {
     let cursor;
@@ -402,8 +440,24 @@ class WholesaleFeedSync extends EventEmitter {
       }
       const result = await this.client.getProducts(params);
       if (!this.isLifecycleCurrent(epoch)) return { cancelled: true, unchanged: false, items: into, metadata };
+      if (result.success === false || result.status !== void 0 && result.status !== "completed" && result.status !== "success") {
+        return {
+          cancelled: false,
+          unchanged: false,
+          items: into,
+          metadata,
+          failure: { error: new Error(result.error ?? "Product bootstrap failed"), adcpError: result.adcpError }
+        };
+      }
       const body = result.data;
-      if (!body) return { cancelled: false, unchanged: false, items: into, metadata };
+      if (!body)
+        return {
+          cancelled: false,
+          unchanged: false,
+          items: into,
+          metadata,
+          failure: { error: new Error("Product bootstrap did not return a completed catalog") }
+        };
       if (body.unchanged) {
         metadata = mergeFeedMetadata(metadata, body);
         return { cancelled: false, unchanged: true, items: into, metadata };
@@ -434,8 +488,24 @@ class WholesaleFeedSync extends EventEmitter {
       }
       const result = await this.client.getSignals(params);
       if (!this.isLifecycleCurrent(epoch)) return { cancelled: true, unchanged: false, items: into, metadata };
+      if (result.success === false || result.status !== void 0 && result.status !== "completed" && result.status !== "success") {
+        return {
+          cancelled: false,
+          unchanged: false,
+          items: into,
+          metadata,
+          failure: { error: new Error(result.error ?? "Signal bootstrap failed"), adcpError: result.adcpError }
+        };
+      }
       const body = result.data;
-      if (!body) return { cancelled: false, unchanged: false, items: into, metadata };
+      if (!body)
+        return {
+          cancelled: false,
+          unchanged: false,
+          items: into,
+          metadata,
+          failure: { error: new Error("Signal bootstrap did not return a completed catalog") }
+        };
       if (body.unchanged) {
         metadata = mergeFeedMetadata(metadata, body);
         return { cancelled: false, unchanged: true, items: into, metadata };
@@ -459,13 +529,13 @@ class WholesaleFeedSync extends EventEmitter {
       );
     }
     const entities = affected === "product" ? "products" : "signals";
-    return this.bootstrap({ emitDiffs: true, entities, epoch });
+    return this.bootstrap({ emitDiffs: true, entities, epoch, propagateFailure: true });
   }
   async recoverFromVersionMismatch(event, epoch = this.lifecycleEpoch) {
     this.emit("resyncing", { reason: "version_mismatch" });
     const beforeVersion = this.currentWholesaleFeedVersionForEvent(event);
     for (let attempt = 1; attempt <= VERSION_MISMATCH_RECOVERY_ATTEMPTS; attempt++) {
-      const recovered = await this.bootstrap({ emitDiffs: true, epoch });
+      const recovered = await this.bootstrap({ emitDiffs: true, epoch, propagateFailure: true });
       if (!recovered) return false;
       const afterVersion = this.currentWholesaleFeedVersionForEvent(event);
       if (afterVersion !== beforeVersion) return true;
@@ -487,11 +557,12 @@ class WholesaleFeedSync extends EventEmitter {
       await this.probeVersion(epoch);
     } catch (err) {
       if (!this.isLifecycleCurrent(epoch)) return;
-      const error = err instanceof Error ? err : new Error(String(err));
-      this.emit("error", { error });
-      this.errorHandler?.(error);
+      if (this._state !== "degraded" && this._state !== "error") {
+        const error = err instanceof Error ? err : new Error(String(err));
+        this.handleBootstrapFailure({ error });
+      }
     }
-    if (this.isLifecycleCurrent(epoch) && this._state === "syncing" && this._mode === "auto-poll") {
+    if (this.isLifecycleCurrent(epoch) && (this._state === "syncing" || this._state === "degraded" || this._state === "error") && this._mode === "auto-poll") {
       this.scheduleProbe(epoch);
     }
   }
@@ -518,7 +589,7 @@ class WholesaleFeedSync extends EventEmitter {
       this.emit("error", { error });
       this.errorHandler?.(error);
     }
-    if (this.isLifecycleCurrent(epoch) && this._state === "syncing" && this.capabilityRefreshIntervalMs > 0) {
+    if (this.isLifecycleCurrent(epoch) && (this._state === "syncing" || this._state === "degraded" || this._state === "error") && this.capabilityRefreshIntervalMs > 0) {
       this.scheduleCapabilityRefresh(epoch);
     }
   }

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

@@ -22,7 +22,7 @@ export type WholesaleFeedSyncMode = 'manual' | 'auto-poll';
 /**
  * Lifecycle state of the sync engine.
  */
-export type WholesaleFeedSyncState = 'idle' | 'bootstrapping' | 'syncing' | 'error';
+export type WholesaleFeedSyncState = 'idle' | 'bootstrapping' | 'syncing' | 'degraded' | 'error';
 /**
  * Subset of `SingleAgentClient` that {@link WholesaleFeedSync} actually uses.
  * Lets tests inject a minimal stub without constructing a full client.
@@ -178,8 +178,8 @@ export interface ResolvedCapabilities {
  *   picks a mode. Useful for UI mode badges.
  * - `resyncing` — emitted before a `wholesale_feed.bulk_change` recovery
  *   re-bootstrap, webhook-version mismatch repair, or manual refresh.
- * - `error` — background poll/probe error. Non-fatal; sync stays in
- *   `'syncing'` and retries on the next tick.
+ * - `error` — initial bootstrap, re-sync, or background probe failure.
+ *   Failed refreshes preserve the last good mirror and retry on the next tick.
  * - `stateChange` — fires on every {@link WholesaleFeedSyncState} transition.
  */
 export interface WholesaleFeedSyncEvents {
@@ -200,6 +200,7 @@ export interface WholesaleFeedSyncEvents {
     }];
     error: [{
         error: Error;
+        adcpError?: import('../core/ConversationTypes.mjs').AdcpErrorInfo;
     }];
     stateChange: [{
         from: WholesaleFeedSyncState;

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

@@ -22,7 +22,7 @@ export type WholesaleFeedSyncMode = 'manual' | 'auto-poll';
 /**
  * Lifecycle state of the sync engine.
  */
-export type WholesaleFeedSyncState = 'idle' | 'bootstrapping' | 'syncing' | 'error';
+export type WholesaleFeedSyncState = 'idle' | 'bootstrapping' | 'syncing' | 'degraded' | 'error';
 /**
  * Subset of `SingleAgentClient` that {@link WholesaleFeedSync} actually uses.
  * Lets tests inject a minimal stub without constructing a full client.
@@ -178,8 +178,8 @@ export interface ResolvedCapabilities {
  *   picks a mode. Useful for UI mode badges.
  * - `resyncing` — emitted before a `wholesale_feed.bulk_change` recovery
  *   re-bootstrap, webhook-version mismatch repair, or manual refresh.
- * - `error` — background poll/probe error. Non-fatal; sync stays in
- *   `'syncing'` and retries on the next tick.
+ * - `error` — initial bootstrap, re-sync, or background probe failure.
+ *   Failed refreshes preserve the last good mirror and retry on the next tick.
  * - `stateChange` — fires on every {@link WholesaleFeedSyncState} transition.
  */
 export interface WholesaleFeedSyncEvents {
@@ -200,6 +200,7 @@ export interface WholesaleFeedSyncEvents {
     }];
     error: [{
         error: Error;
+        adcpError?: import('../core/ConversationTypes').AdcpErrorInfo;
     }];
     stateChange: [{
         from: WholesaleFeedSyncState;

package/docs/TYPE-SUMMARY.md

@@ -1,7 +1,7 @@
 # AdCP Type Summary
 
-> Generated at: 2026-10-01
-> @adcp/sdk v14.0.0
+> Generated at: 2026-10-04
+> @adcp/sdk v14.1.0
 
 Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
 

package/docs/guides/BUILD-AN-AGENT.md

@@ -671,7 +671,7 @@ import {
   requireAuthenticatedOrSigned,
   mcpToolNameResolver,
 } from '@adcp/sdk/server';
-import { BrandJsonJwksResolver } from '@adcp/sdk/signing/server';
+import { ResolvedAgentJwksResolver } from '@adcp/sdk/signing/server';
 
 serve(
   () =>
@@ -692,7 +692,7 @@ serve(
     authenticate: requireAuthenticatedOrSigned({
       signature: verifySignatureAsAuthenticator({
         capability: { supported: true, required_for: ['create_media_buy', 'update_media_buy'], covers_content_digest: 'either' },
-        jwks: new BrandJsonJwksResolver(),
+        jwks: new ResolvedAgentJwksResolver('https://buyer.example/mcp', 'mcp'),
         resolveOperation: mcpToolNameResolver,
       }),
       fallback: verifyApiKey({ keys: { sk_live_abc: { principal: 'acct_42' } } }),

package/docs/guides/BUYER-QUICKSTART-3.2.md

@@ -1,5 +1,7 @@
 # Call a seller with AdCP 3.2
 
+For a new seller, start with [account setup and public discovery](./FIRST-CALL-TO-A-SELLER.md).
+
 For product possibility, accepted change rights, and current execution routes, use the [MediaBuy action assessment helpers](./MEDIA-BUY-ACTION-ASSESSMENT.md).
 
 Requires Node.js `^20.19.0 || >=22.12.0`. Install SDK 14

package/docs/guides/FIRST-CALL-TO-A-SELLER.md

@@ -0,0 +1,104 @@
+# First call to a seller
+
+An account reference selects a provisioned account at that seller. Discovery
+does not provision it. Until setup is complete, send a top-level `brand` on
+tools that support public discovery, and omit `account`.
+
+```ts
+import { AgentClient, createProductCache } from '@adcp/sdk';
+
+const client = new AgentClient(sellerConfig, {
+  accountPolicy: 'auto',
+  productCache: createProductCache({ publicTtl: 60_000, accountTtl: 30_000 }),
+});
+const capabilities = await client.getCapabilities();
+const brand = { domain: 'advertiser.example' };
+const account = { brand, operator: 'agency.example' };
+
+// Only use public discovery when the seller permits it.
+if (!capabilities.account?.requiredForProducts) {
+  const publicCatalog = await client.getProducts({ brand, brief: 'Display inventory' });
+  if (!publicCatalog.success) console.error(publicCatalog.adcpError);
+}
+
+// Choose billing terms before accepting them. This returns seller status and handle.
+const setup = await client.accounts.ensure(account, {
+  billing: 'operator',
+  paymentTerms: 'net_30',
+});
+if (setup.status === 'active') {
+  const pricedCatalog = await client.getProducts({ account, brand, brief: 'Display inventory' });
+  if (!pricedCatalog.success) console.error(pricedCatalog.adcpError);
+}
+```
+
+For agent-billed provisioning, pass `billingEntity` with the seller's required
+business identity. `paymentTerms` and `billingEntity` are also accepted by
+`resolveAccount()`. That helper keeps its existing pending-approval exception;
+`accounts.ensure()` returns the status so callers can present the setup flow.
+Non-active entries refresh through `list_accounts` when a seller handle is known.
+An existing registry entry prevents repeated provisioning and silent acceptance
+of new terms. To change terms, explicitly call `syncAccounts()`.
+An explicit `ensure` with conflicting known setup terms refuses the change.
+If the seller no longer lists an account, explicitly reestablish it with
+`syncAccounts` after choosing terms; status repair never silently re-provisions it.
+Caller cancellation stops waiting for setup; the single seller operation continues
+so another caller cannot accidentally accept different terms concurrently.
+Terminal setup failures permit an explicit retry. For interrupted async setup,
+read `accounts.get(key).pendingTaskId`, reconcile that seller task, and pass its
+completed rows to `accounts.observeSync([key], rows)` (or let the original
+`syncAccounts` completion handle update the registry). Do not resubmit unresolved tasks.
+
+For a seller that requires operator authentication, use `resolveAccount()` to
+select an active account returned by `list_accounts`. An account ID echoed by
+`sync_accounts` is a seller handle; implicit sellers still require the natural
+key on subsequent calls. Do not replace it with `{ account_id }` automatically.
+
+`accountPolicy` defaults to `'off'` to preserve existing requests. Opt-in
+`'auto'` omits unknown accounts on public discovery tools that support `brand`;
+it refuses required-account discovery, async discovery, and mutations until
+the registry knows the key. `'strict'` refuses every unknown account-carrying
+request. Both policies require an active account before spend commitments.
+Explicit account filters on `list_accounts` remain filters.
+Call `listAccounts` first when adopting these policies with existing opaque
+account IDs so the registry knows those seller handles.
+
+Provisioning is remembered per seller and caller. `syncAccounts()` and
+`listAccounts()` update the registry on completed results; failed rows and dry
+runs do not establish accounts. After verifying an `account.status_changed`
+notification, call `client.accounts.applyStatusChange({ account_id })` to repair
+from authoritative `list_accounts`. The notification's status is not trusted as
+a snapshot, which avoids reordered deliveries overwriting current state.
+
+The registry is in memory by default. Set `accountStorage` to an adapter with
+`get(key)` and `set(key, entry)` for persistence. Keys partition by seller URI,
+protocol, and caller scope. Client-credentials OAuth uses the stable client ID, token endpoint, scopes, and resource. Authorization-code OAuth pins this client's initial grant fingerprint, keeping distinct user grants apart while automatic refreshes preserve its partition. Create a new client when switching users. Other credential modes fingerprint credentials;
+for continuity across token rotations, supply `accountRegistryScope` from a
+trusted stable principal identifier. Never share that scope between tenants.
+Request-signing key identity is also part of the default fingerprint, so distinct
+signers stay isolated. Key rotation requires reprovisioning or a trusted stable
+`accountRegistryScope` for the same principal.
+Registry memory and aliases per handle are bounded by `accountRegistryMaxEntries` (default 10,000); durable adapters allow entry eviction and reload. Without storage, reaching capacity throws a setup error; raise the limit or configure storage for large rosters. `resolveAccount()` uses the memoized registry only when you opt in with `accountPolicy: 'auto' | 'strict'`, `accountStorage`, `accountRegistryScope`, or `accountRegistryMaxEntries`; that internal use does not enable observations of unrelated rosters. Otherwise it keeps the 14.0 behavior: every call sends `sync_accounts` and reflects the seller's current status. Memoized entries require explicit `syncAccounts()` or authoritative status repair when seller linkage expires or is replaced externally. Stored entries contain account references, seller handles, status, optional pending task IDs, and hashes of explicitly chosen setup terms;
+billing entities and tokens are not persisted. Manual feed mode recovers through
+an explicit `refresh()`; auto-poll mode also retries initial failures.
+
+Typed `AccountNotFoundError`, `AccountSetupRequiredError`, and
+`AccountPaymentRequiredError` carry `fault: 'buyer_setup'`. Health trackers
+should exclude them from seller-health failure counts. Failed task results still
+expose the protocol code in `result.adcpError` and the typed exception in
+`result.errorInstance`.
+
+The optional product cache uses TTLs in milliseconds and keeps at most `maxEntries` entries (default 1,000). It keeps public and
+account-scoped responses apart and stores the feed version and pricing version
+with each snapshot. Missing `cache_scope` prevents caching. Stale entries are
+conditionally revalidated using their own tokens; failures remain visible to
+the caller and never erase the last valid entry. Caller-authored feed or pricing validators
+retain their unchanged-response semantics. Caches are scoped to the client
+instance so different local verification policies cannot share filtered results.
+
+`WholesaleFeedSync` similarly keeps its last good product and signal mirrors on
+a failed refresh. Its error event includes `adcpError`; a mirror becomes
+`degraded` until a successful refresh restores `syncing`. Initial failure sets
+`error`. Exhaustive state switches must handle the new `degraded` member.
+
+Manual `WholesaleFeedSync.refresh()` and webhook repairs reject failed catalog reads, including failed task results. A failed webhook repair remains eligible for redelivery; acknowledge it only after repair succeeds. Bootstrap `start()` still reports failed task results through its state and error callback/event, and schedules recovery in auto-poll mode.