@adcp/sdk 6.5.0 → 6.7.0

package/dist/lib/server/decisioning/buyer-agent.js

@@ -0,0 +1,372 @@
+"use strict";
+/**
+ * Buyer-agent identity surface — Phase 1 of #1269.
+ *
+ * Models a buyer agent (the buying entity calling a seller) as a durable
+ * commercial relationship in the seller's records, distinct from the
+ * per-request credential that proves identity. The seller's `BuyerAgent`
+ * record carries onboarding state (status, billing capabilities, default
+ * account terms, allowed brands) that drives commercial behavior.
+ *
+ * The credential answers "who signed?" / "who holds this token?" The
+ * `BuyerAgent` answers "who is this counterparty in our books?" — analogous
+ * to how an SSP has a `buyer_id` row keyed to a DSP regardless of whether
+ * the DSP authenticates via OAuth, signed requests, or a pre-shared API
+ * key. Token proves identity; row drives commercial behavior.
+ *
+ * **Phase 1 scope.** This module ships in 3.0.x with the durable identity
+ * shape. Framework-level billing-capability enforcement and the new error
+ * codes from adcontextprotocol/adcp#3831 land in Phase 2 (#1292), gated on
+ * the SDK's 3.1 cutover.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BuyerAgentRegistry = void 0;
+exports.markVerifiedHttpSig = markVerifiedHttpSig;
+exports.signingOnly = signingOnly;
+exports.bearerOnly = bearerOnly;
+exports.mixed = mixed;
+exports.cached = cached;
+/**
+ * Belt-and-suspenders check that an `http_sig` credential carries a non-
+ * empty `agent_url`. A misbehaving authenticator could produce `kind:
+ * 'http_sig'` without populating the verified URL — without this guard, the
+ * registry would pass `undefined` (or `''`) to the adopter's resolver and
+ * silently get back `null`. Caller is responsible for the kind dispatch;
+ * this function only validates the http_sig payload shape.
+ */
+function isVerifiedHttpSigPayload(credential) {
+    return typeof credential.agent_url === 'string' && credential.agent_url.length > 0;
+}
+/**
+ * Module-private symbol used as a provenance brand on verifier-produced
+ * `http_sig` credentials. NOT registered via `Symbol.for(...)` — code
+ * outside this module cannot synthesize the symbol value, which is what
+ * makes it a usable provenance check.
+ *
+ * The brand is non-enumerable so it's invisible to `JSON.stringify`,
+ * `Object.keys`, spread, and structured-clone — meaning a credential
+ * that crosses a serialization boundary loses its brand. For the
+ * security model that's correct: a hostile relay or replay strips the
+ * brand and the registry refuses to treat the credential as verified.
+ *
+ * Only `markVerifiedHttpSig` (called by the framework's signature
+ * verifier in `src/lib/server/auth-signature.ts`) attaches the brand.
+ * Custom `authenticate` callbacks that synthesize a literal-shape
+ * `{ kind: 'http_sig', ... }` credential will NOT carry the brand —
+ * `signingOnly` and `mixed` registry factories reject those.
+ */
+const VERIFIED_HTTP_SIG_BRAND = Symbol('@adcp/sdk.verifiedHttpSig');
+/**
+ * Brand an `http_sig` credential as verifier-produced. Only the framework's
+ * signature verifier (`verifySignatureAsAuthenticator`) calls this; the
+ * brand is the registry's proof that the credential's `agent_url` was
+ * cryptographically verified per adcontextprotocol/adcp#3831.
+ *
+ * Returned object is a fresh shallow copy — the input is not mutated.
+ *
+ * @internal — exported for `auth-signature.ts` only; not part of the
+ * adopter surface.
+ */
+function markVerifiedHttpSig(credential) {
+    const branded = { ...credential };
+    Object.defineProperty(branded, VERIFIED_HTTP_SIG_BRAND, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return branded;
+}
+/**
+ * Predicate the registry factories use to distinguish verifier-produced
+ * `http_sig` credentials from literal-shape impostors. Returns true ONLY
+ * when the credential was produced by the framework's signature verifier
+ * (or another caller that imported the symbol from this module — there
+ * are none).
+ */
+function isVerifiedHttpSig(credential) {
+    return credential.kind === 'http_sig' && credential[VERIFIED_HTTP_SIG_BRAND] === true;
+}
+/**
+ * Construct a signing-only `BuyerAgentRegistry`. Bearer/API-key/OAuth
+ * requests resolve to `null` (framework rejects); only signed requests
+ * are honored.
+ *
+ * The path-of-least-resistance factory for production sellers — implement
+ * one resolver, traffic that doesn't sign is automatically refused.
+ *
+ * @public
+ */
+function signingOnly(opts) {
+    if (typeof opts.resolveByAgentUrl !== 'function') {
+        throw new TypeError('BuyerAgentRegistry.signingOnly: resolveByAgentUrl must be a function');
+    }
+    const resolveByAgentUrl = opts.resolveByAgentUrl;
+    return {
+        async resolve(authInfo) {
+            const credential = authInfo.credential;
+            if (credential === undefined || credential.kind !== 'http_sig')
+                return null;
+            // Reject literal-shape http_sig credentials: only the framework's
+            // signature verifier brands a credential as verified. A custom
+            // `authenticate` callback that synthesizes `{ kind: 'http_sig', ... }`
+            // from arbitrary data would otherwise be routed as if cryptographically
+            // verified — the brand check closes that forgery vector.
+            if (!isVerifiedHttpSig(credential))
+                return null;
+            if (!isVerifiedHttpSigPayload(credential))
+                return null;
+            return resolveByAgentUrl(credential.agent_url);
+        },
+    };
+}
+/**
+ * Construct a bearer-only `BuyerAgentRegistry`. Signed requests still
+ * authenticate via the existing signature-verifier surface, but the
+ * registry resolves all credential kinds via `resolveByCredential` against
+ * the seller's onboarding ledger — useful in pre-trust-beta deployments
+ * where the seller maintains a credential→agent table out-of-band.
+ *
+ * @public
+ */
+function bearerOnly(opts) {
+    if (typeof opts.resolveByCredential !== 'function') {
+        throw new TypeError('BuyerAgentRegistry.bearerOnly: resolveByCredential must be a function');
+    }
+    const resolveByCredential = opts.resolveByCredential;
+    return {
+        async resolve(authInfo) {
+            const credential = authInfo.credential;
+            if (credential === undefined)
+                return null;
+            return resolveByCredential(credential);
+        },
+    };
+}
+/**
+ * Construct a mixed-mode `BuyerAgentRegistry` that supports both signed and
+ * bearer/OAuth/API-key credentials. Signed traffic resolves through
+ * `resolveByAgentUrl` against the verified `credential.agent_url`; non-
+ * signed credentials fall through to `resolveByCredential`.
+ *
+ * Framework prefers the signed path: when both an `Authorization: Bearer`
+ * and a valid `Signature: ...` are present on the same request, the
+ * `http_sig` credential variant is what reaches `resolve`, and only
+ * `resolveByAgentUrl` is invoked. The bearer path is never consulted on
+ * signed traffic.
+ *
+ * @public
+ */
+function mixed(opts) {
+    if (typeof opts.resolveByAgentUrl !== 'function') {
+        throw new TypeError('BuyerAgentRegistry.mixed: resolveByAgentUrl must be a function');
+    }
+    if (typeof opts.resolveByCredential !== 'function') {
+        throw new TypeError('BuyerAgentRegistry.mixed: resolveByCredential must be a function');
+    }
+    const resolveByAgentUrl = opts.resolveByAgentUrl;
+    const resolveByCredential = opts.resolveByCredential;
+    return {
+        async resolve(authInfo) {
+            const credential = authInfo.credential;
+            if (credential === undefined)
+                return null;
+            if (credential.kind === 'http_sig') {
+                // Same forgery clamp as `signingOnly`: only verifier-branded
+                // http_sig credentials route through the signed path.
+                if (!isVerifiedHttpSig(credential))
+                    return null;
+                // Reject a malformed `http_sig` credential here rather than falling
+                // through to resolveByCredential. Otherwise `mixed` would be strictly
+                // weaker than signingOnly: an authenticator that produces an
+                // http_sig-shaped credential without a verified agent_url could
+                // bypass signed-path enforcement by routing through the bearer table.
+                if (!isVerifiedHttpSigPayload(credential))
+                    return null;
+                return resolveByAgentUrl(credential.agent_url);
+            }
+            return resolveByCredential(credential);
+        },
+    };
+}
+/**
+ * Compute a cache key from a credential. Returns null when the
+ * credential is undefined — uncacheable, falls through to the inner
+ * registry on each call. Keys are namespaced by kind so an api_key
+ * `key_id` value can never collide with an http_sig `keyid` value or
+ * an oauth `client_id`. Note that `key_id` is already a stable hash
+ * (Stage 3); using it as a cache key is safe.
+ */
+function cacheKeyForCredential(credential) {
+    if (credential === undefined)
+        return null;
+    switch (credential.kind) {
+        case 'http_sig':
+            return `http_sig:${credential.agent_url}`;
+        case 'api_key':
+            return `api_key:${credential.key_id}`;
+        case 'oauth':
+            return `oauth:${credential.client_id}`;
+        default: {
+            // Exhaustiveness check — adding a new credential kind without
+            // updating this switch produces a compile error here, not a
+            // runtime cache-miss bug.
+            const _exhaustive = credential;
+            void _exhaustive;
+            return null;
+        }
+    }
+}
+/**
+ * Wrap a {@link BuyerAgentRegistry} with TTL-based result caching and
+ * concurrent-resolve coalescing. Adopters whose `resolveByAgentUrl` /
+ * `resolveByCredential` hit a database or external service compose
+ * the cache via:
+ *
+ * ```ts
+ * const registry = BuyerAgentRegistry.cached(
+ *   BuyerAgentRegistry.signingOnly({
+ *     resolveByAgentUrl: async url => db.findBuyerAgent(url),
+ *   }),
+ *   { ttlSeconds: 60 }
+ * );
+ * ```
+ *
+ * Cache properties:
+ * - **TTL-bounded.** Entries expire after `ttlSeconds` (default 60).
+ *   Negative cache (null returns) is opt-in via `cacheNullsTtlSeconds`.
+ * - **LRU-evicted.** Bounded to `maxSize` entries (default 10000).
+ *   Oldest-accessed entry evicts on overflow.
+ * - **Concurrent-resolve coalesced.** N parallel `resolve()` calls on
+ *   the same key produce ONE upstream invocation. Subsequent callers
+ *   await the in-flight promise — important when the seller front-ends
+ *   a slow upstream and a buyer burst arrives.
+ * - **Per-kind cache keys.** Keys are namespaced (`http_sig:`,
+ *   `api_key:`, `oauth:`) so cross-kind collisions cannot leak an agent
+ *   resolved through one credential type to a different type.
+ * - **Skips uncacheable inputs.** When the credential is undefined,
+ *   `resolve()` falls through to the inner registry on each call —
+ *   adopters wiring custom auth without `credential` synthesis (Stage 3
+ *   migration cycle) see no behavior change.
+ * - **Explicit invalidation.** Returns a {@link CachedBuyerAgentRegistry}
+ *   with `.invalidate(credential)` and `.clear()` methods. Call
+ *   `invalidate` when you mutate an agent's record (status flip,
+ *   billing-capability change) so the next request re-resolves rather
+ *   than serving the stale entry. Without this, the stale-status window
+ *   is bounded by `ttlSeconds` — a now-suspended agent retains access
+ *   for up to that long.
+ *
+ * Mirrors the `AsyncCachingJwksResolver` over `JwksResolver` pattern
+ * already in `src/lib/signing/`.
+ *
+ * @public
+ */
+function cached(inner, options = {}) {
+    if (typeof inner !== 'object' || inner === null || typeof inner.resolve !== 'function') {
+        throw new TypeError('BuyerAgentRegistry.cached: `inner` must be a BuyerAgentRegistry');
+    }
+    const ttlMs = (options.ttlSeconds ?? 60) * 1000;
+    const nullsTtlMs = (options.cacheNullsTtlSeconds ?? 0) * 1000;
+    const maxSize = options.maxSize ?? 10000;
+    const now = options.now ?? Date.now;
+    if (ttlMs <= 0)
+        throw new RangeError('BuyerAgentRegistry.cached: ttlSeconds must be > 0');
+    if (nullsTtlMs < 0)
+        throw new RangeError('BuyerAgentRegistry.cached: cacheNullsTtlSeconds must be >= 0');
+    if (maxSize < 1)
+        throw new RangeError('BuyerAgentRegistry.cached: maxSize must be >= 1');
+    // Map iteration order is insertion order, so re-inserting on hit
+    // gives us LRU-on-access semantics for free.
+    const cache = new Map();
+    const inFlight = new Map();
+    return {
+        async resolve(authInfo) {
+            const key = cacheKeyForCredential(authInfo.credential);
+            if (key === null) {
+                // Uncacheable input — pass through. Adopters wiring custom
+                // auth that hasn't migrated to `credential` synthesis see
+                // every call hit the inner resolver.
+                return inner.resolve(authInfo);
+            }
+            const entry = cache.get(key);
+            if (entry !== undefined && now() < entry.expiresAtMs) {
+                // LRU touch: re-insert so this entry becomes the most-recent.
+                cache.delete(key);
+                cache.set(key, entry);
+                return entry.value;
+            }
+            if (entry !== undefined) {
+                // Expired — drop before refetch.
+                cache.delete(key);
+            }
+            // Coalesce concurrent resolves: subsequent callers on the same
+            // key await the existing in-flight promise rather than firing
+            // their own upstream lookup. If the upstream rejects, all
+            // coalesced callers see the same rejection; the `finally` below
+            // releases `inFlight` so the next caller retries upstream
+            // (rejected promises do NOT poison the cache — `cache.set`
+            // inside the IIFE is unreachable on rejection).
+            const existing = inFlight.get(key);
+            if (existing !== undefined)
+                return existing;
+            const promise = (async () => {
+                const value = await inner.resolve(authInfo);
+                const entryTtlMs = value === null ? nullsTtlMs : ttlMs;
+                if (entryTtlMs > 0) {
+                    // Defense-in-depth: freeze the resolved record before
+                    // sharing across coalesced callers. The dispatcher seam
+                    // also freezes per-request (Stage 2), but freezing here
+                    // makes the cached-shared-reference invariant load-
+                    // bearing rather than coincidental — a future caller
+                    // mutating `BuyerAgent.status` would otherwise corrupt
+                    // every other cached-hit consumer's view.
+                    if (value !== null && !Object.isFrozen(value)) {
+                        if (value.billing_capabilities instanceof Set) {
+                            Object.freeze(value.billing_capabilities);
+                        }
+                        Object.freeze(value);
+                    }
+                    cache.set(key, { value, expiresAtMs: now() + entryTtlMs });
+                    while (cache.size > maxSize) {
+                        const oldestKey = cache.keys().next().value;
+                        if (oldestKey === undefined)
+                            break;
+                        cache.delete(oldestKey);
+                    }
+                }
+                return value;
+            })();
+            inFlight.set(key, promise);
+            try {
+                return await promise;
+            }
+            finally {
+                inFlight.delete(key);
+            }
+        },
+        invalidate(credential) {
+            const key = cacheKeyForCredential(credential);
+            if (key !== null)
+                cache.delete(key);
+        },
+        clear() {
+            cache.clear();
+        },
+    };
+}
+/**
+ * Factory namespace mirroring the documented surface from #1269. Adopters
+ * import the namespace and call `BuyerAgentRegistry.signingOnly({...})`,
+ * etc. Individual functions are also exported above for direct use.
+ *
+ * @public
+ */
+exports.BuyerAgentRegistry = {
+    signingOnly,
+    bearerOnly,
+    mixed,
+    cached,
+};
+//# sourceMappingURL=buyer-agent.js.map

package/dist/lib/server/decisioning/buyer-agent.js.map

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

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

@@ -30,12 +30,39 @@ export interface DecisioningCapabilities<TConfig = unknown> {
      * Useful when a creative agent hosts 50 formats but this seller only accepts
      * 10 of them. Filter scope is per-creative-agent: `[{ agent_url: A, format_ids: ['x'] }, { agent_url: B }]`
      * means "from A only format x; from B all formats."
+     *
+     * Omit for signals-only platforms (`signal-marketplace`, `signal-owned`) — they
+     * sell audience data access, not media inventory, and don't compose with creative agents.
+     */
+    creative_agents?: readonly CreativeAgentRef[];
+    /**
+     * Channels this platform sells.
+     *
+     * Omit for non-media-buy platforms — they don't sell ad inventory and have no
+     * channels to declare. Applies to signals (`signal-marketplace`, `signal-owned`),
+     * governance (`governance-spend-authority`, `governance-delivery-monitor`,
+     * `property-lists`, `collection-lists`, `content-standards`), creative-only
+     * (`creative-ad-server`, `creative-template`, `creative-generative`), and
+     * brand (`brand-rights`) platforms.
+     *
+     * **Required at runtime for media-buy platforms.** `validatePlatform` (called
+     * by `createAdcpServerFromPlatform`) throws `PlatformConfigError` when any
+     * `sales-*` specialism is claimed and this field is absent.
+     */
+    channels?: readonly MediaChannel[];
+    /**
+     * Pricing models this platform supports.
+     *
+     * Omit for non-media-buy platforms — they don't sell ad inventory and have no
+     * channel-level pricing to declare. For signals platforms specifically, pricing
+     * is declared per-signal in the signal descriptor's `pricing_options[]` instead.
+     * Same non-media-buy specialism set as `channels` above.
+     *
+     * **Required at runtime for media-buy platforms.** `validatePlatform` (called
+     * by `createAdcpServerFromPlatform`) throws `PlatformConfigError` when any
+     * `sales-*` specialism is claimed and this field is absent.
      */
-    creative_agents: readonly CreativeAgentRef[];
-    /** Channels this platform sells. */
-    channels: readonly MediaChannel[];
-    /** Pricing models this platform supports. */
-    pricingModels: readonly PricingModel[];
+    pricingModels?: readonly PricingModel[];
     /** Targeting capabilities. Optional — framework infers reasonable defaults if omitted. */
     targeting?: TargetingCapabilities;
     /** Reporting capabilities. Optional — framework infers reasonable defaults if omitted. */
@@ -109,9 +136,14 @@ export interface DecisioningCapabilities<TConfig = unknown> {
      * Billing parties this platform supports. `'operator'` = retail-media model
      * (Criteo, Amazon — operator pays the publisher and bills the brand).
      * `'agent'` = pass-through model (buyer's agent settles directly with the
-     * platform). Defaults to `['agent']` when omitted.
+     * platform). `'advertiser'` = seller invoices the advertiser directly,
+     * bypassing operator settlement (advertiser-direct sell-side platforms where
+     * the brand is the direct contractual counterparty). Defaults to `['agent']`
+     * when omitted. To express advertiser-direct billing per account, set
+     * `billing.invoicedTo` to a `BrandReference` (the framework maps any
+     * `BrandReference` to `'advertiser'` on the wire).
      */
-    supportedBillings?: ReadonlyArray<'operator' | 'agent'>;
+    supportedBillings?: ReadonlyArray<'operator' | 'agent' | 'advertiser'>;
     /**
      * If true, this platform refuses transactions without an authenticated
      * operator principal (operator-billed retail-media). Framework emits

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

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

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

@@ -0,0 +1,93 @@
+/**
+ * Method-level composition helpers for {@link DecisioningPlatform} adopters
+ * who need to wrap individual platform methods with pre/post hooks — typical
+ * shapes are early-return short-circuits (price-optimization paths skipping
+ * the inner call), response enrichment (carbon emissions, brand-manifest
+ * merging), and response-level caching.
+ *
+ * Closes adcp-client#1314.
+ *
+ * @public
+ */
+/**
+ * Wrapper returned by a `before` hook to short-circuit the wrapped method.
+ *
+ * Returning a wrapped object (e.g. `{ shortCircuit: cachedPriceOpt }`) skips
+ * the inner method and feeds the wrapped value through `after` (if any)
+ * back to the caller. Returning `undefined` (or no return) falls through.
+ *
+ * Discriminated wrapper rather than a sentinel symbol because the wrapper
+ * is unambiguous even when `TResult` itself includes `undefined`, and
+ * adopters can't accidentally short-circuit by forgetting an import.
+ *
+ * @public
+ */
+export interface ComposeShortCircuit<TResult> {
+    shortCircuit: TResult;
+}
+/**
+ * Hooks accepted by {@link composeMethod}.
+ *
+ * `before` returning `undefined` (or no return) falls through to the wrapped
+ * method. Returning `{ shortCircuit: value }` short-circuits — `after` (if
+ * any) still runs on the short-circuit value before it flows back to the
+ * caller.
+ *
+ * `after` runs on the result whether it came from the wrapped method or
+ * from a `before` short-circuit. Receives the original `params` and `ctx`
+ * for context-dependent enrichment.
+ *
+ * The `after` hook runs BEFORE response-schema validation. The wrapped
+ * value still has to satisfy the wire schema for the tool — adopters
+ * decorating responses with vendor-specific data should put it under
+ * `ext` (the spec's typed extension surface) rather than at the top level.
+ *
+ * @public
+ */
+export interface ComposeHooks<TParams, TCtx, TResult> {
+    before?: (params: TParams, ctx: TCtx) => Promise<ComposeShortCircuit<TResult> | undefined>;
+    after?: (result: TResult, params: TParams, ctx: TCtx) => Promise<TResult>;
+}
+/**
+ * Wrap a single platform method with optional `before` / `after` hooks.
+ *
+ * Type-preserving: the returned function has the same `(params, ctx) =>
+ * Promise<TResult>` signature as `inner`, so it slots into a typed
+ * `DecisioningPlatform` shape without `as` casts.
+ *
+ * Validates `inner` is a function eagerly (at wrap time, not at first
+ * invocation) so adopters who reference an optional method that wasn't
+ * implemented on the underlying platform get a clear error at module load
+ * rather than the first traffic to hit the method.
+ *
+ * @example Short-circuit + enrichment
+ * ```ts
+ * import { composeMethod } from '@adcp/sdk/server';
+ *
+ * const wrapped = {
+ *   ...basePlatform,
+ *   sales: {
+ *     ...basePlatform.sales,
+ *     getMediaBuyDelivery: composeMethod(basePlatform.sales.getMediaBuyDelivery, {
+ *       before: async (params) =>
+ *         params.optimization === 'price'
+ *           ? { shortCircuit: cachedPriceOpt }
+ *           : undefined,
+ *       after: async (result) => ({
+ *         ...result,
+ *         ext: { ...result.ext, carbon_grams_per_impression: await score(result) },
+ *       }),
+ *     }),
+ *     getProducts: composeMethod(basePlatform.sales.getProducts, {
+ *       after: async (result) => mergeBrandManifest(result, await brandCache.get()),
+ *     }),
+ *   },
+ * };
+ *
+ * createAdcpServerFromPlatform(wrapped, opts);
+ * ```
+ *
+ * @public
+ */
+export declare function composeMethod<TParams, TCtx, TResult>(inner: (params: TParams, ctx: TCtx) => Promise<TResult>, hooks: ComposeHooks<TParams, TCtx, TResult>): (params: TParams, ctx: TCtx) => Promise<TResult>;
+//# sourceMappingURL=compose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB,CAAC,OAAO;IAC1C,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO;IAClD,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,mBAAmB,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IAC3F,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,EAClD,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,EACvD,KAAK,EAAE,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,GAC1C,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAwBlD"}

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

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Method-level composition helpers for {@link DecisioningPlatform} adopters
+ * who need to wrap individual platform methods with pre/post hooks — typical
+ * shapes are early-return short-circuits (price-optimization paths skipping
+ * the inner call), response enrichment (carbon emissions, brand-manifest
+ * merging), and response-level caching.
+ *
+ * Closes adcp-client#1314.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeMethod = composeMethod;
+/**
+ * Wrap a single platform method with optional `before` / `after` hooks.
+ *
+ * Type-preserving: the returned function has the same `(params, ctx) =>
+ * Promise<TResult>` signature as `inner`, so it slots into a typed
+ * `DecisioningPlatform` shape without `as` casts.
+ *
+ * Validates `inner` is a function eagerly (at wrap time, not at first
+ * invocation) so adopters who reference an optional method that wasn't
+ * implemented on the underlying platform get a clear error at module load
+ * rather than the first traffic to hit the method.
+ *
+ * @example Short-circuit + enrichment
+ * ```ts
+ * import { composeMethod } from '@adcp/sdk/server';
+ *
+ * const wrapped = {
+ *   ...basePlatform,
+ *   sales: {
+ *     ...basePlatform.sales,
+ *     getMediaBuyDelivery: composeMethod(basePlatform.sales.getMediaBuyDelivery, {
+ *       before: async (params) =>
+ *         params.optimization === 'price'
+ *           ? { shortCircuit: cachedPriceOpt }
+ *           : undefined,
+ *       after: async (result) => ({
+ *         ...result,
+ *         ext: { ...result.ext, carbon_grams_per_impression: await score(result) },
+ *       }),
+ *     }),
+ *     getProducts: composeMethod(basePlatform.sales.getProducts, {
+ *       after: async (result) => mergeBrandManifest(result, await brandCache.get()),
+ *     }),
+ *   },
+ * };
+ *
+ * createAdcpServerFromPlatform(wrapped, opts);
+ * ```
+ *
+ * @public
+ */
+function composeMethod(inner, hooks) {
+    if (typeof inner !== 'function') {
+        throw new TypeError(`composeMethod: 'inner' must be a function, got ${inner === null ? 'null' : typeof inner}. ` +
+            `Did you reference an optional method that wasn't implemented on the platform?`);
+    }
+    return async (params, ctx) => {
+        let result;
+        if (hooks.before) {
+            const early = await hooks.before(params, ctx);
+            if (early === undefined) {
+                result = await inner(params, ctx);
+            }
+            else {
+                result = early.shortCircuit;
+            }
+        }
+        else {
+            result = await inner(params, ctx);
+        }
+        if (hooks.after) {
+            result = await hooks.after(result, params, ctx);
+        }
+        return result;
+    };
+}
+//# sourceMappingURL=compose.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/compose.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;AAoFH,sCA2BC;AApED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,SAAgB,aAAa,CAC3B,KAAuD,EACvD,KAA2C;IAE3C,IAAI,OAAO,KAAK,KAAK,UAAU,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CACjB,kDAAkD,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,KAAK,IAAI;YAC1F,+EAA+E,CAClF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;QAC3B,IAAI,MAAe,CAAC;QACpB,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YAC9C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACN,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC;YAC9B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,MAAM,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACpC,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,MAAM,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC"}