@adcp/sdk 15.6.0 → 15.7.0

package/dist/lib/reporting/ledger/handler.js

@@ -410,6 +410,12 @@ function createReportingStatusHandler(store, options) {
   };
 }
 const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 1e4;
+function reportingRevisionNotFound() {
+  return new import_async_outcome.AdcpError("REFERENCE_NOT_FOUND", {
+    message: "Reporting revision is unavailable",
+    field: "reporting_revision_id"
+  });
+}
 function createReportingDeliveryHandler(store) {
   const activeReadsByAccount = /* @__PURE__ */ new Map();
   return async (request, context) => {
@@ -428,14 +434,15 @@ function createReportingDeliveryHandler(store) {
     try {
       const raw = request;
       if (typeof raw.reporting_revision_id !== "string" || !raw.reporting_revision_id) {
-        throw new Error("Ledger delivery reads require reporting_revision_id");
+        throw new import_async_outcome.AdcpError("VALIDATION_ERROR", {
+          message: "Ledger delivery reads require reporting_revision_id",
+          field: "reporting_revision_id"
+        });
       }
       const revision = await (0, import_revision_metadata.getRevisionMetadataFromStore)(store, raw.reporting_revision_id, accountId);
-      if (!revision) throw new Error("Reporting revision is unavailable");
+      if (!revision) throw reportingRevisionNotFound();
       const obligation = await store.getObligation(revision.reporting_obligation_id);
-      if (!obligation || obligation.account.account_id !== accountId) {
-        throw new Error("Reporting revision is unavailable");
-      }
+      if (!obligation || obligation.account.account_id !== accountId) throw reportingRevisionNotFound();
       const pagination = isRecord(raw.pagination) ? raw.pagination : {};
       const maxResults = typeof pagination.max_results === "number" && Number.isFinite(pagination.max_results) ? Math.max(1, Math.min(500, Math.trunc(pagination.max_results))) : 100;
       const totalCount = revision.binding.rowCount;
@@ -448,7 +455,7 @@ function createReportingDeliveryHandler(store) {
           }
           offset = cursor.offset;
         } catch {
-          throw new Error("Reporting delivery cursor is invalid");
+          throw reportingRevisionNotFound();
         }
       }
       let reportingRows = [];
@@ -464,14 +471,19 @@ function createReportingDeliveryHandler(store) {
           });
         } catch (error) {
           if ((0, import_row_storage.isReportingRowStoreError)(error)) {
-            if (error.code === "ROWS_EXPIRED") throw new Error("Reporting revision is unavailable");
+            if (error.code === "ROWS_EXPIRED") throw reportingRevisionNotFound();
             throw new import_async_outcome.AdcpError("SERVICE_UNAVAILABLE", {
               message: "Reporting revision rows are temporarily unavailable"
             });
           }
           throw error;
         }
-        if (!page || page.total !== totalCount) throw new Error("Reporting revision is unavailable");
+        if (!page) throw reportingRevisionNotFound();
+        if (page.total !== totalCount) {
+          throw new import_async_outcome.AdcpError("SERVICE_UNAVAILABLE", {
+            message: "Reporting revision rows are temporarily unavailable"
+          });
+        }
         reportingRows = page.rows;
       }
       const nextOffset = offset + reportingRows.length;

package/dist/lib/reporting/ledger/handler.mjs

@@ -393,6 +393,12 @@ function createReportingStatusHandler(store, options) {
   };
 }
 const REPORTING_STATUS_REVISION_VIEW_MAX_ROWS = 1e4;
+function reportingRevisionNotFound() {
+  return new AdcpError("REFERENCE_NOT_FOUND", {
+    message: "Reporting revision is unavailable",
+    field: "reporting_revision_id"
+  });
+}
 function createReportingDeliveryHandler(store) {
   const activeReadsByAccount = /* @__PURE__ */ new Map();
   return async (request, context) => {
@@ -411,14 +417,15 @@ function createReportingDeliveryHandler(store) {
     try {
       const raw = request;
       if (typeof raw.reporting_revision_id !== "string" || !raw.reporting_revision_id) {
-        throw new Error("Ledger delivery reads require reporting_revision_id");
+        throw new AdcpError("VALIDATION_ERROR", {
+          message: "Ledger delivery reads require reporting_revision_id",
+          field: "reporting_revision_id"
+        });
       }
       const revision = await getRevisionMetadataFromStore(store, raw.reporting_revision_id, accountId);
-      if (!revision) throw new Error("Reporting revision is unavailable");
+      if (!revision) throw reportingRevisionNotFound();
       const obligation = await store.getObligation(revision.reporting_obligation_id);
-      if (!obligation || obligation.account.account_id !== accountId) {
-        throw new Error("Reporting revision is unavailable");
-      }
+      if (!obligation || obligation.account.account_id !== accountId) throw reportingRevisionNotFound();
       const pagination = isRecord(raw.pagination) ? raw.pagination : {};
       const maxResults = typeof pagination.max_results === "number" && Number.isFinite(pagination.max_results) ? Math.max(1, Math.min(500, Math.trunc(pagination.max_results))) : 100;
       const totalCount = revision.binding.rowCount;
@@ -431,7 +438,7 @@ function createReportingDeliveryHandler(store) {
           }
           offset = cursor.offset;
         } catch {
-          throw new Error("Reporting delivery cursor is invalid");
+          throw reportingRevisionNotFound();
         }
       }
       let reportingRows = [];
@@ -447,14 +454,19 @@ function createReportingDeliveryHandler(store) {
           });
         } catch (error) {
           if (isReportingRowStoreError(error)) {
-            if (error.code === "ROWS_EXPIRED") throw new Error("Reporting revision is unavailable");
+            if (error.code === "ROWS_EXPIRED") throw reportingRevisionNotFound();
             throw new AdcpError("SERVICE_UNAVAILABLE", {
               message: "Reporting revision rows are temporarily unavailable"
             });
           }
           throw error;
         }
-        if (!page || page.total !== totalCount) throw new Error("Reporting revision is unavailable");
+        if (!page) throw reportingRevisionNotFound();
+        if (page.total !== totalCount) {
+          throw new AdcpError("SERVICE_UNAVAILABLE", {
+            message: "Reporting revision rows are temporarily unavailable"
+          });
+        }
         reportingRows = page.rows;
       }
       const nextOffset = offset + reportingRows.length;

package/dist/lib/reporting/ledger/postgres.d.mts

@@ -137,6 +137,17 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     private readonly rowStorageWrites;
     private readonly changeFeed;
     constructor(pool: ReportingPgPool, options?: PostgresReportingLedgerStoreOptions);
+    /** Whether this store writes the host change feed (`changeFeed: true`). */
+    get changeFeedEnabled(): boolean;
+    /**
+     * Delete expired cursor snapshots and changes checkpoints, a bounded batch
+     * at a time. The store-bound form of `sweepExpiredReportingLedgerState`, for
+     * hosts that hold the store but not the pool.
+     */
+    sweepExpiredState(limit?: number): Promise<{
+        snapshotsDeleted: number;
+        checkpointsDeleted: number;
+    }>;
     /** Append one host change-feed row inside the caller's account-locked transaction. */
     private appendChange;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */

package/dist/lib/reporting/ledger/postgres.d.ts

@@ -137,6 +137,17 @@ export declare class PostgresReportingLedgerStore implements ReportingLedgerStor
     private readonly rowStorageWrites;
     private readonly changeFeed;
     constructor(pool: ReportingPgPool, options?: PostgresReportingLedgerStoreOptions);
+    /** Whether this store writes the host change feed (`changeFeed: true`). */
+    get changeFeedEnabled(): boolean;
+    /**
+     * Delete expired cursor snapshots and changes checkpoints, a bounded batch
+     * at a time. The store-bound form of `sweepExpiredReportingLedgerState`, for
+     * hosts that hold the store but not the pool.
+     */
+    sweepExpiredState(limit?: number): Promise<{
+        snapshotsDeleted: number;
+        checkpointsDeleted: number;
+    }>;
     /** Append one host change-feed row inside the caller's account-locked transaction. */
     private appendChange;
     /** Probe and register row storage when enabled. Safe to call repeatedly. */

package/dist/lib/reporting/ledger/postgres.js

@@ -424,6 +424,18 @@ class PostgresReportingLedgerStore {
   rowStorage;
   rowStorageWrites;
   changeFeed;
+  /** Whether this store writes the host change feed (`changeFeed: true`). */
+  get changeFeedEnabled() {
+    return this.changeFeed;
+  }
+  /**
+   * Delete expired cursor snapshots and changes checkpoints, a bounded batch
+   * at a time. The store-bound form of `sweepExpiredReportingLedgerState`, for
+   * hosts that hold the store but not the pool.
+   */
+  async sweepExpiredState(limit = 1e3) {
+    return sweepExpiredReportingLedgerState(this.pool, limit);
+  }
   /** Append one host change-feed row inside the caller's account-locked transaction. */
   async appendChange(client, kind, accountId, recordId, obligationId) {
     if (!this.changeFeed) return;

package/dist/lib/reporting/ledger/postgres.mjs

@@ -423,6 +423,18 @@ class PostgresReportingLedgerStore {
   rowStorage;
   rowStorageWrites;
   changeFeed;
+  /** Whether this store writes the host change feed (`changeFeed: true`). */
+  get changeFeedEnabled() {
+    return this.changeFeed;
+  }
+  /**
+   * Delete expired cursor snapshots and changes checkpoints, a bounded batch
+   * at a time. The store-bound form of `sweepExpiredReportingLedgerState`, for
+   * hosts that hold the store but not the pool.
+   */
+  async sweepExpiredState(limit = 1e3) {
+    return sweepExpiredReportingLedgerState(this.pool, limit);
+  }
   /** Append one host change-feed row inside the caller's account-locked transaction. */
   async appendChange(client, kind, accountId, recordId, obligationId) {
     if (!this.changeFeed) return;

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

@@ -6,6 +6,7 @@ import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '.
 import { type CreatePostgresPersistentNotificationRuntimeOptions, type PostgresPersistentNotificationRuntime } from '../../server/notification-subscriptions/index.mjs';
 import { REPORTING_LEDGER_MIGRATION, PostgresReportingLedgerStore, PostgresReportingManagedDeliveryStore, type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingManagedDeliveryAdapterV1, type ReportingManagedDeliveryRuntimeV1, type PostgresReportingManagedDeliveryStoreOptions, type PostgresReportingNotificationActivityOptions, type PostgresReportingNotificationActivityRuntime, type ReportingPgPool, type ReportingRowStorageOptionsV1, type ReportingSourceWithReaderV1 } from '../ledger/index.mjs';
 import { type PostgresReportingWebhookActivityV1 } from '../webhook-activity.mjs';
+import { type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1 } from './maintenance.mjs';
 import type { InlineReportingReplayRetentionV1 } from '../source/index.mjs';
 import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source/index.mjs';
 /** The intentionally small provider boundary: one bounded slice fetch plus immutable metadata. */
@@ -149,6 +150,29 @@ export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<strin
     /** Ledger metadata retention commitment advertised to buyers. */
     statusRetentionDays: number;
     subscribers?: CreateReportingProducerOptionsV1['subscribers'];
+    /**
+     * Opt in to scheduled ledger maintenance for a Core-only deployment on a
+     * `PostgresReportingLedgerStore`. `start()` runs it at most once per
+     * `intervalMilliseconds`; `runMaintenance()` runs it on demand for a host
+     * with its own scheduler. The production service does this itself and does
+     * not take this option.
+     *
+     * Always swept: expired cursor snapshots and checkpoints, and abandoned row
+     * uploads. `retention` and `changeFeed` have the same shape and meaning as
+     * on `createPostgresReliableReportingProductionService`. Retention uses
+     * this service's `statusRetentionDays`, so it can never retire a period
+     * earlier than the retention advertised to buyers. `changeFeed` requires the
+     * store to be built with `changeFeed: true`.
+     */
+    maintenance?: ReliableReportingMaintenanceOptionsV1;
+}
+export interface ReliableReportingMaintenanceOptionsV1 {
+    /** Minimum time between scheduled maintenance passes. Defaults to 300000 (5 minutes). */
+    intervalMilliseconds?: number;
+    /** Period-aligned retention; see the production service's `retention`. */
+    retention?: ReportingRetentionOptionsV1;
+    /** Change-feed pruning and consumer hold; see the production service's `changeFeed`. */
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
 }
 export interface ReliableReportingSetupV1 {
     readonly component: 'reliable-reporting-core';
@@ -179,6 +203,14 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
         notReady: number;
         failed: number;
     }>;
+    /**
+     * Run one ledger-maintenance pass now and return each task's outcome. For
+     * hosts that run their own scheduler instead of `start()`. A task failure is
+     * reported in its result, not thrown. Requires the `maintenance` option.
+     */
+    runMaintenance(options?: {
+        signal?: AbortSignal;
+    }): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
     start(options: ReliableReportingSchedulerOptionsV1): void;
     stop(): Promise<void>;
 }
@@ -188,7 +220,7 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
  */
 export declare function createReliableReportingService<TCtxMeta = Record<string, unknown>>(options: CreateReliableReportingServiceOptionsV1<TCtxMeta>): ReliableReportingServiceV1<TCtxMeta>;
 type ProductionNotificationOptions = Omit<CreatePostgresPersistentNotificationRuntimeOptions, 'db' | 'publisherScope' | 'checkpointDeliveryAttempt' | 'supportedAccountEventTypes'>;
-export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta = Record<string, unknown>> = Omit<CreateReliableReportingServiceOptionsV1<TCtxMeta>, 'store' | 'subscribers'> & {
+export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta = Record<string, unknown>> = Omit<CreateReliableReportingServiceOptionsV1<TCtxMeta>, 'store' | 'subscribers' | 'maintenance'> & {
     db: ReportingPgPool;
     /** Stable, non-secret deployment namespace shared by reporting workers. */
     namespace: string;
@@ -211,11 +243,7 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * period is also held until every live registered feed consumer (updated
      * within `changeFeed.maxFeedHoldDays`, default 7) has read its changes.
      */
-    retention?: {
-        enabled: true;
-        recordRetentionDays?: number;
-        limit?: number;
-    };
+    retention?: ReportingRetentionOptionsV1;
     /**
      * Maintain the host change feed (`changesAfter`, `getCurrentRevision`,
      * `listCurrentRevisions` on `stores.core`). Adds
@@ -223,10 +251,7 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * changes older than `changeRetentionDays` (default 30) unless a registered
      * consumer updated within `maxFeedHoldDays` (default 7) still needs them.
      */
-    changeFeed?: boolean | {
-        changeRetentionDays?: number;
-        maxFeedHoldDays?: number;
-    };
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
     notifications: ProductionNotificationOptions;
     managedDelivery: {
         adapter: ReportingManagedDeliveryAdapterV1;
@@ -304,14 +329,4 @@ export interface PostgresReliableReportingProductionServiceV1<TCtxMeta = Record<
  */
 export declare function createPostgresReliableReportingProductionService<TCtxMeta = Record<string, unknown>>(options: CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta>): Promise<PostgresReliableReportingProductionServiceV1<TCtxMeta>>;
 export * from './conformance.mjs';
-/**
- * A scheduled maintenance pass completed but could not process some items
- * (for example, a retention period whose objects could not be deleted). The
- * pass resumes them next time; repeated reports need operator attention.
- */
-export declare class ReportingMaintenancePartialFailureError extends Error {
-    readonly task: string;
-    readonly failedCount: number;
-    readonly failedIds: readonly string[];
-    constructor(task: string, failedCount: number, failedIds: readonly string[]);
-}
+export { ReportingMaintenancePartialFailureError, type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceStoreV1, type ReportingLedgerMaintenanceTaskNameV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1, } from './maintenance.mjs';

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

@@ -6,6 +6,7 @@ import type { ReportingDeliveryCapabilities, ReportingDeliveryOffering } from '.
 import { type CreatePostgresPersistentNotificationRuntimeOptions, type PostgresPersistentNotificationRuntime } from '../../server/notification-subscriptions';
 import { REPORTING_LEDGER_MIGRATION, PostgresReportingLedgerStore, PostgresReportingManagedDeliveryStore, type CreateReportingProducerOptionsV1, type ReportingConsumerMismatchEscalationV1, type ReportingLedgerConfigurationV1, type ReportingLedgerStore, type ReportingProducerContactV1, type ReportingProducerV1, type ReportingManagedDeliveryAdapterV1, type ReportingManagedDeliveryRuntimeV1, type PostgresReportingManagedDeliveryStoreOptions, type PostgresReportingNotificationActivityOptions, type PostgresReportingNotificationActivityRuntime, type ReportingPgPool, type ReportingRowStorageOptionsV1, type ReportingSourceWithReaderV1 } from '../ledger';
 import { type PostgresReportingWebhookActivityV1 } from '../webhook-activity';
+import { type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1 } from './maintenance';
 import type { InlineReportingReplayRetentionV1 } from '../source';
 import { type InlineReportingDeliveryFetchV1, type ReportingSourceOfferingV1 } from '../source';
 /** The intentionally small provider boundary: one bounded slice fetch plus immutable metadata. */
@@ -149,6 +150,29 @@ export interface CreateReliableReportingServiceOptionsV1<TCtxMeta = Record<strin
     /** Ledger metadata retention commitment advertised to buyers. */
     statusRetentionDays: number;
     subscribers?: CreateReportingProducerOptionsV1['subscribers'];
+    /**
+     * Opt in to scheduled ledger maintenance for a Core-only deployment on a
+     * `PostgresReportingLedgerStore`. `start()` runs it at most once per
+     * `intervalMilliseconds`; `runMaintenance()` runs it on demand for a host
+     * with its own scheduler. The production service does this itself and does
+     * not take this option.
+     *
+     * Always swept: expired cursor snapshots and checkpoints, and abandoned row
+     * uploads. `retention` and `changeFeed` have the same shape and meaning as
+     * on `createPostgresReliableReportingProductionService`. Retention uses
+     * this service's `statusRetentionDays`, so it can never retire a period
+     * earlier than the retention advertised to buyers. `changeFeed` requires the
+     * store to be built with `changeFeed: true`.
+     */
+    maintenance?: ReliableReportingMaintenanceOptionsV1;
+}
+export interface ReliableReportingMaintenanceOptionsV1 {
+    /** Minimum time between scheduled maintenance passes. Defaults to 300000 (5 minutes). */
+    intervalMilliseconds?: number;
+    /** Period-aligned retention; see the production service's `retention`. */
+    retention?: ReportingRetentionOptionsV1;
+    /** Change-feed pruning and consumer hold; see the production service's `changeFeed`. */
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
 }
 export interface ReliableReportingSetupV1 {
     readonly component: 'reliable-reporting-core';
@@ -179,6 +203,14 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
         notReady: number;
         failed: number;
     }>;
+    /**
+     * Run one ledger-maintenance pass now and return each task's outcome. For
+     * hosts that run their own scheduler instead of `start()`. A task failure is
+     * reported in its result, not thrown. Requires the `maintenance` option.
+     */
+    runMaintenance(options?: {
+        signal?: AbortSignal;
+    }): Promise<ReportingLedgerMaintenanceTaskResultV1[]>;
     start(options: ReliableReportingSchedulerOptionsV1): void;
     stop(): Promise<void>;
 }
@@ -188,7 +220,7 @@ export interface ReliableReportingServiceV1<TCtxMeta = Record<string, unknown>>
  */
 export declare function createReliableReportingService<TCtxMeta = Record<string, unknown>>(options: CreateReliableReportingServiceOptionsV1<TCtxMeta>): ReliableReportingServiceV1<TCtxMeta>;
 type ProductionNotificationOptions = Omit<CreatePostgresPersistentNotificationRuntimeOptions, 'db' | 'publisherScope' | 'checkpointDeliveryAttempt' | 'supportedAccountEventTypes'>;
-export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta = Record<string, unknown>> = Omit<CreateReliableReportingServiceOptionsV1<TCtxMeta>, 'store' | 'subscribers'> & {
+export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta = Record<string, unknown>> = Omit<CreateReliableReportingServiceOptionsV1<TCtxMeta>, 'store' | 'subscribers' | 'maintenance'> & {
     db: ReportingPgPool;
     /** Stable, non-secret deployment namespace shared by reporting workers. */
     namespace: string;
@@ -211,11 +243,7 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * period is also held until every live registered feed consumer (updated
      * within `changeFeed.maxFeedHoldDays`, default 7) has read its changes.
      */
-    retention?: {
-        enabled: true;
-        recordRetentionDays?: number;
-        limit?: number;
-    };
+    retention?: ReportingRetentionOptionsV1;
     /**
      * Maintain the host change feed (`changesAfter`, `getCurrentRevision`,
      * `listCurrentRevisions` on `stores.core`). Adds
@@ -223,10 +251,7 @@ export type CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta =
      * changes older than `changeRetentionDays` (default 30) unless a registered
      * consumer updated within `maxFeedHoldDays` (default 7) still needs them.
      */
-    changeFeed?: boolean | {
-        changeRetentionDays?: number;
-        maxFeedHoldDays?: number;
-    };
+    changeFeed?: ReportingChangeFeedMaintenanceOptionsV1;
     notifications: ProductionNotificationOptions;
     managedDelivery: {
         adapter: ReportingManagedDeliveryAdapterV1;
@@ -304,14 +329,4 @@ export interface PostgresReliableReportingProductionServiceV1<TCtxMeta = Record<
  */
 export declare function createPostgresReliableReportingProductionService<TCtxMeta = Record<string, unknown>>(options: CreatePostgresReliableReportingProductionServiceOptionsV1<TCtxMeta>): Promise<PostgresReliableReportingProductionServiceV1<TCtxMeta>>;
 export * from './conformance';
-/**
- * A scheduled maintenance pass completed but could not process some items
- * (for example, a retention period whose objects could not be deleted). The
- * pass resumes them next time; repeated reports need operator attention.
- */
-export declare class ReportingMaintenancePartialFailureError extends Error {
-    readonly task: string;
-    readonly failedCount: number;
-    readonly failedIds: readonly string[];
-    constructor(task: string, failedCount: number, failedIds: readonly string[]);
-}
+export { ReportingMaintenancePartialFailureError, type ReportingChangeFeedMaintenanceOptionsV1, type ReportingLedgerMaintenanceStoreV1, type ReportingLedgerMaintenanceTaskNameV1, type ReportingLedgerMaintenanceTaskResultV1, type ReportingRetentionOptionsV1, } from './maintenance';

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

@@ -19,7 +19,7 @@ var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "defau
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var service_exports = {};
 __export(service_exports, {
-  ReportingMaintenancePartialFailureError: () => ReportingMaintenancePartialFailureError,
+  ReportingMaintenancePartialFailureError: () => import_maintenance2.ReportingMaintenancePartialFailureError,
   createPostgresReliableReportingProductionService: () => createPostgresReliableReportingProductionService,
   createReliableReportingService: () => createReliableReportingService
 });
@@ -31,11 +31,14 @@ var import_schemas = require('../../types/schemas.generated.js');
 var import_notification_subscriptions = require('../../server/notification-subscriptions/index.js');
 var import_ledger = require('../ledger/index.js');
 var import_webhook_activity = require('../webhook-activity.js');
+var import_maintenance = require('./maintenance.js');
 var import_schedule = require('../ledger/schedule.js');
 var import_source = require('../source/index.js');
 __reExport(service_exports, require('./conformance.js'), module.exports);
+var import_maintenance2 = require('./maintenance.js');
 const ADAPTER_SCOPE_KEY = "_adcp_reporting_adapter";
 const PRODUCTION_MANAGED_COMPOSITION = /* @__PURE__ */ Symbol("production-managed-reporting-composition");
+const DEFAULT_MAINTENANCE_INTERVAL_MILLISECONDS = 3e5;
 function createReliableReportingService(options) {
   const allowManagedDelivery = options[PRODUCTION_MANAGED_COMPOSITION] === true;
   const adapterEntries = Object.entries(options.adapters);
@@ -97,6 +100,42 @@ function createReliableReportingService(options) {
   if (hasConsumerStatus) assertConsumerStatusStore(options.store);
   const retentionDays = options.statusRetentionDays;
   positiveInteger(retentionDays, "statusRetentionDays");
+  const maintenance = options.maintenance;
+  let maintenanceStore;
+  let maintenanceIntervalMilliseconds = DEFAULT_MAINTENANCE_INTERVAL_MILLISECONDS;
+  if (maintenance !== void 0) {
+    if (maintenance === null || typeof maintenance !== "object") {
+      throw new TypeError("maintenance must be an options object");
+    }
+    const candidate = options.store;
+    for (const method of ["retireExpiredPeriods", "pruneChanges", "sweepRowWriteIntents"]) {
+      if (typeof candidate[method] !== "function") {
+        throw new TypeError(
+          `maintenance requires a PostgresReportingLedgerStore (or a store with ${method}); the configured store cannot run ledger maintenance`
+        );
+      }
+    }
+    maintenanceStore = candidate;
+    if (maintenance.changeFeed && maintenanceStore.changeFeedEnabled === false) {
+      throw new TypeError(
+        "maintenance.changeFeed requires the store to be built with changeFeed: true; otherwise pruning silently does nothing"
+      );
+    }
+    if (maintenance.intervalMilliseconds !== void 0) {
+      positiveInteger(maintenance.intervalMilliseconds, "maintenance.intervalMilliseconds");
+      maintenanceIntervalMilliseconds = maintenance.intervalMilliseconds;
+    }
+    (0, import_maintenance.assertReportingLedgerMaintenanceOptions)(maintenance, retentionDays);
+  }
+  const runLedgerMaintenance = (signal, report) => (0, import_maintenance.runReportingLedgerMaintenance)({
+    store: maintenanceStore,
+    ...typeof maintenanceStore.sweepExpiredState === "function" ? { sweepSnapshots: (limit) => maintenanceStore.sweepExpiredState(limit) } : {},
+    statusRetentionDays: retentionDays,
+    retention: maintenance.retention,
+    changeFeed: maintenance.changeFeed,
+    signal,
+    ...report ? { report } : {}
+  });
   const capabilities = deepFreeze({
     supported: true,
     reliable_reporting_version: "1.0",
@@ -269,12 +308,26 @@ function createReliableReportingService(options) {
       });
       return { planned: planned.length, ...result };
     },
+    async runMaintenance(maintenanceOptions) {
+      if (maintenance === void 0) {
+        throw new TypeError("runMaintenance requires the maintenance option");
+      }
+      maintenanceOptions?.signal?.throwIfAborted();
+      return runLedgerMaintenance(maintenanceOptions?.signal);
+    },
     start(scheduler) {
       if (schedulerPromise) throw new Error("Reliable reporting scheduler is already running");
       positiveInteger(scheduler.intervalMilliseconds, "intervalMilliseconds");
       schedulerAbort = new AbortController();
       const signal = schedulerAbort.signal;
-      schedulerPromise = schedulerLoop(service, scheduler, signal, options.store).finally(() => {
+      const scheduledMaintenance = maintenance === void 0 ? void 0 : {
+        intervalMilliseconds: maintenanceIntervalMilliseconds,
+        run: () => runLedgerMaintenance(
+          signal,
+          (error) => reportSchedulerError(scheduler, signal, error, { phase: "maintenance" })
+        )
+      };
+      schedulerPromise = schedulerLoop(service, scheduler, signal, options.store, scheduledMaintenance).finally(() => {
         schedulerPromise = void 0;
         schedulerAbort = void 0;
       });
@@ -506,53 +559,15 @@ async function createPostgresReliableReportingProductionService(options) {
     for (const result of pruneResults) {
       if (result.status === "rejected" && !signal.aborted) await reportAuxiliaryError(scheduler, result.reason);
     }
-    const ledgerMaintenance = [
-      ["snapshot sweep", (0, import_ledger.sweepExpiredReportingLedgerState)(options.db, 1e3)],
-      ["row upload sweep", coreStore.sweepRowWriteIntents({ limit: 100, signal })],
-      ...options.changeFeed ? [
-        [
-          "change-feed pruning",
-          coreStore.pruneChanges(
-            typeof options.changeFeed === "object" ? {
-              ...options.changeFeed.changeRetentionDays !== void 0 ? { changeRetentionDays: options.changeFeed.changeRetentionDays } : {},
-              ...options.changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: options.changeFeed.maxFeedHoldDays } : {}
-            } : {}
-          )
-        ]
-      ] : [],
-      ...options.retention?.enabled ? [
-        [
-          "retention",
-          coreStore.retireExpiredPeriods({
-            statusRetentionDays: options.statusRetentionDays,
-            ...options.retention.recordRetentionDays !== void 0 ? { recordRetentionDays: options.retention.recordRetentionDays } : {},
-            ...typeof options.changeFeed === "object" && options.changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: options.changeFeed.maxFeedHoldDays } : {},
-            limit: options.retention.limit ?? 100,
-            signal
-          })
-        ]
-      ] : []
-    ];
-    const maintenanceResults = await Promise.allSettled(ledgerMaintenance.map(([, task]) => task));
-    for (const [index, result] of maintenanceResults.entries()) {
-      const name = ledgerMaintenance[index][0];
-      if (result.status === "rejected") {
-        if (!signal.aborted) await reportAuxiliaryError(scheduler, result.reason);
-        continue;
-      }
-      const value = result.value;
-      const failed = Array.isArray(value?.failed) ? value.failed.length : typeof value?.failed === "number" ? value.failed : 0;
-      if (failed > 0 && !signal.aborted) {
-        await reportAuxiliaryError(
-          scheduler,
-          new ReportingMaintenancePartialFailureError(
-            name,
-            failed,
-            value?.failures?.length ? value.failures.map((entry) => `${entry.reporting_obligation_id} (${entry.cause})`) : Array.isArray(value?.failed) ? value.failed : []
-          )
-        );
-      }
-    }
+    await (0, import_maintenance.runReportingLedgerMaintenance)({
+      store: coreStore,
+      sweepSnapshots: (limit) => (0, import_ledger.sweepExpiredReportingLedgerState)(options.db, limit),
+      statusRetentionDays: options.statusRetentionDays,
+      retention: options.retention,
+      changeFeed: options.changeFeed,
+      signal,
+      report: (error) => reportAuxiliaryError(scheduler, error)
+    });
     const accountIds = rotate(await deploymentWideAccountIds(coreStore), auxiliaryRotation);
     auxiliaryRotation += 1;
     for (const accountId of accountIds) {
@@ -678,8 +693,9 @@ function routeSource(sources, sourceScope) {
   if (!source) throw new TypeError("Reporting sourceScope has no installed adapter route");
   return source;
 }
-async function schedulerLoop(service, options, signal, store) {
+async function schedulerLoop(service, options, signal, store, maintenance) {
   let rotation = 0;
+  let lastMaintenanceAt;
   while (!signal.aborted) {
     let accountIds = [];
     try {
@@ -716,6 +732,14 @@ async function schedulerLoop(service, options, signal, store) {
         await reportSchedulerError(options, signal, error, { phase: "cycle", accountId });
       }
     }
+    if (maintenance && !signal.aborted && (lastMaintenanceAt === void 0 || Date.now() - lastMaintenanceAt >= maintenance.intervalMilliseconds)) {
+      lastMaintenanceAt = Date.now();
+      try {
+        await maintenance.run();
+      } catch (error) {
+        await reportSchedulerError(options, signal, error, { phase: "maintenance" });
+      }
+    }
     if (!signal.aborted) await abortableDelay(options.intervalMilliseconds, signal);
   }
 }
@@ -732,7 +756,7 @@ async function reportSchedulerError(options, signal, error, site) {
   warnSchedulerFailure(options, site, error);
 }
 function warnSchedulerFailure(options, site, error, observerError) {
-  const where = site.phase === "roster" ? "could not resolve its account roster, so this pass ran no tenants" : site.accountId === void 0 ? "deployment-wide cycle failed; the scheduler continues" : `cycle failed for account ${site.accountId}; later tenants continue`;
+  const where = site.phase === "roster" ? "could not resolve its account roster, so this pass ran no tenants" : site.phase === "maintenance" ? "ledger maintenance failed; the scheduler continues" : site.accountId === void 0 ? "deployment-wide cycle failed; the scheduler continues" : `cycle failed for account ${site.accountId}; later tenants continue`;
   const observed = observerError === void 0 ? "" : ` (the configured onError also threw: ${safeMessage(observerError)})`;
   const message = `[adcp/reporting] scheduler ${where}: ${safeMessage(error)}${observed}`;
   const logger = options.logger;
@@ -1200,20 +1224,6 @@ function deepFreeze(value) {
   }
   return value;
 }
-class ReportingMaintenancePartialFailureError extends Error {
-  constructor(task, failedCount, failedIds) {
-    super(
-      `Reporting ${task} could not process ${failedCount} item(s)${failedIds.length ? `: ${failedIds.slice(0, 20).join(", ")}` : ""}`
-    );
-    this.task = task;
-    this.failedCount = failedCount;
-    this.failedIds = failedIds;
-    this.name = "ReportingMaintenancePartialFailureError";
-  }
-  task;
-  failedCount;
-  failedIds;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ReportingMaintenancePartialFailureError,