@adcp/sdk 15.9.0 → 16.0.0-beta.1

package/dist/lib/reporting/bigquery/index.d.mts

@@ -11,17 +11,30 @@ import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, R
  * are the adopter's.
  *
  * Exactly-once loading: a batch (change-feed range, revision list, job IDs) is
- * planned durably in PostgreSQL before any load. A crash between the load and
- * the cursor commit replays the same batch under the same job IDs, which
- * BigQuery refuses to run twice. A failed load job is retried under a new
- * attempt suffix only after BigQuery reports that job finished with an error,
- * and each table keeps its own attempt count, so no batch lands twice.
+ * planned durably in PostgreSQL before any load. Before every submission the
+ * sink looks the deterministic job ID up in the destination project and
+ * location: a job that finished cleanly counts as loaded, a job still running
+ * is waited for (never uploaded again), and only a missing job is uploaded.
+ * A crash or timeout between the load and the cursor commit therefore replays
+ * the same batch under the same job IDs without a second upload. A failed load
+ * job is retried under a new attempt suffix only after BigQuery reports that
+ * job finished with an error, and each table keeps its own attempt count, so
+ * no batch lands twice. A load that outlasts the deadline never changes the job
+ * ID: the sink grows that table's deadline instead (persisted with the plan).
  * Concurrent runs claim one durable plan with compare-and-swap. Replays of
  * that plan share job IDs; stale runs cannot change its attempts or cursor.
  */
-/** Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink. */
+/**
+ * Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink.
+ *
+ * @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
+ */
 export declare const REPORTING_WAREHOUSE_SINK_MIGRATION: string;
-/** Structural subset of the official `@google-cloud/bigquery` client the sink uses. */
+/**
+ * Structural subset of the official `@google-cloud/bigquery` client the sink uses.
+ *
+ * @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
+ */
 export interface ReportingBigQueryClientV1 {
     dataset(datasetId: string, options?: {
         projectId?: string;
@@ -36,7 +49,7 @@ export interface ReportingBigQueryClientV1 {
         location?: string;
     }): {
         getMetadata(): Promise<unknown>;
-        /** Request cancellation. Optional so wrappers written before the sink used it still type-check. */
+        /** @deprecated Unused: BigQuery does not stop a running load, so the sink never cancels. Kept so wrappers that declare it still type-check. */
         cancel?(): Promise<unknown>;
     };
     query(options: {
@@ -44,10 +57,16 @@ export interface ReportingBigQueryClientV1 {
         location?: string;
     }): Promise<unknown>;
 }
+/**
+ * @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
+ */
 export interface ReportingWarehouseRowContextV1 {
     revision: ReportingLedgerRevisionMetadataV1;
     ordinal: number;
 }
+/**
+ * @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
+ */
 export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     /** Ledger store with `changeFeed: true`. */
     store: Pick<PostgresReportingLedgerStore, 'changesAfter' | 'getRevisionMetadata' | 'readRevisionRows'> & {
@@ -74,14 +93,20 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     datasetId: string;
     rowsTableId: string;
     revisionsTableId: string;
-    /** Dataset location, so jobs run in the dataset's region. */
+    /**
+     * Dataset location, so jobs run in the dataset's region. Set it for any dataset outside the US and EU
+     * multi-regions: BigQuery answers a job lookup without the right location with 404, and the sink then
+     * cannot find the jobs it created.
+     */
     location?: string;
     /** Restrict the sink to one account; omit for the deployment-wide feed. */
     account_id?: string;
     /**
      * Map one verified report row to the adopter's columns. The sink always adds
      * `reporting_revision_id`, `reporting_obligation_id`, `account_id`,
-     * `revision_number`, `finality`, `period_date` and `ordinal`. Default: the
+     * `revision_number`, `finality`, `period_date` (the period start's calendar date in its
+     * `source_timezone`, AdCP's `YYYY-MM-DD`; the batch fails if it cannot be computed) and
+     * `ordinal`. Default: the
      * row as a `row` JSON column.
      */
     mapRow?(row: Record<string, unknown>, context: ReportingWarehouseRowContextV1): Record<string, unknown>;
@@ -98,21 +123,30 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
      */
     labels?: Readonly<Record<string, string>>;
     /**
-     * Deadline for one load (and for each status check). Default 10 minutes.
-     * When a load exceeds it, the sink asks BigQuery to cancel that job by its
-     * deterministic ID (in `projectId` and `location`) and rejects, leaving the
-     * plan in place. The next run finds the cancelled job finished with an
-     * error, advances that table's attempt and rejects; the run after that
-     * loads under the new attempt. If the cancel has not taken effect yet the
-     * next run waits for the job. Each attempt doubles the load deadline (up to
-     * 6 hours), so a load that is slow but healthy converges; set this above
-     * your slowest expected load to avoid the cancelled attempts. A status
-     * check that times out is not cancelled. This is a client-side deadline:
-     * BigQuery's server-side `jobTimeoutMs` cannot be set on a local-file load
-     * through the official client, and cancellation is best effort.
+     * Base deadline for one run's work on one load. Default 10 minutes. It bounds
+     * how long a run uploads a file or waits for a running job; it does not bound
+     * the job. BigQuery does not stop a load when the client gives up (a cancel
+     * is accepted and the job finishes anyway), so the sink never cancels.
+     * Before every submission it looks the deterministic job ID up in `projectId`
+     * and `location`: a job that finished cleanly is accepted, a job that is
+     * pending or running is waited for (polled within the deadline) instead of
+     * being uploaded again, and only a missing job is uploaded. When the
+     * deadline passes, the run rejects with the plan retained and nothing
+     * advanced, and the next run checks the job again. Each such timeout doubles
+     * that table's deadline for later runs (up to 6 hours, persisted with the
+     * plan, and never changing the job ID), so an upload slower than the
+     * deadline eventually gets enough time. Set it above your slowest expected
+     * load to avoid the extra runs. Only a job that finished with an error
+     * advances the attempt. A status check that times out is bounded by this base
+     * deadline and does not grow it. This is a client-side deadline: BigQuery's
+     * server-side `jobTimeoutMs` cannot be set on a local-file load through the
+     * official client.
      */
     loadTimeoutMilliseconds?: number;
 }
+/**
+ * @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
+ */
 export interface BigQueryReportingWarehouseSinkV1 {
     /**
      * Load at most one batch. Resolves with what was loaded; `idle` when no
@@ -153,7 +187,8 @@ export interface BigQueryReportingWarehouseSinkV1 {
      * the destination tables first, or use a new sink name against new tables.
      * Each reset starts a new job ID generation, so reloaded batches submit
      * fresh BigQuery jobs instead of matching the finished jobs of the earlier
-     * history. Nothing holds change retention between `reset()` and the first
+     * history. The sink never cancels a load, so stop every worker and let its
+     * in-flight uploads and jobs finish before emptying the destination tables. Nothing holds change retention between `reset()` and the first
      * committed batch. If `reset()` rejects after clearing the sink's state
      * (the consumer could not be unregistered), call it again before restarting
      * workers; it is idempotent. Needs a store with `removeFeedConsumer`.
@@ -169,8 +204,22 @@ export interface BigQueryReportingWarehouseSinkV1 {
     /** DDL for the reference `current_rows` view. */
     readonly currentRowsViewSql: string;
 }
+/**
+ * @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
+ */
 export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
-/** Deterministic load job ID for one planned change-feed range. */
+/**
+ * How long one run may upload a file or wait for a running job: the configured
+ * base doubled once per earlier timeout of that table's load, capped at 6 hours.
+ *
+ * @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
+ */
+export declare function reportingWarehouseLoadDeadlineV1(baseMilliseconds: number, timeouts: number): number;
+/**
+ * Deterministic load job ID for one planned change-feed range.
+ *
+ * @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
+ */
 export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string, generation?: number): string;
 interface WarehouseTablesV1 {
     projectId?: string;
@@ -178,12 +227,18 @@ interface WarehouseTablesV1 {
     rowsTableId: string;
     revisionsTableId: string;
 }
-/** DDL for the default warehouse tables: partitioned by period date, clustered by account and revision. */
+/**
+ * DDL for the default warehouse tables: partitioned by period date, clustered by account and revision.
+ *
+ * @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
+ */
 export declare function reportingWarehouseDefaultTablesSqlV1(tables: WarehouseTablesV1): string;
 /**
  * DDL for the reference `current_rows` view: only each obligation's current
  * revision (its official revision, otherwise its latest snapshot). Summing
  * cumulative snapshots across revisions double-counts; query this view.
+ *
+ * @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
  */
 export declare function reportingWarehouseCurrentRowsViewSqlV1(tables: WarehouseTablesV1 & {
     viewId?: string;

package/dist/lib/reporting/bigquery/index.d.ts

@@ -11,17 +11,30 @@ import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, R
  * are the adopter's.
  *
  * Exactly-once loading: a batch (change-feed range, revision list, job IDs) is
- * planned durably in PostgreSQL before any load. A crash between the load and
- * the cursor commit replays the same batch under the same job IDs, which
- * BigQuery refuses to run twice. A failed load job is retried under a new
- * attempt suffix only after BigQuery reports that job finished with an error,
- * and each table keeps its own attempt count, so no batch lands twice.
+ * planned durably in PostgreSQL before any load. Before every submission the
+ * sink looks the deterministic job ID up in the destination project and
+ * location: a job that finished cleanly counts as loaded, a job still running
+ * is waited for (never uploaded again), and only a missing job is uploaded.
+ * A crash or timeout between the load and the cursor commit therefore replays
+ * the same batch under the same job IDs without a second upload. A failed load
+ * job is retried under a new attempt suffix only after BigQuery reports that
+ * job finished with an error, and each table keeps its own attempt count, so
+ * no batch lands twice. A load that outlasts the deadline never changes the job
+ * ID: the sink grows that table's deadline instead (persisted with the plan).
  * Concurrent runs claim one durable plan with compare-and-swap. Replays of
  * that plan share job IDs; stale runs cannot change its attempts or cursor.
  */
-/** Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink. */
+/**
+ * Apply after `REPORTING_LEDGER_CHANGES_MIGRATION`. Holds one row per sink.
+ *
+ * @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
+ */
 export declare const REPORTING_WAREHOUSE_SINK_MIGRATION: string;
-/** Structural subset of the official `@google-cloud/bigquery` client the sink uses. */
+/**
+ * Structural subset of the official `@google-cloud/bigquery` client the sink uses.
+ *
+ * @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
+ */
 export interface ReportingBigQueryClientV1 {
     dataset(datasetId: string, options?: {
         projectId?: string;
@@ -36,7 +49,7 @@ export interface ReportingBigQueryClientV1 {
         location?: string;
     }): {
         getMetadata(): Promise<unknown>;
-        /** Request cancellation. Optional so wrappers written before the sink used it still type-check. */
+        /** @deprecated Unused: BigQuery does not stop a running load, so the sink never cancels. Kept so wrappers that declare it still type-check. */
         cancel?(): Promise<unknown>;
     };
     query(options: {
@@ -44,10 +57,16 @@ export interface ReportingBigQueryClientV1 {
         location?: string;
     }): Promise<unknown>;
 }
+/**
+ * @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
+ */
 export interface ReportingWarehouseRowContextV1 {
     revision: ReportingLedgerRevisionMetadataV1;
     ordinal: number;
 }
+/**
+ * @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
+ */
 export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     /** Ledger store with `changeFeed: true`. */
     store: Pick<PostgresReportingLedgerStore, 'changesAfter' | 'getRevisionMetadata' | 'readRevisionRows'> & {
@@ -74,14 +93,20 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
     datasetId: string;
     rowsTableId: string;
     revisionsTableId: string;
-    /** Dataset location, so jobs run in the dataset's region. */
+    /**
+     * Dataset location, so jobs run in the dataset's region. Set it for any dataset outside the US and EU
+     * multi-regions: BigQuery answers a job lookup without the right location with 404, and the sink then
+     * cannot find the jobs it created.
+     */
     location?: string;
     /** Restrict the sink to one account; omit for the deployment-wide feed. */
     account_id?: string;
     /**
      * Map one verified report row to the adopter's columns. The sink always adds
      * `reporting_revision_id`, `reporting_obligation_id`, `account_id`,
-     * `revision_number`, `finality`, `period_date` and `ordinal`. Default: the
+     * `revision_number`, `finality`, `period_date` (the period start's calendar date in its
+     * `source_timezone`, AdCP's `YYYY-MM-DD`; the batch fails if it cannot be computed) and
+     * `ordinal`. Default: the
      * row as a `row` JSON column.
      */
     mapRow?(row: Record<string, unknown>, context: ReportingWarehouseRowContextV1): Record<string, unknown>;
@@ -98,21 +123,30 @@ export interface CreateBigQueryReportingWarehouseSinkOptionsV1 {
      */
     labels?: Readonly<Record<string, string>>;
     /**
-     * Deadline for one load (and for each status check). Default 10 minutes.
-     * When a load exceeds it, the sink asks BigQuery to cancel that job by its
-     * deterministic ID (in `projectId` and `location`) and rejects, leaving the
-     * plan in place. The next run finds the cancelled job finished with an
-     * error, advances that table's attempt and rejects; the run after that
-     * loads under the new attempt. If the cancel has not taken effect yet the
-     * next run waits for the job. Each attempt doubles the load deadline (up to
-     * 6 hours), so a load that is slow but healthy converges; set this above
-     * your slowest expected load to avoid the cancelled attempts. A status
-     * check that times out is not cancelled. This is a client-side deadline:
-     * BigQuery's server-side `jobTimeoutMs` cannot be set on a local-file load
-     * through the official client, and cancellation is best effort.
+     * Base deadline for one run's work on one load. Default 10 minutes. It bounds
+     * how long a run uploads a file or waits for a running job; it does not bound
+     * the job. BigQuery does not stop a load when the client gives up (a cancel
+     * is accepted and the job finishes anyway), so the sink never cancels.
+     * Before every submission it looks the deterministic job ID up in `projectId`
+     * and `location`: a job that finished cleanly is accepted, a job that is
+     * pending or running is waited for (polled within the deadline) instead of
+     * being uploaded again, and only a missing job is uploaded. When the
+     * deadline passes, the run rejects with the plan retained and nothing
+     * advanced, and the next run checks the job again. Each such timeout doubles
+     * that table's deadline for later runs (up to 6 hours, persisted with the
+     * plan, and never changing the job ID), so an upload slower than the
+     * deadline eventually gets enough time. Set it above your slowest expected
+     * load to avoid the extra runs. Only a job that finished with an error
+     * advances the attempt. A status check that times out is bounded by this base
+     * deadline and does not grow it. This is a client-side deadline: BigQuery's
+     * server-side `jobTimeoutMs` cannot be set on a local-file load through the
+     * official client.
      */
     loadTimeoutMilliseconds?: number;
 }
+/**
+ * @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
+ */
 export interface BigQueryReportingWarehouseSinkV1 {
     /**
      * Load at most one batch. Resolves with what was loaded; `idle` when no
@@ -153,7 +187,8 @@ export interface BigQueryReportingWarehouseSinkV1 {
      * the destination tables first, or use a new sink name against new tables.
      * Each reset starts a new job ID generation, so reloaded batches submit
      * fresh BigQuery jobs instead of matching the finished jobs of the earlier
-     * history. Nothing holds change retention between `reset()` and the first
+     * history. The sink never cancels a load, so stop every worker and let its
+     * in-flight uploads and jobs finish before emptying the destination tables. Nothing holds change retention between `reset()` and the first
      * committed batch. If `reset()` rejects after clearing the sink's state
      * (the consumer could not be unregistered), call it again before restarting
      * workers; it is idempotent. Needs a store with `removeFeedConsumer`.
@@ -169,8 +204,22 @@ export interface BigQueryReportingWarehouseSinkV1 {
     /** DDL for the reference `current_rows` view. */
     readonly currentRowsViewSql: string;
 }
+/**
+ * @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
+ */
 export declare function createBigQueryReportingWarehouseSinkV1(options: CreateBigQueryReportingWarehouseSinkOptionsV1): BigQueryReportingWarehouseSinkV1;
-/** Deterministic load job ID for one planned change-feed range. */
+/**
+ * How long one run may upload a file or wait for a running job: the configured
+ * base doubled once per earlier timeout of that table's load, capped at 6 hours.
+ *
+ * @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
+ */
+export declare function reportingWarehouseLoadDeadlineV1(baseMilliseconds: number, timeouts: number): number;
+/**
+ * Deterministic load job ID for one planned change-feed range.
+ *
+ * @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
+ */
 export declare function reportingWarehouseJobIdV1(name: string, from: string | null, to: string, generation?: number): string;
 interface WarehouseTablesV1 {
     projectId?: string;
@@ -178,12 +227,18 @@ interface WarehouseTablesV1 {
     rowsTableId: string;
     revisionsTableId: string;
 }
-/** DDL for the default warehouse tables: partitioned by period date, clustered by account and revision. */
+/**
+ * DDL for the default warehouse tables: partitioned by period date, clustered by account and revision.
+ *
+ * @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
+ */
 export declare function reportingWarehouseDefaultTablesSqlV1(tables: WarehouseTablesV1): string;
 /**
  * DDL for the reference `current_rows` view: only each obligation's current
  * revision (its official revision, otherwise its latest snapshot). Summing
  * cumulative snapshots across revisions double-counts; query this view.
+ *
+ * @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
  */
 export declare function reportingWarehouseCurrentRowsViewSqlV1(tables: WarehouseTablesV1 & {
     viewId?: string;