@adcp/sdk 15.4.0 → 15.6.0

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

@@ -0,0 +1,341 @@
+import { createHash } from "crypto";
+import { promises as fs } from "fs";
+import { tmpdir } from "os";
+import * as path from "path";
+const REPORTING_WAREHOUSE_SINK_MIGRATION = `
+CREATE TABLE IF NOT EXISTS adcp_reporting_warehouse_sinks (
+  sink_name TEXT PRIMARY KEY CHECK (sink_name ~ '^[A-Za-z0-9_.:-]{1,128}$'),
+  committed_cursor TEXT,
+  planned_from_cursor TEXT,
+  planned_to_cursor TEXT,
+  planned_revisions JSONB,
+  planned_rows_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_rows_attempt >= 0),
+  planned_revisions_attempt INTEGER NOT NULL DEFAULT 0 CHECK (planned_revisions_attempt >= 0),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT clock_timestamp(),
+  CHECK ((planned_to_cursor IS NULL) = (planned_revisions IS NULL))
+);
+`.trim();
+const PROJECT = /^[a-z][a-z0-9-]{4,61}[a-z0-9]$/;
+const DATASET_OR_TABLE = /^[A-Za-z_][A-Za-z0-9_]{0,1023}$/;
+const NAME = /^[A-Za-z0-9_.:-]{1,128}$/;
+function createBigQueryReportingWarehouseSinkV1(options) {
+  if (!NAME.test(options.name)) throw new TypeError("Warehouse sink name must be a bounded non-secret identifier");
+  if (options.projectId !== void 0 && !PROJECT.test(options.projectId)) {
+    throw new TypeError("BigQuery projectId is invalid");
+  }
+  for (const [label, value] of [
+    ["datasetId", options.datasetId],
+    ["rowsTableId", options.rowsTableId],
+    ["revisionsTableId", options.revisionsTableId]
+  ]) {
+    if (!DATASET_OR_TABLE.test(value)) throw new TypeError(`BigQuery ${label} is invalid`);
+  }
+  const loadTimeout = options.loadTimeoutMilliseconds ?? 6e5;
+  if (!Number.isSafeInteger(loadTimeout) || loadTimeout < 1e3 || loadTimeout > 6 * 36e5) {
+    throw new RangeError("loadTimeoutMilliseconds must be between 1 second and 6 hours");
+  }
+  const maxRevisions = options.maxRevisionsPerBatch ?? 200;
+  if (!Number.isSafeInteger(maxRevisions) || maxRevisions < 1 || maxRevisions > 1e4) {
+    throw new RangeError("maxRevisionsPerBatch must be between 1 and 10000");
+  }
+  const tables = {
+    projectId: options.projectId,
+    datasetId: options.datasetId,
+    rowsTableId: options.rowsTableId,
+    revisionsTableId: options.revisionsTableId
+  };
+  const dataset = options.bigquery.dataset(options.datasetId, {
+    ...options.projectId ? { projectId: options.projectId } : {},
+    ...options.location ? { location: options.location } : {}
+  });
+  async function loadOnce(tableId, jobId, lines, signal) {
+    signal?.throwIfAborted();
+    const directory = await fs.mkdtemp(path.join(tmpdir(), "adcp-warehouse-"));
+    const file = path.join(directory, `${jobId}.ndjson`);
+    try {
+      await fs.writeFile(file, lines.length ? lines.join("\n") + "\n" : "");
+      try {
+        await withinDeadline(
+          () => dataset.table(tableId).load(file, {
+            jobId,
+            sourceFormat: "NEWLINE_DELIMITED_JSON",
+            writeDisposition: "WRITE_APPEND",
+            jobTimeoutMs: String(loadTimeout),
+            ...options.location ? { location: options.location } : {},
+            ...options.labels ? { labels: { ...options.labels } } : {}
+          }),
+          loadTimeout,
+          signal
+        );
+      } catch (error) {
+        if (!isAlreadyExists(error)) throw error;
+        const metadata = await withinDeadline(
+          () => options.bigquery.job(jobId, options.location ? { location: options.location } : void 0).getMetadata(),
+          loadTimeout,
+          signal
+        );
+        assertJobSucceeded(metadata);
+      }
+    } finally {
+      await fs.rm(directory, { recursive: true, force: true });
+    }
+  }
+  return {
+    defaultTablesSql: reportingWarehouseDefaultTablesSqlV1(tables),
+    currentRowsViewSql: reportingWarehouseCurrentRowsViewSqlV1(tables),
+    async runOnce(runOptions = {}) {
+      const signal = runOptions.signal;
+      await options.db.query(
+        `INSERT INTO adcp_reporting_warehouse_sinks (sink_name) VALUES ($1) ON CONFLICT DO NOTHING`,
+        [options.name]
+      );
+      const state = (await options.db.query(
+        `SELECT committed_cursor, planned_from_cursor, planned_to_cursor, planned_revisions,
+                  planned_rows_attempt, planned_revisions_attempt
+             FROM adcp_reporting_warehouse_sinks WHERE sink_name = $1`,
+        [options.name]
+      )).rows[0];
+      let plan = state.planned_to_cursor && state.planned_revisions ? {
+        from: state.planned_from_cursor,
+        to: state.planned_to_cursor,
+        revisions: state.planned_revisions,
+        rowsAttempt: state.planned_rows_attempt,
+        revisionsAttempt: state.planned_revisions_attempt
+      } : void 0;
+      if (!plan) {
+        const page = await options.store.changesAfter({
+          ...state.committed_cursor ? { cursor: state.committed_cursor } : {},
+          ...options.account_id ? { account_id: options.account_id } : {},
+          kinds: ["revision"],
+          limit: maxRevisions
+        });
+        if (page.records.length === 0) {
+          if (page.cursor !== state.committed_cursor) await commit(page.cursor);
+          return { idle: true, revisions: 0, rows: 0, missing: [] };
+        }
+        plan = {
+          from: state.committed_cursor,
+          to: page.cursor,
+          revisions: page.records.map((record) => ({ id: record.record_id, account_id: record.account_id })),
+          rowsAttempt: 0,
+          revisionsAttempt: 0
+        };
+        await options.db.query(
+          `UPDATE adcp_reporting_warehouse_sinks
+              SET planned_from_cursor = $2, planned_to_cursor = $3, planned_revisions = $4::jsonb,
+                  planned_rows_attempt = 0, planned_revisions_attempt = 0, updated_at = clock_timestamp()
+            WHERE sink_name = $1`,
+          [options.name, plan.from, plan.to, JSON.stringify(plan.revisions)]
+        );
+      }
+      const rowLines = [];
+      const revisionLines = [];
+      const missing = [];
+      for (const planned of plan.revisions) {
+        signal?.throwIfAborted();
+        const revision = await options.store.getRevisionMetadata(planned.id, planned.account_id);
+        if (!revision) {
+          missing.push(planned.id);
+          continue;
+        }
+        const periodDate = sourceLocalDate(
+          revision.wireRevision.period?.start,
+          revision.wireRevision.period?.source_timezone
+        );
+        const base = {
+          reporting_revision_id: revision.reporting_revision_id,
+          reporting_obligation_id: revision.reporting_obligation_id,
+          account_id: planned.account_id,
+          revision_number: revision.revisionNumber,
+          finality: revision.finality,
+          period_date: periodDate
+        };
+        for (let offset = 0; offset < revision.binding.rowCount; ) {
+          const page = await options.store.readRevisionRows({
+            reporting_revision_id: revision.reporting_revision_id,
+            account_id: planned.account_id,
+            offset,
+            limit: 5e3,
+            ...signal ? { signal } : {}
+          });
+          if (!page || page.rows.length === 0) throw new Error("Reporting revision rows ended early");
+          page.rows.forEach((row, index) => {
+            const ordinal = offset + index;
+            const mapped = options.mapRow ? options.mapRow(row, { revision, ordinal }) : { row };
+            rowLines.push(JSON.stringify({ ...mapped, ...base, ordinal }));
+          });
+          offset += page.rows.length;
+        }
+        revisionLines.push(
+          JSON.stringify({
+            ...base,
+            supersedes_reporting_revision_id: revision.supersedes_reporting_revision_id ?? null,
+            period_start: revision.wireRevision.period?.start ?? null,
+            period_end: revision.wireRevision.period?.end ?? null,
+            source_timezone: revision.wireRevision.period?.source_timezone ?? null,
+            observed_at: revision.observedAt,
+            data_through: revision.dataThrough,
+            revision_content_sha256: revision.binding.sha256,
+            row_count: revision.binding.rowCount,
+            control_totals: revision.wireRevision.control_totals ?? []
+          })
+        );
+      }
+      const baseJobId = reportingWarehouseJobIdV1(options.name, plan.from, plan.to);
+      const suffix = (attempt) => attempt ? `_a${attempt}` : "";
+      const steps = [
+        { table: options.rowsTableId, kind: "rows", lines: rowLines, attempt: plan.rowsAttempt },
+        { table: options.revisionsTableId, kind: "revs", lines: revisionLines, attempt: plan.revisionsAttempt }
+      ];
+      for (const step of steps) {
+        if (!step.lines.length) continue;
+        try {
+          await loadOnce(step.table, `${baseJobId}_${step.kind}${suffix(step.attempt)}`, [...step.lines], signal);
+        } catch (error) {
+          if (isFinishedWithError(error)) {
+            const column = step.kind === "rows" ? "planned_rows_attempt" : "planned_revisions_attempt";
+            await options.db.query(
+              `UPDATE adcp_reporting_warehouse_sinks SET ${column} = ${column} + 1,
+                      updated_at = clock_timestamp() WHERE sink_name = $1`,
+              [options.name]
+            );
+          }
+          throw error;
+        }
+      }
+      await commit(plan.to);
+      return { idle: false, revisions: revisionLines.length, rows: rowLines.length, missing };
+    }
+  };
+  async function commit(cursor) {
+    await options.db.query(
+      `UPDATE adcp_reporting_warehouse_sinks
+          SET committed_cursor = $2, planned_from_cursor = NULL, planned_to_cursor = NULL,
+              planned_revisions = NULL, planned_rows_attempt = 0, planned_revisions_attempt = 0,
+              updated_at = clock_timestamp()
+        WHERE sink_name = $1`,
+      [options.name, cursor]
+    );
+    await options.store.saveFeedConsumerCursor(options.name, cursor);
+  }
+}
+function reportingWarehouseJobIdV1(name, from, to) {
+  return `adcp_rr_${createHash("sha256").update(JSON.stringify([name, from, to])).digest("hex").slice(0, 40)}`;
+}
+function qualified(tables, table) {
+  return `\`${tables.projectId ? `${tables.projectId}.` : ""}${tables.datasetId}.${table}\``;
+}
+function reportingWarehouseDefaultTablesSqlV1(tables) {
+  return `
+CREATE TABLE IF NOT EXISTS ${qualified(tables, tables.rowsTableId)} (
+  reporting_revision_id STRING NOT NULL,
+  reporting_obligation_id STRING NOT NULL,
+  account_id STRING NOT NULL,
+  revision_number INT64 NOT NULL,
+  finality STRING NOT NULL,
+  period_date DATE,
+  ordinal INT64 NOT NULL,
+  row JSON
+)
+PARTITION BY period_date
+CLUSTER BY account_id, reporting_revision_id;
+
+CREATE TABLE IF NOT EXISTS ${qualified(tables, tables.revisionsTableId)} (
+  reporting_revision_id STRING NOT NULL,
+  reporting_obligation_id STRING NOT NULL,
+  account_id STRING NOT NULL,
+  revision_number INT64 NOT NULL,
+  finality STRING NOT NULL,
+  period_date DATE,
+  supersedes_reporting_revision_id STRING,
+  period_start TIMESTAMP,
+  period_end TIMESTAMP,
+  source_timezone STRING,
+  observed_at TIMESTAMP,
+  data_through TIMESTAMP,
+  revision_content_sha256 STRING NOT NULL,
+  row_count INT64 NOT NULL,
+  control_totals JSON
+)
+PARTITION BY period_date
+CLUSTER BY account_id, reporting_obligation_id;`.trim();
+}
+function reportingWarehouseCurrentRowsViewSqlV1(tables) {
+  const view = tables.viewId ?? "current_rows";
+  if (!DATASET_OR_TABLE.test(view)) throw new TypeError("BigQuery viewId is invalid");
+  return `
+CREATE OR REPLACE VIEW ${qualified(tables, view)} AS
+SELECT row_data.*
+  FROM ${qualified(tables, tables.rowsTableId)} AS row_data
+  JOIN (
+    SELECT reporting_obligation_id,
+           ARRAY_AGG(reporting_revision_id ORDER BY revision_number DESC LIMIT 1)[OFFSET(0)] AS reporting_revision_id
+      FROM ${qualified(tables, tables.revisionsTableId)}
+     GROUP BY reporting_obligation_id
+  ) AS current_revision
+ USING (reporting_obligation_id, reporting_revision_id);`.trim();
+}
+function sourceLocalDate(start, timeZone) {
+  if (!start) return null;
+  const instant = new Date(start);
+  if (Number.isNaN(instant.getTime())) return null;
+  try {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+      timeZone: timeZone ?? "UTC",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit"
+    }).format(instant);
+    return parts;
+  } catch {
+    return instant.toISOString().slice(0, 10);
+  }
+}
+async function withinDeadline(operation, milliseconds, signal) {
+  signal?.throwIfAborted();
+  let timer;
+  let onAbort;
+  try {
+    return await Promise.race([
+      operation(),
+      new Promise((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("BigQuery call exceeded its deadline; the batch will be retried")),
+          milliseconds
+        );
+        if (signal) {
+          onAbort = () => reject(signal.reason ?? new Error("aborted"));
+          signal.addEventListener("abort", onAbort, { once: true });
+        }
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+function isAlreadyExists(error) {
+  const record = error;
+  return record?.code === 409 || !!record?.errors?.some((entry) => entry.reason === "duplicate");
+}
+function isFinishedWithError(error) {
+  return error?.adcpJobFailed === true;
+}
+function assertJobSucceeded(metadata) {
+  const record = Array.isArray(metadata) ? metadata[0] : metadata;
+  if (record?.status?.state !== "DONE") {
+    throw new Error("A BigQuery load job for this batch is still running; retry later");
+  }
+  if (record.status.errorResult) {
+    const failure = new Error("A BigQuery load job for this batch failed; it will be retried as a new attempt");
+    Object.defineProperty(failure, "adcpJobFailed", { value: true });
+    throw failure;
+  }
+}
+export {
+  REPORTING_WAREHOUSE_SINK_MIGRATION,
+  createBigQueryReportingWarehouseSinkV1,
+  reportingWarehouseCurrentRowsViewSqlV1,
+  reportingWarehouseDefaultTablesSqlV1,
+  reportingWarehouseJobIdV1
+};

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

@@ -5,3 +5,5 @@ export { createGcsReportingResourceReaderV1, createGcsReportingReferenceResolver
 export type { GcsReportingReadScopeV1, GcsReportingReadAuthorizationV1, GcsReportingReaderOptionsV1 } from './reader.mjs';
 export { createGcsReportingManagedDeliveryAdapterV1 } from './adapter.mjs';
 export type { CreateGcsReportingManagedDeliveryAdapterOptionsV1 } from './adapter.mjs';
+export { createGcsReportingRowObjectProviderV1 } from './row-provider.mjs';
+export type { CreateGcsReportingRowObjectProviderOptionsV1 } from './row-provider.mjs';

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

@@ -5,3 +5,5 @@ export { createGcsReportingResourceReaderV1, createGcsReportingReferenceResolver
 export type { GcsReportingReadScopeV1, GcsReportingReadAuthorizationV1, GcsReportingReaderOptionsV1 } from './reader';
 export { createGcsReportingManagedDeliveryAdapterV1 } from './adapter';
 export type { CreateGcsReportingManagedDeliveryAdapterOptionsV1 } from './adapter';
+export { createGcsReportingRowObjectProviderV1 } from './row-provider';
+export type { CreateGcsReportingRowObjectProviderOptionsV1 } from './row-provider';

package/dist/lib/reporting/gcs/index.js

@@ -23,6 +23,7 @@ __export(gcs_exports, {
   createGcsReportingObjectFenceV1: () => import_fence.createGcsReportingObjectFenceV1,
   createGcsReportingReferenceResolverV1: () => import_reader.createGcsReportingReferenceResolverV1,
   createGcsReportingResourceReaderV1: () => import_reader.createGcsReportingResourceReaderV1,
+  createGcsReportingRowObjectProviderV1: () => import_row_provider.createGcsReportingRowObjectProviderV1,
   isReportingGcsFenceError: () => import_errors.isReportingGcsFenceError
 });
 module.exports = __toCommonJS(gcs_exports);
@@ -30,6 +31,7 @@ var import_fence = require('./fence.js');
 var import_errors = require('./errors.js');
 var import_reader = require('./reader.js');
 var import_adapter = require('./adapter.js');
+var import_row_provider = require('./row-provider.js');
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ReportingGcsFenceError,
@@ -37,5 +39,6 @@ var import_adapter = require('./adapter.js');
   createGcsReportingObjectFenceV1,
   createGcsReportingReferenceResolverV1,
   createGcsReportingResourceReaderV1,
+  createGcsReportingRowObjectProviderV1,
   isReportingGcsFenceError
 });

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

@@ -2,11 +2,13 @@ import { createGcsReportingObjectFenceV1 } from "./fence.mjs";
 import { ReportingGcsFenceError, isReportingGcsFenceError } from "./errors.mjs";
 import { createGcsReportingResourceReaderV1, createGcsReportingReferenceResolverV1 } from "./reader.mjs";
 import { createGcsReportingManagedDeliveryAdapterV1 } from "./adapter.mjs";
+import { createGcsReportingRowObjectProviderV1 } from "./row-provider.mjs";
 export {
   ReportingGcsFenceError,
   createGcsReportingManagedDeliveryAdapterV1,
   createGcsReportingObjectFenceV1,
   createGcsReportingReferenceResolverV1,
   createGcsReportingResourceReaderV1,
+  createGcsReportingRowObjectProviderV1,
   isReportingGcsFenceError
 };

package/dist/lib/reporting/gcs/row-provider.d.mts

@@ -0,0 +1,32 @@
+import type { BucketMetadata, Storage } from '@google-cloud/storage';
+import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object.mjs';
+export interface CreateGcsReportingRowObjectProviderOptionsV1 {
+    /** Official client used by bindings without a `credentialRef`. */
+    storage?: Storage;
+    /**
+     * Official clients keyed by `credentialRef`. This map is the closed set of
+     * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
+     */
+    clients?: Readonly<Record<string, Storage>>;
+}
+/**
+ * Row-binding bucket policy (shared persistence spec §3.4). Unlike the Managed
+ * Delivery probe, versioning, soft delete and retention are allowed as
+ * backstops. Refused: buckets without uniform bucket-level access or enforced
+ * public access prevention, and any lifecycle `Delete` rule that can match a
+ * live object under the binding prefix (no prefix filter, or a prefix that
+ * overlaps it). Rules limited to noncurrent versions are allowed.
+ */
+export declare function assertGcsReportingRowBucketPolicyV1(metadata: BucketMetadata, prefix: string): void;
+/**
+ * Google Cloud Storage row-object provider (`@adcp/sdk/reporting/gcs`).
+ *
+ * Inject official `Storage` clients with host-owned, keyless credentials.
+ * Bindings use `location: { bucket }`; `credentialRef` selects an injected
+ * client. Writes are single-request uploads with `ifGenerationMatch: 0`, so an
+ * existing object is never replaced; the recorded native version is the
+ * object generation, and reads and deletes pin it. Objects are stored without
+ * `Content-Encoding`, and reads request raw stored bytes, so GCS never
+ * transcodes them.
+ */
+export declare function createGcsReportingRowObjectProviderV1(options: CreateGcsReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

package/dist/lib/reporting/gcs/row-provider.d.ts

@@ -0,0 +1,32 @@
+import type { BucketMetadata, Storage } from '@google-cloud/storage';
+import type { ReportingRowObjectProviderV1 } from '../ledger/row-storage-object';
+export interface CreateGcsReportingRowObjectProviderOptionsV1 {
+    /** Official client used by bindings without a `credentialRef`. */
+    storage?: Storage;
+    /**
+     * Official clients keyed by `credentialRef`. This map is the closed set of
+     * references a binding may name; an unknown reference fails `UNSAFE_BINDING`.
+     */
+    clients?: Readonly<Record<string, Storage>>;
+}
+/**
+ * Row-binding bucket policy (shared persistence spec §3.4). Unlike the Managed
+ * Delivery probe, versioning, soft delete and retention are allowed as
+ * backstops. Refused: buckets without uniform bucket-level access or enforced
+ * public access prevention, and any lifecycle `Delete` rule that can match a
+ * live object under the binding prefix (no prefix filter, or a prefix that
+ * overlaps it). Rules limited to noncurrent versions are allowed.
+ */
+export declare function assertGcsReportingRowBucketPolicyV1(metadata: BucketMetadata, prefix: string): void;
+/**
+ * Google Cloud Storage row-object provider (`@adcp/sdk/reporting/gcs`).
+ *
+ * Inject official `Storage` clients with host-owned, keyless credentials.
+ * Bindings use `location: { bucket }`; `credentialRef` selects an injected
+ * client. Writes are single-request uploads with `ifGenerationMatch: 0`, so an
+ * existing object is never replaced; the recorded native version is the
+ * object generation, and reads and deletes pin it. Objects are stored without
+ * `Content-Encoding`, and reads request raw stored bytes, so GCS never
+ * transcodes them.
+ */
+export declare function createGcsReportingRowObjectProviderV1(options: CreateGcsReportingRowObjectProviderOptionsV1): ReportingRowObjectProviderV1;

package/dist/lib/reporting/gcs/row-provider.js

@@ -0,0 +1,205 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var row_provider_exports = {};
+__export(row_provider_exports, {
+  assertGcsReportingRowBucketPolicyV1: () => assertGcsReportingRowBucketPolicyV1,
+  createGcsReportingRowObjectProviderV1: () => createGcsReportingRowObjectProviderV1
+});
+module.exports = __toCommonJS(row_provider_exports);
+var import_node_crypto = require("node:crypto");
+var import_row_storage_errors = require('../ledger/row-storage-errors.js');
+var import_row_storage_provider_io = require('../ledger/row-storage-provider-io.js');
+const BUCKET = /^[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]$/;
+const GENERATION = /^[1-9][0-9]{0,15}$/;
+const NONCURRENT_ONLY_CONDITIONS = ["numNewerVersions", "daysSinceNoncurrentTime", "noncurrentTimeBefore"];
+function status(error) {
+  if (!error || typeof error !== "object" || !("code" in error)) return void 0;
+  const code = Number(error.code);
+  return Number.isInteger(code) ? code : void 0;
+}
+function generationOf(metadata) {
+  const generation = metadata?.generation === void 0 ? "" : String(metadata.generation);
+  if (!GENERATION.test(generation) || !Number.isSafeInteger(Number(generation))) {
+    throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE", "object generation is missing");
+  }
+  return generation;
+}
+function pinnedGeneration(nativeVersion) {
+  return typeof nativeVersion === "string" && GENERATION.test(nativeVersion) && Number.isSafeInteger(Number(nativeVersion)) ? nativeVersion : null;
+}
+function assertGcsReportingRowBucketPolicyV1(metadata, prefix) {
+  if (!metadata || typeof metadata !== "object") {
+    throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket policy is unavailable");
+  }
+  if (metadata.iamConfiguration?.uniformBucketLevelAccess?.enabled !== true) {
+    throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket must enable uniform bucket-level access");
+  }
+  if (metadata.iamConfiguration?.publicAccessPrevention !== "enforced") {
+    throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket must enforce public access prevention");
+  }
+  for (const rule of metadata.lifecycle?.rule ?? []) {
+    if (rule?.action?.type !== "Delete") continue;
+    const condition = rule.condition ?? {};
+    if (condition.isLive === false) continue;
+    if (NONCURRENT_ONLY_CONDITIONS.some((name) => condition[name] !== void 0 && condition[name] !== null)) continue;
+    const prefixes = condition.matchesPrefix ?? [];
+    if (prefixes.length === 0 || prefixes.some((filter) => (0, import_row_storage_provider_io.reportingRowPrefixFilterOverlaps)(filter, prefix))) {
+      throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "a bucket lifecycle rule can delete live row objects");
+    }
+  }
+}
+function createGcsReportingRowObjectProviderV1(options) {
+  if (!options || typeof options !== "object") {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "GCS row provider options are required");
+  }
+  const clients = (0, import_row_storage_provider_io.reportingRowClientMap)(options.clients);
+  const isStorage = (value) => !!value && typeof value === "object" && typeof value.bucket === "function";
+  if (options.storage !== void 0 && !isStorage(options.storage) || [...clients.values()].some((client) => !isStorage(client)) || options.storage === void 0 && clients.size === 0) {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "inject an official Storage client as storage or clients");
+  }
+  const validateLocation = (location) => {
+    (0, import_row_storage_provider_io.assertReportingRowLocationKeys)(location, ["bucket"]);
+    if (!BUCKET.test(location.bucket) || location.bucket.includes("..")) {
+      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "GCS bucket name is invalid");
+    }
+  };
+  const bucketFor = (input) => {
+    validateLocation(input.location);
+    return (0, import_row_storage_provider_io.selectReportingRowClient)(options.storage, clients, input.credentialRef).bucket(input.location.bucket);
+  };
+  const assertKey = (key) => {
+    if (typeof key !== "string" || key.length === 0 || Buffer.byteLength(key) > 1024) {
+      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "object key is invalid");
+    }
+  };
+  return {
+    name: "gcs",
+    rangedReads: true,
+    validateLocation,
+    probe(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        let metadata;
+        try {
+          [metadata] = await bucket.getMetadata();
+        } catch (error) {
+          const code = status(error);
+          if (code === 404) throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket does not exist");
+          if (code === 401 || code === 403) {
+            throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "bucket policy cannot be read with this client");
+          }
+          throw error;
+        }
+        assertGcsReportingRowBucketPolicyV1(metadata, input.prefix);
+      });
+    },
+    putIfAbsent(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        const file = bucket.file(input.key);
+        try {
+          const bytes = Buffer.from(input.bytes);
+          await file.save(bytes, {
+            resumable: false,
+            gzip: false,
+            // GCS verifies the declared MD5 before creating the object, so a corrupted upload
+            // is refused server-side. Client-side validation is off because on mismatch the
+            // client deletes the key without a generation precondition.
+            validation: false,
+            contentType: input.contentType,
+            metadata: {
+              contentType: input.contentType,
+              md5Hash: (0, import_node_crypto.createHash)("md5").update(bytes).digest("base64"),
+              cacheControl: "no-store",
+              metadata: { ...input.metadata }
+            },
+            preconditionOpts: { ifGenerationMatch: 0 }
+          });
+        } catch (error) {
+          if (status(error) !== 412) throw error;
+          context.signal.throwIfAborted();
+          const [existing] = await bucket.file(input.key).getMetadata();
+          return { created: false, nativeVersion: generationOf(existing) };
+        }
+        if (file.metadata?.generation !== void 0) {
+          return { created: true, nativeVersion: generationOf(file.metadata) };
+        }
+        const [created] = await file.getMetadata();
+        return { created: true, nativeVersion: generationOf(created) };
+      });
+    },
+    get(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        (0, import_row_storage_provider_io.assertReportingRowReadBounds)(input);
+        const generation = pinnedGeneration(input.nativeVersion);
+        if (generation === null) return null;
+        const file = bucket.file(input.key, { generation });
+        try {
+          if (input.range?.length === 0) {
+            const [metadata] = await file.getMetadata();
+            if (input.range.offset > Number(metadata.size)) {
+              throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+            }
+            return Buffer.alloc(0);
+          }
+          const stream = file.createReadStream({
+            // The client always sends `Accept-Encoding: gzip`; with `decompress: false`
+            // neither GCS nor the client transcodes, so these are the stored bytes.
+            decompress: false,
+            // Digests recorded in PostgreSQL verify every byte returned.
+            validation: false,
+            ...input.range ? { start: input.range.offset, end: input.range.offset + input.range.length - 1 } : {}
+          });
+          return await (0, import_row_storage_provider_io.readReportingRowStream)(stream, input.maxBytes, context.signal);
+        } catch (error) {
+          const code = status(error);
+          if (code === 404) return null;
+          if (code === 416) {
+            throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+          }
+          throw error;
+        }
+      });
+    },
+    delete(input, context) {
+      return (0, import_row_storage_provider_io.runReportingRowProviderOperation)(context.signal, async () => {
+        const bucket = bucketFor(input);
+        assertKey(input.key);
+        const generation = pinnedGeneration(input.nativeVersion);
+        if (generation === null) return "absent";
+        try {
+          await bucket.file(input.key, { generation }).delete();
+          return "deleted";
+        } catch (error) {
+          const code = status(error);
+          if (code === 404 || code === 412) return "absent";
+          throw error;
+        }
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertGcsReportingRowBucketPolicyV1,
+  createGcsReportingRowObjectProviderV1
+});