@happyvertical/smrt-messages 0.60.8 → 0.60.10

package/dist/models/Message.d.ts

@@ -6,6 +6,8 @@
 import '../__smrt-register__.js';
 import { SmrtObject } from '@happyvertical/smrt-core';
 import type { MessageOptions, MessageSendResult, SendMessageOptions, SendStatus } from "../types.js";
+/** `metadata` key recording that the last failed send may have been accepted. */
+export declare const SEND_OUTCOME_UNKNOWN_METADATA_KEY = "sendOutcomeUnknown";
 export declare class Message extends SmrtObject {
     tenantId: string | null;
     accountId: string;
@@ -94,6 +96,19 @@ export declare class Message extends SmrtObject {
      * Send this message via its account's sender
      */
     send(options?: SendMessageOptions): Promise<MessageSendResult>;
+    /**
+     * Whether the latest failed send may still have been accepted by the
+     * provider (see `MessageSendResult.outcomeUnknown`).
+     */
+    isSendOutcomeUnknown(): boolean;
+    /**
+     * Release a send claim whose sender is gone (a crash or lost lease left the
+     * row in `sending`): move it to `failed` with an unknown outcome so the
+     * owner of the delivery decision can send it again. Returns false, changing
+     * nothing, unless the stored row is still `sending`. Only for callers that
+     * have established that no live sender holds the claim.
+     */
+    abandonSendAttempt(reason: string): Promise<boolean>;
     /**
      * Retry sending a failed message
      */

package/dist/models/Message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Message.d.ts","sourceRoot":"","sources":["../../src/models/Message.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,yBAAyB,CAAC;AACjC,OAAO,EAIL,UAAU,EAIX,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACX,MAAM,aAAU,CAAC;AAElB,qBAOa,OAAQ,SAAQ,UAAU;IAErC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAQ;IAM/B,SAAS,SAAM;IAQf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAGhC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAQ;IAKjC,aAAa,SAAM;IAEnB,QAAQ,SAAM;IAEd,OAAO,SAAM;IAEb,IAAI,SAAM;IAEV,WAAW,SAAM;IAEjB,QAAQ,SAAM;IAEd,WAAW,SAAM;IAEjB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAQ;IAEzB,MAAM,UAAS;IAEf,SAAS,UAAS;IAElB,cAAc,UAAS;IAEvB,IAAI,SAAK;IAIT,QAAQ,SAAM;IAOd,UAAU,EAAE,UAAU,CAAW;IAEjC,MAAM,EAAE,IAAI,GAAG,IAAI,CAAQ;IAE3B,SAAS,SAAM;IAEf,UAAU,SAAK;IAEf,UAAU,SAAK;IAEf,eAAe,EAAE,IAAI,GAAG,IAAI,CAAQ;IAGpC,kBAAkB,SAAM;IAIxB,SAAS,OAAc;IAEvB,SAAS,OAAc;gBAEX,OAAO,GAAE,cAAmB;YAqC1B,qBAAqB;IAuDnC;;OAEG;IACH,cAAc,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAS3D;;OAEG;IACH,cAAc,CAAC,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,IAAI;IAI1E;;OAEG;IACH,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAStC;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIhD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAM/B;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAMpC;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,UAAU,CAAC,SAAS,SAAM,GAAG,MAAM;IAMnC;;OAEG;IACG,UAAU;IAWV,WAAW;IASjB;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAW7C;;OAEG;IACG,cAAc;IAapB;;OAEG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAkJpE;;OAEG;IACG,SAAS,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwBzE;;;;;;;;OAQG;IACH,SAAS,CAAC,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IASjD;;OAEG;IACH,WAAW,CAAC,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO;IA0BvD;;OAEG;IACH,aAAa,IAAI,OAAO;IAyBxB;;OAEG;IACH,SAAS,CAAC,eAAe,IAAI,MAAM;CAapC"}
+{"version":3,"file":"Message.d.ts","sourceRoot":"","sources":["../../src/models/Message.ts"],"names":[],"mappings":"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"}

package/dist/models/NotificationDelivery.d.ts

@@ -0,0 +1,128 @@
+import type { SmrtObjectOptions } from '@happyvertical/smrt-core';
+import '../__smrt-register__.js';
+import { SmrtObject } from '@happyvertical/smrt-core';
+/** Channels the notification outbox can deliver through. */
+export type NotificationDeliveryChannel = 'email';
+export declare const NOTIFICATION_DELIVERY_CHANNELS: readonly NotificationDeliveryChannel[];
+/**
+ * Where a delivery is in its lifecycle.
+ *
+ * - `pending`: waiting for `nextAttemptAt`.
+ * - `sending`: leased by one dispatcher until `leaseExpiresAt`.
+ * - `sent`: the provider accepted it (terminal).
+ * - `failed`: rejected for good or out of attempts (terminal).
+ * - `uncertain`: handed to a provider whose outcome is unknown; waits for
+ *   reconciliation and is never resent automatically.
+ * - `cancelled`: suppressed by the host before handoff (terminal).
+ */
+export type NotificationDeliveryStatus = 'pending' | 'sending' | 'sent' | 'failed' | 'uncertain' | 'cancelled';
+export interface NotificationDeliveryOptions extends SmrtObjectOptions {
+    tenantId?: string;
+    recipientUserId?: string;
+    channel?: NotificationDeliveryChannel;
+    sourceRef?: string;
+    kind?: string;
+    subject?: string;
+    textBody?: string;
+    href?: string;
+    recipientAddress?: string;
+    recipientName?: string;
+    accountId?: string;
+    messageId?: string | null;
+    status?: NotificationDeliveryStatus;
+    stateVersion?: number;
+    transitionId?: string;
+    attempts?: number;
+    maxAttempts?: number;
+    nextAttemptAt?: Date;
+    leaseToken?: string | null;
+    leaseExpiresAt?: Date | null;
+    handedOffAt?: Date | null;
+    deliveredAt?: Date | null;
+    providerMessageId?: string;
+    lastError?: string;
+}
+/** Column values a lease transition may change (camelCase field names). */
+export type NotificationDeliveryTransition = Partial<Pick<NotificationDelivery, 'messageId' | 'status' | 'attempts' | 'nextAttemptAt' | 'leaseToken' | 'leaseExpiresAt' | 'handedOffAt' | 'deliveredAt' | 'providerMessageId' | 'lastError'>>;
+/**
+ * One durable, source-keyed notification delivery to one person over one
+ * external channel (the outbox row behind `NotificationOutboxService`).
+ *
+ * `sourceRef` is the idempotency key: one row per
+ * `(tenant, recipient, channel, sourceRef)` (the conflict identity), and that
+ * row produces at most one outbound `Message`. The recipient address is a
+ * snapshot taken from the host's recipient resolver at enqueue time, never a
+ * caller-chosen address.
+ *
+ * Every state change after creation goes through {@link transition}, a
+ * compare-and-set on `stateVersion`, so concurrent dispatchers cannot both
+ * hold the lease or overwrite each other's outcome. Generated REST/MCP/CLI
+ * are off: rows carry recipient addresses and are reached only through the
+ * service.
+ */
+export declare class NotificationDelivery extends SmrtObject {
+    tenantId: string;
+    /** The person being told (`smrt-users:User`, uuid). */
+    recipientUserId: string;
+    /** Delivery channel; only `email` today. */
+    channel: NotificationDeliveryChannel;
+    /** Idempotency key for the underlying event (see class docs). */
+    sourceRef: string;
+    /** Host-defined type, e.g. `project-question.asked`. */
+    kind: string;
+    /** Email subject line. */
+    subject: string;
+    /** Plain-text body; the deep link is appended on its own line. */
+    textBody: string;
+    /** Absolute deep link on the host's configured origin (no credentials). */
+    href: string;
+    /** Address snapshot from the host recipient resolver. */
+    recipientAddress: string;
+    /** Display name snapshot from the host recipient resolver. */
+    recipientName: string;
+    /** Sender `EmailAccount` in the same tenant. */
+    accountId: string;
+    /** The single outbound `Message` (created under the first lease). */
+    messageId: string | null;
+    status: NotificationDeliveryStatus;
+    /** Compare-and-set counter; bumped by every transition. */
+    stateVersion: number;
+    /** Unique id of the transition that wrote the current state. */
+    transitionId: string;
+    /** Leases acquired so far (provider handoffs are a subset). */
+    attempts: number;
+    /** Lease budget before the delivery fails for good. */
+    maxAttempts: number;
+    /** Earliest time a dispatcher may lease a `pending` row. */
+    nextAttemptAt: Date;
+    /** Proof of the current lease holder; cleared when the lease ends. */
+    leaseToken: string | null;
+    /** When the current lease lapses and the row becomes recoverable. */
+    leaseExpiresAt: Date | null;
+    /** Set just before the current attempt reaches the provider. */
+    handedOffAt: Date | null;
+    /** When the provider accepted the message. */
+    deliveredAt: Date | null;
+    /** Provider message id, when the provider returns one. */
+    providerMessageId: string;
+    /** The latest failure or uncertainty reason. */
+    lastError: string;
+    constructor(options?: NotificationDeliveryOptions);
+    /** Whether no further automatic work will happen on this row. */
+    get isSettled(): boolean;
+    /**
+     * Apply `changes` only if the stored row is still at `stateVersion` (and,
+     * when `leaseToken` is given, still held by that lease). Returns whether
+     * this caller won; on success the instance reflects the stored row.
+     *
+     * PostgreSQL and remote LibSQL evaluate the guard in one conditional
+     * UPDATE; local embedded engines use the process write queue, matching
+     * `Message.send()`'s claim. The durable row is re-read either way, and the
+     * write is recognised by its unique `transitionId`, because DuckDB's update
+     * result over-reports affected rows.
+     */
+    transition(changes: NotificationDeliveryTransition, expected?: {
+        leaseToken?: string;
+    }): Promise<boolean>;
+}
+//# sourceMappingURL=NotificationDelivery.d.ts.map

package/dist/models/NotificationDelivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationDelivery.d.ts","sourceRoot":"","sources":["../../src/models/NotificationDelivery.ts"],"names":[],"mappings":"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"}

package/dist/senders/EmailSender.d.ts

@@ -23,4 +23,13 @@ export declare class EmailSender implements MessageSenderInterface {
      */
     private collectAttachments;
 }
+/**
+ * Whether a provider send error proves the message was not accepted: the
+ * server answered with an SMTP reply code, the SDK classified it as an
+ * authentication/validation failure, a send error accepted no recipient, or
+ * the connection was never made. Anything else (a timeout, a reset
+ * connection, an unclassified error) may have happened after the server took
+ * the message, so its outcome is unknown.
+ */
+export declare function isDefiniteSendRejection(error: unknown): boolean;
 //# sourceMappingURL=EmailSender.d.ts.map

package/dist/senders/EmailSender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmailSender.d.ts","sourceRoot":"","sources":["../../src/senders/EmailSender.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAAwB,CAAC;AAC3D,OAAO,KAAK,EACV,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,aAAU,CAAC;AAElB,qBAAa,WAAY,YAAW,sBAAsB;IACxD,QAAQ,CAAC,YAAY,WAAW;IAChC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,OAAO,CAAe;gBAElB,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY;IAKtD,OAAO,IAAI,OAAO;IAIZ,IAAI,CACR,OAAO,EAAE,KAAK,EACd,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;IA8D7B;;;;;;;;OAQG;YACW,kBAAkB;CAyEjC"}
+{"version":3,"file":"EmailSender.d.ts","sourceRoot":"","sources":["../../src/senders/EmailSender.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAiB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAAwB,CAAC;AAC3D,OAAO,KAAK,EACV,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,aAAU,CAAC;AAElB,qBAAa,WAAY,YAAW,sBAAsB;IACxD,QAAQ,CAAC,YAAY,WAAW;IAChC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,OAAO,CAAe;gBAElB,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY;IAKtD,OAAO,IAAI,OAAO;IAIZ,IAAI,CACR,OAAO,EAAE,KAAK,EACd,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,iBAAiB,CAAC;IA+D7B;;;;;;;;OAQG;YACW,kBAAkB;CAyEjC;AAkBD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAmB/D"}

package/dist/services/NotificationOutboxService.d.ts

@@ -0,0 +1,226 @@
+import { type SmrtClassOptions } from '@happyvertical/smrt-core';
+import type { Message } from '../models/Message.js';
+import type { NotificationDelivery, NotificationDeliveryChannel } from '../models/NotificationDelivery.js';
+import { type MessagingPrincipal } from '../permissions.js';
+/** What a transport knows about one provider handoff. */
+export type NotificationTransportOutcome = {
+    status: 'accepted';
+    providerMessageId?: string;
+} | {
+    status: 'rejected';
+    error: string;
+    retryable: boolean;
+} | {
+    status: 'unknown';
+    error: string;
+};
+/** What a transport can say about an earlier handoff during recovery. */
+export type NotificationTransportReconciliation = NotificationTransportOutcome | {
+    status: 'not-sent';
+};
+export interface NotificationTransportRequest {
+    delivery: NotificationDelivery;
+    /** The delivery's single outbound message (an `Email` for `email`). */
+    message: Message;
+    /** Stable per delivery; pass it to providers that dedupe on a key. */
+    idempotencyKey: string;
+}
+/**
+ * Hands one outbound message to a provider. The default
+ * ({@link messageSendTransport}) delivers through `Message.send()` and the
+ * message's account sender; tests and hosts with their own provider inject
+ * another.
+ */
+export interface NotificationTransport {
+    readonly name: string;
+    /**
+     * True only when the provider deduplicates on `idempotencyKey`, so sending
+     * again after an unknown outcome cannot deliver twice. Then an unknown
+     * outcome is retried; otherwise it becomes `uncertain`.
+     */
+    readonly idempotent?: boolean;
+    send(request: NotificationTransportRequest): Promise<NotificationTransportOutcome>;
+    /**
+     * After a crash or lease loss following a handoff, report what is known
+     * from durable state. Omit when nothing can be known (outcome: uncertain).
+     */
+    reconcile?(request: NotificationTransportRequest): Promise<NotificationTransportReconciliation>;
+}
+/**
+ * Delivers through the canonical `Message.send()` (account → provider sender)
+ * and reconciles from the message's own `sendStatus`.
+ *
+ * SMTP and the SDK email providers take no idempotency key, so this
+ * transport is not idempotent: a handoff whose outcome is lost stays
+ * `uncertain` instead of risking a second email.
+ */
+export declare const messageSendTransport: NotificationTransport;
+export type NotificationOutboxDenialReason = 'permission' | 'recipient' | 'sender' | 'link';
+/** Thrown when the host's policy refuses an enqueue; nothing is stored. */
+export declare class NotificationOutboxDeniedError extends Error {
+    readonly reason: NotificationOutboxDenialReason;
+    constructor(reason: NotificationOutboxDenialReason, message: string);
+}
+export interface NotificationRecipientRequest {
+    tenantId: string;
+    recipientUserId: string;
+    channel: NotificationDeliveryChannel;
+}
+export interface NotificationRecipient {
+    address: string;
+    name?: string;
+}
+export interface NotificationSuppressionRequest extends NotificationRecipientRequest {
+    kind: string;
+    sourceRef: string;
+}
+export interface NotificationOutboxOptions {
+    db: SmrtClassOptions['db'];
+    /**
+     * Host authorization for recipients: the address of `recipientUserId` when
+     * the host allows notifying them in `tenantId` (e.g. a member of that
+     * tenant), otherwise null, which denies the enqueue. Callers never supply
+     * an address.
+     */
+    resolveRecipient(request: NotificationRecipientRequest): Promise<NotificationRecipient | null> | NotificationRecipient | null;
+    /** The sending `EmailAccount` id for a tenant (deployment setup). */
+    resolveSenderAccountId(request: {
+        tenantId: string;
+    }): Promise<string | null> | string | null;
+    /** Absolute http(s) URL deep links are built on, e.g. `https://app.example.com`. */
+    linkBaseUrl: string;
+    /** Optional opt-out hook, checked at enqueue and again before handoff. */
+    isSuppressed?(request: NotificationSuppressionRequest): Promise<boolean> | boolean;
+    /** Provider seam; defaults to {@link messageSendTransport}. */
+    transport?: NotificationTransport;
+    /**
+     * When set, enqueue and reconcile require `messages.send` in the tenant.
+     * Omit only for trusted system code that performs its own authorization.
+     */
+    principal?: MessagingPrincipal;
+    /** Lease length; must exceed the slowest provider handoff (default 5 min). */
+    leaseMs?: number;
+    /** Lease budget per delivery (default 5). */
+    maxAttempts?: number;
+    /** Delay before attempt `n + 1` after `n` failed (default 1 min · 2ⁿ⁻¹, ≤ 1 h). */
+    retryDelayMs?(attempts: number): number;
+    /** Clock (tests). */
+    now?(): Date;
+}
+export interface NotificationEmailInput {
+    tenantId: string;
+    recipientUserId: string;
+    /** Idempotency key for the event, e.g. `project-question:<id>:asked`. */
+    sourceRef: string;
+    /** Host-defined type, e.g. `project-question.asked`. */
+    kind: string;
+    /** One line; CR/LF are rejected. */
+    subject: string;
+    /** Plain-text body; the deep link is appended on its own line. */
+    text: string;
+    /** Host-relative path of the deep link (`/portal/...`). */
+    path: string;
+    /** Do not send before this time (default: now). */
+    notBefore?: Date;
+}
+export interface NotificationEnqueueResult {
+    delivery: NotificationDelivery;
+    /** False when `sourceRef` matched an existing delivery (returned untouched). */
+    created: boolean;
+}
+export type NotificationDispatchOutcome = 'sent' | 'retry-scheduled' | 'failed' | 'uncertain' | 'cancelled' | 'lease-lost';
+export interface NotificationDispatchReport {
+    /** Rows this call won a lease on. */
+    leased: number;
+    outcomes: Array<{
+        deliveryId: string;
+        tenantId: string;
+        outcome: NotificationDispatchOutcome;
+    }>;
+}
+export interface NotificationDispatchOptions {
+    /** Tenants to dispatch; omit to discover due rows across all tenants. */
+    tenantIds?: readonly string[];
+    /** Maximum rows to lease in this call (default 25, max 200). */
+    limit?: number;
+}
+export type NotificationReconcileOutcome = 'sent' | 'retry' | 'failed';
+/**
+ * The id of a delivery's one outbound message: a name-based uuid derived from
+ * the delivery id, so every dispatcher computes the same identity.
+ */
+export declare function notificationDeliveryMessageId(deliveryId: string): Promise<string>;
+/** The correlation id that ties a delivery to its one outbound message. */
+export declare function notificationDeliveryCorrelationId(deliveryId: string): string;
+/**
+ * Build an absolute deep link from a host-relative `path` on `baseUrl`.
+ *
+ * The link always stays on the configured origin (no `//host`, backslash, or
+ * scheme tricks) and never carries credentials: the destination is an
+ * ordinary authenticated route, so the recipient signs in as themselves.
+ */
+export declare function buildNotificationLink(baseUrl: string, path: string): string;
+/**
+ * Source-keyed, durable notification email outbox.
+ *
+ * `enqueueEmail()` stores one `NotificationDelivery` per
+ * `(tenant, recipient, email, sourceRef)` — a repeated event returns the
+ * existing row — after the host has authorized the recipient and sender.
+ * `dispatchDue()` leases due rows with a compare-and-set, creates the single
+ * outbound `Email` under the lease, hands it to the transport, and records
+ * the outcome; it is safe to run from several workers at once and to crash
+ * at any point. See `packages/messages/agents/notification-outbox.md`.
+ */
+export declare class NotificationOutboxService {
+    private readonly options;
+    private readonly transport;
+    private readonly leaseMs;
+    private readonly maxAttempts;
+    private readonly retryDelayMs;
+    private readonly now;
+    constructor(options: NotificationOutboxOptions);
+    private collection;
+    private authorize;
+    /** Store one email delivery for the event unless `sourceRef` already has one. */
+    enqueueEmail(input: NotificationEmailInput): Promise<NotificationEnqueueResult>;
+    /** Lease and deliver due rows; returns what happened to each leased row. */
+    dispatchDue(options?: NotificationDispatchOptions): Promise<NotificationDispatchReport>;
+    /** Deliveries waiting for a reconciliation decision, oldest first. */
+    listUncertain(options: {
+        tenantId: string;
+        limit?: number;
+    }): Promise<NotificationDelivery[]>;
+    /**
+     * Settle an `uncertain` delivery after checking the provider out of band:
+     * `sent` (it arrived), `failed` (give up), or `retry` (send again,
+     * accepting the risk of a duplicate; a message left claimed by a dead
+     * sender is released first). Returns false when the row is not uncertain
+     * any more, or for `retry` when the message is recorded as sent.
+     */
+    reconcile(input: {
+        tenantId: string;
+        deliveryId: string;
+        outcome: NotificationReconcileOutcome;
+        note?: string;
+    }): Promise<boolean>;
+    private requireSenderAccount;
+    private isSuppressed;
+    private findDue;
+    /** Lease one candidate and carry it to an outcome; null when not leased. */
+    private dispatchOne;
+    private recoverHandoff;
+    private applyOutcome;
+    private scheduleRetry;
+    /** End the lease in a terminal status; reports lease loss instead of overwriting. */
+    private settle;
+    private endLease;
+    private loadMessage;
+    /**
+     * The delivery's single outbound `Email`, created under the lease. Its id
+     * is derived from the delivery id and inserted insert-only, so a stale
+     * dispatcher that resumes after its lease was taken over hits the stored
+     * row (a unique violation) instead of creating a second email.
+     */
+    private ensureMessage;
+}
+//# sourceMappingURL=NotificationOutboxService.d.ts.map

package/dist/services/NotificationOutboxService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationOutboxService.d.ts","sourceRoot":"","sources":["../../src/services/NotificationOutboxService.ts"],"names":[],"mappings":"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"}