@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/reporting/ledger/notification-activity.d.mts

@@ -0,0 +1,222 @@
+import type { NotificationDeliveryAttemptCheckpointInput, PersistentNotificationRuntime } from '../../server/notification-subscriptions/index.mjs';
+import type { WebhookAttemptSuppressionReason } from '../../server/webhook-emitter.mjs';
+import type { ReportingHealthV1, ReportingLedgerNotificationActivityPortV1, ReportingLedgerObligationV1, ReportingLedgerTransactionV1, ReportingObservedFinalityV1 } from './types.mjs';
+export interface ReportingAccountActivityV1 {
+    activityId: string;
+    transitionId: string;
+    activityType: 'reporting.lifecycle_changed';
+    notificationType?: 'reporting.status_changed';
+    tenantId: string;
+    accountId: string;
+    reporting_obligation_id: string;
+    previousHealth: ReportingHealthV1;
+    health: ReportingHealthV1;
+    previousFinality: ReportingObservedFinalityV1;
+    finality: ReportingObservedFinalityV1;
+    issueIds: string[];
+    occurredAt: string;
+    correlation: {
+        delivery_config_id: string;
+        delivery_config_version: number;
+        report_definition_id: string;
+        feed_purpose: ReportingLedgerObligationV1['feedPurpose'];
+        period: {
+            start: string;
+            end: string;
+        };
+    };
+}
+export interface ReportingAccountActivityRecordV1 extends ReportingAccountActivityV1 {
+    recordedAt: string;
+    notificationProjectedAt?: string;
+    /** Set when the claim was bounded out of the pending set without delivering. */
+    notificationAbandonedAt?: string;
+}
+export interface ReportingAccountActivityPageV1 {
+    activities: ReportingAccountActivityRecordV1[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+export interface ReportingNotificationRecoveryMetricsV1 {
+    claimed: number;
+    matched: number;
+    projected: number;
+    retried: number;
+    leaseLost: number;
+    /** Claims bounded out of the pending set after `maxAttempts`; never delivered. */
+    abandoned: number;
+}
+/**
+ * Raised when live delivery authority failed closed for an operational reason
+ * rather than a deliberate one. The claim is released and retried; the activity
+ * is never projected as delivered.
+ */
+export declare class ReportingNotificationRetryableSuppressionError extends Error {
+    readonly reason: WebhookAttemptSuppressionReason;
+    readonly name = "ReportingNotificationRetryableSuppressionError";
+    constructor(reason: WebhookAttemptSuppressionReason);
+}
+export interface ReportingNotificationProjectionErrorV1 {
+    transitionId: string;
+    tenantId: string;
+    accountId: string;
+    attemptCount: number;
+}
+export interface PostgresReportingNotificationActivityOptions {
+    db: ReportingLedgerTransactionV1;
+    /**
+     * Notification port. A custom `{ emit }` must also set
+     * `hasDeliveryAttemptCheckpoint: true`, which asserts that it forwards the
+     * event it is handed to a runtime that runs the durable pre-POST checkpoint.
+     */
+    notifications: Pick<PersistentNotificationRuntime, 'emit'> & Partial<Pick<PersistentNotificationRuntime, 'hasDeliveryAttemptCheckpoint' | 'deliveryAttemptCheckpoint'>>;
+    /** Stable deployment namespace. Defaults to `adcp-reporting`. */
+    namespace?: string;
+    /** Assert that the supplied database/schema is isolated to this deployment. */
+    acknowledgeIsolatedDatabase?: boolean;
+    /** Defaults to `adcp_reporting_notification_activity`. */
+    tableName?: string;
+    /**
+     * Pure trusted mapping from the authoritative internal ledger account to a
+     * tenant. It runs while the ledger transaction is open and must not perform
+     * I/O or consult caller-controlled transition data.
+     */
+    tenantScopeForAccount(accountId: string): string;
+    /** Retention for projected operator activity. Defaults to 90 days. */
+    retentionMs?: number;
+    /** Atomic pending-intent backpressure per tenant. Defaults to 100,000. */
+    maxPendingPerTenant?: number;
+    /**
+     * Acknowledge a notification port that cannot prove it runs the durable
+     * pre-POST checkpoint. Without it a crash plus a destination replacement
+     * re-addresses the same notification under a second generation and a second
+     * idempotency key, so this is refused by default and exists only for tests
+     * that deliberately demonstrate that hazard.
+     */
+    acknowledgeMissingAttemptCheckpoint?: boolean;
+    /**
+     * The very checkpoint wired into the notification runtime.
+     *
+     * Required, because the checkpoint writes to a `(queryable, namespace,
+     * table)` triple of its own and a mismatch is otherwise undetectable at
+     * runtime: its update would match no row, every attempt would be suppressed
+     * as retryable, the delivery binding would eventually retire, the recipient
+     * would settle terminal and the activity would project — losing the
+     * notification silently. Passing the same object lets that be refused at
+     * construction instead.
+     */
+    attemptCheckpoint?: ReportingNotificationAttemptCheckpointV1;
+    /**
+     * Largest recipient fanout whose frozen intent this runtime will store.
+     *
+     * Must be **at least** the notification runtime's `maxFanoutCandidates`, plus
+     * headroom for the distinct subscribers one notification can accumulate as
+     * destinations churn. Defaults to 10,000 — the ceiling that runtime enforces
+     * on `maxFanoutCandidates` — so the default can never be exceeded by a valid
+     * fanout. Setting it *below* `maxFanoutCandidates` is a misconfiguration: a
+     * legitimate fanout then cannot be committed and the claim retries until
+     * `maxAttempts` abandons it.
+     */
+    maxRecipients?: number;
+    /**
+     * Total recipient rows one notification may retain: the current fanout plus
+     * the pinned identities of subscribers that were addressed and then replaced
+     * or removed.
+     *
+     * Separate from `maxRecipients` because they bound different things. A
+     * maximum fanout of 10,000 that also has one former subscriber pinned needs
+     * 10,001 rows, which a single bound capped at the fanout ceiling could never
+     * express — the claim would be unsatisfiable and abandon undelivered.
+     * Defaults to twice `maxRecipients`, and must be at least `maxRecipients`.
+     */
+    maxRetainedRecipients?: number;
+    /**
+     * Attempts after which a claim that keeps failing is abandoned rather than
+     * retried forever. Defaults to 100.
+     *
+     * Without a bound, a claim that can never succeed — an over-fanout
+     * configuration, a permanently unreachable dependency — stays pending
+     * indefinitely, and enough of them reach `maxPendingPerTenant` and start
+     * refusing new activity writes for the whole tenant. An abandoned claim stops
+     * consuming that capacity while staying visible for operators; it is never
+     * recorded as delivered.
+     */
+    maxAttempts?: number;
+}
+export interface PostgresReportingNotificationActivityRuntime {
+    readonly port: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
+    readonly migrations: {
+        activity: string;
+        all: readonly string[];
+    };
+    probe(): Promise<void>;
+    recoverOnce(options?: {
+        ownerToken?: string;
+        leaseMs?: number;
+        limit?: number;
+        retryAfterMs?: number;
+        /** Operational observer; hook failures never change durable lease semantics. */
+        onError?: (error: unknown, claim: Readonly<ReportingNotificationProjectionErrorV1>) => void | Promise<void>;
+    }): Promise<ReportingNotificationRecoveryMetricsV1>;
+    listActivity(input: {
+        /** Trusted authenticated scope; never copy these values from an event payload. */
+        tenantId: string;
+        accountId: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<ReportingAccountActivityPageV1>;
+    pruneProjected(options?: {
+        limit?: number;
+    }): Promise<number>;
+}
+export declare function getReportingNotificationActivityMigration(options?: {
+    tableName?: string;
+}): string;
+/** Child table holding one row per frozen recipient. */
+export declare function recipientTableName(tableName?: string): string;
+export declare const REPORTING_NOTIFICATION_ACTIVITY_MIGRATION: string;
+/**
+ * Builds the durable pre-POST attempt checkpoint for the reporting activity
+ * recipient table.
+ *
+ * Pass the result to `createPostgresPersistentNotificationRuntime`'s
+ * `checkpointDeliveryAttempt`. It is a standalone factory rather than a method
+ * on the activity runtime so it can be constructed before the notification
+ * runtime it has to be wired into, and it is keyed purely on the durable attempt
+ * context so a recovered outbox attempt — the path most likely to produce an
+ * ambiguous send — records the same checkpoint as the original emission.
+ *
+ * The write is monotonic and idempotent and deliberately takes no recovery
+ * lease: a checkpoint only ever makes a recipient less revisable, which is the
+ * safe direction, and an outbox worker legitimately holds no activity lease.
+ */
+/** Durable store a checkpoint is bound to, so a mismatched pairing cannot be silent. */
+export interface ReportingNotificationAttemptCheckpointV1 {
+    (input: Readonly<NotificationDeliveryAttemptCheckpointInput>): Promise<void>;
+    /**
+     * Exact `(queryable, namespace, table)` this checkpoint writes to. Present on
+     * anything this module builds; absent on an adopter's own forwarder, which is
+     * then only acceptable when the runtime it is wired into exposes the
+     * checkpoint it invokes so identity can be compared directly.
+     */
+    readonly activityStore?: Readonly<{
+        db: ReportingLedgerTransactionV1;
+        namespace: string;
+        tableName: string;
+    }>;
+}
+export declare function createPostgresReportingNotificationAttemptCheckpoint(options: {
+    db: ReportingLedgerTransactionV1;
+    namespace?: string;
+    tableName?: string;
+    /**
+     * Additional event types this checkpoint owns, on top of the mandatory
+     * `reporting.status_changed`. Anything it does not own is another
+     * subsystem's notification and is passed through untouched — the runtime hook
+     * is global, and failing closed on an event that was never frozen here would
+     * suppress every attempt of that event until its retry horizon expired. This
+     * extends the owned set; it can never remove the reporting event.
+     */
+    eventTypes?: readonly string[];
+}): ReportingNotificationAttemptCheckpointV1;
+export declare function createPostgresReportingNotificationActivityRuntime(options: PostgresReportingNotificationActivityOptions): PostgresReportingNotificationActivityRuntime;

package/dist/lib/reporting/ledger/notification-activity.d.ts

@@ -0,0 +1,222 @@
+import type { NotificationDeliveryAttemptCheckpointInput, PersistentNotificationRuntime } from '../../server/notification-subscriptions';
+import type { WebhookAttemptSuppressionReason } from '../../server/webhook-emitter';
+import type { ReportingHealthV1, ReportingLedgerNotificationActivityPortV1, ReportingLedgerObligationV1, ReportingLedgerTransactionV1, ReportingObservedFinalityV1 } from './types';
+export interface ReportingAccountActivityV1 {
+    activityId: string;
+    transitionId: string;
+    activityType: 'reporting.lifecycle_changed';
+    notificationType?: 'reporting.status_changed';
+    tenantId: string;
+    accountId: string;
+    reporting_obligation_id: string;
+    previousHealth: ReportingHealthV1;
+    health: ReportingHealthV1;
+    previousFinality: ReportingObservedFinalityV1;
+    finality: ReportingObservedFinalityV1;
+    issueIds: string[];
+    occurredAt: string;
+    correlation: {
+        delivery_config_id: string;
+        delivery_config_version: number;
+        report_definition_id: string;
+        feed_purpose: ReportingLedgerObligationV1['feedPurpose'];
+        period: {
+            start: string;
+            end: string;
+        };
+    };
+}
+export interface ReportingAccountActivityRecordV1 extends ReportingAccountActivityV1 {
+    recordedAt: string;
+    notificationProjectedAt?: string;
+    /** Set when the claim was bounded out of the pending set without delivering. */
+    notificationAbandonedAt?: string;
+}
+export interface ReportingAccountActivityPageV1 {
+    activities: ReportingAccountActivityRecordV1[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+export interface ReportingNotificationRecoveryMetricsV1 {
+    claimed: number;
+    matched: number;
+    projected: number;
+    retried: number;
+    leaseLost: number;
+    /** Claims bounded out of the pending set after `maxAttempts`; never delivered. */
+    abandoned: number;
+}
+/**
+ * Raised when live delivery authority failed closed for an operational reason
+ * rather than a deliberate one. The claim is released and retried; the activity
+ * is never projected as delivered.
+ */
+export declare class ReportingNotificationRetryableSuppressionError extends Error {
+    readonly reason: WebhookAttemptSuppressionReason;
+    readonly name = "ReportingNotificationRetryableSuppressionError";
+    constructor(reason: WebhookAttemptSuppressionReason);
+}
+export interface ReportingNotificationProjectionErrorV1 {
+    transitionId: string;
+    tenantId: string;
+    accountId: string;
+    attemptCount: number;
+}
+export interface PostgresReportingNotificationActivityOptions {
+    db: ReportingLedgerTransactionV1;
+    /**
+     * Notification port. A custom `{ emit }` must also set
+     * `hasDeliveryAttemptCheckpoint: true`, which asserts that it forwards the
+     * event it is handed to a runtime that runs the durable pre-POST checkpoint.
+     */
+    notifications: Pick<PersistentNotificationRuntime, 'emit'> & Partial<Pick<PersistentNotificationRuntime, 'hasDeliveryAttemptCheckpoint' | 'deliveryAttemptCheckpoint'>>;
+    /** Stable deployment namespace. Defaults to `adcp-reporting`. */
+    namespace?: string;
+    /** Assert that the supplied database/schema is isolated to this deployment. */
+    acknowledgeIsolatedDatabase?: boolean;
+    /** Defaults to `adcp_reporting_notification_activity`. */
+    tableName?: string;
+    /**
+     * Pure trusted mapping from the authoritative internal ledger account to a
+     * tenant. It runs while the ledger transaction is open and must not perform
+     * I/O or consult caller-controlled transition data.
+     */
+    tenantScopeForAccount(accountId: string): string;
+    /** Retention for projected operator activity. Defaults to 90 days. */
+    retentionMs?: number;
+    /** Atomic pending-intent backpressure per tenant. Defaults to 100,000. */
+    maxPendingPerTenant?: number;
+    /**
+     * Acknowledge a notification port that cannot prove it runs the durable
+     * pre-POST checkpoint. Without it a crash plus a destination replacement
+     * re-addresses the same notification under a second generation and a second
+     * idempotency key, so this is refused by default and exists only for tests
+     * that deliberately demonstrate that hazard.
+     */
+    acknowledgeMissingAttemptCheckpoint?: boolean;
+    /**
+     * The very checkpoint wired into the notification runtime.
+     *
+     * Required, because the checkpoint writes to a `(queryable, namespace,
+     * table)` triple of its own and a mismatch is otherwise undetectable at
+     * runtime: its update would match no row, every attempt would be suppressed
+     * as retryable, the delivery binding would eventually retire, the recipient
+     * would settle terminal and the activity would project — losing the
+     * notification silently. Passing the same object lets that be refused at
+     * construction instead.
+     */
+    attemptCheckpoint?: ReportingNotificationAttemptCheckpointV1;
+    /**
+     * Largest recipient fanout whose frozen intent this runtime will store.
+     *
+     * Must be **at least** the notification runtime's `maxFanoutCandidates`, plus
+     * headroom for the distinct subscribers one notification can accumulate as
+     * destinations churn. Defaults to 10,000 — the ceiling that runtime enforces
+     * on `maxFanoutCandidates` — so the default can never be exceeded by a valid
+     * fanout. Setting it *below* `maxFanoutCandidates` is a misconfiguration: a
+     * legitimate fanout then cannot be committed and the claim retries until
+     * `maxAttempts` abandons it.
+     */
+    maxRecipients?: number;
+    /**
+     * Total recipient rows one notification may retain: the current fanout plus
+     * the pinned identities of subscribers that were addressed and then replaced
+     * or removed.
+     *
+     * Separate from `maxRecipients` because they bound different things. A
+     * maximum fanout of 10,000 that also has one former subscriber pinned needs
+     * 10,001 rows, which a single bound capped at the fanout ceiling could never
+     * express — the claim would be unsatisfiable and abandon undelivered.
+     * Defaults to twice `maxRecipients`, and must be at least `maxRecipients`.
+     */
+    maxRetainedRecipients?: number;
+    /**
+     * Attempts after which a claim that keeps failing is abandoned rather than
+     * retried forever. Defaults to 100.
+     *
+     * Without a bound, a claim that can never succeed — an over-fanout
+     * configuration, a permanently unreachable dependency — stays pending
+     * indefinitely, and enough of them reach `maxPendingPerTenant` and start
+     * refusing new activity writes for the whole tenant. An abandoned claim stops
+     * consuming that capacity while staying visible for operators; it is never
+     * recorded as delivered.
+     */
+    maxAttempts?: number;
+}
+export interface PostgresReportingNotificationActivityRuntime {
+    readonly port: ReportingLedgerNotificationActivityPortV1<ReportingLedgerTransactionV1>;
+    readonly migrations: {
+        activity: string;
+        all: readonly string[];
+    };
+    probe(): Promise<void>;
+    recoverOnce(options?: {
+        ownerToken?: string;
+        leaseMs?: number;
+        limit?: number;
+        retryAfterMs?: number;
+        /** Operational observer; hook failures never change durable lease semantics. */
+        onError?: (error: unknown, claim: Readonly<ReportingNotificationProjectionErrorV1>) => void | Promise<void>;
+    }): Promise<ReportingNotificationRecoveryMetricsV1>;
+    listActivity(input: {
+        /** Trusted authenticated scope; never copy these values from an event payload. */
+        tenantId: string;
+        accountId: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<ReportingAccountActivityPageV1>;
+    pruneProjected(options?: {
+        limit?: number;
+    }): Promise<number>;
+}
+export declare function getReportingNotificationActivityMigration(options?: {
+    tableName?: string;
+}): string;
+/** Child table holding one row per frozen recipient. */
+export declare function recipientTableName(tableName?: string): string;
+export declare const REPORTING_NOTIFICATION_ACTIVITY_MIGRATION: string;
+/**
+ * Builds the durable pre-POST attempt checkpoint for the reporting activity
+ * recipient table.
+ *
+ * Pass the result to `createPostgresPersistentNotificationRuntime`'s
+ * `checkpointDeliveryAttempt`. It is a standalone factory rather than a method
+ * on the activity runtime so it can be constructed before the notification
+ * runtime it has to be wired into, and it is keyed purely on the durable attempt
+ * context so a recovered outbox attempt — the path most likely to produce an
+ * ambiguous send — records the same checkpoint as the original emission.
+ *
+ * The write is monotonic and idempotent and deliberately takes no recovery
+ * lease: a checkpoint only ever makes a recipient less revisable, which is the
+ * safe direction, and an outbox worker legitimately holds no activity lease.
+ */
+/** Durable store a checkpoint is bound to, so a mismatched pairing cannot be silent. */
+export interface ReportingNotificationAttemptCheckpointV1 {
+    (input: Readonly<NotificationDeliveryAttemptCheckpointInput>): Promise<void>;
+    /**
+     * Exact `(queryable, namespace, table)` this checkpoint writes to. Present on
+     * anything this module builds; absent on an adopter's own forwarder, which is
+     * then only acceptable when the runtime it is wired into exposes the
+     * checkpoint it invokes so identity can be compared directly.
+     */
+    readonly activityStore?: Readonly<{
+        db: ReportingLedgerTransactionV1;
+        namespace: string;
+        tableName: string;
+    }>;
+}
+export declare function createPostgresReportingNotificationAttemptCheckpoint(options: {
+    db: ReportingLedgerTransactionV1;
+    namespace?: string;
+    tableName?: string;
+    /**
+     * Additional event types this checkpoint owns, on top of the mandatory
+     * `reporting.status_changed`. Anything it does not own is another
+     * subsystem's notification and is passed through untouched — the runtime hook
+     * is global, and failing closed on an event that was never frozen here would
+     * suppress every attempt of that event until its retry horizon expired. This
+     * extends the owned set; it can never remove the reporting event.
+     */
+    eventTypes?: readonly string[];
+}): ReportingNotificationAttemptCheckpointV1;
+export declare function createPostgresReportingNotificationActivityRuntime(options: PostgresReportingNotificationActivityOptions): PostgresReportingNotificationActivityRuntime;