@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,333 @@
|
|
|
1
|
+
import type { ReportingConsumerMismatchEscalationV1, ReportingLedgerConsumerStatementV1, ReportingLedgerIssueV1, ReportingLedgerObligationV1, ReportingLedgerRevisionSnapshotV1, ReportingLedgerStore, ReportingLedgerSubscriptionPrincipalV1 } from './types';
|
|
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;
|
|
@@ -0,0 +1,310 @@
|
|
|
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 issue_events_exports = {};
|
|
20
|
+
__export(issue_events_exports, {
|
|
21
|
+
REPORTING_ISSUE_EVENT_KINDS_V1: () => REPORTING_ISSUE_EVENT_KINDS_V1,
|
|
22
|
+
ReportingIssueObserverError: () => ReportingIssueObserverError,
|
|
23
|
+
createReportingIssueEventDispatcherV1: () => createReportingIssueEventDispatcherV1,
|
|
24
|
+
planReportingIssueEventsV1: () => planReportingIssueEventsV1,
|
|
25
|
+
renderReportingIssueEventV1: () => renderReportingIssueEventV1,
|
|
26
|
+
reportingConsumerMismatchOccurrenceV1: () => reportingConsumerMismatchOccurrenceV1,
|
|
27
|
+
reportingIssueEscalationV1: () => reportingIssueEscalationV1,
|
|
28
|
+
reportingIssueEventIdV1: () => reportingIssueEventIdV1,
|
|
29
|
+
supportsReportingIssueEventsV1: () => supportsReportingIssueEventsV1
|
|
30
|
+
});
|
|
31
|
+
module.exports = __toCommonJS(issue_events_exports);
|
|
32
|
+
var import_node_crypto = require("node:crypto");
|
|
33
|
+
var import_source = require('../source/index.js');
|
|
34
|
+
var import_health = require('./health.js');
|
|
35
|
+
var import_instant = require('./instant.js');
|
|
36
|
+
const REPORTING_ISSUE_EVENT_KINDS_V1 = Object.freeze([
|
|
37
|
+
"opened",
|
|
38
|
+
"escalated",
|
|
39
|
+
"acknowledged",
|
|
40
|
+
"waived",
|
|
41
|
+
"resolved"
|
|
42
|
+
]);
|
|
43
|
+
function reportingIssueEventIdV1(issueId, consumerId, kind) {
|
|
44
|
+
const digest = (0, import_node_crypto.createHash)("sha256").update((0, import_source.canonicalJsonV1)(["reporting-issue-event-v1", issueId, consumerId, kind])).digest("hex");
|
|
45
|
+
return `rpie_${digest.slice(0, 40)}`;
|
|
46
|
+
}
|
|
47
|
+
function occurrenceKey(value) {
|
|
48
|
+
return (0, import_source.canonicalJsonV1)([value.issueId, value.consumerId]);
|
|
49
|
+
}
|
|
50
|
+
function reportingConsumerMismatchOccurrenceV1(obligation, leaf, revisions) {
|
|
51
|
+
if (!leaf || revisions.length === 0) return void 0;
|
|
52
|
+
const mismatch = (0, import_health.projectReportingConsumerStatusMismatchV1)(obligation, leaf, revisions, "healthy", leaf.recorded_at);
|
|
53
|
+
if (!mismatch) return void 0;
|
|
54
|
+
return {
|
|
55
|
+
issueId: mismatch.issue.issueId,
|
|
56
|
+
accountId: leaf.account_id,
|
|
57
|
+
consumerId: leaf.consumerId,
|
|
58
|
+
reportingObligationId: obligation.reporting_obligation_id,
|
|
59
|
+
reportingStatusId: leaf.reporting_status_id,
|
|
60
|
+
openedAt: mismatch.issue.openedAt
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
function eventRecord(occurrence, kind, occurredAt) {
|
|
64
|
+
return {
|
|
65
|
+
eventId: reportingIssueEventIdV1(occurrence.issueId, occurrence.consumerId, kind),
|
|
66
|
+
kind,
|
|
67
|
+
issueId: occurrence.issueId,
|
|
68
|
+
accountId: occurrence.accountId,
|
|
69
|
+
consumerId: occurrence.consumerId,
|
|
70
|
+
reportingObligationId: occurrence.reportingObligationId,
|
|
71
|
+
reportingStatusId: occurrence.reportingStatusId,
|
|
72
|
+
occurredAt
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
function planReportingIssueEventsV1(input) {
|
|
76
|
+
const conflicting = new Set(input.conflicts.map(occurrenceKey));
|
|
77
|
+
const open = new Set(input.open.map(occurrenceKey));
|
|
78
|
+
const resolved = input.open.filter((value) => !conflicting.has(occurrenceKey(value))).map(
|
|
79
|
+
(value) => eventRecord(
|
|
80
|
+
value,
|
|
81
|
+
"resolved",
|
|
82
|
+
(0, import_instant.compareReportingInstants)(input.at, value.occurredAt) < 0 ? value.occurredAt : input.at
|
|
83
|
+
)
|
|
84
|
+
);
|
|
85
|
+
const opened = input.conflicts.filter((value) => !open.has(occurrenceKey(value))).map((value) => eventRecord(value, "opened", value.openedAt));
|
|
86
|
+
return [...resolved, ...opened];
|
|
87
|
+
}
|
|
88
|
+
function reportingIssueEscalationV1(opened, escalationSeconds, now) {
|
|
89
|
+
const window = escalationSeconds * 1e3;
|
|
90
|
+
if ((0, import_instant.compareReportingInstantToOffset)(now, opened.occurredAt, window) < 0) return void 0;
|
|
91
|
+
return eventRecord(opened, "escalated", (0, import_instant.addReportingInstantOffset)(opened.occurredAt, window));
|
|
92
|
+
}
|
|
93
|
+
function supportsReportingIssueEventsV1(store) {
|
|
94
|
+
if (typeof store !== "object" || store === null) return false;
|
|
95
|
+
const candidate = store;
|
|
96
|
+
return candidate.issueEventsSupported === true && typeof candidate.issueEventsReady === "function" && typeof candidate.sweepIssueEscalations === "function" && typeof candidate.claimIssueEvents === "function" && typeof candidate.completeIssueEvent === "function" && typeof candidate.releaseIssueEvent === "function" && typeof candidate.pruneIssueEvents === "function";
|
|
97
|
+
}
|
|
98
|
+
function renderReportingIssueEventV1(lease, context, escalation) {
|
|
99
|
+
const subscription = context?.obligation.subscription;
|
|
100
|
+
return {
|
|
101
|
+
eventId: lease.eventId,
|
|
102
|
+
kind: lease.kind,
|
|
103
|
+
occurredAt: lease.occurredAt,
|
|
104
|
+
accountId: lease.accountId,
|
|
105
|
+
consumerId: lease.consumerId,
|
|
106
|
+
...subscription ? { principal: { tenantId: subscription.tenantId, principalId: subscription.principalId } } : {},
|
|
107
|
+
issueId: lease.issueId,
|
|
108
|
+
reportingObligationId: lease.reportingObligationId,
|
|
109
|
+
reportingStatusId: lease.reportingStatusId,
|
|
110
|
+
issue: lease.kind === "resolved" || !context ? null : renderIssueOrNull(lease, context, escalation),
|
|
111
|
+
attempt: lease.attempts
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
function renderIssueOrNull(lease, context, escalation) {
|
|
115
|
+
const { obligation, revisions, issues, statement } = context;
|
|
116
|
+
if (!revisions || !issues || !statement) return null;
|
|
117
|
+
try {
|
|
118
|
+
return renderIssue(lease, { obligation, revisions, issues, statement }, escalation);
|
|
119
|
+
} catch {
|
|
120
|
+
return null;
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
function renderIssue(lease, context, escalation) {
|
|
124
|
+
const at = lease.occurredAt;
|
|
125
|
+
const revisions = context.revisions.filter((value) => (0, import_instant.compareReportingInstants)(value.createdAt, at) <= 0);
|
|
126
|
+
const issues = context.issues.filter(
|
|
127
|
+
(value) => (0, import_instant.compareReportingInstants)(value.observedAt, at) <= 0 && (value.resolvedAt === void 0 || (0, import_instant.compareReportingInstants)(value.resolvedAt, at) > 0)
|
|
128
|
+
);
|
|
129
|
+
const core = (0, import_health.projectReportingObligationHealthV1)(context.obligation, revisions, at);
|
|
130
|
+
const sellerHealth = (0, import_health.projectReportingUnreadableRevisionHealthV1)(context.obligation, revisions, issues, core.health);
|
|
131
|
+
const mismatch = (0, import_health.projectReportingConsumerStatusMismatchV1)(
|
|
132
|
+
context.obligation,
|
|
133
|
+
context.statement,
|
|
134
|
+
revisions,
|
|
135
|
+
sellerHealth,
|
|
136
|
+
at,
|
|
137
|
+
escalation
|
|
138
|
+
);
|
|
139
|
+
return mismatch?.issue.issueId === lease.issueId ? structuredClone(mismatch.issue) : null;
|
|
140
|
+
}
|
|
141
|
+
class ReportingIssueObserverError extends Error {
|
|
142
|
+
name = "ReportingIssueObserverError";
|
|
143
|
+
component;
|
|
144
|
+
/** The event being delivered, for `issue_observer` and `issue_events:snapshot`. */
|
|
145
|
+
eventId;
|
|
146
|
+
constructor(component, cause, eventId) {
|
|
147
|
+
super(
|
|
148
|
+
component === "issue_observer" ? `Reporting issue observer failed for ${eventId}; the event is retried` : component === "issue_events" ? "Reporting issue events could not be swept or claimed" : `Reporting issue event ${eventId} could not be rendered yet; it is retried`,
|
|
149
|
+
{ cause }
|
|
150
|
+
);
|
|
151
|
+
this.component = component;
|
|
152
|
+
this.eventId = eventId;
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
function createReportingIssueEventDispatcherV1(options) {
|
|
156
|
+
const { store, observer, escalation } = options;
|
|
157
|
+
if (!supportsReportingIssueEventsV1(store)) {
|
|
158
|
+
throw new TypeError(
|
|
159
|
+
"The ledger store does not record issue events. Use memoryStorage(), or postgresStorage({ pool }) from @adcp/reporting-storage with migration 0012 applied."
|
|
160
|
+
);
|
|
161
|
+
}
|
|
162
|
+
if (typeof observer !== "function") throw new TypeError("The issue observer must be a function");
|
|
163
|
+
const timeout = positive(options.observerTimeoutMilliseconds ?? 1e4, "observerTimeoutMilliseconds");
|
|
164
|
+
const batchSize = positive(options.batchSize ?? 10, "batchSize");
|
|
165
|
+
const maxBatches = positive(options.maxBatches ?? 10, "maxBatches");
|
|
166
|
+
const retryBase = positive(options.retryBaseMilliseconds ?? 3e4, "retryBaseMilliseconds");
|
|
167
|
+
const retryCap = positive(options.retryCapMilliseconds ?? 36e5, "retryCapMilliseconds");
|
|
168
|
+
if (retryCap < retryBase) throw new RangeError("retryCapMilliseconds must be at least retryBaseMilliseconds");
|
|
169
|
+
const retention = options.retentionMilliseconds === null ? null : nonNegative(options.retentionMilliseconds ?? 7 * 864e5, "retentionMilliseconds");
|
|
170
|
+
const leaseMilliseconds = batchSize * timeout + 3e4;
|
|
171
|
+
const backoff = (attempts) => Math.min(retryCap, retryBase * 2 ** Math.min(Math.max(attempts - 1, 0), 20));
|
|
172
|
+
return {
|
|
173
|
+
leaseMilliseconds,
|
|
174
|
+
async runOnce(input = {}) {
|
|
175
|
+
const result = { escalationsRecorded: 0, delivered: 0, failed: 0, errors: [] };
|
|
176
|
+
const scope = input.accountId !== void 0 ? { accountId: input.accountId } : {};
|
|
177
|
+
if (escalation) {
|
|
178
|
+
try {
|
|
179
|
+
result.escalationsRecorded = await store.sweepIssueEscalations({
|
|
180
|
+
escalationSeconds: escalation.escalationSeconds,
|
|
181
|
+
...scope
|
|
182
|
+
});
|
|
183
|
+
} catch (error) {
|
|
184
|
+
result.errors.push(new ReportingIssueObserverError("issue_events", error));
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
for (let batch = 0; batch < maxBatches && !input.signal?.aborted; batch += 1) {
|
|
188
|
+
let leases;
|
|
189
|
+
try {
|
|
190
|
+
leases = await store.claimIssueEvents({ leaseMilliseconds, limit: batchSize, ...scope });
|
|
191
|
+
} catch (error) {
|
|
192
|
+
result.errors.push(new ReportingIssueObserverError("issue_events", error));
|
|
193
|
+
break;
|
|
194
|
+
}
|
|
195
|
+
if (leases.length === 0) break;
|
|
196
|
+
const obligations = /* @__PURE__ */ new Map();
|
|
197
|
+
const evidence = /* @__PURE__ */ new Map();
|
|
198
|
+
const obligationOf = (lease) => cached(obligations, lease.reportingObligationId, () => readObligation(store, lease));
|
|
199
|
+
const evidenceOf = (lease) => cached(evidence, lease.reportingObligationId, async () => {
|
|
200
|
+
const obligation = await obligationOf(lease);
|
|
201
|
+
return obligation ? readEvidence(store, lease, obligation) : void 0;
|
|
202
|
+
});
|
|
203
|
+
for (const [index, lease] of leases.entries()) {
|
|
204
|
+
if (input.signal?.aborted) {
|
|
205
|
+
for (const pending of leases.slice(index)) {
|
|
206
|
+
await settle(() => store.releaseIssueEvent(pending, { retryAfterMilliseconds: 0 }));
|
|
207
|
+
}
|
|
208
|
+
break;
|
|
209
|
+
}
|
|
210
|
+
let context;
|
|
211
|
+
try {
|
|
212
|
+
if (lease.kind === "resolved") {
|
|
213
|
+
const obligation = await obligationOf(lease);
|
|
214
|
+
context = obligation ? { obligation } : void 0;
|
|
215
|
+
} else {
|
|
216
|
+
const read = await evidenceOf(lease);
|
|
217
|
+
context = read && lease.statement ? { ...read, statement: lease.statement } : read;
|
|
218
|
+
}
|
|
219
|
+
} catch (error) {
|
|
220
|
+
result.failed += 1;
|
|
221
|
+
result.errors.push(new ReportingIssueObserverError("issue_events:snapshot", error, lease.eventId));
|
|
222
|
+
await settle(() => store.releaseIssueEvent(lease, { retryAfterMilliseconds: backoff(lease.attempts) }));
|
|
223
|
+
continue;
|
|
224
|
+
}
|
|
225
|
+
const event = renderReportingIssueEventV1(lease, context, escalation);
|
|
226
|
+
try {
|
|
227
|
+
await withTimeout(
|
|
228
|
+
Promise.resolve().then(() => observer(Object.freeze(event))),
|
|
229
|
+
timeout
|
|
230
|
+
);
|
|
231
|
+
} catch (error) {
|
|
232
|
+
result.failed += 1;
|
|
233
|
+
result.errors.push(new ReportingIssueObserverError("issue_observer", error, lease.eventId));
|
|
234
|
+
await settle(() => store.releaseIssueEvent(lease, { retryAfterMilliseconds: backoff(lease.attempts) }));
|
|
235
|
+
continue;
|
|
236
|
+
}
|
|
237
|
+
try {
|
|
238
|
+
if (await store.completeIssueEvent(lease)) result.delivered += 1;
|
|
239
|
+
} catch (error) {
|
|
240
|
+
result.errors.push(new ReportingIssueObserverError("issue_events", error, lease.eventId));
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
if (retention !== null) {
|
|
245
|
+
try {
|
|
246
|
+
await store.pruneIssueEvents({ olderThanMilliseconds: retention });
|
|
247
|
+
} catch (error) {
|
|
248
|
+
result.errors.push(new ReportingIssueObserverError("issue_events", error));
|
|
249
|
+
}
|
|
250
|
+
}
|
|
251
|
+
return result;
|
|
252
|
+
}
|
|
253
|
+
};
|
|
254
|
+
}
|
|
255
|
+
function cached(cache, key, read) {
|
|
256
|
+
let value = cache.get(key);
|
|
257
|
+
if (!value) {
|
|
258
|
+
value = read();
|
|
259
|
+
cache.set(key, value);
|
|
260
|
+
}
|
|
261
|
+
return value;
|
|
262
|
+
}
|
|
263
|
+
async function readObligation(store, lease) {
|
|
264
|
+
const obligation = await store.getObligation(lease.reportingObligationId, lease.accountId);
|
|
265
|
+
return obligation && obligation.account.account_id === lease.accountId ? obligation : void 0;
|
|
266
|
+
}
|
|
267
|
+
async function readEvidence(store, lease, obligation) {
|
|
268
|
+
const revisions = typeof store.listRevisionMetadata === "function" ? await store.listRevisionMetadata(lease.reportingObligationId, lease.accountId) : (await store.listRevisions(lease.reportingObligationId)).map(({ rows: _rows, ...metadata }) => metadata);
|
|
269
|
+
const issues = await store.listIssues(lease.reportingObligationId);
|
|
270
|
+
return { obligation, revisions, issues };
|
|
271
|
+
}
|
|
272
|
+
async function settle(release) {
|
|
273
|
+
try {
|
|
274
|
+
await release();
|
|
275
|
+
} catch {
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
async function withTimeout(value, timeoutMilliseconds) {
|
|
279
|
+
let timer;
|
|
280
|
+
try {
|
|
281
|
+
await Promise.race([
|
|
282
|
+
value,
|
|
283
|
+
new Promise((_, reject) => {
|
|
284
|
+
timer = setTimeout(() => reject(new Error("Reporting issue observer timed out")), timeoutMilliseconds);
|
|
285
|
+
})
|
|
286
|
+
]);
|
|
287
|
+
} finally {
|
|
288
|
+
if (timer) clearTimeout(timer);
|
|
289
|
+
}
|
|
290
|
+
}
|
|
291
|
+
function positive(value, name) {
|
|
292
|
+
if (!Number.isSafeInteger(value) || value < 1) throw new RangeError(`${name} must be a positive integer`);
|
|
293
|
+
return value;
|
|
294
|
+
}
|
|
295
|
+
function nonNegative(value, name) {
|
|
296
|
+
if (!Number.isSafeInteger(value) || value < 0) throw new RangeError(`${name} must be a non-negative integer`);
|
|
297
|
+
return value;
|
|
298
|
+
}
|
|
299
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
300
|
+
0 && (module.exports = {
|
|
301
|
+
REPORTING_ISSUE_EVENT_KINDS_V1,
|
|
302
|
+
ReportingIssueObserverError,
|
|
303
|
+
createReportingIssueEventDispatcherV1,
|
|
304
|
+
planReportingIssueEventsV1,
|
|
305
|
+
renderReportingIssueEventV1,
|
|
306
|
+
reportingConsumerMismatchOccurrenceV1,
|
|
307
|
+
reportingIssueEscalationV1,
|
|
308
|
+
reportingIssueEventIdV1,
|
|
309
|
+
supportsReportingIssueEventsV1
|
|
310
|
+
});
|