@marktiderman/genesis-notifications 0.0.0-stage → 0.1.1

package/dist/server.d.ts

@@ -0,0 +1,658 @@
+import { a as Channel, p as NotificationTypeRow, R as Recipient, l as NotificationRegistry, r as NotifyInput, s as NotifyResult } from './types-BilguCPW.js';
+import { RunReport } from './runner.js';
+import { a as EmailTemplate } from './email-render-CID_pXDy.js';
+export { b as EmailContent, E as EmailTemplateContext, c as canonicalJson, d as defaultEmailTemplate, e as displayName, f as escapeHtml, h as headerSafe, i as isSafeAddress } from './email-render-CID_pXDy.js';
+
+/**
+ * The database half, through the service role: what the runner and the
+ * handler call. `supabaseNotificationStore(admin)` wraps migration 0001's
+ * functions; tests (and an app with another queue) pass their own.
+ */
+
+type RpcResult = {
+    data: unknown;
+    error: {
+        message?: string;
+        code?: string | null;
+    } | null;
+};
+/** The part of a Supabase client the store uses, signed in with the service role (`SUPABASE_SECRET_KEY`). */
+interface RpcClient {
+    rpc: (fn: any, args?: any) => PromiseLike<RpcResult>;
+}
+/** A database refusal, with its SQLSTATE; never the row it refused. */
+declare class NotificationStoreError extends Error {
+    readonly operation: string;
+    readonly code: string | null;
+    constructor(operation: string, code: string | null);
+}
+interface ClaimedDevice {
+    id: string;
+    token: string;
+    platform: string;
+}
+interface SenderIdentity {
+    from_name: string | null;
+    reply_to: string | null;
+    domain: string | null;
+    domain_verified: boolean;
+}
+/** One claimed send job, as genesis_notifications_claim hands it over. */
+interface ClaimedJob {
+    id: string;
+    claim_id: string;
+    notification_id: string;
+    channel: Exclude<Channel, "in_app">;
+    attempt: number;
+    deferrals: number;
+    redelivery: boolean;
+    type: string;
+    category: string;
+    tenant_id: string | null;
+    user_id: string | null;
+    email: string | null;
+    recipient_name: string | null;
+    data: Record<string, unknown>;
+    thread_key: string | null;
+    collapse_key: string | null;
+    badge: number | null;
+    brand: Record<string, unknown> | null;
+    transactional: boolean;
+    /** Preferences can't turn it off, so its email has no unsubscribe link. */
+    critical: boolean;
+    push_privacy: "default" | "generic";
+    ios_category: string | null;
+    hide_previews: boolean;
+    devices: ClaimedDevice[] | null;
+    sender: SenderIdentity | null;
+    rendered: RenderedEmail | null;
+    rendered_hash: string | null;
+    secret: string | null;
+}
+/** An email as first rendered: what every retry sends. */
+interface RenderedEmail {
+    from: string;
+    to: string[];
+    reply_to?: string;
+    subject: string;
+    html: string;
+    text: string;
+    headers?: Record<string, string>;
+    tags?: {
+        name: string;
+        value: string;
+    }[];
+}
+type SettleOutcome = {
+    status: "sent";
+    provider_id?: string | null;
+} | {
+    status: "skipped";
+    reason: string;
+} | {
+    status: "filtered";
+} | {
+    status: "failed";
+    error: string;
+    provider_id?: string | null;
+} | {
+    status: "retry";
+    error: string;
+    retry_at: string;
+    counted: boolean;
+    provider_id?: string | null;
+};
+interface PushTicketRow {
+    device_id: string;
+    ticket_id: string | null;
+    status: "sent" | "failed";
+    error: string | null;
+}
+interface NotificationStore {
+    /** `maxAttempts`: a job whose lease ran out that many times fails (`lease_expired`) instead of coming back. */
+    claim(channel: "push" | "email", limit: number, leaseSeconds: number, maxAttempts?: number): Promise<ClaimedJob[]>;
+    storeRendered(id: string, claimId: string, rendered: RenderedEmail, hash: string): Promise<{
+        rendered: RenderedEmail;
+        hash: string;
+    } | null>;
+    settle(id: string, claimId: string, outcome: SettleOutcome): Promise<boolean>;
+    /** Keeps the provider's id the moment a send returns, before it settles, so an early webhook finds the job. False when the claim is gone. */
+    recordProviderId(id: string, claimId: string, providerId: string): Promise<boolean>;
+    pushTickets(deliveryId: string, tickets: PushTicketRow[]): Promise<void>;
+    receiptsClaim(limit: number): Promise<{
+        id: number;
+        ticket_id: string;
+    }[]>;
+    receiptsSettle(results: {
+        id: number;
+        status: "delivered" | "failed";
+        error: string | null;
+    }[]): Promise<void>;
+    emailEvent(providerId: string, event: "delivered" | "bounced" | "complained", permanent: boolean): Promise<boolean>;
+    /** For a login (`userId`), or someone with none by the SHA-256 of their address; for one tenant's mail (`tenantId`), or mail sent for none. */
+    unsubscribe(userId: string | null, emailHash: string | null, category: string, tenantId: string | null): Promise<boolean>;
+    syncTypes(rows: NotificationTypeRow[]): Promise<number>;
+}
+/**
+ * The store over migration 0001's functions.
+ *
+ * @stability Beta
+ */
+declare function supabaseNotificationStore(client: RpcClient): NotificationStore;
+
+/**
+ * `notify()`: what a domain calls, from its server. It checks the input
+ * (the registry knows the type, the recipients are well formed, `data`
+ * holds no secret) and calls `genesis_notify`, which decides channels from
+ * preferences and queues the sends. A domain's own SQL can call
+ * `genesis_notify` directly with the same arguments.
+ */
+
+interface NotifyOptions {
+    /** Checks the type against the registry before the database does. */
+    registry?: NotificationRegistry;
+}
+/**
+ * Queue a notification for each recipient. Resolves one result per recipient
+ * that exists (a deleted login is left out); the same idempotency key again
+ * (for the same type and tenant) resolves `created: false` and sends nothing more.
+ *
+ * @stability Beta
+ */
+declare function notify<K extends string>(client: RpcClient, input: NotifyInput<K>, options?: NotifyOptions): Promise<NotifyResult[]>;
+interface CancelInput {
+    /** The type the notifications were made with: a key is a domain's, per type. */
+    type: string;
+    /** The key the notifications were made with. */
+    idempotencyKey: string;
+    /** The tenant they were made for. Default: those made with no tenant (never another tenant's). */
+    tenantId?: string | null;
+    /** Only these recipients (as `notify()` takes them). Default: everyone the key reached. */
+    recipients?: readonly Recipient[];
+    /** Archive the feed rows too. Default false. */
+    archive?: boolean;
+}
+/**
+ * Stop what hasn't gone out for a type, tenant and idempotency key (a release
+ * rolled back, an event undone): every pending send job is marked cancelled
+ * and never claimed. A job already sent is left alone; one being sent right
+ * now ends cancelled unless that attempt goes through (it is never retried).
+ * With `archive`, the feed rows are archived too.
+ *
+ * @stability Beta
+ */
+declare function cancelNotification(client: RpcClient, input: CancelInput): Promise<{
+    cancelled: number;
+    archived: number;
+}>;
+/**
+ * Mirror the registry into `notification_types` (run it on deploy, or the
+ * server's first request): types left out are retired, never deleted.
+ *
+ * @stability Beta
+ */
+declare function syncNotificationTypes(client: RpcClient, registry: NotificationRegistry): Promise<number>;
+
+/**
+ * A send failure with a message that is safe to store and log (a status and
+ * a provider's error code, never content, an address or a secret). The
+ * runner turns it into a retry or a failure.
+ */
+declare class SendError extends Error {
+    name: string;
+    readonly retryable: boolean;
+    readonly retryAfterSeconds: number | undefined;
+    readonly status: number | undefined;
+    constructor(message: string, options?: {
+        retryable?: boolean;
+        retryAfterSeconds?: number;
+        status?: number;
+    });
+}
+/** Whether an HTTP status is worth retrying unchanged: 408, 425, 429 and 5xx. */
+declare function isRetryableStatus(status: number): boolean;
+/** Seconds from a Retry-After header (delta-seconds or an HTTP date), else `fallback`. 1 s to a day. */
+declare function retryAfterSeconds(header: string | null | undefined, fallback?: number, now?: number): number;
+/** Every request gives up after this long. */
+declare const REQUEST_TIMEOUT_MS = 10000;
+interface HttpDeps {
+    /** Default the global `fetch`. */
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+
+/**
+ * Expo's push service: https://docs.expo.dev/push-notifications/sending-notifications/
+ *
+ *   POST /--/api/v2/push/send          up to 100 messages; one ticket each, in order
+ *   POST /--/api/v2/push/getReceipts   up to 1000 ticket ids; a receipt for each one ready
+ *
+ * Nothing here logs; an error names a status or Expo's error code, never a
+ * token or a message.
+ */
+
+declare const EXPO_SEND_URL = "https://exp.host/--/api/v2/push/send";
+declare const EXPO_RECEIPTS_URL = "https://exp.host/--/api/v2/push/getReceipts";
+/** Expo takes up to 100 messages per send. */
+declare const EXPO_SEND_BATCH = 100;
+/** And up to 1000 ticket ids per receipts request. */
+declare const EXPO_RECEIPTS_BATCH = 1000;
+/** One message for Expo. */
+interface PushMessage {
+    to: string;
+    title?: string;
+    subtitle?: string;
+    body?: string;
+    /** Reaches the app (`notification.request.content.data`): ids and the link, never content. */
+    data?: Record<string, string | number | boolean | null>;
+    sound?: "default" | null;
+    badge?: number;
+    /** Android: the notification channel (one per category). */
+    channelId?: string;
+    /** The device category whose actions it shows (Reply, Mark as read). */
+    categoryId?: string;
+    /** iOS: groups notifications on the lock screen (a conversation). */
+    threadId?: string;
+    /** Replaces an earlier one with the same id, in transit (and on screen on iOS). */
+    collapseId?: string;
+    /** Android: replaces one already on screen with the same tag. */
+    tag?: string;
+    ttl?: number;
+    priority?: "default" | "normal" | "high";
+    /** iOS: lets the app's Notification Service Extension change it (rich push). */
+    mutableContent?: boolean;
+}
+type PushTicket = {
+    status: "ok";
+    id: string;
+} | {
+    status: "error";
+    code: string;
+};
+type PushReceipt = {
+    status: "ok";
+} | {
+    status: "error";
+    code: string;
+};
+/** Sends pushes and reads receipts; `expoPushProvider` is the built-in one. */
+interface PushProvider {
+    readonly name: string;
+    /** At most `EXPO_SEND_BATCH` messages; one ticket per message, in order. Throws a `SendError` when the request failed. */
+    send(messages: readonly PushMessage[], options?: {
+        signal?: AbortSignal;
+    }): Promise<PushTicket[]>;
+    /** Receipts for at most `EXPO_RECEIPTS_BATCH` tickets; ids with none yet are left out. */
+    receipts(ids: readonly string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<Record<string, PushReceipt>>;
+}
+interface ExpoOptions extends HttpDeps {
+    /** Expo's access token, for "Enhanced Security for Push Notifications" (turn it on). */
+    accessToken?: string;
+    sendUrl?: string;
+    receiptsUrl?: string;
+}
+/** An Expo error code (`DeviceNotRegistered`), safe to store; anything else is `Unknown`. */
+declare function expoErrorCode(value: {
+    details?: {
+        error?: unknown;
+    };
+} | undefined): string;
+/** Expo refused the request itself (a 4xx other than 429): resend its messages one by one. */
+declare function refusedOutright(error: unknown): boolean;
+/**
+ * Expo's push service as a `PushProvider`.
+ *
+ * @stability Beta
+ */
+declare function expoPushProvider(options?: ExpoOptions): PushProvider;
+
+/**
+ * Resend's REST API as an `EmailProvider`. One key per app (`RESEND_API_KEY`);
+ * each tenant gets its own sender identity (`senderFor`), not its own key.
+ *
+ * Retries are byte-identical (the runner stores the first render), and every
+ * send carries an idempotency key, so Resend sends once:
+ * - 409 `invalid_idempotent_request`: the key was used with another body. The
+ *   stored render never changes, so the body differed in what is built at send
+ *   time: a secret link builder that isn't deterministic (it must give the same
+ *   link for the same notification every time). The job fails loudly
+ *   (`idempotency_body_changed`); it is never counted as sent.
+ * - 409 `concurrent_idempotent_requests`: another attempt is in flight: retry soon.
+ *
+ * Requests are paced (`perSecond`, default 5) under Resend's default limit of
+ * 10 requests a second per team, which every key of the team shares.
+ */
+
+/** One email, ready to send. Addresses and headers are already checked. */
+interface EmailMessage {
+    from: string;
+    to: string[];
+    replyTo?: string;
+    subject: string;
+    html: string;
+    text: string;
+    /** Extra headers (`List-Unsubscribe`, `List-Unsubscribe-Post`). */
+    headers?: Record<string, string>;
+    /** Provider tags: name and value are letters, digits, "_" or "-". */
+    tags?: {
+        name: string;
+        value: string;
+    }[];
+    /** Stable across retries of one send job. */
+    idempotencyKey: string;
+}
+interface EmailSendResult {
+    /** The provider's id for the email (what its webhooks name). */
+    id: string | null;
+    /** The provider says it was sent before (the same idempotency key). */
+    alreadySent?: boolean;
+}
+/** Sends one email. Throws a `SendError` on failure. */
+interface EmailProvider {
+    readonly name: string;
+    send(message: EmailMessage, options?: {
+        signal?: AbortSignal;
+    }): Promise<EmailSendResult>;
+}
+declare const RESEND_API = "https://api.resend.com/emails";
+/** Requests a second the provider starts by default: half Resend's default team limit (10). */
+declare const RESEND_DEFAULT_PER_SECOND = 5;
+interface ResendOptions extends HttpDeps {
+    apiKey: string;
+    endpoint?: string;
+    /** Requests started per second, at most. Default `RESEND_DEFAULT_PER_SECOND` (5). Raise it only if Resend raised your team's limit. */
+    perSecond?: number;
+    /** For tests: the clock and the wait the pacer uses. */
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/**
+ * Resend as an `EmailProvider`.
+ *
+ * @stability Beta
+ */
+declare function resendProvider(options: ResendOptions): EmailProvider;
+
+/**
+ * Secret links: a link whose query is a credential (a one-time sign-in, an
+ * invite, a response's edit link). They never go in `notifications.data` or
+ * a push. The domain stores a reference (`{ response_id }`) and, for a token
+ * that exists only hashed, passes the plaintext as `notify({ secret })`; the
+ * runner builds the link at send time, for the email only.
+ */
+/** What a secret link is built from. */
+interface SecretLinkRef {
+    /** The notification's `data` (references, never secrets). */
+    data: Record<string, unknown>;
+    /** The plaintext from `notify({ secret })`, decrypted for this send only. */
+    secret: string | null;
+    notificationId: string;
+    tenantId: string | null;
+}
+/** Type key → how its link is built. A builder signs the link with its own key, or puts `secret` in it. */
+type SecretLinks = Readonly<Record<string, (ref: SecretLinkRef) => string | Promise<string>>>;
+/** No builder for a type whose emails need one, or a builder that gave back something that isn't an https link. */
+declare class SecretLinkError extends Error {
+    constructor(message: string);
+}
+/**
+ * The secret link for one notification, built server-side at send time.
+ * Throws a `SecretLinkError` when there is no builder for `type` or it gives
+ * something other than an `https:` URL (`http:` only for localhost).
+ *
+ * @stability Beta
+ */
+declare function resolveSecretLink(links: SecretLinks, type: string, ref: SecretLinkRef): Promise<string>;
+/** What a template puts where the secret link goes; the runner swaps it in at send time, so the stored render never holds it. */
+declare const SECRET_LINK_PLACEHOLDER = "https://genesis-secret-link.invalid/";
+
+/**
+ * `createNotificationRunner`: sends what `notify()` queued, on the shared
+ * runner (`@marktiderman/genesis-notifications/runner`). Run `run()` every
+ * minute and `checkReceipts()` every 15 minutes (pg_cron with pg_net calling
+ * the handler, or any scheduler).
+ *
+ * Push: the claimed jobs' devices in Expo batches of 100 (a job's devices
+ * never split across two), each batch sent, its tickets recorded and its jobs
+ * settled on its own, and no batch started once its lease is about to run
+ * out (those jobs come straight back), with `threadId`,
+ * `categoryId`, `badge`, a `collapseId` (the collapse key, else the
+ * notification id, so a resend after a timeout replaces rather than repeats),
+ * and neutral text when the person hides previews or the type says so. The
+ * payload's `data` is the link, the notification id and the type, never the
+ * notification's own `data`. Tickets are recorded per device; a
+ * `DeviceNotRegistered` forgets the device.
+ *
+ * Email: rendered once at first claim and stored, so every retry sends the
+ * same bytes with the same idempotency key. From the tenant's verified
+ * domain, or the app's shared one with the tenant's name and reply-to;
+ * transactional and other mail from separate domains; RFC 8058 unsubscribe
+ * headers on everything that isn't transactional; a secret link swapped in
+ * at send time. The provider's id is kept the moment a send returns, before
+ * the job settles, so a webhook that comes first finds it.
+ *
+ * Links (a type's `render().url`) must be paths on the app's own origin
+ * (`/messages/42`): anything else (another host, `//host`, `javascript:`) is
+ * left out of the push and the email.
+ */
+
+interface EmailOptions {
+    provider: EmailProvider;
+    /** The from name when a tenant has none ("Example"). */
+    appName: string;
+    /**
+     * The app's shared sending domains, verified in Resend: transactional mail
+     * and other mail go from separate ones, so one's reputation never holds up
+     * the other. `other` defaults to `transactional`.
+     */
+    domains: {
+        transactional: string;
+        other?: string;
+    };
+    /** The address's local part. Default `notifications`. */
+    localPart?: string;
+    /** Type key → template. A type without one gets `defaultEmailTemplate`. */
+    templates?: Readonly<Record<string, EmailTemplate>>;
+    defaultTemplate?: EmailTemplate;
+    /** How each secret-link type's link is built (`resolveSecretLink`). */
+    secretLinks?: SecretLinks;
+    /** Required when any type sends email that isn't transactional. */
+    unsubscribe?: {
+        url: string;
+        secret: string;
+    };
+    /**
+     * The provider for one job. Default the app's `provider`. The seam for a
+     * tenant-owned key later (read from Vault by id); not built in v1.
+     */
+    providerFor?: (job: ClaimedJob) => EmailProvider;
+}
+interface NotificationRunnerOptions {
+    store: NotificationStore;
+    registry: NotificationRegistry;
+    push?: {
+        provider: PushProvider;
+    };
+    email?: EmailOptions;
+    /** The app's origin, for absolute links in emails (`https://app.example.com`). */
+    appUrl?: string;
+    /** Jobs claimed per channel per run. Default 100. */
+    batchSize?: number;
+    /** How long a claim holds a job. Default 300 seconds. */
+    leaseSeconds?: number;
+    /**
+     * How long one `run()` may take (your function's wall-clock limit, less a
+     * margin). With it, a run claims again while the last claim was full, and
+     * stops claiming once the time left is under the lease. Without it, a run
+     * claims once per channel. At least `leaseSeconds`.
+     */
+    runBudgetMs?: number;
+    maxAttempts?: number;
+    maxDeferrals?: number;
+    /** Safe lines only (ids, statuses, error codes). */
+    log?: (message: string) => void;
+    now?: () => number;
+}
+interface NotificationRunner {
+    /** Sends what is due on every configured channel. */
+    run(options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        push: RunReport | null;
+        email: RunReport | null;
+    }>;
+    runPush(options?: {
+        signal?: AbortSignal;
+    }): Promise<RunReport>;
+    runEmail(options?: {
+        signal?: AbortSignal;
+    }): Promise<RunReport>;
+    /** Asks Expo for the receipts that are due and records them. */
+    checkReceipts(options?: {
+        signal?: AbortSignal;
+        budgetMs?: number;
+    }): Promise<{
+        checked: number;
+        settled: number;
+    }>;
+}
+/**
+ * The runner.
+ *
+ * @stability Beta
+ */
+declare function createNotificationRunner(options: NotificationRunnerOptions): NotificationRunner;
+
+interface NotificationsHandlerOptions {
+    runner: NotificationRunner;
+    store: NotificationStore;
+    /** The bearer secret a scheduler sends to /run and /receipts (32 characters or more). */
+    cronSecret: string;
+    /** The unsubscribe signing secret (the runner's `email.unsubscribe.secret`). */
+    unsubscribeSecret?: string;
+    /** Resend's webhook signing secret (`whsec_…`). */
+    resendWebhookSecret?: string;
+    /** Words on the unsubscribe page. */
+    copy?: Partial<{
+        title: string;
+        confirm: string;
+        button: string;
+        done: string;
+        invalid: string;
+    }>;
+    log?: (message: string) => void;
+}
+/**
+ * The handler.
+ *
+ * @stability Beta
+ */
+declare function createNotificationsHandler(options: NotificationsHandlerOptions): (request: Request) => Promise<Response>;
+
+/**
+ * A request pacer: at most `perSecond` requests start in any second, spaced
+ * evenly, however many callers wait at once. Each provider instance has its
+ * own; two runners running at once each keep to it, so set it for that.
+ */
+interface RateLimiter {
+    /** Resolves when the caller may start its request; rejects if `signal` aborts first. */
+    acquire(signal?: AbortSignal): Promise<void>;
+}
+interface RateLimiterOptions {
+    perSecond: number;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** @stability Beta */
+declare function createRateLimiter(options: RateLimiterOptions): RateLimiter;
+
+interface UnsubscribeClaims {
+    /** The login, when the recipient has one. */
+    userId?: string;
+    /** SHA-256 (hex) of the lower-cased, trimmed address, when they have none (`emailHash`). */
+    emailHash?: string;
+    category: string;
+    /** The tenant the email came from; the unsubscribe holds for it only. */
+    tenantId?: string;
+}
+/** What the suppression list keys an address by: SHA-256 of it lower-cased and trimmed (as `genesis_notifications_email_hash`). */
+declare function emailHash(email: string): Promise<string>;
+/** A signed, URL-safe token for `claims`. */
+declare function createUnsubscribeToken(secret: string, claims: UnsubscribeClaims): Promise<string>;
+/** The claims of a token this secret signed, or null for anything else. */
+declare function verifyUnsubscribeToken(secret: string, token: string): Promise<UnsubscribeClaims | null>;
+/** The RFC 8058 headers for one email. `url` is your unsubscribe endpoint; the token goes in its query. */
+declare function unsubscribeHeaders(url: string, token: string): Record<string, string>;
+
+/** How far a webhook's timestamp may be from now: five minutes, as Svix checks. */
+declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+/** Whether `body` was signed with `secret`; false for anything stale, unsigned or malformed. */
+declare function verifyResendWebhook(secret: string, headers: Headers, body: string, now?: number): Promise<boolean>;
+/** What the notifier does with an email event; null for the events it doesn't use. */
+declare function emailEventOf(payload: unknown): {
+    providerId: string;
+    event: "delivered" | "bounced" | "complained";
+    permanent: boolean;
+} | null;
+
+/**
+ * Is a sender domain the tenant's, and ready to send from? An ownership TXT
+ * record holding the tenant's own token (so one tenant can't verify another's
+ * domain), SPF on Resend's return-path host, DKIM at Resend's selector, and a
+ * DMARC record, read through DNS over HTTPS so it runs anywhere `fetch` does.
+ * The app's own shared sending domains (and anything under them) are never a
+ * tenant's.
+ */
+
+interface DomainCheck {
+    /** `_genesis-notifications.<domain>` holds `genesis-notifications-verify=<token>`. */
+    ownership: boolean;
+    spf: boolean;
+    dkim: boolean;
+    dmarc: boolean;
+    /** The domain is (or is under) one of the app's own shared domains: never a tenant's. */
+    reserved: boolean;
+    /** Owned, all three records, and not reserved. */
+    ok: boolean;
+}
+interface DomainCheckOptions extends HttpDeps {
+    /** The sender's `domain_token` (from `notification_senders`; made when the domain was set). */
+    token: string;
+    /** The app's shared sending domains (`email.domains`): a tenant may never verify one, or one under it. */
+    reservedDomains: readonly string[];
+    /** Default Cloudflare's JSON resolver. */
+    resolver?: string;
+    /** Resend's DKIM selector. Default `resend`. */
+    dkimSelector?: string;
+    /** Where the SPF record lives. Default `send.<domain>` (Resend's return path). */
+    spfHost?: string;
+    /** What the SPF record includes. Default `amazonses.com` (Resend's). */
+    spfInclude?: string;
+}
+/** The ownership record's host. */
+declare const SENDER_OWNERSHIP_HOST = "_genesis-notifications";
+/**
+ * The TXT record a tenant adds to prove `domain` is theirs: show it beside
+ * Resend's SPF and DKIM records in your sender settings.
+ *
+ * @stability Beta
+ */
+declare function senderOwnershipRecord(domain: string, token: string): {
+    type: "TXT";
+    name: string;
+    value: string;
+};
+/** Whether `domain` is one of `reserved`, or under one. */
+declare function isReservedDomain(domain: string, reserved: readonly (string | undefined | null)[]): boolean;
+/**
+ * Checks ownership, SPF, DKIM and DMARC for `domain`. Record the result with
+ * `genesis_notifications_set_sender_dns(tenant, domain, token, ok ? 'verified' : 'failed', result)`
+ * with the same token, so a check made before the tenant changed its domain changes nothing.
+ *
+ * @stability Beta
+ */
+declare function checkSenderDomain(domain: string, options: DomainCheckOptions): Promise<DomainCheck>;
+
+export { type CancelInput, type ClaimedDevice, type ClaimedJob, type DomainCheck, type DomainCheckOptions, EXPO_RECEIPTS_BATCH, EXPO_RECEIPTS_URL, EXPO_SEND_BATCH, EXPO_SEND_URL, type EmailMessage, type EmailOptions, type EmailProvider, type EmailSendResult, EmailTemplate, type ExpoOptions, type HttpDeps, type NotificationRunner, type NotificationRunnerOptions, type NotificationStore, NotificationStoreError, type NotificationsHandlerOptions, type NotifyOptions, type PushMessage, type PushProvider, type PushReceipt, type PushTicket, type PushTicketRow, REQUEST_TIMEOUT_MS, RESEND_API, RESEND_DEFAULT_PER_SECOND, type RateLimiter, type RateLimiterOptions, type RenderedEmail, type ResendOptions, type RpcClient, SECRET_LINK_PLACEHOLDER, SENDER_OWNERSHIP_HOST, SecretLinkError, type SecretLinkRef, type SecretLinks, SendError, type SenderIdentity, type SettleOutcome, type UnsubscribeClaims, WEBHOOK_TOLERANCE_SECONDS, cancelNotification, checkSenderDomain, createNotificationRunner, createNotificationsHandler, createRateLimiter, createUnsubscribeToken, emailEventOf, emailHash, expoErrorCode, expoPushProvider, isReservedDomain, isRetryableStatus, notify, refusedOutright, resendProvider, resolveSecretLink, retryAfterSeconds, senderOwnershipRecord, supabaseNotificationStore, syncNotificationTypes, unsubscribeHeaders, verifyResendWebhook, verifyUnsubscribeToken };