@adcp/sdk 6.1.0 → 6.2.0

package/dist/lib/utils/sync-creatives-adapter.js

@@ -2,44 +2,97 @@
 /**
  * Sync Creatives Adapter
  *
- * Handles conversion between v2 and v3 sync_creatives requests.
- * The library exposes only the v3 API to clients and internally adapts
- * requests for v2 servers.
+ * Adapts v3 `sync_creatives` request payloads for v2.5 servers. The public
+ * surface (`adaptSyncCreativesRequestForV2`) is unchanged; all conversions
+ * are transparent to callers.
  *
- * Key v3 → v2 differences:
- *   - `account` field is required in v3 but absent in v2 — stripped on send
- *   - `catalogs` array on each creative is v3-only — stripped on send
- *   - `status` enum ('approved' | 'rejected') replaces v2 `approved` boolean
+ * v3 → v2 field mappings applied here:
+ *   - `account` / `adcp_major_version` — stripped (v3-only top-level fields)
+ *   - `catalogs` per creative — stripped (v3-only)
+ *   - `status` enum ('approved' | 'rejected') → `approved` boolean
+ *   - `assets` as a role-keyed manifest ({ video: { asset_type, url, … } })
+ *     → flattened to a single v2 asset payload (`oneOf` discriminated by
+ *     `asset_type`). The primary (first) role is forwarded; remaining roles
+ *     are dropped with a console.warn naming the discarded roles. To preserve
+ *     all roles, connect to a v3 server.
+ *   - `assets` already flat (has `asset_type` at top level) — passed through
+ *     unchanged.
+ *   - No `assets` field — omitted.
+ *
+ * @internal Not part of the public @adcp/sdk API surface.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.adaptSyncCreativesRequestForV2 = adaptSyncCreativesRequestForV2;
 /**
- * Adapt a single creative asset for a v2 server.
- * Strips v3-only fields and converts `status` enum → `approved` boolean.
+ * Returns true for a v3 role-keyed manifest ({ role: AssetInstance, … }).
+ * Returns false for a flat v2 asset payload (has top-level `asset_type`),
+ * for an empty object, or for any non-plain-object value.
+ */
+function isManifestShape(assets) {
+    if (typeof assets !== 'object' || assets === null || Array.isArray(assets))
+        return false;
+    if ('asset_type' in assets)
+        return false; // already a flat single-asset payload
+    const values = Object.values(assets);
+    // Empty object is not a manifest — treat as pass-through
+    return values.some(v => typeof v === 'object' && v !== null && 'asset_type' in v);
+}
+/**
+ * Adapt a single creative for a v2 server.
+ * Strips v3-only fields, converts `status` enum → `approved` boolean,
+ * and flattens a manifest-shaped `assets` to a single v2 asset payload.
  */
-function adaptCreativeAssetForV2(creative) {
-    const { catalogs, status, ...rest } = creative;
-    const adapted = { ...rest };
+function adaptCreativeForV2(creative) {
+    const { catalogs, status, assets, ...rest } = creative;
+    const base = { ...rest };
     // Convert v3 status enum → v2 approved boolean
     if (status === 'approved') {
-        adapted.approved = true;
+        base.approved = true;
     }
     else if (status === 'rejected') {
-        adapted.approved = false;
+        base.approved = false;
     }
     // Any other status value (or absent) — omit approved entirely
-    return adapted;
+    if (assets === undefined) {
+        // v3 schema marks assets as required, but guard defensively for any
+        // typed as any that arrives without the field
+        return base;
+    }
+    if (!isManifestShape(assets)) {
+        // Already a flat asset payload (has asset_type at top level), an empty
+        // object, or an unrecognised shape — pass through verbatim and let the
+        // server's response validation surface any mismatch
+        return { ...base, assets };
+    }
+    // Manifest: { role: AssetInstance, … }
+    // isManifestShape guarantees at least one entry with asset_type, but the first
+    // entry may be a non-asset role (e.g. metadata). Pick the first entry whose
+    // value actually carries asset_type so the forwarded payload is always valid.
+    const entries = Object.entries(assets);
+    const primary = entries.find(([, v]) => typeof v === 'object' && v !== null && 'asset_type' in v);
+    if (!primary) {
+        // All roles are malformed — pass through verbatim, let the server reject
+        return { ...base, assets };
+    }
+    const [primaryRole, primaryAsset] = primary;
+    const assetRoles = entries.map(([r]) => r);
+    if (assetRoles.length > 1) {
+        console.warn(`[AdCP] sync_creatives: creative "${base.creative_id}" has multiple asset roles ` +
+            `(${assetRoles.join(', ')}); only "${primaryRole}" will be sent to v2 server. ` +
+            `Upgrade to a v3 server to preserve all roles.`);
+    }
+    return { ...base, assets: primaryAsset };
 }
 /**
  * Adapt a sync_creatives request for a v2 server.
- * Strips v3-only top-level fields and adapts each creative asset.
+ * Strips v3-only top-level fields and adapts each creative.
  */
 function adaptSyncCreativesRequestForV2(request) {
     const { account, adcp_major_version, ...rest } = request;
     return {
         ...rest,
         ...(rest.creatives && {
-            creatives: rest.creatives.map(adaptCreativeAssetForV2),
+            creatives: rest.creatives.map(adaptCreativeForV2),
         }),
     };
 }

package/dist/lib/utils/sync-creatives-adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-creatives-adapter.js","sourceRoot":"","sources":["../../../src/lib/utils/sync-creatives-adapter.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AA0BH,wEASC;AAjCD;;;GAGG;AACH,SAAS,uBAAuB,CAAC,QAAa;IAC5C,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC;IAE/C,MAAM,OAAO,GAAQ,EAAE,GAAG,IAAI,EAAE,CAAC;IAEjC,+CAA+C;IAC/C,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QAC1B,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1B,CAAC;SAAM,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,CAAC,QAAQ,GAAG,KAAK,CAAC;IAC3B,CAAC;IACD,8DAA8D;IAE9D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,SAAgB,8BAA8B,CAAC,OAAY;IACzD,MAAM,EAAE,OAAO,EAAE,kBAAkB,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,CAAC;IAEzD,OAAO;QACL,GAAG,IAAI;QACP,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI;YACpB,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,CAAC;SACvD,CAAC;KACH,CAAC;AACJ,CAAC"}
+{"version":3,"file":"sync-creatives-adapter.js","sourceRoot":"","sources":["../../../src/lib/utils/sync-creatives-adapter.ts"],"names":[],"mappings":"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"}

package/dist/lib/validation/client-hooks.d.ts

@@ -6,21 +6,26 @@
 import { type ValidationOutcome } from './schema-validator';
 export type ValidationMode = 'strict' | 'warn' | 'off';
 export interface ValidationHookConfig {
-    /** Validate outgoing requests. Default: strict in dev/test, warn in prod. */
+    /** Validate outgoing requests. Default: `warn` everywhere. */
     requests?: ValidationMode;
-    /** Validate incoming responses. Default: strict in dev/test, warn in prod. */
+    /** Validate incoming responses. Default: `warn` everywhere. */
     responses?: ValidationMode;
 }
 /**
  * Resolve the effective request/response modes.
  *
- * Response default: strict in dev/test, warn in prod (preserves the
- * existing `strictSchemaValidation` contract).
+ * Both default to `warn` everywhere — buyers get drift surfaced through
+ * `result.debug_logs` without losing the response payload to a strict
+ * rejection. v2.5 sellers in particular ship enough legacy drift
+ * (envelope nulls, optional-required fields, enum mismatches) that
+ * strict-by-default leaves callers staring at "0 products" with no
+ * useful signal. Buyers and harnesses that want hard-stop behavior
+ * (conformance suites, third-party validators) opt into strict via
+ * `validation: { responses: 'strict' }` — explicit config always wins.
  *
- * Request default: `warn` everywhere. Strict-by-default would break
- * existing callers that intentionally send partial payloads (error-path
- * tests, exploratory probes) — storyboards and third-party clients that
- * want hard-stop enforcement should set `requests: 'strict'` explicitly.
+ * This is the **client-side** default. `createAdcpServer` keeps its
+ * stricter dev/test handler-validation contract — that catches our own
+ * handler bugs, which strict mode is genuinely good at.
  */
 export declare function resolveValidationModes(config?: ValidationHookConfig): Required<ValidationHookConfig>;
 export interface DebugLogEntry {

package/dist/lib/validation/client-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client-hooks.d.ts","sourceRoot":"","sources":["../../../src/lib/validation/client-hooks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAmD,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG7G,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAKpG;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAaD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,cAAc,EACpB,SAAS,CAAC,EAAE,aAAa,EAAE,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,iBAAiB,GAAG,SAAS,CAS/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,cAAc,EACpB,SAAS,CAAC,EAAE,aAAa,EAAE,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,iBAAiB,CAOnB"}
+{"version":3,"file":"client-hooks.d.ts","sourceRoot":"","sources":["../../../src/lib/validation/client-hooks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAmD,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG7G,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,+DAA+D;IAC/D,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,oBAAoB,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAKpG;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAaD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,cAAc,EACpB,SAAS,CAAC,EAAE,aAAa,EAAE,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,iBAAiB,GAAG,SAAS,CAS/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,cAAc,EACpB,SAAS,CAAC,EAAE,aAAa,EAAE,EAC3B,OAAO,CAAC,EAAE,MAAM,GACf,iBAAiB,CAOnB"}

package/dist/lib/validation/client-hooks.js

@@ -10,26 +10,26 @@ exports.validateOutgoingRequest = validateOutgoingRequest;
 exports.validateIncomingResponse = validateIncomingResponse;
 const schema_validator_1 = require("./schema-validator");
 const schema_errors_1 = require("./schema-errors");
-function defaultResponseMode() {
-    // Responses have been validated strictly by default since the SDK shipped
-    // Zod validation; preserve that in dev/test and soften to warn in prod.
-    return process.env.NODE_ENV === 'production' ? 'warn' : 'strict';
-}
 /**
  * Resolve the effective request/response modes.
  *
- * Response default: strict in dev/test, warn in prod (preserves the
- * existing `strictSchemaValidation` contract).
+ * Both default to `warn` everywhere — buyers get drift surfaced through
+ * `result.debug_logs` without losing the response payload to a strict
+ * rejection. v2.5 sellers in particular ship enough legacy drift
+ * (envelope nulls, optional-required fields, enum mismatches) that
+ * strict-by-default leaves callers staring at "0 products" with no
+ * useful signal. Buyers and harnesses that want hard-stop behavior
+ * (conformance suites, third-party validators) opt into strict via
+ * `validation: { responses: 'strict' }` — explicit config always wins.
  *
- * Request default: `warn` everywhere. Strict-by-default would break
- * existing callers that intentionally send partial payloads (error-path
- * tests, exploratory probes) — storyboards and third-party clients that
- * want hard-stop enforcement should set `requests: 'strict'` explicitly.
+ * This is the **client-side** default. `createAdcpServer` keeps its
+ * stricter dev/test handler-validation contract — that catches our own
+ * handler bugs, which strict mode is genuinely good at.
  */
 function resolveValidationModes(config) {
     return {
         requests: config?.requests ?? 'warn',
-        responses: config?.responses ?? defaultResponseMode(),
+        responses: config?.responses ?? 'warn',
     };
 }
 function logWarning(debugLogs, taskName, outcome) {

package/dist/lib/validation/client-hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"client-hooks.js","sourceRoot":"","sources":["../../../src/lib/validation/client-hooks.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA+BH,wDAKC;AA8BD,0DAeC;AAWD,4DAaC;AAvGD,yDAA6G;AAC7G,mDAAuD;AAWvD,SAAS,mBAAmB;IAC1B,0EAA0E;IAC1E,wEAAwE;IACxE,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC;AACnE,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,sBAAsB,CAAC,MAA6B;IAClE,OAAO;QACL,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,MAAM;QACpC,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,mBAAmB,EAAE;KACtD,CAAC;AACJ,CAAC;AASD,SAAS,UAAU,CAAC,SAAsC,EAAE,QAAgB,EAAE,OAA0B;IACtG,IAAI,CAAC,SAAS;QAAE,OAAO;IACvB,SAAS,CAAC,IAAI,CAAC;QACb,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,iCAAiC,QAAQ,KAAK,IAAA,+BAAY,EAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QACrF,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,aAAa,EAAE,OAAO,CAAC,OAAO;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,uBAAuB,CACrC,QAAgB,EAChB,MAAe,EACf,IAAoB,EACpB,SAA2B,EAC3B,OAAgB;IAEhB,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,OAAO,GAAG,IAAA,kCAAe,EAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3D,IAAI,OAAO,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IAClC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,UAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACzC,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,IAAA,oCAAoB,EAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,wBAAwB,CACtC,QAAgB,EAChB,IAAa,EACb,IAAoB,EACpB,SAA2B,EAC3B,OAAgB;IAEhB,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IACxE,MAAM,OAAO,GAAG,IAAA,mCAAgB,EAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,UAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"client-hooks.js","sourceRoot":"","sources":["../../../src/lib/validation/client-hooks.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AA8BH,wDAKC;AA8BD,0DAeC;AAWD,4DAaC;AAtGD,yDAA6G;AAC7G,mDAAuD;AAWvD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,sBAAsB,CAAC,MAA6B;IAClE,OAAO;QACL,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,MAAM;QACpC,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,MAAM;KACvC,CAAC;AACJ,CAAC;AASD,SAAS,UAAU,CAAC,SAAsC,EAAE,QAAgB,EAAE,OAA0B;IACtG,IAAI,CAAC,SAAS;QAAE,OAAO;IACvB,SAAS,CAAC,IAAI,CAAC;QACb,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,iCAAiC,QAAQ,KAAK,IAAA,+BAAY,EAAC,OAAO,CAAC,MAAM,CAAC,EAAE;QACrF,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,aAAa,EAAE,OAAO,CAAC,OAAO;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,uBAAuB,CACrC,QAAgB,EAChB,MAAe,EACf,IAAoB,EACpB,SAA2B,EAC3B,OAAgB;IAEhB,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IACrC,MAAM,OAAO,GAAG,IAAA,kCAAe,EAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3D,IAAI,OAAO,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IAClC,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACpB,UAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;QACzC,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,MAAM,IAAA,oCAAoB,EAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,wBAAwB,CACtC,QAAgB,EAChB,IAAa,EACb,IAAoB,EACpB,SAA2B,EAC3B,OAAgB;IAEhB,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IACxE,MAAM,OAAO,GAAG,IAAA,mCAAgB,EAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1D,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,UAAU,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/lib/version.d.ts

@@ -1,7 +1,7 @@
 /**
  * AdCP SDK library version
  */
-export declare const LIBRARY_VERSION = "6.1.0";
+export declare const LIBRARY_VERSION = "6.2.0";
 /**
  * AdCP specification version this library is built for
  */
@@ -29,10 +29,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
  * Full version information
  */
 export declare const VERSION_INFO: {
-    readonly library: "6.1.0";
+    readonly library: "6.2.0";
     readonly adcp: "3.0.1";
     readonly compatibleVersions: readonly ["v2.5", "v2.6", "v3", "3.0.0-beta.1", "3.0.0-beta.3", "3.0.0", "3.0.1"];
-    readonly generatedAt: "2026-05-01T01:08:59.054Z";
+    readonly generatedAt: "2026-05-01T11:45:44.010Z";
 };
 /**
  * Get the AdCP specification version this library is built for

package/dist/lib/version.js

@@ -11,7 +11,7 @@ exports.parseAdcpMajorVersion = parseAdcpMajorVersion;
 /**
  * AdCP SDK library version
  */
-exports.LIBRARY_VERSION = '6.1.0';
+exports.LIBRARY_VERSION = '6.2.0';
 /**
  * AdCP specification version this library is built for
  */
@@ -38,10 +38,10 @@ exports.COMPATIBLE_ADCP_VERSIONS = [
  * Full version information
  */
 exports.VERSION_INFO = {
-    library: '6.1.0',
+    library: '6.2.0',
     adcp: '3.0.1',
     compatibleVersions: exports.COMPATIBLE_ADCP_VERSIONS,
-    generatedAt: '2026-05-01T01:08:59.054Z',
+    generatedAt: '2026-05-01T11:45:44.010Z',
 };
 /**
  * Get the AdCP specification version this library is built for

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

@@ -522,6 +522,8 @@ return adcpError('SERVICE_UNAVAILABLE', 'Try again in 30 seconds');
 return adcpError('ACCOUNT_SUSPENDED', 'Contact support');
 ```
 
+> **Heads-up for buyer-agent authors**: four codes are spec-`correctable` but operator-semantically human-escalate — don't auto-mutate-and-retry on `POLICY_VIOLATION`, `COMPLIANCE_UNSATISFIED`, `GOVERNANCE_DENIED`, or `AUTH_REQUIRED`. Surface to the user. (`AUTH_REQUIRED` conflates missing-creds with revoked-creds; until [adcontextprotocol/adcp#3730](https://github.com/adcontextprotocol/adcp/issues/3730) splits these, treat as escalate.) See `skills/call-adcp-agent/SKILL.md` for the full callout.
+
 See `docs/llms.txt` for the full error code table with recovery classifications.
 
 ### Storyboards

package/docs/llms.txt

@@ -1,7 +1,7 @@
 # Ad Context Protocol (AdCP)
 
-> Generated at: 2026-04-30
-> Library: @adcp/sdk v5.25.1
+> Generated at: 2026-05-01
+> Library: @adcp/sdk v6.1.0
 > AdCP major version: 3
 > Canonical URL: https://adcontextprotocol.github.io/adcp-client/llms.txt
 
@@ -1063,34 +1063,51 @@ Agents use the `recovery` classification to decide what to do: `transient` → r
 
 | Code | Recovery | Description |
 |------|----------|-------------|
-| `INVALID_REQUEST` | correctable | The request is malformed or contains invalid parameters |
-| `AUTH_REQUIRED` | correctable | Authentication is required or the provided credentials are invalid |
-| `RATE_LIMITED` | transient | Too many requests; retry after the specified delay |
-| `SERVICE_UNAVAILABLE` | transient | The service is temporarily unavailable |
-| `POLICY_VIOLATION` | correctable | The request violates a platform or advertiser policy |
-| `PRODUCT_NOT_FOUND` | correctable | The requested product does not exist |
-| `PRODUCT_UNAVAILABLE` | transient | The product exists but is not currently available |
-| `PROPOSAL_EXPIRED` | correctable | The proposal has expired and is no longer valid |
-| `BUDGET_TOO_LOW` | correctable | The specified budget is below the minimum threshold |
-| `CREATIVE_REJECTED` | correctable | One or more creatives failed review or validation |
-| `UNSUPPORTED_FEATURE` | terminal | The requested feature is not supported by this seller |
-| `AUDIENCE_TOO_SMALL` | correctable | The target audience is too small to deliver against |
-| `ACCOUNT_NOT_FOUND` | terminal | The specified account does not exist |
-| `ACCOUNT_SETUP_REQUIRED` | terminal | The account requires additional setup before use |
-| `ACCOUNT_AMBIGUOUS` | correctable | Multiple accounts match; provide a more specific identifier |
-| `ACCOUNT_PAYMENT_REQUIRED` | terminal | The account has an outstanding payment issue |
-| `ACCOUNT_SUSPENDED` | terminal | The account has been suspended |
-| `COMPLIANCE_UNSATISFIED` | correctable | Compliance requirements have not been met |
-| `BUDGET_EXHAUSTED` | terminal | The budget has been fully spent |
+| `INVALID_REQUEST` | correctable | Request is malformed, missing required fields, or violates schema constraints |
+| `AUTH_REQUIRED` | correctable | Authentication is required to access this resource |
+| `RATE_LIMITED` | transient | Request rate exceeded; retry after the retry_after interval |
+| `SERVICE_UNAVAILABLE` | transient | Seller service is temporarily unavailable |
+| `POLICY_VIOLATION` | correctable | Request violates the seller's content or advertising policies |
+| `PRODUCT_NOT_FOUND` | correctable | One or more referenced product IDs are unknown or expired |
+| `PRODUCT_UNAVAILABLE` | correctable | The requested product is sold out or no longer available |
+| `PROPOSAL_EXPIRED` | correctable | A referenced proposal ID has passed its expires_at timestamp |
+| `BUDGET_TOO_LOW` | correctable | Budget is below the seller's minimum |
+| `CREATIVE_REJECTED` | correctable | Creative failed content policy review |
+| `UNSUPPORTED_FEATURE` | correctable | A requested feature or field is not supported by this seller |
+| `AUDIENCE_TOO_SMALL` | correctable | Audience segment is below the minimum required size for targeting |
+| `ACCOUNT_NOT_FOUND` | terminal | The account reference could not be resolved |
+| `ACCOUNT_SETUP_REQUIRED` | correctable | Natural key resolved but the account needs setup before use |
+| `ACCOUNT_AMBIGUOUS` | correctable | Natural key resolves to multiple accounts |
+| `ACCOUNT_PAYMENT_REQUIRED` | terminal | Account has an outstanding balance requiring payment before new buys |
+| `ACCOUNT_SUSPENDED` | terminal | Account has been suspended |
+| `COMPLIANCE_UNSATISFIED` | correctable | A required disclosure from the brief's compliance section cannot be satisfied by the target format |
+| `GOVERNANCE_DENIED` | correctable | A registered governance agent denied the transaction |
+| `BUDGET_EXHAUSTED` | terminal | Account or campaign budget has been fully spent |
 | `BUDGET_EXCEEDED` | correctable | Operation would exceed the allocated budget for the media buy or package |
-| `CONFLICT` | correctable | The request conflicts with the current state of the resource |
+| `CONFLICT` | transient | Concurrent modification detected; the resource was modified between read and write |
 | `IDEMPOTENCY_CONFLICT` | correctable | An earlier request with the same idempotency_key was processed with a different canonical payload. Use a fresh UUID v4 for the new request, or resend the exact original payload to get the cached response. |
 | `IDEMPOTENCY_EXPIRED` | correctable | The idempotency_key is past the seller's replay window. If the prior call succeeded, look up the resource by natural key before retrying; otherwise mint a fresh UUID v4. |
+| `CREATIVE_DEADLINE_EXCEEDED` | correctable | Creative change submitted after the package's creative_deadline |
 | `INVALID_STATE` | correctable | Operation is not permitted for the resource's current status |
 | `MEDIA_BUY_NOT_FOUND` | correctable | Referenced media buy does not exist or is not accessible |
 | `NOT_CANCELLABLE` | correctable | The media buy or package cannot be canceled in its current state |
 | `PACKAGE_NOT_FOUND` | correctable | Referenced package does not exist within the specified media buy |
+| `CREATIVE_NOT_FOUND` | correctable | Referenced creative does not exist in the agent's creative library |
+| `SIGNAL_NOT_FOUND` | correctable | Referenced signal does not exist in the agent's catalog |
+| `SESSION_NOT_FOUND` | correctable | SI session ID is invalid, expired, or does not exist |
+| `PLAN_NOT_FOUND` | correctable | Referenced governance plan does not exist or is not accessible |
+| `REFERENCE_NOT_FOUND` | correctable | Generic fallback for a referenced identifier, grant, session, or other resource that does not exist or is not accessible by the caller |
+| `SESSION_TERMINATED` | correctable | SI session has already been terminated and cannot accept further messages |
 | `VALIDATION_ERROR` | correctable | Request contains invalid field values or violates business rules beyond schema validation |
+| `PRODUCT_EXPIRED` | correctable | One or more referenced products have passed their expires_at timestamp |
+| `PROPOSAL_NOT_COMMITTED` | correctable | The referenced proposal has proposal_status 'draft' and cannot be used to create a media buy |
+| `IO_REQUIRED` | correctable | The committed proposal requires a signed insertion order but no io_acceptance was provided |
+| `TERMS_REJECTED` | correctable | Buyer-proposed measurement_terms were rejected by the seller |
+| `REQUOTE_REQUIRED` | correctable | An update_media_buy request changes the parameter envelope (budget, flight dates, volume, targeting) the original quote was priced against |
+| `VERSION_UNSUPPORTED` | correctable | The declared adcp_major_version is not supported by this seller |
+| `CAMPAIGN_SUSPENDED` | transient | Campaign governance has been suspended pending human review |
+| `GOVERNANCE_UNAVAILABLE` | transient | A registered governance agent is unreachable and the seller cannot obtain a governance decision |
+| `PERMISSION_DENIED` | correctable | The authenticated caller is not authorized for the requested action under the seller's policies, or a required signed credential is missing or invalid |
 
 Unknown codes: fall back to the HTTP status code (4xx = correctable, 5xx = transient).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adcp/sdk",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "AdCP SDK — client, server, and compliance harnesses for the AdContext Protocol (MCP + A2A)",
   "workspaces": [
     ".",
@@ -35,6 +35,11 @@
       "require": "./dist/lib/types/index.js",
       "types": "./dist/lib/types/index.d.ts"
     },
+    "./types/v2-5": {
+      "import": "./dist/lib/types/v2-5/index.js",
+      "require": "./dist/lib/types/v2-5/index.js",
+      "types": "./dist/lib/types/v2-5/index.d.ts"
+    },
     "./testing": {
       "import": "./dist/lib/testing/index.js",
       "require": "./dist/lib/testing/index.js",
@@ -121,6 +126,9 @@
       "types": [
         "dist/lib/types/index.d.ts"
       ],
+      "types/v2-5": [
+        "dist/lib/types/v2-5/index.d.ts"
+      ],
       "testing": [
         "dist/lib/testing/index.d.ts"
       ],
@@ -200,6 +208,8 @@
     "sync-schemas:all": "npm run sync-schemas && npm run sync-schemas:v2.5",
     "schema-diff": "tsx scripts/schema-diff.ts",
     "generate-types": "tsx scripts/generate-types.ts && tsx scripts/generate-enum-arrays.ts",
+    "generate-types:v2.5": "tsx scripts/generate-v2-5-types.ts",
+    "generate-types:all": "npm run generate-types && npm run generate-types:v2.5",
     "generate-registry-types": "tsx scripts/generate-registry-types.ts",
     "generate-enum-arrays": "tsx scripts/generate-enum-arrays.ts",
     "generate-inline-enum-arrays": "tsx scripts/generate-inline-enum-arrays.ts",

package/skills/build-seller-agent/SKILL.md

@@ -41,6 +41,11 @@ Every sales-_ specialism (including `sales-social`, `sales-broadcast-tv`, `sales
 | `list_creatives`         | Read the creative library back with pagination                                     | `sales.listCreatives`    |
 | `get_media_buy_delivery` | Delivery + spend reporting with `reporting_period`, per-package billing rows       | `sales.getMediaBuyDelivery` |
 
+> **`sales-guaranteed` minimum tool surface** — register ALL of these or storyboard scenarios will cascade-skip with `skip_reason: missing_tool`:
+> `get_adcp_capabilities`, `sync_accounts`, `list_accounts`, `get_products`, `list_creative_formats`, `create_media_buy`, `update_media_buy`, `get_media_buys`, `sync_creatives`, `get_media_buy_delivery`
+>
+> (`list_creatives` is optional — only required if the seller hosts its own creative library; creative-agent delegates omit it)
+
 **Minimum platform skeleton** — every sales-\* seller starts here, then adds specialism-specific behavior on top:
 
 ```ts
@@ -522,7 +527,17 @@ productsResponse({
 
 **`create_media_buy`** — `CreateMediaBuyRequestSchema.shape`
 
-Validate the request before creating the buy. Return an error response (not `adcpError`) when business validation fails:
+Return `adcpError(...)` for all business validation failures. Error-code matrix — all spec-defined rejections on `create_media_buy` / `update_media_buy`:
+
+| Tool | Condition | Code |
+| --- | --- | --- |
+| `create_media_buy` | `performance_standards` or `measurement_terms` on a package are unacceptable | `adcpError('TERMS_REJECTED', { message: '...' })` |
+| `create_media_buy` | `product_id` on a package not in catalog | `adcpError('PRODUCT_NOT_FOUND', { field: 'packages[N].product_id' })` |
+| `create_media_buy` | product exists but inventory sold out / unavailable for the requested flight | `adcpError('PRODUCT_UNAVAILABLE', { field: 'packages[N].product_id' })` |
+| `create_media_buy` | budget below the product's floor price | `adcpError('BUDGET_TOO_LOW', { message: '...' })` |
+| `create_media_buy` | reversed dates, schema violation | `adcpError('INVALID_REQUEST', { message: '...' })` |
+| `update_media_buy` | `media_buy_id` not found | `adcpError('MEDIA_BUY_NOT_FOUND', { field: 'media_buy_id' })` |
+| `update_media_buy` | `package_id` within a valid buy not found | `adcpError('PACKAGE_NOT_FOUND', { field: 'package_id' })` |
 
 ```
 // Success — revision, confirmed_at, and valid_actions are auto-set:
@@ -900,7 +915,7 @@ import {
   type SalesPlatform,
   type AccountStore,
 } from '@adcp/sdk/server';
-import type { ServeContext } from '@adcp/sdk';
+import type { ServeContext, MediaBuyStatus } from '@adcp/sdk';
 
 // Publisher-typed metadata blob round-tripped via Account.ctx_metadata.
 // Whatever shape your adapter wants — the SDK doesn't inspect it.
@@ -1032,11 +1047,28 @@ class MySeller implements DecisioningPlatform<{}, MySellerMeta> {
       // wholesale. The patch carries envelope fields (idempotency_key,
       // context) that have no business in your domain state. Spreading
       // them pollutes `get_media_buys` responses and breaks dedup.
-      const updated = { ...existing, status: patch.paused === true ? 'paused' : 'active' };
+
+      // State machine: creative_assignments arriving advances pending_creatives.
+      // pending_creatives → pending_start (start_time in future) or active (start_time now/past).
+      let status = existing.status as MediaBuyStatus;
+      if (patch.paused === true) {
+        status = 'paused';
+      } else if (
+        status === 'pending_creatives' &&
+        (patch.packages ?? []).some((p: { creative_assignments?: unknown[] }) =>
+          (p.creative_assignments ?? []).length > 0)
+      ) {
+        const startTime = existing.start_time ? new Date(existing.start_time as string) : null;
+        status = startTime && startTime > new Date() ? 'pending_start' : 'active';
+      } else if (patch.paused === false && status === 'paused') {
+        status = 'active';
+      }
+
+      const updated = { ...existing, status };
       await ctx.store.put('media_buys', mediaBuyId, updated);
       return {
         media_buy_id: mediaBuyId,
-        status: updated.status as 'paused' | 'active',
+        status: updated.status as MediaBuyStatus,
         // `affected_packages` is `Package[]` (per `/schemas/latest/core/package.json`)
         // — objects with at minimum `package_id`. Don't return bare strings;
         // the update-media-buy-response oneOf discriminates against them and
@@ -1103,8 +1135,9 @@ Key points:
 3. Response builders are auto-applied — just return the data
 4. Use `ctx.store` for state — persists across stateless HTTP requests
 5. Set `sandbox: true` on all mock/demo responses
-6. Use `adcpError()` for business validation failures
+6. Use `adcpError()` for business validation failures — see the error-code matrix in § create_media_buy above
 7. Use `as const` on string literal arrays and union-typed fields in product definitions — TypeScript infers `string[]` from `['display', 'olv']` but the SDK requires specific union types like `MediaChannel[]`. Apply `as const` to `channels`, `delivery_type`, `selection_type`, and `pricing_model` values.
+8. `pending_creatives` is a transient state — `update_media_buy` MUST advance it to `pending_start` or `active` when `creative_assignments` arrive (see state-machine logic in § update_media_buy above)
 
 ## Governance
 

package/skills/build-seller-agent/specialisms/sales-guaranteed.md

@@ -30,8 +30,7 @@ createMediaBuy: async (params, ctx) => {
     product_id: pkg.product_id,
     pricing_option_id: pkg.pricing_option_id,
     budget: pkg.budget,
-    property_list: pkg.property_list,     // persist inventory-list refs verbatim
-    collection_list: pkg.collection_list,
+    targeting_overlay: pkg.targeting_overlay, // persists property_list / collection_list verbatim
     creative_assignments: pkg.creative_assignments ?? [],
   }));
   const buy = {
@@ -45,7 +44,9 @@ createMediaBuy: async (params, ctx) => {
 },
 ```
 
-**`get_media_buys` must echo `packages[].property_list` / `collection_list`.** The `inventory_list_targeting` baseline scenarios call `create_media_buy` with list references, then call `get_media_buys` expecting those same `list_id` values to appear at `media_buys[].packages[].property_list.list_id` / `.collection_list.list_id`. Persist verbatim, echo verbatim. `update_media_buy` should merge new list refs without dropping prior ones.
+**`get_media_buys` must echo `packages[].targeting_overlay.property_list` / `.collection_list`.** Per the AdCP types, `property_list` and `collection_list` live inside `TargetingOverlay`, not directly on `Package` (see `/schemas/latest/core/package.json` and `/schemas/latest/core/targeting.json`). The `inventory_list_targeting` baseline scenarios send list refs at `packages[].targeting_overlay.{property_list,collection_list}`; `get_media_buys` must echo them back at the same nested path. Persist the full `targeting_overlay` verbatim; echo verbatim. `update_media_buy` should merge new targeting overlays without dropping prior refs.
+
+**State transition: `pending_creatives → pending_start / active`.** When `update_media_buy` attaches `creative_assignments` to a buy in `pending_creatives` status, the buy MUST advance: `pending_start` if `start_time` is in the future, `active` if `start_time` is now or past. See the `updateMediaBuy` state-machine logic in `../SKILL.md` § update_media_buy.
 
 **Task envelope — when IO signing is required.** Use `registerAdcpTaskTool` from `@adcp/sdk/server` so `tasks/get` returns the completion artifact:
 

package/skills/call-adcp-agent.previous/SKILL.md

@@ -233,14 +233,93 @@ Quick lookup before reading the full envelope. Match what you see in `adcp_error
 | `keyword: 'enum'` at `/destinations/*/type` | Made-up destination type | Use `'platform'` (with `platform`) or `'agent'` (with `agent_url`). |
 | Response carries `status: 'submitted'` and `task_id` | Async — work is queued, NOT done | Poll via `tasks/get` (A2A) or the MCP async task extension using `task_id`. |
 | `recovery: 'transient'` (rate limit, 5xx, timeout) | Server-side, retry-safe | Retry with the **same** `idempotency_key`. |
-<<<<<<< Updated upstream
 | `406 Not Acceptable` before any AdCP framing | Hand-rolled HTTP without `Accept: text/event-stream` (MCP transport) | Use `@modelcontextprotocol/sdk` client; it sets the right Accept header. |
-=======
->>>>>>> Stashed changes
-| `recovery: 'correctable'` | Buyer-side fix | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt. |
+| `recovery: 'correctable'` | Buyer-side fix | Read `issues[]`, patch the pointers, resend. Most cases close in one attempt. (See exceptions below — four codes are technically `correctable` but operator-semantically human-escalate.) |
 | `recovery: 'terminal'` (account suspended, payment required, …) | Requires human action | Don't retry. Surface to the user. |
 | HTTP 401 with `WWW-Authenticate` header | Missing or expired credential | Add `Authorization` per the agent's auth spec; re-auth if applicable. |
 
+> **⚠️ Four codes are technically `correctable` but operator-semantically human-escalate. Don't auto-tweak.**
+>
+> - **`POLICY_VIOLATION`** — buyer's content/targeting violates seller policy. Auto-mutating creative or targeting and resubmitting **looks like evasion** to the seller's governance reviewer. Surface to a human.
+> - **`COMPLIANCE_UNSATISFIED`** — required disclosure can't be satisfied by the chosen format. Auto-relaxing the compliance section IS the compliance failure. Surface to a human.
+> - **`GOVERNANCE_DENIED`** — registered governance agent rejected the spend. Auto-shrinking budget and retrying looks like governance evasion. Surface to the plan operator.
+> - **`AUTH_REQUIRED`** — conflates missing creds (genuinely correctable) with revoked / expired creds (operator must rotate). Until [adcontextprotocol/adcp#3730](https://github.com/adcontextprotocol/adcp/issues/3730) splits this into `auth_missing` + `auth_invalid`, treat as escalate-after-one-attempt.
+>
+> Spec recovery on these is `correctable`; operator behavior is human-in-loop. The pattern: read `error.message` + `error.suggestion`, surface to the user, **don't loop**.
+
+### Operationalize the recovery rules — `decideRetry`
+
+`@adcp/sdk` exports `decideRetry(error, ctx?)` which encodes the operator-grade defaults from the table above plus this section. It returns a discriminated `RetryDecision` so the type system enforces the same-vs-fresh `idempotency_key` rule:
+
+```typescript
+import { decideRetry } from '@adcp/sdk';
+import { randomUUID } from 'node:crypto';
+
+async function callWithRetry(toolName: string, params: Record<string, unknown>): Promise<unknown> {
+  let attempt = 1;
+  let idempotencyKey = randomUUID();
+
+  while (true) {
+    try {
+      return await agent.call(toolName, { ...params, idempotency_key: idempotencyKey });
+    } catch (e) {
+      const error = extractAdcpError(e); // your SDK's error extractor
+      if (!error) throw e; // not an AdCP-shaped failure — let it bubble
+
+      const decision = decideRetry(error, { attempt });
+
+      if (decision.action === 'retry') {
+        // Server-side transient (RATE_LIMITED, SERVICE_UNAVAILABLE, CONFLICT).
+        // Replay with the SAME idempotency_key after the suggested delay.
+        await sleep(decision.delayMs);
+        attempt++;
+        continue;
+      }
+
+      if (decision.action === 'mutate-and-retry') {
+        // Buyer-fixable. Apply the seller's correction (decision.field /
+        // decision.suggestion) and mint a FRESH idempotency_key — payload
+        // changed, so the seller's replay-window must NOT dedupe.
+        params = applyCorrection(params, error, decision); // your domain logic
+        idempotencyKey = randomUUID();
+        await sleep(decision.delayMs); // small jitter (~125-250ms by default)
+        attempt++;
+        continue;
+      }
+
+      // 'escalate' — stop the loop and surface to a human. Includes
+      // commercial-relationship signals (POLICY_VIOLATION etc.), auth
+      // failures, IDEMPOTENCY_EXPIRED (do a natural-key check first!),
+      // attempt-cap exhaustion, and unknown vendor codes.
+      throw new EscalationRequired(decision.reason, decision.message);
+    }
+  }
+}
+```
+
+The discriminated union means TypeScript narrows correctly in each branch — `decision.delayMs` is only available on retry/mutate-and-retry, `decision.field` only on mutate-and-retry, `decision.message` only on escalate.
+
+For per-vertical overrides (e.g., a creative-template platform that legitimately auto-fixes `CREATIVE_REJECTED` format mismatches), instantiate `BuyerRetryPolicy` directly:
+
+```typescript
+import { BuyerRetryPolicy } from '@adcp/sdk';
+
+const policy = new BuyerRetryPolicy({
+  overrides: {
+    CREATIVE_REJECTED: (error) => {
+      if (error.field === 'creative.format' && /unsupported_format/.test(error.message)) {
+        return { action: 'mutate-and-retry', delayMs: 0, attemptCap: 2, sameIdempotencyKey: false, reason: 'capability' };
+      }
+      return null; // fall through to default (escalate as commercial)
+    },
+  },
+});
+
+const decision = policy.decide(error, { attempt });
+```
+
+Default policy is intentionally conservative — see the source comments in `src/lib/utils/buyer-retry-policy.ts` for per-code reasoning.
+
 If your symptom isn't here, fall through to the next section.
 
 ## If you get stuck