@adcp/sdk 5.25.1 → 6.0.0

package/dist/lib/server/decisioning/context.d.ts

@@ -0,0 +1,212 @@
+/**
+ * RequestContext — what the framework passes to every decision-point method.
+ *
+ *   - `account` — resolved tenant for this request (from `accounts.resolve()`)
+ *   - `state.*` — sync state reads (workflow steps, governance context, proposal lookups)
+ *   - `resolve.*` — async framework-mediated fetches (property lists, formats)
+ *
+ * Async patterns:
+ *   - **Sync**: adopter implements `xxx(req, ctx) => Promise<T>`. Framework
+ *     awaits in foreground; projects to wire success arm.
+ *   - **HITL**: adopter implements `xxxTask(taskId, req, ctx) => Promise<T>`.
+ *     Framework returns submitted envelope to buyer first, then runs the
+ *     task method in background; return value becomes terminal task state.
+ *   - **Status changes**: adopter calls `publishStatusChange(...)` (event bus)
+ *     from anywhere — webhook handler, cron, in-process worker. Framework
+ *     records the change and projects to subscribers / per-resource reads.
+ *
+ * Platform reads only; framework writes only. Adopters never mutate the context.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+import type { Account } from './account';
+import type { Format, FormatReferenceStructuredObject, PropertyList, CollectionList } from '../../types/tools.generated';
+import type { TaskHandoff, TaskHandoffContext } from './async-outcome';
+import type { CtxMetadataRef, ResourceKind } from '../ctx-metadata';
+export interface RequestContext<TAccount = Account> {
+    /** Resolved account for this request. */
+    account: TAccount;
+    /** Sync reads of in-flight state. */
+    state: WorkflowStateReader;
+    /** Async framework-mediated resolvers. */
+    resolve: ResourceResolver;
+    /**
+     * Ctx-metadata accessor — opaque-blob round-trip cache for adapter-internal
+     * state (GAM `ad_unit_ids` per product, `gam_order_id` per media buy, etc.).
+     *
+     * **Present only when `createAdcpServerFromPlatform({ ctxMetadata })` was
+     * wired with a `CtxMetadataStore`.** Adopters who don't wire a store see
+     * `undefined` here — branch defensively.
+     *
+     * The accessor is account-scoped automatically (uses `ctx.account.id` as
+     * the tenant boundary). Pass `kind + id`, get an opaque blob the publisher
+     * stashed during a prior call's response. Returns `undefined` on miss —
+     * fall through to your own DB.
+     *
+     * @example Read a product's ctx_metadata in createMediaBuy
+     * ```ts
+     * createMediaBuy: async (req, ctx) => {
+     *   for (const pkg of req.packages) {
+     *     const meta = await ctx.ctxMetadata?.product(pkg.product_id);
+     *     if (meta?.gam?.ad_unit_ids) {
+     *       await this.gam.createLineItem(pkg, meta.gam.ad_unit_ids);
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @example Persist platform IDs from createMediaBuy
+     * ```ts
+     * createMediaBuy: async (req, ctx) => {
+     *   const order = await this.gam.createOrder(req);
+     *   await ctx.ctxMetadata?.set('media_buy', order.id, { gam_order_id: order.id });
+     *   for (const li of order.lineItems) {
+     *     await ctx.ctxMetadata?.set('package', li.id, { gam_line_item_id: li.id });
+     *   }
+     *   return { media_buy_id: order.id, status: 'pending_creatives', packages: ... };
+     * }
+     * ```
+     *
+     * @public
+     */
+    ctxMetadata?: CtxMetadataAccessor;
+    /**
+     * Hand off the call to a background task. Returns a `TaskHandoff<T>`
+     * marker — return that from your method to signal the framework should
+     * project the spec-defined `Submitted` envelope to the buyer and run
+     * `fn` asynchronously. `fn` receives a `TaskHandoffContext` with the
+     * framework-issued `id` plus `update`/`heartbeat` affordances; its
+     * return value becomes the task's terminal artifact.
+     *
+     * Use this for hybrid sellers — the same tool serves both fast
+     * (programmatic remnant, instant `media_buy_id`) and slow (guaranteed
+     * inventory, trafficker review) inventory. Branch in your method body
+     * on whatever signal determines the path (product type, buyer
+     * pre-approval, etc.). Buyers pattern-match on the wire response shape
+     * (`media_buy_id` → sync; `task_id` → submitted) — predictable per
+     * request, dynamic per call.
+     *
+     * @example
+     * ```ts
+     * createMediaBuy: async (req, ctx) => {
+     *   if (this.requiresHITL(req)) {
+     *     return ctx.handoffToTask(async (taskCtx) => {
+     *       await taskCtx.update({ message: 'Awaiting trafficker' });
+     *       return await this.runHITL(req);
+     *     });
+     *   }
+     *   return await this.commitSync(req);
+     * }
+     * ```
+     */
+    handoffToTask<TResult>(fn: (taskCtx: TaskHandoffContext) => Promise<TResult>): TaskHandoff<TResult>;
+}
+export interface WorkflowStateReader {
+    /**
+     * Workflow steps that touched a given object. Object types: 'media_buy',
+     * 'creative', 'product', 'plan', 'audience', 'rights_grant', 'task'.
+     * Returns chronological steps. Used for "what's happened to this buy?"
+     * queries without re-fetching from the platform.
+     */
+    findByObject(type: WorkflowObjectType, id: string): readonly WorkflowStep[];
+    /**
+     * Resolve a proposal_id to its proposal context. Threaded by the framework
+     * across get_products → refine → create_media_buy without platform code.
+     * Returns null if the framework doesn't recognize the id.
+     */
+    findProposalById(proposalId: string): Proposal | null;
+    /**
+     * Currently in-flight verified governance context for the call. Returns
+     * the JWS string for downstream checks (or null for non-governance flows).
+     * Framework verifies signature, plan-binding, seller-binding, and
+     * phase-binding before exposing — platform can trust the value.
+     */
+    governanceContext(): GovernanceContextJWS | null;
+    /** Chronological steps for this request's account. Useful for audit reads. */
+    workflowSteps(): readonly WorkflowStep[];
+}
+export interface ResourceResolver {
+    /**
+     * Fetch a property list by id. Framework validates the id exists in the
+     * seller's declared lists before returning; consumers can trust the result.
+     */
+    propertyList(listId: string): Promise<PropertyList>;
+    /** Same for collection lists. */
+    collectionList(listId: string): Promise<CollectionList>;
+    /**
+     * Fetch a creative format definition. Framework routes through the
+     * `capabilities.creative_agents` declaration with a 1h cache; self-hosted
+     * formats hit the local CreativePlatform.listFormats(). Returns the
+     * resolved Format with full asset slot definitions.
+     */
+    creativeFormat(formatId: FormatReferenceStructuredObject): Promise<Format>;
+}
+export type WorkflowObjectType = 'media_buy' | 'creative' | 'product' | 'plan' | 'audience' | 'rights_grant' | 'task';
+export interface WorkflowStep {
+    /** Stable step identifier. */
+    id: string;
+    /** Object that this step touched. */
+    object: {
+        type: WorkflowObjectType;
+        id: string;
+    };
+    /** Tool that was called (wire verb). */
+    tool: string;
+    /** ISO 8601 timestamp. */
+    at: string;
+    /** Caller principal. */
+    actor: {
+        agent_url?: string;
+        principal?: string;
+    };
+    /** Outcome: 'submitted' / 'completed' / 'failed' / 'progress'. */
+    status: 'submitted' | 'completed' | 'failed' | 'progress';
+}
+export interface Proposal {
+    proposal_id: string;
+    /** Products in this proposal. */
+    product_ids: string[];
+    /** When the proposal was generated. */
+    issued_at: string;
+    /** When the proposal expires. */
+    expires_at?: string;
+    /** Account this proposal was issued to. */
+    account_id: string;
+}
+/**
+ * JWS-signed governance context. The framework returns the verified token;
+ * platform can re-pass to downstream calls (e.g., report_usage) and the
+ * framework will validate consistency. Don't unwrap or modify.
+ */
+export type GovernanceContextJWS = string;
+/**
+ * Account-scoped ctx-metadata accessor. The framework binds this to the
+ * resolved `ctx.account.id` per request — adopters never pass account.
+ *
+ * Generic `get`/`set`/`bulkGet` carry a `ResourceKind` discriminator;
+ * per-kind shorthand methods (`product(id)`, `mediaBuy(id)`, etc.) map to
+ * `get(kind, id)` for ergonomic call sites.
+ */
+export interface CtxMetadataAccessor {
+    /** Look up by kind + id. Returns `undefined` on miss. */
+    get(kind: ResourceKind, id: string): Promise<unknown | undefined>;
+    /** Bulk lookup. Result Map keyed by `${kind}:${id}`. Misses absent from Map. */
+    bulkGet(refs: readonly CtxMetadataRef[]): Promise<ReadonlyMap<string, unknown>>;
+    /**
+     * Persist a blob under (account, kind, id). Throws `CTX_METADATA_TOO_LARGE`
+     * if serialized size exceeds the configured cap (16KB default).
+     */
+    set(kind: ResourceKind, id: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /** Delete a single entry. */
+    delete(kind: ResourceKind, id: string): Promise<void>;
+    account(id: string): Promise<unknown | undefined>;
+    product(id: string): Promise<unknown | undefined>;
+    mediaBuy(id: string): Promise<unknown | undefined>;
+    package(id: string): Promise<unknown | undefined>;
+    creative(id: string): Promise<unknown | undefined>;
+    audience(id: string): Promise<unknown | undefined>;
+    signal(id: string): Promise<unknown | undefined>;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/lib/server/decisioning/context.d.ts.map

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

package/dist/lib/server/decisioning/context.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * RequestContext — what the framework passes to every decision-point method.
+ *
+ *   - `account` — resolved tenant for this request (from `accounts.resolve()`)
+ *   - `state.*` — sync state reads (workflow steps, governance context, proposal lookups)
+ *   - `resolve.*` — async framework-mediated fetches (property lists, formats)
+ *
+ * Async patterns:
+ *   - **Sync**: adopter implements `xxx(req, ctx) => Promise<T>`. Framework
+ *     awaits in foreground; projects to wire success arm.
+ *   - **HITL**: adopter implements `xxxTask(taskId, req, ctx) => Promise<T>`.
+ *     Framework returns submitted envelope to buyer first, then runs the
+ *     task method in background; return value becomes terminal task state.
+ *   - **Status changes**: adopter calls `publishStatusChange(...)` (event bus)
+ *     from anywhere — webhook handler, cron, in-process worker. Framework
+ *     records the change and projects to subscribers / per-resource reads.
+ *
+ * Platform reads only; framework writes only. Adopters never mutate the context.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=context.js.map

package/dist/lib/server/decisioning/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/context.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/lib/server/decisioning/errors-typed.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Typed `AdcpError` subclasses. Adopters pick from a closed set of class
+ * imports rather than memorizing string codes + recovery semantics.
+ *
+ * Each class encodes the canonical `code` / `recovery` / `field` /
+ * `suggestion` shape for its scenario. LLM-generated platforms get
+ * autocomplete on the import; humans skim the list to find the right
+ * class for their case.
+ *
+ * Empirical baseline (Emma matrix v17, 2026-04-30): LLM-generated
+ * sellers throw generic `Error` because the AdcpError code catalog
+ * isn't visible at the throw site. Framework auto-maps generic throws
+ * to `SERVICE_UNAVAILABLE`, which storyboards reject because (e.g.)
+ * the right code for "package_id doesn't exist" is `PACKAGE_NOT_FOUND`.
+ * Typed classes close the gap: the LLM imports `PackageNotFoundError`
+ * and the right code is implicit.
+ *
+ * **Coverage**: the ~20 highest-traffic codes from the v3 spec. Adopters
+ * needing a code not in this list still construct `AdcpError(code, ...)`
+ * directly with the full code vocabulary; this module is a convenience
+ * over the typed-class subset.
+ *
+ * @public
+ */
+import { AdcpError } from './async-outcome';
+interface CommonOpts {
+    /** Override the default message. Most callers use the default. */
+    message?: string;
+    /** Suggested fix surfaced to the buyer. */
+    suggestion?: string;
+    /** Additional structured context. */
+    details?: Record<string, unknown>;
+}
+export declare class PackageNotFoundError extends AdcpError {
+    constructor(packageId: string, opts?: CommonOpts);
+}
+export declare class MediaBuyNotFoundError extends AdcpError {
+    constructor(mediaBuyId: string, opts?: CommonOpts);
+}
+export declare class ProductNotFoundError extends AdcpError {
+    constructor(productId: string, opts?: CommonOpts);
+}
+export declare class CreativeNotFoundError extends AdcpError {
+    constructor(creativeId: string, opts?: CommonOpts);
+}
+export declare class ProductUnavailableError extends AdcpError {
+    constructor(productId: string, opts?: CommonOpts);
+}
+export declare class CreativeRejectedError extends AdcpError {
+    constructor(creativeId: string, reason: string, opts?: CommonOpts);
+}
+export declare class BudgetTooLowError extends AdcpError {
+    constructor(opts?: CommonOpts & {
+        floor?: number;
+        currency?: string;
+    });
+}
+export declare class BudgetExhaustedError extends AdcpError {
+    constructor(opts?: CommonOpts);
+}
+export declare class IdempotencyConflictError extends AdcpError {
+    constructor(opts?: CommonOpts);
+}
+export declare class InvalidRequestError extends AdcpError {
+    constructor(field: string, message: string, opts?: CommonOpts);
+}
+export declare class InvalidStateError extends AdcpError {
+    constructor(field: string, message: string, opts?: CommonOpts);
+}
+/**
+ * Convenience for the common `start_time >= end_time` case. Use
+ * `InvalidRequestError` for arbitrary field-level validation.
+ */
+export declare class BackwardsTimeRangeError extends AdcpError {
+    constructor(opts?: CommonOpts);
+}
+export declare class AuthRequiredError extends AdcpError {
+    constructor(opts?: CommonOpts);
+}
+export declare class PermissionDeniedError extends AdcpError {
+    constructor(action: string, opts?: CommonOpts);
+}
+export declare class RateLimitedError extends AdcpError {
+    constructor(retryAfterSeconds: number, opts?: CommonOpts);
+}
+export declare class ServiceUnavailableError extends AdcpError {
+    constructor(opts?: CommonOpts & {
+        retryAfterSeconds?: number;
+    });
+}
+export declare class UnsupportedFeatureError extends AdcpError {
+    constructor(feature: string, opts?: CommonOpts);
+}
+export declare class ComplianceUnsatisfiedError extends AdcpError {
+    constructor(reason: string, opts?: CommonOpts);
+}
+export declare class GovernanceDeniedError extends AdcpError {
+    constructor(reason: string, opts?: CommonOpts);
+}
+export declare class PolicyViolationError extends AdcpError {
+    constructor(policy: string, opts?: CommonOpts);
+}
+export {};
+//# sourceMappingURL=errors-typed.d.ts.map

package/dist/lib/server/decisioning/errors-typed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-typed.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/errors-typed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,UAAU,UAAU;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAOD,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CASrD;AAED,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAStD;AAED,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CASrD;AAED,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,UAAU,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAStD;AAcD,qBAAa,uBAAwB,SAAQ,SAAS;gBACxC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CASrD;AAED,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAStE;AAMD,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,IAAI,GAAE,UAAU,GAAG;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO;CAe1E;AAED,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,IAAI,GAAE,UAAe;CASlC;AAMD,qBAAa,wBAAyB,SAAQ,SAAS;gBACzC,IAAI,GAAE,UAAe;CASlC;AAMD,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CASlE;AAED,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CASlE;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,SAAS;gBACxC,IAAI,GAAE,UAAe;CASlC;AAMD,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,IAAI,GAAE,UAAe;CAQlC;AAED,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAQlD;AAMD,qBAAa,gBAAiB,SAAQ,SAAS;gBACjC,iBAAiB,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAS7D;AAED,qBAAa,uBAAwB,SAAQ,SAAS;gBACxC,IAAI,GAAE,UAAU,GAAG;QAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAO;CAUnE;AAED,qBAAa,uBAAwB,SAAQ,SAAS;gBACxC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAQnD;AAMD,qBAAa,0BAA2B,SAAQ,SAAS;gBAC3C,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAQlD;AAED,qBAAa,qBAAsB,SAAQ,SAAS;gBACtC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAQlD;AAED,qBAAa,oBAAqB,SAAQ,SAAS;gBACrC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe;CAQlD"}

package/dist/lib/server/decisioning/errors-typed.js

@@ -0,0 +1,304 @@
+"use strict";
+/**
+ * Typed `AdcpError` subclasses. Adopters pick from a closed set of class
+ * imports rather than memorizing string codes + recovery semantics.
+ *
+ * Each class encodes the canonical `code` / `recovery` / `field` /
+ * `suggestion` shape for its scenario. LLM-generated platforms get
+ * autocomplete on the import; humans skim the list to find the right
+ * class for their case.
+ *
+ * Empirical baseline (Emma matrix v17, 2026-04-30): LLM-generated
+ * sellers throw generic `Error` because the AdcpError code catalog
+ * isn't visible at the throw site. Framework auto-maps generic throws
+ * to `SERVICE_UNAVAILABLE`, which storyboards reject because (e.g.)
+ * the right code for "package_id doesn't exist" is `PACKAGE_NOT_FOUND`.
+ * Typed classes close the gap: the LLM imports `PackageNotFoundError`
+ * and the right code is implicit.
+ *
+ * **Coverage**: the ~20 highest-traffic codes from the v3 spec. Adopters
+ * needing a code not in this list still construct `AdcpError(code, ...)`
+ * directly with the full code vocabulary; this module is a convenience
+ * over the typed-class subset.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PolicyViolationError = exports.GovernanceDeniedError = exports.ComplianceUnsatisfiedError = exports.UnsupportedFeatureError = exports.ServiceUnavailableError = exports.RateLimitedError = exports.PermissionDeniedError = exports.AuthRequiredError = exports.BackwardsTimeRangeError = exports.InvalidStateError = exports.InvalidRequestError = exports.IdempotencyConflictError = exports.BudgetExhaustedError = exports.BudgetTooLowError = exports.CreativeRejectedError = exports.ProductUnavailableError = exports.CreativeNotFoundError = exports.ProductNotFoundError = exports.MediaBuyNotFoundError = exports.PackageNotFoundError = void 0;
+const async_outcome_1 = require("./async-outcome");
+// ---------------------------------------------------------------------------
+// Resource-not-found family — `recovery: 'terminal'`. ID is wrong; retry
+// with the same ID can't succeed. Buyer must fetch a fresh ID.
+// ---------------------------------------------------------------------------
+class PackageNotFoundError extends async_outcome_1.AdcpError {
+    constructor(packageId, opts = {}) {
+        super('PACKAGE_NOT_FOUND', {
+            recovery: 'terminal',
+            message: opts.message ?? `Package not found: ${packageId}`,
+            field: 'package_id',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.PackageNotFoundError = PackageNotFoundError;
+class MediaBuyNotFoundError extends async_outcome_1.AdcpError {
+    constructor(mediaBuyId, opts = {}) {
+        super('MEDIA_BUY_NOT_FOUND', {
+            recovery: 'terminal',
+            message: opts.message ?? `Media buy not found: ${mediaBuyId}`,
+            field: 'media_buy_id',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.MediaBuyNotFoundError = MediaBuyNotFoundError;
+class ProductNotFoundError extends async_outcome_1.AdcpError {
+    constructor(productId, opts = {}) {
+        super('PRODUCT_NOT_FOUND', {
+            recovery: 'terminal',
+            message: opts.message ?? `Product not found: ${productId}`,
+            field: 'product_id',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.ProductNotFoundError = ProductNotFoundError;
+class CreativeNotFoundError extends async_outcome_1.AdcpError {
+    constructor(creativeId, opts = {}) {
+        super('CREATIVE_NOT_FOUND', {
+            recovery: 'terminal',
+            message: opts.message ?? `Creative not found: ${creativeId}`,
+            field: 'creative_id',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.CreativeNotFoundError = CreativeNotFoundError;
+// Note: an `AccountNotFoundError` already exists in `./account` as a plain
+// `Error` subclass for the framework's `accounts.resolve()` path (caught
+// and translated internally). Adopters who need the wire-facing
+// `ACCOUNT_NOT_FOUND` error code throw `new AdcpError('ACCOUNT_NOT_FOUND',
+// { recovery: 'terminal', message: '...', field: 'account.id' })` directly.
+// ---------------------------------------------------------------------------
+// Resource-unavailable family — id is right but state precludes use.
+// `recovery: 'terminal'` for sold-out / unavailable; buyer needs to choose
+// something else.
+// ---------------------------------------------------------------------------
+class ProductUnavailableError extends async_outcome_1.AdcpError {
+    constructor(productId, opts = {}) {
+        super('PRODUCT_UNAVAILABLE', {
+            recovery: 'terminal',
+            message: opts.message ?? `Product unavailable (sold out / no inventory): ${productId}`,
+            field: 'product_id',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.ProductUnavailableError = ProductUnavailableError;
+class CreativeRejectedError extends async_outcome_1.AdcpError {
+    constructor(creativeId, reason, opts = {}) {
+        super('CREATIVE_REJECTED', {
+            recovery: 'terminal',
+            message: opts.message ?? `Creative ${creativeId} rejected: ${reason}`,
+            field: 'creative_id',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            details: { ...(opts.details ?? {}), reason },
+        });
+    }
+}
+exports.CreativeRejectedError = CreativeRejectedError;
+// ---------------------------------------------------------------------------
+// Budget family
+// ---------------------------------------------------------------------------
+class BudgetTooLowError extends async_outcome_1.AdcpError {
+    constructor(opts = {}) {
+        const floorStr = opts.floor != null && opts.currency != null
+            ? `Floor is ${opts.floor} ${opts.currency}.`
+            : opts.floor != null
+                ? `Floor is ${opts.floor}.`
+                : 'Budget below required floor.';
+        super('BUDGET_TOO_LOW', {
+            recovery: 'correctable',
+            message: opts.message ?? floorStr,
+            field: 'total_budget',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.floor != null && { details: { ...(opts.details ?? {}), floor: opts.floor, currency: opts.currency } }),
+        });
+    }
+}
+exports.BudgetTooLowError = BudgetTooLowError;
+class BudgetExhaustedError extends async_outcome_1.AdcpError {
+    constructor(opts = {}) {
+        super('BUDGET_EXHAUSTED', {
+            recovery: 'terminal',
+            message: opts.message ?? 'Budget exhausted.',
+            field: 'total_budget',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.BudgetExhaustedError = BudgetExhaustedError;
+// ---------------------------------------------------------------------------
+// Idempotency family
+// ---------------------------------------------------------------------------
+class IdempotencyConflictError extends async_outcome_1.AdcpError {
+    constructor(opts = {}) {
+        super('IDEMPOTENCY_CONFLICT', {
+            recovery: 'terminal',
+            message: opts.message ?? 'Same idempotency_key with different payload.',
+            field: 'idempotency_key',
+            suggestion: opts.suggestion ?? 'Use a fresh idempotency_key for the new payload.',
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.IdempotencyConflictError = IdempotencyConflictError;
+// ---------------------------------------------------------------------------
+// Validation / state family
+// ---------------------------------------------------------------------------
+class InvalidRequestError extends async_outcome_1.AdcpError {
+    constructor(field, message, opts = {}) {
+        super('INVALID_REQUEST', {
+            recovery: 'correctable',
+            message,
+            field,
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.InvalidRequestError = InvalidRequestError;
+class InvalidStateError extends async_outcome_1.AdcpError {
+    constructor(field, message, opts = {}) {
+        super('INVALID_STATE', {
+            recovery: 'terminal',
+            message,
+            field,
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.InvalidStateError = InvalidStateError;
+/**
+ * Convenience for the common `start_time >= end_time` case. Use
+ * `InvalidRequestError` for arbitrary field-level validation.
+ */
+class BackwardsTimeRangeError extends async_outcome_1.AdcpError {
+    constructor(opts = {}) {
+        super('INVALID_REQUEST', {
+            recovery: 'correctable',
+            message: opts.message ?? 'start_time must be before end_time.',
+            field: 'start_time',
+            suggestion: opts.suggestion ?? 'Verify the buyer-provided campaign window.',
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.BackwardsTimeRangeError = BackwardsTimeRangeError;
+// ---------------------------------------------------------------------------
+// Auth / permission family
+// ---------------------------------------------------------------------------
+class AuthRequiredError extends async_outcome_1.AdcpError {
+    constructor(opts = {}) {
+        super('AUTH_REQUIRED', {
+            recovery: 'terminal',
+            message: opts.message ?? 'Authentication required.',
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.AuthRequiredError = AuthRequiredError;
+class PermissionDeniedError extends async_outcome_1.AdcpError {
+    constructor(action, opts = {}) {
+        super('PERMISSION_DENIED', {
+            recovery: 'terminal',
+            message: opts.message ?? `Permission denied for ${action}.`,
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            details: { ...(opts.details ?? {}), action },
+        });
+    }
+}
+exports.PermissionDeniedError = PermissionDeniedError;
+// ---------------------------------------------------------------------------
+// Throttling / availability family
+// ---------------------------------------------------------------------------
+class RateLimitedError extends async_outcome_1.AdcpError {
+    constructor(retryAfterSeconds, opts = {}) {
+        super('RATE_LIMITED', {
+            recovery: 'transient',
+            message: opts.message ?? `Rate limited. Retry after ${retryAfterSeconds}s.`,
+            retry_after: Math.max(1, Math.min(3600, Math.floor(retryAfterSeconds))),
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.RateLimitedError = RateLimitedError;
+class ServiceUnavailableError extends async_outcome_1.AdcpError {
+    constructor(opts = {}) {
+        super('SERVICE_UNAVAILABLE', {
+            recovery: 'transient',
+            message: opts.message ?? 'Service temporarily unavailable.',
+            retry_after: opts.retryAfterSeconds != null ? Math.max(1, Math.min(3600, Math.floor(opts.retryAfterSeconds))) : 60,
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            ...(opts.details !== undefined && { details: opts.details }),
+        });
+    }
+}
+exports.ServiceUnavailableError = ServiceUnavailableError;
+class UnsupportedFeatureError extends async_outcome_1.AdcpError {
+    constructor(feature, opts = {}) {
+        super('UNSUPPORTED_FEATURE', {
+            recovery: 'terminal',
+            message: opts.message ?? `Feature not supported: ${feature}.`,
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            details: { ...(opts.details ?? {}), feature },
+        });
+    }
+}
+exports.UnsupportedFeatureError = UnsupportedFeatureError;
+// ---------------------------------------------------------------------------
+// Compliance / governance family
+// ---------------------------------------------------------------------------
+class ComplianceUnsatisfiedError extends async_outcome_1.AdcpError {
+    constructor(reason, opts = {}) {
+        super('COMPLIANCE_UNSATISFIED', {
+            recovery: 'terminal',
+            message: opts.message ?? `Compliance not satisfied: ${reason}`,
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            details: { ...(opts.details ?? {}), reason },
+        });
+    }
+}
+exports.ComplianceUnsatisfiedError = ComplianceUnsatisfiedError;
+class GovernanceDeniedError extends async_outcome_1.AdcpError {
+    constructor(reason, opts = {}) {
+        super('GOVERNANCE_DENIED', {
+            recovery: 'terminal',
+            message: opts.message ?? `Governance denied: ${reason}`,
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            details: { ...(opts.details ?? {}), reason },
+        });
+    }
+}
+exports.GovernanceDeniedError = GovernanceDeniedError;
+class PolicyViolationError extends async_outcome_1.AdcpError {
+    constructor(policy, opts = {}) {
+        super('POLICY_VIOLATION', {
+            recovery: 'terminal',
+            message: opts.message ?? `Policy violation: ${policy}`,
+            ...(opts.suggestion !== undefined && { suggestion: opts.suggestion }),
+            details: { ...(opts.details ?? {}), policy },
+        });
+    }
+}
+exports.PolicyViolationError = PolicyViolationError;
+//# sourceMappingURL=errors-typed.js.map