@adcp/sdk 5.23.0

package/dist/lib/utils/a2a-discovery.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * A2A Agent Card Discovery Utilities
+ *
+ * Supports both /.well-known/agent.json (current A2A spec)
+ * and /.well-known/agent-card.json (legacy) for agent card discovery.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRANSPORT_SUFFIX_REGEX = exports.A2A_CARD_PATHS = void 0;
+exports.stripTransportSuffix = stripTransportSuffix;
+exports.isAgentCardPath = isAgentCardPath;
+exports.isWellKnownAgentCardUrl = isWellKnownAgentCardUrl;
+exports.buildCardUrls = buildCardUrls;
+exports.stripAgentCardPath = stripAgentCardPath;
+/** A2A agent card well-known paths, preferred first */
+exports.A2A_CARD_PATHS = ['/.well-known/agent.json', '/.well-known/agent-card.json'];
+/** Matches either well-known agent card path at end of string (case-insensitive) */
+const AGENT_CARD_PATH_REGEX = /\/\.well-known\/agent(-card)?\.json$/i;
+/**
+ * AdCP protocol transport suffixes that the runner appends to reach a
+ * protocol endpoint. Kept here as the single source of truth — both
+ * `SingleAgentClient.computeBaseUrl` and the storyboard scope canonicalizer
+ * import this so new transports (e.g., future websocket) only need to be
+ * added in one place.
+ */
+exports.TRANSPORT_SUFFIX_REGEX = /\/(?:mcp|a2a|sse)\/?$/i;
+/** Strip a protocol transport suffix (`/mcp`, `/a2a`, `/sse`) from a URL path. */
+function stripTransportSuffix(url) {
+    return url.replace(exports.TRANSPORT_SUFFIX_REGEX, '');
+}
+/** Matches a root-level well-known agent card URL (scheme://host/.well-known/agent[-card].json) */
+const AGENT_CARD_URL_REGEX = /^https?:\/\/[^/]+\/\.well-known\/agent(-card)?\.json$/i;
+/**
+ * Check if a URL string ends with an agent card well-known path
+ */
+function isAgentCardPath(url) {
+    return AGENT_CARD_PATH_REGEX.test(url);
+}
+/**
+ * Check if a URL is a root-level well-known agent card URL.
+ *
+ * Matches: https://example.com/.well-known/agent.json
+ * Matches: https://example.com/.well-known/agent-card.json
+ * Rejects: https://example.com/api/.well-known/agent.json
+ */
+function isWellKnownAgentCardUrl(url) {
+    return AGENT_CARD_URL_REGEX.test(url);
+}
+/**
+ * Build the list of agent card URLs to try for a given agent URL.
+ *
+ * If the URL already points to a well-known agent card path, returns it as-is.
+ * Otherwise returns both paths (preferred first) appended to the base URL.
+ */
+function buildCardUrls(agentUrl) {
+    if (isAgentCardPath(agentUrl)) {
+        return [agentUrl];
+    }
+    const base = agentUrl.replace(/\/$/, '');
+    return exports.A2A_CARD_PATHS.map(path => `${base}${path}`);
+}
+/**
+ * Strip a well-known agent card path from a URL, returning the base URL.
+ */
+function stripAgentCardPath(url) {
+    return url.replace(AGENT_CARD_PATH_REGEX, '');
+}
+//# sourceMappingURL=a2a-discovery.js.map

package/dist/lib/utils/a2a-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"a2a-discovery.js","sourceRoot":"","sources":["../../../src/lib/utils/a2a-discovery.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAkBH,oDAEC;AAQD,0CAEC;AASD,0DAEC;AAQD,sCAMC;AAKD,gDAEC;AA5DD,uDAAuD;AAC1C,QAAA,cAAc,GAAG,CAAC,yBAAyB,EAAE,8BAA8B,CAAU,CAAC;AAEnG,oFAAoF;AACpF,MAAM,qBAAqB,GAAG,uCAAuC,CAAC;AAEtE;;;;;;GAMG;AACU,QAAA,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,kFAAkF;AAClF,SAAgB,oBAAoB,CAAC,GAAW;IAC9C,OAAO,GAAG,CAAC,OAAO,CAAC,8BAAsB,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,mGAAmG;AACnG,MAAM,oBAAoB,GAAG,wDAAwD,CAAC;AAEtF;;GAEG;AACH,SAAgB,eAAe,CAAC,GAAW;IACzC,OAAO,qBAAqB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,uBAAuB,CAAC,GAAW;IACjD,OAAO,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,QAAgB;IAC5C,IAAI,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpB,CAAC;IACD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,sBAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;AACtD,CAAC;AAED;;GAEG;AACH,SAAgB,kBAAkB,CAAC,GAAW;IAC5C,OAAO,GAAG,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC"}

package/dist/lib/utils/adcp-version-config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolve and validate a configured `adcpVersion`. Returns the value to store
+ * on the instance — either the caller's pin or the SDK default.
+ *
+ * Throws `ConfigurationError` when the pin is unparseable or its derived major
+ * differs from `ADCP_MAJOR_VERSION`. The error message points at the Stage 3+
+ * roadmap so callers know cross-major support isn't a missing feature, just
+ * not landed yet.
+ */
+export declare function resolveAdcpVersion(adcpVersion: string | undefined): string;
+//# sourceMappingURL=adcp-version-config.d.ts.map

package/dist/lib/utils/adcp-version-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adcp-version-config.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/adcp-version-config.ts"],"names":[],"mappings":"AAeA;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAyB1E"}

package/dist/lib/utils/adcp-version-config.js

@@ -0,0 +1,44 @@
+"use strict";
+// Validation helpers for the per-instance `adcpVersion` constructor option
+// added in Stage 2 of the multi-version refactor.
+//
+// Stage 2 plumbs the option onto every client/server constructor and exposes
+// `getAdcpVersion()` for inspection, but the wire-level `adcp_major_version`
+// field is still emitted from the global `ADCP_MAJOR_VERSION` constant.
+// To prevent silent drift between the configured pin and what actually goes
+// out on the wire, we fence the constructor: only `adcpVersion` strings whose
+// derived major matches `ADCP_MAJOR_VERSION` are accepted today. Cross-major
+// pinning (e.g. `'4.0.0-beta.1'` while the SDK ships against major 3) waits
+// until Stage 3 wires the per-instance major into the protocol layer.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAdcpVersion = resolveAdcpVersion;
+const version_1 = require("../version");
+const errors_1 = require("../errors");
+/**
+ * Resolve and validate a configured `adcpVersion`. Returns the value to store
+ * on the instance — either the caller's pin or the SDK default.
+ *
+ * Throws `ConfigurationError` when the pin is unparseable or its derived major
+ * differs from `ADCP_MAJOR_VERSION`. The error message points at the Stage 3+
+ * roadmap so callers know cross-major support isn't a missing feature, just
+ * not landed yet.
+ */
+function resolveAdcpVersion(adcpVersion) {
+    if (adcpVersion === undefined)
+        return version_1.ADCP_VERSION;
+    const major = (0, version_1.parseAdcpMajorVersion)(adcpVersion);
+    if (!Number.isFinite(major)) {
+        throw new errors_1.ConfigurationError(`adcpVersion ${JSON.stringify(adcpVersion)} is not a valid AdCP version. ` +
+            `Expected a semver string (e.g. '3.0.1', '3.1.0-beta.1') or a legacy alias. ` +
+            `Currently accepted: ${version_1.COMPATIBLE_ADCP_VERSIONS.filter(v => (0, version_1.parseAdcpMajorVersion)(v) === version_1.ADCP_MAJOR_VERSION).join(', ')}.`, 'adcpVersion');
+    }
+    if (major !== version_1.ADCP_MAJOR_VERSION) {
+        throw new errors_1.ConfigurationError(`adcpVersion ${JSON.stringify(adcpVersion)} pins major ${major}, but this ` +
+            `SDK build ships against major ${version_1.ADCP_MAJOR_VERSION}. Cross-major pinning ` +
+            `lands in Stage 3 of the multi-version refactor (per-instance schema + ` +
+            `wire-major plumbing). Within a major, beta and patch pins are accepted: ` +
+            `${version_1.COMPATIBLE_ADCP_VERSIONS.filter(v => (0, version_1.parseAdcpMajorVersion)(v) === version_1.ADCP_MAJOR_VERSION).join(', ')}.`, 'adcpVersion');
+    }
+    return adcpVersion;
+}
+//# sourceMappingURL=adcp-version-config.js.map

package/dist/lib/utils/adcp-version-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adcp-version-config.js","sourceRoot":"","sources":["../../../src/lib/utils/adcp-version-config.ts"],"names":[],"mappings":";AAAA,2EAA2E;AAC3E,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,wEAAwE;AACxE,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,4EAA4E;AAC5E,sEAAsE;;AActE,gDAyBC;AArCD,wCAA+G;AAC/G,sCAA+C;AAE/C;;;;;;;;GAQG;AACH,SAAgB,kBAAkB,CAAC,WAA+B;IAChE,IAAI,WAAW,KAAK,SAAS;QAAE,OAAO,sBAAY,CAAC;IAEnD,MAAM,KAAK,GAAG,IAAA,+BAAqB,EAAC,WAAW,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,2BAAkB,CAC1B,eAAe,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,gCAAgC;YACxE,6EAA6E;YAC7E,uBAAuB,kCAAwB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAA,+BAAqB,EAAC,CAAC,CAAC,KAAK,4BAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAC5H,aAAa,CACd,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,KAAK,4BAAkB,EAAE,CAAC;QACjC,MAAM,IAAI,2BAAkB,CAC1B,eAAe,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,eAAe,KAAK,aAAa;YACzE,iCAAiC,4BAAkB,wBAAwB;YAC3E,wEAAwE;YACxE,0EAA0E;YAC1E,GAAG,kCAAwB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,IAAA,+BAAqB,EAAC,CAAC,CAAC,KAAK,4BAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EACxG,aAAa,CACd,CAAC;IACJ,CAAC;IAED,OAAO,WAAW,CAAC;AACrB,CAAC"}

package/dist/lib/utils/asset-builders.d.ts

@@ -0,0 +1,44 @@
+import type { AudioAsset, CSSAsset, HTMLAsset, ImageAsset, JavaScriptAsset, MarkdownAsset, TextAsset, URLAsset, VideoAsset, WebhookAsset } from '../types/tools.generated';
+type Tagged<T, Tag extends string> = Omit<T, 'asset_type'> & {
+    asset_type: Tag;
+};
+/** Build an `ImageAsset` with `asset_type: 'image'` injected. */
+export declare function imageAsset(fields: Omit<ImageAsset, 'asset_type'>): Tagged<ImageAsset, 'image'>;
+/** Build a `VideoAsset` with `asset_type: 'video'` injected. */
+export declare function videoAsset(fields: Omit<VideoAsset, 'asset_type'>): Tagged<VideoAsset, 'video'>;
+/** Build an `AudioAsset` with `asset_type: 'audio'` injected. */
+export declare function audioAsset(fields: Omit<AudioAsset, 'asset_type'>): Tagged<AudioAsset, 'audio'>;
+/** Build a `TextAsset` with `asset_type: 'text'` injected. */
+export declare function textAsset(fields: Omit<TextAsset, 'asset_type'>): Tagged<TextAsset, 'text'>;
+/** Build a `URLAsset` with `asset_type: 'url'` injected. */
+export declare function urlAsset(fields: Omit<URLAsset, 'asset_type'>): Tagged<URLAsset, 'url'>;
+/** Build an `HTMLAsset` with `asset_type: 'html'` injected. */
+export declare function htmlAsset(fields: Omit<HTMLAsset, 'asset_type'>): Tagged<HTMLAsset, 'html'>;
+/** Build a `JavaScriptAsset` with `asset_type: 'javascript'` injected. */
+export declare function javascriptAsset(fields: Omit<JavaScriptAsset, 'asset_type'>): Tagged<JavaScriptAsset, 'javascript'>;
+/** Build a `CSSAsset` with `asset_type: 'css'` injected. */
+export declare function cssAsset(fields: Omit<CSSAsset, 'asset_type'>): Tagged<CSSAsset, 'css'>;
+/** Build a `MarkdownAsset` with `asset_type: 'markdown'` injected. */
+export declare function markdownAsset(fields: Omit<MarkdownAsset, 'asset_type'>): Tagged<MarkdownAsset, 'markdown'>;
+/** Build a `WebhookAsset` with `asset_type: 'webhook'` injected. */
+export declare function webhookAsset(fields: Omit<WebhookAsset, 'asset_type'>): Tagged<WebhookAsset, 'webhook'>;
+/**
+ * Grouped accessor for every creative-asset builder. `Asset.image({...})`
+ * reads better in assets-by-role manifests and gives one-dot autocomplete
+ * over the whole family. The individual named exports remain the primary
+ * entry points.
+ */
+export declare const Asset: {
+    readonly image: typeof imageAsset;
+    readonly video: typeof videoAsset;
+    readonly audio: typeof audioAsset;
+    readonly text: typeof textAsset;
+    readonly url: typeof urlAsset;
+    readonly html: typeof htmlAsset;
+    readonly javascript: typeof javascriptAsset;
+    readonly css: typeof cssAsset;
+    readonly markdown: typeof markdownAsset;
+    readonly webhook: typeof webhookAsset;
+};
+export {};
+//# sourceMappingURL=asset-builders.d.ts.map

package/dist/lib/utils/asset-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-builders.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/asset-builders.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,UAAU,EACV,QAAQ,EACR,SAAS,EACT,UAAU,EACV,eAAe,EACf,aAAa,EACb,SAAS,EACT,QAAQ,EACR,UAAU,EACV,YAAY,EACb,MAAM,0BAA0B,CAAC;AAKlC,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,SAAS,MAAM,IAAI,IAAI,CAAC,CAAC,EAAE,YAAY,CAAC,GAAG;IAAE,UAAU,EAAE,GAAG,CAAA;CAAE,CAAC;AAMjF,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAE9F;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAE9F;AAED,iEAAiE;AACjE,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAE9F;AAED,8DAA8D;AAC9D,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAE1F;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAEtF;AAED,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAE1F;AAED,0EAA0E;AAC1E,wBAAgB,eAAe,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,eAAe,EAAE,YAAY,CAAC,CAElH;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAEtF;AAED,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,aAAa,EAAE,UAAU,CAAC,CAE1G;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,GAAG,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,CAEtG;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;CAWR,CAAC"}

package/dist/lib/utils/asset-builders.js

@@ -0,0 +1,84 @@
+"use strict";
+// Typed factory helpers for creative asset objects.
+//
+// Every asset interface in the schema carries an `asset_type` literal
+// discriminator (e.g. `asset_type: 'image'`) that's always the canonical
+// tag for its class. Requiring callers to type it by hand is boilerplate
+// that the compiler already knows the answer to. These builders take the
+// rest of the asset shape and inject the discriminator, so
+// `imageAsset({ url, width, height })` produces a valid `ImageAsset`
+// without repeating `asset_type: 'image'` at every call site.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Asset = void 0;
+exports.imageAsset = imageAsset;
+exports.videoAsset = videoAsset;
+exports.audioAsset = audioAsset;
+exports.textAsset = textAsset;
+exports.urlAsset = urlAsset;
+exports.htmlAsset = htmlAsset;
+exports.javascriptAsset = javascriptAsset;
+exports.cssAsset = cssAsset;
+exports.markdownAsset = markdownAsset;
+exports.webhookAsset = webhookAsset;
+// Spread order matters: the discriminator is written last so a runtime
+// bypass (e.g. an `as unknown` cast that slips `asset_type` into `fields`)
+// can't clobber it.
+/** Build an `ImageAsset` with `asset_type: 'image'` injected. */
+function imageAsset(fields) {
+    return { ...fields, asset_type: 'image' };
+}
+/** Build a `VideoAsset` with `asset_type: 'video'` injected. */
+function videoAsset(fields) {
+    return { ...fields, asset_type: 'video' };
+}
+/** Build an `AudioAsset` with `asset_type: 'audio'` injected. */
+function audioAsset(fields) {
+    return { ...fields, asset_type: 'audio' };
+}
+/** Build a `TextAsset` with `asset_type: 'text'` injected. */
+function textAsset(fields) {
+    return { ...fields, asset_type: 'text' };
+}
+/** Build a `URLAsset` with `asset_type: 'url'` injected. */
+function urlAsset(fields) {
+    return { ...fields, asset_type: 'url' };
+}
+/** Build an `HTMLAsset` with `asset_type: 'html'` injected. */
+function htmlAsset(fields) {
+    return { ...fields, asset_type: 'html' };
+}
+/** Build a `JavaScriptAsset` with `asset_type: 'javascript'` injected. */
+function javascriptAsset(fields) {
+    return { ...fields, asset_type: 'javascript' };
+}
+/** Build a `CSSAsset` with `asset_type: 'css'` injected. */
+function cssAsset(fields) {
+    return { ...fields, asset_type: 'css' };
+}
+/** Build a `MarkdownAsset` with `asset_type: 'markdown'` injected. */
+function markdownAsset(fields) {
+    return { ...fields, asset_type: 'markdown' };
+}
+/** Build a `WebhookAsset` with `asset_type: 'webhook'` injected. */
+function webhookAsset(fields) {
+    return { ...fields, asset_type: 'webhook' };
+}
+/**
+ * Grouped accessor for every creative-asset builder. `Asset.image({...})`
+ * reads better in assets-by-role manifests and gives one-dot autocomplete
+ * over the whole family. The individual named exports remain the primary
+ * entry points.
+ */
+exports.Asset = {
+    image: imageAsset,
+    video: videoAsset,
+    audio: audioAsset,
+    text: textAsset,
+    url: urlAsset,
+    html: htmlAsset,
+    javascript: javascriptAsset,
+    css: cssAsset,
+    markdown: markdownAsset,
+    webhook: webhookAsset,
+};
+//# sourceMappingURL=asset-builders.js.map

package/dist/lib/utils/asset-builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-builders.js","sourceRoot":"","sources":["../../../src/lib/utils/asset-builders.ts"],"names":[],"mappings":";AAAA,oDAAoD;AACpD,EAAE;AACF,sEAAsE;AACtE,yEAAyE;AACzE,yEAAyE;AACzE,yEAAyE;AACzE,2DAA2D;AAC3D,qEAAqE;AACrE,8DAA8D;;;AAyB9D,gCAEC;AAGD,gCAEC;AAGD,gCAEC;AAGD,8BAEC;AAGD,4BAEC;AAGD,8BAEC;AAGD,0CAEC;AAGD,4BAEC;AAGD,sCAEC;AAGD,oCAEC;AApDD,uEAAuE;AACvE,2EAA2E;AAC3E,oBAAoB;AAEpB,iEAAiE;AACjE,SAAgB,UAAU,CAAC,MAAsC;IAC/D,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC5C,CAAC;AAED,gEAAgE;AAChE,SAAgB,UAAU,CAAC,MAAsC;IAC/D,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC5C,CAAC;AAED,iEAAiE;AACjE,SAAgB,UAAU,CAAC,MAAsC;IAC/D,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AAC5C,CAAC;AAED,8DAA8D;AAC9D,SAAgB,SAAS,CAAC,MAAqC;IAC7D,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED,4DAA4D;AAC5D,SAAgB,QAAQ,CAAC,MAAoC;IAC3D,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC1C,CAAC;AAED,+DAA+D;AAC/D,SAAgB,SAAS,CAAC,MAAqC;IAC7D,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAC3C,CAAC;AAED,0EAA0E;AAC1E,SAAgB,eAAe,CAAC,MAA2C;IACzE,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACjD,CAAC;AAED,4DAA4D;AAC5D,SAAgB,QAAQ,CAAC,MAAoC;IAC3D,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;AAC1C,CAAC;AAED,sEAAsE;AACtE,SAAgB,aAAa,CAAC,MAAyC;IACrE,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC;AAC/C,CAAC;AAED,oEAAoE;AACpE,SAAgB,YAAY,CAAC,MAAwC;IACnE,OAAO,EAAE,GAAG,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACU,QAAA,KAAK,GAAG;IACnB,KAAK,EAAE,UAAU;IACjB,KAAK,EAAE,UAAU;IACjB,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,QAAQ;IACb,IAAI,EAAE,SAAS;IACf,UAAU,EAAE,eAAe;IAC3B,GAAG,EAAE,QAAQ;IACb,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,YAAY;CACb,CAAC"}

package/dist/lib/utils/capabilities.d.ts

@@ -0,0 +1,259 @@
+/**
+ * AdCP Capabilities utilities
+ *
+ * Provides types and helpers for working with agent capabilities,
+ * including synthetic capabilities for v2 servers that don't support
+ * the get_adcp_capabilities tool.
+ */
+/**
+ * Detected AdCP major version
+ */
+export type AdcpMajorVersion = 2 | 3;
+/**
+ * Supported AdCP protocols/domains
+ */
+export type AdcpProtocol = 'media_buy' | 'signals' | 'governance' | 'creative' | 'sponsored_intelligence' | 'trusted_match' | 'compliance_testing' | 'brand';
+/**
+ * Media buy features available on the agent
+ */
+export interface MediaBuyFeatures {
+    /** Agent supports inline creative upload in create/update_media_buy */
+    inlineCreativeManagement?: boolean;
+    /** Agent supports property_list filtering in get_products */
+    propertyListFiltering?: boolean;
+    /** Agent supports content standards validation */
+    contentStandards?: boolean;
+    /** Agent supports conversion event tracking (sync_event_sources, log_event) */
+    conversionTracking?: boolean;
+    /** Agent supports first-party CRM audience management (sync_audiences) */
+    audienceTargeting?: boolean;
+}
+/**
+ * Account management capabilities declared by the seller
+ */
+export interface AccountCapabilities {
+    /**
+     * Whether the seller requires operator-level credentials.
+     * When false (default), the agent authenticates once and declares brands/operators via sync_accounts.
+     * When true, each operator must authenticate independently.
+     */
+    requireOperatorAuth: boolean;
+    /**
+     * OAuth authorization endpoint for obtaining operator-level credentials.
+     * Present when the seller supports OAuth for operator authentication.
+     * May be absent even when requireOperatorAuth is true — in that case,
+     * operators obtain credentials out-of-band (e.g., seller portal, API key).
+     */
+    authorizationEndpoint?: string;
+    /**
+     * Billing models this seller supports (e.g., 'operator', 'agent').
+     */
+    supportedBilling: ('operator' | 'agent' | 'advertiser')[];
+    /**
+     * Default billing model applied when omitted from sync_accounts.
+     */
+    defaultBilling?: 'operator' | 'agent' | 'advertiser';
+    /**
+     * Whether an active account is required before calling get_products.
+     */
+    requiredForProducts: boolean;
+    /**
+     * Whether the seller supports sandbox accounts for testing.
+     * For implicit accounts (require_operator_auth: false), declare sandbox via sync_accounts
+     * with sandbox: true and reference by natural key. For explicit accounts
+     * (require_operator_auth: true), discover pre-existing test accounts via list_accounts.
+     */
+    sandbox: boolean;
+}
+/**
+ * Creative protocol capabilities declared by the agent.
+ */
+export interface CreativeCapabilities {
+    /** Agent can validate compliance requirements while building creatives */
+    supportsCompliance: boolean;
+    /** Agent exposes a creative library addressable via creative_id */
+    hasCreativeLibrary: boolean;
+    /** Agent can generate creatives from a natural-language brief */
+    supportsGeneration: boolean;
+    /** Agent can adapt an existing creative to a new format */
+    supportsTransformation: boolean;
+}
+/**
+ * Idempotency capabilities declared by the seller.
+ *
+ * Clients MUST NOT fall back to an assumed TTL when the seller omits this —
+ * `getIdempotencyReplayTtlSeconds()` throws when the declaration is missing
+ * on a v3 server rather than silently defaulting to 24h. A seller without the
+ * declaration is non-compliant and unsafe for retry-sensitive operations.
+ */
+export interface IdempotencyCapabilities {
+    /**
+     * Seconds the seller retains cached `(principal, idempotency_key, payload)`
+     * tuples. BYOK callers compare their persisted key's age against this to
+     * decide whether a fresh key + natural-key lookup is safer than reusing.
+     */
+    replayTtlSeconds: number;
+}
+/**
+ * Normalized capabilities response that works for both v2 and v3 servers
+ */
+export interface AdcpCapabilities {
+    /** Detected version ('v2' or 'v3') */
+    version: 'v2' | 'v3';
+    /** Array of supported major versions (e.g., [2] or [2, 3]) */
+    majorVersions: AdcpMajorVersion[];
+    /** Supported protocols */
+    protocols: AdcpProtocol[];
+    /** Media buy specific features */
+    features: MediaBuyFeatures;
+    /** Account management capabilities */
+    account?: AccountCapabilities;
+    /** Creative protocol capabilities */
+    creative?: CreativeCapabilities;
+    /** Idempotency replay capabilities (v3 sellers declaring `adcp.idempotency`) */
+    idempotency?: IdempotencyCapabilities;
+    /** Supported extension namespaces (e.g., 'scope3', 'garm') */
+    extensions: string[];
+    /**
+     * Experimental AdCP surfaces this agent implements. Dot-namespaced feature
+     * ids (e.g. `brand.rights_lifecycle`, `governance.campaign`, `trusted_match.core`)
+     * sellers declare when they opt into surfaces whose schemas carry
+     * `x-status: experimental`. Consumers should gate any reliance on
+     * experimental fields on presence of the matching id here.
+     *
+     * See https://adcontextprotocol.org/docs/reference/experimental-status
+     */
+    experimentalFeatures?: string[];
+    /** Publisher domains covered by this agent */
+    publisherDomains?: string[];
+    /** Supported advertising channels */
+    channels?: string[];
+    /** Last updated timestamp (if provided by server) */
+    lastUpdated?: string;
+    /** Whether this was synthesized from tool list (v2) or from get_adcp_capabilities (v3) */
+    _synthetic: boolean;
+    /** Raw response from get_adcp_capabilities (only for v3) */
+    _raw?: Record<string, unknown>;
+}
+/**
+ * Tool info for capability detection
+ */
+export interface ToolInfo {
+    name: string;
+    description?: string;
+}
+/**
+ * Known AdCP tool names for protocol detection.
+ * These map to task names in the AdCP schema index (kebab-case -> snake_case).
+ *
+ * Note: Some tools appear in multiple arrays (e.g., list_creative_formats is in
+ * both MEDIA_BUY_TOOLS and CREATIVE_TOOLS). This is intentional - these tools
+ * serve multiple domains, and their presence should activate all relevant protocols.
+ */
+export declare const MEDIA_BUY_TOOLS: readonly ["get_products", "list_creative_formats", "create_media_buy", "update_media_buy", "sync_creatives", "list_creatives", "get_media_buy_delivery", "provide_performance_feedback", "sync_audiences"];
+export declare const SIGNALS_TOOLS: readonly ["get_signals", "activate_signal"];
+export declare const GOVERNANCE_TOOLS: readonly ["create_property_list", "update_property_list", "get_property_list", "list_property_lists", "delete_property_list", "list_content_standards", "get_content_standards", "create_content_standards", "update_content_standards", "calibrate_content", "validate_content_delivery", "get_media_buy_artifacts", "sync_plans", "check_governance", "report_plan_outcome", "get_plan_audit_logs", "get_creative_features"];
+export declare const CREATIVE_TOOLS: readonly ["build_creative", "list_creative_formats", "preview_creative", "list_creatives", "sync_creatives"];
+export declare const SPONSORED_INTELLIGENCE_TOOLS: readonly ["si_get_offering", "si_initiate_session", "si_send_message", "si_terminate_session"];
+export declare const TRUSTED_MATCH_TOOLS: readonly ["context_match", "identity_match"];
+export declare const COMPLIANCE_TOOLS: readonly ["comply_test_controller"];
+export declare const BRAND_RIGHTS_TOOLS: readonly ["get_brand_identity", "get_rights", "acquire_rights"];
+export declare const EVENT_TRACKING_TOOLS: readonly ["sync_event_sources", "log_event"];
+export declare const ACCOUNT_TOOLS: readonly ["list_accounts", "sync_accounts"];
+export declare const PROTOCOL_TOOLS: readonly ["get_adcp_capabilities"];
+/**
+ * Augment declared capabilities with compliance_testing if the tool is present
+ * but no `compliance_testing` capability block / protocol entry was advertised.
+ *
+ * Per AdCP 3.0, agents declare comply_test_controller support via the
+ * top-level `capabilities.compliance_testing` block. `parseCapabilitiesResponse`
+ * already promotes that block into the internal `protocols` list, so if we
+ * reach this function with the tool present but the protocol missing, the
+ * agent forgot the declaration. We auto-bridge (the SDK's internal type can
+ * treat the agent as compliance-capable) and warn the agent once so they can
+ * ship the proper block.
+ *
+ * Other protocols (media_buy, signals, etc.) are NOT augmented because a stub
+ * or partial tool registration could produce false positives.
+ */
+export declare function augmentCapabilitiesFromTools(capabilities: AdcpCapabilities, tools: ToolInfo[]): AdcpCapabilities;
+export declare function buildSyntheticCapabilities(tools: ToolInfo[]): AdcpCapabilities;
+/**
+ * Parse a get_adcp_capabilities response into normalized form
+ */
+export declare function parseCapabilitiesResponse(response: any): AdcpCapabilities;
+/**
+ * Check if capabilities indicate v3 support
+ */
+export declare function supportsV3(capabilities: AdcpCapabilities): boolean;
+/**
+ * Check if a specific protocol is supported
+ */
+export declare function supportsProtocol(capabilities: AdcpCapabilities, protocol: AdcpProtocol): boolean;
+/**
+ * Check if property list filtering is supported (v3 feature)
+ */
+export declare function supportsPropertyListFiltering(capabilities: AdcpCapabilities): boolean;
+/**
+ * Check if content standards are supported (v3 feature)
+ */
+export declare function supportsContentStandards(capabilities: AdcpCapabilities): boolean;
+/**
+ * Check if the seller requires per-operator authentication
+ */
+export declare function requiresOperatorAuth(capabilities: AdcpCapabilities): boolean;
+/**
+ * Check if an active account is required before calling get_products
+ */
+export declare function requiresAccountForProducts(capabilities: AdcpCapabilities): boolean;
+/**
+ * Check if the seller supports sandbox accounts
+ */
+export declare function supportsSandbox(capabilities: AdcpCapabilities): boolean;
+/**
+ * Check if the agent has opted into a specific experimental AdCP surface.
+ *
+ * Experimental surfaces carry `x-status: experimental` in the spec and their
+ * fields may change between minor releases. Consumers should gate any
+ * reliance on experimental fields on a positive check here.
+ *
+ * @param capabilities — normalized capabilities from `parseCapabilitiesResponse`
+ * @param featureId — dot-namespaced id (e.g. `brand.rights_lifecycle`)
+ *
+ * @example
+ * ```ts
+ * if (supportsExperimentalFeature(caps, 'brand.rights_lifecycle')) {
+ *   // safe to call acquire_rights / release_rights and read their responses
+ * }
+ * ```
+ */
+export declare function supportsExperimentalFeature(capabilities: AdcpCapabilities, featureId: string): boolean;
+/**
+ * Feature name that can be checked via supports()/require().
+ *
+ * Supported namespaces:
+ * - Plain names resolve to media_buy.features (e.g., 'audience_targeting')
+ * - 'media_buy', 'signals', etc. check supported_protocols
+ * - 'ext:<name>' checks extensions_supported (e.g., 'ext:scope3')
+ * - 'targeting.<name>' checks media_buy.execution.targeting (e.g., 'targeting.geo_countries')
+ */
+export type FeatureName = string;
+/**
+ * Map of task names to features they require.
+ *
+ * When validateFeatures is enabled (default), SingleAgentClient checks
+ * these features against seller capabilities before sending a request.
+ * Tasks not listed here have no feature requirements.
+ */
+export declare const TASK_FEATURE_MAP: Record<string, FeatureName[]>;
+/**
+ * Resolve whether a single feature is supported by the given capabilities.
+ *
+ * Absent = unsupported (returns false).
+ */
+export declare function resolveFeature(capabilities: AdcpCapabilities, feature: FeatureName): boolean;
+/**
+ * List all declared feature names from capabilities (for error messages).
+ */
+export declare function listDeclaredFeatures(capabilities: AdcpCapabilities): string[];
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/lib/utils/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/capabilities.ts"],"names":[],"mappings":"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"}