@adcp/sdk 5.23.0

package/dist/lib/substitution/observer/SubstitutionObserver.js

@@ -0,0 +1,248 @@
+"use strict";
+/**
+ * Runner-side primitives for observing catalog-item macro substitution
+ * in creative previews. Consumed by conformance runners grading the
+ * `substitution-observer-runner` test-kit contract.
+ *
+ * Usage — inline HTML observation:
+ * ```ts
+ * const observer = new SubstitutionObserver();
+ * const records = observer.parse_html(preview_html);
+ * const matches = observer.match_bindings(records, template, bindings);
+ * for (const m of matches) {
+ *   const r = observer.assert_rfc3986_safe(m);
+ *   if (!r.ok) report(r);
+ * }
+ * ```
+ *
+ * Usage — preview URL fetch (applies SSRF policy):
+ * ```ts
+ * const records = await observer.fetch_and_parse(new URL(preview_url));
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubstitutionObserver = exports.PreviewFetchError = void 0;
+const promises_1 = __importDefault(require("node:dns/promises"));
+const node_net_1 = require("node:net");
+const html_parser_1 = require("./html-parser");
+const alignment_1 = require("./alignment");
+const assertions_1 = require("./assertions");
+const ssrf_1 = require("./ssrf");
+class PreviewFetchError extends Error {
+    sub_reason;
+    detail;
+    constructor(sub_reason, detail) {
+        super(`preview_url_unusable:${sub_reason} — ${detail}`);
+        this.name = 'PreviewFetchError';
+        this.sub_reason = sub_reason;
+        this.detail = detail;
+    }
+}
+exports.PreviewFetchError = PreviewFetchError;
+class SubstitutionObserver {
+    /**
+     * Parse inline preview HTML and return tracker URLs from the
+     * contract's normative tag/attribute set. URLs that fail WHATWG URL
+     * parsing are skipped silently — a downstream binding that expected
+     * them surfaces as `substitution_binding_missing`.
+     */
+    parse_html(html) {
+        return (0, html_parser_1.extractTrackerUrls)(html);
+    }
+    /**
+     * Fetch `preview_url` under the SSRF policy, validate response
+     * shape, and parse the body. Redirects are treated as failure
+     * (policy: `follow_redirects: false`). The body is capped at
+     * `max_body_bytes` bytes — exceeding the cap yields a
+     * `size_exceeded` failure rather than a truncated parse.
+     *
+     * Throws {@link PreviewFetchError} on any fetch-layer failure so the
+     * runner can map the sub-reason to the contract's
+     * `preview_url_unusable_sub_reasons` vocabulary.
+     */
+    async fetch_and_parse(url, options = {}) {
+        const policy = options.ssrf_policy ?? ssrf_1.DEFAULT_SSRF_POLICY;
+        const maxBodyBytes = options.max_body_bytes ?? 262_144;
+        const connectTimeoutMs = (options.max_connect_seconds ?? 3) * 1000;
+        const timeoutMs = (options.timeout_seconds ?? 10) * 1000;
+        const allowedContentTypes = options.required_content_types ?? ['text/html', 'application/xhtml+xml'];
+        const presync = (0, ssrf_1.enforceSsrfPolicy)(url, policy);
+        if (!presync.allowed) {
+            throw new PreviewFetchError('ssrf_blocked', presync.rule ?? 'unknown_rule');
+        }
+        // Every non-IP host path requires DNS revalidation — never pass a
+        // hostname to the HTTP client without re-checking resolved addresses.
+        const bareHost = unwrapHost(url.hostname);
+        const isBareIp = (0, node_net_1.isIP)(bareHost) !== 0;
+        let pinnedAddress = isBareIp ? bareHost : null;
+        if (!isBareIp) {
+            let addresses = [];
+            try {
+                const lookup = await promises_1.default.lookup(url.hostname, { all: true, verbatim: true });
+                addresses = lookup.map(entry => entry.address);
+            }
+            catch (e) {
+                throw new PreviewFetchError('fetch_timeout', `DNS lookup failed: ${e.message}`);
+            }
+            const resolvedCheck = (0, ssrf_1.enforceSsrfPolicyResolved)(url, addresses, policy);
+            if (!resolvedCheck.allowed) {
+                throw new PreviewFetchError('ssrf_blocked', resolvedCheck.rule ?? 'unknown_rule');
+            }
+            pinnedAddress = addresses[0] ?? null;
+        }
+        const { request, Agent } = await loadUndici();
+        // Pin to the already-policy-checked address. Providing `connect.lookup`
+        // makes undici resolve through our callback instead of invoking the OS
+        // resolver a second time — closes the DNS-rebinding window between
+        // our `dns.lookup` above and the TCP connect below. If the caller
+        // injected a dispatcher, trust their pinning.
+        const ownsDispatcher = !options.dispatcher;
+        const dispatcher = options.dispatcher ??
+            new Agent({
+                connect: {
+                    timeout: connectTimeoutMs,
+                    ...(pinnedAddress
+                        ? {
+                            lookup: (_host, _opts, cb) => cb(null, pinnedAddress, (0, node_net_1.isIPv6)(pinnedAddress) ? 6 : 4),
+                        }
+                        : {}),
+                },
+                bodyTimeout: timeoutMs,
+                headersTimeout: timeoutMs,
+            });
+        const abortCtrl = new AbortController();
+        const timerHandle = setTimeout(() => {
+            abortCtrl.abort(new Error('preview fetch timeout'));
+        }, timeoutMs);
+        // Allow Node to exit even if the timer is still scheduled — a
+        // stranded observer shouldn't keep the process alive.
+        timerHandle.unref?.();
+        try {
+            const res = await request(url.href, {
+                method: 'GET',
+                dispatcher: dispatcher,
+                maxRedirections: 0,
+                signal: abortCtrl.signal,
+                headers: { accept: allowedContentTypes.join(', ') },
+            });
+            if (res.statusCode >= 300 && res.statusCode < 400) {
+                throw new PreviewFetchError('redirect_returned', `status=${res.statusCode}`);
+            }
+            if (res.statusCode < 200 || res.statusCode >= 300) {
+                throw new PreviewFetchError('http_status', `status=${res.statusCode}`);
+            }
+            const contentType = (String(res.headers['content-type'] ?? '').split(';')[0] ?? '').trim().toLowerCase();
+            if (!allowedContentTypes.includes(contentType)) {
+                throw new PreviewFetchError('content_type', `content-type=${contentType || 'missing'}`);
+            }
+            const body = await readCapped(res.body, maxBodyBytes);
+            return (0, html_parser_1.extractTrackerUrls)(body);
+        }
+        catch (e) {
+            if (e instanceof PreviewFetchError)
+                throw e;
+            if (e.name === 'AbortError') {
+                throw new PreviewFetchError('fetch_timeout', `exceeded ${timeoutMs}ms`);
+            }
+            throw new PreviewFetchError('fetch_timeout', e.message);
+        }
+        finally {
+            clearTimeout(timerHandle);
+            abortCtrl.abort();
+            if (ownsDispatcher) {
+                const closable = dispatcher;
+                try {
+                    await closable.close?.();
+                }
+                catch {
+                    // Ignore — best-effort cleanup.
+                }
+            }
+        }
+    }
+    /** See {@link matchBindings}. */
+    match_bindings(records, template, bindings) {
+        return (0, alignment_1.matchBindings)(records, template, bindings);
+    }
+    /** See {@link assertRfc3986Safe}. */
+    assert_rfc3986_safe(match, options = {}) {
+        return (0, assertions_1.assertRfc3986Safe)(match, options);
+    }
+    /** See {@link assertUnreservedOnly}. */
+    assert_unreserved_only(match, options = {}) {
+        return (0, assertions_1.assertUnreservedOnly)(match, options);
+    }
+    /** See {@link assertNoNestedExpansion}. */
+    assert_no_nested_expansion(match, prohibited_pattern = assertions_1.DEFAULT_MACRO_PROHIBITED_PATTERN, options = {}) {
+        return (0, assertions_1.assertNoNestedExpansion)(match, prohibited_pattern, options);
+    }
+    /** See {@link assertSchemePreserved}. */
+    assert_scheme_preserved(match, template_scheme) {
+        return (0, assertions_1.assertSchemePreserved)(match, template_scheme);
+    }
+    /** See {@link enforceSsrfPolicy}. */
+    enforce_ssrf_policy(url, policy = ssrf_1.DEFAULT_SSRF_POLICY) {
+        return (0, ssrf_1.enforceSsrfPolicy)(url, policy);
+    }
+}
+exports.SubstitutionObserver = SubstitutionObserver;
+function unwrapHost(host) {
+    return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+}
+async function readCapped(body, capBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of body) {
+        const buf = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+        total += buf.length;
+        if (total > capBytes) {
+            throw new PreviewFetchError('size_exceeded', `>${capBytes} bytes`);
+        }
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+let undiciModule;
+async function loadUndici() {
+    if (!undiciModule) {
+        undiciModule = await Promise.resolve().then(() => __importStar(require('undici')));
+    }
+    return undiciModule;
+}
+//# sourceMappingURL=SubstitutionObserver.js.map

package/dist/lib/substitution/observer/SubstitutionObserver.js.map

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

package/dist/lib/substitution/observer/alignment.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Macro-position alignment: map each observed tracker URL back to the
+ * template position its macro occupied, so the verifier can compare
+ * observed bytes against the expected encoding at exactly that slot.
+ *
+ * Implements the normative algorithm from the test-kit contract:
+ *
+ *   1. Tokenize the template from its raw string so literal AdCP macros
+ *      (`{SKU}`) survive — WHATWG URL percent-encodes `{` in paths, which
+ *      would mask the macro position.
+ *   2. Parse observed URLs with WHATWG URL (they are properly encoded).
+ *   3. Align observed query pairs by decoded key (positionally among
+ *      pairs sharing the same key); align path segments positionally.
+ *   4. Emit BindingMatch entries the verifier can assert on.
+ */
+import type { BindingMatch, CatalogBinding, TrackerUrlRecord } from '../types';
+/**
+ * Match each observed record to the template positions its bindings
+ * occupy. A binding may match multiple records when the observed
+ * preview contains repetitions (e.g., impression + click pixels
+ * sharing a SKU).
+ */
+export declare function matchBindings(records: readonly TrackerUrlRecord[], template: URL | string, bindings: readonly CatalogBinding[]): BindingMatch[];
+//# sourceMappingURL=alignment.d.ts.map

package/dist/lib/substitution/observer/alignment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment.d.ts","sourceRoot":"","sources":["../../../../src/lib/substitution/observer/alignment.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAsB,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAuEnG;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,gBAAgB,EAAE,EACpC,QAAQ,EAAE,GAAG,GAAG,MAAM,EACtB,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,YAAY,EAAE,CA+BhB"}

package/dist/lib/substitution/observer/alignment.js

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * Macro-position alignment: map each observed tracker URL back to the
+ * template position its macro occupied, so the verifier can compare
+ * observed bytes against the expected encoding at exactly that slot.
+ *
+ * Implements the normative algorithm from the test-kit contract:
+ *
+ *   1. Tokenize the template from its raw string so literal AdCP macros
+ *      (`{SKU}`) survive — WHATWG URL percent-encodes `{` in paths, which
+ *      would mask the macro position.
+ *   2. Parse observed URLs with WHATWG URL (they are properly encoded).
+ *   3. Align observed query pairs by decoded key (positionally among
+ *      pairs sharing the same key); align path segments positionally.
+ *   4. Emit BindingMatch entries the verifier can assert on.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchBindings = matchBindings;
+const rfc3986_1 = require("../rfc3986");
+const vectors_1 = require("../vectors");
+const MACRO_SEGMENT_RE = /\{[A-Z][A-Z0-9_]*\}/;
+/**
+ * Resolve the fixture vector or inline overrides for a binding. The
+ * `expected_encoded` field is the per-position encoded substring
+ * (e.g., `00013%26cmd%3Ddrop`), NOT the full fixture URL.
+ *
+ * Canonical vectors (referenced by `vector_name` and present in
+ * {@link CATALOG_MACRO_VECTORS}) resolve from the fixture. Custom
+ * bindings MUST supply BOTH `raw_value` and `expected_encoded` — the
+ * runner MUST NOT produce the oracle by calling its own encoder on
+ * the seller's input (that makes the test tautological). A custom
+ * binding missing `expected_encoded` is dropped; the caller surfaces
+ * it as `substitution_binding_missing`.
+ */
+function resolveBinding(binding) {
+    let vector;
+    if (binding.vector_name)
+        vector = (0, vectors_1.getCatalogMacroVector)(binding.vector_name);
+    if (vector) {
+        const raw_value = binding.raw_value ?? vector.value;
+        // The fixture's `expected` is a full URL; the runner needs the
+        // encoded substring at the macro position. `encodeUnreserved` is
+        // the same algorithm the fixture's expected was produced by — the
+        // parity test in `substitution-fixture-parity.test.js` locks that
+        // invariant, so this is NOT tautological for canonical vectors.
+        const expected_encoded = binding.expected_encoded ?? (0, rfc3986_1.encodeUnreserved)(vector.value);
+        return { raw_value, expected_encoded, is_custom_vector: false };
+    }
+    // No canonical vector — caller must supply both raw_value AND
+    // expected_encoded, otherwise the binding is unresolvable.
+    if (binding.raw_value === undefined || binding.expected_encoded === undefined) {
+        return null;
+    }
+    return {
+        raw_value: binding.raw_value,
+        expected_encoded: binding.expected_encoded,
+        is_custom_vector: true,
+    };
+}
+/**
+ * Match each observed record to the template positions its bindings
+ * occupy. A binding may match multiple records when the observed
+ * preview contains repetitions (e.g., impression + click pixels
+ * sharing a SKU).
+ */
+function matchBindings(records, template, bindings) {
+    const templateLayout = parseTemplate(template);
+    const matches = [];
+    for (const binding of bindings) {
+        const resolved = resolveBinding(binding);
+        if (!resolved)
+            continue;
+        const positions = findMacroPositions(templateLayout, binding.macro);
+        if (positions.length === 0)
+            continue;
+        for (const record of sameTemplateRecords(records, templateLayout)) {
+            const observed = parseObserved(record.url);
+            for (const position of positions) {
+                const observed_value = resolveObservedValue(observed, position);
+                if (observed_value === null)
+                    continue;
+                matches.push({
+                    binding,
+                    raw_value: resolved.raw_value,
+                    expected_encoded: resolved.expected_encoded,
+                    observed_url: record.url,
+                    record,
+                    position,
+                    observed_value,
+                    is_custom_vector: resolved.is_custom_vector,
+                });
+            }
+        }
+    }
+    return matches;
+}
+/**
+ * Tokenize a template from its raw string. Preserves literal `{MACRO}`
+ * sequences in path and query. Throws if the template is not an
+ * absolute URL. Avoids regex parsing of untrusted input to sidestep
+ * any polynomial-backtracking risk on adversarial templates.
+ */
+function parseTemplate(template) {
+    const raw = typeof template === 'string' ? template : template.href;
+    const parts = splitAbsoluteUrl(raw);
+    if (!parts)
+        throw new Error(`Template is not an absolute URL: ${raw}`);
+    const { origin, path } = parts;
+    const search = parts.search;
+    const path_segments = path === '' || path === '/' ? [] : path.replace(/^\//, '').split('/');
+    const query_pairs = search
+        ? search.split('&').map((segment, index) => {
+            const eq = segment.indexOf('=');
+            const keyRaw = eq === -1 ? segment : segment.slice(0, eq);
+            const valueRaw = eq === -1 ? '' : segment.slice(eq + 1);
+            return { key: safeDecode(keyRaw), raw_value: valueRaw, index };
+        })
+        : [];
+    // Origin reported as WHATWG URL's `origin` shape so comparison with
+    // observed URLs (which are WHATWG-parsed) is apples-to-apples.
+    const normalizedOrigin = normalizeOrigin(origin);
+    return {
+        origin: normalizedOrigin,
+        path_segments,
+        query_pairs,
+        href: raw,
+    };
+}
+function normalizeOrigin(scheme_and_authority) {
+    // Handle `scheme://authority` form.
+    try {
+        const u = new URL(scheme_and_authority + '/');
+        return u.origin;
+    }
+    catch {
+        return scheme_and_authority;
+    }
+}
+/**
+ * Linear-time absolute-URL splitter. Returns the scheme+authority
+ * prefix, the raw path, and the raw search (without leading `?`), or
+ * `null` if the input isn't shaped `scheme://authority...`. Avoids
+ * regex on untrusted input so adversarial templates can't trigger
+ * polynomial backtracking.
+ */
+function splitAbsoluteUrl(raw) {
+    // Locate the `://` delimiter. Scheme MUST be non-empty and start with
+    // a letter; we enforce that minimum here without scanning the whole
+    // scheme for validity (WHATWG URL would accept most absolute forms).
+    const schemeEnd = raw.indexOf('://');
+    if (schemeEnd <= 0)
+        return null;
+    const firstChar = raw.charCodeAt(0);
+    const isAlpha = (firstChar >= 0x41 && firstChar <= 0x5a) || (firstChar >= 0x61 && firstChar <= 0x7a);
+    if (!isAlpha)
+        return null;
+    const afterScheme = schemeEnd + 3;
+    // Authority ends at the first `/`, `?`, or `#` — or end of string.
+    let authorityEnd = raw.length;
+    for (let i = afterScheme; i < raw.length; i++) {
+        const c = raw.charCodeAt(i);
+        if (c === 0x2f /* / */ || c === 0x3f /* ? */ || c === 0x23 /* # */) {
+            authorityEnd = i;
+            break;
+        }
+    }
+    const origin = raw.slice(0, authorityEnd);
+    // Path runs from authorityEnd up to `?`, `#`, or end of string.
+    let pathEnd = raw.length;
+    for (let i = authorityEnd; i < raw.length; i++) {
+        const c = raw.charCodeAt(i);
+        if (c === 0x3f /* ? */ || c === 0x23 /* # */) {
+            pathEnd = i;
+            break;
+        }
+    }
+    const path = raw.slice(authorityEnd, pathEnd);
+    // Search runs from `?` up to `#` or end. No leading `?` in the returned form.
+    let search = '';
+    if (raw.charCodeAt(pathEnd) === 0x3f) {
+        let searchEnd = raw.length;
+        for (let i = pathEnd + 1; i < raw.length; i++) {
+            if (raw.charCodeAt(i) === 0x23 /* # */) {
+                searchEnd = i;
+                break;
+            }
+        }
+        search = raw.slice(pathEnd + 1, searchEnd);
+    }
+    return { origin, path, search };
+}
+function parseObserved(url) {
+    const path_segments = url.pathname === '/' ? [] : url.pathname.replace(/^\//, '').split('/');
+    const rawSearch = url.search.startsWith('?') ? url.search.slice(1) : url.search;
+    const query_pairs = rawSearch
+        ? rawSearch.split('&').map((segment, index) => {
+            const eq = segment.indexOf('=');
+            const keyRaw = eq === -1 ? segment : segment.slice(0, eq);
+            const valueRaw = eq === -1 ? '' : segment.slice(eq + 1);
+            return { key: safeDecode(keyRaw), raw_value: valueRaw, index };
+        })
+        : [];
+    return { url, path_segments, query_pairs, href: url.href };
+}
+/**
+ * Narrow observed records to those that could plausibly be substituted
+ * forms of `template`: same origin, same number of path segments,
+ * literal segments matching where the template has no macro, and every
+ * template query key present in the observed URL.
+ *
+ * This is a same-shape filter, not an alignment oracle — two templates
+ * with identical path+key shapes but different semantics will confuse
+ * it. Runners SHOULD invoke `match_bindings` once per `(template,
+ * preview)` pair rather than pass all records from a multi-template
+ * preview to a single call.
+ */
+function sameTemplateRecords(records, template) {
+    const templateKeys = new Set(template.query_pairs.map(p => p.key));
+    const templateSegCount = template.path_segments.length;
+    return records.filter(r => {
+        if (r.url.origin !== template.origin)
+            return false;
+        const observed = parseObserved(r.url);
+        if (observed.path_segments.length !== templateSegCount)
+            return false;
+        for (let i = 0; i < templateSegCount; i++) {
+            const seg = template.path_segments[i] ?? '';
+            const obs = observed.path_segments[i] ?? '';
+            if (!MACRO_SEGMENT_RE.test(seg) && seg !== obs)
+                return false;
+        }
+        for (const key of templateKeys) {
+            if (!observed.query_pairs.some(p => p.key === key))
+                return false;
+        }
+        return true;
+    });
+}
+/**
+ * Find the template positions where `macro` appears. Whole-value
+ * matches win first (rare; legal for `<a href="{CLICK}">`). Otherwise
+ * emit every query-value and path-segment match in scan order.
+ */
+function findMacroPositions(layout, macro) {
+    const out = [];
+    if (layout.href === macro) {
+        out.push({ kind: 'href_whole_value' });
+    }
+    for (const pair of layout.query_pairs) {
+        if (pair.raw_value === macro) {
+            out.push({ kind: 'query', key: pair.key, index: pair.index });
+        }
+    }
+    layout.path_segments.forEach((seg, index) => {
+        if (seg === macro) {
+            out.push({ kind: 'path', index });
+        }
+    });
+    return out;
+}
+function resolveObservedValue(layout, position) {
+    if (position.kind === 'href_whole_value') {
+        return layout.href;
+    }
+    if (position.kind === 'path') {
+        return layout.path_segments[position.index] ?? null;
+    }
+    const matching = layout.query_pairs.filter(p => p.key === position.key);
+    return matching[0]?.raw_value ?? null;
+}
+function safeDecode(s) {
+    try {
+        return decodeURIComponent(s.replace(/\+/g, ' '));
+    }
+    catch {
+        return s;
+    }
+}
+//# sourceMappingURL=alignment.js.map

package/dist/lib/substitution/observer/alignment.js.map

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

package/dist/lib/substitution/observer/assertions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Per-binding assertions the runner runs on each BindingMatch. Each
+ * returns an {@link AssertionResult} with a contract error code on
+ * failure. Custom-vector payloads are SHA-256 redacted by default to
+ * honor the contract's `error_report_payload_policy`; canonical
+ * fixture vectors are echoed verbatim.
+ */
+import type { AssertionOptions, AssertionResult, BindingMatch } from '../types';
+/**
+ * Default prohibited pattern for {@link assertNoNestedExpansion} —
+ * any brace-delimited token, regardless of case or naming convention.
+ * Storyboards that need a narrower check (a specific sentinel macro)
+ * pass a custom `RegExp`.
+ */
+export declare const DEFAULT_MACRO_PROHIBITED_PATTERN: RegExp;
+/**
+ * Byte-for-byte comparison of the observed value against the expected
+ * encoded substring under the contract's hex-case policy. Uppercase
+ * and lowercase hex digits inside a `%NN` triplet are treated as
+ * equivalent; bytes outside triplets compare case-sensitively.
+ */
+export declare function assertRfc3986Safe(match: BindingMatch, options?: AssertionOptions): AssertionResult;
+/**
+ * Stricter variant of {@link assertRfc3986Safe} — every byte at the
+ * macro position is either an unreserved character or a valid `%NN`
+ * triplet. Producers using a reserved-char denylist instead of the
+ * unreserved whitelist fail here even when the byte-equal check passes
+ * (the canonical counterexamples are parens `(` `)` and sub-delims).
+ */
+export declare function assertUnreservedOnly(match: BindingMatch, options?: AssertionOptions): AssertionResult;
+/**
+ * Reject second-round AdCP macro expansion at the macro position. A
+ * seller that re-scanned its output after substitution would resolve
+ * a `{DEVICE_ID}` literal inside the catalog value — this assertion
+ * fails that behavior. The default `prohibited_pattern` matches any
+ * brace-delimited token ({@link DEFAULT_MACRO_PROHIBITED_PATTERN});
+ * storyboards that bind a specific sentinel macro SHOULD pass a
+ * narrower pattern.
+ */
+export declare function assertNoNestedExpansion(match: BindingMatch, prohibited_pattern?: RegExp, options?: AssertionOptions): AssertionResult;
+/**
+ * Verify the observed URL's scheme matches the template's scheme. Only
+ * meaningful at `href_whole_value` positions where a catalog value
+ * could replace an entire URL and change its scheme (e.g., a
+ * `javascript:`-scheme injection into `<a href="{CLICK}">`).
+ */
+export declare function assertSchemePreserved(match: BindingMatch, template_scheme: string): AssertionResult;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/lib/substitution/observer/assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../../../../src/lib/substitution/observer/assertions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAGhF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,QAAiB,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe,CAetG;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,eAAe,CAYzG;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,YAAY,EACnB,kBAAkB,GAAE,MAAyC,EAC7D,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CAkBjB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,GAAG,eAAe,CAoBnG"}