@adcp/sdk 5.23.0

package/dist/lib/utils/pricing-adapter.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * Pricing Option Adapter
+ *
+ * Handles conversion between v2.x and v3 pricing option field names.
+ * The library exposes only v3 API (fixed_price, floor_price) to clients,
+ * and internally adapts requests for v2.x servers.
+ *
+ * Field mappings:
+ * - v3 fixed_price ↔ v2 rate (for fixed pricing)
+ * - v3 floor_price ↔ v2 price_guidance.floor (for auction pricing)
+ * - v3 presence of fixed_price ↔ v2 is_fixed: true/false
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.usesV2PricingFields = usesV2PricingFields;
+exports.usesV3PricingFields = usesV3PricingFields;
+exports.isFixedPricing = isFixedPricing;
+exports.isCPAPricing = isCPAPricing;
+exports.getPrice = getPrice;
+exports.getFloorPrice = getFloorPrice;
+exports.adaptPricingOptionForV2 = adaptPricingOptionForV2;
+exports.normalizePricingOption = normalizePricingOption;
+exports.adaptProductPricingForV2 = adaptProductPricingForV2;
+exports.normalizeProductPricing = normalizeProductPricing;
+exports.adaptGetProductsRequestForV2 = adaptGetProductsRequestForV2;
+exports.normalizeProductChannels = normalizeProductChannels;
+exports.normalizeGetProductsResponse = normalizeGetProductsResponse;
+exports.adaptPackagePricingForV2 = adaptPackagePricingForV2;
+exports.adaptMediaBuyPricingForV2 = adaptMediaBuyPricingForV2;
+exports.normalizeMediaBuyPricingResponse = normalizeMediaBuyPricingResponse;
+/**
+ * Check if a pricing option uses v2 field names
+ */
+function usesV2PricingFields(option) {
+    if (!option || typeof option !== 'object')
+        return false;
+    // v2 uses 'rate' or 'is_fixed' or has floor inside price_guidance
+    return option.rate !== undefined || option.is_fixed !== undefined || option.price_guidance?.floor !== undefined;
+}
+/**
+ * Check if a pricing option uses v3 field names
+ */
+function usesV3PricingFields(option) {
+    if (!option || typeof option !== 'object')
+        return false;
+    // v3 uses fixed_price or floor_price at top level
+    return option.fixed_price !== undefined || option.floor_price !== undefined;
+}
+/**
+ * Detect if a pricing option is fixed pricing (works with v2 or v3)
+ */
+function isFixedPricing(option) {
+    // v3: presence of fixed_price indicates fixed pricing
+    if (option.fixed_price !== undefined) {
+        return true;
+    }
+    // v2: is_fixed boolean
+    if (option.is_fixed !== undefined) {
+        return option.is_fixed;
+    }
+    // v2: presence of rate without is_fixed defaults to fixed
+    if (option.rate !== undefined) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Detect if a pricing option is CPA (cost per acquisition) pricing
+ */
+function isCPAPricing(option) {
+    return option?.pricing_model === 'cpa';
+}
+/**
+ * Get the price value from a pricing option (works with v2 or v3)
+ */
+function getPrice(option) {
+    // v3 field takes precedence
+    if (option.fixed_price !== undefined) {
+        return option.fixed_price;
+    }
+    // Fall back to v2 field
+    return option.rate;
+}
+/**
+ * Get the floor price from a pricing option (works with v2 or v3)
+ */
+function getFloorPrice(option) {
+    // v3 field takes precedence
+    if (option.floor_price !== undefined) {
+        return option.floor_price;
+    }
+    // Fall back to v2 field (inside price_guidance)
+    return option.price_guidance?.floor;
+}
+/**
+ * Adapt a v3-style pricing option for a v2 server.
+ * Converts fixed_price → rate, floor_price → price_guidance.floor
+ */
+function adaptPricingOptionForV2(option) {
+    // Already v2 format or no v3 fields
+    if (!usesV3PricingFields(option)) {
+        return option;
+    }
+    const { fixed_price, floor_price, price_guidance, ...rest } = option;
+    const result = { ...rest };
+    if (fixed_price !== undefined) {
+        // Fixed pricing
+        result.rate = fixed_price;
+        result.is_fixed = true;
+    }
+    else {
+        // Auction pricing
+        result.is_fixed = false;
+        // Build v2 price_guidance with floor inside
+        if (floor_price !== undefined || price_guidance) {
+            result.price_guidance = {
+                ...(price_guidance || {}),
+            };
+            if (floor_price !== undefined) {
+                result.price_guidance.floor = floor_price;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Normalize a v2-style pricing option to v3.
+ * Converts rate → fixed_price, price_guidance.floor → floor_price
+ */
+function normalizePricingOption(option) {
+    // Already v3 format
+    if (usesV3PricingFields(option) && !usesV2PricingFields(option)) {
+        return option;
+    }
+    const v2Option = option;
+    const { rate, is_fixed, price_guidance, ...rest } = v2Option;
+    const result = { ...rest };
+    // Convert rate → fixed_price (for fixed pricing)
+    if (rate !== undefined && (is_fixed === true || is_fixed === undefined)) {
+        result.fixed_price = rate;
+    }
+    // Convert price_guidance.floor → floor_price (for auction pricing)
+    if (price_guidance) {
+        const { floor, ...percentiles } = price_guidance;
+        if (floor !== undefined) {
+            result.floor_price = floor;
+        }
+        // Keep percentiles in price_guidance if any exist
+        if (Object.keys(percentiles).length > 0) {
+            result.price_guidance = percentiles;
+        }
+    }
+    return result;
+}
+/**
+ * Adapt all pricing options in a product for v2 server
+ */
+function adaptProductPricingForV2(product) {
+    if (!product?.pricing_options || !Array.isArray(product.pricing_options)) {
+        return product;
+    }
+    return {
+        ...product,
+        pricing_options: product.pricing_options.map(adaptPricingOptionForV2),
+    };
+}
+/**
+ * Normalize all pricing options in a product to v3
+ */
+function normalizeProductPricing(product) {
+    if (!product?.pricing_options || !Array.isArray(product.pricing_options)) {
+        return product;
+    }
+    return {
+        ...product,
+        pricing_options: product.pricing_options.map(normalizePricingOption),
+    };
+}
+/**
+ * Adapt a get_products request for a v2 server.
+ *
+ * Converts v3 fields to their v2 equivalents:
+ * - brand (BrandReference) → brand_manifest (base domain URL string)
+ * - catalog → promoted_offerings (type='offering') or promoted_offerings.product_selectors (type='product')
+ * - channels in filters → v2 channel names
+ *
+ * Strips v3-only fields v2 agents don't understand:
+ * - buying_mode, buyer_campaign_ref, property_list, account_id, pagination (top-level)
+ * - filters: required_features, required_axe_integrations, required_geo_targeting,
+ *            signal_targeting, regions, metros
+ */
+function adaptGetProductsRequestForV2(request) {
+    const adapted = { ...request };
+    // Convert v3 brand (BrandReference) → v2 brand_manifest (bare domain URL).
+    // v2 servers resolve brand info from the base domain URL.
+    if (adapted.brand?.domain) {
+        adapted.brand_manifest = `https://${adapted.brand.domain}`;
+        delete adapted.brand;
+    }
+    // Convert v3 catalog → v2 promoted_offerings
+    if (adapted.catalog) {
+        const catalog = adapted.catalog;
+        if (catalog.type === 'product') {
+            adapted.promoted_offerings = {
+                product_selectors: {
+                    ...(catalog.gtins?.length && { manifest_gtins: catalog.gtins }),
+                    ...(catalog.ids?.length && { manifest_skus: catalog.ids }),
+                    ...(catalog.tags?.length && { manifest_tags: catalog.tags }),
+                    ...(catalog.category && { manifest_category: catalog.category }),
+                    ...(catalog.query && { manifest_query: catalog.query }),
+                },
+            };
+        }
+        else if (catalog.type === 'offering') {
+            adapted.promoted_offerings = {
+                ...(catalog.items?.length && { offerings: catalog.items }),
+            };
+        }
+        delete adapted.catalog;
+    }
+    // Map v3 channel names to v2 equivalents
+    if (adapted.filters?.channels) {
+        const v2ChannelMap = {
+            olv: 'video',
+            ctv: 'video',
+            streaming_audio: 'audio',
+            retail_media: 'retail',
+        };
+        // Deduplicate after mapping (e.g. olv+ctv both become 'video')
+        const mapped = adapted.filters.channels.map((ch) => v2ChannelMap[ch] ?? ch);
+        adapted.filters = {
+            ...adapted.filters,
+            channels: [...new Set(mapped)],
+        };
+    }
+    // Strip v3-only filter fields (format_ids exists in both v2 and v3, keep it)
+    if (adapted.filters) {
+        const { required_features, required_axe_integrations, required_geo_targeting, signal_targeting, regions, metros, ...v2Filters } = adapted.filters;
+        adapted.filters = v2Filters;
+    }
+    // Strip v3-only top-level fields
+    delete adapted.buying_mode;
+    delete adapted.buyer_campaign_ref;
+    delete adapted.property_list;
+    delete adapted.account;
+    delete adapted.pagination;
+    delete adapted.adcp_major_version;
+    return adapted;
+}
+/**
+ * Normalize v2 channel names on a product to v3.
+ * v2 used coarser buckets; some map one-to-many (e.g. 'video' → ['olv', 'ctv']).
+ */
+function normalizeProductChannels(product) {
+    if (!product?.channels || !Array.isArray(product.channels)) {
+        return product;
+    }
+    const v3ChannelMap = {
+        video: ['olv', 'ctv'],
+        audio: ['streaming_audio'],
+        native: ['display'],
+        retail: ['retail_media'],
+    };
+    const normalized = product.channels.flatMap((ch) => v3ChannelMap[ch] ?? [ch]);
+    return { ...product, channels: [...new Set(normalized)] };
+}
+/**
+ * Normalize all products in a get_products response to v3
+ */
+function normalizeGetProductsResponse(response) {
+    // If there's no products field at all, this may be an error response — pass through
+    if (!('products' in (response ?? {}))) {
+        return response;
+    }
+    // If products exists but isn't an array, the response is malformed
+    if (!Array.isArray(response.products)) {
+        return {
+            errors: [
+                {
+                    code: 'invalid_response',
+                    message: `Expected products to be an array, got ${typeof response.products}`,
+                },
+            ],
+        };
+    }
+    return {
+        ...response,
+        products: response.products.map((p) => normalizeProductChannels(normalizeProductPricing(p))),
+    };
+}
+/**
+ * Adapt a package request's pricing option selection for v2 server.
+ * This handles bid_price which references pricing option floor semantics.
+ */
+function adaptPackagePricingForV2(pkg) {
+    // Package requests don't typically contain pricing_options,
+    // but they do contain pricing_option_id which selects one.
+    // No transformation needed for bid_price - it's the same in both versions.
+    return pkg;
+}
+/**
+ * Adapt a create_media_buy request for v2 server (pricing fields)
+ */
+function adaptMediaBuyPricingForV2(request) {
+    // Media buy requests select pricing options by ID, not by defining them.
+    // No pricing field transformation needed in requests.
+    return request;
+}
+/**
+ * Normalize a media buy response's package pricing to v3
+ */
+function normalizeMediaBuyPricingResponse(response) {
+    // Media buy responses may include products with pricing_options
+    if (response?.products && Array.isArray(response.products)) {
+        return {
+            ...response,
+            products: response.products.map(normalizeProductPricing),
+        };
+    }
+    return response;
+}
+//# sourceMappingURL=pricing-adapter.js.map

package/dist/lib/utils/pricing-adapter.js.map

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

package/dist/lib/utils/protocol-detection.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Protocol Detection Utilities
+ *
+ * Auto-detects whether an agent endpoint uses MCP or A2A protocol
+ */
+/**
+ * Detect protocol for a given agent URL
+ *
+ * Uses a hybrid approach:
+ * 1. Check URL patterns (fast heuristic)
+ * 2. Try A2A discovery endpoints (authoritative)
+ * 3. Default to MCP if A2A discovery fails
+ *
+ * @param url Agent URL to check
+ * @returns Promise resolving to 'a2a' or 'mcp'
+ */
+export declare function detectProtocol(url: string): Promise<'a2a' | 'mcp'>;
+/**
+ * Detect protocol with custom timeout
+ *
+ * @param url Agent URL to check
+ * @param timeoutMs Timeout in milliseconds (default: 5000)
+ * @returns Promise resolving to 'a2a' or 'mcp'
+ */
+export declare function detectProtocolWithTimeout(url: string, timeoutMs?: number): Promise<'a2a' | 'mcp'>;
+//# sourceMappingURL=protocol-detection.d.ts.map

package/dist/lib/utils/protocol-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-detection.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/protocol-detection.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,CAExE;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,CAE7G"}

package/dist/lib/utils/protocol-detection.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Protocol Detection Utilities
+ *
+ * Auto-detects whether an agent endpoint uses MCP or A2A protocol
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectProtocol = detectProtocol;
+exports.detectProtocolWithTimeout = detectProtocolWithTimeout;
+const a2a_discovery_1 = require("./a2a-discovery");
+/**
+ * Detect protocol for a given agent URL
+ *
+ * Uses a hybrid approach:
+ * 1. Check URL patterns (fast heuristic)
+ * 2. Try A2A discovery endpoints (authoritative)
+ * 3. Default to MCP if A2A discovery fails
+ *
+ * @param url Agent URL to check
+ * @returns Promise resolving to 'a2a' or 'mcp'
+ */
+async function detectProtocol(url) {
+    return detectA2AOrMcp(url, 5000);
+}
+/**
+ * Detect protocol with custom timeout
+ *
+ * @param url Agent URL to check
+ * @param timeoutMs Timeout in milliseconds (default: 5000)
+ * @returns Promise resolving to 'a2a' or 'mcp'
+ */
+async function detectProtocolWithTimeout(url, timeoutMs = 5000) {
+    return detectA2AOrMcp(url, timeoutMs);
+}
+async function detectA2AOrMcp(url, timeoutMs) {
+    if (url.endsWith('/mcp/') || url.endsWith('/mcp')) {
+        return 'mcp';
+    }
+    for (const path of a2a_discovery_1.A2A_CARD_PATHS) {
+        try {
+            const discoveryUrl = new URL(path, url);
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+            const response = await fetch(discoveryUrl.toString(), {
+                method: 'GET',
+                signal: controller.signal,
+                headers: {
+                    Accept: 'application/json, */*',
+                },
+            });
+            clearTimeout(timeoutId);
+            if (response.ok) {
+                return 'a2a';
+            }
+        }
+        catch (error) {
+            // Fetch failed - try next path
+        }
+    }
+    return 'mcp';
+}
+//# sourceMappingURL=protocol-detection.js.map

package/dist/lib/utils/protocol-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-detection.js","sourceRoot":"","sources":["../../../src/lib/utils/protocol-detection.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAeH,wCAEC;AASD,8DAEC;AA1BD,mDAAiD;AAEjD;;;;;;;;;;GAUG;AACI,KAAK,UAAU,cAAc,CAAC,GAAW;IAC9C,OAAO,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,yBAAyB,CAAC,GAAW,EAAE,YAAoB,IAAI;IACnF,OAAO,cAAc,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;AACxC,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,GAAW,EAAE,SAAiB;IAC1D,IAAI,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,8BAAc,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACxC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;YAElE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,QAAQ,EAAE,EAAE;gBACpD,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,UAAU,CAAC,MAAM;gBACzB,OAAO,EAAE;oBACP,MAAM,EAAE,uBAAuB;iBAChC;aACF,CAAC,CAAC;YAEH,YAAY,CAAC,SAAS,CAAC,CAAC;YAExB,IAAI,QAAQ,CAAC,EAAE,EAAE,CAAC;gBAChB,OAAO,KAAK,CAAC;YACf,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,+BAA+B;QACjC,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/lib/utils/render-builders.d.ts

@@ -0,0 +1,41 @@
+import type { PreviewRender } from '../types/core.generated';
+type UrlRender = Extract<PreviewRender, {
+    output_format: 'url';
+}>;
+type HtmlRender = Extract<PreviewRender, {
+    output_format: 'html';
+}>;
+type BothRender = Extract<PreviewRender, {
+    output_format: 'both';
+}>;
+type Tagged<T, Tag extends string> = Omit<T, 'output_format'> & {
+    output_format: Tag;
+};
+/**
+ * Build a url-variant `PreviewRender` with `output_format: 'url'` injected.
+ *
+ * Requires `preview_url` — you can't call this without the field the `url`
+ * discriminator makes required, which is the whole point of the helper.
+ */
+export declare function urlRender(fields: Omit<UrlRender, 'output_format'>): Tagged<UrlRender, 'url'>;
+/**
+ * Build an html-variant `PreviewRender` with `output_format: 'html'` injected.
+ */
+export declare function htmlRender(fields: Omit<HtmlRender, 'output_format'>): Tagged<HtmlRender, 'html'>;
+/**
+ * Build a both-variant `PreviewRender` with `output_format: 'both'` injected.
+ * Requires both `preview_url` and `preview_html`.
+ */
+export declare function bothRender(fields: Omit<BothRender, 'output_format'>): Tagged<BothRender, 'both'>;
+/**
+ * Grouped namespace over the same helpers, useful when constructing a
+ * `renders[]` that mixes variants. Prefer the named exports at single
+ * call sites; use `Render.url({...})` when building several types together.
+ */
+export declare const Render: {
+    readonly url: typeof urlRender;
+    readonly html: typeof htmlRender;
+    readonly both: typeof bothRender;
+};
+export {};
+//# sourceMappingURL=render-builders.d.ts.map

package/dist/lib/utils/render-builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-builders.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/render-builders.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,KAAK,SAAS,GAAG,OAAO,CAAC,aAAa,EAAE;IAAE,aAAa,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAClE,KAAK,UAAU,GAAG,OAAO,CAAC,aAAa,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AACpE,KAAK,UAAU,GAAG,OAAO,CAAC,aAAa,EAAE;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEpE,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,SAAS,MAAM,IAAI,IAAI,CAAC,CAAC,EAAE,eAAe,CAAC,GAAG;IAAE,aAAa,EAAE,GAAG,CAAA;CAAE,CAAC;AAEvF;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,GAAG,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAE5F;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAEhG;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAEhG;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM;;;;CAIT,CAAC"}

package/dist/lib/utils/render-builders.js

@@ -0,0 +1,52 @@
+"use strict";
+// Typed factory helpers for `preview_creative` render objects.
+//
+// `PreviewRender` is a `oneOf` union on `output_format` — three variants:
+//   `url` requires `preview_url`, `html` requires `preview_html`, `both`
+//   requires both. The discriminator decides which field becomes required,
+//   but nothing forces the caller to set it correctly. Matrix runs
+//   repeatedly surfaced renders missing `preview_url` or `output_format`
+//   because an agent wrote the object shape by hand.
+//
+// These builders mirror `imageAsset` / `videoAsset` / etc.: the caller
+// passes the payload fields and the helper injects the discriminator.
+// Spread order places the discriminator last so a runtime cast cannot
+// overwrite the canonical tag.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Render = void 0;
+exports.urlRender = urlRender;
+exports.htmlRender = htmlRender;
+exports.bothRender = bothRender;
+/**
+ * Build a url-variant `PreviewRender` with `output_format: 'url'` injected.
+ *
+ * Requires `preview_url` — you can't call this without the field the `url`
+ * discriminator makes required, which is the whole point of the helper.
+ */
+function urlRender(fields) {
+    return { ...fields, output_format: 'url' };
+}
+/**
+ * Build an html-variant `PreviewRender` with `output_format: 'html'` injected.
+ */
+function htmlRender(fields) {
+    return { ...fields, output_format: 'html' };
+}
+/**
+ * Build a both-variant `PreviewRender` with `output_format: 'both'` injected.
+ * Requires both `preview_url` and `preview_html`.
+ */
+function bothRender(fields) {
+    return { ...fields, output_format: 'both' };
+}
+/**
+ * Grouped namespace over the same helpers, useful when constructing a
+ * `renders[]` that mixes variants. Prefer the named exports at single
+ * call sites; use `Render.url({...})` when building several types together.
+ */
+exports.Render = {
+    url: urlRender,
+    html: htmlRender,
+    both: bothRender,
+};
+//# sourceMappingURL=render-builders.js.map

package/dist/lib/utils/render-builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-builders.js","sourceRoot":"","sources":["../../../src/lib/utils/render-builders.ts"],"names":[],"mappings":";AAAA,+DAA+D;AAC/D,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,2EAA2E;AAC3E,mEAAmE;AACnE,yEAAyE;AACzE,qDAAqD;AACrD,EAAE;AACF,uEAAuE;AACvE,sEAAsE;AACtE,sEAAsE;AACtE,+BAA+B;;;AAgB/B,8BAEC;AAKD,gCAEC;AAMD,gCAEC;AAvBD;;;;;GAKG;AACH,SAAgB,SAAS,CAAC,MAAwC;IAChE,OAAO,EAAE,GAAG,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,SAAgB,UAAU,CAAC,MAAyC;IAClE,OAAO,EAAE,GAAG,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,SAAgB,UAAU,CAAC,MAAyC;IAClE,OAAO,EAAE,GAAG,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACU,QAAA,MAAM,GAAG;IACpB,GAAG,EAAE,SAAS;IACd,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;CACR,CAAC"}

package/dist/lib/utils/request-normalizer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Request parameter normalization for backward compatibility.
+ *
+ * Converts deprecated field names and shapes so callers written against
+ * earlier schema versions keep working. Each conversion emits a one-time
+ * deprecation warning via warnOnce().
+ */
+/**
+ * Normalize a single package's params for backward compatibility.
+ *
+ * Handles:
+ * - context.buyer_ref → buyer_ref (pre-4.15 servers require top-level buyer_ref)
+ * - optimization_goal (scalar) → optimization_goals (array)
+ * - catalog (scalar object) → catalogs (array)
+ */
+export declare function normalizePackageParams(pkg: any): any;
+/**
+ * Normalize request params for backward compatibility.
+ *
+ * Infers missing fields that can be derived from deprecated params so callers
+ * written against older schema versions keep working.
+ */
+export declare function normalizeRequestParams(taskType: string, params: any, opts?: {
+    skipIdempotencyAutoInject?: boolean;
+}): any;
+//# sourceMappingURL=request-normalizer.d.ts.map

package/dist/lib/utils/request-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-normalizer.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/request-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,CA8BpD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,GAAG,EACX,IAAI,GAAE;IAAE,yBAAyB,CAAC,EAAE,OAAO,CAAA;CAAO,GACjD,GAAG,CAkJL"}