@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
|
@@ -44,6 +44,14 @@ function compareReportingInstantToOffset(value, base, offsetMilliseconds) {
|
|
|
44
44
|
const offset = durationUnits(offsetMilliseconds, delta.scale);
|
|
45
45
|
return delta.units < offset ? -1 : delta.units > offset ? 1 : 0;
|
|
46
46
|
}
|
|
47
|
+
function addReportingInstantOffset(base, offsetMilliseconds) {
|
|
48
|
+
const parsed = parseReportingInstant(base);
|
|
49
|
+
const scale = Math.max(3, parsed.fraction.length);
|
|
50
|
+
const units = scaledValue(parsed, scale) + durationUnits(offsetMilliseconds, scale);
|
|
51
|
+
const unit = 10n ** BigInt(scale);
|
|
52
|
+
const wholeSecond = new Date(Number(units / unit) * 1e3).toISOString().replace(".000Z", "");
|
|
53
|
+
return `${wholeSecond}.${(units % unit).toString().padStart(scale, "0")}Z`;
|
|
54
|
+
}
|
|
47
55
|
function reportingInstantHasDuration(start, end, durationMilliseconds) {
|
|
48
56
|
const delta = difference(end, start);
|
|
49
57
|
return delta.units === durationUnits(durationMilliseconds, delta.scale);
|
|
@@ -61,6 +69,7 @@ function reportingDurationCeilOrdinal(anchor, effectiveFrom, durationMillisecond
|
|
|
61
69
|
return (delta.units + duration - 1n) / duration;
|
|
62
70
|
}
|
|
63
71
|
export {
|
|
72
|
+
addReportingInstantOffset,
|
|
64
73
|
canonicalReportingInstant,
|
|
65
74
|
compareReportingInstantToOffset,
|
|
66
75
|
compareReportingInstants,
|
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
import type { ReportingConsumerMismatchEscalationV1, ReportingLedgerConsumerStatementV1, ReportingLedgerIssueV1, ReportingLedgerObligationV1, ReportingLedgerRevisionSnapshotV1, ReportingLedgerStore, ReportingLedgerSubscriptionPrincipalV1 } from './types.mjs';
|
|
2
|
+
/**
|
|
3
|
+
* One lifecycle transition of one reporting-issue occurrence.
|
|
4
|
+
*
|
|
5
|
+
* `opened`, `acknowledged`, `waived` and `resolved` are the spec's `issue_state` values; `escalated` is
|
|
6
|
+
* the `consumer_mismatch_escalation_seconds` boundary, where the issue turns `action_required` with a
|
|
7
|
+
* `contact_*` action. TypeScript stores never emit `acknowledged` or `waived` yet: the TypeScript ledger
|
|
8
|
+
* has no operator issue-state API (the Python SDK's `set_issue_state`). They are listed for parity.
|
|
9
|
+
*
|
|
10
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
11
|
+
*/
|
|
12
|
+
export type ReportingIssueEventKindV1 = 'opened' | 'escalated' | 'acknowledged' | 'waived' | 'resolved';
|
|
13
|
+
/**
|
|
14
|
+
* Every kind, in lifecycle order.
|
|
15
|
+
*
|
|
16
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
17
|
+
*/
|
|
18
|
+
export declare const REPORTING_ISSUE_EVENT_KINDS_V1: readonly ReportingIssueEventKindV1[];
|
|
19
|
+
/**
|
|
20
|
+
* The stable id of one transition of one issue occurrence:
|
|
21
|
+
* `"rpie_" + sha256(canonical_json_utf8_v1(["reporting-issue-event-v1", issueId, consumerId, kind])).hex()[:40]`.
|
|
22
|
+
* Every redelivery of one transition carries the same id.
|
|
23
|
+
*
|
|
24
|
+
* The Python SDK derives its id from `["reporting-issue-event-v1", issue_id, kind]`. Its `issue_id` is
|
|
25
|
+
* already consumer-scoped (the occurrence key includes the consumer), so the pair is unique there. The
|
|
26
|
+
* TypeScript `issueId` is the one `get_reporting_status` publishes, `hash(obligation, reporting_status_id)`,
|
|
27
|
+
* and two consumers may reuse one `reporting_status_id`, so the consumer is added here. The two SDKs
|
|
28
|
+
* never produce equal ids for one disagreement anyway, since their `issueId`s differ.
|
|
29
|
+
*
|
|
30
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
31
|
+
*/
|
|
32
|
+
export declare function reportingIssueEventIdV1(issueId: string, consumerId: string, kind: ReportingIssueEventKindV1): string;
|
|
33
|
+
/**
|
|
34
|
+
* One `CONSUMER_STATUS_MISMATCH` occurrence: a consumer's current statement that conflicts with the
|
|
35
|
+
* seller's record of one obligation.
|
|
36
|
+
*
|
|
37
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
38
|
+
*/
|
|
39
|
+
export interface ReportingConsumerMismatchOccurrenceV1 {
|
|
40
|
+
/** The issue's `issue_id`, as `get_reporting_status` publishes it. */
|
|
41
|
+
issueId: string;
|
|
42
|
+
accountId: string;
|
|
43
|
+
/** The buyer whose statement caused it. */
|
|
44
|
+
consumerId: string;
|
|
45
|
+
reportingObligationId: string;
|
|
46
|
+
/** The causing statement. */
|
|
47
|
+
reportingStatusId: string;
|
|
48
|
+
/** The issue's `opened_at`: fixed from immutable ledger facts, never from the read time. */
|
|
49
|
+
openedAt: string;
|
|
50
|
+
}
|
|
51
|
+
/**
|
|
52
|
+
* Whether `leaf` conflicts with the seller's record of `obligation`, and the occurrence if it does.
|
|
53
|
+
*
|
|
54
|
+
* The same projection `get_reporting_status` runs, with one difference: the seller-health suppression is
|
|
55
|
+
* removed. While the seller's own projection is degraded the read publishes the seller's issue instead,
|
|
56
|
+
* but the disagreement still stands, so the occurrence stays open (the Python SDK's
|
|
57
|
+
* `consumer_statement_conflicts` makes the same split). An occurrence needs at least one revision: the
|
|
58
|
+
* projection anchors `openedAt` no earlier than the first one, so before it exists the instant is not
|
|
59
|
+
* yet fixed.
|
|
60
|
+
*
|
|
61
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
62
|
+
*/
|
|
63
|
+
export declare function reportingConsumerMismatchOccurrenceV1(obligation: ReportingLedgerObligationV1, leaf: ReportingLedgerConsumerStatementV1 | undefined, revisions: readonly Pick<ReportingLedgerRevisionSnapshotV1, 'reporting_revision_id' | 'revisionNumber' | 'supersedes_reporting_revision_id' | 'createdAt'>[]): ReportingConsumerMismatchOccurrenceV1 | undefined;
|
|
64
|
+
/**
|
|
65
|
+
* One event as a store records it: the transition, and the occurrence it belongs to.
|
|
66
|
+
*
|
|
67
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
68
|
+
*/
|
|
69
|
+
export interface ReportingIssueEventRecordV1 {
|
|
70
|
+
eventId: string;
|
|
71
|
+
kind: ReportingIssueEventKindV1;
|
|
72
|
+
issueId: string;
|
|
73
|
+
accountId: string;
|
|
74
|
+
consumerId: string;
|
|
75
|
+
reportingObligationId: string;
|
|
76
|
+
reportingStatusId: string;
|
|
77
|
+
/** When the transition took effect: `openedAt`, the escalation boundary, or when it resolved. */
|
|
78
|
+
occurredAt: string;
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* The events one write records over one settled scope: `opened` for each occurrence that conflicts now
|
|
82
|
+
* and is not open, `resolved` for each open occurrence that no longer conflicts.
|
|
83
|
+
*
|
|
84
|
+
* `open` is the `opened` record of every occurrence in the scope that is not yet resolved; `conflicts`
|
|
85
|
+
* is every occurrence that conflicts after the write, over the same scope. `at` is the write's instant:
|
|
86
|
+
* a cleared occurrence resolves then, never before it opened. Resolutions come first, so a statement
|
|
87
|
+
* that supersedes a conflicting one records the old occurrence's `resolved` before the new one's
|
|
88
|
+
* `opened`. Occurrences are matched on `(issueId, consumerId)`. A store inserts each record with "on conflict
|
|
89
|
+
* do nothing" on `(issueId, consumerId, kind)`.
|
|
90
|
+
*
|
|
91
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
92
|
+
*/
|
|
93
|
+
export declare function planReportingIssueEventsV1(input: {
|
|
94
|
+
open: readonly ReportingIssueEventRecordV1[];
|
|
95
|
+
conflicts: readonly ReportingConsumerMismatchOccurrenceV1[];
|
|
96
|
+
at: string;
|
|
97
|
+
}): ReportingIssueEventRecordV1[];
|
|
98
|
+
/**
|
|
99
|
+
* The `escalated` record for an open occurrence once `now` has passed its `openedAt` plus the window,
|
|
100
|
+
* dated at that exact boundary; `undefined` before it.
|
|
101
|
+
*
|
|
102
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
103
|
+
*/
|
|
104
|
+
export declare function reportingIssueEscalationV1(opened: ReportingIssueEventRecordV1, escalationSeconds: number, now: string): ReportingIssueEventRecordV1 | undefined;
|
|
105
|
+
/**
|
|
106
|
+
* One claimed event, as a store hands it to the dispatcher.
|
|
107
|
+
*
|
|
108
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
109
|
+
*/
|
|
110
|
+
export interface ReportingIssueEventLeaseV1 extends ReportingIssueEventRecordV1 {
|
|
111
|
+
/** When the store recorded the event. */
|
|
112
|
+
recordedAt: string;
|
|
113
|
+
/** Delivery attempts, this one included. */
|
|
114
|
+
attempts: number;
|
|
115
|
+
leaseToken: string;
|
|
116
|
+
leaseExpiresAt: string;
|
|
117
|
+
/** The causing consumer statement, while the store still retains it. Used to render the issue. */
|
|
118
|
+
statement?: ReportingLedgerConsumerStatementV1;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* A ledger store that records issue events beside its writes and serves them under a lease.
|
|
122
|
+
*
|
|
123
|
+
* `issueEventsSupported` is the opt-in: a store that merely has methods of these names is not taken to
|
|
124
|
+
* record events. The in-memory store behind `memoryStorage()` implements it, and so does
|
|
125
|
+
* `PostgresReportingLedgerStore` from `@adcp/reporting-storage` once migration `0012
|
|
126
|
+
* reporting_issue_events` is applied.
|
|
127
|
+
*
|
|
128
|
+
* A store that deletes an obligation (period retirement) must resolve the obligation's open occurrences in the
|
|
129
|
+
* same transaction: nothing can resolve or escalate them afterwards, so they would otherwise stay open forever
|
|
130
|
+
* and never become prunable. Their pending events stay deliverable.
|
|
131
|
+
*
|
|
132
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
133
|
+
*/
|
|
134
|
+
export interface ReportingIssueEventStoreV1 {
|
|
135
|
+
readonly issueEventsSupported: true;
|
|
136
|
+
/** Whether the store can record events now (its schema is installed). */
|
|
137
|
+
issueEventsReady(): Promise<boolean>;
|
|
138
|
+
/**
|
|
139
|
+
* Record `escalated` for open occurrences past `openedAt + escalationSeconds`, settling each
|
|
140
|
+
* occurrence's obligation first so a cleared condition resolves instead. Exactly once per occurrence
|
|
141
|
+
* across replicas. Returns the `escalated` events recorded.
|
|
142
|
+
*/
|
|
143
|
+
sweepIssueEscalations(input: {
|
|
144
|
+
escalationSeconds: number;
|
|
145
|
+
accountId?: string;
|
|
146
|
+
limit?: number;
|
|
147
|
+
}): Promise<number>;
|
|
148
|
+
/**
|
|
149
|
+
* Lease up to `limit` due events, at most one per occurrence (`(issueId, consumerId)`), each occurrence's in recording order: an
|
|
150
|
+
* event is claimable only once every earlier event of its occurrence was delivered. An unsettled lease
|
|
151
|
+
* expires after `leaseMilliseconds` and is claimable again.
|
|
152
|
+
*/
|
|
153
|
+
claimIssueEvents(input: {
|
|
154
|
+
leaseMilliseconds: number;
|
|
155
|
+
limit: number;
|
|
156
|
+
accountId?: string;
|
|
157
|
+
}): Promise<ReportingIssueEventLeaseV1[]>;
|
|
158
|
+
/** Mark a leased event delivered; `false` when the lease was lost. */
|
|
159
|
+
completeIssueEvent(lease: ReportingIssueEventLeaseV1): Promise<boolean>;
|
|
160
|
+
/** Give back a failed delivery, due again `retryAfterMilliseconds` from now; `false` when the lease was lost. */
|
|
161
|
+
releaseIssueEvent(lease: ReportingIssueEventLeaseV1, input: {
|
|
162
|
+
retryAfterMilliseconds: number;
|
|
163
|
+
}): Promise<boolean>;
|
|
164
|
+
/**
|
|
165
|
+
* Delete up to `limit` whole closed occurrences and return the events deleted. Closed means resolved, every
|
|
166
|
+
* event delivered more than `olderThanMilliseconds` ago, and unable to be derived again: the causing
|
|
167
|
+
* statement is no longer the consumer's current leaf, or the obligation is gone.
|
|
168
|
+
*
|
|
169
|
+
* Never an open occurrence, however old its delivered events: the `opened` record is what a later write
|
|
170
|
+
* resolves and what the escalation sweep escalates, so deleting it would lose both. Never a resolved one
|
|
171
|
+
* whose statement is still current either: it is the anchor that stops a later write recording its delivered
|
|
172
|
+
* events again under the same `eventId`.
|
|
173
|
+
*/
|
|
174
|
+
pruneIssueEvents(input: {
|
|
175
|
+
olderThanMilliseconds: number;
|
|
176
|
+
limit?: number;
|
|
177
|
+
}): Promise<number>;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Whether `store` opted in to recording issue events.
|
|
181
|
+
*
|
|
182
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
183
|
+
*/
|
|
184
|
+
export declare function supportsReportingIssueEventsV1(store: unknown): store is ReportingIssueEventStoreV1;
|
|
185
|
+
/**
|
|
186
|
+
* What the issue observer receives: one lifecycle transition of one reporting-issue occurrence.
|
|
187
|
+
*
|
|
188
|
+
* Delivered **at least once**: deduplicate on `eventId`, which is the same on every delivery of this
|
|
189
|
+
* transition.
|
|
190
|
+
*
|
|
191
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
192
|
+
*/
|
|
193
|
+
export interface ReportingIssueEventV1 {
|
|
194
|
+
/** Stable across redeliveries of this transition: deduplicate on it. */
|
|
195
|
+
eventId: string;
|
|
196
|
+
/** TypeScript stores emit `opened`, `escalated` and `resolved`; never `acknowledged` or `waived` yet. */
|
|
197
|
+
kind: ReportingIssueEventKindV1;
|
|
198
|
+
/** When the transition took effect: the issue's `openedAt`, the escalation boundary, or when it resolved. */
|
|
199
|
+
occurredAt: string;
|
|
200
|
+
accountId: string;
|
|
201
|
+
/** The buyer whose statement caused the caller-scoped issue. */
|
|
202
|
+
consumerId: string;
|
|
203
|
+
/**
|
|
204
|
+
* The owning principal, when the obligation belongs to a reporting subscription. Present on every kind,
|
|
205
|
+
* `resolved` included, while the obligation is retained; omitted once retention has removed it.
|
|
206
|
+
*/
|
|
207
|
+
principal?: ReportingLedgerSubscriptionPrincipalV1;
|
|
208
|
+
issueId: string;
|
|
209
|
+
reportingObligationId: string;
|
|
210
|
+
/** The consumer statement that caused the issue. */
|
|
211
|
+
reportingStatusId: string;
|
|
212
|
+
/**
|
|
213
|
+
* The issue as `get_reporting_status` rendered it for `consumerId` at `occurredAt`:
|
|
214
|
+
* `responsibleParty`, `recommendedAction`, `severity`, `openedAt`. `null` for `resolved`, while the
|
|
215
|
+
* seller's own projection suppressed it at that instant, and when the evidence is no longer retained.
|
|
216
|
+
* Rendering is best effort and leaves Managed Delivery out.
|
|
217
|
+
*/
|
|
218
|
+
issue: ReportingLedgerIssueV1 | null;
|
|
219
|
+
/** This delivery's attempt number, from 1. */
|
|
220
|
+
attempt: number;
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* The seller's callback. Its return value is ignored; a returned promise is awaited up to the
|
|
224
|
+
* dispatcher's timeout.
|
|
225
|
+
*
|
|
226
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
227
|
+
*/
|
|
228
|
+
export type ReportingIssueObserverV1 = (event: Readonly<ReportingIssueEventV1>) => void | Promise<void>;
|
|
229
|
+
/**
|
|
230
|
+
* Evidence the dispatcher reads for one event. `obligation` alone gives the event its `principal`, which
|
|
231
|
+
* is all a `resolved` event needs; rendering the issue also needs `revisions`, `issues` and the causing
|
|
232
|
+
* `statement`, and renders `null` without them.
|
|
233
|
+
*
|
|
234
|
+
* @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
235
|
+
*/
|
|
236
|
+
export interface ReportingIssueEventRenderContextV1 {
|
|
237
|
+
obligation: ReportingLedgerObligationV1;
|
|
238
|
+
revisions?: readonly ReportingLedgerRevisionSnapshotV1[];
|
|
239
|
+
/** The obligation's persisted issues; an open `REVISION_UNREADABLE` degrades the seller's projection. */
|
|
240
|
+
issues?: readonly ReportingLedgerIssueV1[];
|
|
241
|
+
statement?: ReportingLedgerConsumerStatementV1;
|
|
242
|
+
}
|
|
243
|
+
/**
|
|
244
|
+
* Build the observer's event, rendering the issue as `get_reporting_status` showed it to `consumerId` at
|
|
245
|
+
* `occurredAt`: revisions created by then, persisted issues open at then, the causing statement, and
|
|
246
|
+
* the seller's escalation window. Anything it cannot reconstruct yields `issue: null` rather than a
|
|
247
|
+
* wrong issue.
|
|
248
|
+
*
|
|
249
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
250
|
+
*/
|
|
251
|
+
export declare function renderReportingIssueEventV1(lease: ReportingIssueEventLeaseV1, context: ReportingIssueEventRenderContextV1 | undefined, escalation?: ReportingConsumerMismatchEscalationV1): ReportingIssueEventV1;
|
|
252
|
+
/**
|
|
253
|
+
* A failure the issue dispatcher reports instead of throwing: the observer raised or timed out
|
|
254
|
+
* (`issue_observer`), claiming or sweeping failed (`issue_events`), or an event's evidence could not be
|
|
255
|
+
* read for rendering (`issue_events:snapshot`). The scheduler hands each to its `onError`; `runCycle`
|
|
256
|
+
* returns them in `issueEvents.errors`. An event behind an `issue_observer` or `issue_events:snapshot`
|
|
257
|
+
* failure is retried after a backoff.
|
|
258
|
+
*
|
|
259
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
260
|
+
*/
|
|
261
|
+
export declare class ReportingIssueObserverError extends Error {
|
|
262
|
+
readonly name = "ReportingIssueObserverError";
|
|
263
|
+
readonly component: 'issue_observer' | 'issue_events' | 'issue_events:snapshot';
|
|
264
|
+
/** The event being delivered, for `issue_observer` and `issue_events:snapshot`. */
|
|
265
|
+
readonly eventId: string | undefined;
|
|
266
|
+
constructor(component: ReportingIssueObserverError['component'], cause: unknown, eventId?: string);
|
|
267
|
+
}
|
|
268
|
+
/**
|
|
269
|
+
* What one dispatcher turn did.
|
|
270
|
+
*
|
|
271
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
272
|
+
*/
|
|
273
|
+
export interface ReportingIssueEventDeliveryV1 {
|
|
274
|
+
/** `escalated` events this turn's sweep recorded. */
|
|
275
|
+
escalationsRecorded: number;
|
|
276
|
+
/** Events the observer accepted. */
|
|
277
|
+
delivered: number;
|
|
278
|
+
/** Events the observer raised or timed out on, or that could not be rendered; each is retried later. */
|
|
279
|
+
failed: number;
|
|
280
|
+
errors: ReportingIssueObserverError[];
|
|
281
|
+
}
|
|
282
|
+
/**
|
|
283
|
+
* Options for {@link createReportingIssueEventDispatcherV1}.
|
|
284
|
+
*
|
|
285
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
286
|
+
*/
|
|
287
|
+
export interface ReportingIssueEventDispatcherOptionsV1 {
|
|
288
|
+
store: ReportingLedgerStore & ReportingIssueEventStoreV1;
|
|
289
|
+
observer: ReportingIssueObserverV1;
|
|
290
|
+
/** The seller's advertised escalation commitment. Without it no `escalated` event is recorded. */
|
|
291
|
+
escalation?: ReportingConsumerMismatchEscalationV1;
|
|
292
|
+
/** Per-call timeout for an async observer. Default 10 s, the subscriber timeout. */
|
|
293
|
+
observerTimeoutMilliseconds?: number;
|
|
294
|
+
/** Events claimed per batch. Default 10. */
|
|
295
|
+
batchSize?: number;
|
|
296
|
+
/** Batches per turn. Default 10. */
|
|
297
|
+
maxBatches?: number;
|
|
298
|
+
/** First retry delay; doubles per attempt. Default 30 s. */
|
|
299
|
+
retryBaseMilliseconds?: number;
|
|
300
|
+
/** Retry delay ceiling. Default 1 h. Retries never stop. */
|
|
301
|
+
retryCapMilliseconds?: number;
|
|
302
|
+
/**
|
|
303
|
+
* A closed occurrence (resolved, and its statement superseded or its obligation gone) whose events were all
|
|
304
|
+
* delivered longer ago than this is pruned. Open occurrences are never pruned. Default 7 days; `null` keeps
|
|
305
|
+
* everything.
|
|
306
|
+
*/
|
|
307
|
+
retentionMilliseconds?: number | null;
|
|
308
|
+
}
|
|
309
|
+
/**
|
|
310
|
+
* Delivers a store's recorded issue events to an observer, at least once.
|
|
311
|
+
*
|
|
312
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
313
|
+
*/
|
|
314
|
+
export interface ReportingIssueEventDispatcherV1 {
|
|
315
|
+
/** Long enough for a whole batch to time out, so a lease never lapses mid-batch. */
|
|
316
|
+
readonly leaseMilliseconds: number;
|
|
317
|
+
/**
|
|
318
|
+
* One turn: sweep escalations, then claim due events in leased batches (at most one per occurrence at a
|
|
319
|
+
* time), render each, call the observer, and mark it delivered or release it for a retry. Never throws
|
|
320
|
+
* for an observer or store failure: those are returned in `errors`.
|
|
321
|
+
*/
|
|
322
|
+
runOnce(input?: {
|
|
323
|
+
accountId?: string;
|
|
324
|
+
signal?: AbortSignal;
|
|
325
|
+
}): Promise<ReportingIssueEventDeliveryV1>;
|
|
326
|
+
}
|
|
327
|
+
/**
|
|
328
|
+
* Build the dispatcher `createReliableReportingService` runs on every `runCycle` when given
|
|
329
|
+
* `issueObserver`. Run it yourself only when you compose the ledger without the service.
|
|
330
|
+
*
|
|
331
|
+
* @experimental Reliable Reporting issue observer: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
|
|
332
|
+
*/
|
|
333
|
+
export declare function createReportingIssueEventDispatcherV1(options: ReportingIssueEventDispatcherOptionsV1): ReportingIssueEventDispatcherV1;
|