@adcp/sdk 6.11.0 → 6.12.0

package/dist/lib/server/decisioning/proposal/lifecycle.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Proposal-lifecycle framework helpers — the v1.5 intercept seam.
+ *
+ * Sits parallel to existing dispatch helpers in `runtime/from-platform.ts`.
+ * Framework intercepts at a seam, does its work, dispatches.
+ *
+ * Public surface (the dispatch path imports these):
+ *
+ *   - {@link enforceProposalExpiry} — D7. Look up the committed proposal,
+ *     validate `state === 'committed'` and `now <= expires_at + grace`,
+ *     return the record.
+ *   - {@link validateCapabilityOverlap} — D4. Walk a buyer's
+ *     `create_media_buy` / `update_media_buy` request packages against
+ *     each recipe's `capability_overlap` and reject mismatches with
+ *     `INVALID_REQUEST`.
+ *   - {@link validateOverlapSubsetOfWire} — D4 round-4. Validate at
+ *     `putDraft` time that each recipe's `capability_overlap` axis is a
+ *     subset of the corresponding wire-declared product capabilities.
+ *     Mismatches throw `INTERNAL_ERROR` (adopter bug, not buyer bug).
+ *   - {@link detectFinalizeAction} — pull out the first finalize-action
+ *     refine entry from a `GetProductsRequest`.
+ *   - structured-log helpers per § Observability.
+ *
+ * Ports `adcp-client-python.src/adcp/decisioning/proposal_lifecycle.py`.
+ *
+ * @public
+ * @packageDocumentation
+ */
+import type { GetProductsRequest, Product } from '../../../types/tools.generated';
+import type { ProposalRecord, ProposalStore } from './store';
+import type { Recipe } from './types';
+/**
+ * Validate a proposal is committed and within its hold window.
+ *
+ * Three failure modes mapped to spec error codes:
+ *
+ *   - Record not found OR cross-tenant → `PROPOSAL_NOT_FOUND` (terminal).
+ *     Cross-tenant probes return the same error as missing IDs (no
+ *     principal-enumeration via id probing).
+ *   - State !== `'committed'` → `PROPOSAL_NOT_COMMITTED` (correctable).
+ *     The buyer needs to call `getProducts({ buying_mode: 'refine',
+ *     refine: [{ action: 'finalize' }] })` first.
+ *   - Committed but `now > expires_at + grace` → `PROPOSAL_EXPIRED`
+ *     (correctable per AdCP 3.0.6 — the buyer re-discovers via
+ *     `get_products` to obtain a fresh proposal).
+ *
+ * @public
+ */
+export declare function enforceProposalExpiry<TRecipe extends Recipe>(proposalId: string, args: {
+    proposalStore: ProposalStore<TRecipe>;
+    expectedAccountId: string;
+    graceSeconds?: number;
+    now?: Date;
+}): Promise<ProposalRecord<TRecipe>>;
+interface PackageLike {
+    product_id?: string;
+    pricing_option_id?: string;
+    pricing_model?: string;
+    delivery_type?: string;
+    signal_type?: string;
+    targeting_overlay?: Record<string, unknown>;
+    /**
+     * Adopter-resolved pricing model — the validation reads this when
+     * present. Set by the framework when it has resolved
+     * `pricing_option_id` against the product's pricing options.
+     */
+    _resolved_pricing_model?: string;
+    _resolved_delivery_type?: string;
+    [k: string]: unknown;
+}
+/**
+ * Pre-adapter validation seam: walk buyer's packages against each recipe's
+ * `capability_overlap` and reject mismatches.
+ *
+ * Called from the framework's `create_media_buy` and `update_media_buy`
+ * dispatch paths after recipes are hydrated from the {@link ProposalStore}.
+ * Per D4, the framework owns this gate so every adopter doesn't write the
+ * same intersection logic.
+ *
+ * Validation axes (per {@link CapabilityOverlap}):
+ *
+ *   - `pricingModels` — checked against `package._resolved_pricing_model`
+ *     or `package.pricing_model`.
+ *   - `targetingDimensions` — checked against `package.targeting_overlay` keys.
+ *   - `deliveryTypes` — checked against `package._resolved_delivery_type`
+ *     or `package.delivery_type`.
+ *   - `signalTypes` — checked against `package.signal_type`.
+ *
+ * Per the design's undefined-vs-empty-set semantics: `undefined` skips the
+ * gate; an explicit `Set` (including the empty set) is enforced.
+ *
+ * @public
+ */
+export declare function validateCapabilityOverlap<TRecipe extends Recipe>(args: {
+    packages: readonly PackageLike[];
+    recipes: ReadonlyMap<string, TRecipe>;
+    fieldPathPrefix?: string;
+}): void;
+/**
+ * Validate `recipe.capability_overlap` is a subset of the matching product's
+ * wire-declared capabilities.
+ *
+ * Called at `putDraft` time. Mismatches throw `INTERNAL_ERROR` — this is
+ * an adopter bug (the manager declared an overlap claiming capabilities the
+ * wire shape doesn't advertise), not a buyer bug.
+ *
+ * @public
+ */
+export declare function validateOverlapSubsetOfWire<TRecipe extends Recipe>(args: {
+    recipes: ReadonlyMap<string, TRecipe>;
+    products: readonly Product[];
+}): void;
+/**
+ * Result of {@link detectFinalizeAction}: the index, proposal_id, and
+ * optional ask of the first finalize-action refine entry.
+ *
+ * @public
+ */
+export interface FinalizeActionRef {
+    index: number;
+    proposalId: string;
+    ask?: string;
+}
+/**
+ * Return the first finalize-action refine entry from a
+ * `GetProductsRequest`, or `null` if no finalize entry exists.
+ *
+ * The index points at the entry's position in `refine[]` so the framework
+ * can produce indexed wire field paths (`refine[3].proposal_id`) on
+ * rejection — buyers parsing the error get a precise pointer.
+ *
+ * Per the spec, `buying_mode: 'refine'` carries a `refine[]` array of
+ * entries. Each entry has a `scope` (`request` / `product` / `proposal`)
+ * and an optional `action` (`include` / `omit` / `finalize`). v1.5 only
+ * intercepts `proposal`-scoped entries with `action: 'finalize'`.
+ *
+ * The framework processes ONE finalize entry per request; if the buyer
+ * sends multiple finalize entries, only the first is processed (rest fall
+ * through to the standard refine path).
+ *
+ * @public
+ */
+export declare function detectFinalizeAction(req: GetProductsRequest): FinalizeActionRef | null;
+/**
+ * Logger-shaped sink for structured proposal-lifecycle events. Defaults to
+ * `console.info`-style emission; the dispatch path can pass a typed logger
+ * to route through the rest of the framework's logging.
+ *
+ * @public
+ */
+export interface ProposalLifecycleLogger {
+    info(message: string, fields?: Record<string, unknown>): void;
+}
+/**
+ * Replace the module-level logger that proposal-lifecycle structured
+ * events (`proposal.draft_persisted`, `proposal.finalized`, `proposal.expired`,
+ * `proposal.consumed`) emit through. Adopters wire this to their existing
+ * logger (pino, bunyan, etc.) so lifecycle events route through the same
+ * pipeline as the rest of their server logs. Tests use it to capture
+ * structured emissions for assertion.
+ *
+ * @public
+ */
+export declare function setProposalLifecycleLogger(next: ProposalLifecycleLogger): void;
+/** `proposal.draft_persisted` event. */
+export declare function logDraftPersisted(args: {
+    proposalId: string;
+    accountId: string;
+    recipesCount: number;
+}): void;
+/**
+ * `proposal.finalized` event. `path` is `'inline'` or `'handoff'`.
+ */
+export declare function logFinalizeSucceeded(args: {
+    proposalId: string;
+    accountId: string;
+    expiresAt: Date;
+    path: 'inline' | 'handoff';
+}): void;
+/** `proposal.expired` event. */
+export declare function logExpired(args: {
+    proposalId: string;
+    accountId: string;
+    now: Date;
+    expiresAt: Date;
+    graceSeconds: number;
+}): void;
+/** `proposal.consumed` event. */
+export declare function logConsumed(args: {
+    proposalId: string;
+    accountId: string;
+    mediaBuyId: string;
+}): void;
+export {};
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/lib/server/decisioning/proposal/lifecycle.d.ts.map

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

package/dist/lib/server/decisioning/proposal/lifecycle.js

@@ -0,0 +1,366 @@
+"use strict";
+/**
+ * Proposal-lifecycle framework helpers — the v1.5 intercept seam.
+ *
+ * Sits parallel to existing dispatch helpers in `runtime/from-platform.ts`.
+ * Framework intercepts at a seam, does its work, dispatches.
+ *
+ * Public surface (the dispatch path imports these):
+ *
+ *   - {@link enforceProposalExpiry} — D7. Look up the committed proposal,
+ *     validate `state === 'committed'` and `now <= expires_at + grace`,
+ *     return the record.
+ *   - {@link validateCapabilityOverlap} — D4. Walk a buyer's
+ *     `create_media_buy` / `update_media_buy` request packages against
+ *     each recipe's `capability_overlap` and reject mismatches with
+ *     `INVALID_REQUEST`.
+ *   - {@link validateOverlapSubsetOfWire} — D4 round-4. Validate at
+ *     `putDraft` time that each recipe's `capability_overlap` axis is a
+ *     subset of the corresponding wire-declared product capabilities.
+ *     Mismatches throw `INTERNAL_ERROR` (adopter bug, not buyer bug).
+ *   - {@link detectFinalizeAction} — pull out the first finalize-action
+ *     refine entry from a `GetProductsRequest`.
+ *   - structured-log helpers per § Observability.
+ *
+ * Ports `adcp-client-python.src/adcp/decisioning/proposal_lifecycle.py`.
+ *
+ * @public
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceProposalExpiry = enforceProposalExpiry;
+exports.validateCapabilityOverlap = validateCapabilityOverlap;
+exports.validateOverlapSubsetOfWire = validateOverlapSubsetOfWire;
+exports.detectFinalizeAction = detectFinalizeAction;
+exports.setProposalLifecycleLogger = setProposalLifecycleLogger;
+exports.logDraftPersisted = logDraftPersisted;
+exports.logFinalizeSucceeded = logFinalizeSucceeded;
+exports.logExpired = logExpired;
+exports.logConsumed = logConsumed;
+const async_outcome_1 = require("../async-outcome");
+// ---------------------------------------------------------------------------
+// D7 — expires_at enforcement
+// ---------------------------------------------------------------------------
+/**
+ * Validate a proposal is committed and within its hold window.
+ *
+ * Three failure modes mapped to spec error codes:
+ *
+ *   - Record not found OR cross-tenant → `PROPOSAL_NOT_FOUND` (terminal).
+ *     Cross-tenant probes return the same error as missing IDs (no
+ *     principal-enumeration via id probing).
+ *   - State !== `'committed'` → `PROPOSAL_NOT_COMMITTED` (correctable).
+ *     The buyer needs to call `getProducts({ buying_mode: 'refine',
+ *     refine: [{ action: 'finalize' }] })` first.
+ *   - Committed but `now > expires_at + grace` → `PROPOSAL_EXPIRED`
+ *     (correctable per AdCP 3.0.6 — the buyer re-discovers via
+ *     `get_products` to obtain a fresh proposal).
+ *
+ * @public
+ */
+async function enforceProposalExpiry(proposalId, args) {
+    const { proposalStore, expectedAccountId, graceSeconds = 0, now } = args;
+    const record = await proposalStore.get(proposalId, { expectedAccountId });
+    if (!record) {
+        throw new async_outcome_1.AdcpError('PROPOSAL_NOT_FOUND', {
+            recovery: 'terminal',
+            message: `Proposal ${JSON.stringify(proposalId)} not found. The buyer must call get_products ` +
+                `with buying_mode='refine' and refine=[{action:'finalize',...}] to obtain a ` +
+                `committed proposal_id before referencing it on create_media_buy.`,
+            field: 'proposal_id',
+        });
+    }
+    if (record.state !== 'committed') {
+        throw new async_outcome_1.AdcpError('PROPOSAL_NOT_COMMITTED', {
+            recovery: 'correctable',
+            message: `Proposal ${JSON.stringify(proposalId)} is in state ${JSON.stringify(record.state)}; ` +
+                `only committed proposals can be accepted via create_media_buy. Call get_products ` +
+                `with buying_mode='refine' and action='finalize' first.`,
+            field: 'proposal_id',
+        });
+    }
+    if (record.expiresAt) {
+        const current = now ?? new Date();
+        const deadline = record.expiresAt.getTime() + graceSeconds * 1000;
+        if (current.getTime() > deadline) {
+            logExpired({
+                proposalId,
+                accountId: record.accountId,
+                now: current,
+                expiresAt: record.expiresAt,
+                graceSeconds,
+            });
+            throw new async_outcome_1.AdcpError('PROPOSAL_EXPIRED', {
+                // Per AdCP 3.0.6 schemas/cache/3.0.6/enums/error-code.json,
+                // PROPOSAL_EXPIRED is `correctable` — the buyer re-discovers
+                // via `get_products` to obtain a fresh proposal (the hold
+                // window has lapsed but the buyer can re-request).
+                recovery: 'correctable',
+                message: `Proposal ${JSON.stringify(proposalId)} expired at ${record.expiresAt.toISOString()}; ` +
+                    `create_media_buy must be called within the inventory hold window. Call get_products ` +
+                    `with buying_mode='refine' and action='finalize' to request a fresh hold.`,
+                field: 'proposal_id',
+            });
+        }
+    }
+    return record;
+}
+/**
+ * Pre-adapter validation seam: walk buyer's packages against each recipe's
+ * `capability_overlap` and reject mismatches.
+ *
+ * Called from the framework's `create_media_buy` and `update_media_buy`
+ * dispatch paths after recipes are hydrated from the {@link ProposalStore}.
+ * Per D4, the framework owns this gate so every adopter doesn't write the
+ * same intersection logic.
+ *
+ * Validation axes (per {@link CapabilityOverlap}):
+ *
+ *   - `pricingModels` — checked against `package._resolved_pricing_model`
+ *     or `package.pricing_model`.
+ *   - `targetingDimensions` — checked against `package.targeting_overlay` keys.
+ *   - `deliveryTypes` — checked against `package._resolved_delivery_type`
+ *     or `package.delivery_type`.
+ *   - `signalTypes` — checked against `package.signal_type`.
+ *
+ * Per the design's undefined-vs-empty-set semantics: `undefined` skips the
+ * gate; an explicit `Set` (including the empty set) is enforced.
+ *
+ * @public
+ */
+function validateCapabilityOverlap(args) {
+    const { packages, recipes, fieldPathPrefix = 'packages' } = args;
+    for (let i = 0; i < packages.length; i++) {
+        const pkg = packages[i];
+        const productId = pkg.product_id;
+        if (!productId)
+            continue;
+        const recipe = recipes.get(productId);
+        if (!recipe || !recipe.capability_overlap)
+            continue;
+        const overlap = recipe.capability_overlap;
+        if (overlap.pricingModels) {
+            const requested = pkg._resolved_pricing_model ?? pkg.pricing_model;
+            if (requested !== undefined && !overlap.pricingModels.has(String(requested))) {
+                throw new async_outcome_1.AdcpError('INVALID_REQUEST', {
+                    recovery: 'terminal',
+                    message: `Buyer requested pricing_model=${JSON.stringify(requested)} on package ` +
+                        `${JSON.stringify(productId)}, but this product's recipe declares ` +
+                        `capability_overlap.pricingModels=${JSON.stringify([...overlap.pricingModels].sort())}. ` +
+                        `The seller did not enable that pricing model for this product.`,
+                    field: `${fieldPathPrefix}[${i}].pricing_option_id`,
+                });
+            }
+        }
+        if (overlap.targetingDimensions) {
+            const overlay = pkg.targeting_overlay;
+            const keys = overlay && typeof overlay === 'object' ? Object.keys(overlay) : [];
+            const disallowed = keys.filter(k => !overlap.targetingDimensions.has(k));
+            if (disallowed.length > 0) {
+                throw new async_outcome_1.AdcpError('INVALID_REQUEST', {
+                    recovery: 'terminal',
+                    message: `Buyer requested targeting dimensions ${JSON.stringify(disallowed.sort())} on ` +
+                        `package ${JSON.stringify(productId)}, but this product's recipe declares ` +
+                        `capability_overlap.targetingDimensions=` +
+                        `${JSON.stringify([...overlap.targetingDimensions].sort())}. The seller did not ` +
+                        `enable those targeting dimensions for this product.`,
+                    field: `${fieldPathPrefix}[${i}].targeting_overlay`,
+                });
+            }
+        }
+        if (overlap.deliveryTypes) {
+            const delivery = pkg._resolved_delivery_type ?? pkg.delivery_type;
+            if (delivery !== undefined && !overlap.deliveryTypes.has(String(delivery))) {
+                throw new async_outcome_1.AdcpError('INVALID_REQUEST', {
+                    recovery: 'terminal',
+                    message: `Buyer requested delivery_type=${JSON.stringify(delivery)} on package ` +
+                        `${JSON.stringify(productId)}, but this product's recipe declares ` +
+                        `capability_overlap.deliveryTypes=${JSON.stringify([...overlap.deliveryTypes].sort())}.`,
+                    field: `${fieldPathPrefix}[${i}].delivery_type`,
+                });
+            }
+        }
+        if (overlap.signalTypes) {
+            const signalType = pkg.signal_type;
+            if (signalType !== undefined && !overlap.signalTypes.has(String(signalType))) {
+                throw new async_outcome_1.AdcpError('INVALID_REQUEST', {
+                    recovery: 'terminal',
+                    message: `Buyer requested signal_type=${JSON.stringify(signalType)} on package ` +
+                        `${JSON.stringify(productId)}, but this product's recipe declares ` +
+                        `capability_overlap.signalTypes=${JSON.stringify([...overlap.signalTypes].sort())}.`,
+                    field: `${fieldPathPrefix}[${i}].signal_type`,
+                });
+            }
+        }
+    }
+}
+/**
+ * Validate `recipe.capability_overlap` is a subset of the matching product's
+ * wire-declared capabilities.
+ *
+ * Called at `putDraft` time. Mismatches throw `INTERNAL_ERROR` — this is
+ * an adopter bug (the manager declared an overlap claiming capabilities the
+ * wire shape doesn't advertise), not a buyer bug.
+ *
+ * @public
+ */
+function validateOverlapSubsetOfWire(args) {
+    const productsById = new Map();
+    for (const p of args.products) {
+        if (p.product_id)
+            productsById.set(p.product_id, p);
+    }
+    for (const [productId, recipe] of args.recipes) {
+        if (!recipe.capability_overlap)
+            continue;
+        const product = productsById.get(productId);
+        if (!product)
+            continue; // missing-product is caught elsewhere
+        const overlap = recipe.capability_overlap;
+        if (overlap.pricingModels) {
+            const wirePricing = wirePricingModels(product);
+            const extras = [...overlap.pricingModels].filter(p => !wirePricing.has(p));
+            if (extras.length > 0) {
+                throw new async_outcome_1.AdcpError('INTERNAL_ERROR', {
+                    recovery: 'terminal',
+                    message: `Recipe for product ${JSON.stringify(productId)} declares ` +
+                        `capability_overlap.pricingModels=${JSON.stringify([...overlap.pricingModels].sort())} ` +
+                        `including ${JSON.stringify(extras.sort())}, but the wire product only advertises ` +
+                        `${JSON.stringify([...wirePricing].sort())}. The recipe's overlap must be a subset ` +
+                        `of the wire-declared capabilities; adopter declaration is inconsistent with the ` +
+                        `product shape.`,
+                });
+            }
+        }
+        if (overlap.deliveryTypes) {
+            const wireDelivery = wireDeliveryTypes(product);
+            const extras = [...overlap.deliveryTypes].filter(p => !wireDelivery.has(p));
+            // Only enforce when the wire declares something — products lacking a
+            // delivery_type field shouldn't trip the gate.
+            if (extras.length > 0 && wireDelivery.size > 0) {
+                throw new async_outcome_1.AdcpError('INTERNAL_ERROR', {
+                    recovery: 'terminal',
+                    message: `Recipe for product ${JSON.stringify(productId)} declares ` +
+                        `capability_overlap.deliveryTypes=${JSON.stringify([...overlap.deliveryTypes].sort())} ` +
+                        `including ${JSON.stringify(extras.sort())}, but the wire product only advertises ` +
+                        `${JSON.stringify([...wireDelivery].sort())}.`,
+                });
+            }
+        }
+    }
+}
+function wirePricingModels(product) {
+    const out = new Set();
+    const pricing = product.pricing_options;
+    if (!pricing)
+        return out;
+    for (const opt of pricing) {
+        if (opt.pricing_model)
+            out.add(String(opt.pricing_model));
+    }
+    return out;
+}
+function wireDeliveryTypes(product) {
+    const dt = product.delivery_type;
+    return dt ? new Set([String(dt)]) : new Set();
+}
+/**
+ * Return the first finalize-action refine entry from a
+ * `GetProductsRequest`, or `null` if no finalize entry exists.
+ *
+ * The index points at the entry's position in `refine[]` so the framework
+ * can produce indexed wire field paths (`refine[3].proposal_id`) on
+ * rejection — buyers parsing the error get a precise pointer.
+ *
+ * Per the spec, `buying_mode: 'refine'` carries a `refine[]` array of
+ * entries. Each entry has a `scope` (`request` / `product` / `proposal`)
+ * and an optional `action` (`include` / `omit` / `finalize`). v1.5 only
+ * intercepts `proposal`-scoped entries with `action: 'finalize'`.
+ *
+ * The framework processes ONE finalize entry per request; if the buyer
+ * sends multiple finalize entries, only the first is processed (rest fall
+ * through to the standard refine path).
+ *
+ * @public
+ */
+function detectFinalizeAction(req) {
+    const refine = req.refine;
+    if (!refine || refine.length === 0)
+        return null;
+    for (let index = 0; index < refine.length; index++) {
+        const entry = refine[index];
+        if (entry.scope === 'proposal' && entry.action === 'finalize') {
+            const proposalId = entry.proposal_id;
+            if (typeof proposalId === 'string' && proposalId.length > 0) {
+                const ask = typeof entry.ask === 'string' ? entry.ask : undefined;
+                return ask !== undefined ? { index, proposalId, ask } : { index, proposalId };
+            }
+        }
+    }
+    return null;
+}
+let logger = {
+    info: (message, fields) => {
+        if (fields) {
+            console.log(JSON.stringify({ message, ...fields }));
+        }
+        else {
+            console.log(message);
+        }
+    },
+};
+/**
+ * Replace the module-level logger that proposal-lifecycle structured
+ * events (`proposal.draft_persisted`, `proposal.finalized`, `proposal.expired`,
+ * `proposal.consumed`) emit through. Adopters wire this to their existing
+ * logger (pino, bunyan, etc.) so lifecycle events route through the same
+ * pipeline as the rest of their server logs. Tests use it to capture
+ * structured emissions for assertion.
+ *
+ * @public
+ */
+function setProposalLifecycleLogger(next) {
+    logger = next;
+}
+/** `proposal.draft_persisted` event. */
+function logDraftPersisted(args) {
+    logger.info('proposal.draft_persisted', {
+        event: 'proposal.draft_persisted',
+        proposal_id: args.proposalId,
+        account_id: args.accountId,
+        recipes_count: args.recipesCount,
+    });
+}
+/**
+ * `proposal.finalized` event. `path` is `'inline'` or `'handoff'`.
+ */
+function logFinalizeSucceeded(args) {
+    logger.info('proposal.finalized', {
+        event: 'proposal.finalized',
+        proposal_id: args.proposalId,
+        account_id: args.accountId,
+        expires_at: args.expiresAt.toISOString(),
+        path: args.path,
+    });
+}
+/** `proposal.expired` event. */
+function logExpired(args) {
+    logger.info('proposal.expired', {
+        event: 'proposal.expired',
+        proposal_id: args.proposalId,
+        account_id: args.accountId,
+        now: args.now.toISOString(),
+        expires_at: args.expiresAt.toISOString(),
+        grace_seconds: args.graceSeconds,
+    });
+}
+/** `proposal.consumed` event. */
+function logConsumed(args) {
+    logger.info('proposal.consumed', {
+        event: 'proposal.consumed',
+        proposal_id: args.proposalId,
+        account_id: args.accountId,
+        media_buy_id: args.mediaBuyId,
+    });
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/lib/server/decisioning/proposal/lifecycle.js.map

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

package/dist/lib/server/decisioning/proposal/mock-manager.d.ts

@@ -0,0 +1,93 @@
+/**
+ * MockProposalManager — v1 default forwarder.
+ *
+ * Symmetric with the mock-mode dispatch pattern adopters use to point
+ * `DecisioningPlatform` upstreams at a running `bin/adcp.js mock-server`.
+ * Adopters who don't yet have proposal logic of their own start with this
+ * class pointed at the appropriate mock-server specialism; their first
+ * working seller agent runs against the mock fixtures with zero adopter
+ * code on the proposal side. They implement their own
+ * {@link ProposalManager} subtype incrementally as they replace
+ * mock-served slices with real assembly logic.
+ *
+ * The mock-server lifecycle is **not** managed by the SDK. Adopters or CI
+ * start it as needed (`bin/adcp.js mock-server sales-non-guaranteed`) and
+ * pass the resulting URL to this class's constructor.
+ *
+ * Ports `adcp-client-python.src/adcp/decisioning/proposal_manager.py`'s
+ * `MockProposalManager` (PR #504).
+ *
+ * **Runtime requirement**: uses `globalThis.fetch`, which lands as a built-in
+ * on Node 18+ (the package declares `"engines": { "node": ">=18.0.0" }`).
+ * Adopters running on older Node, on Bun without the global, or in any
+ * environment without a global `fetch` should pass an explicit `fetch`
+ * implementation via the `fetch` constructor option.
+ *
+ * @public
+ * @packageDocumentation
+ */
+import type { Account } from '../account';
+import type { RequestContext } from '../context';
+import type { GetProductsRequest, GetProductsResponse } from '../../../types/tools.generated';
+import type { ProposalCapabilities, ProposalManager, ProposalSalesSpecialism, Recipe } from './types';
+/**
+ * Construction options for {@link MockProposalManager}.
+ *
+ * @public
+ */
+export interface MockProposalManagerOptions {
+    /**
+     * URL of the running mock-server. The forwarder POSTs
+     * `GetProductsRequest` payloads to `${mockUpstreamUrl}/get_products`
+     * and (when refine is enabled) `${mockUpstreamUrl}/refine_products`.
+     *
+     * Required and non-empty.
+     */
+    mockUpstreamUrl: string;
+    /**
+     * Which sales specialism this mock manager serves. Defaults to
+     * `sales-non-guaranteed` (the catalog-style mock-server fixture).
+     * Adopters wiring a guaranteed mock pass `sales-guaranteed` so the
+     * framework's capability projection matches the fixtures.
+     */
+    salesSpecialism?: ProposalSalesSpecialism;
+    /**
+     * When true, the manager declares `refine` capability and forwards
+     * `buying_mode: 'refine'` requests to `/refine_products`. Default
+     * false — the framework falls through to `getProducts` for refine.
+     */
+    refine?: boolean;
+    /**
+     * Headers forwarded on every mock-server request (e.g. `X-Tenant-Id`).
+     */
+    defaultHeaders?: Readonly<Record<string, string>>;
+    /**
+     * Per-request timeout in milliseconds. Default 30 seconds.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional `fetch` override for testing. Defaults to the global
+     * `fetch` (Node 18+).
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * v1 default forwarder. Dispatches `getProducts` / `refineProducts` to
+ * a running mock-server.
+ *
+ * @public
+ */
+export declare class MockProposalManager<TRecipe extends Recipe = Recipe, TCtxMeta = unknown> implements ProposalManager<TRecipe, TCtxMeta> {
+    readonly capabilities: ProposalCapabilities;
+    private readonly url;
+    private readonly headers;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: MockProposalManagerOptions);
+    /** The configured mock-server URL — useful for diagnostics. */
+    get mockUpstreamUrl(): string;
+    getProducts(req: GetProductsRequest, _ctx: RequestContext<Account<TCtxMeta>>): Promise<GetProductsResponse>;
+    refineProducts(req: GetProductsRequest, _ctx: RequestContext<Account<TCtxMeta>>): Promise<GetProductsResponse>;
+    private forward;
+}
+//# sourceMappingURL=mock-manager.d.ts.map