@adcp/sdk 15.3.0 → 15.5.0

package/dist/lib/reporting/ledger/row-storage-object.mjs

@@ -0,0 +1,239 @@
+import { createHash, randomUUID } from "crypto";
+import { promises as fs } from "fs";
+import * as path from "path";
+import { canonicalize } from "../../utils/jcs.mjs";
+import { ReportingRowStoreError } from "./row-storage-errors.mjs";
+const REPORTING_ROW_KEY_PLACEHOLDERS = Object.freeze([
+  "prefix",
+  "namespace_key",
+  "account_key",
+  "period_date",
+  "finality",
+  "revision_key",
+  "content_sha256",
+  "chunk_index"
+]);
+const REPORTING_ROW_DEFAULT_KEY_TEMPLATE = "{prefix}/{namespace_key}/{account_key}/{period_date}/{finality}/{revision_key}/{content_sha256}/{chunk_index}";
+const PREFIX = /^[A-Za-z0-9_.=-]+(?:\/[A-Za-z0-9_.=-]+)*$/;
+const KEY = /^[A-Za-z0-9_.=-]+(?:\/[A-Za-z0-9_.=-]+)*$/;
+const PLACEHOLDER = /\{([a-z0-9_]+)\}/g;
+function assertReportingRowKeyTemplateV1(template) {
+  if (!template.startsWith("{prefix}/{namespace_key}/")) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "key templates must begin with {prefix}/{namespace_key}/");
+  }
+  for (const required of ["{content_sha256}", "{chunk_index}"]) {
+    if (!template.includes(required)) {
+      throw new ReportingRowStoreError("INVALID_INPUT", `key templates must include ${required}`);
+    }
+  }
+  const unknown = [...template.matchAll(PLACEHOLDER)].map((match) => match[1]).filter((name) => !REPORTING_ROW_KEY_PLACEHOLDERS.includes(name));
+  if (unknown.length > 0) {
+    throw new ReportingRowStoreError("INVALID_INPUT", `unknown key template placeholders: ${unknown.join(", ")}`);
+  }
+  const literal = template.replace(PLACEHOLDER, "x");
+  if (!KEY.test(literal) || literal.split("/").some((segment) => segment === "." || segment === "..")) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "key template contains unsafe characters or segments");
+  }
+}
+function assertReportingRowPrefixV1(prefix) {
+  if (!PREFIX.test(prefix) || prefix.length > 512 || prefix.split("/").some((segment) => segment === "." || segment === "..")) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "row binding prefix is invalid");
+  }
+}
+function reportingRowAccountKeyV1(namespaceKey, accountId) {
+  return sha256Hex(canonicalize(["adcp.account_key.v1", namespaceKey, accountId]));
+}
+function reportingRowRevisionKeyV1(rowSetId) {
+  return sha256Hex(canonicalize(["adcp.revision_key.v1", rowSetId]));
+}
+function renderReportingRowObjectKeyV1(input) {
+  const values = {
+    prefix: input.prefix,
+    namespace_key: input.namespaceKey,
+    account_key: reportingRowAccountKeyV1(input.namespaceKey, input.accountId),
+    period_date: periodDate(input.periodStart),
+    finality: input.finality ?? "adjustment",
+    revision_key: reportingRowRevisionKeyV1(input.rowSetId),
+    content_sha256: input.contentSha256,
+    chunk_index: String(input.chunkIndex).padStart(6, "0")
+  };
+  const key = input.template.replace(PLACEHOLDER, (_, name) => values[name]) + (input.compression === "gzip" ? ".jsonl.gz" : ".jsonl");
+  if (!KEY.test(key) || key.split("/").some((segment) => segment === "." || segment === "..") || !key.startsWith(`${input.prefix}/${input.namespaceKey}/`)) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "rendered object key escapes the binding prefix");
+  }
+  return key;
+}
+function periodDate(periodStart) {
+  if (!periodStart) return "undated";
+  const parsed = new Date(periodStart);
+  if (Number.isNaN(parsed.getTime())) return "undated";
+  return parsed.toISOString().slice(0, 10).replace(/-/g, "/");
+}
+function createFilesystemReportingRowObjectProviderV1(options) {
+  const roots = /* @__PURE__ */ new Map();
+  for (const [name, directory] of Object.entries(options.roots)) {
+    if (!/^[A-Za-z0-9_.-]{1,64}$/.test(name) || !path.isAbsolute(directory)) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "filesystem roots need a simple name and an absolute path");
+    }
+    roots.set(name, path.resolve(directory));
+  }
+  const resolve = (location, key) => {
+    const root = roots.get(location.root ?? "");
+    if (!root) throw new ReportingRowStoreError("UNSAFE_BINDING", "filesystem root is not configured");
+    const target = path.resolve(root, key);
+    if (!target.startsWith(root + path.sep)) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "object key escapes the filesystem root");
+    }
+    return target;
+  };
+  const version = async (target) => {
+    const stat = await fs.stat(target);
+    return `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+  };
+  return {
+    name: "filesystem",
+    rangedReads: true,
+    validateLocation(location) {
+      const keys = Object.keys(location);
+      if (keys.length !== 1 || keys[0] !== "root" || !roots.has(location.root)) {
+        throw new ReportingRowStoreError("INVALID_INPUT", "filesystem locations name exactly one configured root");
+      }
+    },
+    async probe(input) {
+      const root = roots.get(input.location.root ?? "");
+      if (!root) throw new ReportingRowStoreError("UNSAFE_BINDING", "filesystem root is not configured");
+      await fs.mkdir(root, { recursive: true });
+    },
+    async putIfAbsent(input, context) {
+      context.signal.throwIfAborted();
+      const target = resolve(input.location, input.key);
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      const temporary = `${target}.${randomUUID()}.tmp`;
+      const handle = await fs.open(temporary, "wx");
+      try {
+        await handle.writeFile(input.bytes);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      try {
+        await fs.link(temporary, target);
+        return { created: true, nativeVersion: await version(target) };
+      } catch (error) {
+        if (error.code === "EEXIST") {
+          return { created: false, nativeVersion: await version(target) };
+        }
+        throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "filesystem write failed");
+      } finally {
+        await fs.rm(temporary, { force: true });
+      }
+    },
+    async get(input, context) {
+      context.signal.throwIfAborted();
+      const target = resolve(input.location, input.key);
+      let handle;
+      try {
+        handle = await fs.open(target, "r");
+      } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "filesystem read failed");
+      }
+      try {
+        const stat = await handle.stat();
+        if (`${stat.ino}:${stat.mtimeMs}:${stat.size}` !== input.nativeVersion) return null;
+        const offset = input.range?.offset ?? 0;
+        const length = input.range?.length ?? stat.size - offset;
+        if (offset < 0 || length < 0 || offset + length > stat.size) {
+          throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the stored object");
+        }
+        if (length > input.maxBytes) {
+          throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
+        }
+        const buffer = Buffer.alloc(length);
+        await handle.read(buffer, 0, length, offset);
+        return buffer;
+      } finally {
+        await handle.close();
+      }
+    },
+    async delete(input, context) {
+      context.signal.throwIfAborted();
+      const target = resolve(input.location, input.key);
+      try {
+        if (await version(target) !== input.nativeVersion) return "absent";
+        await fs.unlink(target);
+        return "deleted";
+      } catch (error) {
+        if (error.code === "ENOENT") return "absent";
+        throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE", "filesystem delete failed");
+      }
+    }
+  };
+}
+async function runReportingRowObjectProviderConformanceV1(provider, input) {
+  assertReportingRowPrefixV1(input.prefix);
+  provider.validateLocation(input.location);
+  const context = { signal: AbortSignal.timeout(6e4) };
+  const passed = [];
+  const key = `${input.prefix}/conformance/${randomUUID()}.jsonl`;
+  const first = Buffer.from('{"a":1}\n{"b":2}\n');
+  const metadata = { "adcp-installation": "conformance", "adcp-intent": "conformance" };
+  const base = { location: input.location, ...input.credentialRef ? { credentialRef: input.credentialRef } : {} };
+  await provider.probe(input, context);
+  passed.push("probe");
+  const created = await provider.putIfAbsent(
+    { ...base, key, bytes: first, contentType: "application/x-ndjson", metadata },
+    context
+  );
+  if (!created.created || !created.nativeVersion) throw new Error("putIfAbsent did not create a new object");
+  passed.push("create");
+  const conflict = await provider.putIfAbsent(
+    { ...base, key, bytes: Buffer.from('{"c":3}\n'), contentType: "application/x-ndjson", metadata },
+    context
+  );
+  if (conflict.created || conflict.nativeVersion !== created.nativeVersion) {
+    throw new Error("putIfAbsent replaced or re-versioned an existing object");
+  }
+  const stored = await provider.get({ ...base, key, nativeVersion: created.nativeVersion, maxBytes: 1024 }, context);
+  if (!stored || !Buffer.from(stored).equals(first))
+    throw new Error("create-only write did not preserve the first bytes");
+  passed.push("create-only");
+  if (provider.rangedReads) {
+    const ranged = await provider.get(
+      { ...base, key, nativeVersion: created.nativeVersion, range: { offset: 8, length: 8 }, maxBytes: 1024 },
+      context
+    );
+    if (!ranged || Buffer.from(ranged).toString("utf8") !== '{"b":2}\n')
+      throw new Error("ranged read returned wrong bytes");
+    passed.push("ranged-read");
+  }
+  if (await provider.get({ ...base, key, nativeVersion: "not-a-version", maxBytes: 1024 }, context) !== null) {
+    throw new Error("get returned bytes for a version that does not exist");
+  }
+  passed.push("version-pinned-read");
+  if (await provider.delete({ ...base, key, nativeVersion: "not-a-version" }, context) !== "absent") {
+    throw new Error("delete removed an object at a different version");
+  }
+  if (await provider.delete({ ...base, key, nativeVersion: created.nativeVersion }, context) !== "deleted") {
+    throw new Error("delete did not remove the exact version");
+  }
+  if (await provider.delete({ ...base, key, nativeVersion: created.nativeVersion }, context) !== "absent") {
+    throw new Error("repeated delete was not idempotent");
+  }
+  passed.push("exact-version-delete");
+  return passed;
+}
+function sha256Hex(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+export {
+  REPORTING_ROW_DEFAULT_KEY_TEMPLATE,
+  REPORTING_ROW_KEY_PLACEHOLDERS,
+  assertReportingRowKeyTemplateV1,
+  assertReportingRowPrefixV1,
+  createFilesystemReportingRowObjectProviderV1,
+  renderReportingRowObjectKeyV1,
+  reportingRowAccountKeyV1,
+  reportingRowRevisionKeyV1,
+  runReportingRowObjectProviderConformanceV1
+};

package/dist/lib/reporting/ledger/row-storage-provider-io.d.mts

@@ -0,0 +1,51 @@
+import { ReportingRowStoreError } from './row-storage-errors.mjs';
+/**
+ * Internal helpers shared by the bundled cloud row-object providers (GCS, S3,
+ * Azure Blob). Not part of the public `reporting/ledger` surface.
+ */
+/** Stable code for an aborted operation: deadline expiry versus caller cancellation. */
+export declare function reportingRowAbortError(signal: AbortSignal): ReportingRowStoreError;
+/**
+ * Run one provider operation under the caller's signal. Settles as soon as the
+ * signal aborts, even when the official client ignores cancellation. Raw
+ * provider errors never escape: anything that is not already a
+ * `ReportingRowStoreError` becomes `PROVIDER_UNAVAILABLE`.
+ */
+export declare function runReportingRowProviderOperation<T>(signal: AbortSignal, work: () => Promise<T>): Promise<T>;
+/**
+ * Drain a byte stream, aborting once it exceeds `maxBytes`
+ * (`ROWS_INTEGRITY_FAILED`) or the signal fires. The stream is always destroyed.
+ */
+export declare function readReportingRowStream(stream: AsyncIterable<unknown> & {
+    destroy?: (error?: Error) => unknown;
+}, maxBytes: number, signal: AbortSignal): Promise<Buffer>;
+/** Validate a get request's range and cap before any provider I/O. */
+export declare function assertReportingRowReadBounds(input: {
+    range?: {
+        offset: number;
+        length: number;
+    };
+    maxBytes: number;
+}): void;
+/**
+ * Pick the host-injected client for a binding. `credentialRef` selects from a
+ * closed map; without one, the default client is used. Unknown references fail
+ * closed with `UNSAFE_BINDING` and never echo the reference.
+ */
+export declare function selectReportingRowClient<T>(defaultClient: T | undefined, clients: ReadonlyMap<string, T>, credentialRef: string | undefined): T;
+/** Copy a host client map into a closed, frozen lookup. */
+export declare function reportingRowClientMap<T>(clients: Readonly<Record<string, T>> | undefined): ReadonlyMap<string, T>;
+/** Throw `INVALID_INPUT` unless `location` has exactly the allowed keys (and every required one). */
+export declare function assertReportingRowLocationKeys(location: Readonly<Record<string, string>>, required: readonly string[], optional?: readonly string[]): void;
+/**
+ * Whether an object-store prefix filter can match keys under the binding's
+ * owned prefix. An absent or empty filter matches everything.
+ */
+export declare function reportingRowPrefixFilterOverlaps(filter: string | undefined, bindingPrefix: string): boolean;
+/**
+ * S3 and Azure record a version ID when the store is versioned, else the
+ * ETag. ETags are always kept quoted, which version IDs never are, so the two
+ * cannot be confused when the version is read back.
+ */
+export declare function reportingRowEtagVersion(etag: string): string;
+export declare function isReportingRowEtagVersion(nativeVersion: string): boolean;

package/dist/lib/reporting/ledger/row-storage-provider-io.d.ts

@@ -0,0 +1,51 @@
+import { ReportingRowStoreError } from './row-storage-errors';
+/**
+ * Internal helpers shared by the bundled cloud row-object providers (GCS, S3,
+ * Azure Blob). Not part of the public `reporting/ledger` surface.
+ */
+/** Stable code for an aborted operation: deadline expiry versus caller cancellation. */
+export declare function reportingRowAbortError(signal: AbortSignal): ReportingRowStoreError;
+/**
+ * Run one provider operation under the caller's signal. Settles as soon as the
+ * signal aborts, even when the official client ignores cancellation. Raw
+ * provider errors never escape: anything that is not already a
+ * `ReportingRowStoreError` becomes `PROVIDER_UNAVAILABLE`.
+ */
+export declare function runReportingRowProviderOperation<T>(signal: AbortSignal, work: () => Promise<T>): Promise<T>;
+/**
+ * Drain a byte stream, aborting once it exceeds `maxBytes`
+ * (`ROWS_INTEGRITY_FAILED`) or the signal fires. The stream is always destroyed.
+ */
+export declare function readReportingRowStream(stream: AsyncIterable<unknown> & {
+    destroy?: (error?: Error) => unknown;
+}, maxBytes: number, signal: AbortSignal): Promise<Buffer>;
+/** Validate a get request's range and cap before any provider I/O. */
+export declare function assertReportingRowReadBounds(input: {
+    range?: {
+        offset: number;
+        length: number;
+    };
+    maxBytes: number;
+}): void;
+/**
+ * Pick the host-injected client for a binding. `credentialRef` selects from a
+ * closed map; without one, the default client is used. Unknown references fail
+ * closed with `UNSAFE_BINDING` and never echo the reference.
+ */
+export declare function selectReportingRowClient<T>(defaultClient: T | undefined, clients: ReadonlyMap<string, T>, credentialRef: string | undefined): T;
+/** Copy a host client map into a closed, frozen lookup. */
+export declare function reportingRowClientMap<T>(clients: Readonly<Record<string, T>> | undefined): ReadonlyMap<string, T>;
+/** Throw `INVALID_INPUT` unless `location` has exactly the allowed keys (and every required one). */
+export declare function assertReportingRowLocationKeys(location: Readonly<Record<string, string>>, required: readonly string[], optional?: readonly string[]): void;
+/**
+ * Whether an object-store prefix filter can match keys under the binding's
+ * owned prefix. An absent or empty filter matches everything.
+ */
+export declare function reportingRowPrefixFilterOverlaps(filter: string | undefined, bindingPrefix: string): boolean;
+/**
+ * S3 and Azure record a version ID when the store is versioned, else the
+ * ETag. ETags are always kept quoted, which version IDs never are, so the two
+ * cannot be confused when the version is read back.
+ */
+export declare function reportingRowEtagVersion(etag: string): string;
+export declare function isReportingRowEtagVersion(nativeVersion: string): boolean;

package/dist/lib/reporting/ledger/row-storage-provider-io.js

@@ -0,0 +1,152 @@
+"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_storage_provider_io_exports = {};
+__export(row_storage_provider_io_exports, {
+  assertReportingRowLocationKeys: () => assertReportingRowLocationKeys,
+  assertReportingRowReadBounds: () => assertReportingRowReadBounds,
+  isReportingRowEtagVersion: () => isReportingRowEtagVersion,
+  readReportingRowStream: () => readReportingRowStream,
+  reportingRowAbortError: () => reportingRowAbortError,
+  reportingRowClientMap: () => reportingRowClientMap,
+  reportingRowEtagVersion: () => reportingRowEtagVersion,
+  reportingRowPrefixFilterOverlaps: () => reportingRowPrefixFilterOverlaps,
+  runReportingRowProviderOperation: () => runReportingRowProviderOperation,
+  selectReportingRowClient: () => selectReportingRowClient
+});
+module.exports = __toCommonJS(row_storage_provider_io_exports);
+var import_row_storage_errors = require('./row-storage-errors.js');
+function reportingRowAbortError(signal) {
+  const reason = signal.reason;
+  if ((0, import_row_storage_errors.isReportingRowStoreError)(reason)) return reason;
+  return new import_row_storage_errors.ReportingRowStoreError(reason?.name === "TimeoutError" ? "DEADLINE_EXCEEDED" : "ABORTED");
+}
+async function runReportingRowProviderOperation(signal, work) {
+  if (!(signal instanceof AbortSignal)) throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "a signal is required");
+  if (signal.aborted) throw reportingRowAbortError(signal);
+  let onAbort;
+  try {
+    return await Promise.race([
+      work(),
+      new Promise((_, reject) => {
+        onAbort = () => reject(reportingRowAbortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+      })
+    ]);
+  } catch (error) {
+    if (signal.aborted) throw reportingRowAbortError(signal);
+    if ((0, import_row_storage_errors.isReportingRowStoreError)(error)) throw error;
+    throw new import_row_storage_errors.ReportingRowStoreError("PROVIDER_UNAVAILABLE");
+  } finally {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+async function readReportingRowStream(stream, maxBytes, signal) {
+  const abort = () => stream.destroy?.(reportingRowAbortError(signal));
+  signal.addEventListener("abort", abort, { once: true });
+  const chunks = [];
+  let count = 0;
+  try {
+    if (signal.aborted) throw reportingRowAbortError(signal);
+    for await (const chunk of stream) {
+      if (signal.aborted) throw reportingRowAbortError(signal);
+      const bytes = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+      count += bytes.byteLength;
+      if (count > maxBytes) {
+        throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
+      }
+      chunks.push(bytes);
+    }
+    if (signal.aborted) throw reportingRowAbortError(signal);
+    return Buffer.concat(chunks);
+  } finally {
+    signal.removeEventListener("abort", abort);
+    stream.destroy?.();
+  }
+}
+function assertReportingRowReadBounds(input) {
+  if (!Number.isSafeInteger(input.maxBytes) || input.maxBytes < 0) {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "maxBytes must be a non-negative integer");
+  }
+  if (input.range === void 0) return;
+  const { offset, length } = input.range;
+  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0) {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "range must use non-negative integers");
+  }
+  if (length > input.maxBytes) {
+    throw new import_row_storage_errors.ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the read cap");
+  }
+}
+function selectReportingRowClient(defaultClient, clients, credentialRef) {
+  const client = credentialRef === void 0 ? defaultClient : clients.get(credentialRef);
+  if (client === void 0) {
+    throw new import_row_storage_errors.ReportingRowStoreError("UNSAFE_BINDING", "no client is configured for this binding");
+  }
+  return client;
+}
+function reportingRowClientMap(clients) {
+  const map = /* @__PURE__ */ new Map();
+  if (clients === void 0) return map;
+  if (!clients || typeof clients !== "object") {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "clients must map credential references to clients");
+  }
+  for (const [ref, client] of Object.entries(clients)) {
+    if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(ref) || !client) {
+      throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "clients must map credential references to clients");
+    }
+    map.set(ref, client);
+  }
+  return map;
+}
+function assertReportingRowLocationKeys(location, required, optional = []) {
+  if (!location || typeof location !== "object" || Array.isArray(location)) {
+    throw new import_row_storage_errors.ReportingRowStoreError("INVALID_INPUT", "location must be an object");
+  }
+  const keys = Object.keys(location);
+  const allowed = /* @__PURE__ */ new Set([...required, ...optional]);
+  if (keys.some((key) => !allowed.has(key) || typeof location[key] !== "string") || required.some((key) => !keys.includes(key))) {
+    throw new import_row_storage_errors.ReportingRowStoreError(
+      "INVALID_INPUT",
+      `location accepts only ${[...required, ...optional.map((key) => `${key}?`)].join(", ")}`
+    );
+  }
+}
+function reportingRowPrefixFilterOverlaps(filter, bindingPrefix) {
+  if (!filter) return true;
+  const owned = `${bindingPrefix}/`;
+  return owned.startsWith(filter) || filter.startsWith(owned);
+}
+function reportingRowEtagVersion(etag) {
+  return etag.startsWith('"') && etag.endsWith('"') && etag.length >= 2 ? etag : `"${etag}"`;
+}
+function isReportingRowEtagVersion(nativeVersion) {
+  return nativeVersion.length >= 2 && nativeVersion.startsWith('"') && nativeVersion.endsWith('"');
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertReportingRowLocationKeys,
+  assertReportingRowReadBounds,
+  isReportingRowEtagVersion,
+  readReportingRowStream,
+  reportingRowAbortError,
+  reportingRowClientMap,
+  reportingRowEtagVersion,
+  reportingRowPrefixFilterOverlaps,
+  runReportingRowProviderOperation,
+  selectReportingRowClient
+});

package/dist/lib/reporting/ledger/row-storage-provider-io.mjs

@@ -0,0 +1,119 @@
+import { ReportingRowStoreError, isReportingRowStoreError } from "./row-storage-errors.mjs";
+function reportingRowAbortError(signal) {
+  const reason = signal.reason;
+  if (isReportingRowStoreError(reason)) return reason;
+  return new ReportingRowStoreError(reason?.name === "TimeoutError" ? "DEADLINE_EXCEEDED" : "ABORTED");
+}
+async function runReportingRowProviderOperation(signal, work) {
+  if (!(signal instanceof AbortSignal)) throw new ReportingRowStoreError("INVALID_INPUT", "a signal is required");
+  if (signal.aborted) throw reportingRowAbortError(signal);
+  let onAbort;
+  try {
+    return await Promise.race([
+      work(),
+      new Promise((_, reject) => {
+        onAbort = () => reject(reportingRowAbortError(signal));
+        signal.addEventListener("abort", onAbort, { once: true });
+      })
+    ]);
+  } catch (error) {
+    if (signal.aborted) throw reportingRowAbortError(signal);
+    if (isReportingRowStoreError(error)) throw error;
+    throw new ReportingRowStoreError("PROVIDER_UNAVAILABLE");
+  } finally {
+    if (onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+async function readReportingRowStream(stream, maxBytes, signal) {
+  const abort = () => stream.destroy?.(reportingRowAbortError(signal));
+  signal.addEventListener("abort", abort, { once: true });
+  const chunks = [];
+  let count = 0;
+  try {
+    if (signal.aborted) throw reportingRowAbortError(signal);
+    for await (const chunk of stream) {
+      if (signal.aborted) throw reportingRowAbortError(signal);
+      const bytes = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+      count += bytes.byteLength;
+      if (count > maxBytes) {
+        throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "stored object exceeds its recorded size");
+      }
+      chunks.push(bytes);
+    }
+    if (signal.aborted) throw reportingRowAbortError(signal);
+    return Buffer.concat(chunks);
+  } finally {
+    signal.removeEventListener("abort", abort);
+    stream.destroy?.();
+  }
+}
+function assertReportingRowReadBounds(input) {
+  if (!Number.isSafeInteger(input.maxBytes) || input.maxBytes < 0) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "maxBytes must be a non-negative integer");
+  }
+  if (input.range === void 0) return;
+  const { offset, length } = input.range;
+  if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "range must use non-negative integers");
+  }
+  if (length > input.maxBytes) {
+    throw new ReportingRowStoreError("ROWS_INTEGRITY_FAILED", "requested range exceeds the read cap");
+  }
+}
+function selectReportingRowClient(defaultClient, clients, credentialRef) {
+  const client = credentialRef === void 0 ? defaultClient : clients.get(credentialRef);
+  if (client === void 0) {
+    throw new ReportingRowStoreError("UNSAFE_BINDING", "no client is configured for this binding");
+  }
+  return client;
+}
+function reportingRowClientMap(clients) {
+  const map = /* @__PURE__ */ new Map();
+  if (clients === void 0) return map;
+  if (!clients || typeof clients !== "object") {
+    throw new ReportingRowStoreError("INVALID_INPUT", "clients must map credential references to clients");
+  }
+  for (const [ref, client] of Object.entries(clients)) {
+    if (!/^[A-Za-z0-9_.:-]{1,128}$/.test(ref) || !client) {
+      throw new ReportingRowStoreError("INVALID_INPUT", "clients must map credential references to clients");
+    }
+    map.set(ref, client);
+  }
+  return map;
+}
+function assertReportingRowLocationKeys(location, required, optional = []) {
+  if (!location || typeof location !== "object" || Array.isArray(location)) {
+    throw new ReportingRowStoreError("INVALID_INPUT", "location must be an object");
+  }
+  const keys = Object.keys(location);
+  const allowed = /* @__PURE__ */ new Set([...required, ...optional]);
+  if (keys.some((key) => !allowed.has(key) || typeof location[key] !== "string") || required.some((key) => !keys.includes(key))) {
+    throw new ReportingRowStoreError(
+      "INVALID_INPUT",
+      `location accepts only ${[...required, ...optional.map((key) => `${key}?`)].join(", ")}`
+    );
+  }
+}
+function reportingRowPrefixFilterOverlaps(filter, bindingPrefix) {
+  if (!filter) return true;
+  const owned = `${bindingPrefix}/`;
+  return owned.startsWith(filter) || filter.startsWith(owned);
+}
+function reportingRowEtagVersion(etag) {
+  return etag.startsWith('"') && etag.endsWith('"') && etag.length >= 2 ? etag : `"${etag}"`;
+}
+function isReportingRowEtagVersion(nativeVersion) {
+  return nativeVersion.length >= 2 && nativeVersion.startsWith('"') && nativeVersion.endsWith('"');
+}
+export {
+  assertReportingRowLocationKeys,
+  assertReportingRowReadBounds,
+  isReportingRowEtagVersion,
+  readReportingRowStream,
+  reportingRowAbortError,
+  reportingRowClientMap,
+  reportingRowEtagVersion,
+  reportingRowPrefixFilterOverlaps,
+  runReportingRowProviderOperation,
+  selectReportingRowClient
+};