@adcp/sdk 16.0.0-beta.3 → 16.0.0-beta.5

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.
Files changed (185) hide show
  1. package/dist/lib/auth/oauth/diagnose.js +3 -11
  2. package/dist/lib/auth/oauth/diagnose.mjs +4 -12
  3. package/dist/lib/auth/oauth/diagnostics.d.mts +2 -1
  4. package/dist/lib/auth/oauth/diagnostics.d.ts +2 -1
  5. package/dist/lib/auth/oauth/diagnostics.js +8 -10
  6. package/dist/lib/auth/oauth/diagnostics.mjs +7 -10
  7. package/dist/lib/index.d.mts +1 -1
  8. package/dist/lib/index.d.ts +1 -1
  9. package/dist/lib/index.js +2 -0
  10. package/dist/lib/index.mjs +7 -1
  11. package/dist/lib/reporting/consumer-runtime.js +2 -1
  12. package/dist/lib/reporting/consumer-runtime.mjs +2 -1
  13. package/dist/lib/reporting/ledger/handler.js +50 -11
  14. package/dist/lib/reporting/ledger/handler.mjs +50 -12
  15. package/dist/lib/reporting/ledger/index.d.mts +17 -14
  16. package/dist/lib/reporting/ledger/index.d.ts +17 -14
  17. package/dist/lib/reporting/ledger/index.js +32 -20
  18. package/dist/lib/reporting/ledger/index.mjs +21 -10
  19. package/dist/lib/reporting/ledger/offering-validation.d.mts +9 -0
  20. package/dist/lib/reporting/ledger/offering-validation.d.ts +9 -0
  21. package/dist/lib/reporting/{gcs/bucket-policy.js → ledger/offering-validation.js} +9 -8
  22. package/dist/lib/reporting/ledger/offering-validation.mjs +8 -0
  23. package/dist/lib/reporting/ledger/receipts.d.mts +48 -0
  24. package/dist/lib/reporting/ledger/receipts.d.ts +48 -0
  25. package/dist/lib/reporting/ledger/receipts.js +186 -0
  26. package/dist/lib/reporting/ledger/receipts.mjs +161 -0
  27. package/dist/lib/reporting/ledger/status-ingest.js +3 -3
  28. package/dist/lib/reporting/ledger/status-ingest.mjs +4 -5
  29. package/dist/lib/reporting/ledger/types.d.mts +43 -0
  30. package/dist/lib/reporting/ledger/types.d.ts +43 -0
  31. package/dist/lib/reporting/ledger/types.js +31 -2
  32. package/dist/lib/reporting/ledger/types.mjs +26 -1
  33. package/dist/lib/reporting/pagination.d.mts +6 -0
  34. package/dist/lib/reporting/pagination.d.ts +6 -0
  35. package/dist/lib/reporting/{gcs/errors.js → pagination.js} +12 -17
  36. package/dist/lib/reporting/pagination.mjs +12 -0
  37. package/dist/lib/reporting/reconciliation.d.mts +1 -0
  38. package/dist/lib/reporting/reconciliation.d.ts +1 -0
  39. package/dist/lib/reporting/reconciliation.js +3 -2
  40. package/dist/lib/reporting/reconciliation.mjs +3 -2
  41. package/dist/lib/reporting/service/index.d.mts +79 -153
  42. package/dist/lib/reporting/service/index.d.ts +79 -153
  43. package/dist/lib/reporting/service/index.js +34 -491
  44. package/dist/lib/reporting/service/index.mjs +36 -510
  45. package/dist/lib/reporting/service/scheduler-support.d.mts +43 -0
  46. package/dist/lib/reporting/service/scheduler-support.d.ts +43 -0
  47. package/dist/lib/reporting/service/scheduler-support.js +125 -0
  48. package/dist/lib/reporting/service/scheduler-support.mjs +96 -0
  49. package/dist/lib/schemas-data/v2.5/_provenance.json +1 -1
  50. package/dist/lib/signing/canonicalize.d.mts +4 -0
  51. package/dist/lib/signing/canonicalize.d.ts +4 -0
  52. package/dist/lib/signing/canonicalize.js +14 -8
  53. package/dist/lib/signing/canonicalize.mjs +14 -8
  54. package/dist/lib/signing/content-digest.d.mts +8 -0
  55. package/dist/lib/signing/content-digest.d.ts +8 -0
  56. package/dist/lib/signing/content-digest.js +11 -5
  57. package/dist/lib/signing/content-digest.mjs +10 -5
  58. package/dist/lib/signing/signer.js +9 -6
  59. package/dist/lib/signing/signer.mjs +10 -7
  60. package/dist/lib/signing/web-bot-auth.js +103 -37
  61. package/dist/lib/signing/web-bot-auth.mjs +108 -37
  62. package/dist/lib/testing/storyboard/junit.js +16 -3
  63. package/dist/lib/testing/storyboard/junit.mjs +16 -3
  64. package/dist/lib/testing/storyboard/request-signing/builder.js +10 -9
  65. package/dist/lib/testing/storyboard/request-signing/builder.mjs +10 -9
  66. package/dist/lib/testing/storyboard/runner.js +94 -25
  67. package/dist/lib/testing/storyboard/runner.mjs +94 -25
  68. package/dist/lib/testing/storyboard/types.d.mts +6 -0
  69. package/dist/lib/testing/storyboard/types.d.ts +6 -0
  70. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  71. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  72. package/dist/lib/types/schemas.generated.d.ts +907 -60
  73. package/dist/lib/types/schemas.generated.js +7 -7
  74. package/dist/lib/types/schemas.generated.mjs +7 -7
  75. package/dist/lib/version.d.mts +3 -3
  76. package/dist/lib/version.d.ts +3 -3
  77. package/dist/lib/version.js +3 -3
  78. package/dist/lib/version.mjs +3 -3
  79. package/docs/TYPE-SUMMARY.md +23 -5
  80. package/docs/guides/REPORTING-GCS-FENCE.md +3 -3
  81. package/docs/guides/REPORTING-GCS-MANAGED.md +4 -4
  82. package/docs/guides/REPORTING-LEDGER-CUTOVER.md +7 -7
  83. package/docs/guides/REPORTING-LEDGER.md +107 -51
  84. package/docs/guides/REPORTING-OPERATIONS.md +66 -5
  85. package/docs/guides/REPORTING-STABILITY.md +36 -32
  86. package/docs/llms.txt +4 -3
  87. package/docs/migration-14.x-rc-worksheet.md +4 -7
  88. package/docs/migration-reporting-storage-package.md +186 -0
  89. package/examples/README.md +1 -1
  90. package/package.json +13 -78
  91. package/dist/lib/reporting/azure/index.d.mts +0 -31
  92. package/dist/lib/reporting/azure/index.d.ts +0 -31
  93. package/dist/lib/reporting/azure/index.js +0 -266
  94. package/dist/lib/reporting/azure/index.mjs +0 -249
  95. package/dist/lib/reporting/bigquery/index.d.mts +0 -246
  96. package/dist/lib/reporting/bigquery/index.d.ts +0 -246
  97. package/dist/lib/reporting/bigquery/index.js +0 -633
  98. package/dist/lib/reporting/bigquery/index.mjs +0 -594
  99. package/dist/lib/reporting/gcs/adapter.d.mts +0 -38
  100. package/dist/lib/reporting/gcs/adapter.d.ts +0 -38
  101. package/dist/lib/reporting/gcs/adapter.js +0 -342
  102. package/dist/lib/reporting/gcs/adapter.mjs +0 -325
  103. package/dist/lib/reporting/gcs/bucket-policy.d.mts +0 -3
  104. package/dist/lib/reporting/gcs/bucket-policy.d.ts +0 -3
  105. package/dist/lib/reporting/gcs/bucket-policy.mjs +0 -7
  106. package/dist/lib/reporting/gcs/errors.d.mts +0 -11
  107. package/dist/lib/reporting/gcs/errors.d.ts +0 -11
  108. package/dist/lib/reporting/gcs/errors.mjs +0 -16
  109. package/dist/lib/reporting/gcs/fence.d.mts +0 -41
  110. package/dist/lib/reporting/gcs/fence.d.ts +0 -41
  111. package/dist/lib/reporting/gcs/fence.js +0 -250
  112. package/dist/lib/reporting/gcs/fence.mjs +0 -230
  113. package/dist/lib/reporting/gcs/index.d.mts +0 -18
  114. package/dist/lib/reporting/gcs/index.d.ts +0 -18
  115. package/dist/lib/reporting/gcs/index.js +0 -44
  116. package/dist/lib/reporting/gcs/index.mjs +0 -14
  117. package/dist/lib/reporting/gcs/io.d.mts +0 -7
  118. package/dist/lib/reporting/gcs/io.d.ts +0 -7
  119. package/dist/lib/reporting/gcs/io.js +0 -95
  120. package/dist/lib/reporting/gcs/io.mjs +0 -69
  121. package/dist/lib/reporting/gcs/reader.d.mts +0 -67
  122. package/dist/lib/reporting/gcs/reader.d.ts +0 -67
  123. package/dist/lib/reporting/gcs/reader.js +0 -193
  124. package/dist/lib/reporting/gcs/reader.mjs +0 -169
  125. package/dist/lib/reporting/gcs/row-provider.d.mts +0 -39
  126. package/dist/lib/reporting/gcs/row-provider.d.ts +0 -39
  127. package/dist/lib/reporting/gcs/row-provider.js +0 -225
  128. package/dist/lib/reporting/gcs/row-provider.mjs +0 -208
  129. package/dist/lib/reporting/gcs/validation.d.mts +0 -5
  130. package/dist/lib/reporting/gcs/validation.d.ts +0 -5
  131. package/dist/lib/reporting/gcs/validation.js +0 -49
  132. package/dist/lib/reporting/gcs/validation.mjs +0 -25
  133. package/dist/lib/reporting/ledger/change-feed.d.mts +0 -69
  134. package/dist/lib/reporting/ledger/change-feed.d.ts +0 -69
  135. package/dist/lib/reporting/ledger/change-feed.js +0 -107
  136. package/dist/lib/reporting/ledger/change-feed.mjs +0 -80
  137. package/dist/lib/reporting/ledger/managed-postgres.d.mts +0 -293
  138. package/dist/lib/reporting/ledger/managed-postgres.d.ts +0 -293
  139. package/dist/lib/reporting/ledger/managed-postgres.js +0 -2346
  140. package/dist/lib/reporting/ledger/managed-postgres.mjs +0 -2332
  141. package/dist/lib/reporting/ledger/managed-router.d.mts +0 -148
  142. package/dist/lib/reporting/ledger/managed-router.d.ts +0 -148
  143. package/dist/lib/reporting/ledger/managed-router.js +0 -280
  144. package/dist/lib/reporting/ledger/managed-router.mjs +0 -258
  145. package/dist/lib/reporting/ledger/managed.d.mts +0 -535
  146. package/dist/lib/reporting/ledger/managed.d.ts +0 -535
  147. package/dist/lib/reporting/ledger/managed.js +0 -761
  148. package/dist/lib/reporting/ledger/managed.mjs +0 -729
  149. package/dist/lib/reporting/ledger/notification-activity.d.mts +0 -332
  150. package/dist/lib/reporting/ledger/notification-activity.d.ts +0 -332
  151. package/dist/lib/reporting/ledger/notification-activity.js +0 -1366
  152. package/dist/lib/reporting/ledger/notification-activity.mjs +0 -1337
  153. package/dist/lib/reporting/ledger/object-writes.d.mts +0 -128
  154. package/dist/lib/reporting/ledger/object-writes.d.ts +0 -128
  155. package/dist/lib/reporting/ledger/object-writes.js +0 -147
  156. package/dist/lib/reporting/ledger/object-writes.mjs +0 -114
  157. package/dist/lib/reporting/ledger/postgres.d.mts +0 -689
  158. package/dist/lib/reporting/ledger/postgres.d.ts +0 -689
  159. package/dist/lib/reporting/ledger/postgres.js +0 -4462
  160. package/dist/lib/reporting/ledger/postgres.mjs +0 -4462
  161. package/dist/lib/reporting/ledger/row-storage-migration.d.mts +0 -59
  162. package/dist/lib/reporting/ledger/row-storage-migration.d.ts +0 -59
  163. package/dist/lib/reporting/ledger/row-storage-migration.js +0 -365
  164. package/dist/lib/reporting/ledger/row-storage-migration.mjs +0 -339
  165. package/dist/lib/reporting/ledger/row-storage-object.d.mts +0 -203
  166. package/dist/lib/reporting/ledger/row-storage-object.d.ts +0 -203
  167. package/dist/lib/reporting/ledger/row-storage-object.js +0 -379
  168. package/dist/lib/reporting/ledger/row-storage-object.mjs +0 -335
  169. package/dist/lib/reporting/ledger/row-storage-provider-io.d.mts +0 -44
  170. package/dist/lib/reporting/ledger/row-storage-provider-io.d.ts +0 -44
  171. package/dist/lib/reporting/ledger/row-storage-provider-io.js +0 -142
  172. package/dist/lib/reporting/ledger/row-storage-provider-io.mjs +0 -111
  173. package/dist/lib/reporting/ledger/row-storage.d.mts +0 -316
  174. package/dist/lib/reporting/ledger/row-storage.d.ts +0 -316
  175. package/dist/lib/reporting/ledger/row-storage.js +0 -812
  176. package/dist/lib/reporting/ledger/row-storage.mjs +0 -802
  177. package/dist/lib/reporting/s3/index.d.mts +0 -34
  178. package/dist/lib/reporting/s3/index.d.ts +0 -34
  179. package/dist/lib/reporting/s3/index.js +0 -347
  180. package/dist/lib/reporting/s3/index.mjs +0 -340
  181. package/dist/lib/reporting/service/maintenance.d.mts +0 -148
  182. package/dist/lib/reporting/service/maintenance.d.ts +0 -148
  183. package/dist/lib/reporting/service/maintenance.js +0 -185
  184. package/dist/lib/reporting/service/maintenance.mjs +0 -159
  185. package/examples/reliable-reporting-service/README.md +0 -169
@@ -1,246 +0,0 @@
1
- import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, ReportingPgPool } from '../ledger/index.mjs';
2
- /**
3
- * BigQuery warehouse sink for Reliable Reporting (shared SDK persistence spec,
4
- * adcontextprotocol/adcp#7996 §3.6).
5
- *
6
- * The sink is a derived, non-authoritative copy of committed revisions. It
7
- * follows the ledger's host change feed, reads every revision's rows through
8
- * the store's verified reader, maps them to the adopter's columns, and loads
9
- * one batch per tick with a deterministic job ID. It is never read for
10
- * serving or verification, so its tables, columns, partitioning and retention
11
- * are the adopter's.
12
- *
13
- * Exactly-once loading: a batch (change-feed range, revision list, job IDs) is
14
- * planned durably in PostgreSQL before any load. Before every submission the
15
- * sink looks the deterministic job ID up in the destination project and
16
- * location: a job that finished cleanly counts as loaded, a job still running
17
- * is waited for (never uploaded again), and only a missing job is uploaded.
18
- * A crash or timeout between the load and the cursor commit therefore replays
19
- * the same batch under the same job IDs without a second upload. A failed load
20
- * job is retried under a new attempt suffix only after BigQuery reports that
21
- * job finished with an error, and each table keeps its own attempt count, so
22
- * no batch lands twice. A load that outlasts the deadline never changes the job
23
- * ID: the sink grows that table's deadline instead (persisted with the plan).
24
- * Concurrent runs claim one durable plan with compare-and-swap. Replays of
25
- * that plan share job IDs; stale runs cannot change its attempts or cursor.
26
- */
27
- /**
28
- * Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink.
29
- *
30
- * @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
31
- */
32
- export declare const REPORTING_WAREHOUSE_SINK_MIGRATION: string;
33
- /**
34
- * Structural subset of the official `@google-cloud/bigquery` client the sink uses.
35
- *
36
- * @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
37
- */
38
- export interface ReportingBigQueryClientV1 {
39
- dataset(datasetId: string, options?: {
40
- projectId?: string;
41
- location?: string;
42
- }): {
43
- table(tableId: string): {
44
- load(source: string, metadata: Record<string, unknown>): Promise<unknown>;
45
- };
46
- };
47
- job(jobId: string, options?: {
48
- projectId?: string;
49
- location?: string;
50
- }): {
51
- getMetadata(): Promise<unknown>;
52
- /** @deprecated Unused: BigQuery does not stop a running load, so the sink never cancels. Kept so wrappers that declare it still type-check. */
53
- cancel?(): Promise<unknown>;
54
- };
55
- query(options: {
56
- query: string;
57
- location?: string;
58
- }): Promise<unknown>;
59
- }
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 interface ReportingWarehouseRowContextV1 {
64
- revision: ReportingLedgerRevisionMetadataV1;
65
- ordinal: number;
66
- }
67
- /**
68
- * @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
69
- */
70
- export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
71
- /** Ledger store with `changeFeed: true`. */
72
- store: Pick<PostgresReportingLedgerStore, 'changesAfter' | 'getRevisionMetadata' | 'readRevisionRows'> & {
73
- /**
74
- * The sink ignores the result, so wrappers written when this resolved
75
- * `void` keep compiling.
76
- */
77
- saveFeedConsumerCursor(name: string, cursor: string, options?: {
78
- refreshUnchanged?: boolean;
79
- }): Promise<unknown>;
80
- } & /** Needed only by `reset()`; custom store wrappers that predate it keep compiling. */ Partial<Pick<PostgresReportingLedgerStore, 'removeFeedConsumer'>>;
81
- /** PostgreSQL pool holding `REPORTING_WAREHOUSE_SINK_MIGRATION`. */
82
- db: Pick<ReportingPgPool, 'query'>;
83
- /** Host-constructed official BigQuery client. */
84
- bigquery: ReportingBigQueryClientV1;
85
- /**
86
- * Stable sink and consumer name. All replicas sharing it must use the same
87
- * ledger database, feed scope, destination, location and row mapping. Use
88
- * a new name when that configuration changes. Names must also be unique
89
- * across independent ledgers sharing a BigQuery project.
90
- */
91
- name: string;
92
- projectId?: string;
93
- datasetId: string;
94
- rowsTableId: string;
95
- revisionsTableId: string;
96
- /**
97
- * Dataset location, so jobs run in the dataset's region. Set it for any dataset outside the US and EU
98
- * multi-regions: BigQuery answers a job lookup without the right location with 404, and the sink then
99
- * cannot find the jobs it created.
100
- */
101
- location?: string;
102
- /** Restrict the sink to one account; omit for the deployment-wide feed. */
103
- account_id?: string;
104
- /**
105
- * Map one verified report row to the adopter's columns. The sink always adds
106
- * `reporting_revision_id`, `reporting_obligation_id`, `account_id`,
107
- * `revision_number`, `finality`, `period_date` (the period start's calendar date in its
108
- * `source_timezone`, AdCP's `YYYY-MM-DD`; the batch fails if it cannot be computed) and
109
- * `ordinal`. Default: the
110
- * row as a `row` JSON column.
111
- */
112
- mapRow?(row: Record<string, unknown>, context: ReportingWarehouseRowContextV1): Record<string, unknown>;
113
- /** Revisions per batch. Default 200. */
114
- maxRevisionsPerBatch?: number;
115
- /**
116
- * @deprecated Has no effect, and the sink warns when it is set. The official
117
- * client submits a local-file load by uploading a job resource whose
118
- * `configuration.load` is built from the load options, and offers no way to
119
- * set `configuration.labels`; BigQuery silently drops `labels` found inside
120
- * `configuration.load`. For cost attribution, filter
121
- * `INFORMATION_SCHEMA.JOBS` on `destination_table` or on the `adcp_rr_`
122
- * job ID prefix instead.
123
- */
124
- labels?: Readonly<Record<string, string>>;
125
- /**
126
- * Base deadline for one run's work on one load. Default 10 minutes. It bounds
127
- * how long a run uploads a file or waits for a running job; it does not bound
128
- * the job. BigQuery does not stop a load when the client gives up (a cancel
129
- * is accepted and the job finishes anyway), so the sink never cancels.
130
- * Before every submission it looks the deterministic job ID up in `projectId`
131
- * and `location`: a job that finished cleanly is accepted, a job that is
132
- * pending or running is waited for (polled within the deadline) instead of
133
- * being uploaded again, and only a missing job is uploaded. When the
134
- * deadline passes, the run rejects with the plan retained and nothing
135
- * advanced, and the next run checks the job again. Each such timeout doubles
136
- * that table's deadline for later runs (up to 6 hours, persisted with the
137
- * plan, and never changing the job ID), so an upload slower than the
138
- * deadline eventually gets enough time. Set it above your slowest expected
139
- * load to avoid the extra runs. Only a job that finished with an error
140
- * advances the attempt. A status check that times out is bounded by this base
141
- * deadline and does not grow it. This is a client-side deadline: BigQuery's
142
- * server-side `jobTimeoutMs` cannot be set on a local-file load through the
143
- * official client.
144
- */
145
- loadTimeoutMilliseconds?: number;
146
- }
147
- /**
148
- * @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
149
- */
150
- export interface BigQueryReportingWarehouseSinkV1 {
151
- /**
152
- * Load at most one batch. Resolves with what was loaded; `idle` when no
153
- * revision changes were selected. Idle ticks can advance past other feed changes.
154
- * An overlapping run that loses its plan or cursor claim rejects. Retry
155
- * `runOnce()` to resume the current durable plan or committed cursor.
156
- *
157
- * `missing` lists revision IDs the change feed announced that no longer
158
- * exist in the ledger because their period was retired before this batch
159
- * ran. That is a data-loss signal: the sink fell behind retention (it was
160
- * down longer than `maxFeedHoldDays`, so retention stopped waiting for it)
161
- * and the warehouse lacks those revisions. Backfill them from another source
162
- * or accept the gap. The cursor still advances so the sink is not stuck.
163
- * Alert on a non-empty `missing`. After a crash-and-replay of a planned
164
- * batch, a listed revision may already have been loaded by the first attempt.
165
- */
166
- runOnce(options?: {
167
- signal?: AbortSignal;
168
- }): Promise<{
169
- idle: boolean;
170
- revisions: number;
171
- rows: number;
172
- missing: string[];
173
- }>;
174
- /**
175
- * Clear the sink's saved state so the next `runOnce()` starts again from the
176
- * oldest retained change, and unregister its feed consumer so the old
177
- * checkpoint stops holding back retention. This is the way out of a sink
178
- * that keeps rejecting with `CURSOR_EXPIRED`: a brand-new sink whose first
179
- * read lost a startup race with pruning, or a sink that fell behind
180
- * retention and has been resynchronized from current revisions. Stop every
181
- * worker using this sink name first.
182
- *
183
- * It refuses while a batch plan is retained, because that batch's load jobs
184
- * may already have succeeded; pass `discardRetainedPlan: true` once you have
185
- * reconciled it against BigQuery. The warehouse is not touched: a sink that
186
- * already loaded history will load the retained revisions again, so empty
187
- * the destination tables first, or use a new sink name against new tables.
188
- * Each reset starts a new job ID generation, so reloaded batches submit
189
- * fresh BigQuery jobs instead of matching the finished jobs of the earlier
190
- * history. The sink never cancels a load, so stop every worker and let its
191
- * in-flight uploads and jobs finish before emptying the destination tables. Nothing holds change retention between `reset()` and the first
192
- * committed batch. If `reset()` rejects after clearing the sink's state
193
- * (the consumer could not be unregistered), call it again before restarting
194
- * workers; it is idempotent. Needs a store with `removeFeedConsumer`.
195
- * Resolves with whether a saved sink state existed.
196
- */
197
- reset(options?: {
198
- discardRetainedPlan?: boolean;
199
- }): Promise<{
200
- cleared: boolean;
201
- }>;
202
- /** DDL for the default rows and revisions tables (partitioned and clustered). */
203
- readonly defaultTablesSql: string;
204
- /** DDL for the reference `current_rows` view. */
205
- readonly currentRowsViewSql: string;
206
- }
207
- /**
208
- * @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
209
- */
210
- export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
211
- /**
212
- * How long one run may upload a file or wait for a running job: the configured
213
- * base doubled once per earlier timeout of that table's load, capped at 6 hours.
214
- *
215
- * @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
216
- */
217
- export declare function reportingWarehouseLoadDeadlineV1(baseMilliseconds: number, timeouts: number): number;
218
- /**
219
- * Deterministic load job ID for one planned change-feed range.
220
- *
221
- * @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
222
- */
223
- export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string, generation?: number): string;
224
- interface WarehouseTablesV1 {
225
- projectId?: string;
226
- datasetId: string;
227
- rowsTableId: string;
228
- revisionsTableId: string;
229
- }
230
- /**
231
- * DDL for the default warehouse tables: partitioned by period date, clustered by account and revision.
232
- *
233
- * @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
234
- */
235
- export declare function reportingWarehouseDefaultTablesSqlV1(tables: WarehouseTablesV1): string;
236
- /**
237
- * DDL for the reference `current_rows` view: only each obligation's current
238
- * revision (its official revision, otherwise its latest snapshot). Summing
239
- * cumulative snapshots across revisions double-counts; query this view.
240
- *
241
- * @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
242
- */
243
- export declare function reportingWarehouseCurrentRowsViewSqlV1(tables: WarehouseTablesV1 & {
244
- viewId?: string;
245
- }): string;
246
- export {};
@@ -1,246 +0,0 @@
1
- import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, ReportingPgPool } from '../ledger';
2
- /**
3
- * BigQuery warehouse sink for Reliable Reporting (shared SDK persistence spec,
4
- * adcontextprotocol/adcp#7996 §3.6).
5
- *
6
- * The sink is a derived, non-authoritative copy of committed revisions. It
7
- * follows the ledger's host change feed, reads every revision's rows through
8
- * the store's verified reader, maps them to the adopter's columns, and loads
9
- * one batch per tick with a deterministic job ID. It is never read for
10
- * serving or verification, so its tables, columns, partitioning and retention
11
- * are the adopter's.
12
- *
13
- * Exactly-once loading: a batch (change-feed range, revision list, job IDs) is
14
- * planned durably in PostgreSQL before any load. Before every submission the
15
- * sink looks the deterministic job ID up in the destination project and
16
- * location: a job that finished cleanly counts as loaded, a job still running
17
- * is waited for (never uploaded again), and only a missing job is uploaded.
18
- * A crash or timeout between the load and the cursor commit therefore replays
19
- * the same batch under the same job IDs without a second upload. A failed load
20
- * job is retried under a new attempt suffix only after BigQuery reports that
21
- * job finished with an error, and each table keeps its own attempt count, so
22
- * no batch lands twice. A load that outlasts the deadline never changes the job
23
- * ID: the sink grows that table's deadline instead (persisted with the plan).
24
- * Concurrent runs claim one durable plan with compare-and-swap. Replays of
25
- * that plan share job IDs; stale runs cannot change its attempts or cursor.
26
- */
27
- /**
28
- * Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink.
29
- *
30
- * @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
31
- */
32
- export declare const REPORTING_WAREHOUSE_SINK_MIGRATION: string;
33
- /**
34
- * Structural subset of the official `@google-cloud/bigquery` client the sink uses.
35
- *
36
- * @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
37
- */
38
- export interface ReportingBigQueryClientV1 {
39
- dataset(datasetId: string, options?: {
40
- projectId?: string;
41
- location?: string;
42
- }): {
43
- table(tableId: string): {
44
- load(source: string, metadata: Record<string, unknown>): Promise<unknown>;
45
- };
46
- };
47
- job(jobId: string, options?: {
48
- projectId?: string;
49
- location?: string;
50
- }): {
51
- getMetadata(): Promise<unknown>;
52
- /** @deprecated Unused: BigQuery does not stop a running load, so the sink never cancels. Kept so wrappers that declare it still type-check. */
53
- cancel?(): Promise<unknown>;
54
- };
55
- query(options: {
56
- query: string;
57
- location?: string;
58
- }): Promise<unknown>;
59
- }
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 interface ReportingWarehouseRowContextV1 {
64
- revision: ReportingLedgerRevisionMetadataV1;
65
- ordinal: number;
66
- }
67
- /**
68
- * @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
69
- */
70
- export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
71
- /** Ledger store with `changeFeed: true`. */
72
- store: Pick<PostgresReportingLedgerStore, 'changesAfter' | 'getRevisionMetadata' | 'readRevisionRows'> & {
73
- /**
74
- * The sink ignores the result, so wrappers written when this resolved
75
- * `void` keep compiling.
76
- */
77
- saveFeedConsumerCursor(name: string, cursor: string, options?: {
78
- refreshUnchanged?: boolean;
79
- }): Promise<unknown>;
80
- } & /** Needed only by `reset()`; custom store wrappers that predate it keep compiling. */ Partial<Pick<PostgresReportingLedgerStore, 'removeFeedConsumer'>>;
81
- /** PostgreSQL pool holding `REPORTING_WAREHOUSE_SINK_MIGRATION`. */
82
- db: Pick<ReportingPgPool, 'query'>;
83
- /** Host-constructed official BigQuery client. */
84
- bigquery: ReportingBigQueryClientV1;
85
- /**
86
- * Stable sink and consumer name. All replicas sharing it must use the same
87
- * ledger database, feed scope, destination, location and row mapping. Use
88
- * a new name when that configuration changes. Names must also be unique
89
- * across independent ledgers sharing a BigQuery project.
90
- */
91
- name: string;
92
- projectId?: string;
93
- datasetId: string;
94
- rowsTableId: string;
95
- revisionsTableId: string;
96
- /**
97
- * Dataset location, so jobs run in the dataset's region. Set it for any dataset outside the US and EU
98
- * multi-regions: BigQuery answers a job lookup without the right location with 404, and the sink then
99
- * cannot find the jobs it created.
100
- */
101
- location?: string;
102
- /** Restrict the sink to one account; omit for the deployment-wide feed. */
103
- account_id?: string;
104
- /**
105
- * Map one verified report row to the adopter's columns. The sink always adds
106
- * `reporting_revision_id`, `reporting_obligation_id`, `account_id`,
107
- * `revision_number`, `finality`, `period_date` (the period start's calendar date in its
108
- * `source_timezone`, AdCP's `YYYY-MM-DD`; the batch fails if it cannot be computed) and
109
- * `ordinal`. Default: the
110
- * row as a `row` JSON column.
111
- */
112
- mapRow?(row: Record<string, unknown>, context: ReportingWarehouseRowContextV1): Record<string, unknown>;
113
- /** Revisions per batch. Default 200. */
114
- maxRevisionsPerBatch?: number;
115
- /**
116
- * @deprecated Has no effect, and the sink warns when it is set. The official
117
- * client submits a local-file load by uploading a job resource whose
118
- * `configuration.load` is built from the load options, and offers no way to
119
- * set `configuration.labels`; BigQuery silently drops `labels` found inside
120
- * `configuration.load`. For cost attribution, filter
121
- * `INFORMATION_SCHEMA.JOBS` on `destination_table` or on the `adcp_rr_`
122
- * job ID prefix instead.
123
- */
124
- labels?: Readonly<Record<string, string>>;
125
- /**
126
- * Base deadline for one run's work on one load. Default 10 minutes. It bounds
127
- * how long a run uploads a file or waits for a running job; it does not bound
128
- * the job. BigQuery does not stop a load when the client gives up (a cancel
129
- * is accepted and the job finishes anyway), so the sink never cancels.
130
- * Before every submission it looks the deterministic job ID up in `projectId`
131
- * and `location`: a job that finished cleanly is accepted, a job that is
132
- * pending or running is waited for (polled within the deadline) instead of
133
- * being uploaded again, and only a missing job is uploaded. When the
134
- * deadline passes, the run rejects with the plan retained and nothing
135
- * advanced, and the next run checks the job again. Each such timeout doubles
136
- * that table's deadline for later runs (up to 6 hours, persisted with the
137
- * plan, and never changing the job ID), so an upload slower than the
138
- * deadline eventually gets enough time. Set it above your slowest expected
139
- * load to avoid the extra runs. Only a job that finished with an error
140
- * advances the attempt. A status check that times out is bounded by this base
141
- * deadline and does not grow it. This is a client-side deadline: BigQuery's
142
- * server-side `jobTimeoutMs` cannot be set on a local-file load through the
143
- * official client.
144
- */
145
- loadTimeoutMilliseconds?: number;
146
- }
147
- /**
148
- * @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
149
- */
150
- export interface BigQueryReportingWarehouseSinkV1 {
151
- /**
152
- * Load at most one batch. Resolves with what was loaded; `idle` when no
153
- * revision changes were selected. Idle ticks can advance past other feed changes.
154
- * An overlapping run that loses its plan or cursor claim rejects. Retry
155
- * `runOnce()` to resume the current durable plan or committed cursor.
156
- *
157
- * `missing` lists revision IDs the change feed announced that no longer
158
- * exist in the ledger because their period was retired before this batch
159
- * ran. That is a data-loss signal: the sink fell behind retention (it was
160
- * down longer than `maxFeedHoldDays`, so retention stopped waiting for it)
161
- * and the warehouse lacks those revisions. Backfill them from another source
162
- * or accept the gap. The cursor still advances so the sink is not stuck.
163
- * Alert on a non-empty `missing`. After a crash-and-replay of a planned
164
- * batch, a listed revision may already have been loaded by the first attempt.
165
- */
166
- runOnce(options?: {
167
- signal?: AbortSignal;
168
- }): Promise<{
169
- idle: boolean;
170
- revisions: number;
171
- rows: number;
172
- missing: string[];
173
- }>;
174
- /**
175
- * Clear the sink's saved state so the next `runOnce()` starts again from the
176
- * oldest retained change, and unregister its feed consumer so the old
177
- * checkpoint stops holding back retention. This is the way out of a sink
178
- * that keeps rejecting with `CURSOR_EXPIRED`: a brand-new sink whose first
179
- * read lost a startup race with pruning, or a sink that fell behind
180
- * retention and has been resynchronized from current revisions. Stop every
181
- * worker using this sink name first.
182
- *
183
- * It refuses while a batch plan is retained, because that batch's load jobs
184
- * may already have succeeded; pass `discardRetainedPlan: true` once you have
185
- * reconciled it against BigQuery. The warehouse is not touched: a sink that
186
- * already loaded history will load the retained revisions again, so empty
187
- * the destination tables first, or use a new sink name against new tables.
188
- * Each reset starts a new job ID generation, so reloaded batches submit
189
- * fresh BigQuery jobs instead of matching the finished jobs of the earlier
190
- * history. The sink never cancels a load, so stop every worker and let its
191
- * in-flight uploads and jobs finish before emptying the destination tables. Nothing holds change retention between `reset()` and the first
192
- * committed batch. If `reset()` rejects after clearing the sink's state
193
- * (the consumer could not be unregistered), call it again before restarting
194
- * workers; it is idempotent. Needs a store with `removeFeedConsumer`.
195
- * Resolves with whether a saved sink state existed.
196
- */
197
- reset(options?: {
198
- discardRetainedPlan?: boolean;
199
- }): Promise<{
200
- cleared: boolean;
201
- }>;
202
- /** DDL for the default rows and revisions tables (partitioned and clustered). */
203
- readonly defaultTablesSql: string;
204
- /** DDL for the reference `current_rows` view. */
205
- readonly currentRowsViewSql: string;
206
- }
207
- /**
208
- * @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
209
- */
210
- export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
211
- /**
212
- * How long one run may upload a file or wait for a running job: the configured
213
- * base doubled once per earlier timeout of that table's load, capped at 6 hours.
214
- *
215
- * @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
216
- */
217
- export declare function reportingWarehouseLoadDeadlineV1(baseMilliseconds: number, timeouts: number): number;
218
- /**
219
- * Deterministic load job ID for one planned change-feed range.
220
- *
221
- * @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
222
- */
223
- export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string, generation?: number): string;
224
- interface WarehouseTablesV1 {
225
- projectId?: string;
226
- datasetId: string;
227
- rowsTableId: string;
228
- revisionsTableId: string;
229
- }
230
- /**
231
- * DDL for the default warehouse tables: partitioned by period date, clustered by account and revision.
232
- *
233
- * @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
234
- */
235
- export declare function reportingWarehouseDefaultTablesSqlV1(tables: WarehouseTablesV1): string;
236
- /**
237
- * DDL for the reference `current_rows` view: only each obligation's current
238
- * revision (its official revision, otherwise its latest snapshot). Summing
239
- * cumulative snapshots across revisions double-counts; query this view.
240
- *
241
- * @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
242
- */
243
- export declare function reportingWarehouseCurrentRowsViewSqlV1(tables: WarehouseTablesV1 & {
244
- viewId?: string;
245
- }): string;
246
- export {};