@adcp/sdk 5.25.0 → 6.0.0

package/dist/lib/server/ctx-metadata/wire-shape.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * Compile-time + runtime defense against `ctx_metadata` leaking into
+ * buyer-facing wire payloads.
+ *
+ * - **Compile-time:** `WireShape<T>` strips `ctx_metadata` from a type
+ *   tree, so the framework's response builder return types refuse a
+ *   payload that carries it.
+ * - **Runtime:** `stripCtxMetadata(value)` shape-aware shallow walk
+ *   over known carrier locations (response root + `packages[]` +
+ *   `creatives[]` + `audiences[]` + `signals[]` + `media_buys[]` +
+ *   `products[]`). Catches custom-handler escape hatches and HITL
+ *   task return values that re-introduce the field at runtime.
+ *
+ * Single chokepoint at the dispatcher seam. Strip runs *before* the
+ * idempotency cache write so cached replays don't leak.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripCtxMetadata = stripCtxMetadata;
+exports.hasCtxMetadata = hasCtxMetadata;
+const CTX_METADATA_KEY = 'ctx_metadata';
+/**
+ * Runtime strip. Walks known carrier shapes in the response and
+ * deletes `ctx_metadata` keys. Returns the input value (mutates in
+ * place — the dispatcher constructs a fresh response per call, so
+ * mutation is safe).
+ *
+ * **Why shape-aware shallow walk, not full recursion.** Full
+ * recursion is O(response size) and risks stripping a field a
+ * future spec adds with the same name elsewhere (e.g., a diagnostic
+ * envelope's `ctx_metadata`). Shape-aware walks the carrier
+ * locations defined by AdCP 3.0 — adding a new carrier requires
+ * updating this list, which is the right kind of friction.
+ */
+function stripCtxMetadata(value) {
+    if (value == null || typeof value !== 'object')
+        return value;
+    stripFromCarrier(value);
+    return value;
+}
+/**
+ * Carrier locations: keys whose values may be objects or arrays of
+ * objects that carry `ctx_metadata`. Add new keys here when a future
+ * spec extends the wire-resource surface.
+ */
+const CARRIER_KEYS = [
+    'account',
+    'accounts',
+    'media_buy',
+    'media_buys',
+    'package',
+    'packages',
+    'product',
+    'products',
+    'creative',
+    'creatives',
+    'audience',
+    'audiences',
+    'signal',
+    'signals',
+    'rights_grant',
+    'rights_grants',
+    'property_list',
+    'property_lists',
+    'collection_list',
+    'collection_lists',
+    'asset',
+    'assets',
+];
+function stripFromCarrier(obj) {
+    if (CTX_METADATA_KEY in obj)
+        delete obj[CTX_METADATA_KEY];
+    for (const key of CARRIER_KEYS) {
+        const nested = obj[key];
+        if (nested == null)
+            continue;
+        if (Array.isArray(nested)) {
+            for (const item of nested) {
+                if (item != null && typeof item === 'object')
+                    stripFromCarrier(item);
+            }
+        }
+        else if (typeof nested === 'object') {
+            stripFromCarrier(nested);
+        }
+    }
+}
+/**
+ * Detect whether a payload contains `ctx_metadata` at any walked
+ * carrier location. Used by the test suite to assert wire payloads
+ * are clean — production code paths just call `stripCtxMetadata`.
+ */
+function hasCtxMetadata(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    return walkForCtxMetadata(value);
+}
+function walkForCtxMetadata(obj) {
+    if (CTX_METADATA_KEY in obj)
+        return true;
+    for (const key of CARRIER_KEYS) {
+        const nested = obj[key];
+        if (nested == null)
+            continue;
+        if (Array.isArray(nested)) {
+            for (const item of nested) {
+                if (item != null && typeof item === 'object' && walkForCtxMetadata(item)) {
+                    return true;
+                }
+            }
+        }
+        else if (typeof nested === 'object') {
+            if (walkForCtxMetadata(nested))
+                return true;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=wire-shape.js.map

package/dist/lib/server/ctx-metadata/wire-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-shape.js","sourceRoot":"","sources":["../../../../src/lib/server/ctx-metadata/wire-shape.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;AAqCH,4CAIC;AAoDD,wCAGC;AA9FD,MAAM,gBAAgB,GAAG,cAAuB,CAAC;AAsBjD;;;;;;;;;;;;GAYG;AACH,SAAgB,gBAAgB,CAAI,KAAQ;IAC1C,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAqB,CAAC;IAC7E,gBAAgB,CAAC,KAAgC,CAAC,CAAC;IACnD,OAAO,KAAqB,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,YAAY,GAAG;IACnB,SAAS;IACT,UAAU;IACV,WAAW;IACX,YAAY;IACZ,SAAS;IACT,UAAU;IACV,SAAS;IACT,UAAU;IACV,UAAU;IACV,WAAW;IACX,UAAU;IACV,WAAW;IACX,QAAQ;IACR,SAAS;IACT,cAAc;IACd,eAAe;IACf,eAAe;IACf,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,OAAO;IACP,QAAQ;CACA,CAAC;AAEX,SAAS,gBAAgB,CAAC,GAA4B;IACpD,IAAI,gBAAgB,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC1D,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,MAAM,IAAI,IAAI;YAAE,SAAS;QAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;gBAC1B,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;oBAAE,gBAAgB,CAAC,IAA+B,CAAC,CAAC;YAClG,CAAC;QACH,CAAC;aAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACtC,gBAAgB,CAAC,MAAiC,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,KAAc;IAC3C,IAAI,KAAK,IAAI,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC7D,OAAO,kBAAkB,CAAC,KAAgC,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,kBAAkB,CAAC,GAA4B;IACtD,IAAI,gBAAgB,IAAI,GAAG;QAAE,OAAO,IAAI,CAAC;IACzC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,MAAM,IAAI,IAAI;YAAE,SAAS;QAC7B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;gBAC1B,IAAI,IAAI,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,kBAAkB,CAAC,IAA+B,CAAC,EAAE,CAAC;oBACpG,OAAO,IAAI,CAAC;gBACd,CAAC;YACH,CAAC;QACH,CAAC;aAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YACtC,IAAI,kBAAkB,CAAC,MAAiC,CAAC;gBAAE,OAAO,IAAI,CAAC;QACzE,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

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

@@ -0,0 +1,309 @@
+/**
+ * Account model. Single-level (matches AdCP wire's AccountReference).
+ * Platform-internal hierarchies (GAM Network → Advertiser → Order;
+ * Spotify Brand → Campaign) are encoded in `metadata`, not in the typed
+ * shape. Generic `TCtxMeta` lets platforms type their metadata at the call site.
+ *
+ * Tenant isolation is enforced at `accounts.resolve()` returning null for
+ * cross-scope references, not via a multi-level type.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+import type { BrandReference, AccountReference, ReportUsageRequest, ReportUsageResponse, GetAccountFinancialsRequest, GetAccountFinancialsSuccess } from '../../types/tools.generated';
+import type { CursorPage, CursorRequest } from './pagination';
+/**
+ * Account — framework's rich representation. A strict superset of the wire
+ * `Account` shape (from `list_accounts` / response envelopes):
+ *
+ *   - Adds `metadata: TCtxMeta` (platform-internal fields the framework doesn't
+ *     read but adopters use to thread platform-specific data)
+ *   - Adds `authInfo: AuthPrincipal` (auth context for the request — MUST NOT
+ *     leak to the wire)
+ *   - All wire-required fields (`id`/`account_id`, `name`, `status`) are
+ *     required here too.
+ *
+ * Framework projects to wire shape via `toWireAccount`: strips `metadata` +
+ * `authInfo`, renames `id` → `account_id`. ~10 lines, no `as never` casts.
+ */
+export interface Account<TCtxMeta = Record<string, unknown>> {
+    /** Your platform's account_id. Maps to wire `Account.account_id`. */
+    id: string;
+    /** Human-readable account name (e.g., 'Acme', 'Acme c/o Pinnacle'). Required on the wire. */
+    name: string;
+    /** Account status. Maps to wire `Account.status`. */
+    status: AdcpAccountStatus;
+    /** Canonical brand reference. Either id OR (brand+operator) identifies the account. */
+    brand?: BrandReference;
+    /** Operator domain (agency / managed-services). Pairs with `brand`. */
+    operator?: string;
+    /**
+     * The advertiser whose rates apply to this account. Maps to wire
+     * `Account.advertiser`. Use when the account is operated by an agency on
+     * behalf of an advertiser whose rates differ from the operator's.
+     */
+    advertiser?: string;
+    /**
+     * Settlement boundary for operator-billed retail-media platforms.
+     * `'agent'` = pass-through (buyer's agent settles directly with the platform).
+     * `'operator'` = retail-media model (operator pays publisher, bills brand).
+     * `BrandReference` = invoice routes to a third party (Amazon DSP returning
+     * a different invoice principal than the requester is the canonical case).
+     *
+     * Optional — most platforms don't need this; comply storyboards use it to
+     * assert the right party is billed.
+     */
+    billing?: {
+        invoicedTo: 'agent' | 'operator' | BrandReference;
+    };
+    /**
+     * Adapter-internal opaque state. Framework doesn't read this; **stripped
+     * before emitting on the wire**. GAM puts `{ networkId, advertiserId }`;
+     * Spotify puts `{ brandId, businessId }`; Criteo puts `{ customerId }`.
+     * Each platform's choice.
+     *
+     * Same field name (`ctx_metadata`) used across every DecisioningPlatform
+     * resource (Product, MediaBuy, Package, Creative, Audience, Signal,
+     * Account) for naming consistency. Account is special operationally:
+     * `accounts.resolve()` is called per-request, so the publisher is the
+     * canonical source of truth and the SDK does NOT round-trip Account
+     * `ctx_metadata` through the cache (unlike Product / MediaBuy / etc.,
+     * where the SDK bridges between `getProducts` and `createMediaBuy`).
+     * Put adapter state in `ctx_metadata`; treat it as fresh from your
+     * `accounts.resolve()` on every request.
+     */
+    ctx_metadata: TCtxMeta;
+    /** Caller's authenticated principal. **Stripped before emitting on the wire.** */
+    authInfo: AuthPrincipal;
+}
+/**
+ * Request context passed to `AccountStore.resolve()` so adopters fronting
+ * an upstream platform API can translate the auth principal into their
+ * tenant model on resolution. Mirrors `ResolveAccountContext` on the
+ * underlying `AdcpServerConfig`.
+ *
+ * `authInfo` is the OAuth-style token shape the framework extracts from
+ * `serve({ authenticate })` — it's the FRAMEWORK auth shape, not the v6
+ * `AuthPrincipal` (which is what the platform sets on the RESOLVED
+ * `Account.authInfo`). The transition is intentional: the framework hands
+ * the resolver the raw transport-level auth, and the resolver decides
+ * what to persist on the Account as `AuthPrincipal`.
+ *
+ * @public
+ */
+/**
+ * The OAuth-style auth shape extracted by `serve({ authenticate })`. Threaded
+ * to `accounts.resolve(ref, ctx)` and to the `tasks_get` custom-tool handler
+ * so adopters can authorize the resolution against the principal.
+ *
+ * Distinct from {@link AuthPrincipal} — `ResolvedAuthInfo` is the RAW
+ * transport-level auth the framework hands to the resolver; `AuthPrincipal`
+ * is what the resolver chooses to persist on the resolved `Account`. The
+ * resolver decides what to keep / drop / re-shape.
+ *
+ * @public
+ */
+export interface ResolvedAuthInfo {
+    token: string;
+    clientId: string;
+    scopes: string[];
+    expiresAt?: number;
+    extra?: Record<string, unknown>;
+}
+export interface ResolveContext {
+    /** Authenticated principal extracted by `serve({ authenticate })`. Undefined when no `authenticate` is configured. */
+    authInfo?: ResolvedAuthInfo;
+    /** Tool the buyer is calling — useful for tool-aware tenant routing. */
+    toolName?: string;
+}
+export interface AuthPrincipal {
+    /** Stable identifier for the calling agent (e.g., `https://buyer.example.com/mcp`). */
+    agent_url?: string;
+    /** Token kind: API key, OAuth bearer, signed-request claim. */
+    kind: 'api_key' | 'oauth' | 'signature' | 'public';
+    /** Bearer token / API key value. Platform-side don't log this. */
+    token?: string;
+    /** OAuth scopes / API-key principal name. */
+    principal?: string;
+    /** Additional claims (jwt sub, kid, etc.). */
+    claims?: Record<string, unknown>;
+}
+export interface AccountStore<TCtxMeta = Record<string, unknown>> {
+    /**
+     * How buyers reference accounts on this platform.
+     * - `'explicit'` — buyer passes `account_id` inline on every request (Snap,
+     *   Meta, GAM via Network/Company id). The default.
+     * - `'implicit'` — buyer must `sync_accounts` first; subsequent requests are
+     *   resolved from the auth principal's pre-synced linkage (LinkedIn, some
+     *   retail-media operators). Framework refuses inline `account_id` references
+     *   for these platforms.
+     * - `'derived'` — single-tenant agents where there is no account_id on the
+     *   wire at all and the auth principal alone identifies the tenant. Most
+     *   self-hosted broadcasters and retail-media operators in proxy mode.
+     *
+     * Defaults to `'explicit'` when omitted.
+     */
+    readonly resolution?: 'explicit' | 'implicit' | 'derived';
+    /**
+     * Resolve buyer's AccountReference into the platform's tenant model.
+     *
+     * `ref` is `undefined` when the wire request didn't carry an account
+     * field — `provide_performance_feedback` and `list_creative_formats` are
+     * the canonical examples. Per `resolution` mode:
+     * - `'derived'` (single-tenant): return the singleton account regardless.
+     * - `'implicit'`: look up the account from the auth principal.
+     * - `'explicit'` (default): no account is available; either throw
+     *   `AccountNotFoundError` to signal "tool requires account" OR return
+     *   a synthetic singleton if the tool legitimately doesn't need
+     *   tenant scoping (e.g., publisher-wide format catalog from
+     *   `list_creative_formats`).
+     *
+     * `ctx.authInfo` is the caller's authenticated principal (when
+     * `serve({ authenticate })` is wired). Adapters fronting an upstream
+     * platform API (Snap, Meta, retail-media) translate auth to tenant ID:
+     *
+     * ```ts
+     * resolve: async (ref, ctx) => {
+     *   if (ref?.account_id) return await this.db.findById(ref.account_id);
+     *   const platformAcct = await myUpstream.findByOAuthClient(ctx?.authInfo?.clientId);
+     *   return platformAcct ? this.toAccount(platformAcct) : null;
+     * }
+     * ```
+     *
+     * Two failure shapes:
+     * - **Unknown / cross-tenant reference**: return `null` (canonical) — OR
+     *   throw `AccountNotFoundError` if your codebase already throws a
+     *   not-found exception class. Framework emits the spec's fixed
+     *   `ACCOUNT_NOT_FOUND` envelope either way. The buyer learns no detail
+     *   beyond "not found" — guarding against principal-enumeration.
+     * - **Transient upstream failure** (DB outage, identity-provider 5xx):
+     *   throw a generic exception. Framework maps to `SERVICE_UNAVAILABLE`
+     *   so the buyer can retry.
+     */
+    resolve(ref: AccountReference | undefined, ctx?: ResolveContext): Promise<Account<TCtxMeta> | null>;
+    /**
+     * sync_accounts API surface. Framework normalizes the wire request; platform
+     * upserts and returns per-account result rows. `throw new AdcpError(...)`
+     * for buyer-facing rejection.
+     *
+     * **Optional.** Stateless platforms (creative-template, signal-marketplace
+     * proxies) that don't manage account lifecycle can omit this; framework
+     * surfaces `UNSUPPORTED_FEATURE` to buyers calling `sync_accounts`.
+     */
+    upsert?(refs: AccountReference[]): Promise<SyncAccountsResultRow[]>;
+    /**
+     * list_accounts API surface. Framework wraps with cursor envelope.
+     *
+     * **Optional.** Same rationale as `upsert` — stateless platforms can omit.
+     */
+    list?(filter: AccountFilter & CursorRequest): Promise<CursorPage<Account<TCtxMeta>>>;
+    /**
+     * report_usage API surface. Operator-billed platforms accept usage rows
+     * (often impressions / spend by media_buy + period) for billing
+     * reconciliation. Optional — adopters that don't run billing through the
+     * agent leave this unimplemented and the framework returns
+     * UNSUPPORTED_FEATURE.
+     *
+     * Idempotent on `(account, period_start, period_end, line_item_id)` —
+     * platform must dedupe replays under the framework's idempotency key.
+     *
+     * `ctx.authInfo` carries the caller's OAuth principal (when
+     * `serve({ authenticate })` is wired). Platforms fronting an upstream
+     * billing API (Snap, Meta, retail-media) use it to authorize the usage
+     * post against the principal's tenant — same pattern as `accounts.resolve`.
+     */
+    reportUsage?(req: ReportUsageRequest, ctx?: ResolveContext): Promise<ReportUsageResponse>;
+    /**
+     * get_account_financials API surface. Operator-billed platforms expose
+     * spend / credit / payment status per the wire shape. Optional — agent-
+     * billed platforms (where the buyer settles directly with the publisher)
+     * leave this unimplemented.
+     *
+     * Read tool — no idempotency requirement. Throw `AdcpError` for buyer-
+     * fixable rejection (`'PERMISSION_DENIED'` if the principal can't see
+     * financials for the requested account).
+     *
+     * `ctx.authInfo` carries the caller's OAuth principal (when
+     * `serve({ authenticate })` is wired). Platforms that guard financials
+     * per-principal use it to authorize the read — same pattern as
+     * `accounts.resolve`.
+     */
+    getAccountFinancials?(req: GetAccountFinancialsRequest, ctx?: ResolveContext): Promise<GetAccountFinancialsSuccess>;
+}
+/**
+ * Optional throw-class for `AccountStore.resolve` not-found signaling. Returning
+ * `null` from `resolve` is canonical and equivalent; throw this only if your
+ * codebase already throws a typed not-found exception elsewhere.
+ *
+ * **Throwable only from `AccountStore.resolve()`.** Throwing it from a
+ * specialism method (`createMediaBuy`, `getProducts`, etc.) bypasses the
+ * framework's not-found mapping and surfaces as `SERVICE_UNAVAILABLE`.
+ *
+ * The constructor's `message` is for server-side operator diagnostics only.
+ * The framework emits a fixed `ACCOUNT_NOT_FOUND` envelope regardless; the
+ * message never reaches the buyer. Operator-side log pipelines may aggregate
+ * this string, so MUST NOT include caller-supplied identifiers (echoed account
+ * refs, request args) — those leak across operator / buyer trust boundaries.
+ *
+ * Use ONLY for the narrow not-found case. Upstream-API outages, misconfigured
+ * env vars, and schema-validation failures should propagate as generic
+ * exceptions and surface to the buyer as `SERVICE_UNAVAILABLE`.
+ */
+export declare class AccountNotFoundError extends Error {
+    readonly name: "AccountNotFoundError";
+    constructor(message?: string);
+}
+export interface AccountFilter {
+    /** Filter by brand domain across all operators. */
+    brand_domain?: string;
+    /** Filter by operator across all brands. */
+    operator?: string;
+    /** Filter by status. */
+    status?: AdcpAccountStatus[];
+}
+export interface SyncAccountsResultRow {
+    account_id?: string;
+    brand: BrandReference;
+    operator: string;
+    action: 'created' | 'updated' | 'unchanged' | 'failed';
+    status: AdcpAccountStatus;
+    errors?: {
+        code: string;
+        message: string;
+    }[];
+}
+export type AdcpAccountStatus = 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
+import type { Account as WireAccount } from '../../types/tools.generated';
+/**
+ * Project a framework `Account<TCtxMeta>` to the wire `Account` shape.
+ *
+ * Strips `metadata` and `authInfo` (framework-internal); renames `id` →
+ * `account_id`; passes through `name`, `status`, `brand`, `operator`,
+ * `advertiser`, and `billing.invoicedTo` mappings.
+ *
+ * Used by the framework when emitting `list_accounts` and other wire
+ * responses that include account data. Adopters never call this directly —
+ * they return `Account<TCtxMeta>` from `accounts.resolve` / `accounts.list`
+ * and the framework projects.
+ */
+export declare function toWireAccount<TCtxMeta>(account: Account<TCtxMeta>): WireAccount;
+/**
+ * Extract `account_id` from an `AccountReference` discriminated union without
+ * casting. Returns `undefined` when `ref` is absent or the union arm doesn't
+ * carry an `account_id` (e.g., `{ brand, operator }` or sandbox variants).
+ *
+ * Typical use in `accounts.resolve` implementations:
+ *
+ * ```ts
+ * resolve: async (ref, ctx) => {
+ *   const id = refAccountId(ref);
+ *   if (id) return this.db.findById(id);
+ *   return this.db.findByOAuthClient(ctx?.authInfo?.clientId ?? '');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function refAccountId(ref?: AccountReference): string | undefined;
+//# sourceMappingURL=account.d.ts.map

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

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

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

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Account model. Single-level (matches AdCP wire's AccountReference).
+ * Platform-internal hierarchies (GAM Network → Advertiser → Order;
+ * Spotify Brand → Campaign) are encoded in `metadata`, not in the typed
+ * shape. Generic `TCtxMeta` lets platforms type their metadata at the call site.
+ *
+ * Tenant isolation is enforced at `accounts.resolve()` returning null for
+ * cross-scope references, not via a multi-level type.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccountNotFoundError = void 0;
+exports.toWireAccount = toWireAccount;
+exports.refAccountId = refAccountId;
+/**
+ * Optional throw-class for `AccountStore.resolve` not-found signaling. Returning
+ * `null` from `resolve` is canonical and equivalent; throw this only if your
+ * codebase already throws a typed not-found exception elsewhere.
+ *
+ * **Throwable only from `AccountStore.resolve()`.** Throwing it from a
+ * specialism method (`createMediaBuy`, `getProducts`, etc.) bypasses the
+ * framework's not-found mapping and surfaces as `SERVICE_UNAVAILABLE`.
+ *
+ * The constructor's `message` is for server-side operator diagnostics only.
+ * The framework emits a fixed `ACCOUNT_NOT_FOUND` envelope regardless; the
+ * message never reaches the buyer. Operator-side log pipelines may aggregate
+ * this string, so MUST NOT include caller-supplied identifiers (echoed account
+ * refs, request args) — those leak across operator / buyer trust boundaries.
+ *
+ * Use ONLY for the narrow not-found case. Upstream-API outages, misconfigured
+ * env vars, and schema-validation failures should propagate as generic
+ * exceptions and surface to the buyer as `SERVICE_UNAVAILABLE`.
+ */
+class AccountNotFoundError extends Error {
+    name = 'AccountNotFoundError';
+    constructor(message = 'Account not found') {
+        super(message);
+    }
+}
+exports.AccountNotFoundError = AccountNotFoundError;
+/**
+ * Project a framework `Account<TCtxMeta>` to the wire `Account` shape.
+ *
+ * Strips `metadata` and `authInfo` (framework-internal); renames `id` →
+ * `account_id`; passes through `name`, `status`, `brand`, `operator`,
+ * `advertiser`, and `billing.invoicedTo` mappings.
+ *
+ * Used by the framework when emitting `list_accounts` and other wire
+ * responses that include account data. Adopters never call this directly —
+ * they return `Account<TCtxMeta>` from `accounts.resolve` / `accounts.list`
+ * and the framework projects.
+ */
+function toWireAccount(account) {
+    const wire = {
+        account_id: account.id,
+        name: account.name,
+        status: account.status,
+    };
+    if (account.brand !== undefined)
+        wire.brand = account.brand;
+    if (account.operator !== undefined)
+        wire.operator = account.operator;
+    if (account.advertiser !== undefined)
+        wire.advertiser = account.advertiser;
+    if (account.billing !== undefined) {
+        // Wire `Account.billing: 'operator' | 'agent' | 'advertiser'` is the
+        // invoiced-to party. Internal `billing.invoicedTo` collapses string +
+        // BrandReference; a BrandReference indicates a third-party advertiser
+        // (Amazon DSP-shaped flow), which projects to `'advertiser'`.
+        const t = account.billing.invoicedTo;
+        wire.billing = typeof t === 'string' ? t : 'advertiser';
+    }
+    return wire;
+}
+// ---------------------------------------------------------------------------
+// AccountReference helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract `account_id` from an `AccountReference` discriminated union without
+ * casting. Returns `undefined` when `ref` is absent or the union arm doesn't
+ * carry an `account_id` (e.g., `{ brand, operator }` or sandbox variants).
+ *
+ * Typical use in `accounts.resolve` implementations:
+ *
+ * ```ts
+ * resolve: async (ref, ctx) => {
+ *   const id = refAccountId(ref);
+ *   if (id) return this.db.findById(id);
+ *   return this.db.findByOAuthClient(ctx?.authInfo?.clientId ?? '');
+ * }
+ * ```
+ *
+ * @public
+ */
+function refAccountId(ref) {
+    return ref && 'account_id' in ref ? ref.account_id : undefined;
+}
+//# sourceMappingURL=account.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/account.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AA4TH,sCAkBC;AAuBD,oCAEC;AAjHD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IACpC,IAAI,GAAG,sBAA+B,CAAC;IAChD,YAAY,OAAO,GAAG,mBAAmB;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AALD,oDAKC;AAkCD;;;;;;;;;;;GAWG;AACH,SAAgB,aAAa,CAAW,OAA0B;IAChE,MAAM,IAAI,GAAgB;QACxB,UAAU,EAAE,OAAO,CAAC,EAAE;QACtB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC;IACF,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5D,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;QAAE,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACrE,IAAI,OAAO,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAC3E,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,qEAAqE;QACrE,sEAAsE;QACtE,sEAAsE;QACtE,8DAA8D;QAC9D,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;IAC1D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,YAAY,CAAC,GAAsB;IACjD,OAAO,GAAG,IAAI,YAAY,IAAI,GAAG,CAAC,CAAC,CAAE,GAA+B,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9F,CAAC"}

package/dist/lib/server/decisioning/admin-router.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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
+ */
+import type { Request, Response, NextFunction, IRouter } from 'express';
+import type { TenantRegistry } from './tenant-registry';
+/**
+ * Minimal Express-router-shaped object so we don't need a hard dependency
+ * on the Express types in this file. Adopters who use a different framework
+ * (Koa, Fastify) can mount the same handler functions via the framework's
+ * adapter — `createTenantAdminHandlers(registry)` returns the bare handlers.
+ */
+export interface RouterLike {
+    get(path: string, handler: (req: Request, res: Response, next?: NextFunction) => void): unknown;
+    post(path: string, handler: (req: Request, res: Response, next?: NextFunction) => void): unknown;
+    delete(path: string, handler: (req: Request, res: Response, next?: NextFunction) => void): unknown;
+}
+export interface TenantAdminHandlers {
+    listTenants(req: Request, res: Response): void;
+    getTenant(req: Request, res: Response): void;
+    recheckTenant(req: Request, res: Response): Promise<void>;
+    unregisterTenant(req: Request, res: Response): void;
+}
+/**
+ * Bare handlers — for adopters running a non-Express framework. The router
+ * helper below mounts these on the standard paths.
+ */
+export declare function createTenantAdminHandlers(registry: TenantRegistry): TenantAdminHandlers;
+/**
+ * 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).
+ */
+export declare function mountTenantAdmin(router: RouterLike, registry: TenantRegistry): RouterLike;
+/**
+ * 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.
+ */
+export declare function createTenantAdminRouter<R extends RouterLike>(routerFactory: R, registry: TenantRegistry): R;
+export type { IRouter };
+//# sourceMappingURL=admin-router.d.ts.map

package/dist/lib/server/decisioning/admin-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-router.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/admin-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC;IAChG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC;IACjG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC;CACpG;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC/C,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC7C,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;CACrD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,GAAG,mBAAmB,CAoDvF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,GAAG,UAAU,CAOzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,UAAU,EAAE,aAAa,EAAE,CAAC,EAAE,QAAQ,EAAE,cAAc,GAAG,CAAC,CAG3G;AAED,YAAY,EAAE,OAAO,EAAE,CAAC"}