@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
|
@@ -1,94 +1 @@
|
|
|
1
|
-
|
|
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
|
-
};
|
|
44
|
-
const filtered = applyAdcpErrorAllowlist(code, adcp_error);
|
|
45
|
-
const structuredContent = {
|
|
46
|
-
adcp_error: filtered,
|
|
47
|
-
...isEchoableContext(options.context) ? { context: options.context } : {}
|
|
48
|
-
};
|
|
49
|
-
return {
|
|
50
|
-
content: [{ type: "text", text: JSON.stringify(structuredContent) }],
|
|
51
|
-
isError: true,
|
|
52
|
-
structuredContent
|
|
53
|
-
};
|
|
54
|
-
}
|
|
55
|
-
function applyAdcpErrorAllowlist(code, payload) {
|
|
56
|
-
payload = sanitizeAdcpErrorDetails(code, payload);
|
|
57
|
-
const allowlist = ADCP_ERROR_FIELD_ALLOWLIST[code];
|
|
58
|
-
if (!allowlist) return payload;
|
|
59
|
-
const out = {};
|
|
60
|
-
for (const [key, value] of Object.entries(payload)) {
|
|
61
|
-
if (!allowlist.has(key)) continue;
|
|
62
|
-
out[key] = key === "recovery" ? normalizeAllowlistedRecoveryForCode(code, value) : value;
|
|
63
|
-
}
|
|
64
|
-
return out;
|
|
65
|
-
}
|
|
66
|
-
function sanitizeStructuredAdcpError(error) {
|
|
67
|
-
return applyAdcpErrorAllowlist(error.code, error);
|
|
68
|
-
}
|
|
69
|
-
function sanitizeAdcpErrorDetails(code, payload) {
|
|
70
|
-
if (code !== "AUTHORIZATION_REQUIRED" || payload.details === void 0) return payload;
|
|
71
|
-
const sanitizedDetails = pickSafeDetails(payload.details, AUTHORIZATION_REQUIRED_DETAIL_KEYS, {
|
|
72
|
-
maxDepth: 4,
|
|
73
|
-
maxSizeBytes: 4096
|
|
74
|
-
});
|
|
75
|
-
const { details: _details, ...rest } = payload;
|
|
76
|
-
return sanitizedDetails === void 0 ? rest : { ...rest, details: sanitizedDetails };
|
|
77
|
-
}
|
|
78
|
-
function isErrorRecovery(value) {
|
|
79
|
-
return value === "transient" || value === "correctable" || value === "terminal";
|
|
80
|
-
}
|
|
81
|
-
function normalizeRecoveryForCode(code, value) {
|
|
82
|
-
return isErrorRecovery(value) ? value : isStandardErrorCode(code) ? STANDARD_ERROR_CODES[code].recovery : "terminal";
|
|
83
|
-
}
|
|
84
|
-
function normalizeAllowlistedRecoveryForCode(code, value) {
|
|
85
|
-
if (isStandardErrorCode(code)) {
|
|
86
|
-
return STANDARD_ERROR_CODES[code].recovery;
|
|
87
|
-
}
|
|
88
|
-
return normalizeRecoveryForCode(code, value);
|
|
89
|
-
}
|
|
90
|
-
export {
|
|
91
|
-
adcpError,
|
|
92
|
-
applyAdcpErrorAllowlist,
|
|
93
|
-
sanitizeStructuredAdcpError
|
|
94
|
-
};
|
|
1
|
+
export * from "../utils/adcp-error-response.mjs";
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export { adcpError } from './errors.mjs';
|
|
2
|
-
export type { AdcpErrorOptions, AdcpErrorPayload, AdcpErrorResponse } from './errors.mjs';
|
|
2
|
+
export type { AdcpErrorOptions, AdcpErrorPayload, AdcpErrorResponse, AdcpMutationOutcome } from './errors.mjs';
|
|
3
3
|
export { normalizeError, normalizeErrors } from './normalize-errors.mjs';
|
|
4
4
|
export type { NormalizedError } from './normalize-errors.mjs';
|
|
5
5
|
export { pickSafeDetails } from './pick-safe-details.mjs';
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export { adcpError } from './errors';
|
|
2
|
-
export type { AdcpErrorOptions, AdcpErrorPayload, AdcpErrorResponse } from './errors';
|
|
2
|
+
export type { AdcpErrorOptions, AdcpErrorPayload, AdcpErrorResponse, AdcpMutationOutcome } from './errors';
|
|
3
3
|
export { normalizeError, normalizeErrors } from './normalize-errors';
|
|
4
4
|
export type { NormalizedError } from './normalize-errors';
|
|
5
5
|
export { pickSafeDetails } from './pick-safe-details';
|
|
@@ -25,6 +25,7 @@ var import_server = require("@modelcontextprotocol/server");
|
|
|
25
25
|
var import_node = require("@modelcontextprotocol/node");
|
|
26
26
|
var import_adcp_server = require('./adcp-server.js');
|
|
27
27
|
var import_create_adcp_server = require('./create-adcp-server.js');
|
|
28
|
+
var import_declared_input_schema = require('./declared-input-schema.js');
|
|
28
29
|
var import_mcp_app = require('./mcp-app.js');
|
|
29
30
|
var import_schema_loader = require('../validation/schema-loader.js');
|
|
30
31
|
var import_adcp_version_config = require('../utils/adcp-version-config.js');
|
|
@@ -88,8 +89,17 @@ function officialAdcpToolSummary(toolName, adcpVersion, profile) {
|
|
|
88
89
|
adcpVersion
|
|
89
90
|
) ?? (0, import_schema_loader.getToolSchemaDocument)(toolName, "request", adcpVersion)?.schema.description?.toString();
|
|
90
91
|
}
|
|
91
|
-
function
|
|
92
|
-
|
|
92
|
+
function modernInputJsonSchema(toolName, schema) {
|
|
93
|
+
try {
|
|
94
|
+
const probe = new import_server.McpServer({ name: "adcp-input-schema-probe", version: "0.0.0" });
|
|
95
|
+
probe.registerTool(toolName, { inputSchema: schema }, async () => ({ content: [] }));
|
|
96
|
+
return probe.toolInputSchemaJson(toolName);
|
|
97
|
+
} catch {
|
|
98
|
+
return void 0;
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
function schemaForModernMcp(schema, hasOfficialSchema, advertisedSchema = schema) {
|
|
102
|
+
if (!hasOfficialSchema && !hasJsonConversionForSchemaOrRawShape(advertisedSchema) && !warnedAboutCustomSchemaJsonConversion) {
|
|
93
103
|
warnedAboutCustomSchemaJsonConversion = true;
|
|
94
104
|
console.warn(
|
|
95
105
|
"[adcp/serve] A custom MCP tool schema does not expose ~standard.jsonSchema. With Zod, complete modern tools/list schemas require zod >=4.2.0. Current AdCP tools use bundled official JSON Schemas, but this custom or legacy tool may be advertised with an empty schema."
|
|
@@ -114,6 +124,8 @@ function createModernMcpServerAdapter(agentServer) {
|
|
|
114
124
|
const description = tool.description ?? officialAdcpToolSummary(tool.name, adcpVersion, pinnedMcpToolProfile);
|
|
115
125
|
const frameworkAdcpTool = tool._meta?.adcp_version === adcpVersion;
|
|
116
126
|
const advertisedInputSchema = frameworkAdcpTool ? officialAdcpInputSchema(tool.name, adcpVersion, pinnedMcpToolProfile) : void 0;
|
|
127
|
+
const declaredInputSchema = (0, import_declared_input_schema.getDeclaredInputSchema)(sdkServer, tool.name);
|
|
128
|
+
const declaredInputJsonSchema = declaredInputSchema !== void 0 ? modernInputJsonSchema(tool.name, declaredInputSchema) ?? { type: "object", properties: {} } : void 0;
|
|
117
129
|
return {
|
|
118
130
|
...definition,
|
|
119
131
|
...description !== void 0 && { description },
|
|
@@ -122,9 +134,14 @@ function createModernMcpServerAdapter(agentServer) {
|
|
|
122
134
|
// framework's AdCP validator must see domain-invalid objects so it can
|
|
123
135
|
// return a structured `adcp_error` + context echo; the official strict
|
|
124
136
|
// projection remains discovery-only below.
|
|
125
|
-
inputSchema: schemaForModernMcp(
|
|
137
|
+
inputSchema: schemaForModernMcp(
|
|
138
|
+
inputSchema,
|
|
139
|
+
advertisedInputSchema !== void 0,
|
|
140
|
+
declaredInputSchema ?? inputSchema
|
|
141
|
+
)
|
|
126
142
|
},
|
|
127
143
|
...advertisedInputSchema !== void 0 && { advertisedInputSchema },
|
|
144
|
+
...declaredInputJsonSchema !== void 0 && { declaredInputJsonSchema },
|
|
128
145
|
// Output schemas can dwarf the input discovery surface and are not
|
|
129
146
|
// required for clients to form tool calls. Preserve an adopter's
|
|
130
147
|
// explicitly registered schema, but do not replace it with a bundled
|
|
@@ -215,7 +232,7 @@ function createModernMcpServerAdapter(agentServer) {
|
|
|
215
232
|
}).map((tool) => {
|
|
216
233
|
const registered = registeredTools.get(tool.name);
|
|
217
234
|
const frameworkAdcpTool = tool._meta?.adcp_version === adcpVersion;
|
|
218
|
-
const discoveryInputSchema = frameworkAdcpTool ? officialAdcpInputSchema(tool.name, discoveryVersion, discoveryProfile) : tool.
|
|
235
|
+
const discoveryInputSchema = frameworkAdcpTool ? officialAdcpInputSchema(tool.name, discoveryVersion, discoveryProfile) : tool.declaredInputJsonSchema;
|
|
219
236
|
return {
|
|
220
237
|
name: tool.name,
|
|
221
238
|
...tool.title !== void 0 && { title: tool.title },
|
|
@@ -18,6 +18,7 @@ import {
|
|
|
18
18
|
listRegisteredToolDefinitions
|
|
19
19
|
} from "./adcp-server.mjs";
|
|
20
20
|
import { ADCP_INSTRUCTIONS_RESOLVER, MEDIA_BUY_MCP_TOOL_PROFILE } from "./create-adcp-server.mjs";
|
|
21
|
+
import { getDeclaredInputSchema } from "./declared-input-schema.mjs";
|
|
21
22
|
import {
|
|
22
23
|
isMcpAppToolMeta,
|
|
23
24
|
mcpAppResourceUri,
|
|
@@ -87,8 +88,17 @@ function officialAdcpToolSummary(toolName, adcpVersion, profile) {
|
|
|
87
88
|
adcpVersion
|
|
88
89
|
) ?? getToolSchemaDocument(toolName, "request", adcpVersion)?.schema.description?.toString();
|
|
89
90
|
}
|
|
90
|
-
function
|
|
91
|
-
|
|
91
|
+
function modernInputJsonSchema(toolName, schema) {
|
|
92
|
+
try {
|
|
93
|
+
const probe = new ModernMcpServer({ name: "adcp-input-schema-probe", version: "0.0.0" });
|
|
94
|
+
probe.registerTool(toolName, { inputSchema: schema }, async () => ({ content: [] }));
|
|
95
|
+
return probe.toolInputSchemaJson(toolName);
|
|
96
|
+
} catch {
|
|
97
|
+
return void 0;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
function schemaForModernMcp(schema, hasOfficialSchema, advertisedSchema = schema) {
|
|
101
|
+
if (!hasOfficialSchema && !hasJsonConversionForSchemaOrRawShape(advertisedSchema) && !warnedAboutCustomSchemaJsonConversion) {
|
|
92
102
|
warnedAboutCustomSchemaJsonConversion = true;
|
|
93
103
|
console.warn(
|
|
94
104
|
"[adcp/serve] A custom MCP tool schema does not expose ~standard.jsonSchema. With Zod, complete modern tools/list schemas require zod >=4.2.0. Current AdCP tools use bundled official JSON Schemas, but this custom or legacy tool may be advertised with an empty schema."
|
|
@@ -113,6 +123,8 @@ function createModernMcpServerAdapter(agentServer) {
|
|
|
113
123
|
const description = tool.description ?? officialAdcpToolSummary(tool.name, adcpVersion, pinnedMcpToolProfile);
|
|
114
124
|
const frameworkAdcpTool = tool._meta?.adcp_version === adcpVersion;
|
|
115
125
|
const advertisedInputSchema = frameworkAdcpTool ? officialAdcpInputSchema(tool.name, adcpVersion, pinnedMcpToolProfile) : void 0;
|
|
126
|
+
const declaredInputSchema = getDeclaredInputSchema(sdkServer, tool.name);
|
|
127
|
+
const declaredInputJsonSchema = declaredInputSchema !== void 0 ? modernInputJsonSchema(tool.name, declaredInputSchema) ?? { type: "object", properties: {} } : void 0;
|
|
116
128
|
return {
|
|
117
129
|
...definition,
|
|
118
130
|
...description !== void 0 && { description },
|
|
@@ -121,9 +133,14 @@ function createModernMcpServerAdapter(agentServer) {
|
|
|
121
133
|
// framework's AdCP validator must see domain-invalid objects so it can
|
|
122
134
|
// return a structured `adcp_error` + context echo; the official strict
|
|
123
135
|
// projection remains discovery-only below.
|
|
124
|
-
inputSchema: schemaForModernMcp(
|
|
136
|
+
inputSchema: schemaForModernMcp(
|
|
137
|
+
inputSchema,
|
|
138
|
+
advertisedInputSchema !== void 0,
|
|
139
|
+
declaredInputSchema ?? inputSchema
|
|
140
|
+
)
|
|
125
141
|
},
|
|
126
142
|
...advertisedInputSchema !== void 0 && { advertisedInputSchema },
|
|
143
|
+
...declaredInputJsonSchema !== void 0 && { declaredInputJsonSchema },
|
|
127
144
|
// Output schemas can dwarf the input discovery surface and are not
|
|
128
145
|
// required for clients to form tool calls. Preserve an adopter's
|
|
129
146
|
// explicitly registered schema, but do not replace it with a bundled
|
|
@@ -214,7 +231,7 @@ function createModernMcpServerAdapter(agentServer) {
|
|
|
214
231
|
}).map((tool) => {
|
|
215
232
|
const registered = registeredTools.get(tool.name);
|
|
216
233
|
const frameworkAdcpTool = tool._meta?.adcp_version === adcpVersion;
|
|
217
|
-
const discoveryInputSchema = frameworkAdcpTool ? officialAdcpInputSchema(tool.name, discoveryVersion, discoveryProfile) : tool.
|
|
234
|
+
const discoveryInputSchema = frameworkAdcpTool ? officialAdcpInputSchema(tool.name, discoveryVersion, discoveryProfile) : tool.declaredInputJsonSchema;
|
|
218
235
|
return {
|
|
219
236
|
name: tool.name,
|
|
220
237
|
...tool.title !== void 0 && { title: tool.title },
|
|
@@ -36,6 +36,13 @@ export interface SellerActionResolutionOptions {
|
|
|
36
36
|
* for serving. Aggregate buy status cannot establish that fact. */
|
|
37
37
|
update_creative_start_policy?: SellerActionDecision;
|
|
38
38
|
};
|
|
39
|
+
/**
|
|
40
|
+
* Whether this seller declares `media_buy.features.creative_start_policy:
|
|
41
|
+
* true`. `update_creative_start_policy` is offered only when this is `true`:
|
|
42
|
+
* without the declaration the framework refuses the opt-in the action
|
|
43
|
+
* advertises. Unknown is a denial.
|
|
44
|
+
*/
|
|
45
|
+
creativeStartPolicy?: boolean;
|
|
39
46
|
now?: number;
|
|
40
47
|
}
|
|
41
48
|
export interface SellerActionResolution {
|
|
@@ -36,6 +36,13 @@ export interface SellerActionResolutionOptions {
|
|
|
36
36
|
* for serving. Aggregate buy status cannot establish that fact. */
|
|
37
37
|
update_creative_start_policy?: SellerActionDecision;
|
|
38
38
|
};
|
|
39
|
+
/**
|
|
40
|
+
* Whether this seller declares `media_buy.features.creative_start_policy:
|
|
41
|
+
* true`. `update_creative_start_policy` is offered only when this is `true`:
|
|
42
|
+
* without the declaration the framework refuses the opt-in the action
|
|
43
|
+
* advertises. Unknown is a denial.
|
|
44
|
+
*/
|
|
45
|
+
creativeStartPolicy?: boolean;
|
|
39
46
|
now?: number;
|
|
40
47
|
}
|
|
41
48
|
export interface SellerActionResolution {
|
|
@@ -25,6 +25,7 @@ var import_version = require('../version.js');
|
|
|
25
25
|
var import_action_contracts = require('../media-buy/action-contracts.js');
|
|
26
26
|
var import_action_assessment = require('../media-buy/action-assessment.js');
|
|
27
27
|
var import_mutations = require('../media-buy/mutations.js');
|
|
28
|
+
var import_creative_start_policy = require('../media-buy/creative-start-policy.js');
|
|
28
29
|
const mediaBuyActionResolver = {
|
|
29
30
|
/**
|
|
30
31
|
* Explicitly accept complete binding terms selected by the seller from all
|
|
@@ -247,7 +248,15 @@ const mediaBuyActionResolver = {
|
|
|
247
248
|
);
|
|
248
249
|
}
|
|
249
250
|
const startup = input.metadata?.update_creative_start_policy;
|
|
250
|
-
if (startup) {
|
|
251
|
+
if (startup && input.creativeStartPolicy !== true) {
|
|
252
|
+
unavailable.push({
|
|
253
|
+
status: "currently_unavailable",
|
|
254
|
+
action: "update_creative_start_policy",
|
|
255
|
+
reason: "not_supported_on_buy",
|
|
256
|
+
certainty: "blocked",
|
|
257
|
+
message: `update_creative_start_policy requires ${import_creative_start_policy.CREATIVE_START_POLICY_FEATURE}, which this seller does not declare.`
|
|
258
|
+
});
|
|
259
|
+
} else if (startup) {
|
|
251
260
|
const scope = Array.isArray(startup.applicable_package_ids) ? startup.applicable_package_ids : void 0;
|
|
252
261
|
const entry = {
|
|
253
262
|
action: "update_creative_start_policy",
|
|
@@ -14,6 +14,7 @@ import {
|
|
|
14
14
|
} from "../media-buy/action-contracts.mjs";
|
|
15
15
|
import { assessActionAvailability } from "../media-buy/action-assessment.mjs";
|
|
16
16
|
import { decomposeUpdateMediaBuy } from "../media-buy/mutations.mjs";
|
|
17
|
+
import { CREATIVE_START_POLICY_FEATURE } from "../media-buy/creative-start-policy.mjs";
|
|
17
18
|
const mediaBuyActionResolver = {
|
|
18
19
|
/**
|
|
19
20
|
* Explicitly accept complete binding terms selected by the seller from all
|
|
@@ -236,7 +237,15 @@ const mediaBuyActionResolver = {
|
|
|
236
237
|
);
|
|
237
238
|
}
|
|
238
239
|
const startup = input.metadata?.update_creative_start_policy;
|
|
239
|
-
if (startup) {
|
|
240
|
+
if (startup && input.creativeStartPolicy !== true) {
|
|
241
|
+
unavailable.push({
|
|
242
|
+
status: "currently_unavailable",
|
|
243
|
+
action: "update_creative_start_policy",
|
|
244
|
+
reason: "not_supported_on_buy",
|
|
245
|
+
certainty: "blocked",
|
|
246
|
+
message: `update_creative_start_policy requires ${CREATIVE_START_POLICY_FEATURE}, which this seller does not declare.`
|
|
247
|
+
});
|
|
248
|
+
} else if (startup) {
|
|
240
249
|
const scope = Array.isArray(startup.applicable_package_ids) ? startup.applicable_package_ids : void 0;
|
|
241
250
|
const entry = {
|
|
242
251
|
action: "update_creative_start_policy",
|
|
@@ -1,47 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Media buy response helpers that eliminate common implementation traps.
|
|
3
|
-
*
|
|
4
|
-
* These helpers encode protocol rules (status→valid_actions mapping,
|
|
5
|
-
* required cancellation metadata, initial revision numbers) so agent
|
|
6
|
-
* builders get the right shape by default.
|
|
7
|
-
*/
|
|
8
|
-
import type { MediaBuyStatus, CanceledBy, Package } from '../types/core.generated.mjs';
|
|
9
|
-
import type { CreateMediaBuySuccess } from '../types/tools.generated.mjs';
|
|
10
|
-
/**
|
|
11
|
-
* Actions a buyer can perform on a media buy.
|
|
12
|
-
* Derived from the generated schema to stay in sync automatically.
|
|
13
|
-
*/
|
|
14
|
-
export type ValidAction = NonNullable<CreateMediaBuySuccess['valid_actions']>[number];
|
|
15
|
-
/**
|
|
16
|
-
* Returns the default set of valid buyer actions for a given media buy status.
|
|
17
|
-
*
|
|
18
|
-
* Terminal statuses (completed, rejected, canceled) return an empty array.
|
|
19
|
-
* Active statuses return the full set of actions; paused restricts to
|
|
20
|
-
* resume, cancel, and budget/date updates.
|
|
21
|
-
*
|
|
22
|
-
* Both pending statuses allow full modification — the protocol permits
|
|
23
|
-
* restructuring a buy (packages, budget, dates) while awaiting creatives
|
|
24
|
-
* or start date.
|
|
25
|
-
*
|
|
26
|
-
* Sellers with restricted capabilities can filter the result:
|
|
27
|
-
* ```typescript
|
|
28
|
-
* const actions = validActionsForStatus('active')
|
|
29
|
-
* .filter(a => a !== 'sync_creatives'); // no creative management
|
|
30
|
-
* ```
|
|
31
|
-
*/
|
|
32
|
-
export declare function validActionsForStatus(status: MediaBuyStatus): ValidAction[];
|
|
33
|
-
/**
|
|
34
|
-
* Input for cancelMediaBuyResponse(). Requires the fields that agent builders
|
|
35
|
-
* commonly forget — canceled_by and revision are mandatory,
|
|
36
|
-
* canceled_at defaults to now.
|
|
37
|
-
*/
|
|
38
|
-
export interface CancelMediaBuyInput {
|
|
39
|
-
media_buy_id: string;
|
|
40
|
-
canceled_by: CanceledBy;
|
|
41
|
-
/** Current revision after the cancellation update. */
|
|
42
|
-
revision: number;
|
|
43
|
-
reason?: string;
|
|
44
|
-
canceled_at?: string;
|
|
45
|
-
affected_packages?: Package[];
|
|
46
|
-
sandbox?: boolean;
|
|
47
|
-
}
|
|
1
|
+
export * from '../media-buy/valid-actions.mjs';
|
|
@@ -1,47 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Media buy response helpers that eliminate common implementation traps.
|
|
3
|
-
*
|
|
4
|
-
* These helpers encode protocol rules (status→valid_actions mapping,
|
|
5
|
-
* required cancellation metadata, initial revision numbers) so agent
|
|
6
|
-
* builders get the right shape by default.
|
|
7
|
-
*/
|
|
8
|
-
import type { MediaBuyStatus, CanceledBy, Package } from '../types/core.generated';
|
|
9
|
-
import type { CreateMediaBuySuccess } from '../types/tools.generated';
|
|
10
|
-
/**
|
|
11
|
-
* Actions a buyer can perform on a media buy.
|
|
12
|
-
* Derived from the generated schema to stay in sync automatically.
|
|
13
|
-
*/
|
|
14
|
-
export type ValidAction = NonNullable<CreateMediaBuySuccess['valid_actions']>[number];
|
|
15
|
-
/**
|
|
16
|
-
* Returns the default set of valid buyer actions for a given media buy status.
|
|
17
|
-
*
|
|
18
|
-
* Terminal statuses (completed, rejected, canceled) return an empty array.
|
|
19
|
-
* Active statuses return the full set of actions; paused restricts to
|
|
20
|
-
* resume, cancel, and budget/date updates.
|
|
21
|
-
*
|
|
22
|
-
* Both pending statuses allow full modification — the protocol permits
|
|
23
|
-
* restructuring a buy (packages, budget, dates) while awaiting creatives
|
|
24
|
-
* or start date.
|
|
25
|
-
*
|
|
26
|
-
* Sellers with restricted capabilities can filter the result:
|
|
27
|
-
* ```typescript
|
|
28
|
-
* const actions = validActionsForStatus('active')
|
|
29
|
-
* .filter(a => a !== 'sync_creatives'); // no creative management
|
|
30
|
-
* ```
|
|
31
|
-
*/
|
|
32
|
-
export declare function validActionsForStatus(status: MediaBuyStatus): ValidAction[];
|
|
33
|
-
/**
|
|
34
|
-
* Input for cancelMediaBuyResponse(). Requires the fields that agent builders
|
|
35
|
-
* commonly forget — canceled_by and revision are mandatory,
|
|
36
|
-
* canceled_at defaults to now.
|
|
37
|
-
*/
|
|
38
|
-
export interface CancelMediaBuyInput {
|
|
39
|
-
media_buy_id: string;
|
|
40
|
-
canceled_by: CanceledBy;
|
|
41
|
-
/** Current revision after the cancellation update. */
|
|
42
|
-
revision: number;
|
|
43
|
-
reason?: string;
|
|
44
|
-
canceled_at?: string;
|
|
45
|
-
affected_packages?: Package[];
|
|
46
|
-
sandbox?: boolean;
|
|
47
|
-
}
|
|
1
|
+
export * from '../media-buy/valid-actions';
|
|
@@ -3,10 +3,6 @@ var __defProp = Object.defineProperty;
|
|
|
3
3
|
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
4
|
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
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
6
|
var __copyProps = (to, from, except, desc) => {
|
|
11
7
|
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
8
|
for (let key of __getOwnPropNames(from))
|
|
@@ -15,28 +11,12 @@ var __copyProps = (to, from, except, desc) => {
|
|
|
15
11
|
}
|
|
16
12
|
return to;
|
|
17
13
|
};
|
|
14
|
+
var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
|
|
18
15
|
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
16
|
var media_buy_helpers_exports = {};
|
|
20
|
-
__export(media_buy_helpers_exports, {
|
|
21
|
-
validActionsForStatus: () => validActionsForStatus
|
|
22
|
-
});
|
|
23
17
|
module.exports = __toCommonJS(media_buy_helpers_exports);
|
|
24
|
-
|
|
25
|
-
switch (status) {
|
|
26
|
-
case "pending_creatives":
|
|
27
|
-
case "pending_start":
|
|
28
|
-
return ["cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"];
|
|
29
|
-
case "active":
|
|
30
|
-
return ["pause", "cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"];
|
|
31
|
-
case "paused":
|
|
32
|
-
return ["resume", "cancel", "update_budget", "update_dates"];
|
|
33
|
-
case "completed":
|
|
34
|
-
case "rejected":
|
|
35
|
-
case "canceled":
|
|
36
|
-
return [];
|
|
37
|
-
}
|
|
38
|
-
}
|
|
18
|
+
__reExport(media_buy_helpers_exports, require('../media-buy/valid-actions.js'), module.exports);
|
|
39
19
|
// Annotate the CommonJS export names for ESM import in node:
|
|
40
20
|
0 && (module.exports = {
|
|
41
|
-
|
|
21
|
+
...require('../media-buy/valid-actions.js')
|
|
42
22
|
});
|
|
@@ -1,18 +1 @@
|
|
|
1
|
-
|
|
2
|
-
switch (status) {
|
|
3
|
-
case "pending_creatives":
|
|
4
|
-
case "pending_start":
|
|
5
|
-
return ["cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"];
|
|
6
|
-
case "active":
|
|
7
|
-
return ["pause", "cancel", "update_budget", "update_dates", "update_packages", "add_packages", "sync_creatives"];
|
|
8
|
-
case "paused":
|
|
9
|
-
return ["resume", "cancel", "update_budget", "update_dates"];
|
|
10
|
-
case "completed":
|
|
11
|
-
case "rejected":
|
|
12
|
-
case "canceled":
|
|
13
|
-
return [];
|
|
14
|
-
}
|
|
15
|
-
}
|
|
16
|
-
export {
|
|
17
|
-
validActionsForStatus
|
|
18
|
-
};
|
|
1
|
+
export * from "../media-buy/valid-actions.mjs";
|
|
@@ -1,89 +1 @@
|
|
|
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;
|
|
1
|
+
export * from '../utils/pick-safe-details.mjs';
|
|
@@ -1,89 +1 @@
|
|
|
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;
|
|
1
|
+
export * from '../utils/pick-safe-details';
|