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

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

@@ -1,185 +0,0 @@
-"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 maintenance_exports = {};
-__export(maintenance_exports, {
-  ReportingMaintenancePartialFailureError: () => ReportingMaintenancePartialFailureError,
-  assertReportingLedgerMaintenanceOptions: () => assertReportingLedgerMaintenanceOptions,
-  runReportingLedgerMaintenance: () => runReportingLedgerMaintenance
-});
-module.exports = __toCommonJS(maintenance_exports);
-class ReportingMaintenancePartialFailureError extends Error {
-  constructor(task, failedCount, failedIds, warnings = []) {
-    super(
-      (failedCount > 0 ? `Reporting ${task} could not process ${failedCount} item(s)${failedIds.length ? `: ${failedIds.slice(0, 20).join(", ")}` : ""}` : `Reporting ${task} needs attention`) + (warnings.length ? `${failedCount > 0 ? "; " : ": "}${warnings.join("; ")}` : "")
-    );
-    this.task = task;
-    this.failedCount = failedCount;
-    this.failedIds = failedIds;
-    this.warnings = warnings;
-    this.name = "ReportingMaintenancePartialFailureError";
-  }
-  task;
-  failedCount;
-  failedIds;
-  warnings;
-}
-async function runReportingLedgerMaintenance(input) {
-  const { store, signal, changeFeed, retention, compaction } = input;
-  const start = (name, run) => {
-    try {
-      return [name, run()];
-    } catch (error) {
-      return [name, Promise.reject(error)];
-    }
-  };
-  const tasks = [
-    ...input.sweepSnapshots ? [start("snapshot sweep", () => input.sweepSnapshots(1e3))] : [],
-    start("row upload sweep", () => store.sweepRowWriteIntents({ limit: 100, ...signal ? { signal } : {} })),
-    ...changeFeed ? [
-      start(
-        "change-feed pruning",
-        () => store.pruneChanges(
-          typeof changeFeed === "object" ? {
-            ...changeFeed.changeRetentionDays !== void 0 ? { changeRetentionDays: changeFeed.changeRetentionDays } : {},
-            ...changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {}
-          } : {}
-        )
-      )
-    ] : [],
-    ...retention?.enabled ? [
-      start(
-        "retention",
-        () => store.retireExpiredPeriods({
-          statusRetentionDays: input.statusRetentionDays,
-          ...retention.recordRetentionDays !== void 0 ? { recordRetentionDays: retention.recordRetentionDays } : {},
-          ...typeof changeFeed === "object" && changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {},
-          limit: retention.limit ?? 100,
-          ...signal ? { signal } : {}
-        })
-      )
-    ] : [],
-    ...compaction?.enabled ? [
-      start("snapshot compaction", () => {
-        if (typeof store.compactSupersededSnapshots !== "function") {
-          throw new TypeError("compaction requires a store with compactSupersededSnapshots");
-        }
-        if (input.automatedRecoveryWindowSeconds === void 0) {
-          throw new TypeError("compaction requires automatedRecoveryWindowSeconds");
-        }
-        return store.compactSupersededSnapshots({
-          statusRetentionDays: input.statusRetentionDays,
-          automatedRecoveryWindowSeconds: input.automatedRecoveryWindowSeconds,
-          ...typeof changeFeed === "object" && changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {},
-          limit: compaction.limit ?? 100,
-          ...signal ? { signal } : {}
-        });
-      })
-    ] : []
-  ];
-  const settled = await Promise.allSettled(tasks.map(([, task]) => task));
-  const results = [];
-  for (const [index, outcome] of settled.entries()) {
-    const name = tasks[index][0];
-    if (outcome.status === "rejected") {
-      if (!signal?.aborted) await input.report?.(outcome.reason);
-      results.push({ task: name, status: "failed", error: outcome.reason });
-      continue;
-    }
-    const value = outcome.value;
-    const failed = Array.isArray(value?.failed) ? value.failed.length : typeof value?.failed === "number" ? value.failed : 0;
-    const warnings = [];
-    if (value?.stuck?.length) {
-      warnings.push(
-        `${value.stuck.length} period(s) keep failing: ${value.stuck.slice(0, 20).map((entry) => `${entry.reporting_obligation_id} (${entry.cause}, ${entry.attempts} attempts)`).join(", ")}`
-      );
-    }
-    if (typeof value?.deferred === "number" && value.deferred > 0) {
-      warnings.push(`${value.deferred} item(s) backing off after a failure`);
-    }
-    if (typeof value?.skippedUnconfigured === "number" && value.skippedUnconfigured > 0) {
-      warnings.push(
-        `${value.skippedUnconfigured} expired upload(s) skipped because this host does not configure their row binding`
-      );
-    }
-    if (typeof value?.overdue === "number" && value.overdue > 0) {
-      warnings.push(
-        `${value.overdue} upload(s) expired long ago and still unswept; their objects are leaking (check that a host configures their binding and that provider deletes succeed)`
-      );
-    }
-    let partialFailure;
-    if (failed > 0 || warnings.length > 0) {
-      partialFailure = new ReportingMaintenancePartialFailureError(
-        name,
-        failed,
-        value?.failures?.length ? value.failures.map((entry) => `${entry.reporting_obligation_id} (${entry.cause})`) : Array.isArray(value?.failed) ? value.failed : [],
-        warnings
-      );
-      if (!signal?.aborted) await input.report?.(partialFailure);
-    }
-    results.push({
-      task: name,
-      status: "completed",
-      result: outcome.value,
-      ...partialFailure ? { partialFailure } : {}
-    });
-  }
-  return results;
-}
-function assertReportingLedgerMaintenanceOptions(input, statusRetentionDays) {
-  const positive = (value, field) => {
-    if (!Number.isSafeInteger(value) || value <= 0) {
-      throw new TypeError(`${field} must be a positive safe integer`);
-    }
-  };
-  const { retention, changeFeed, compaction } = input;
-  if (compaction !== void 0) {
-    if (compaction === null || typeof compaction !== "object" || compaction.enabled !== true) {
-      throw new TypeError("maintenance.compaction must be { enabled: true, ... }");
-    }
-    if (compaction.limit !== void 0) positive(compaction.limit, "maintenance.compaction.limit");
-  }
-  if (retention !== void 0) {
-    if (retention === null || typeof retention !== "object" || retention.enabled !== true) {
-      throw new TypeError("maintenance.retention must be { enabled: true, ... }");
-    }
-    if (retention.recordRetentionDays !== void 0) {
-      positive(retention.recordRetentionDays, "maintenance.retention.recordRetentionDays");
-      if (retention.recordRetentionDays < statusRetentionDays) {
-        throw new RangeError(
-          "maintenance.retention.recordRetentionDays must be no shorter than statusRetentionDays, the retention advertised to buyers"
-        );
-      }
-    }
-    if (retention.limit !== void 0) positive(retention.limit, "maintenance.retention.limit");
-  }
-  if (typeof changeFeed === "object" && changeFeed !== null) {
-    if (changeFeed.changeRetentionDays !== void 0) {
-      positive(changeFeed.changeRetentionDays, "maintenance.changeFeed.changeRetentionDays");
-    }
-    if (changeFeed.maxFeedHoldDays !== void 0) {
-      positive(changeFeed.maxFeedHoldDays, "maintenance.changeFeed.maxFeedHoldDays");
-    }
-  }
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ReportingMaintenancePartialFailureError,
-  assertReportingLedgerMaintenanceOptions,
-  runReportingLedgerMaintenance
-});

package/dist/lib/reporting/service/maintenance.mjs

@@ -1,159 +0,0 @@
-class ReportingMaintenancePartialFailureError extends Error {
-  constructor(task, failedCount, failedIds, warnings = []) {
-    super(
-      (failedCount > 0 ? `Reporting ${task} could not process ${failedCount} item(s)${failedIds.length ? `: ${failedIds.slice(0, 20).join(", ")}` : ""}` : `Reporting ${task} needs attention`) + (warnings.length ? `${failedCount > 0 ? "; " : ": "}${warnings.join("; ")}` : "")
-    );
-    this.task = task;
-    this.failedCount = failedCount;
-    this.failedIds = failedIds;
-    this.warnings = warnings;
-    this.name = "ReportingMaintenancePartialFailureError";
-  }
-  task;
-  failedCount;
-  failedIds;
-  warnings;
-}
-async function runReportingLedgerMaintenance(input) {
-  const { store, signal, changeFeed, retention, compaction } = input;
-  const start = (name, run) => {
-    try {
-      return [name, run()];
-    } catch (error) {
-      return [name, Promise.reject(error)];
-    }
-  };
-  const tasks = [
-    ...input.sweepSnapshots ? [start("snapshot sweep", () => input.sweepSnapshots(1e3))] : [],
-    start("row upload sweep", () => store.sweepRowWriteIntents({ limit: 100, ...signal ? { signal } : {} })),
-    ...changeFeed ? [
-      start(
-        "change-feed pruning",
-        () => store.pruneChanges(
-          typeof changeFeed === "object" ? {
-            ...changeFeed.changeRetentionDays !== void 0 ? { changeRetentionDays: changeFeed.changeRetentionDays } : {},
-            ...changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {}
-          } : {}
-        )
-      )
-    ] : [],
-    ...retention?.enabled ? [
-      start(
-        "retention",
-        () => store.retireExpiredPeriods({
-          statusRetentionDays: input.statusRetentionDays,
-          ...retention.recordRetentionDays !== void 0 ? { recordRetentionDays: retention.recordRetentionDays } : {},
-          ...typeof changeFeed === "object" && changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {},
-          limit: retention.limit ?? 100,
-          ...signal ? { signal } : {}
-        })
-      )
-    ] : [],
-    ...compaction?.enabled ? [
-      start("snapshot compaction", () => {
-        if (typeof store.compactSupersededSnapshots !== "function") {
-          throw new TypeError("compaction requires a store with compactSupersededSnapshots");
-        }
-        if (input.automatedRecoveryWindowSeconds === void 0) {
-          throw new TypeError("compaction requires automatedRecoveryWindowSeconds");
-        }
-        return store.compactSupersededSnapshots({
-          statusRetentionDays: input.statusRetentionDays,
-          automatedRecoveryWindowSeconds: input.automatedRecoveryWindowSeconds,
-          ...typeof changeFeed === "object" && changeFeed.maxFeedHoldDays !== void 0 ? { maxFeedHoldDays: changeFeed.maxFeedHoldDays } : {},
-          limit: compaction.limit ?? 100,
-          ...signal ? { signal } : {}
-        });
-      })
-    ] : []
-  ];
-  const settled = await Promise.allSettled(tasks.map(([, task]) => task));
-  const results = [];
-  for (const [index, outcome] of settled.entries()) {
-    const name = tasks[index][0];
-    if (outcome.status === "rejected") {
-      if (!signal?.aborted) await input.report?.(outcome.reason);
-      results.push({ task: name, status: "failed", error: outcome.reason });
-      continue;
-    }
-    const value = outcome.value;
-    const failed = Array.isArray(value?.failed) ? value.failed.length : typeof value?.failed === "number" ? value.failed : 0;
-    const warnings = [];
-    if (value?.stuck?.length) {
-      warnings.push(
-        `${value.stuck.length} period(s) keep failing: ${value.stuck.slice(0, 20).map((entry) => `${entry.reporting_obligation_id} (${entry.cause}, ${entry.attempts} attempts)`).join(", ")}`
-      );
-    }
-    if (typeof value?.deferred === "number" && value.deferred > 0) {
-      warnings.push(`${value.deferred} item(s) backing off after a failure`);
-    }
-    if (typeof value?.skippedUnconfigured === "number" && value.skippedUnconfigured > 0) {
-      warnings.push(
-        `${value.skippedUnconfigured} expired upload(s) skipped because this host does not configure their row binding`
-      );
-    }
-    if (typeof value?.overdue === "number" && value.overdue > 0) {
-      warnings.push(
-        `${value.overdue} upload(s) expired long ago and still unswept; their objects are leaking (check that a host configures their binding and that provider deletes succeed)`
-      );
-    }
-    let partialFailure;
-    if (failed > 0 || warnings.length > 0) {
-      partialFailure = new ReportingMaintenancePartialFailureError(
-        name,
-        failed,
-        value?.failures?.length ? value.failures.map((entry) => `${entry.reporting_obligation_id} (${entry.cause})`) : Array.isArray(value?.failed) ? value.failed : [],
-        warnings
-      );
-      if (!signal?.aborted) await input.report?.(partialFailure);
-    }
-    results.push({
-      task: name,
-      status: "completed",
-      result: outcome.value,
-      ...partialFailure ? { partialFailure } : {}
-    });
-  }
-  return results;
-}
-function assertReportingLedgerMaintenanceOptions(input, statusRetentionDays) {
-  const positive = (value, field) => {
-    if (!Number.isSafeInteger(value) || value <= 0) {
-      throw new TypeError(`${field} must be a positive safe integer`);
-    }
-  };
-  const { retention, changeFeed, compaction } = input;
-  if (compaction !== void 0) {
-    if (compaction === null || typeof compaction !== "object" || compaction.enabled !== true) {
-      throw new TypeError("maintenance.compaction must be { enabled: true, ... }");
-    }
-    if (compaction.limit !== void 0) positive(compaction.limit, "maintenance.compaction.limit");
-  }
-  if (retention !== void 0) {
-    if (retention === null || typeof retention !== "object" || retention.enabled !== true) {
-      throw new TypeError("maintenance.retention must be { enabled: true, ... }");
-    }
-    if (retention.recordRetentionDays !== void 0) {
-      positive(retention.recordRetentionDays, "maintenance.retention.recordRetentionDays");
-      if (retention.recordRetentionDays < statusRetentionDays) {
-        throw new RangeError(
-          "maintenance.retention.recordRetentionDays must be no shorter than statusRetentionDays, the retention advertised to buyers"
-        );
-      }
-    }
-    if (retention.limit !== void 0) positive(retention.limit, "maintenance.retention.limit");
-  }
-  if (typeof changeFeed === "object" && changeFeed !== null) {
-    if (changeFeed.changeRetentionDays !== void 0) {
-      positive(changeFeed.changeRetentionDays, "maintenance.changeFeed.changeRetentionDays");
-    }
-    if (changeFeed.maxFeedHoldDays !== void 0) {
-      positive(changeFeed.maxFeedHoldDays, "maintenance.changeFeed.maxFeedHoldDays");
-    }
-  }
-}
-export {
-  ReportingMaintenancePartialFailureError,
-  assertReportingLedgerMaintenanceOptions,
-  runReportingLedgerMaintenance
-};

package/examples/reliable-reporting-service/README.md

@@ -1,169 +0,0 @@
-# Adapter-first Reliable Reporting Core
-
-This is the minimal production assembly. The provider adapter returns only
-real upstream results: `null` means not ready, `[]` is an observed zero-row
-period, and a populated response carries the provider's rows and temporal
-evidence. It never manufactures fallback delivery.
-
-```ts
-import { Pool } from 'pg';
-import { createAdcpServerFromPlatform } from '@adcp/sdk/server';
-import { PostgresReportingLedgerStore } from '@adcp/sdk/reporting/ledger';
-import { createReliableReportingService, type ReliableReportingAdapterV1 } from '@adcp/sdk/reporting/service';
-
-// Your provider integration owns these immutable declarations and the real
-// bounded API read. The fetch context contains only durable, non-secret
-// routing IDs; derive OAuth/bearer credentials inside the provider client.
-const providerAdapter: ReliableReportingAdapterV1 = {
-  sourceOffering: provider.reportingSourceOffering,
-  deliveryOffering: provider.reportingDeliveryOffering,
-  fetchSlice: (request, context) =>
-    provider.fetchReportingSlice(request, {
-      signal: context.signal,
-      networkId: String(context.sourceScope.network_id),
-    }),
-};
-
-const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-const reporting = createReliableReportingService({
-  store: new PostgresReportingLedgerStore(pool, {
-    acknowledgeIsolatedDatabase: true,
-  }),
-  adapters: { provider: providerAdapter },
-  contact: { name: 'Reporting operations', email: 'reporting@example.com' },
-  automatedRecoveryWindowSeconds: 86_400,
-  statusRetentionDays: 90, // enforce the same or longer retention in the ledger database
-  resolveSource: account => ({
-    adapterId: 'provider',
-    sourceScope: { network_id: account.ctx_metadata.provider.networkId },
-    sourceTimezone: account.ctx_metadata.provider.timezone,
-  }),
-  resolveCurrency: account => account.ctx_metadata.provider.currency,
-  // Authorization boundary: the constituents this account may report on, read
-  // from your booking system rather than echoed from the buyer's declaration.
-  resolveCoverage: async account => ({
-    constituents: await bookings.authorizedReportingConstituents(account.id),
-  }),
-  resolveConsumerId: ctx => {
-    if (!ctx.agent) throw new Error('Authenticated buyer-agent registry required');
-    return ctx.agent.agent_url;
-  },
-});
-
-await pool.query(reporting.setup.migrations[0]);
-const installedPlatform = reporting.install(platform);
-const server = createAdcpServerFromPlatform(installedPlatform, serverOptions);
-
-// Pick exactly one operational ownership model.
-reporting.start({
-  intervalMilliseconds: 60_000,
-  deploymentWide: true,
-  maxObligationsPerAccount: 500,
-  maxWorkerIterationsPerAccount: 100,
-  onError: error => operations.capture(error),
-});
-
-process.once('SIGTERM', async () => {
-  await reporting.stop();
-  await pool.end();
-});
-```
-
-For tenant-partitioned scheduling, replace `deploymentWide: true` with
-`accountIds: () => tenantDirectory.reportingAccountIds()`. A resolver must
-return an array; it can never fall back to a deployment-wide scan, and an
-empty or missing account ID is refused rather than widened. One account's
-failed cycle reaches `onError` without skipping the accounts behind it. Configure an
-authenticated `agentRegistry` before using the `ctx.agent` consumer identity
-shown above.
-
-`platform.accounts.upsert` must be installed: it is the native
-`sync_accounts` implementation advertised by the Core capability. Its
-authenticated reporting-configuration path calls `installConfiguration` as
-shown below.
-
-During authenticated `sync_accounts` handling, validate the requested
-offering and resolve its media-buy/package denominator, then call:
-
-```ts
-const frozen = await reporting.installConfiguration(resolvedConfiguration, {
-  account: ctx.account,
-});
-```
-
-`resolvedConfiguration` contains reporting semantics only: no account identity,
-source scope, source contract, timezone, currency, `constituents`, or
-`mediaBuyIds`. The denominator comes from `resolveCoverage`, so a buyer cannot
-name another buyer's media buys on a shared upstream network. The service derives those only from the already-resolved account.
-See [the ledger guide](../../docs/guides/REPORTING-LEDGER.md) for the complete
-input shape, per-account scheduling, migration from manual wiring, and the
-conformance helper.
-
-## Integrated seller production service
-
-For Managed Delivery and Reconciled Billing, compose the real provider,
-authorization, notification, and migration adapters in one probed service.
-The host-owned dependencies below must use live systems and bounded network
-timeouts; `applyMigrations` runs before any capability is published.
-
-```ts
-import { createPostgresReliableReportingProductionService } from '@adcp/sdk/reporting/service';
-
-const production = await createPostgresReliableReportingProductionService({
-  db: pool,
-  namespace: 'reporting-prod',
-  publisherScope: 'seller-prod',
-  acknowledgeIsolatedDatabase: true,
-  adapters: { provider: providerAdapter },
-  contact: { name: 'Reporting operations', email: 'reporting@example.com' },
-  automatedRecoveryWindowSeconds: 86_400,
-  statusRetentionDays: 90,
-  resolveSource: account => ({
-    adapterId: 'provider',
-    sourceScope: { network_id: account.ctx_metadata.provider.networkId },
-    sourceTimezone: account.ctx_metadata.provider.timezone,
-  }),
-  resolveCurrency: account => account.ctx_metadata.provider.currency,
-  resolveCoverage: async account => ({
-    constituents: await bookings.authorizedReportingConstituents(account.id),
-  }),
-  resolveConsumerId: ctx => buyerRegistry.requireAuthenticatedConsumerId(ctx),
-  obligatedConsumers: ({ reporting_obligation_id, account_id }) =>
-    billingRoster.obligatedConsumers(reporting_obligation_id, account_id),
-  notifications: {
-    subscriptions: { acknowledgeIsolatedDatabase: true },
-    webhooks: {
-      signerProvider: keyManager.reportingWebhookSigner(),
-      fetch: safeWebhookFetch, // enforce the SDK's pinned SSRF policy
-    },
-    proofAdapter: notificationAuthority.proofAdapter,
-    authorizeDelivery: notificationAuthority.authorizeDelivery,
-    validateDestination: notificationAuthority.validateDestination,
-  },
-  managedDelivery: {
-    adapter: provider.managedDeliveryAdapter,
-    resourceRetentionDays: 90,
-    authorizationRevocationSeconds: 3_600,
-  },
-  activity: { tenantScopeForAccount: accountId => accountDirectory.tenantFor(accountId) },
-  resolveWebhookActivityScope: ctx => accountDirectory.webhookActivityScope(ctx),
-  applyMigrations: statements => migrations.applyInOrder(statements),
-});
-
-const installedPlatform = production.install(platform); // accounts.upsert and accounts.list required
-const server = createAdcpServerFromPlatform(installedPlatform, serverOptions);
-production.start({ intervalMilliseconds: 60_000, deploymentWide: true });
-
-process.once('SIGTERM', async () => {
-  await production.stop();
-  await pool.end();
-});
-```
-
-Use one isolated namespace and publisher scope per independently operated
-tenant partition. The production worker's recovery passes scan that entire
-namespace, so `start()` and `recoverOnce()` require `deploymentWide: true`.
-The trusted `obligatedConsumers` roster is required when an offering uses
-`consumer_receipt`; an incomplete roster keeps billing health conservative.
-See the [production operations guide](../../docs/guides/REPORTING-OPERATIONS.md)
-for migration, readiness, and recovery procedures.