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

package/dist/lib/reporting/azure/index.mjs

@@ -1,249 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { ReportingRowStoreError } from "../ledger/row-storage-errors.mjs";
-import {
-  assertReportingRowLocationKeys,
-  assertReportingRowReadBounds,
-  readReportingRowStream,
-  reportingRowClientMap,
-  runReportingRowProviderOperation,
-  selectReportingRowClient
-} from "../ledger/row-storage-provider-io.mjs";
-const ACCOUNT = /^[a-z0-9]{3,24}$/;
-const CONTAINER = /^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){2,62}$/;
-const VERSION_ID = /^[0-9A-Za-z:.+-]{1,64}$/;
-function statusOf(error) {
-  const status = Number(error?.statusCode);
-  return Number.isInteger(status) ? status : void 0;
-}
-function codeOf(error) {
-  const value = error?.code ?? error?.details?.errorCode;
-  return typeof value === "string" ? value : "";
-}
-const isConflict = (error) => statusOf(error) === 409 || statusOf(error) === 412 || codeOf(error) === "BlobAlreadyExists";
-const isMissing = (error) => statusOf(error) === 404 || statusOf(error) === 412;
-const isForbidden = (error) => statusOf(error) === 401 || statusOf(error) === 403;
-function versionOf(response) {
-  const id = response.versionId;
-  if (typeof id !== "string" || !VERSION_ID.test(id)) {
-    throw new ReportingRowStoreError(
-      "UNSAFE_BINDING",
-      "store returned no blob versionId; blob versioning must be enabled on the storage account so deletes are fenced to one write"
-    );
-  }
-  return id;
-}
-function servedVersion(response, versionId) {
-  return response.versionId === versionId;
-}
-function metadataOf(metadata) {
-  const result = {};
-  for (const [name, value] of Object.entries(metadata)) {
-    const identifier = name.replace(/[^A-Za-z0-9_]/g, "_");
-    result[/^[A-Za-z_]/.test(identifier) ? identifier : `_${identifier}`] = value;
-  }
-  return result;
-}
-function createAzureBlobReportingRowObjectProviderV1(options) {
-  if (!options || typeof options !== "object") {
-    throw new ReportingRowStoreError("INVALID_INPUT", "Azure Blob row provider options are required");
-  }
-  const clients = reportingRowClientMap(options.clients);
-  const isClient = (value) => !!value && typeof value === "object" && typeof value.getContainerClient === "function" && typeof value.accountName === "string";
-  if (options.client !== void 0 && !isClient(options.client) || [...clients.values()].some((client) => !isClient(client)) || options.client === void 0 && clients.size === 0) {
-    throw new ReportingRowStoreError("INVALID_INPUT", "inject an official BlobServiceClient as client or clients");
-  }
-  const validateLocation = (location) => {
-    assertReportingRowLocationKeys(location, ["account", "container"]);
-    if (!ACCOUNT.test(location.account)) {
-      throw new ReportingRowStoreError("INVALID_INPUT", "Azure storage account name is invalid");
-    }
-    if (!CONTAINER.test(location.container)) {
-      throw new ReportingRowStoreError("INVALID_INPUT", "Azure container name is invalid");
-    }
-  };
-  const containerFor = (input) => {
-    validateLocation(input.location);
-    const client = selectReportingRowClient(options.client, clients, input.credentialRef);
-    if (client.accountName !== input.location.account) {
-      throw new ReportingRowStoreError("UNSAFE_BINDING", "client does not belong to the binding account");
-    }
-    return client.getContainerClient(input.location.container);
-  };
-  const blobFor = (input) => {
-    if (typeof input.objectRef !== "string" || input.objectRef.length === 0 || input.objectRef.length > 1024) {
-      throw new ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
-    }
-    return containerFor(input).getBlockBlobClient(input.objectRef);
-  };
-  const pinned = (blob, nativeVersionRef) => typeof nativeVersionRef === "string" && VERSION_ID.test(nativeVersionRef) ? { blob: blob.withVersion(nativeVersionRef), versionId: nativeVersionRef } : null;
-  async function assertCreateOnlyEnforced(container, prefix, signal) {
-    const blob = container.getBlockBlobClient(`${prefix}/.adcp-probe/${randomUUID()}`);
-    const versionIds = [];
-    let written = false;
-    const upload = async (body) => {
-      const bytes = Buffer.from(body);
-      const response = await blob.upload(bytes, bytes.byteLength, {
-        conditions: { ifNoneMatch: "*" },
-        blobHTTPHeaders: { blobContentType: "application/x-ndjson", blobCacheControl: "no-store" },
-        abortSignal: signal
-      });
-      written = true;
-      if (response.versionId) versionIds.push(response.versionId);
-      versionOf(response);
-    };
-    try {
-      await upload('{"probe":1}\n');
-      try {
-        await upload('{"probe":2}\n');
-      } catch (error) {
-        if (isConflict(error)) return;
-        throw error;
-      }
-      throw new ReportingRowStoreError("UNSAFE_BINDING", "store ignores If-None-Match and replaces blobs");
-    } finally {
-      if (written && !signal.aborted) {
-        await blob.delete({ abortSignal: signal }).catch(() => void 0);
-        for (const versionId of versionIds) {
-          if (signal.aborted) break;
-          await blob.withVersion(versionId).delete({ abortSignal: signal }).catch(() => void 0);
-        }
-      }
-    }
-  }
-  return {
-    name: "azure_blob",
-    rangedReads: true,
-    validateLocation,
-    probe(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const container = containerFor(input);
-        let properties;
-        try {
-          properties = await container.getProperties({ abortSignal: context.signal });
-        } catch (error) {
-          if (statusOf(error) === 404) throw new ReportingRowStoreError("UNSAFE_BINDING", "container does not exist");
-          if (isForbidden(error)) throw new ReportingRowStoreError("UNSAFE_BINDING", "container is not accessible");
-          throw error;
-        }
-        if (properties.blobPublicAccess) {
-          throw new ReportingRowStoreError("UNSAFE_BINDING", "container allows anonymous read access");
-        }
-        await assertCreateOnlyEnforced(container, input.prefix, context.signal);
-      });
-    },
-    putIfAbsent(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const blob = blobFor(input);
-        const bytes = Buffer.from(input.bytes);
-        try {
-          const response = await blob.upload(bytes, bytes.byteLength, {
-            conditions: { ifNoneMatch: "*" },
-            blobHTTPHeaders: { blobContentType: input.contentType, blobCacheControl: "no-store" },
-            metadata: metadataOf(input.metadata),
-            abortSignal: context.signal
-          });
-          return { created: true, nativeVersionRef: versionOf(response) };
-        } catch (error) {
-          if (!isConflict(error)) throw error;
-        }
-        const existing = await blob.getProperties({ abortSignal: context.signal });
-        return { created: false, nativeVersionRef: versionOf(existing) };
-      });
-    },
-    get(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const blob = blobFor(input);
-        assertReportingRowReadBounds(input);
-        const target = pinned(blob, input.nativeVersionRef);
-        if (target === null) return null;
-        try {
-          if (input.range?.length === 0) {
-            const properties = await target.blob.getProperties({ abortSignal: context.signal });
-            if (!servedVersion(properties, target.versionId)) return null;
-            if (input.range.offset > Number(properties.contentLength ?? 0)) {
-              throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
-            }
-            return Buffer.alloc(0);
-          }
-          const response = await target.blob.download(input.range?.offset ?? 0, input.range?.length, {
-            abortSignal: context.signal
-          });
-          const body = response.readableStreamBody;
-          if (!body || typeof body[Symbol.asyncIterator] !== "function") {
-            throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "blob body is not a stream");
-          }
-          if (!servedVersion(response, target.versionId)) {
-            body.destroy?.();
-            return null;
-          }
-          if (typeof response.contentLength === "number" && response.contentLength > input.maxBytes) {
-            body.destroy?.();
-            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
-          }
-          return await readReportingRowStream(body, input.maxBytes, context.signal);
-        } catch (error) {
-          if (isMissing(error)) return null;
-          if (statusOf(error) === 400) return null;
-          if (statusOf(error) === 416 || codeOf(error) === "InvalidRange") {
-            throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
-          }
-          throw error;
-        }
-      });
-    },
-    stat(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const blob = blobFor(input);
-        const target = pinned(blob, input.nativeVersionRef);
-        if (target === null) return null;
-        try {
-          const properties = await target.blob.getProperties({ abortSignal: context.signal });
-          if (!servedVersion(properties, target.versionId)) return null;
-          const size = properties.contentLength;
-          if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0) {
-            throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "blob metadata is malformed");
-          }
-          return { nativeVersionRef: target.versionId, sizeBytes: size };
-        } catch (error) {
-          if (isMissing(error) || statusOf(error) === 400) return null;
-          throw error;
-        }
-      });
-    },
-    delete(input, context) {
-      return runReportingRowProviderOperation(context.signal, async () => {
-        const blob = blobFor(input);
-        const target = pinned(blob, input.nativeVersionRef);
-        if (target === null) return "absent";
-        const signal = context.signal;
-        try {
-          const recorded = await target.blob.getProperties({ abortSignal: signal });
-          if (recorded.versionId !== target.versionId) return "absent";
-        } catch (error) {
-          if (isMissing(error) || statusOf(error) === 400) return "absent";
-          throw error;
-        }
-        let deletedCurrent = false;
-        try {
-          const current = await blob.getProperties({ abortSignal: signal });
-          if (current.versionId === target.versionId && current.etag) {
-            await blob.delete({ conditions: { ifMatch: current.etag }, abortSignal: signal });
-            deletedCurrent = true;
-          }
-        } catch (error) {
-          if (!isMissing(error)) throw error;
-        }
-        try {
-          await target.blob.delete({ abortSignal: signal });
-          return "deleted";
-        } catch (error) {
-          if (isMissing(error) || statusOf(error) === 400) return deletedCurrent ? "deleted" : "absent";
-          throw error;
-        }
-      });
-    }
-  };
-}
-export {
-  createAzureBlobReportingRowObjectProviderV1
-};

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

@@ -1,246 +0,0 @@
-import type { PostgresReportingLedgerStore, ReportingLedgerRevisionMetadataV1, ReportingPgPool } from '../ledger/index.mjs';
-/**
- * BigQuery warehouse sink for Reliable Reporting (shared SDK persistence spec,
- * adcontextprotocol/adcp#7996 §3.6).
- *
- * The sink is a derived, non-authoritative copy of committed revisions. It
- * follows the ledger's host change feed, reads every revision's rows through
- * the store's verified reader, maps them to the adopter's columns, and loads
- * one batch per tick with a deterministic job ID. It is never read for
- * serving or verification, so its tables, columns, partitioning and retention
- * are the adopter's.
- *
- * Exactly-once loading: a batch (change-feed range, revision list, job IDs) is
- * 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.
- *
- * @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.
- *
- * @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;
-        location?: string;
-    }): {
-        table(tableId: string): {
-            load(source: string, metadata: Record<string, unknown>): Promise<unknown>;
-        };
-    };
-    job(jobId: string, options?: {
-        projectId?: string;
-        location?: string;
-    }): {
-        getMetadata(): Promise<unknown>;
-        /** @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: {
-        query: string;
-        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'> & {
-        /**
-         * The sink ignores the result, so wrappers written when this resolved
-         * `void` keep compiling.
-         */
-        saveFeedConsumerCursor(name: string, cursor: string, options?: {
-            refreshUnchanged?: boolean;
-        }): Promise<unknown>;
-    } & /** Needed only by `reset()`; custom store wrappers that predate it keep compiling. */ Partial<Pick<PostgresReportingLedgerStore, 'removeFeedConsumer'>>;
-    /** PostgreSQL pool holding `REPORTING_WAREHOUSE_SINK_MIGRATION`. */
-    db: Pick<ReportingPgPool, 'query'>;
-    /** Host-constructed official BigQuery client. */
-    bigquery: ReportingBigQueryClientV1;
-    /**
-     * Stable sink and consumer name. All replicas sharing it must use the same
-     * ledger database, feed scope, destination, location and row mapping. Use
-     * a new name when that configuration changes. Names must also be unique
-     * across independent ledgers sharing a BigQuery project.
-     */
-    name: string;
-    projectId?: string;
-    datasetId: string;
-    rowsTableId: string;
-    revisionsTableId: string;
-    /**
-     * 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` (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>;
-    /** Revisions per batch. Default 200. */
-    maxRevisionsPerBatch?: number;
-    /**
-     * @deprecated Has no effect, and the sink warns when it is set. The official
-     * client submits a local-file load by uploading a job resource whose
-     * `configuration.load` is built from the load options, and offers no way to
-     * set `configuration.labels`; BigQuery silently drops `labels` found inside
-     * `configuration.load`. For cost attribution, filter
-     * `INFORMATION_SCHEMA.JOBS` on `destination_table` or on the `adcp_rr_`
-     * job ID prefix instead.
-     */
-    labels?: Readonly<Record<string, string>>;
-    /**
-     * 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
-     * revision changes were selected. Idle ticks can advance past other feed changes.
-     * An overlapping run that loses its plan or cursor claim rejects. Retry
-     * `runOnce()` to resume the current durable plan or committed cursor.
-     *
-     * `missing` lists revision IDs the change feed announced that no longer
-     * exist in the ledger because their period was retired before this batch
-     * ran. That is a data-loss signal: the sink fell behind retention (it was
-     * down longer than `maxFeedHoldDays`, so retention stopped waiting for it)
-     * and the warehouse lacks those revisions. Backfill them from another source
-     * or accept the gap. The cursor still advances so the sink is not stuck.
-     * Alert on a non-empty `missing`. After a crash-and-replay of a planned
-     * batch, a listed revision may already have been loaded by the first attempt.
-     */
-    runOnce(options?: {
-        signal?: AbortSignal;
-    }): Promise<{
-        idle: boolean;
-        revisions: number;
-        rows: number;
-        missing: string[];
-    }>;
-    /**
-     * Clear the sink's saved state so the next `runOnce()` starts again from the
-     * oldest retained change, and unregister its feed consumer so the old
-     * checkpoint stops holding back retention. This is the way out of a sink
-     * that keeps rejecting with `CURSOR_EXPIRED`: a brand-new sink whose first
-     * read lost a startup race with pruning, or a sink that fell behind
-     * retention and has been resynchronized from current revisions. Stop every
-     * worker using this sink name first.
-     *
-     * It refuses while a batch plan is retained, because that batch's load jobs
-     * may already have succeeded; pass `discardRetainedPlan: true` once you have
-     * reconciled it against BigQuery. The warehouse is not touched: a sink that
-     * already loaded history will load the retained revisions again, so empty
-     * 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. 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`.
-     * Resolves with whether a saved sink state existed.
-     */
-    reset(options?: {
-        discardRetainedPlan?: boolean;
-    }): Promise<{
-        cleared: boolean;
-    }>;
-    /** DDL for the default rows and revisions tables (partitioned and clustered). */
-    readonly defaultTablesSql: string;
-    /** 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;
-/**
- * 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;
-    datasetId: string;
-    rowsTableId: string;
-    revisionsTableId: string;
-}
-/**
- * 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;
-}): string;
-export {};