@adcp/sdk 15.3.0 → 15.4.0

package/dist/lib/reporting/ledger/revision-metadata.d.mts

@@ -0,0 +1,17 @@
+import type { ReportingLedgerAdjustmentMetadataV1, ReportingLedgerRevisionMetadataV1, ReportingLedgerStore, ReportingRevisionRowsPageV1, ReportingRevisionRowsReadV1 } from './types.mjs';
+/**
+ * Row-free revision listing for paths that only need identity, finality,
+ * supersession, binding and wire metadata. Prefers the store's
+ * `listRevisionMetadata`; a store without it is read through `listRevisions`
+ * and its rows are dropped before they reach the caller.
+ */
+export declare function listRevisionMetadataFromStore(store: Pick<ReportingLedgerStore, 'listRevisions' | 'listRevisionMetadata'>, reporting_obligation_id: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
+/** Row-free counterpart of {@link listRevisionMetadataFromStore} for adjustments. */
+export declare function listAdjustmentMetadataFromStore(store: Pick<ReportingLedgerStore, 'listAdjustments' | 'listAdjustmentMetadata'>, reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
+/** Account-scoped revision metadata, preferring the store's row-free read. */
+export declare function getRevisionMetadataFromStore(store: Pick<ReportingLedgerStore, 'getRevision' | 'getRevisionMetadata'>, reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+/**
+ * One page of a revision's rows. Prefers the store's paged reader; otherwise
+ * loads the revision through `getRevision` and slices it.
+ */
+export declare function readRevisionRowsFromStore(store: Pick<ReportingLedgerStore, 'getRevision' | 'readRevisionRows'>, input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;

package/dist/lib/reporting/ledger/revision-metadata.d.ts

@@ -0,0 +1,17 @@
+import type { ReportingLedgerAdjustmentMetadataV1, ReportingLedgerRevisionMetadataV1, ReportingLedgerStore, ReportingRevisionRowsPageV1, ReportingRevisionRowsReadV1 } from './types';
+/**
+ * Row-free revision listing for paths that only need identity, finality,
+ * supersession, binding and wire metadata. Prefers the store's
+ * `listRevisionMetadata`; a store without it is read through `listRevisions`
+ * and its rows are dropped before they reach the caller.
+ */
+export declare function listRevisionMetadataFromStore(store: Pick<ReportingLedgerStore, 'listRevisions' | 'listRevisionMetadata'>, reporting_obligation_id: string): Promise<ReportingLedgerRevisionMetadataV1[]>;
+/** Row-free counterpart of {@link listRevisionMetadataFromStore} for adjustments. */
+export declare function listAdjustmentMetadataFromStore(store: Pick<ReportingLedgerStore, 'listAdjustments' | 'listAdjustmentMetadata'>, reporting_obligation_id: string): Promise<ReportingLedgerAdjustmentMetadataV1[]>;
+/** Account-scoped revision metadata, preferring the store's row-free read. */
+export declare function getRevisionMetadataFromStore(store: Pick<ReportingLedgerStore, 'getRevision' | 'getRevisionMetadata'>, reporting_revision_id: string, account_id: string): Promise<ReportingLedgerRevisionMetadataV1 | null>;
+/**
+ * One page of a revision's rows. Prefers the store's paged reader; otherwise
+ * loads the revision through `getRevision` and slices it.
+ */
+export declare function readRevisionRowsFromStore(store: Pick<ReportingLedgerStore, 'getRevision' | 'readRevisionRows'>, input: ReportingRevisionRowsReadV1): Promise<ReportingRevisionRowsPageV1 | null>;

package/dist/lib/reporting/ledger/revision-metadata.js

@@ -0,0 +1,71 @@
+"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 revision_metadata_exports = {};
+__export(revision_metadata_exports, {
+  getRevisionMetadataFromStore: () => getRevisionMetadataFromStore,
+  listAdjustmentMetadataFromStore: () => listAdjustmentMetadataFromStore,
+  listRevisionMetadataFromStore: () => listRevisionMetadataFromStore,
+  readRevisionRowsFromStore: () => readRevisionRowsFromStore
+});
+module.exports = __toCommonJS(revision_metadata_exports);
+async function listRevisionMetadataFromStore(store, reporting_obligation_id) {
+  if (typeof store.listRevisionMetadata === "function") {
+    return store.listRevisionMetadata(reporting_obligation_id);
+  }
+  const revisions = await store.listRevisions(reporting_obligation_id);
+  return revisions.map(({ rows: _rows, ...metadata }) => metadata);
+}
+async function listAdjustmentMetadataFromStore(store, reporting_obligation_id) {
+  if (typeof store.listAdjustmentMetadata === "function") {
+    return store.listAdjustmentMetadata(reporting_obligation_id);
+  }
+  const adjustments = await store.listAdjustments(reporting_obligation_id);
+  return adjustments.map(({ rows: _rows, ...metadata }) => metadata);
+}
+async function getRevisionMetadataFromStore(store, reporting_revision_id, account_id) {
+  if (typeof store.getRevisionMetadata === "function") {
+    return store.getRevisionMetadata(reporting_revision_id, account_id);
+  }
+  const revision = await store.getRevision(reporting_revision_id, account_id);
+  if (!revision) return null;
+  const { rows: _rows, ...metadata } = revision;
+  return metadata;
+}
+async function readRevisionRowsFromStore(store, input) {
+  if (!Number.isSafeInteger(input.offset) || input.offset < 0) {
+    throw new RangeError("Reporting row page offset must be a non-negative integer");
+  }
+  if (!Number.isSafeInteger(input.limit) || input.limit < 1) {
+    throw new RangeError("Reporting row page limit must be a positive integer");
+  }
+  if (typeof store.readRevisionRows === "function") return store.readRevisionRows(input);
+  const revision = await store.getRevision(input.reporting_revision_id, input.account_id);
+  if (!revision) return null;
+  return {
+    rows: revision.rows.slice(input.offset, input.offset + input.limit),
+    total: revision.rows.length
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getRevisionMetadataFromStore,
+  listAdjustmentMetadataFromStore,
+  listRevisionMetadataFromStore,
+  readRevisionRowsFromStore
+});

package/dist/lib/reporting/ledger/revision-metadata.mjs

@@ -0,0 +1,44 @@
+async function listRevisionMetadataFromStore(store, reporting_obligation_id) {
+  if (typeof store.listRevisionMetadata === "function") {
+    return store.listRevisionMetadata(reporting_obligation_id);
+  }
+  const revisions = await store.listRevisions(reporting_obligation_id);
+  return revisions.map(({ rows: _rows, ...metadata }) => metadata);
+}
+async function listAdjustmentMetadataFromStore(store, reporting_obligation_id) {
+  if (typeof store.listAdjustmentMetadata === "function") {
+    return store.listAdjustmentMetadata(reporting_obligation_id);
+  }
+  const adjustments = await store.listAdjustments(reporting_obligation_id);
+  return adjustments.map(({ rows: _rows, ...metadata }) => metadata);
+}
+async function getRevisionMetadataFromStore(store, reporting_revision_id, account_id) {
+  if (typeof store.getRevisionMetadata === "function") {
+    return store.getRevisionMetadata(reporting_revision_id, account_id);
+  }
+  const revision = await store.getRevision(reporting_revision_id, account_id);
+  if (!revision) return null;
+  const { rows: _rows, ...metadata } = revision;
+  return metadata;
+}
+async function readRevisionRowsFromStore(store, input) {
+  if (!Number.isSafeInteger(input.offset) || input.offset < 0) {
+    throw new RangeError("Reporting row page offset must be a non-negative integer");
+  }
+  if (!Number.isSafeInteger(input.limit) || input.limit < 1) {
+    throw new RangeError("Reporting row page limit must be a positive integer");
+  }
+  if (typeof store.readRevisionRows === "function") return store.readRevisionRows(input);
+  const revision = await store.getRevision(input.reporting_revision_id, input.account_id);
+  if (!revision) return null;
+  return {
+    rows: revision.rows.slice(input.offset, input.offset + input.limit),
+    total: revision.rows.length
+  };
+}
+export {
+  getRevisionMetadataFromStore,
+  listAdjustmentMetadataFromStore,
+  listRevisionMetadataFromStore,
+  readRevisionRowsFromStore
+};

package/dist/lib/reporting/ledger/row-encoding.d.mts

@@ -0,0 +1,128 @@
+/**
+ * Canonical JSONL row encoding for reporting revisions (shared SDK
+ * persistence contract, `reporting-row-storage` v1).
+ *
+ * Rows are stored as `JCS(row) + "\n"` in ordinal order. JCS escapes newline
+ * characters inside strings, so the `0x0A` byte only ever separates rows.
+ * Rows are grouped into segments (the unit of verification and paged reads)
+ * and chunks (the unit of storage). Boundaries are fixed by the contract so
+ * every SDK produces byte-identical chunks and manifests for the same rows:
+ *
+ * - a new chunk starts when the current chunk holds
+ *   {@link REPORTING_ROW_CHUNK_MAX_ROWS} rows, or when appending the next row
+ *   would exceed {@link REPORTING_ROW_CHUNK_MAX_BYTES} canonical bytes;
+ * - segments restart at each chunk boundary and close every
+ *   {@link REPORTING_ROW_SEGMENT_MAX_ROWS} rows.
+ *
+ * A row larger than the chunk byte limit forms its own segment and chunk.
+ * Digests always cover uncompressed canonical bytes.
+ */
+export declare const REPORTING_ROW_ENCODING_V1: "adcp_canonical_jsonl_v1";
+export declare const REPORTING_ROW_SEGMENT_MAX_ROWS = 500;
+export declare const REPORTING_ROW_CHUNK_MAX_SEGMENTS = 20;
+export declare const REPORTING_ROW_CHUNK_MAX_ROWS: number;
+export declare const REPORTING_ROW_CHUNK_MAX_BYTES: number;
+export type ReportingRowEncodingErrorCode = 'INVALID_ROW' | 'MANIFEST_MISMATCH' | 'CHUNK_INTEGRITY_FAILED' | 'ENVELOPE_INTEGRITY_FAILED';
+export declare class ReportingRowEncodingError extends Error {
+    readonly code: ReportingRowEncodingErrorCode;
+    constructor(code: ReportingRowEncodingErrorCode, detail: string);
+}
+export declare function isReportingRowEncodingError(error: unknown): error is ReportingRowEncodingError;
+export interface ReportingRowSegmentManifestV1 {
+    first_ordinal: number;
+    row_count: number;
+    /** Offset of the segment within its chunk's uncompressed canonical bytes. */
+    byte_offset: number;
+    byte_count: number;
+    sha256: string;
+}
+export interface ReportingRowChunkManifestV1 {
+    chunk_index: number;
+    first_ordinal: number;
+    row_count: number;
+    byte_count: number;
+    sha256: string;
+    segments: ReportingRowSegmentManifestV1[];
+}
+export interface ReportingRowChunkV1 {
+    manifest: ReportingRowChunkManifestV1;
+    /** Uncompressed canonical JSONL bytes. */
+    bytes: Buffer;
+}
+export interface ReportingEncodedRowsV1 {
+    encoding: typeof REPORTING_ROW_ENCODING_V1;
+    rowCount: number;
+    /** Total canonical JSONL bytes across all chunks. */
+    byteCount: number;
+    chunks: ReportingRowChunkV1[];
+    manifests: ReportingRowChunkManifestV1[];
+    /** `sha256(JCS(manifests))`; bound immutably on the revision header. */
+    rowManifestSha256: string;
+}
+export interface ReportingRevisionEnvelopeInputV1 {
+    reporting_revision_id: string;
+    row_count: number;
+    control_totals: readonly unknown[];
+}
+export interface ReportingRevisionEnvelopeDigestV1 {
+    sha256: string;
+    /** Byte length of the canonical envelope; equals `binding.byteCount`. */
+    byteCount: number;
+}
+/**
+ * Canonicalize one row for storage. Refuses values whose canonical bytes are
+ * not portable across conforming JCS implementations: non-plain objects,
+ * non-finite numbers, integers outside ±(2^53 − 1), and lone surrogates.
+ */
+export declare function canonicalReportingRowV1(row: unknown, ordinal?: number): string;
+/** Encode rows into contract-fixed canonical JSONL chunks and manifests. */
+export declare function encodeReportingRowsV1(rows: readonly unknown[]): ReportingEncodedRowsV1;
+/** `sha256(JCS(manifests))` over the ordered chunk manifests, locators excluded. */
+export declare function reportingRowManifestSha256V1(manifests: readonly ReportingRowChunkManifestV1[]): string;
+/**
+ * Verify that a manifest set is internally consistent and matches the
+ * header's committed `row_manifest_sha256` and `row_count`. Ordinals must be
+ * contiguous from zero, chunk and segment boundaries must follow the contract
+ * limits, and segment byte ranges must tile their chunk exactly.
+ */
+export declare function verifyReportingRowManifestsV1(manifests: readonly ReportingRowChunkManifestV1[], expected: {
+    rowCount: number;
+    rowManifestSha256: string;
+}): void;
+/**
+ * Verify a whole chunk's canonical bytes against its manifest: total digest,
+ * byte count, and every segment's digest and line count.
+ */
+export declare function verifyReportingRowChunkV1(manifest: ReportingRowChunkManifestV1, bytes: Uint8Array): void;
+/**
+ * Verify and decode a contiguous range of segments `[fromSegment, toSegment]`
+ * (inclusive). `bytes` must hold exactly those segments' canonical bytes,
+ * starting at the first segment's `byte_offset` — the shape returned by a
+ * ranged object read. Rows are released only after every segment verifies.
+ */
+export declare function decodeVerifiedReportingRowSegmentsV1(manifest: ReportingRowChunkManifestV1, segmentRange: readonly [fromSegment: number, toSegment: number], bytes: Uint8Array): Record<string, unknown>[];
+/**
+ * Streaming hasher for the protocol revision binding
+ * `sha256(JCS({reporting_revision_id, row_count, control_totals, reporting_rows}))`.
+ * Feed verified chunk bytes in order; rows are never parsed.
+ */
+export declare function createReportingRevisionEnvelopeHasherV1(envelope: ReportingRevisionEnvelopeInputV1): {
+    update(chunkBytes: Uint8Array): void;
+    digest(): ReportingRevisionEnvelopeDigestV1;
+};
+/** Envelope digest over already-encoded chunk bytes. */
+export declare function reportingRevisionEnvelopeDigestV1(envelope: ReportingRevisionEnvelopeInputV1, chunks: Iterable<Uint8Array>): ReportingRevisionEnvelopeDigestV1;
+/** Streaming hasher for digest profile `rows_v1`: `sha256(JCS(rows))`. */
+export declare function createReportingRowsOnlyHasherV1(rowCount: number): {
+    update(chunkBytes: Uint8Array): void;
+    digest(): ReportingRevisionEnvelopeDigestV1;
+};
+/**
+ * Throw unless the canonical chunks reproduce the header's committed revision
+ * binding. Used at write time (proof that chunks and envelope agree) and for
+ * full-revision reads.
+ */
+export declare function assertReportingRevisionEnvelopeV1(envelope: ReportingRevisionEnvelopeInputV1, chunks: Iterable<Uint8Array>, expected: {
+    sha256: string;
+    byteCount?: number;
+}): void;

package/dist/lib/reporting/ledger/row-encoding.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Canonical JSONL row encoding for reporting revisions (shared SDK
+ * persistence contract, `reporting-row-storage` v1).
+ *
+ * Rows are stored as `JCS(row) + "\n"` in ordinal order. JCS escapes newline
+ * characters inside strings, so the `0x0A` byte only ever separates rows.
+ * Rows are grouped into segments (the unit of verification and paged reads)
+ * and chunks (the unit of storage). Boundaries are fixed by the contract so
+ * every SDK produces byte-identical chunks and manifests for the same rows:
+ *
+ * - a new chunk starts when the current chunk holds
+ *   {@link REPORTING_ROW_CHUNK_MAX_ROWS} rows, or when appending the next row
+ *   would exceed {@link REPORTING_ROW_CHUNK_MAX_BYTES} canonical bytes;
+ * - segments restart at each chunk boundary and close every
+ *   {@link REPORTING_ROW_SEGMENT_MAX_ROWS} rows.
+ *
+ * A row larger than the chunk byte limit forms its own segment and chunk.
+ * Digests always cover uncompressed canonical bytes.
+ */
+export declare const REPORTING_ROW_ENCODING_V1: "adcp_canonical_jsonl_v1";
+export declare const REPORTING_ROW_SEGMENT_MAX_ROWS = 500;
+export declare const REPORTING_ROW_CHUNK_MAX_SEGMENTS = 20;
+export declare const REPORTING_ROW_CHUNK_MAX_ROWS: number;
+export declare const REPORTING_ROW_CHUNK_MAX_BYTES: number;
+export type ReportingRowEncodingErrorCode = 'INVALID_ROW' | 'MANIFEST_MISMATCH' | 'CHUNK_INTEGRITY_FAILED' | 'ENVELOPE_INTEGRITY_FAILED';
+export declare class ReportingRowEncodingError extends Error {
+    readonly code: ReportingRowEncodingErrorCode;
+    constructor(code: ReportingRowEncodingErrorCode, detail: string);
+}
+export declare function isReportingRowEncodingError(error: unknown): error is ReportingRowEncodingError;
+export interface ReportingRowSegmentManifestV1 {
+    first_ordinal: number;
+    row_count: number;
+    /** Offset of the segment within its chunk's uncompressed canonical bytes. */
+    byte_offset: number;
+    byte_count: number;
+    sha256: string;
+}
+export interface ReportingRowChunkManifestV1 {
+    chunk_index: number;
+    first_ordinal: number;
+    row_count: number;
+    byte_count: number;
+    sha256: string;
+    segments: ReportingRowSegmentManifestV1[];
+}
+export interface ReportingRowChunkV1 {
+    manifest: ReportingRowChunkManifestV1;
+    /** Uncompressed canonical JSONL bytes. */
+    bytes: Buffer;
+}
+export interface ReportingEncodedRowsV1 {
+    encoding: typeof REPORTING_ROW_ENCODING_V1;
+    rowCount: number;
+    /** Total canonical JSONL bytes across all chunks. */
+    byteCount: number;
+    chunks: ReportingRowChunkV1[];
+    manifests: ReportingRowChunkManifestV1[];
+    /** `sha256(JCS(manifests))`; bound immutably on the revision header. */
+    rowManifestSha256: string;
+}
+export interface ReportingRevisionEnvelopeInputV1 {
+    reporting_revision_id: string;
+    row_count: number;
+    control_totals: readonly unknown[];
+}
+export interface ReportingRevisionEnvelopeDigestV1 {
+    sha256: string;
+    /** Byte length of the canonical envelope; equals `binding.byteCount`. */
+    byteCount: number;
+}
+/**
+ * Canonicalize one row for storage. Refuses values whose canonical bytes are
+ * not portable across conforming JCS implementations: non-plain objects,
+ * non-finite numbers, integers outside ±(2^53 − 1), and lone surrogates.
+ */
+export declare function canonicalReportingRowV1(row: unknown, ordinal?: number): string;
+/** Encode rows into contract-fixed canonical JSONL chunks and manifests. */
+export declare function encodeReportingRowsV1(rows: readonly unknown[]): ReportingEncodedRowsV1;
+/** `sha256(JCS(manifests))` over the ordered chunk manifests, locators excluded. */
+export declare function reportingRowManifestSha256V1(manifests: readonly ReportingRowChunkManifestV1[]): string;
+/**
+ * Verify that a manifest set is internally consistent and matches the
+ * header's committed `row_manifest_sha256` and `row_count`. Ordinals must be
+ * contiguous from zero, chunk and segment boundaries must follow the contract
+ * limits, and segment byte ranges must tile their chunk exactly.
+ */
+export declare function verifyReportingRowManifestsV1(manifests: readonly ReportingRowChunkManifestV1[], expected: {
+    rowCount: number;
+    rowManifestSha256: string;
+}): void;
+/**
+ * Verify a whole chunk's canonical bytes against its manifest: total digest,
+ * byte count, and every segment's digest and line count.
+ */
+export declare function verifyReportingRowChunkV1(manifest: ReportingRowChunkManifestV1, bytes: Uint8Array): void;
+/**
+ * Verify and decode a contiguous range of segments `[fromSegment, toSegment]`
+ * (inclusive). `bytes` must hold exactly those segments' canonical bytes,
+ * starting at the first segment's `byte_offset` — the shape returned by a
+ * ranged object read. Rows are released only after every segment verifies.
+ */
+export declare function decodeVerifiedReportingRowSegmentsV1(manifest: ReportingRowChunkManifestV1, segmentRange: readonly [fromSegment: number, toSegment: number], bytes: Uint8Array): Record<string, unknown>[];
+/**
+ * Streaming hasher for the protocol revision binding
+ * `sha256(JCS({reporting_revision_id, row_count, control_totals, reporting_rows}))`.
+ * Feed verified chunk bytes in order; rows are never parsed.
+ */
+export declare function createReportingRevisionEnvelopeHasherV1(envelope: ReportingRevisionEnvelopeInputV1): {
+    update(chunkBytes: Uint8Array): void;
+    digest(): ReportingRevisionEnvelopeDigestV1;
+};
+/** Envelope digest over already-encoded chunk bytes. */
+export declare function reportingRevisionEnvelopeDigestV1(envelope: ReportingRevisionEnvelopeInputV1, chunks: Iterable<Uint8Array>): ReportingRevisionEnvelopeDigestV1;
+/** Streaming hasher for digest profile `rows_v1`: `sha256(JCS(rows))`. */
+export declare function createReportingRowsOnlyHasherV1(rowCount: number): {
+    update(chunkBytes: Uint8Array): void;
+    digest(): ReportingRevisionEnvelopeDigestV1;
+};
+/**
+ * Throw unless the canonical chunks reproduce the header's committed revision
+ * binding. Used at write time (proof that chunks and envelope agree) and for
+ * full-revision reads.
+ */
+export declare function assertReportingRevisionEnvelopeV1(envelope: ReportingRevisionEnvelopeInputV1, chunks: Iterable<Uint8Array>, expected: {
+    sha256: string;
+    byteCount?: number;
+}): void;