@adcp/sdk 17.0.0-beta.21 → 17.0.0-beta.23
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/adapters/version/index.d.mts +1 -1
- package/dist/lib/adapters/version/index.d.ts +1 -1
- package/dist/lib/adapters/version/index.js +2 -0
- package/dist/lib/adapters/version/index.mjs +2 -0
- package/dist/lib/adapters/version/negotiate.d.mts +13 -0
- package/dist/lib/adapters/version/negotiate.d.ts +13 -0
- package/dist/lib/adapters/version/negotiate.js +6 -0
- package/dist/lib/adapters/version/negotiate.mjs +5 -0
- 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 +23 -1
- package/dist/lib/core/SingleAgentClient.d.ts +23 -1
- package/dist/lib/core/SingleAgentClient.js +102 -18
- package/dist/lib/core/SingleAgentClient.mjs +108 -18
- 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/protocols/mcp-modern.js +20 -4
- package/dist/lib/protocols/mcp-modern.mjs +20 -4
- package/dist/lib/registry/types.generated.d.ts +224 -3
- 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 +97 -24
- package/dist/lib/server/create-adcp-server.mjs +108 -23
- 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/client.js +26 -5
- package/dist/lib/testing/client.mjs +24 -5
- 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 +4 -4
- package/dist/lib/testing/storyboard/runner.mjs +4 -4
- package/dist/lib/testing/storyboard/task-map.js +4 -1
- package/dist/lib/testing/storyboard/task-map.mjs +4 -1
- 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,196 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server-side helpers for producing L3-compliant AdCP error responses.
|
|
3
|
+
*
|
|
4
|
+
* Use `adcpError()` in MCP tool handlers to return structured errors
|
|
5
|
+
* that clients can automatically detect, classify, and act on.
|
|
6
|
+
*/
|
|
7
|
+
import { type StandardErrorCode, type ErrorRecovery } from '../types/error-codes.mjs';
|
|
8
|
+
import type { ValidationIssue } from '../validation/schema-validator.mjs';
|
|
9
|
+
export interface AdcpErrorOptions {
|
|
10
|
+
message: string;
|
|
11
|
+
/**
|
|
12
|
+
* Opaque request context to echo beside `adcp_error`. Only a non-null,
|
|
13
|
+
* non-array object is echoable, matching the framework envelope behavior.
|
|
14
|
+
*/
|
|
15
|
+
context?: unknown;
|
|
16
|
+
/**
|
|
17
|
+
* Override the recovery classification. Defaults to
|
|
18
|
+
* `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`
|
|
19
|
+
* otherwise. Dropped from the wire shape for codes whose entry in
|
|
20
|
+
* `ADCP_ERROR_FIELD_ALLOWLIST` excludes it; normalized back to the
|
|
21
|
+
* standard table value for allowlisted standard-code envelopes.
|
|
22
|
+
*/
|
|
23
|
+
recovery?: ErrorRecovery;
|
|
24
|
+
/**
|
|
25
|
+
* Name of the request field the error applies to (validation /
|
|
26
|
+
* constraint errors). Dropped from the wire shape for codes whose
|
|
27
|
+
* `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g. `IDEMPOTENCY_CONFLICT`
|
|
28
|
+
* — a conflict response MUST NOT echo prior payload state).
|
|
29
|
+
*/
|
|
30
|
+
field?: string;
|
|
31
|
+
/**
|
|
32
|
+
* Human-readable remediation hint. Dropped from the wire shape for
|
|
33
|
+
* codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g.
|
|
34
|
+
* `IDEMPOTENCY_CONFLICT`).
|
|
35
|
+
*/
|
|
36
|
+
suggestion?: string;
|
|
37
|
+
/**
|
|
38
|
+
* Seconds to wait before retrying a transient error. Only meaningful
|
|
39
|
+
* on retryable codes (`RATE_LIMITED`, `SERVICE_UNAVAILABLE`); dropped
|
|
40
|
+
* on terminal codes whose allowlist excludes it (`IDEMPOTENCY_CONFLICT`
|
|
41
|
+
* — a computed `retry_after` on conflict would leak cached-entry age).
|
|
42
|
+
*/
|
|
43
|
+
retry_after?: number;
|
|
44
|
+
/**
|
|
45
|
+
* Code-specific diagnostic payload. Dropped from the wire shape for
|
|
46
|
+
* codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it
|
|
47
|
+
* (`IDEMPOTENCY_CONFLICT` — a conflict response MUST NOT echo the
|
|
48
|
+
* prior request payload or cached response body).
|
|
49
|
+
*/
|
|
50
|
+
details?: Record<string, unknown>;
|
|
51
|
+
/**
|
|
52
|
+
* Schema validation issues surfaced at the top level of `adcp_error`
|
|
53
|
+
* so operators see JSON Pointers on the first render. Primary use is
|
|
54
|
+
* `VALIDATION_ERROR`; framework validation hooks populate this
|
|
55
|
+
* automatically and also mirror the same array to `details.issues`
|
|
56
|
+
* for buyers that already index into `details` per AdCP spec
|
|
57
|
+
* convention.
|
|
58
|
+
*/
|
|
59
|
+
issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
|
|
60
|
+
schemaPath?: string;
|
|
61
|
+
}>;
|
|
62
|
+
/**
|
|
63
|
+
* Buyer-actionable classification. Populate when the top-level `code`
|
|
64
|
+
* is coarse or producer-internal and a buyer-safe `{code, message}` pair
|
|
65
|
+
* (drawn from the standard error vocabulary) would give the buyer's
|
|
66
|
+
* agent something to act on. Per AdCP 3.2 `core/error.json`, `message`
|
|
67
|
+
* MUST be safe to show to the buyer — no vendor identifiers, ad-server
|
|
68
|
+
* type names, internal object names, internal IDs, or stack traces. The
|
|
69
|
+
* envelope allowlist for `IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_IN_FLIGHT`
|
|
70
|
+
* drops this key — those codes are wire-shape-restricted and never carry
|
|
71
|
+
* a buyer-actionable classification.
|
|
72
|
+
*/
|
|
73
|
+
buyer_reason?: {
|
|
74
|
+
code: string;
|
|
75
|
+
message: string;
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* Whether the failed state-changing request changed seller state (AdCP 3.3
|
|
79
|
+
* `error.mutation_outcome`). Set `'not_applied'` only with pre-commit
|
|
80
|
+
* evidence: a typed rejection raised before the idempotency claim and
|
|
81
|
+
* before any write. Leave it unset to make no claim.
|
|
82
|
+
*/
|
|
83
|
+
mutation_outcome?: AdcpMutationOutcome;
|
|
84
|
+
}
|
|
85
|
+
/** AdCP 3.3 `error.mutation_outcome` values. */
|
|
86
|
+
export type AdcpMutationOutcome = 'not_applied' | 'unknown' | 'applied';
|
|
87
|
+
export interface AdcpErrorPayload {
|
|
88
|
+
code: string;
|
|
89
|
+
message: string;
|
|
90
|
+
/**
|
|
91
|
+
* Closed-enum classifier. Populated by `adcpError()` from
|
|
92
|
+
* `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an
|
|
93
|
+
* override. Marked optional because per-code inside-`adcp_error`
|
|
94
|
+
* allowlists may deliberately drop it from the wire shape — consumers
|
|
95
|
+
* reading a payload parsed off the wire MUST tolerate `undefined`.
|
|
96
|
+
*/
|
|
97
|
+
recovery?: ErrorRecovery;
|
|
98
|
+
field?: string;
|
|
99
|
+
suggestion?: string;
|
|
100
|
+
retry_after?: number;
|
|
101
|
+
details?: Record<string, unknown>;
|
|
102
|
+
/**
|
|
103
|
+
* Schema validation issues (`VALIDATION_ERROR`) exposed at the top
|
|
104
|
+
* level so the list is the first thing a reader sees when inspecting
|
|
105
|
+
* the envelope. Also mirrored at `details.issues` for spec-convention
|
|
106
|
+
* compatibility.
|
|
107
|
+
*/
|
|
108
|
+
issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
|
|
109
|
+
schemaPath?: string;
|
|
110
|
+
}>;
|
|
111
|
+
/**
|
|
112
|
+
* Buyer-actionable classification of the failure. See
|
|
113
|
+
* {@link AdcpErrorOptions.buyer_reason} for the buyer-safety contract.
|
|
114
|
+
*/
|
|
115
|
+
buyer_reason?: {
|
|
116
|
+
code: string;
|
|
117
|
+
message: string;
|
|
118
|
+
};
|
|
119
|
+
mutation_outcome?: AdcpMutationOutcome;
|
|
120
|
+
}
|
|
121
|
+
export interface AdcpErrorResponse {
|
|
122
|
+
[key: string]: unknown;
|
|
123
|
+
content: Array<{
|
|
124
|
+
type: 'text';
|
|
125
|
+
text: string;
|
|
126
|
+
}>;
|
|
127
|
+
isError: true;
|
|
128
|
+
structuredContent: {
|
|
129
|
+
adcp_error: AdcpErrorPayload;
|
|
130
|
+
context?: object;
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Build an L3-compliant MCP tool error response with all three transport layers:
|
|
135
|
+
*
|
|
136
|
+
* 1. `structuredContent.adcp_error` — programmatic extraction (L3)
|
|
137
|
+
* 2. `content[0].text` — JSON text fallback (L2)
|
|
138
|
+
* 3. `isError: true` — MCP error signal
|
|
139
|
+
*
|
|
140
|
+
* Recovery is auto-populated from the standard error code table when not provided.
|
|
141
|
+
*
|
|
142
|
+
* Before returning, any field NOT allowlisted for the given code in
|
|
143
|
+
* {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's
|
|
144
|
+
* ergonomics for every code AND the strict wire shape for codes that have
|
|
145
|
+
* a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:
|
|
146
|
+
* payload-shaped diagnostics like `field`, `suggestion`, and `details`
|
|
147
|
+
* silently drop while standard `recovery` metadata is preserved as the
|
|
148
|
+
* canonical standard-table value. Codes without a registered allowlist
|
|
149
|
+
* pass through unchanged.
|
|
150
|
+
*
|
|
151
|
+
* **Two-layer wire shape.** This builder emits the envelope layer
|
|
152
|
+
* (`structuredContent.adcp_error`) only. For tools whose response
|
|
153
|
+
* schema declares a typed Error arm (`errors[]` required at the top
|
|
154
|
+
* level), the framework dispatcher synthesises the payload-layer
|
|
155
|
+
* `errors[]` from the same data at finalize time, so the wire carries
|
|
156
|
+
* both the envelope marker and the typed Error arm together — no
|
|
157
|
+
* adopter code change required. The list of affected tools is derived
|
|
158
|
+
* at server build from the bundled schema cache. RFC:
|
|
159
|
+
* `docs/proposals/adcperror-two-layer-emission.md`.
|
|
160
|
+
*
|
|
161
|
+
* @example
|
|
162
|
+
* ```typescript
|
|
163
|
+
* import { adcpError } from '@adcp/sdk';
|
|
164
|
+
*
|
|
165
|
+
* server.registerTool("get_products", { inputSchema: schema }, async request => {
|
|
166
|
+
* const { query, context } = request;
|
|
167
|
+
* if (!products.length) {
|
|
168
|
+
* return adcpError('PRODUCT_NOT_FOUND', {
|
|
169
|
+
* message: 'No products match query',
|
|
170
|
+
* field: 'query',
|
|
171
|
+
* suggestion: 'Try a broader search term',
|
|
172
|
+
* context,
|
|
173
|
+
* });
|
|
174
|
+
* }
|
|
175
|
+
* return { content: [...], structuredContent: { products, context } };
|
|
176
|
+
* });
|
|
177
|
+
* ```
|
|
178
|
+
*/
|
|
179
|
+
export declare function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse;
|
|
180
|
+
/**
|
|
181
|
+
* Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.
|
|
182
|
+
* When an allowlisted standard code carries `recovery`, normalize it to
|
|
183
|
+
* the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a
|
|
184
|
+
* caller-supplied value.
|
|
185
|
+
* Codes without an entry pass through unchanged — the allowlist is
|
|
186
|
+
* opt-in per code, not a global filter. The returned object is re-typed
|
|
187
|
+
* as `AdcpErrorPayload` on the assumption that `code` and `message`
|
|
188
|
+
* (the only required fields) are in every registered allowlist; that
|
|
189
|
+
* invariant is re-asserted at runtime by the module-load check in
|
|
190
|
+
* `envelope-allowlist.ts`.
|
|
191
|
+
*/
|
|
192
|
+
export declare function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload;
|
|
193
|
+
export declare function sanitizeStructuredAdcpError<T extends {
|
|
194
|
+
code: string;
|
|
195
|
+
message: string;
|
|
196
|
+
}>(error: T): T;
|
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server-side helpers for producing L3-compliant AdCP error responses.
|
|
3
|
+
*
|
|
4
|
+
* Use `adcpError()` in MCP tool handlers to return structured errors
|
|
5
|
+
* that clients can automatically detect, classify, and act on.
|
|
6
|
+
*/
|
|
7
|
+
import { type StandardErrorCode, type ErrorRecovery } from '../types/error-codes';
|
|
8
|
+
import type { ValidationIssue } from '../validation/schema-validator';
|
|
9
|
+
export interface AdcpErrorOptions {
|
|
10
|
+
message: string;
|
|
11
|
+
/**
|
|
12
|
+
* Opaque request context to echo beside `adcp_error`. Only a non-null,
|
|
13
|
+
* non-array object is echoable, matching the framework envelope behavior.
|
|
14
|
+
*/
|
|
15
|
+
context?: unknown;
|
|
16
|
+
/**
|
|
17
|
+
* Override the recovery classification. Defaults to
|
|
18
|
+
* `STANDARD_ERROR_CODES[code].recovery` for known codes, `'terminal'`
|
|
19
|
+
* otherwise. Dropped from the wire shape for codes whose entry in
|
|
20
|
+
* `ADCP_ERROR_FIELD_ALLOWLIST` excludes it; normalized back to the
|
|
21
|
+
* standard table value for allowlisted standard-code envelopes.
|
|
22
|
+
*/
|
|
23
|
+
recovery?: ErrorRecovery;
|
|
24
|
+
/**
|
|
25
|
+
* Name of the request field the error applies to (validation /
|
|
26
|
+
* constraint errors). Dropped from the wire shape for codes whose
|
|
27
|
+
* `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g. `IDEMPOTENCY_CONFLICT`
|
|
28
|
+
* — a conflict response MUST NOT echo prior payload state).
|
|
29
|
+
*/
|
|
30
|
+
field?: string;
|
|
31
|
+
/**
|
|
32
|
+
* Human-readable remediation hint. Dropped from the wire shape for
|
|
33
|
+
* codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it (e.g.
|
|
34
|
+
* `IDEMPOTENCY_CONFLICT`).
|
|
35
|
+
*/
|
|
36
|
+
suggestion?: string;
|
|
37
|
+
/**
|
|
38
|
+
* Seconds to wait before retrying a transient error. Only meaningful
|
|
39
|
+
* on retryable codes (`RATE_LIMITED`, `SERVICE_UNAVAILABLE`); dropped
|
|
40
|
+
* on terminal codes whose allowlist excludes it (`IDEMPOTENCY_CONFLICT`
|
|
41
|
+
* — a computed `retry_after` on conflict would leak cached-entry age).
|
|
42
|
+
*/
|
|
43
|
+
retry_after?: number;
|
|
44
|
+
/**
|
|
45
|
+
* Code-specific diagnostic payload. Dropped from the wire shape for
|
|
46
|
+
* codes whose `ADCP_ERROR_FIELD_ALLOWLIST` entry excludes it
|
|
47
|
+
* (`IDEMPOTENCY_CONFLICT` — a conflict response MUST NOT echo the
|
|
48
|
+
* prior request payload or cached response body).
|
|
49
|
+
*/
|
|
50
|
+
details?: Record<string, unknown>;
|
|
51
|
+
/**
|
|
52
|
+
* Schema validation issues surfaced at the top level of `adcp_error`
|
|
53
|
+
* so operators see JSON Pointers on the first render. Primary use is
|
|
54
|
+
* `VALIDATION_ERROR`; framework validation hooks populate this
|
|
55
|
+
* automatically and also mirror the same array to `details.issues`
|
|
56
|
+
* for buyers that already index into `details` per AdCP spec
|
|
57
|
+
* convention.
|
|
58
|
+
*/
|
|
59
|
+
issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
|
|
60
|
+
schemaPath?: string;
|
|
61
|
+
}>;
|
|
62
|
+
/**
|
|
63
|
+
* Buyer-actionable classification. Populate when the top-level `code`
|
|
64
|
+
* is coarse or producer-internal and a buyer-safe `{code, message}` pair
|
|
65
|
+
* (drawn from the standard error vocabulary) would give the buyer's
|
|
66
|
+
* agent something to act on. Per AdCP 3.2 `core/error.json`, `message`
|
|
67
|
+
* MUST be safe to show to the buyer — no vendor identifiers, ad-server
|
|
68
|
+
* type names, internal object names, internal IDs, or stack traces. The
|
|
69
|
+
* envelope allowlist for `IDEMPOTENCY_CONFLICT` / `IDEMPOTENCY_IN_FLIGHT`
|
|
70
|
+
* drops this key — those codes are wire-shape-restricted and never carry
|
|
71
|
+
* a buyer-actionable classification.
|
|
72
|
+
*/
|
|
73
|
+
buyer_reason?: {
|
|
74
|
+
code: string;
|
|
75
|
+
message: string;
|
|
76
|
+
};
|
|
77
|
+
/**
|
|
78
|
+
* Whether the failed state-changing request changed seller state (AdCP 3.3
|
|
79
|
+
* `error.mutation_outcome`). Set `'not_applied'` only with pre-commit
|
|
80
|
+
* evidence: a typed rejection raised before the idempotency claim and
|
|
81
|
+
* before any write. Leave it unset to make no claim.
|
|
82
|
+
*/
|
|
83
|
+
mutation_outcome?: AdcpMutationOutcome;
|
|
84
|
+
}
|
|
85
|
+
/** AdCP 3.3 `error.mutation_outcome` values. */
|
|
86
|
+
export type AdcpMutationOutcome = 'not_applied' | 'unknown' | 'applied';
|
|
87
|
+
export interface AdcpErrorPayload {
|
|
88
|
+
code: string;
|
|
89
|
+
message: string;
|
|
90
|
+
/**
|
|
91
|
+
* Closed-enum classifier. Populated by `adcpError()` from
|
|
92
|
+
* `STANDARD_ERROR_CODES[code].recovery` unless the caller provides an
|
|
93
|
+
* override. Marked optional because per-code inside-`adcp_error`
|
|
94
|
+
* allowlists may deliberately drop it from the wire shape — consumers
|
|
95
|
+
* reading a payload parsed off the wire MUST tolerate `undefined`.
|
|
96
|
+
*/
|
|
97
|
+
recovery?: ErrorRecovery;
|
|
98
|
+
field?: string;
|
|
99
|
+
suggestion?: string;
|
|
100
|
+
retry_after?: number;
|
|
101
|
+
details?: Record<string, unknown>;
|
|
102
|
+
/**
|
|
103
|
+
* Schema validation issues (`VALIDATION_ERROR`) exposed at the top
|
|
104
|
+
* level so the list is the first thing a reader sees when inspecting
|
|
105
|
+
* the envelope. Also mirrored at `details.issues` for spec-convention
|
|
106
|
+
* compatibility.
|
|
107
|
+
*/
|
|
108
|
+
issues?: Array<Omit<ValidationIssue, 'schemaPath'> & {
|
|
109
|
+
schemaPath?: string;
|
|
110
|
+
}>;
|
|
111
|
+
/**
|
|
112
|
+
* Buyer-actionable classification of the failure. See
|
|
113
|
+
* {@link AdcpErrorOptions.buyer_reason} for the buyer-safety contract.
|
|
114
|
+
*/
|
|
115
|
+
buyer_reason?: {
|
|
116
|
+
code: string;
|
|
117
|
+
message: string;
|
|
118
|
+
};
|
|
119
|
+
mutation_outcome?: AdcpMutationOutcome;
|
|
120
|
+
}
|
|
121
|
+
export interface AdcpErrorResponse {
|
|
122
|
+
[key: string]: unknown;
|
|
123
|
+
content: Array<{
|
|
124
|
+
type: 'text';
|
|
125
|
+
text: string;
|
|
126
|
+
}>;
|
|
127
|
+
isError: true;
|
|
128
|
+
structuredContent: {
|
|
129
|
+
adcp_error: AdcpErrorPayload;
|
|
130
|
+
context?: object;
|
|
131
|
+
};
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Build an L3-compliant MCP tool error response with all three transport layers:
|
|
135
|
+
*
|
|
136
|
+
* 1. `structuredContent.adcp_error` — programmatic extraction (L3)
|
|
137
|
+
* 2. `content[0].text` — JSON text fallback (L2)
|
|
138
|
+
* 3. `isError: true` — MCP error signal
|
|
139
|
+
*
|
|
140
|
+
* Recovery is auto-populated from the standard error code table when not provided.
|
|
141
|
+
*
|
|
142
|
+
* Before returning, any field NOT allowlisted for the given code in
|
|
143
|
+
* {@link ADCP_ERROR_FIELD_ALLOWLIST} is dropped — sellers get the builder's
|
|
144
|
+
* ergonomics for every code AND the strict wire shape for codes that have
|
|
145
|
+
* a registered allowlist. `IDEMPOTENCY_CONFLICT` is the canonical case:
|
|
146
|
+
* payload-shaped diagnostics like `field`, `suggestion`, and `details`
|
|
147
|
+
* silently drop while standard `recovery` metadata is preserved as the
|
|
148
|
+
* canonical standard-table value. Codes without a registered allowlist
|
|
149
|
+
* pass through unchanged.
|
|
150
|
+
*
|
|
151
|
+
* **Two-layer wire shape.** This builder emits the envelope layer
|
|
152
|
+
* (`structuredContent.adcp_error`) only. For tools whose response
|
|
153
|
+
* schema declares a typed Error arm (`errors[]` required at the top
|
|
154
|
+
* level), the framework dispatcher synthesises the payload-layer
|
|
155
|
+
* `errors[]` from the same data at finalize time, so the wire carries
|
|
156
|
+
* both the envelope marker and the typed Error arm together — no
|
|
157
|
+
* adopter code change required. The list of affected tools is derived
|
|
158
|
+
* at server build from the bundled schema cache. RFC:
|
|
159
|
+
* `docs/proposals/adcperror-two-layer-emission.md`.
|
|
160
|
+
*
|
|
161
|
+
* @example
|
|
162
|
+
* ```typescript
|
|
163
|
+
* import { adcpError } from '@adcp/sdk';
|
|
164
|
+
*
|
|
165
|
+
* server.registerTool("get_products", { inputSchema: schema }, async request => {
|
|
166
|
+
* const { query, context } = request;
|
|
167
|
+
* if (!products.length) {
|
|
168
|
+
* return adcpError('PRODUCT_NOT_FOUND', {
|
|
169
|
+
* message: 'No products match query',
|
|
170
|
+
* field: 'query',
|
|
171
|
+
* suggestion: 'Try a broader search term',
|
|
172
|
+
* context,
|
|
173
|
+
* });
|
|
174
|
+
* }
|
|
175
|
+
* return { content: [...], structuredContent: { products, context } };
|
|
176
|
+
* });
|
|
177
|
+
* ```
|
|
178
|
+
*/
|
|
179
|
+
export declare function adcpError(code: StandardErrorCode | (string & {}), options: AdcpErrorOptions): AdcpErrorResponse;
|
|
180
|
+
/**
|
|
181
|
+
* Drop every field not in {@link ADCP_ERROR_FIELD_ALLOWLIST} for `code`.
|
|
182
|
+
* When an allowlisted standard code carries `recovery`, normalize it to
|
|
183
|
+
* the fixed classifier from `STANDARD_ERROR_CODES` instead of trusting a
|
|
184
|
+
* caller-supplied value.
|
|
185
|
+
* Codes without an entry pass through unchanged — the allowlist is
|
|
186
|
+
* opt-in per code, not a global filter. The returned object is re-typed
|
|
187
|
+
* as `AdcpErrorPayload` on the assumption that `code` and `message`
|
|
188
|
+
* (the only required fields) are in every registered allowlist; that
|
|
189
|
+
* invariant is re-asserted at runtime by the module-load check in
|
|
190
|
+
* `envelope-allowlist.ts`.
|
|
191
|
+
*/
|
|
192
|
+
export declare function applyAdcpErrorAllowlist(code: string, payload: Record<string, unknown>): AdcpErrorPayload;
|
|
193
|
+
export declare function sanitizeStructuredAdcpError<T extends {
|
|
194
|
+
code: string;
|
|
195
|
+
message: string;
|
|
196
|
+
}>(error: T): T;
|
|
@@ -0,0 +1,118 @@
|
|
|
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 adcp_error_response_exports = {};
|
|
20
|
+
__export(adcp_error_response_exports, {
|
|
21
|
+
adcpError: () => adcpError,
|
|
22
|
+
applyAdcpErrorAllowlist: () => applyAdcpErrorAllowlist,
|
|
23
|
+
sanitizeStructuredAdcpError: () => sanitizeStructuredAdcpError
|
|
24
|
+
});
|
|
25
|
+
module.exports = __toCommonJS(adcp_error_response_exports);
|
|
26
|
+
var import_error_codes = require('../types/error-codes.js');
|
|
27
|
+
var import_envelope_allowlist = require('./envelope-allowlist.js');
|
|
28
|
+
var import_pick_safe_details = require('./pick-safe-details.js');
|
|
29
|
+
function isEchoableContext(value) {
|
|
30
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
31
|
+
}
|
|
32
|
+
const AUTHORIZATION_REQUIRED_DETAIL_KEYS = [
|
|
33
|
+
"required_connections",
|
|
34
|
+
"missing_connections",
|
|
35
|
+
"provider",
|
|
36
|
+
"connection_type",
|
|
37
|
+
"required_for",
|
|
38
|
+
"scope",
|
|
39
|
+
"status",
|
|
40
|
+
"resource_ref",
|
|
41
|
+
"platform_account_id",
|
|
42
|
+
"identity_id",
|
|
43
|
+
"handle",
|
|
44
|
+
"profile_url",
|
|
45
|
+
"post_id",
|
|
46
|
+
"post_url",
|
|
47
|
+
"authorization_url",
|
|
48
|
+
"authorization_instructions",
|
|
49
|
+
"checked_at",
|
|
50
|
+
"expires_at",
|
|
51
|
+
"reference_authorization"
|
|
52
|
+
];
|
|
53
|
+
function adcpError(code, options) {
|
|
54
|
+
const recovery = normalizeRecoveryForCode(code, options.recovery);
|
|
55
|
+
const adcp_error = {
|
|
56
|
+
code,
|
|
57
|
+
message: options.message,
|
|
58
|
+
recovery,
|
|
59
|
+
...options.field != null && { field: options.field },
|
|
60
|
+
...options.suggestion != null && { suggestion: options.suggestion },
|
|
61
|
+
...options.retry_after != null && { retry_after: options.retry_after },
|
|
62
|
+
...options.issues != null && { issues: options.issues },
|
|
63
|
+
...options.details != null && { details: options.details },
|
|
64
|
+
...options.buyer_reason != null && { buyer_reason: options.buyer_reason },
|
|
65
|
+
...options.mutation_outcome != null && { mutation_outcome: options.mutation_outcome }
|
|
66
|
+
};
|
|
67
|
+
const filtered = applyAdcpErrorAllowlist(code, adcp_error);
|
|
68
|
+
const structuredContent = {
|
|
69
|
+
adcp_error: filtered,
|
|
70
|
+
...isEchoableContext(options.context) ? { context: options.context } : {}
|
|
71
|
+
};
|
|
72
|
+
return {
|
|
73
|
+
content: [{ type: "text", text: JSON.stringify(structuredContent) }],
|
|
74
|
+
isError: true,
|
|
75
|
+
structuredContent
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
function applyAdcpErrorAllowlist(code, payload) {
|
|
79
|
+
payload = sanitizeAdcpErrorDetails(code, payload);
|
|
80
|
+
const allowlist = import_envelope_allowlist.ADCP_ERROR_FIELD_ALLOWLIST[code];
|
|
81
|
+
if (!allowlist) return payload;
|
|
82
|
+
const out = {};
|
|
83
|
+
for (const [key, value] of Object.entries(payload)) {
|
|
84
|
+
if (!allowlist.has(key)) continue;
|
|
85
|
+
out[key] = key === "recovery" ? normalizeAllowlistedRecoveryForCode(code, value) : value;
|
|
86
|
+
}
|
|
87
|
+
return out;
|
|
88
|
+
}
|
|
89
|
+
function sanitizeStructuredAdcpError(error) {
|
|
90
|
+
return applyAdcpErrorAllowlist(error.code, error);
|
|
91
|
+
}
|
|
92
|
+
function sanitizeAdcpErrorDetails(code, payload) {
|
|
93
|
+
if (code !== "AUTHORIZATION_REQUIRED" || payload.details === void 0) return payload;
|
|
94
|
+
const sanitizedDetails = (0, import_pick_safe_details.pickSafeDetails)(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {
|
|
95
|
+
maxDepth: 4,
|
|
96
|
+
maxSizeBytes: 4096
|
|
97
|
+
});
|
|
98
|
+
const { details: _details, ...rest } = payload;
|
|
99
|
+
return sanitizedDetails === void 0 ? rest : { ...rest, details: sanitizedDetails };
|
|
100
|
+
}
|
|
101
|
+
function isErrorRecovery(value) {
|
|
102
|
+
return value === "transient" || value === "correctable" || value === "terminal";
|
|
103
|
+
}
|
|
104
|
+
function normalizeRecoveryForCode(code, value) {
|
|
105
|
+
return isErrorRecovery(value) ? value : (0, import_error_codes.isStandardErrorCode)(code) ? import_error_codes.STANDARD_ERROR_CODES[code].recovery : "terminal";
|
|
106
|
+
}
|
|
107
|
+
function normalizeAllowlistedRecoveryForCode(code, value) {
|
|
108
|
+
if ((0, import_error_codes.isStandardErrorCode)(code)) {
|
|
109
|
+
return import_error_codes.STANDARD_ERROR_CODES[code].recovery;
|
|
110
|
+
}
|
|
111
|
+
return normalizeRecoveryForCode(code, value);
|
|
112
|
+
}
|
|
113
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
114
|
+
0 && (module.exports = {
|
|
115
|
+
adcpError,
|
|
116
|
+
applyAdcpErrorAllowlist,
|
|
117
|
+
sanitizeStructuredAdcpError
|
|
118
|
+
});
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import {
|
|
2
|
+
STANDARD_ERROR_CODES,
|
|
3
|
+
isStandardErrorCode
|
|
4
|
+
} from "../types/error-codes.mjs";
|
|
5
|
+
import { ADCP_ERROR_FIELD_ALLOWLIST } from "./envelope-allowlist.mjs";
|
|
6
|
+
import { pickSafeDetails } from "./pick-safe-details.mjs";
|
|
7
|
+
function isEchoableContext(value) {
|
|
8
|
+
return value !== null && typeof value === "object" && !Array.isArray(value);
|
|
9
|
+
}
|
|
10
|
+
const AUTHORIZATION_REQUIRED_DETAIL_KEYS = [
|
|
11
|
+
"required_connections",
|
|
12
|
+
"missing_connections",
|
|
13
|
+
"provider",
|
|
14
|
+
"connection_type",
|
|
15
|
+
"required_for",
|
|
16
|
+
"scope",
|
|
17
|
+
"status",
|
|
18
|
+
"resource_ref",
|
|
19
|
+
"platform_account_id",
|
|
20
|
+
"identity_id",
|
|
21
|
+
"handle",
|
|
22
|
+
"profile_url",
|
|
23
|
+
"post_id",
|
|
24
|
+
"post_url",
|
|
25
|
+
"authorization_url",
|
|
26
|
+
"authorization_instructions",
|
|
27
|
+
"checked_at",
|
|
28
|
+
"expires_at",
|
|
29
|
+
"reference_authorization"
|
|
30
|
+
];
|
|
31
|
+
function adcpError(code, options) {
|
|
32
|
+
const recovery = normalizeRecoveryForCode(code, options.recovery);
|
|
33
|
+
const adcp_error = {
|
|
34
|
+
code,
|
|
35
|
+
message: options.message,
|
|
36
|
+
recovery,
|
|
37
|
+
...options.field != null && { field: options.field },
|
|
38
|
+
...options.suggestion != null && { suggestion: options.suggestion },
|
|
39
|
+
...options.retry_after != null && { retry_after: options.retry_after },
|
|
40
|
+
...options.issues != null && { issues: options.issues },
|
|
41
|
+
...options.details != null && { details: options.details },
|
|
42
|
+
...options.buyer_reason != null && { buyer_reason: options.buyer_reason },
|
|
43
|
+
...options.mutation_outcome != null && { mutation_outcome: options.mutation_outcome }
|
|
44
|
+
};
|
|
45
|
+
const filtered = applyAdcpErrorAllowlist(code, adcp_error);
|
|
46
|
+
const structuredContent = {
|
|
47
|
+
adcp_error: filtered,
|
|
48
|
+
...isEchoableContext(options.context) ? { context: options.context } : {}
|
|
49
|
+
};
|
|
50
|
+
return {
|
|
51
|
+
content: [{ type: "text", text: JSON.stringify(structuredContent) }],
|
|
52
|
+
isError: true,
|
|
53
|
+
structuredContent
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
function applyAdcpErrorAllowlist(code, payload) {
|
|
57
|
+
payload = sanitizeAdcpErrorDetails(code, payload);
|
|
58
|
+
const allowlist = ADCP_ERROR_FIELD_ALLOWLIST[code];
|
|
59
|
+
if (!allowlist) return payload;
|
|
60
|
+
const out = {};
|
|
61
|
+
for (const [key, value] of Object.entries(payload)) {
|
|
62
|
+
if (!allowlist.has(key)) continue;
|
|
63
|
+
out[key] = key === "recovery" ? normalizeAllowlistedRecoveryForCode(code, value) : value;
|
|
64
|
+
}
|
|
65
|
+
return out;
|
|
66
|
+
}
|
|
67
|
+
function sanitizeStructuredAdcpError(error) {
|
|
68
|
+
return applyAdcpErrorAllowlist(error.code, error);
|
|
69
|
+
}
|
|
70
|
+
function sanitizeAdcpErrorDetails(code, payload) {
|
|
71
|
+
if (code !== "AUTHORIZATION_REQUIRED" || payload.details === void 0) return payload;
|
|
72
|
+
const sanitizedDetails = pickSafeDetails(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {
|
|
73
|
+
maxDepth: 4,
|
|
74
|
+
maxSizeBytes: 4096
|
|
75
|
+
});
|
|
76
|
+
const { details: _details, ...rest } = payload;
|
|
77
|
+
return sanitizedDetails === void 0 ? rest : { ...rest, details: sanitizedDetails };
|
|
78
|
+
}
|
|
79
|
+
function isErrorRecovery(value) {
|
|
80
|
+
return value === "transient" || value === "correctable" || value === "terminal";
|
|
81
|
+
}
|
|
82
|
+
function normalizeRecoveryForCode(code, value) {
|
|
83
|
+
return isErrorRecovery(value) ? value : isStandardErrorCode(code) ? STANDARD_ERROR_CODES[code].recovery : "terminal";
|
|
84
|
+
}
|
|
85
|
+
function normalizeAllowlistedRecoveryForCode(code, value) {
|
|
86
|
+
if (isStandardErrorCode(code)) {
|
|
87
|
+
return STANDARD_ERROR_CODES[code].recovery;
|
|
88
|
+
}
|
|
89
|
+
return normalizeRecoveryForCode(code, value);
|
|
90
|
+
}
|
|
91
|
+
export {
|
|
92
|
+
adcpError,
|
|
93
|
+
applyAdcpErrorAllowlist,
|
|
94
|
+
sanitizeStructuredAdcpError
|
|
95
|
+
};
|
|
@@ -22,7 +22,7 @@ __export(buyer_retry_policy_exports, {
|
|
|
22
22
|
decideRetry: () => decideRetry
|
|
23
23
|
});
|
|
24
24
|
module.exports = __toCommonJS(buyer_retry_policy_exports);
|
|
25
|
-
var
|
|
25
|
+
var import_adcp_error_response = require('./adcp-error-response.js');
|
|
26
26
|
var import_error_codes = require('../types/error-codes.js');
|
|
27
27
|
const EXPLICIT_CODE_POLICY = {
|
|
28
28
|
// Transients — server-side, retry-safe with same idempotency_key.
|
|
@@ -218,7 +218,7 @@ function isRecord(value) {
|
|
|
218
218
|
}
|
|
219
219
|
function authorizationRequiredEscalationContext(error) {
|
|
220
220
|
if (error.code !== "AUTHORIZATION_REQUIRED" || error.details === void 0) return {};
|
|
221
|
-
const sanitized = (0,
|
|
221
|
+
const sanitized = (0, import_adcp_error_response.applyAdcpErrorAllowlist)("AUTHORIZATION_REQUIRED", {
|
|
222
222
|
code: error.code,
|
|
223
223
|
message: error.message,
|
|
224
224
|
recovery: error.recovery,
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { applyAdcpErrorAllowlist } from "
|
|
1
|
+
import { applyAdcpErrorAllowlist } from "./adcp-error-response.mjs";
|
|
2
2
|
import { STANDARD_ERROR_CODES } from "../types/error-codes.mjs";
|
|
3
3
|
const EXPLICIT_CODE_POLICY = {
|
|
4
4
|
// Transients — server-side, retry-safe with same idempotency_key.
|
|
@@ -45,6 +45,12 @@ export interface MediaBuyFeatures {
|
|
|
45
45
|
conversionTracking?: boolean;
|
|
46
46
|
/** Agent supports first-party CRM audience management (sync_audiences) */
|
|
47
47
|
audienceTargeting?: boolean;
|
|
48
|
+
/**
|
|
49
|
+
* AdCP 3.3: seller honors `packages[].start_requires_all_creatives_approved:
|
|
50
|
+
* true` on `control_media_buy`. Without it, sellers refuse `true` with
|
|
51
|
+
* `UNSUPPORTED_FEATURE` and buyers must not send it. Absent means undeclared.
|
|
52
|
+
*/
|
|
53
|
+
creativeStartPolicy?: boolean;
|
|
48
54
|
}
|
|
49
55
|
/**
|
|
50
56
|
* Account management capabilities declared by the seller
|
|
@@ -45,6 +45,12 @@ export interface MediaBuyFeatures {
|
|
|
45
45
|
conversionTracking?: boolean;
|
|
46
46
|
/** Agent supports first-party CRM audience management (sync_audiences) */
|
|
47
47
|
audienceTargeting?: boolean;
|
|
48
|
+
/**
|
|
49
|
+
* AdCP 3.3: seller honors `packages[].start_requires_all_creatives_approved:
|
|
50
|
+
* true` on `control_media_buy`. Without it, sellers refuse `true` with
|
|
51
|
+
* `UNSUPPORTED_FEATURE` and buyers must not send it. Absent means undeclared.
|
|
52
|
+
*/
|
|
53
|
+
creativeStartPolicy?: boolean;
|
|
48
54
|
}
|
|
49
55
|
/**
|
|
50
56
|
* Account management capabilities declared by the seller
|
|
@@ -293,7 +293,10 @@ function parseCapabilitiesResponse(response) {
|
|
|
293
293
|
propertyListFiltering: response.media_buy?.features?.property_list_filtering ?? false,
|
|
294
294
|
contentStandards: response.media_buy?.features?.content_standards === true || declaresContentStandardsSpecialism,
|
|
295
295
|
conversionTracking: response.media_buy?.features?.conversion_tracking ?? false,
|
|
296
|
-
audienceTargeting: response.media_buy?.features?.audience_targeting ?? false
|
|
296
|
+
audienceTargeting: response.media_buy?.features?.audience_targeting ?? false,
|
|
297
|
+
...typeof response.media_buy?.features?.creative_start_policy === "boolean" && {
|
|
298
|
+
creativeStartPolicy: response.media_buy.features.creative_start_policy
|
|
299
|
+
}
|
|
297
300
|
};
|
|
298
301
|
let account;
|
|
299
302
|
if (response.account) {
|
|
@@ -480,8 +483,9 @@ const FEATURE_KEY_MAP = {
|
|
|
480
483
|
content_standards: "contentStandards",
|
|
481
484
|
conversion_tracking: "conversionTracking",
|
|
482
485
|
audience_targeting: "audienceTargeting",
|
|
483
|
-
audience_management: "audienceTargeting"
|
|
486
|
+
audience_management: "audienceTargeting",
|
|
484
487
|
// legacy alias
|
|
488
|
+
creative_start_policy: "creativeStartPolicy"
|
|
485
489
|
};
|
|
486
490
|
function resolveFeature(capabilities, feature) {
|
|
487
491
|
if (capabilities.protocols.includes(feature)) {
|