@adcp/sdk 5.23.0

package/dist/lib/utils/format-renders.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Format Renders Normalizer
+ *
+ * Handles conversion between v2 top-level dimensions and v3 renders array.
+ * The library exposes only v3 API (renders array) to clients,
+ * and internally normalizes responses from v2 servers.
+ */
+/**
+ * Dimensions for a render
+ */
+export interface RenderDimensions {
+    width: number;
+    height: number;
+}
+/**
+ * v3 render specification — one entry in `Format.renders[]`.
+ *
+ * Renamed from `FormatRender` (see deprecated alias below) to free the
+ * `FormatRender` name for the factory namespace in `format-render-builders`,
+ * which is the more common autocomplete target. TypeScript keeps type and
+ * value namespaces separate, but the re-export barrel in `src/lib/index.ts`
+ * can't disambiguate between a type re-export and a const re-export at the
+ * same name — hence the rename.
+ */
+export interface FormatRenderEntry {
+    /** Unique identifier for this render */
+    render_id: string;
+    /** Semantic role (e.g., 'primary', 'companion', 'mobile_variant') */
+    role: string;
+    /** Dimensions of this render */
+    dimensions?: RenderDimensions;
+    /** Whether dimensions come from format_id parameters */
+    parameters_from_format_id?: boolean;
+}
+/**
+ * @deprecated Renamed to `FormatRenderEntry`. This alias keeps existing
+ * imports compiling but is not re-exported from the package barrel
+ * (`@adcp/sdk`) — the barrel's `FormatRender` identifier now refers to
+ * the factory namespace. Migrate to `FormatRenderEntry` next release.
+ */
+export type FormatRender = FormatRenderEntry;
+/**
+ * v2 format with top-level dimensions
+ */
+export interface FormatV2 {
+    width?: number;
+    height?: number;
+    dimensions?: RenderDimensions;
+    [key: string]: unknown;
+}
+/**
+ * v3 format with renders array
+ */
+export interface FormatV3 {
+    renders?: FormatRenderEntry[];
+    [key: string]: unknown;
+}
+/**
+ * Normalize a format from v2 (top-level dimensions) to v3 (renders array).
+ * If the format already has renders, returns as-is.
+ */
+export declare function normalizeFormatRenders(format: FormatV2 | FormatV3): FormatV3;
+/**
+ * Normalize all formats in a list_creative_formats response
+ */
+export declare function normalizeFormatsResponse(response: any): any;
+/**
+ * Get renders from a format (normalizes v2 to v3 format)
+ */
+export declare function getFormatRenders(format: FormatV2 | FormatV3): FormatRenderEntry[];
+/**
+ * Get primary render from a format
+ */
+export declare function getPrimaryRender(format: FormatV2 | FormatV3): FormatRenderEntry | undefined;
+/**
+ * Get companion renders from a format
+ */
+export declare function getCompanionRenders(format: FormatV2 | FormatV3): FormatRenderEntry[];
+/**
+ * Check if format has multiple renders (companion ads, adaptive)
+ */
+export declare function isMultiRenderFormat(format: FormatV2 | FormatV3): boolean;
+/**
+ * Check if format uses v2 top-level dimensions
+ */
+export declare function usesV2Dimensions(format: any): boolean;
+/**
+ * Check if format uses v3 renders array
+ */
+export declare function usesV3Renders(format: any): boolean;
+/**
+ * Get format dimensions (works with both v2 and v3)
+ * For multi-render formats, returns primary render dimensions
+ */
+export declare function getFormatDimensions(format: FormatV2 | FormatV3): RenderDimensions | undefined;
+//# sourceMappingURL=format-renders.d.ts.map

package/dist/lib/utils/format-renders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-renders.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/format-renders.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,wDAAwD;IACxD,yBAAyB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,iBAAiB,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CA4C5E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,GAAG,GAAG,GAAG,CAc3D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,iBAAiB,EAAE,CAGjF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,iBAAiB,GAAG,SAAS,CAG3F;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,iBAAiB,EAAE,CAGpF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAGxE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAIrD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAElD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,gBAAgB,GAAG,SAAS,CAoB7F"}

package/dist/lib/utils/format-renders.js

@@ -0,0 +1,141 @@
+"use strict";
+/**
+ * Format Renders Normalizer
+ *
+ * Handles conversion between v2 top-level dimensions and v3 renders array.
+ * The library exposes only v3 API (renders array) to clients,
+ * and internally normalizes responses from v2 servers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeFormatRenders = normalizeFormatRenders;
+exports.normalizeFormatsResponse = normalizeFormatsResponse;
+exports.getFormatRenders = getFormatRenders;
+exports.getPrimaryRender = getPrimaryRender;
+exports.getCompanionRenders = getCompanionRenders;
+exports.isMultiRenderFormat = isMultiRenderFormat;
+exports.usesV2Dimensions = usesV2Dimensions;
+exports.usesV3Renders = usesV3Renders;
+exports.getFormatDimensions = getFormatDimensions;
+/**
+ * Normalize a format from v2 (top-level dimensions) to v3 (renders array).
+ * If the format already has renders, returns as-is.
+ */
+function normalizeFormatRenders(format) {
+    // Already has renders array - return as-is
+    if (format.renders && Array.isArray(format.renders)) {
+        return format;
+    }
+    const v2Format = format;
+    // Check for v2 dimensions
+    const hasWidth = v2Format.width !== undefined;
+    const hasHeight = v2Format.height !== undefined;
+    const hasDimensions = v2Format.dimensions !== undefined;
+    if (!hasWidth && !hasHeight && !hasDimensions) {
+        // No dimension info - could be a template format
+        // Return without renders (caller can check accepts_parameters)
+        return format;
+    }
+    // Build dimensions object
+    let dimensions;
+    if (hasDimensions) {
+        dimensions = v2Format.dimensions;
+    }
+    else if (hasWidth || hasHeight) {
+        dimensions = {
+            width: v2Format.width ?? 0,
+            height: v2Format.height ?? 0,
+        };
+    }
+    // Remove v2 fields and add v3 renders
+    const { width, height, dimensions: _, ...rest } = v2Format;
+    return {
+        ...rest,
+        renders: [
+            {
+                render_id: 'primary',
+                role: 'primary',
+                dimensions,
+            },
+        ],
+    };
+}
+/**
+ * Normalize all formats in a list_creative_formats response
+ */
+function normalizeFormatsResponse(response) {
+    // Handle raw array responses (agent omitted { formats: [...] } wrapper)
+    if (Array.isArray(response)) {
+        return { formats: response.map(normalizeFormatRenders) };
+    }
+    if (!response.formats || !Array.isArray(response.formats)) {
+        return response;
+    }
+    return {
+        ...response,
+        formats: response.formats.map(normalizeFormatRenders),
+    };
+}
+/**
+ * Get renders from a format (normalizes v2 to v3 format)
+ */
+function getFormatRenders(format) {
+    const normalized = normalizeFormatRenders(format);
+    return normalized.renders ?? [];
+}
+/**
+ * Get primary render from a format
+ */
+function getPrimaryRender(format) {
+    const renders = getFormatRenders(format);
+    return renders.find(r => r.role === 'primary') ?? renders[0];
+}
+/**
+ * Get companion renders from a format
+ */
+function getCompanionRenders(format) {
+    const renders = getFormatRenders(format);
+    return renders.filter(r => r.role === 'companion');
+}
+/**
+ * Check if format has multiple renders (companion ads, adaptive)
+ */
+function isMultiRenderFormat(format) {
+    const renders = getFormatRenders(format);
+    return renders.length > 1;
+}
+/**
+ * Check if format uses v2 top-level dimensions
+ */
+function usesV2Dimensions(format) {
+    return ((format.width !== undefined || format.height !== undefined || format.dimensions !== undefined) && !format.renders);
+}
+/**
+ * Check if format uses v3 renders array
+ */
+function usesV3Renders(format) {
+    return Array.isArray(format.renders);
+}
+/**
+ * Get format dimensions (works with both v2 and v3)
+ * For multi-render formats, returns primary render dimensions
+ */
+function getFormatDimensions(format) {
+    // v3 format - get from primary render
+    if (format.renders) {
+        const primary = getPrimaryRender(format);
+        return primary?.dimensions;
+    }
+    // v2 format - get from top-level
+    const v2Format = format;
+    if (v2Format.dimensions) {
+        return v2Format.dimensions;
+    }
+    if (v2Format.width !== undefined || v2Format.height !== undefined) {
+        return {
+            width: v2Format.width ?? 0,
+            height: v2Format.height ?? 0,
+        };
+    }
+    return undefined;
+}
+//# sourceMappingURL=format-renders.js.map

package/dist/lib/utils/format-renders.js.map

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

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

@@ -0,0 +1,96 @@
+/**
+ * Idempotency key ergonomics for AdCP mutating requests.
+ *
+ * AdCP v3 requires an `idempotency_key` on every mutating request. This
+ * module handles two things the SDK owns:
+ *
+ * 1. Knowing which tools are mutating (so we auto-generate for them and not
+ *    for read-only tools).
+ * 2. Generating UUID v4 keys that satisfy the spec's
+ *    `^[A-Za-z0-9_.:-]{16,255}$` pattern.
+ */
+/**
+ * Tools whose request schema requires `idempotency_key`.
+ *
+ * Derived from the Zod schemas at module load so this stays in sync with
+ * the upstream AdCP schema — no hand-maintained list to drift.
+ *
+ * `si_terminate_session` is intentionally excluded even though it's a
+ * mutating operation: the spec documents it as naturally idempotent via
+ * `session_id` (terminate twice = no-op).
+ */
+export declare const MUTATING_TASKS: ReadonlySet<string>;
+/**
+ * Whether a tool's request schema requires `idempotency_key`.
+ *
+ * Callers use this to decide whether to auto-generate a key when one isn't
+ * provided. Unknown tool names return `false` — we don't guess.
+ */
+export declare function isMutatingTask(toolName: string): boolean;
+/**
+ * Generate a fresh idempotency key for a mutating request.
+ *
+ * Returns a UUID v4, which satisfies the spec's
+ * `^[A-Za-z0-9_.:-]{16,255}$` pattern and provides ≥122 bits of entropy
+ * (the spec minimum to prevent cache enumeration).
+ */
+export declare function generateIdempotencyKey(): string;
+/**
+ * Pattern the spec requires `idempotency_key` to match. Exported so callers
+ * doing BYOK can validate their keys before sending.
+ */
+export declare const IDEMPOTENCY_KEY_PATTERN: RegExp;
+/**
+ * Validate that a key matches the spec pattern. Useful for callers that
+ * persist keys (e.g., bring-your-own-key from a database) and want to
+ * catch drift early.
+ */
+export declare function isValidIdempotencyKey(key: string): boolean;
+/**
+ * Utility type: take a generated request interface that requires
+ * `idempotency_key` and make that field optional for callers.
+ *
+ * The SDK auto-generates a UUID v4 when callers don't provide one, so
+ * public client signatures use this loosened input type. Callers who
+ * want byte-identical retries across process restarts still pass their
+ * own key — it's just no longer required at compile time.
+ */
+export type MutatingRequestInput<T extends {
+    idempotency_key: string;
+}> = Omit<T, 'idempotency_key'> & {
+    idempotency_key?: string;
+};
+/**
+ * Validate a bring-your-own-key `idempotency_key` up front and return a
+ * `{ idempotency_key }` fragment to spread into a mutating request.
+ *
+ * Useful when the caller persists keys across process restarts (e.g., key
+ * stored in a DB alongside a campaign row) and wants to catch drift before
+ * the round-trip — the server would reject a malformed key with
+ * `INVALID_REQUEST`, but failing locally produces a faster, cleaner error.
+ *
+ * Throws when the key doesn't match `IDEMPOTENCY_KEY_PATTERN`
+ * (`^[A-Za-z0-9_.:-]{16,255}$`).
+ *
+ * @example
+ * ```ts
+ * const key = await db.getOrCreateIdempotencyKey(campaign.id);
+ * const result = await client.createMediaBuy({ ...params, ...useIdempotencyKey(key) });
+ * ```
+ */
+export declare function useIdempotencyKey(key: string): {
+    idempotency_key: string;
+};
+/**
+ * Truncate an idempotency key for logging — first 8 chars followed by `…`.
+ * Callers who need the full key for debugging can opt in via
+ * `ADCP_LOG_IDEMPOTENCY_KEYS=1`.
+ */
+export declare function redactIdempotencyKey(key: string): string;
+/**
+ * Return a shallow copy of `args` with any `idempotency_key` field replaced by
+ * its truncated form for safe debug logging. Leaves non-key fields untouched.
+ * No-op when `ADCP_LOG_IDEMPOTENCY_KEYS` is set.
+ */
+export declare function redactIdempotencyKeyInArgs<T extends Record<string, unknown>>(args: T): T;
+//# sourceMappingURL=idempotency.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/idempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAAyB,CAAC;AAwBzE;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAA8B,CAAC;AAEnE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,IAAI,IAAI,CAAC,CAAC,EAAE,iBAAiB,CAAC,GAAG;IACrG,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,eAAe,EAAE,MAAM,CAAA;CAAE,CAU1E;AAcD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAKxF"}

package/dist/lib/utils/idempotency.js

@@ -0,0 +1,156 @@
+"use strict";
+/**
+ * Idempotency key ergonomics for AdCP mutating requests.
+ *
+ * AdCP v3 requires an `idempotency_key` on every mutating request. This
+ * module handles two things the SDK owns:
+ *
+ * 1. Knowing which tools are mutating (so we auto-generate for them and not
+ *    for read-only tools).
+ * 2. Generating UUID v4 keys that satisfy the spec's
+ *    `^[A-Za-z0-9_.:-]{16,255}$` pattern.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDEMPOTENCY_KEY_PATTERN = exports.MUTATING_TASKS = void 0;
+exports.isMutatingTask = isMutatingTask;
+exports.generateIdempotencyKey = generateIdempotencyKey;
+exports.isValidIdempotencyKey = isValidIdempotencyKey;
+exports.useIdempotencyKey = useIdempotencyKey;
+exports.redactIdempotencyKey = redactIdempotencyKey;
+exports.redactIdempotencyKeyInArgs = redactIdempotencyKeyInArgs;
+const crypto_1 = require("crypto");
+const tool_request_schemas_1 = require("./tool-request-schemas");
+/**
+ * Tools whose request schema requires `idempotency_key`.
+ *
+ * Derived from the Zod schemas at module load so this stays in sync with
+ * the upstream AdCP schema — no hand-maintained list to drift.
+ *
+ * `si_terminate_session` is intentionally excluded even though it's a
+ * mutating operation: the spec documents it as naturally idempotent via
+ * `session_id` (terminate twice = no-op).
+ */
+exports.MUTATING_TASKS = deriveMutatingTasks();
+function deriveMutatingTasks() {
+    const result = new Set();
+    for (const [toolName, schema] of Object.entries(tool_request_schemas_1.TOOL_REQUEST_SCHEMAS)) {
+        if (!schema)
+            continue;
+        const shape = schema.shape;
+        if (!shape)
+            continue;
+        const field = shape.idempotency_key;
+        if (!field)
+            continue;
+        if (isRequiredZodField(field)) {
+            result.add(toolName);
+        }
+    }
+    return result;
+}
+function isRequiredZodField(field) {
+    const def = field?._def;
+    if (!def)
+        return false;
+    // Zod wraps optional fields in ZodOptional or ZodDefault. Required = neither.
+    return def.typeName !== 'ZodOptional' && def.typeName !== 'ZodDefault';
+}
+/**
+ * Whether a tool's request schema requires `idempotency_key`.
+ *
+ * Callers use this to decide whether to auto-generate a key when one isn't
+ * provided. Unknown tool names return `false` — we don't guess.
+ */
+function isMutatingTask(toolName) {
+    return exports.MUTATING_TASKS.has(toolName);
+}
+/**
+ * Generate a fresh idempotency key for a mutating request.
+ *
+ * Returns a UUID v4, which satisfies the spec's
+ * `^[A-Za-z0-9_.:-]{16,255}$` pattern and provides ≥122 bits of entropy
+ * (the spec minimum to prevent cache enumeration).
+ */
+function generateIdempotencyKey() {
+    return (0, crypto_1.randomUUID)();
+}
+/**
+ * Pattern the spec requires `idempotency_key` to match. Exported so callers
+ * doing BYOK can validate their keys before sending.
+ */
+exports.IDEMPOTENCY_KEY_PATTERN = /^[A-Za-z0-9_.:-]{16,255}$/;
+/**
+ * Validate that a key matches the spec pattern. Useful for callers that
+ * persist keys (e.g., bring-your-own-key from a database) and want to
+ * catch drift early.
+ */
+function isValidIdempotencyKey(key) {
+    return exports.IDEMPOTENCY_KEY_PATTERN.test(key);
+}
+/**
+ * Validate a bring-your-own-key `idempotency_key` up front and return a
+ * `{ idempotency_key }` fragment to spread into a mutating request.
+ *
+ * Useful when the caller persists keys across process restarts (e.g., key
+ * stored in a DB alongside a campaign row) and wants to catch drift before
+ * the round-trip — the server would reject a malformed key with
+ * `INVALID_REQUEST`, but failing locally produces a faster, cleaner error.
+ *
+ * Throws when the key doesn't match `IDEMPOTENCY_KEY_PATTERN`
+ * (`^[A-Za-z0-9_.:-]{16,255}$`).
+ *
+ * @example
+ * ```ts
+ * const key = await db.getOrCreateIdempotencyKey(campaign.id);
+ * const result = await client.createMediaBuy({ ...params, ...useIdempotencyKey(key) });
+ * ```
+ */
+function useIdempotencyKey(key) {
+    if (typeof key !== 'string' || !isValidIdempotencyKey(key)) {
+        // Preview only 8 chars so near-valid keys (16+ chars, minor drift) don't
+        // flow verbatim into exception messages and stack traces. Matches the
+        // redactIdempotencyKey() policy for debug logs.
+        const preview = typeof key === 'string' ? `${JSON.stringify(key.slice(0, 8))}${key.length > 8 ? '…' : ''}` : typeof key;
+        throw new Error(`Invalid idempotency_key: must match ${exports.IDEMPOTENCY_KEY_PATTERN}. Received: ${preview}`);
+    }
+    return { idempotency_key: key };
+}
+/**
+ * True when the caller has opted into logging full idempotency keys via the
+ * `ADCP_LOG_IDEMPOTENCY_KEYS` environment variable. Keys are a retry-pattern
+ * oracle within their TTL, so the default is to truncate.
+ */
+function fullIdempotencyKeyLoggingEnabled() {
+    const value = process.env.ADCP_LOG_IDEMPOTENCY_KEYS;
+    if (!value)
+        return false;
+    const v = value.toLowerCase();
+    return v === '1' || v === 'true' || v === 'yes';
+}
+/**
+ * Truncate an idempotency key for logging — first 8 chars followed by `…`.
+ * Callers who need the full key for debugging can opt in via
+ * `ADCP_LOG_IDEMPOTENCY_KEYS=1`.
+ */
+function redactIdempotencyKey(key) {
+    if (fullIdempotencyKeyLoggingEnabled())
+        return key;
+    if (typeof key !== 'string' || key.length === 0)
+        return key;
+    return `${key.slice(0, 8)}…`;
+}
+/**
+ * Return a shallow copy of `args` with any `idempotency_key` field replaced by
+ * its truncated form for safe debug logging. Leaves non-key fields untouched.
+ * No-op when `ADCP_LOG_IDEMPOTENCY_KEYS` is set.
+ */
+function redactIdempotencyKeyInArgs(args) {
+    if (!args || typeof args !== 'object')
+        return args;
+    if (!('idempotency_key' in args) || typeof args.idempotency_key !== 'string')
+        return args;
+    if (fullIdempotencyKeyLoggingEnabled())
+        return args;
+    return { ...args, idempotency_key: redactIdempotencyKey(args.idempotency_key) };
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/lib/utils/idempotency.js.map

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

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

@@ -0,0 +1,39 @@
+import type { CreativeFormat } from '../types';
+export { logger, createLogger, type LogLevel, type LoggerConfig } from './logger';
+export { batchPreviewProducts, batchPreviewFormats, clearPreviewCache, type PreviewResult, type BatchPreviewOptions, } from './preview-utils';
+export declare const REQUEST_TIMEOUT: number;
+export declare const MAX_CONCURRENT: number;
+export declare const STANDARD_FORMATS: CreativeFormat[];
+/**
+ * Circuit Breaker for handling agent failures
+ */
+export declare class CircuitBreaker {
+    private agentId;
+    private failures;
+    private lastFailTime;
+    private state;
+    private readonly failureThreshold;
+    private readonly resetTimeout;
+    constructor(agentId: string);
+    call<T>(fn: () => Promise<T>): Promise<T>;
+    private onSuccess;
+    private onFailure;
+}
+export declare function getCircuitBreaker(agentId: string): CircuitBreaker;
+/**
+ * Get standard creative formats
+ */
+export declare function getStandardFormats(): CreativeFormat[];
+export { unwrapProtocolResponse, isAdcpError, isAdcpSuccess } from './response-unwrapper';
+export type { AdCPResponse } from './response-unwrapper';
+export { extractResult, type ToolCallResultLike } from './extract-result';
+export { isRetryable, getRetryDelay } from './retry';
+export { extractAdcpErrorFromMcp, extractAdcpErrorFromTransport, extractAdcpErrorInfo, extractCorrelationId, resolveRecovery, getExpectedAction, } from './error-extraction';
+export type { ExtractedAdcpError } from './error-extraction';
+export { detectProtocol, detectProtocolWithTimeout } from './protocol-detection';
+export { A2A_CARD_PATHS, TRANSPORT_SUFFIX_REGEX, isAgentCardPath, isWellKnownAgentCardUrl, buildCardUrls, stripAgentCardPath, stripTransportSuffix, } from './a2a-discovery';
+export { getFormatAssets, getRequiredAssets, getOptionalAssets, getIndividualAssets, getRepeatableGroups, usesDeprecatedAssetsField, getAssetCount, hasAssets, } from './format-assets';
+export { adaptGetProductsRequestForV2, normalizeProductChannels, adaptPricingOptionForV2, normalizePricingOption, normalizeProductPricing, normalizeGetProductsResponse, usesV2PricingFields, usesV3PricingFields, isFixedPricing, isCPAPricing, getPrice, getFloorPrice, type PricingOptionV2, type PricingOptionV3, type PriceGuidanceV2, type PriceGuidanceV3, } from './pricing-adapter';
+export { adaptSyncCreativesRequestForV2 } from './sync-creatives-adapter';
+export { paginate, paginatePages, type PaginateOptions } from './pagination';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG/C,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAIlF,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,aAAa,EAClB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AAGzB,eAAO,MAAM,eAAe,QAAmD,CAAC;AAChF,eAAO,MAAM,cAAc,QAA8C,CAAC;AAG1E,eAAO,MAAM,gBAAgB,EAAE,cAAc,EA8C5C,CAAC;AAEF;;GAEG;AACH,qBAAa,cAAc;IAOb,OAAO,CAAC,OAAO;IAN3B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,KAAK,CAA6C;IAC1D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAK;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAElB,OAAO,EAAE,MAAM;IAE7B,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAoB/C,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,SAAS;CASlB;AAKD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAKjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,EAAE,CAErD;AAGD,OAAO,EAAE,sBAAsB,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1F,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG1E,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAGrD,OAAO,EACL,uBAAuB,EACvB,6BAA6B,EAC7B,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,OAAO,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAGjF,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,uBAAuB,EACvB,aAAa,EACb,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,yBAAyB,EACzB,aAAa,EACb,SAAS,GACV,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACvB,4BAA4B,EAC5B,mBAAmB,EACnB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,8BAA8B,EAAE,MAAM,0BAA0B,CAAC;AAG1E,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC"}