@adcp/sdk 5.25.0 → 6.0.0

package/dist/lib/server/decisioning/admin-router.js

@@ -0,0 +1,120 @@
+"use strict";
+/**
+ * Admin Express router for the v6.0 TenantRegistry.
+ *
+ * Mounted on a separate port / path from the public agent endpoint so
+ * tenant traffic and ops surface stay independent. Adopters wire it
+ * behind their existing auth (basic auth, mTLS, OAuth introspection):
+ *
+ * ```ts
+ * import express from 'express';
+ * import { createTenantAdminRouter } from '@adcp/sdk/server/decisioning';
+ *
+ * const adminApp = express();
+ * adminApp.use('/admin', requireOpsAuth, createTenantAdminRouter(registry));
+ * adminApp.listen(9090);
+ * ```
+ *
+ * Endpoints:
+ *
+ *   - `GET    /tenants`              — list all tenants with health status
+ *   - `GET    /tenants/:id`          — single tenant status (404 if unknown)
+ *   - `POST   /tenants/:id/recheck`  — force JWKS revalidation (returns new status)
+ *   - `DELETE /tenants/:id`          — unregister (idempotent; 204 either way)
+ *
+ * All responses are JSON. Missing tenants return 404 + `{ error: 'tenant_not_found' }`.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTenantAdminHandlers = createTenantAdminHandlers;
+exports.mountTenantAdmin = mountTenantAdmin;
+exports.createTenantAdminRouter = createTenantAdminRouter;
+/**
+ * Bare handlers — for adopters running a non-Express framework. The router
+ * helper below mounts these on the standard paths.
+ */
+function createTenantAdminHandlers(registry) {
+    return {
+        listTenants(_req, res) {
+            res.json({ tenants: registry.list() });
+        },
+        getTenant(req, res) {
+            const id = req.params.id;
+            if (!id) {
+                res.status(400).json({ error: 'tenant_id_required' });
+                return;
+            }
+            const status = registry.getStatus(id);
+            if (!status) {
+                res.status(404).json({ error: 'tenant_not_found', tenant_id: id });
+                return;
+            }
+            res.json(status);
+        },
+        async recheckTenant(req, res) {
+            const id = req.params.id;
+            if (!id) {
+                res.status(400).json({ error: 'tenant_id_required' });
+                return;
+            }
+            try {
+                const status = await registry.recheck(id);
+                res.json(status);
+            }
+            catch (err) {
+                if (err instanceof Error && /not registered/.test(err.message)) {
+                    res.status(404).json({ error: 'tenant_not_found', tenant_id: id });
+                    return;
+                }
+                res.status(500).json({
+                    error: 'recheck_failed',
+                    tenant_id: id,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+            }
+        },
+        unregisterTenant(req, res) {
+            const id = req.params.id;
+            if (!id) {
+                res.status(400).json({ error: 'tenant_id_required' });
+                return;
+            }
+            registry.unregister(id);
+            res.status(204).end();
+        },
+    };
+}
+/**
+ * Build an Express router with the standard admin endpoints mounted.
+ * Pass an `express.Router()` instance to mount on (so we don't need an
+ * Express dependency in this file).
+ */
+function mountTenantAdmin(router, registry) {
+    const handlers = createTenantAdminHandlers(registry);
+    router.get('/tenants', handlers.listTenants);
+    router.get('/tenants/:id', handlers.getTenant);
+    router.post('/tenants/:id/recheck', handlers.recheckTenant);
+    router.delete('/tenants/:id', handlers.unregisterTenant);
+    return router;
+}
+/**
+ * Convenience: takes an `express` import and a registry, returns a
+ * mounted `Router` ready to attach. Usage:
+ *
+ * ```ts
+ * import express from 'express';
+ * import { createTenantAdminRouter } from '@adcp/sdk/server/decisioning';
+ * adminApp.use('/admin', createTenantAdminRouter(express.Router(), registry));
+ * ```
+ *
+ * The `routerFactory` argument lets adopters pre-configure middleware
+ * (auth, logging) on the router before passing it in.
+ */
+function createTenantAdminRouter(routerFactory, registry) {
+    mountTenantAdmin(routerFactory, registry);
+    return routerFactory;
+}
+//# sourceMappingURL=admin-router.js.map

package/dist/lib/server/decisioning/admin-router.js.map

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

package/dist/lib/server/decisioning/assembly-helpers.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Wire-shape assembly helpers.
+ *
+ * AdCP wire shapes carry many required fields (Product needs 8 required
+ * properties; PricingOption needs at least 3 plus model-specific extras).
+ * Building them by hand is the largest single source of validation
+ * cascades in LLM-generated platforms (Emma matrix v18: a single missed
+ * `format_ids[0].id` shape error swallowed 30+ storyboard steps).
+ *
+ * These helpers emit correct wire shapes from a flatter, intent-shaped
+ * input. Adopters opt in — anything you don't pass in gets a sensible
+ * default; anything required gets a clear TS error if you omit it.
+ *
+ * @public
+ */
+import type { Product, PricingOption, ReportingCapabilities } from '../../types/tools.generated';
+export interface BuildProductInput {
+    /** Unique product id. */
+    id: string;
+    /** Human-readable name surfaced to buyers. */
+    name: string;
+    /** Description surfaced to buyers. Defaults to `name`. */
+    description?: string;
+    /**
+     * Format ids accepted on creatives bound to this product.
+     *
+     * Pass either:
+     *   - Array of strings → SDK wraps each as `{ id, agent_url }` using the
+     *     `agentUrl` you pass alongside (required for string-form formats —
+     *     wire schema requires `agent_url` per AdCP 3.0.1)
+     *   - Array of `{ id, agent_url }` for cross-agent format references
+     *     (each entry carries its own agent_url)
+     */
+    formats: ReadonlyArray<string | {
+        id: string;
+        agent_url?: string;
+    }>;
+    /**
+     * Your agent's URL (e.g., `'http://127.0.0.1:4200/mcp'` in tests, your
+     * production MCP endpoint live). Required when any entry in `formats` is
+     * a bare string (so the helper can build `{ id, agent_url }`). Ignored
+     * when every entry is `{ id, agent_url }`.
+     *
+     * Per AdCP 3.0.1, `format_ids[i].agent_url` is required on the wire shape
+     * — every format reference must point at the agent that defines that
+     * format. Pass once per `buildProduct` call and the helper threads it
+     * into each format ref.
+     */
+    agentUrl?: string;
+    /** `'guaranteed'` (reserved inventory) or `'non_guaranteed'` (auction / remnant). */
+    delivery_type: 'guaranteed' | 'non_guaranteed';
+    /**
+     * One or more pricing options. Pass strings for "default CPM with floor"
+     * convenience, or full `PricingOption` objects for fine-grained control.
+     *
+     * Convenience shortcut: `pricing: { model: 'cpm', floor: 5, currency: 'USD' }`
+     * builds a single CPM auction pricing option with the given floor.
+     */
+    pricing?: {
+        model: 'cpm' | 'vcpm' | 'cpc' | 'cpcv' | 'cpv' | 'cpp' | 'cpa' | 'flat_rate' | 'time';
+        floor?: number;
+        fixed?: number;
+        currency?: string;
+        pricing_option_id?: string;
+    } | ReadonlyArray<PricingOption>;
+    /**
+     * Shortcut for the common single-publisher case: pass the domain (e.g.,
+     * `'sports.example'`) and the helper builds `publisher_properties: [{
+     * publisher_domain: '<domain>', selection_type: 'all' }]`.
+     *
+     * Use `publisher_properties` directly for multi-domain or by-id / by-tag
+     * selection.
+     */
+    publisher_domain?: string;
+    /**
+     * Publisher properties this product covers. Required (per AdCP 3.0.1
+     * product schema) — pass `publisher_domain` for the common single-domain
+     * shortcut, OR pass this directly for fine-grained selection.
+     *
+     * Each entry is a discriminated union by `selection_type`:
+     *   - `'all'` — select all properties at the publisher_domain
+     *   - `'by_id'` — select specific property_ids[]
+     *   - `'by_tag'` — select by property_tags[]
+     */
+    publisher_properties?: ReadonlyArray<{
+        publisher_domain: string;
+        selection_type: 'all';
+    } | {
+        publisher_domain: string;
+        selection_type: 'by_id';
+        property_ids: ReadonlyArray<{
+            property_type: string;
+            identifier: string;
+            [k: string]: unknown;
+        }>;
+    } | {
+        publisher_domain: string;
+        selection_type: 'by_tag';
+        property_tags: ReadonlyArray<string>;
+    }>;
+    /** Reporting capabilities. Defaults to hourly+daily impressions/spend/clicks. */
+    reporting_capabilities?: ReportingCapabilities;
+    /** Channels this product targets (`'display'`, `'video'`, etc.). */
+    channels?: ReadonlyArray<string>;
+    /** Adapter-internal opaque blob round-tripped by the SDK. */
+    ctx_metadata?: unknown;
+    /** Anything else on the wire shape (escape hatch). */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Build a wire-correct `Product` from intent-shaped input. Required fields
+ * (per AdCP 3.0.1 product.json) are filled in with sensible defaults when
+ * omitted; the caller can override any of them.
+ *
+ * @example Catalog product (minimal)
+ * ```ts
+ * const product = buildProduct({
+ *   id: 'sports_display_auction',
+ *   name: 'Sports Display Auction',
+ *   formats: ['display_300x250', 'display_728x90'],
+ *   delivery_type: 'non_guaranteed',
+ *   pricing: { model: 'cpm', floor: 5.0, currency: 'USD' },
+ *   ctx_metadata: { gam: { ad_unit_ids: ['au_123'] } },
+ * });
+ * ```
+ *
+ * @example Multi-pricing-option product
+ * ```ts
+ * const product = buildProduct({
+ *   id: 'premium_homepage',
+ *   name: 'Premium Homepage Takeover',
+ *   formats: [{ id: 'display_970x250' }],
+ *   delivery_type: 'guaranteed',
+ *   pricing: [
+ *     buildPricingOption({ id: 'po_cpm', model: 'cpm', fixed: 25.0, currency: 'USD' }),
+ *     buildPricingOption({ id: 'po_flat', model: 'flat_rate', fixed: 50000, currency: 'USD' }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function buildProduct(input: BuildProductInput): Product;
+export interface BuildPricingOptionInput {
+    /** Pricing option id, unique within the product. Defaults to `${model}_${floor||fixed||'default'}`. */
+    id?: string;
+    /** Pricing model. */
+    model: 'cpm' | 'vcpm' | 'cpc' | 'cpcv' | 'cpv' | 'cpp' | 'cpa' | 'flat_rate' | 'time';
+    /** Fixed price per unit. Mutually exclusive with `floor`. */
+    fixed?: number;
+    /** Auction floor price. Mutually exclusive with `fixed`. */
+    floor?: number;
+    /** ISO 4217 currency code (e.g., `'USD'`, `'EUR'`). Defaults to `'USD'`. */
+    currency?: string;
+    /** Minimum spend requirement per package using this pricing option. */
+    min_spend_per_package?: number;
+}
+/**
+ * Build a wire-correct `PricingOption` from intent-shaped input. Use the
+ * shortcut on `buildProduct({ pricing })` for the common case; call
+ * `buildPricingOption` directly when you need multiple options on a product.
+ *
+ * @example
+ * ```ts
+ * const cpm = buildPricingOption({ model: 'cpm', floor: 5.0, currency: 'USD' });
+ * const flat = buildPricingOption({ id: 'po_flat', model: 'flat_rate', fixed: 50000, currency: 'USD' });
+ * ```
+ */
+export declare function buildPricingOption(input: BuildPricingOptionInput): PricingOption;
+export interface BuildPackageInput {
+    id: string;
+    /** Buyer-supplied client-side reference (echoed from the request). */
+    buyer_ref?: string;
+    /** AdCP package status. Defaults to `'pending_creatives'` (just-created buys). */
+    status?: 'draft' | 'pending_creatives' | 'pending_start' | 'active' | 'paused' | 'completed' | 'canceled' | 'rejected';
+    /** product_id this package was bound to. */
+    product_id?: string;
+    /** pricing_option_id selected for this package. */
+    pricing_option_id?: string;
+    /** Adapter-internal opaque blob round-tripped by the SDK. */
+    ctx_metadata?: unknown;
+    /** Anything else on the wire shape. */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Build a wire-correct package shape for a media buy response.
+ *
+ * @example
+ * ```ts
+ * createMediaBuy: async (req, ctx) => {
+ *   const order = await this.gam.createOrder(req);
+ *   return {
+ *     media_buy_id: order.id,
+ *     status: 'pending_creatives',
+ *     packages: order.lineItems.map(li => buildPackage({
+ *       id: li.id,
+ *       buyer_ref: li.buyerRef,
+ *       status: 'pending_creatives',
+ *       ctx_metadata: { gam_line_item_id: li.gamLineItemId },
+ *     })),
+ *   };
+ * }
+ * ```
+ */
+export declare function buildPackage(input: BuildPackageInput): Record<string, unknown>;
+//# sourceMappingURL=assembly-helpers.d.ts.map

package/dist/lib/server/decisioning/assembly-helpers.d.ts.map

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

package/dist/lib/server/decisioning/assembly-helpers.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Wire-shape assembly helpers.
+ *
+ * AdCP wire shapes carry many required fields (Product needs 8 required
+ * properties; PricingOption needs at least 3 plus model-specific extras).
+ * Building them by hand is the largest single source of validation
+ * cascades in LLM-generated platforms (Emma matrix v18: a single missed
+ * `format_ids[0].id` shape error swallowed 30+ storyboard steps).
+ *
+ * These helpers emit correct wire shapes from a flatter, intent-shaped
+ * input. Adopters opt in — anything you don't pass in gets a sensible
+ * default; anything required gets a clear TS error if you omit it.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildProduct = buildProduct;
+exports.buildPricingOption = buildPricingOption;
+exports.buildPackage = buildPackage;
+const DEFAULT_REPORTING_CAPABILITIES = {
+    available_reporting_frequencies: ['hourly', 'daily'],
+    expected_delay_minutes: 60,
+    timezone: 'UTC',
+    supports_webhooks: false,
+    available_metrics: ['impressions', 'spend', 'clicks'],
+    date_range_support: 'date_range',
+};
+function resolvePublisherProperties(input) {
+    if (input.publisher_properties && input.publisher_properties.length > 0) {
+        return input.publisher_properties;
+    }
+    if (input.publisher_domain) {
+        return [{ publisher_domain: input.publisher_domain, selection_type: 'all' }];
+    }
+    throw new Error(`buildProduct: ${input.id} requires either \`publisher_domain\` (single-publisher shortcut) ` +
+        `or \`publisher_properties\` (multi-domain / by-id / by-tag selection). The wire schema requires ` +
+        `at least one publisher_property entry per product.`);
+}
+/**
+ * Build a wire-correct `Product` from intent-shaped input. Required fields
+ * (per AdCP 3.0.1 product.json) are filled in with sensible defaults when
+ * omitted; the caller can override any of them.
+ *
+ * @example Catalog product (minimal)
+ * ```ts
+ * const product = buildProduct({
+ *   id: 'sports_display_auction',
+ *   name: 'Sports Display Auction',
+ *   formats: ['display_300x250', 'display_728x90'],
+ *   delivery_type: 'non_guaranteed',
+ *   pricing: { model: 'cpm', floor: 5.0, currency: 'USD' },
+ *   ctx_metadata: { gam: { ad_unit_ids: ['au_123'] } },
+ * });
+ * ```
+ *
+ * @example Multi-pricing-option product
+ * ```ts
+ * const product = buildProduct({
+ *   id: 'premium_homepage',
+ *   name: 'Premium Homepage Takeover',
+ *   formats: [{ id: 'display_970x250' }],
+ *   delivery_type: 'guaranteed',
+ *   pricing: [
+ *     buildPricingOption({ id: 'po_cpm', model: 'cpm', fixed: 25.0, currency: 'USD' }),
+ *     buildPricingOption({ id: 'po_flat', model: 'flat_rate', fixed: 50000, currency: 'USD' }),
+ *   ],
+ * });
+ * ```
+ */
+function buildProduct(input) {
+    const formats = input.formats.map(f => {
+        if (typeof f === 'string') {
+            if (!input.agentUrl) {
+                throw new Error(`buildProduct: ${input.id} declares format '${f}' as a bare string, but \`agentUrl\` is required ` +
+                    `to build the wire \`{ id, agent_url }\` shape. Pass \`agentUrl\` on the input, OR pass each format ` +
+                    `as \`{ id, agent_url }\` directly.`);
+            }
+            return { id: f, agent_url: input.agentUrl };
+        }
+        if (f.agent_url)
+            return f;
+        if (input.agentUrl)
+            return { ...f, agent_url: input.agentUrl };
+        throw new Error(`buildProduct: ${input.id} format '${f.id}' has no agent_url and no \`agentUrl\` was passed on the input.`);
+    });
+    let pricing_options;
+    if (Array.isArray(input.pricing)) {
+        pricing_options = [...input.pricing];
+    }
+    else if (input.pricing) {
+        // Narrow: not an array, so it's the BuildPricingOptionInput shorthand object.
+        pricing_options = [buildPricingOption(input.pricing)];
+    }
+    else {
+        // No pricing supplied — emit a single CPM placeholder so the wire shape
+        // validates. Adopters who skip pricing usually don't realize it's required.
+        pricing_options = [buildPricingOption({ model: 'cpm', floor: 0.01, currency: 'USD' })];
+    }
+    const product = {
+        product_id: input.id,
+        name: input.name,
+        description: input.description ?? input.name,
+        publisher_properties: resolvePublisherProperties(input),
+        format_ids: formats,
+        delivery_type: input.delivery_type,
+        pricing_options,
+        reporting_capabilities: input.reporting_capabilities ?? DEFAULT_REPORTING_CAPABILITIES,
+        ...(input.channels && input.channels.length > 0 && { channels: [...input.channels] }),
+        ...(input.ctx_metadata !== undefined && { ctx_metadata: input.ctx_metadata }),
+        ...(input.extra ?? {}),
+    };
+    return product;
+}
+/**
+ * Build a wire-correct `PricingOption` from intent-shaped input. Use the
+ * shortcut on `buildProduct({ pricing })` for the common case; call
+ * `buildPricingOption` directly when you need multiple options on a product.
+ *
+ * @example
+ * ```ts
+ * const cpm = buildPricingOption({ model: 'cpm', floor: 5.0, currency: 'USD' });
+ * const flat = buildPricingOption({ id: 'po_flat', model: 'flat_rate', fixed: 50000, currency: 'USD' });
+ * ```
+ */
+function buildPricingOption(input) {
+    if (input.fixed !== undefined && input.floor !== undefined) {
+        throw new Error('buildPricingOption: `fixed` and `floor` are mutually exclusive (CPM/etc. is either fixed-price or auction).');
+    }
+    const currency = input.currency ?? 'USD';
+    const idHint = input.fixed != null ? `fixed_${input.fixed}` : input.floor != null ? `floor_${input.floor}` : 'default';
+    const opt = {
+        pricing_option_id: input.id ?? `${input.model}_${idHint}`,
+        pricing_model: input.model,
+        currency,
+        ...(input.fixed !== undefined && { fixed_price: input.fixed }),
+        ...(input.floor !== undefined && { floor_price: input.floor }),
+        ...(input.min_spend_per_package !== undefined && { min_spend_per_package: input.min_spend_per_package }),
+    };
+    return opt;
+}
+/**
+ * Build a wire-correct package shape for a media buy response.
+ *
+ * @example
+ * ```ts
+ * createMediaBuy: async (req, ctx) => {
+ *   const order = await this.gam.createOrder(req);
+ *   return {
+ *     media_buy_id: order.id,
+ *     status: 'pending_creatives',
+ *     packages: order.lineItems.map(li => buildPackage({
+ *       id: li.id,
+ *       buyer_ref: li.buyerRef,
+ *       status: 'pending_creatives',
+ *       ctx_metadata: { gam_line_item_id: li.gamLineItemId },
+ *     })),
+ *   };
+ * }
+ * ```
+ */
+function buildPackage(input) {
+    return {
+        package_id: input.id,
+        status: input.status ?? 'pending_creatives',
+        ...(input.buyer_ref !== undefined && { buyer_ref: input.buyer_ref }),
+        ...(input.product_id !== undefined && { product_id: input.product_id }),
+        ...(input.pricing_option_id !== undefined && { pricing_option_id: input.pricing_option_id }),
+        ...(input.ctx_metadata !== undefined && { ctx_metadata: input.ctx_metadata }),
+        ...(input.extra ?? {}),
+    };
+}
+//# sourceMappingURL=assembly-helpers.js.map

package/dist/lib/server/decisioning/assembly-helpers.js.map

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

package/dist/lib/server/decisioning/async-outcome.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Error vocabulary + structured error class for `DecisioningPlatform`.
+ *
+ * Adopters write per-tool methods (sync OR `*Task` HITL variant), return
+ * the success value, or `throw new AdcpError(...)` for structured rejection.
+ * The framework projects the structured fields onto the wire `adcp_error`
+ * envelope; generic thrown errors map to `SERVICE_UNAVAILABLE`.
+ *
+ * `AsyncOutcome<T>` and the `ok` / `submitted` / `rejected` constructors
+ * remain as the framework's internal projection vocabulary; adopter code
+ * doesn't return them.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+/**
+ * Error code vocabulary mirroring `schemas/cache/3.0.0/enums/error-code.json`
+ * (45 standard codes). Adopters can return platform-specific codes too —
+ * agents fall back to the `recovery` classification on unknowns via the
+ * `(string & {})` escape hatch on `AdcpStructuredError.code`.
+ *
+ * TODO(6.0): generate this from `schemas/cache/<version>/enums/error-code.json`
+ * via the same codegen pipeline as the rest of `tools.generated.ts`.
+ */
+export declare const KNOWN_ERROR_CODES: readonly ["INVALID_REQUEST", "AUTH_REQUIRED", "RATE_LIMITED", "SERVICE_UNAVAILABLE", "POLICY_VIOLATION", "PRODUCT_NOT_FOUND", "PRODUCT_UNAVAILABLE", "PRODUCT_EXPIRED", "PROPOSAL_EXPIRED", "PROPOSAL_NOT_COMMITTED", "BUDGET_TOO_LOW", "BUDGET_EXHAUSTED", "BUDGET_EXCEEDED", "CREATIVE_REJECTED", "CREATIVE_DEADLINE_EXCEEDED", "CREATIVE_NOT_FOUND", "UNSUPPORTED_FEATURE", "AUDIENCE_TOO_SMALL", "ACCOUNT_NOT_FOUND", "ACCOUNT_SETUP_REQUIRED", "ACCOUNT_AMBIGUOUS", "ACCOUNT_PAYMENT_REQUIRED", "ACCOUNT_SUSPENDED", "COMPLIANCE_UNSATISFIED", "GOVERNANCE_DENIED", "GOVERNANCE_UNAVAILABLE", "CAMPAIGN_SUSPENDED", "CONFLICT", "IDEMPOTENCY_CONFLICT", "IDEMPOTENCY_EXPIRED", "INVALID_STATE", "IO_REQUIRED", "MEDIA_BUY_NOT_FOUND", "NOT_CANCELLABLE", "PACKAGE_NOT_FOUND", "PERMISSION_DENIED", "PLAN_NOT_FOUND", "REFERENCE_NOT_FOUND", "REQUOTE_REQUIRED", "SESSION_NOT_FOUND", "SESSION_TERMINATED", "SIGNAL_NOT_FOUND", "TERMS_REJECTED", "VALIDATION_ERROR", "VERSION_UNSUPPORTED"];
+export type ErrorCode = (typeof KNOWN_ERROR_CODES)[number];
+/**
+ * Structured error envelope. Mirrors `schemas/cache/3.0.0/core/error.json`.
+ *
+ * `recovery` is REQUIRED at this interface level. The wire schema makes it
+ * optional; we tighten because every adopter needs to declare buyer-recovery
+ * intent on every rejection — implicit "terminal" by absence has historically
+ * caused buyers to misroute retries.
+ *
+ * Adopter code throws `AdcpError` (the class wrapper); the framework catches
+ * and projects the structured fields onto the wire envelope.
+ */
+export interface AdcpStructuredError {
+    code: ErrorCode | (string & {});
+    recovery: 'transient' | 'correctable' | 'terminal';
+    message: string;
+    /** Field path associated with the error (e.g., `'packages[0].targeting'`). */
+    field?: string;
+    /** Suggested fix surfaced to the buyer. */
+    suggestion?: string;
+    /**
+     * Seconds to wait before retrying. REQUIRED by the spec for `RATE_LIMITED`
+     * and `SERVICE_UNAVAILABLE`; framework auto-fills if omitted.
+     * Adopters MUST clamp to [1, 3600] per spec.
+     */
+    retry_after?: number;
+    details?: Record<string, unknown>;
+}
+/**
+ * Throwable structured error. Adopter code throws this to fail a specialism
+ * method with a buyer-facing wire envelope.
+ *
+ * ```ts
+ * createMediaBuy: async (req, ctx) => {
+ *   if (req.total_budget.amount < this.floor) {
+ *     throw new AdcpError('BUDGET_TOO_LOW', {
+ *       recovery: 'correctable',
+ *       message: `Floor is $${this.floor} CPM`,
+ *       field: 'total_budget.amount',
+ *     });
+ *   }
+ *   return await this.gam.createOrder(req);
+ * }
+ * ```
+ *
+ * Framework catches `AdcpError` from any specialism method and projects
+ * the structured fields onto the wire `adcp_error` envelope.
+ * Generic thrown errors map to `SERVICE_UNAVAILABLE` with `recovery: 'transient'`.
+ */
+export declare class AdcpError extends Error {
+    readonly name: "AdcpError";
+    readonly code: ErrorCode | (string & {});
+    readonly recovery: 'transient' | 'correctable' | 'terminal';
+    readonly field?: string;
+    readonly suggestion?: string;
+    readonly retry_after?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(code: ErrorCode | (string & {}), options: {
+        recovery: 'transient' | 'correctable' | 'terminal';
+        message: string;
+        field?: string;
+        suggestion?: string;
+        retry_after?: number;
+        details?: Record<string, unknown>;
+    });
+    /** Coerce to the structured envelope shape the framework projects to the wire. */
+    toStructuredError(): AdcpStructuredError;
+    /**
+     * Override `Error.toString` so default `console.error(err)` /
+     * CloudWatch / structured-log adopters see the `code` and `recovery`
+     * alongside the message rather than the bare `AdcpError: <message>`
+     * default. Triage in operator dashboards needs the code more than
+     * the stack.
+     */
+    toString(): string;
+}
+/**
+ * Brand value framework checks at the dispatch seam to detect "this method
+ * is handing off to a task." Module-level constant so adopters can't construct
+ * one without going through `ctx.handoffToTask(fn)`.
+ */
+declare const TASK_HANDOFF_BRAND: unique symbol;
+/**
+ * Marker the framework recognizes as "promote this call to a task."
+ * Returned from `ctx.handoffToTask(fn)`. Type parameter `TResult` is the
+ * eventual terminal artifact `fn` resolves to.
+ *
+ * Adopters never construct this directly — `ctx.handoffToTask(fn)` is the
+ * only sanctioned producer. The framework's dispatch layer detects the
+ * brand, allocates a `task_id`, returns the spec-defined `Submitted`
+ * envelope to the buyer, and runs `fn` in the background. `fn`'s return
+ * value becomes the task's terminal artifact; `throw AdcpError` becomes
+ * the terminal error.
+ *
+ * The opaque `_taskFn` field exists only at the type level — at runtime
+ * the function is stored in a module-private WeakMap keyed by the
+ * marker, so adopters who try to invoke `handoff._taskFn(ctx)` directly
+ * get `undefined`. The only way to run the handoff body is to return
+ * the marker from a specialism method and let the framework dispatch.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+export interface TaskHandoff<TResult> {
+    readonly [TASK_HANDOFF_BRAND]: true;
+}
+/**
+ * Context the framework supplies to the handoff function. Mirrors
+ * `RequestContext.task` from the deprecated `*Task` shape — `id` is the
+ * framework-issued task id, `update`/`heartbeat` are the same affordances.
+ *
+ * @public
+ */
+export interface TaskHandoffContext {
+    readonly id: string;
+    update(progress: TaskHandoffProgress): Promise<void>;
+    heartbeat(): Promise<void>;
+}
+export interface TaskHandoffProgress {
+    message?: string;
+    percentage?: number;
+    step_number?: number;
+    total_steps?: number;
+    current_step?: string;
+}
+export {};
+//# sourceMappingURL=async-outcome.d.ts.map