@adcp/sdk 17.0.0-beta.21 → 17.0.0-beta.22
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +26 -2
- package/dist/lib/client/core.d.mts +4 -0
- package/dist/lib/client/core.d.ts +4 -0
- package/dist/lib/client/core.js +13 -0
- package/dist/lib/client/core.mjs +12 -0
- package/dist/lib/conformance/property-lists.d.mts +1 -1
- package/dist/lib/conformance/property-lists.d.ts +1 -1
- package/dist/lib/conformance/property-lists.js +1 -1
- package/dist/lib/conformance/property-lists.mjs +1 -1
- package/dist/lib/core/SingleAgentClient.d.mts +10 -1
- package/dist/lib/core/SingleAgentClient.d.ts +10 -1
- package/dist/lib/core/SingleAgentClient.js +56 -7
- package/dist/lib/core/SingleAgentClient.mjs +61 -7
- package/dist/lib/core/targeting-helpers.d.mts +123 -0
- package/dist/lib/core/targeting-helpers.d.ts +123 -0
- package/dist/lib/core/targeting-helpers.js +412 -0
- package/dist/lib/core/targeting-helpers.mjs +370 -0
- package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
- package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
- package/dist/lib/entrypoints/client-account-changes.js +28 -0
- package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
- package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
- package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
- package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
- package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
- package/dist/lib/entrypoints/discovery.d.mts +9 -0
- package/dist/lib/entrypoints/discovery.d.ts +9 -0
- package/dist/lib/entrypoints/discovery.js +72 -0
- package/dist/lib/entrypoints/discovery.mjs +56 -0
- package/dist/lib/entrypoints/errors.d.mts +11 -0
- package/dist/lib/entrypoints/errors.d.ts +11 -0
- package/dist/lib/entrypoints/errors.js +159 -0
- package/dist/lib/entrypoints/errors.mjs +132 -0
- package/dist/lib/entrypoints/media-buy.d.mts +5 -0
- package/dist/lib/entrypoints/media-buy.d.ts +5 -0
- package/dist/lib/entrypoints/media-buy.js +119 -0
- package/dist/lib/entrypoints/media-buy.mjs +100 -0
- package/dist/lib/entrypoints/registry.d.mts +5 -0
- package/dist/lib/entrypoints/registry.d.ts +5 -0
- package/dist/lib/entrypoints/registry.js +61 -0
- package/dist/lib/entrypoints/registry.mjs +40 -0
- package/dist/lib/entrypoints/utils.d.mts +7 -0
- package/dist/lib/entrypoints/utils.d.ts +7 -0
- package/dist/lib/entrypoints/utils.js +100 -0
- package/dist/lib/entrypoints/utils.mjs +72 -0
- package/dist/lib/entrypoints/version.d.mts +3 -0
- package/dist/lib/entrypoints/version.d.ts +3 -0
- package/dist/lib/entrypoints/version.js +57 -0
- package/dist/lib/entrypoints/version.mjs +36 -0
- package/dist/lib/index.d.mts +1 -1
- package/dist/lib/index.d.ts +1 -1
- package/dist/lib/media-buy/action-contracts.js +3 -3
- package/dist/lib/media-buy/action-contracts.mjs +1 -1
- package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
- package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
- package/dist/lib/media-buy/creative-start-policy.js +59 -0
- package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
- package/dist/lib/media-buy/valid-actions.d.mts +47 -0
- package/dist/lib/media-buy/valid-actions.d.ts +47 -0
- package/dist/lib/media-buy/valid-actions.js +42 -0
- package/dist/lib/media-buy/valid-actions.mjs +18 -0
- package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
- package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
- package/dist/lib/net/pin-and-bind-fetch.js +209 -0
- package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
- package/dist/lib/registry/types.generated.d.ts +18 -2
- package/dist/lib/reporting/ledger/index.d.mts +1 -0
- package/dist/lib/reporting/ledger/index.d.ts +1 -0
- package/dist/lib/reporting/ledger/index.js +3 -1
- package/dist/lib/reporting/ledger/index.mjs +1 -0
- package/dist/lib/reporting/ledger/instant.d.mts +5 -0
- package/dist/lib/reporting/ledger/instant.d.ts +5 -0
- package/dist/lib/reporting/ledger/instant.js +10 -0
- package/dist/lib/reporting/ledger/instant.mjs +9 -0
- package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
- package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
- package/dist/lib/reporting/ledger/issue-events.js +310 -0
- package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
- package/dist/lib/reporting/service/index.d.mts +36 -1
- package/dist/lib/reporting/service/index.d.ts +36 -1
- package/dist/lib/reporting/service/index.js +51 -1
- package/dist/lib/reporting/service/index.mjs +52 -2
- package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
- package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
- package/dist/lib/reporting/service/scheduler-support.js +1 -1
- package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
- package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
- package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
- package/dist/lib/server/capabilities-release-projection.js +128 -0
- package/dist/lib/server/capabilities-release-projection.mjs +112 -0
- package/dist/lib/server/create-adcp-server.d.mts +29 -5
- package/dist/lib/server/create-adcp-server.d.ts +29 -5
- package/dist/lib/server/create-adcp-server.js +95 -22
- package/dist/lib/server/create-adcp-server.mjs +106 -21
- package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
- package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
- package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
- package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
- package/dist/lib/server/declared-input-schema.d.mts +108 -0
- package/dist/lib/server/declared-input-schema.d.ts +108 -0
- package/dist/lib/server/declared-input-schema.js +167 -0
- package/dist/lib/server/declared-input-schema.mjs +137 -0
- package/dist/lib/server/envelope-allowlist.d.mts +1 -105
- package/dist/lib/server/envelope-allowlist.d.ts +1 -105
- package/dist/lib/server/envelope-allowlist.js +3 -79
- package/dist/lib/server/envelope-allowlist.mjs +1 -71
- package/dist/lib/server/errors.d.mts +1 -186
- package/dist/lib/server/errors.d.ts +1 -186
- package/dist/lib/server/errors.js +3 -98
- package/dist/lib/server/errors.mjs +1 -94
- package/dist/lib/server/index.d.mts +1 -1
- package/dist/lib/server/index.d.ts +1 -1
- package/dist/lib/server/mcp-modern-server.js +21 -4
- package/dist/lib/server/mcp-modern-server.mjs +21 -4
- package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
- package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
- package/dist/lib/server/media-buy-action-resolver.js +10 -1
- package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
- package/dist/lib/server/media-buy-helpers.d.mts +1 -47
- package/dist/lib/server/media-buy-helpers.d.ts +1 -47
- package/dist/lib/server/media-buy-helpers.js +3 -23
- package/dist/lib/server/media-buy-helpers.mjs +1 -18
- package/dist/lib/server/pick-safe-details.d.mts +1 -89
- package/dist/lib/server/pick-safe-details.d.ts +1 -89
- package/dist/lib/server/pick-safe-details.js +3 -61
- package/dist/lib/server/pick-safe-details.mjs +1 -56
- package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
- package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
- package/dist/lib/server/pin-and-bind-fetch.js +3 -190
- package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
- package/dist/lib/server/targeting-helpers.d.mts +1 -123
- package/dist/lib/server/targeting-helpers.d.ts +1 -123
- package/dist/lib/server/targeting-helpers.js +3 -393
- package/dist/lib/server/targeting-helpers.mjs +1 -370
- package/dist/lib/server/test-controller.js +7 -3
- package/dist/lib/server/test-controller.mjs +7 -3
- package/dist/lib/storage/memory-ledger.js +219 -1
- package/dist/lib/storage/memory-ledger.mjs +223 -1
- package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
- package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
- package/dist/lib/testing/comply-controller.js +7 -2
- package/dist/lib/testing/comply-controller.mjs +7 -2
- package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
- package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
- package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
- package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
- package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
- package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
- package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
- package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
- package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
- package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
- package/dist/lib/testing/storyboard/runner.js +2 -2
- package/dist/lib/testing/storyboard/runner.mjs +2 -2
- package/dist/lib/testing/storyboard/validations.d.mts +1 -1
- package/dist/lib/testing/storyboard/validations.d.ts +1 -1
- package/dist/lib/utils/adcp-error-response.d.mts +196 -0
- package/dist/lib/utils/adcp-error-response.d.ts +196 -0
- package/dist/lib/utils/adcp-error-response.js +118 -0
- package/dist/lib/utils/adcp-error-response.mjs +95 -0
- package/dist/lib/utils/buyer-retry-policy.js +2 -2
- package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
- package/dist/lib/utils/capabilities.d.mts +6 -0
- package/dist/lib/utils/capabilities.d.ts +6 -0
- package/dist/lib/utils/capabilities.js +6 -2
- package/dist/lib/utils/capabilities.mjs +6 -2
- package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
- package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
- package/dist/lib/utils/envelope-allowlist.js +98 -0
- package/dist/lib/utils/envelope-allowlist.mjs +71 -0
- package/dist/lib/utils/pick-safe-details.d.mts +89 -0
- package/dist/lib/utils/pick-safe-details.d.ts +89 -0
- package/dist/lib/utils/pick-safe-details.js +80 -0
- package/dist/lib/utils/pick-safe-details.mjs +56 -0
- package/dist/lib/v2/projection/augment-response.d.mts +4 -0
- package/dist/lib/v2/projection/augment-response.d.ts +4 -0
- package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
- package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
- package/dist/lib/v2/projection/creative-delivery.js +20 -4
- package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
- package/dist/lib/v2/projection/index.d.mts +2 -2
- package/dist/lib/v2/projection/index.d.ts +2 -2
- package/dist/lib/v2/projection/index.js +4 -0
- package/dist/lib/v2/projection/index.mjs +5 -1
- package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
- package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
- package/dist/lib/v2/projection/legacy-metadata.js +14 -0
- package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
- package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
- package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
- package/dist/lib/v2/projection/legacy-routes.js +2 -1
- package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
- package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
- package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
- package/dist/lib/v2/projection/v1-to-v2.js +18 -11
- package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
- package/dist/lib/version.d.mts +3 -3
- package/dist/lib/version.d.ts +3 -3
- package/dist/lib/version.js +3 -3
- package/dist/lib/version.mjs +3 -3
- package/docs/TYPE-SUMMARY.md +2 -2
- package/docs/guides/CREATIVE-DELIVERY.md +12 -0
- package/docs/guides/REPORTING-LEDGER.md +121 -0
- package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
- package/docs/llms.txt +2 -2
- package/docs/migration-14.x-rc-worksheet.md +4 -4
- package/docs/migration-16-to-17.md +149 -0
- package/docs/migration-reporting-storage-package.md +10 -0
- package/package.json +106 -1
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Envelope-allowlist governance for AdCP error responses.
|
|
3
|
+
*
|
|
4
|
+
* Two orthogonal concerns both govern what round-trips on an AdCP error
|
|
5
|
+
* envelope. They live side-by-side here so that a change to one forces
|
|
6
|
+
* the reviewer to weigh the other (security review M4 on #788 — the
|
|
7
|
+
* pair is conceptually related and can drift in separate files).
|
|
8
|
+
*
|
|
9
|
+
* - `ERROR_ENVELOPE_FIELD_ALLOWLIST` governs keys that may appear as
|
|
10
|
+
* SIBLINGS of `adcp_error` on the wire response. Enforced by
|
|
11
|
+
* `wrapEnvelope` in `./wrap-envelope.ts`.
|
|
12
|
+
* - `ADCP_ERROR_FIELD_ALLOWLIST` governs keys that may appear INSIDE
|
|
13
|
+
* the `adcp_error` block, keyed by error code. Consumed by
|
|
14
|
+
* `adcpError()` (which filters its output to the allowlisted set)
|
|
15
|
+
* AND by the dispatcher in `create-adcp-server.ts` (re-applied to
|
|
16
|
+
* every handler-returned envelope via `sanitizeAdcpErrorEnvelope`
|
|
17
|
+
* — defence-in-depth for handlers that hand-roll an error envelope
|
|
18
|
+
* instead of going through the builder). The same set powers the
|
|
19
|
+
* `idempotency.conflict_no_payload_leak` invariant in
|
|
20
|
+
* `../testing/storyboard/default-invariants.ts`. The legacy
|
|
21
|
+
* `CONFLICT_ADCP_ERROR_ALLOWLIST` export is a convenience alias for
|
|
22
|
+
* the `IDEMPOTENCY_CONFLICT` entry.
|
|
23
|
+
*
|
|
24
|
+
* Both sets apply to the same wire response but at different nesting
|
|
25
|
+
* levels. A seller that needs to extend one should audit whether the
|
|
26
|
+
* other also needs updating.
|
|
27
|
+
*
|
|
28
|
+
* Hand-rolling an error envelope? Prefer `adcpError(code, options)` —
|
|
29
|
+
* it wraps both transport layers and applies this allowlist for you.
|
|
30
|
+
* The dispatcher sanitizer is a belt-and-suspenders, not a primary API.
|
|
31
|
+
*/
|
|
32
|
+
/**
|
|
33
|
+
* Fail-closed default allowlist for unknown error codes.
|
|
34
|
+
*
|
|
35
|
+
* An error code without an explicit entry in
|
|
36
|
+
* `ERROR_ENVELOPE_FIELD_ALLOWLIST` gets this set — only `context`
|
|
37
|
+
* round-trips (matching the invariant that every allowlist permits
|
|
38
|
+
* correlation tracing). Sellers that want `replayed` or `operation_id`
|
|
39
|
+
* on a bespoke error code must register it explicitly.
|
|
40
|
+
*
|
|
41
|
+
* This is the fail-closed posture — sellers MUST opt in to any field
|
|
42
|
+
* they want on an error envelope, rather than inheriting success-path
|
|
43
|
+
* semantics by default. Security review M3 on #788.
|
|
44
|
+
*/
|
|
45
|
+
export declare const DEFAULT_ERROR_ENVELOPE_FIELDS: ReadonlySet<string>;
|
|
46
|
+
/**
|
|
47
|
+
* Per-error-code envelope-field allowlist.
|
|
48
|
+
*
|
|
49
|
+
* A code listed here restricts which envelope fields `wrapEnvelope`
|
|
50
|
+
* will attach on top of the error's inner payload. Codes NOT listed
|
|
51
|
+
* here receive `DEFAULT_ERROR_ENVELOPE_FIELDS` (fail-closed —
|
|
52
|
+
* `context` only).
|
|
53
|
+
*
|
|
54
|
+
* `IDEMPOTENCY_CONFLICT` deliberately excludes `replayed`: the
|
|
55
|
+
* conflict path in `create-adcp-server.ts` builds its error via
|
|
56
|
+
* `finalize()`, which only echoes `context` and never calls
|
|
57
|
+
* `stampReplayed`. The framework's own behavior is preserved.
|
|
58
|
+
*
|
|
59
|
+
* **Invariant**: every allowlist set MUST include `'context'`.
|
|
60
|
+
* `ensureContextEcho` enforces this at module load so new error codes
|
|
61
|
+
* can't accidentally drop context echo (which sellers rely on for
|
|
62
|
+
* correlation tracing across both success and error paths).
|
|
63
|
+
*/
|
|
64
|
+
export declare const ERROR_ENVELOPE_FIELD_ALLOWLIST: Readonly<Record<string, ReadonlySet<string>>>;
|
|
65
|
+
/**
|
|
66
|
+
* Per-error-code allowlist for keys permitted INSIDE the `adcp_error`
|
|
67
|
+
* block. The `adcpError()` builder consults this table and drops any
|
|
68
|
+
* field the caller passes that isn't allowlisted for the given code —
|
|
69
|
+
* the allowlist IS the contract for what a framework-emitted error may
|
|
70
|
+
* carry. Storyboard invariants enforce the same contract on the wire.
|
|
71
|
+
*
|
|
72
|
+
* A code without an explicit entry permits everything `adcpError()`
|
|
73
|
+
* would otherwise emit — the default case is pass-through. Sellers who
|
|
74
|
+
* want a bespoke code to be strict should register it here (or wrap
|
|
75
|
+
* `adcpError()` with their own sanitizer).
|
|
76
|
+
*
|
|
77
|
+
* **Scope warning for future contributors:** only register a code here
|
|
78
|
+
* if it belongs to the AdCP standard error vocabulary (`enums/error-code.json`).
|
|
79
|
+
* Per `core/error.json`, clients "MUST handle unknown codes gracefully
|
|
80
|
+
* by falling back to the recovery classification" — so dropping
|
|
81
|
+
* `recovery` on a vendor / non-standard code makes the response
|
|
82
|
+
* genuinely lossy for any buyer agent that doesn't have the code in
|
|
83
|
+
* its local vocabulary.
|
|
84
|
+
*
|
|
85
|
+
* `IDEMPOTENCY_CONFLICT` is narrow on purpose: a conflict response MUST
|
|
86
|
+
* NOT echo the prior request payload or cached response (stolen-key
|
|
87
|
+
* read oracle defence). Standard recovery metadata is allowed because it
|
|
88
|
+
* is normalized to the fixed classifier, not trusted as caller-provided
|
|
89
|
+
* prior request or cached response data.
|
|
90
|
+
* `retry_after` is excluded: no framework path currently emits it on conflict, and a seller
|
|
91
|
+
* that computed `retry_after = cached_entry_age` would leak the prior
|
|
92
|
+
* payload's creation time (a distinguisher between "key never seen" vs
|
|
93
|
+
* "key seen N seconds ago"). Retry hints belong on transient codes
|
|
94
|
+
* (`SERVICE_UNAVAILABLE`, `RATE_LIMITED`), not on a terminal conflict.
|
|
95
|
+
* `adcpError()` and the dispatcher sanitizer both enforce this.
|
|
96
|
+
*/
|
|
97
|
+
export declare const ADCP_ERROR_FIELD_ALLOWLIST: Readonly<Record<string, ReadonlySet<string>>>;
|
|
98
|
+
/**
|
|
99
|
+
* Convenience alias for the `IDEMPOTENCY_CONFLICT` entry in
|
|
100
|
+
* {@link ADCP_ERROR_FIELD_ALLOWLIST}. Kept as a named export because
|
|
101
|
+
* the default `idempotency.conflict_no_payload_leak` invariant and a
|
|
102
|
+
* handful of consumer tests reach for it by name; new code should use
|
|
103
|
+
* `ADCP_ERROR_FIELD_ALLOWLIST.IDEMPOTENCY_CONFLICT` directly.
|
|
104
|
+
*/
|
|
105
|
+
export declare const CONFLICT_ADCP_ERROR_ALLOWLIST: ReadonlySet<string>;
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
var envelope_allowlist_exports = {};
|
|
20
|
+
__export(envelope_allowlist_exports, {
|
|
21
|
+
ADCP_ERROR_FIELD_ALLOWLIST: () => ADCP_ERROR_FIELD_ALLOWLIST,
|
|
22
|
+
CONFLICT_ADCP_ERROR_ALLOWLIST: () => CONFLICT_ADCP_ERROR_ALLOWLIST,
|
|
23
|
+
DEFAULT_ERROR_ENVELOPE_FIELDS: () => DEFAULT_ERROR_ENVELOPE_FIELDS,
|
|
24
|
+
ERROR_ENVELOPE_FIELD_ALLOWLIST: () => ERROR_ENVELOPE_FIELD_ALLOWLIST
|
|
25
|
+
});
|
|
26
|
+
module.exports = __toCommonJS(envelope_allowlist_exports);
|
|
27
|
+
const DEFAULT_ERROR_ENVELOPE_FIELDS = Object.freeze(/* @__PURE__ */ new Set(["context"]));
|
|
28
|
+
const ERROR_ENVELOPE_FIELD_ALLOWLIST = Object.freeze({
|
|
29
|
+
// Spec-defined: conflict is not a replay; `replayed` intentionally
|
|
30
|
+
// dropped. `operation_id` round-trips for async-op correlation.
|
|
31
|
+
IDEMPOTENCY_CONFLICT: /* @__PURE__ */ new Set(["context", "operation_id"]),
|
|
32
|
+
// A cached purge result is itself the durable outcome. Replays MUST be
|
|
33
|
+
// distinguishable without reopening the committed-resource lookup.
|
|
34
|
+
COMMITTED_RESOURCE_PURGED: /* @__PURE__ */ new Set(["context", "replayed"])
|
|
35
|
+
});
|
|
36
|
+
const ADCP_ERROR_FIELD_ALLOWLIST = Object.freeze({
|
|
37
|
+
IDEMPOTENCY_CONFLICT: /* @__PURE__ */ new Set([
|
|
38
|
+
"code",
|
|
39
|
+
"message",
|
|
40
|
+
"recovery",
|
|
41
|
+
"status",
|
|
42
|
+
"correlation_id",
|
|
43
|
+
"request_id",
|
|
44
|
+
"operation_id"
|
|
45
|
+
]),
|
|
46
|
+
// `IDEMPOTENCY_IN_FLIGHT` (AdCP 3.1) carries `recovery: transient` plus a
|
|
47
|
+
// store-derived `retry_after` so transient-aware buyer SDKs can replay
|
|
48
|
+
// shortly. Allowlist registration is defense-in-depth — `adcpError()` at
|
|
49
|
+
// the in-flight call site only assembles framework-controlled keys today,
|
|
50
|
+
// but the registration forces any future caller that tries to attach
|
|
51
|
+
// payload fingerprints onto the in-flight envelope to land here in code
|
|
52
|
+
// review first.
|
|
53
|
+
IDEMPOTENCY_IN_FLIGHT: /* @__PURE__ */ new Set([
|
|
54
|
+
"code",
|
|
55
|
+
"message",
|
|
56
|
+
"recovery",
|
|
57
|
+
"retry_after",
|
|
58
|
+
"status",
|
|
59
|
+
"correlation_id",
|
|
60
|
+
"request_id",
|
|
61
|
+
"operation_id"
|
|
62
|
+
])
|
|
63
|
+
});
|
|
64
|
+
const CONFLICT_ADCP_ERROR_ALLOWLIST = ADCP_ERROR_FIELD_ALLOWLIST.IDEMPOTENCY_CONFLICT;
|
|
65
|
+
function ensureContextEcho(allowlist) {
|
|
66
|
+
if (!DEFAULT_ERROR_ENVELOPE_FIELDS.has("context")) {
|
|
67
|
+
throw new Error(
|
|
68
|
+
"DEFAULT_ERROR_ENVELOPE_FIELDS must include 'context' so correlation ids can round-trip on error envelopes."
|
|
69
|
+
);
|
|
70
|
+
}
|
|
71
|
+
for (const [code, fields] of Object.entries(allowlist)) {
|
|
72
|
+
if (!fields.has("context")) {
|
|
73
|
+
throw new Error(
|
|
74
|
+
`ERROR_ENVELOPE_FIELD_ALLOWLIST['${code}'] is missing 'context'. Every error-code allowlist must include 'context' so correlation ids can round-trip on error envelopes.`
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
ensureContextEcho(ERROR_ENVELOPE_FIELD_ALLOWLIST);
|
|
80
|
+
function ensureCoreAdcpErrorFields(allowlist) {
|
|
81
|
+
for (const [code, fields] of Object.entries(allowlist)) {
|
|
82
|
+
for (const required of ["code", "message"]) {
|
|
83
|
+
if (!fields.has(required)) {
|
|
84
|
+
throw new Error(
|
|
85
|
+
`ADCP_ERROR_FIELD_ALLOWLIST['${code}'] is missing '${required}'. Every inside-adcp_error allowlist must include 'code' and 'message' \u2014 they are the only two required fields on the AdCP error schema.`
|
|
86
|
+
);
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
ensureCoreAdcpErrorFields(ADCP_ERROR_FIELD_ALLOWLIST);
|
|
92
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
93
|
+
0 && (module.exports = {
|
|
94
|
+
ADCP_ERROR_FIELD_ALLOWLIST,
|
|
95
|
+
CONFLICT_ADCP_ERROR_ALLOWLIST,
|
|
96
|
+
DEFAULT_ERROR_ENVELOPE_FIELDS,
|
|
97
|
+
ERROR_ENVELOPE_FIELD_ALLOWLIST
|
|
98
|
+
});
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
const DEFAULT_ERROR_ENVELOPE_FIELDS = Object.freeze(/* @__PURE__ */ new Set(["context"]));
|
|
2
|
+
const ERROR_ENVELOPE_FIELD_ALLOWLIST = Object.freeze({
|
|
3
|
+
// Spec-defined: conflict is not a replay; `replayed` intentionally
|
|
4
|
+
// dropped. `operation_id` round-trips for async-op correlation.
|
|
5
|
+
IDEMPOTENCY_CONFLICT: /* @__PURE__ */ new Set(["context", "operation_id"]),
|
|
6
|
+
// A cached purge result is itself the durable outcome. Replays MUST be
|
|
7
|
+
// distinguishable without reopening the committed-resource lookup.
|
|
8
|
+
COMMITTED_RESOURCE_PURGED: /* @__PURE__ */ new Set(["context", "replayed"])
|
|
9
|
+
});
|
|
10
|
+
const ADCP_ERROR_FIELD_ALLOWLIST = Object.freeze({
|
|
11
|
+
IDEMPOTENCY_CONFLICT: /* @__PURE__ */ new Set([
|
|
12
|
+
"code",
|
|
13
|
+
"message",
|
|
14
|
+
"recovery",
|
|
15
|
+
"status",
|
|
16
|
+
"correlation_id",
|
|
17
|
+
"request_id",
|
|
18
|
+
"operation_id"
|
|
19
|
+
]),
|
|
20
|
+
// `IDEMPOTENCY_IN_FLIGHT` (AdCP 3.1) carries `recovery: transient` plus a
|
|
21
|
+
// store-derived `retry_after` so transient-aware buyer SDKs can replay
|
|
22
|
+
// shortly. Allowlist registration is defense-in-depth — `adcpError()` at
|
|
23
|
+
// the in-flight call site only assembles framework-controlled keys today,
|
|
24
|
+
// but the registration forces any future caller that tries to attach
|
|
25
|
+
// payload fingerprints onto the in-flight envelope to land here in code
|
|
26
|
+
// review first.
|
|
27
|
+
IDEMPOTENCY_IN_FLIGHT: /* @__PURE__ */ new Set([
|
|
28
|
+
"code",
|
|
29
|
+
"message",
|
|
30
|
+
"recovery",
|
|
31
|
+
"retry_after",
|
|
32
|
+
"status",
|
|
33
|
+
"correlation_id",
|
|
34
|
+
"request_id",
|
|
35
|
+
"operation_id"
|
|
36
|
+
])
|
|
37
|
+
});
|
|
38
|
+
const CONFLICT_ADCP_ERROR_ALLOWLIST = ADCP_ERROR_FIELD_ALLOWLIST.IDEMPOTENCY_CONFLICT;
|
|
39
|
+
function ensureContextEcho(allowlist) {
|
|
40
|
+
if (!DEFAULT_ERROR_ENVELOPE_FIELDS.has("context")) {
|
|
41
|
+
throw new Error(
|
|
42
|
+
"DEFAULT_ERROR_ENVELOPE_FIELDS must include 'context' so correlation ids can round-trip on error envelopes."
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
for (const [code, fields] of Object.entries(allowlist)) {
|
|
46
|
+
if (!fields.has("context")) {
|
|
47
|
+
throw new Error(
|
|
48
|
+
`ERROR_ENVELOPE_FIELD_ALLOWLIST['${code}'] is missing 'context'. Every error-code allowlist must include 'context' so correlation ids can round-trip on error envelopes.`
|
|
49
|
+
);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
ensureContextEcho(ERROR_ENVELOPE_FIELD_ALLOWLIST);
|
|
54
|
+
function ensureCoreAdcpErrorFields(allowlist) {
|
|
55
|
+
for (const [code, fields] of Object.entries(allowlist)) {
|
|
56
|
+
for (const required of ["code", "message"]) {
|
|
57
|
+
if (!fields.has(required)) {
|
|
58
|
+
throw new Error(
|
|
59
|
+
`ADCP_ERROR_FIELD_ALLOWLIST['${code}'] is missing '${required}'. Every inside-adcp_error allowlist must include 'code' and 'message' \u2014 they are the only two required fields on the AdCP error schema.`
|
|
60
|
+
);
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
ensureCoreAdcpErrorFields(ADCP_ERROR_FIELD_ALLOWLIST);
|
|
66
|
+
export {
|
|
67
|
+
ADCP_ERROR_FIELD_ALLOWLIST,
|
|
68
|
+
CONFLICT_ADCP_ERROR_ALLOWLIST,
|
|
69
|
+
DEFAULT_ERROR_ENVELOPE_FIELDS,
|
|
70
|
+
ERROR_ENVELOPE_FIELD_ALLOWLIST
|
|
71
|
+
};
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Security primitive for the `details` field on `AdcpError` and the
|
|
3
|
+
* `Error` wire row. Adopters fronting upstream platforms (GAM, Snap,
|
|
4
|
+
* retail-media APIs, internal billing systems) often want to surface
|
|
5
|
+
* upstream error context to buyers — but raw upstream errors carry
|
|
6
|
+
* credentials, PII, internal stack traces, request IDs that leak
|
|
7
|
+
* tenant identity, and other liability surfaces that MUST NOT cross
|
|
8
|
+
* the wire boundary.
|
|
9
|
+
*
|
|
10
|
+
* `pickSafeDetails(input, allowlist, opts?)` is an explicit-allowlist
|
|
11
|
+
* sanitizer: only keys in the allowlist survive, with optional caps
|
|
12
|
+
* on depth and serialized size. Returns `undefined` when the input is
|
|
13
|
+
* not a plain object or the allowlist filter produces an empty
|
|
14
|
+
* result, so callers can spread the return into an optional `details`
|
|
15
|
+
* field without polluting it with `{}`.
|
|
16
|
+
*
|
|
17
|
+
* Adopters should call this BEFORE constructing the `AdcpError` /
|
|
18
|
+
* wire `Error` row. The framework's `normalizeError` does NOT
|
|
19
|
+
* sanitize details — it shallow-copies whatever was passed.
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```ts
|
|
23
|
+
* import { pickSafeDetails } from '@adcp/client/server';
|
|
24
|
+
*
|
|
25
|
+
* try {
|
|
26
|
+
* await gamClient.createOrder(req);
|
|
27
|
+
* } catch (upstreamErr) {
|
|
28
|
+
* throw new AdcpError('UPSTREAM_REJECTED', {
|
|
29
|
+
* recovery: 'transient',
|
|
30
|
+
* message: 'Ad server rejected the order',
|
|
31
|
+
* // Allowlist: only safe upstream fields cross the wire
|
|
32
|
+
* details: pickSafeDetails(upstreamErr, [
|
|
33
|
+
* 'http_status',
|
|
34
|
+
* 'request_id',
|
|
35
|
+
* 'gam_error_code',
|
|
36
|
+
* ]),
|
|
37
|
+
* });
|
|
38
|
+
* }
|
|
39
|
+
* ```
|
|
40
|
+
*
|
|
41
|
+
* @public
|
|
42
|
+
*/
|
|
43
|
+
export interface PickSafeDetailsOptions {
|
|
44
|
+
/**
|
|
45
|
+
* Maximum nesting depth retained in the result. `undefined` keeps
|
|
46
|
+
* the input unchanged at any depth; values like `2` keep top-level
|
|
47
|
+
* + one nested level. Strings, numbers, booleans, and null are
|
|
48
|
+
* leaves; arrays and plain objects count as a level.
|
|
49
|
+
*
|
|
50
|
+
* Default: `2` — top-level + one nested level. Caps cardinality
|
|
51
|
+
* blast radius from accidentally-recursive upstream error objects.
|
|
52
|
+
*/
|
|
53
|
+
maxDepth?: number;
|
|
54
|
+
/**
|
|
55
|
+
* Maximum serialized JSON byte size of the result (best-effort
|
|
56
|
+
* UTF-8 estimate via `JSON.stringify().length`). When the projected
|
|
57
|
+
* result exceeds this, returns `undefined` rather than truncating —
|
|
58
|
+
* adopters should choose a tighter allowlist if they hit the cap.
|
|
59
|
+
*
|
|
60
|
+
* Default: `2048` bytes. Wire envelopes shouldn't carry kilobytes
|
|
61
|
+
* of details; if you need that, ship via `publishStatusChange` or
|
|
62
|
+
* `task_registry.progress`.
|
|
63
|
+
*/
|
|
64
|
+
maxSizeBytes?: number;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Filter `input` to keys named in `allowlist`, depth-capped and
|
|
68
|
+
* size-capped. Returns `undefined` when the result is empty or
|
|
69
|
+
* exceeds the size cap so callers can spread the value into an
|
|
70
|
+
* optional `details` field without polluting it.
|
|
71
|
+
*
|
|
72
|
+
* Properties NOT in the allowlist are dropped silently (no warning;
|
|
73
|
+
* the design assumes the allowlist is the contract). Nested objects
|
|
74
|
+
* are recursively filtered with the SAME allowlist — there is no
|
|
75
|
+
* per-key allowlist for nested fields. Adopters who need per-level
|
|
76
|
+
* filtering should call `pickSafeDetails` recursively on each
|
|
77
|
+
* nested value.
|
|
78
|
+
*
|
|
79
|
+
* Common-sense behaviors:
|
|
80
|
+
* - `null` / `undefined` / non-object input → `undefined`
|
|
81
|
+
* - Empty result after filtering → `undefined`
|
|
82
|
+
* - Arrays at the top level → `undefined` (use a wrapping object)
|
|
83
|
+
* - Functions and Symbols are dropped
|
|
84
|
+
* - Date / RegExp / Error / Map / Set are dropped (use a string
|
|
85
|
+
* allowlist of primitive fields, or pre-shape the input)
|
|
86
|
+
*
|
|
87
|
+
* @public
|
|
88
|
+
*/
|
|
89
|
+
export declare function pickSafeDetails(input: unknown, allowlist: readonly string[], opts?: PickSafeDetailsOptions): Record<string, unknown> | undefined;
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Security primitive for the `details` field on `AdcpError` and the
|
|
3
|
+
* `Error` wire row. Adopters fronting upstream platforms (GAM, Snap,
|
|
4
|
+
* retail-media APIs, internal billing systems) often want to surface
|
|
5
|
+
* upstream error context to buyers — but raw upstream errors carry
|
|
6
|
+
* credentials, PII, internal stack traces, request IDs that leak
|
|
7
|
+
* tenant identity, and other liability surfaces that MUST NOT cross
|
|
8
|
+
* the wire boundary.
|
|
9
|
+
*
|
|
10
|
+
* `pickSafeDetails(input, allowlist, opts?)` is an explicit-allowlist
|
|
11
|
+
* sanitizer: only keys in the allowlist survive, with optional caps
|
|
12
|
+
* on depth and serialized size. Returns `undefined` when the input is
|
|
13
|
+
* not a plain object or the allowlist filter produces an empty
|
|
14
|
+
* result, so callers can spread the return into an optional `details`
|
|
15
|
+
* field without polluting it with `{}`.
|
|
16
|
+
*
|
|
17
|
+
* Adopters should call this BEFORE constructing the `AdcpError` /
|
|
18
|
+
* wire `Error` row. The framework's `normalizeError` does NOT
|
|
19
|
+
* sanitize details — it shallow-copies whatever was passed.
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```ts
|
|
23
|
+
* import { pickSafeDetails } from '@adcp/client/server';
|
|
24
|
+
*
|
|
25
|
+
* try {
|
|
26
|
+
* await gamClient.createOrder(req);
|
|
27
|
+
* } catch (upstreamErr) {
|
|
28
|
+
* throw new AdcpError('UPSTREAM_REJECTED', {
|
|
29
|
+
* recovery: 'transient',
|
|
30
|
+
* message: 'Ad server rejected the order',
|
|
31
|
+
* // Allowlist: only safe upstream fields cross the wire
|
|
32
|
+
* details: pickSafeDetails(upstreamErr, [
|
|
33
|
+
* 'http_status',
|
|
34
|
+
* 'request_id',
|
|
35
|
+
* 'gam_error_code',
|
|
36
|
+
* ]),
|
|
37
|
+
* });
|
|
38
|
+
* }
|
|
39
|
+
* ```
|
|
40
|
+
*
|
|
41
|
+
* @public
|
|
42
|
+
*/
|
|
43
|
+
export interface PickSafeDetailsOptions {
|
|
44
|
+
/**
|
|
45
|
+
* Maximum nesting depth retained in the result. `undefined` keeps
|
|
46
|
+
* the input unchanged at any depth; values like `2` keep top-level
|
|
47
|
+
* + one nested level. Strings, numbers, booleans, and null are
|
|
48
|
+
* leaves; arrays and plain objects count as a level.
|
|
49
|
+
*
|
|
50
|
+
* Default: `2` — top-level + one nested level. Caps cardinality
|
|
51
|
+
* blast radius from accidentally-recursive upstream error objects.
|
|
52
|
+
*/
|
|
53
|
+
maxDepth?: number;
|
|
54
|
+
/**
|
|
55
|
+
* Maximum serialized JSON byte size of the result (best-effort
|
|
56
|
+
* UTF-8 estimate via `JSON.stringify().length`). When the projected
|
|
57
|
+
* result exceeds this, returns `undefined` rather than truncating —
|
|
58
|
+
* adopters should choose a tighter allowlist if they hit the cap.
|
|
59
|
+
*
|
|
60
|
+
* Default: `2048` bytes. Wire envelopes shouldn't carry kilobytes
|
|
61
|
+
* of details; if you need that, ship via `publishStatusChange` or
|
|
62
|
+
* `task_registry.progress`.
|
|
63
|
+
*/
|
|
64
|
+
maxSizeBytes?: number;
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Filter `input` to keys named in `allowlist`, depth-capped and
|
|
68
|
+
* size-capped. Returns `undefined` when the result is empty or
|
|
69
|
+
* exceeds the size cap so callers can spread the value into an
|
|
70
|
+
* optional `details` field without polluting it.
|
|
71
|
+
*
|
|
72
|
+
* Properties NOT in the allowlist are dropped silently (no warning;
|
|
73
|
+
* the design assumes the allowlist is the contract). Nested objects
|
|
74
|
+
* are recursively filtered with the SAME allowlist — there is no
|
|
75
|
+
* per-key allowlist for nested fields. Adopters who need per-level
|
|
76
|
+
* filtering should call `pickSafeDetails` recursively on each
|
|
77
|
+
* nested value.
|
|
78
|
+
*
|
|
79
|
+
* Common-sense behaviors:
|
|
80
|
+
* - `null` / `undefined` / non-object input → `undefined`
|
|
81
|
+
* - Empty result after filtering → `undefined`
|
|
82
|
+
* - Arrays at the top level → `undefined` (use a wrapping object)
|
|
83
|
+
* - Functions and Symbols are dropped
|
|
84
|
+
* - Date / RegExp / Error / Map / Set are dropped (use a string
|
|
85
|
+
* allowlist of primitive fields, or pre-shape the input)
|
|
86
|
+
*
|
|
87
|
+
* @public
|
|
88
|
+
*/
|
|
89
|
+
export declare function pickSafeDetails(input: unknown, allowlist: readonly string[], opts?: PickSafeDetailsOptions): Record<string, unknown> | undefined;
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
var pick_safe_details_exports = {};
|
|
20
|
+
__export(pick_safe_details_exports, {
|
|
21
|
+
pickSafeDetails: () => pickSafeDetails
|
|
22
|
+
});
|
|
23
|
+
module.exports = __toCommonJS(pick_safe_details_exports);
|
|
24
|
+
const DEFAULT_OPTIONS = {
|
|
25
|
+
maxDepth: 2,
|
|
26
|
+
maxSizeBytes: 2048
|
|
27
|
+
};
|
|
28
|
+
function pickSafeDetails(input, allowlist, opts) {
|
|
29
|
+
if (!isPlainObject(input)) return void 0;
|
|
30
|
+
if (allowlist.length === 0) return void 0;
|
|
31
|
+
const maxDepth = opts?.maxDepth ?? DEFAULT_OPTIONS.maxDepth;
|
|
32
|
+
const maxSize = opts?.maxSizeBytes ?? DEFAULT_OPTIONS.maxSizeBytes;
|
|
33
|
+
const allowSet = new Set(allowlist);
|
|
34
|
+
const result = filterByAllowlist(input, allowSet, maxDepth);
|
|
35
|
+
if (result == null || Object.keys(result).length === 0) return void 0;
|
|
36
|
+
let serialized;
|
|
37
|
+
try {
|
|
38
|
+
serialized = JSON.stringify(result);
|
|
39
|
+
} catch {
|
|
40
|
+
return void 0;
|
|
41
|
+
}
|
|
42
|
+
if (serialized.length > maxSize) return void 0;
|
|
43
|
+
return result;
|
|
44
|
+
}
|
|
45
|
+
function filterByAllowlist(obj, allow, remainingDepth) {
|
|
46
|
+
const out = {};
|
|
47
|
+
for (const key of Object.keys(obj)) {
|
|
48
|
+
if (!allow.has(key)) continue;
|
|
49
|
+
const value = obj[key];
|
|
50
|
+
const safe = sanitizeValue(value, allow, remainingDepth - 1);
|
|
51
|
+
if (safe !== void 0) out[key] = safe;
|
|
52
|
+
}
|
|
53
|
+
return Object.keys(out).length === 0 ? null : out;
|
|
54
|
+
}
|
|
55
|
+
function sanitizeValue(value, allow, remainingDepth) {
|
|
56
|
+
if (value === null) return null;
|
|
57
|
+
const t = typeof value;
|
|
58
|
+
if (t === "string" || t === "number" || t === "boolean") return value;
|
|
59
|
+
if (t === "function" || t === "symbol" || t === "undefined" || t === "bigint") return void 0;
|
|
60
|
+
if (Array.isArray(value)) {
|
|
61
|
+
const mapped = value.map((v) => sanitizeValue(v, allow, remainingDepth));
|
|
62
|
+
return mapped.filter((v) => v !== void 0);
|
|
63
|
+
}
|
|
64
|
+
if (isPlainObject(value)) {
|
|
65
|
+
if (remainingDepth <= 0) return void 0;
|
|
66
|
+
const filtered = filterByAllowlist(value, allow, remainingDepth);
|
|
67
|
+
return filtered ?? void 0;
|
|
68
|
+
}
|
|
69
|
+
return void 0;
|
|
70
|
+
}
|
|
71
|
+
function isPlainObject(value) {
|
|
72
|
+
if (value === null || typeof value !== "object") return false;
|
|
73
|
+
if (Array.isArray(value)) return false;
|
|
74
|
+
const proto = Object.getPrototypeOf(value);
|
|
75
|
+
return proto === Object.prototype || proto === null;
|
|
76
|
+
}
|
|
77
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
78
|
+
0 && (module.exports = {
|
|
79
|
+
pickSafeDetails
|
|
80
|
+
});
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
const DEFAULT_OPTIONS = {
|
|
2
|
+
maxDepth: 2,
|
|
3
|
+
maxSizeBytes: 2048
|
|
4
|
+
};
|
|
5
|
+
function pickSafeDetails(input, allowlist, opts) {
|
|
6
|
+
if (!isPlainObject(input)) return void 0;
|
|
7
|
+
if (allowlist.length === 0) return void 0;
|
|
8
|
+
const maxDepth = opts?.maxDepth ?? DEFAULT_OPTIONS.maxDepth;
|
|
9
|
+
const maxSize = opts?.maxSizeBytes ?? DEFAULT_OPTIONS.maxSizeBytes;
|
|
10
|
+
const allowSet = new Set(allowlist);
|
|
11
|
+
const result = filterByAllowlist(input, allowSet, maxDepth);
|
|
12
|
+
if (result == null || Object.keys(result).length === 0) return void 0;
|
|
13
|
+
let serialized;
|
|
14
|
+
try {
|
|
15
|
+
serialized = JSON.stringify(result);
|
|
16
|
+
} catch {
|
|
17
|
+
return void 0;
|
|
18
|
+
}
|
|
19
|
+
if (serialized.length > maxSize) return void 0;
|
|
20
|
+
return result;
|
|
21
|
+
}
|
|
22
|
+
function filterByAllowlist(obj, allow, remainingDepth) {
|
|
23
|
+
const out = {};
|
|
24
|
+
for (const key of Object.keys(obj)) {
|
|
25
|
+
if (!allow.has(key)) continue;
|
|
26
|
+
const value = obj[key];
|
|
27
|
+
const safe = sanitizeValue(value, allow, remainingDepth - 1);
|
|
28
|
+
if (safe !== void 0) out[key] = safe;
|
|
29
|
+
}
|
|
30
|
+
return Object.keys(out).length === 0 ? null : out;
|
|
31
|
+
}
|
|
32
|
+
function sanitizeValue(value, allow, remainingDepth) {
|
|
33
|
+
if (value === null) return null;
|
|
34
|
+
const t = typeof value;
|
|
35
|
+
if (t === "string" || t === "number" || t === "boolean") return value;
|
|
36
|
+
if (t === "function" || t === "symbol" || t === "undefined" || t === "bigint") return void 0;
|
|
37
|
+
if (Array.isArray(value)) {
|
|
38
|
+
const mapped = value.map((v) => sanitizeValue(v, allow, remainingDepth));
|
|
39
|
+
return mapped.filter((v) => v !== void 0);
|
|
40
|
+
}
|
|
41
|
+
if (isPlainObject(value)) {
|
|
42
|
+
if (remainingDepth <= 0) return void 0;
|
|
43
|
+
const filtered = filterByAllowlist(value, allow, remainingDepth);
|
|
44
|
+
return filtered ?? void 0;
|
|
45
|
+
}
|
|
46
|
+
return void 0;
|
|
47
|
+
}
|
|
48
|
+
function isPlainObject(value) {
|
|
49
|
+
if (value === null || typeof value !== "object") return false;
|
|
50
|
+
if (Array.isArray(value)) return false;
|
|
51
|
+
const proto = Object.getPrototypeOf(value);
|
|
52
|
+
return proto === Object.prototype || proto === null;
|
|
53
|
+
}
|
|
54
|
+
export {
|
|
55
|
+
pickSafeDetails
|
|
56
|
+
};
|
|
@@ -132,6 +132,10 @@ export declare function toCanonicalFormatOptionsWithRoutes(productId: string, fo
|
|
|
132
132
|
* before being forwarded to a legacy seller. Rebuild the write-side resolver
|
|
133
133
|
* with `canonicalFormatLegacyResolverFromRoutes(restoredRoutes)`.
|
|
134
134
|
*
|
|
135
|
+
* A legacy id at a seller's own agent URL may be projected by a guess from its
|
|
136
|
+
* name (`display_300x250` read as `image`). Its route carries
|
|
137
|
+
* `inferred_from_id: true`; pass `authoritativeOnly: true` to skip guesses.
|
|
138
|
+
*
|
|
135
139
|
* @throws TypeError when a canonical declaration uses a direct legacy identity
|
|
136
140
|
* alias such as `agent_url` or `agentUrl` instead of `v1_format_ref`.
|
|
137
141
|
*/
|
|
@@ -132,6 +132,10 @@ export declare function toCanonicalFormatOptionsWithRoutes(productId: string, fo
|
|
|
132
132
|
* before being forwarded to a legacy seller. Rebuild the write-side resolver
|
|
133
133
|
* with `canonicalFormatLegacyResolverFromRoutes(restoredRoutes)`.
|
|
134
134
|
*
|
|
135
|
+
* A legacy id at a seller's own agent URL may be projected by a guess from its
|
|
136
|
+
* name (`display_300x250` read as `image`). Its route carries
|
|
137
|
+
* `inferred_from_id: true`; pass `authoritativeOnly: true` to skip guesses.
|
|
138
|
+
*
|
|
135
139
|
* @throws TypeError when a canonical declaration uses a direct legacy identity
|
|
136
140
|
* alias such as `agent_url` or `agentUrl` instead of `v1_format_ref`.
|
|
137
141
|
*/
|
|
@@ -346,9 +346,17 @@ export declare class CreativeFormatCapabilityError extends Error {
|
|
|
346
346
|
export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode?: 'canonical', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): CanonicalProjectedCreative<T>;
|
|
347
347
|
export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: 'legacy' | 'unknown', operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): LegacyProjectedCreative<T>;
|
|
348
348
|
export declare function projectCreativeForDelivery<T extends CreativeAsset>(creative: T, selectorContainer: CreativeFormatSelectorContainer, wireMode: CreativeFormatWireMode, operation?: string, legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[]): CanonicalProjectedCreative<T> | LegacyProjectedCreative<T>;
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
349
|
+
/**
|
|
350
|
+
* Project a create/update media-buy request's packages and creatives to the
|
|
351
|
+
* seller's creative wire. On the legacy wire, pass `formatOptionRefsOnWire`
|
|
352
|
+
* when the seller's release defines package `format_option_refs` (AdCP 3.1;
|
|
353
|
+
* see {@link releaseCarriesPackageFormatOptionRefs}): selections with no
|
|
354
|
+
* legacy `format_ids` are then sent as `format_option_refs` instead of
|
|
355
|
+
* throwing. Selections that do map are still rewritten to `format_ids`.
|
|
356
|
+
*/
|
|
357
|
+
export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'canonical', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'canonical'>;
|
|
358
|
+
export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: 'legacy' | 'unknown', operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
|
|
359
|
+
export declare function projectMediaBuyCreativesForDelivery<T>(request: T, wireMode: CreativeFormatWireMode, operation?: 'create_media_buy' | 'update_media_buy', legacyFormatConverter?: LegacyFormatConverter, canonicalFormatLegacyResolver?: CanonicalFormatLegacyResolver, legacyFormatDefinitions?: readonly V1FormatDefinition[], formatOptionRefsOnWire?: boolean): ProjectedMediaBuyCreativeRequest<T, 'canonical'> | ProjectedMediaBuyCreativeRequest<T, 'legacy'>;
|
|
352
360
|
export interface CreativePackageFit {
|
|
353
361
|
package_id: string;
|
|
354
362
|
verdict: CreativeFitVerdict;
|
|
@@ -413,3 +421,12 @@ export type UndeclaredFormatOptionLookup = (ref: FormatOptionReference, productI
|
|
|
413
421
|
*/
|
|
414
422
|
export declare function projectUndeclaredFormatOptionSelectors<T>(request: T, operation: 'create_media_buy' | 'update_media_buy' | 'sync_creatives', lookup: UndeclaredFormatOptionLookup): T;
|
|
415
423
|
export declare function resolveCreativeFormatWireMode(capabilities: unknown, negotiatedVersion?: string): CreativeFormatWireMode;
|
|
424
|
+
/**
|
|
425
|
+
* Whether the seller's advertised `supported_versions` prove a mutually served
|
|
426
|
+
* release whose package request defines `format_option_refs` (AdCP 3.1 and
|
|
427
|
+
* later). AdCP 3.0 does not define the field, and a release that cannot be
|
|
428
|
+
* proven is treated as 3.0, so a selection is never silently dropped. Throws
|
|
429
|
+
* `CreativeFormatCapabilityError` for the same release contradictions as
|
|
430
|
+
* {@link resolveCreativeFormatWireMode}.
|
|
431
|
+
*/
|
|
432
|
+
export declare function releaseCarriesPackageFormatOptionRefs(capabilities: unknown, requestedVersion: string): boolean;
|