@marktiderman/genesis-forms 0.7.0 → 0.9.0

package/dist/destinations.d.cts

@@ -1,4 +1,4 @@
-import { J as Json, F as FormDefinition, a as FieldBlock } from './types-oAckGR_Z.cjs';
+import { J as Json, F as FormDefinition, a as FieldBlock, C as Condition } from './types-C0pUfew3.cjs';
 
 /**
  * The contract every destination keeps. A destination sends one checked
@@ -53,12 +53,26 @@ interface DeliveryOptions {
     redelivery?: boolean | undefined;
     /** Aborts the delivery. Each request also has its own timeout. */
     signal?: AbortSignal | undefined;
+    /**
+     * The submission was delivered before and this is its update (an edit).
+     * The sheet overwrites the response's row where it is (appending only when
+     * it is gone), and the webhook's event type becomes `form.updated`.
+     */
+    update?: boolean | undefined;
+    /**
+     * The app's id for the destination. Passed on to option functions (a
+     * secret, an account, an access token, a URL), so they can look up what
+     * is stored for it.
+     */
+    destinationId?: string | undefined;
 }
 /** One submission in a batch: each carries its own definition and delivery id. */
 interface DeliveryItem {
     submission: DeliverySubmission;
     definition: FormDefinition;
     deliveryId?: string | undefined;
+    /** This item is an update of a submission delivered before (see `DeliveryOptions.update`). */
+    update?: boolean | undefined;
 }
 type DeliveryResult = {
     ok: true;
@@ -66,6 +80,12 @@ type DeliveryResult = {
     state?: Record<string, Json>;
     /** Submission ids already there (a redelivery), so nothing was sent for them. */
     skipped?: string[];
+    /**
+     * Set when the destination deliberately sent nothing (no address to
+     * send to, a daily cap reached): the reason, safe to store. Not a
+     * failure and never retried; `createDeliveryRunner` records it as skipped.
+     */
+    notSent?: string;
 } | DeliveryFailure;
 interface DeliveryFailure {
     ok: false;
@@ -83,6 +103,12 @@ interface DeliveryFailure {
     retryAfterSeconds?: number;
     /** The HTTP status that refused it, if one did. */
     status?: number;
+    /**
+     * The receiver asked to be switched off (a webhook answered 410 Gone, as
+     * Standard Webhooks specifies): disable the destination rather than keep
+     * sending to it. Always with `retryable: false`.
+     */
+    disable?: true;
     /** Safe to store and log: a status and a short reason, never secrets, answers or contact details. */
     error: string;
 }
@@ -109,10 +135,13 @@ declare class DeliveryError extends Error {
     readonly retryable: boolean;
     readonly retryAfterSeconds: number | undefined;
     readonly status: number | undefined;
+    /** The receiver asked to be switched off (`DeliveryFailure.disable`); never retryable. */
+    readonly disable: boolean;
     constructor(message: string, options?: {
         retryable?: boolean | undefined;
         retryAfterSeconds?: number | undefined;
         status?: number | undefined;
+        disable?: boolean | undefined;
     });
 }
 /** Every outbound request gives up after this long, unless the destination is given another `timeoutMs`. */
@@ -149,6 +178,15 @@ interface HttpDeps {
     /** Per request. Default `REQUEST_TIMEOUT_MS`. */
     timeoutMs?: number | undefined;
 }
+/** What an option function is told besides the config. */
+interface ResolveContext {
+    /** `DeliveryOptions.destinationId`, when the app gave one. */
+    destinationId?: string | undefined;
+}
+/** A factory option worked out per delivery from the destination's config. */
+type OptionResolver<T> = (config: DestinationConfig, context: ResolveContext) => T | Promise<T>;
+/** WebCrypto's key type, named without depending on the DOM lib. */
+type WebCryptoKey = Awaited<ReturnType<typeof crypto.subtle.importKey>>;
 
 interface RowOptions {
     /**
@@ -342,8 +380,18 @@ interface SheetConfig {
     sheetName?: string;
 }
 interface SheetsDestinationOptions extends HttpDeps {
-    /** The service account, or a function that finds the one for a destination's config. */
-    account: GoogleServiceAccount | ((config: DestinationConfig) => GoogleServiceAccount | Promise<GoogleServiceAccount>);
+    /**
+     * The service account the sheet is shared with, or a function that finds
+     * the one for a destination's config. Give this or `accessToken`.
+     */
+    account?: GoogleServiceAccount | OptionResolver<GoogleServiceAccount> | undefined;
+    /**
+     * An access token for the sheet instead of a service account: a sheet a
+     * person connected with Google sign-in, say (see `googleOAuthAccessToken`).
+     * Gets the config and `{ destinationId }`; called once per delivery or
+     * batch, so cache inside it.
+     */
+    accessToken?: OptionResolver<string> | undefined;
     /**
      * Prefix text a spreadsheet could run as a formula with `'` (see
      * `escapeFormula`), headers included. Default false: writes are RAW, so
@@ -381,35 +429,94 @@ interface SheetState {
 }
 declare function sheetsDestination(options: SheetsDestinationOptions): Destination;
 
+/**
+ * Where a Slack or webhook destination may post, checked against SSRF: https
+ * only, on the default port, with no credentials in the address, and only to
+ * a public host, never a private, loopback, link-local or otherwise internal
+ * one. `parseHookUrl` checks the text (use it when someone adds the address);
+ * `checkHookHost` checks every address the name resolves to right now (use it
+ * before every request: what a name points to can change).
+ *
+ * A check before the request still leaves a short window in which the name
+ * could be re-pointed (DNS rebinding). Where untrusted people choose URLs,
+ * also send from a network that cannot reach internal services.
+ */
+
+type HookKind = "slack" | "webhook";
+/** Resolves a host name to its addresses (IPv4 and IPv6), as the server's DNS sees them. In Node: `dns.promises.lookup(host, { all: true })` mapped to `.address`. */
+type ResolveHost = (host: string) => Promise<string[]>;
+declare const MAX_HOOK_URL_LENGTH = 2048;
+/** The hosts a Slack incoming webhook lives on. */
+declare const SLACK_HOSTS: ReadonlySet<string>;
+/** An address that can't be used, with a reason safe to show and to store (never the address). */
+declare class HookUrlError extends DeliveryError {
+    name: string;
+}
+/** Whether an IP address (v4 or v6) is a public one a hook may reach. Anything unparsable is not. */
+declare function isPublicAddress(ip: string): boolean;
+/**
+ * The address as it will be used (its fragment dropped), or a `HookUrlError`
+ * saying what is wrong with it. Checks the text only; `checkHookHost` checks
+ * where the name resolves. A `"slack"` address must be a Slack incoming
+ * webhook (`https://hooks.slack.com/services/…`).
+ */
+declare function parseHookUrl(raw: string, kind?: HookKind): URL;
+/**
+ * Checks that every address the URL's host resolves to is public. A host
+ * that resolves to nothing, or whose lookup fails, is refused too, as a
+ * retryable failure (DNS may be briefly down); a private address is final.
+ */
+declare function checkHookHost(url: URL, resolve: ResolveHost): Promise<void>;
+/** The host as a screen may show it (never the path: a Slack or webhook path can be the secret). */
+declare function hookHost(url: URL): string;
+
 /** What the webhook destination reads from a destination's config. */
 interface WebhookConfig {
     url: string;
 }
 interface WebhookDestinationOptions extends HttpDeps {
     /**
-     * The signing secret: base64 of at least 16 random bytes, usually with
-     * the `whsec_` prefix Standard Webhooks tools issue (`whsec_` plus base64
-     * of 24 to 64 bytes is what the spec recommends). The prefix is optional;
-     * the rest is always base64-decoded, as every Standard Webhooks library
-     * does, so a receiver verifies with the same string. A secret that is not
-     * base64 fails permanently. Or a function that finds the one for a
-     * destination's config. Never put it in config.
+     * The signing secret: base64 of at least 24 random bytes (the spec
+     * recommends 24 to 64), usually with the `whsec_` prefix Standard Webhooks
+     * tools issue. The prefix is optional; the rest is always base64-decoded,
+     * as every Standard Webhooks library does, so a receiver verifies with the
+     * same string. A secret that is not base64, or is shorter, fails
+     * permanently. Several secrets (new and old, during a rotation) sign with
+     * each, space-separated in `webhook-signature`, so the receiver verifies
+     * with either. Or a function that finds them for a destination's config.
+     * Never put it in config.
      */
-    secret: string | ((config: DestinationConfig) => string | Promise<string>);
+    secret: string | readonly string[] | OptionResolver<string | readonly string[]>;
     /** Allow `http:` URLs. Default false. */
     allowInsecureUrls?: boolean | undefined;
     /** Allow localhost and private, loopback and link-local address literals. Default false. */
     allowPrivateHosts?: boolean | undefined;
     /** Sensitive fields: `"include"` (default), `"mask"` or `"omit"`. */
     sensitive?: RowOptions["sensitive"];
-    /** The event type in the payload. Default `"form.submitted"`. */
+    /** The event type in the payload. Default `"form.submitted"`, or `"form.updated"` for an update. */
     type?: string | undefined;
+    /**
+     * Where to post, when it is not `config.url`: the address kept apart from
+     * config (encrypted, say, since a webhook URL can carry a token). Gets the
+     * config and `{ destinationId }`. It passes the same checks.
+     */
+    url?: OptionResolver<string> | undefined;
+    /**
+     * Resolves the URL's host before every request, and the delivery is refused
+     * unless every address is public (see `checkHookHost`). This catches a
+     * hostname that points at a private address, which the URL checks alone
+     * cannot. Recommended wherever untrusted people choose URLs.
+     */
+    resolveHost?: ResolveHost | undefined;
     now?: (() => number) | undefined;
 }
 /** The JSON body a webhook receives. */
 interface WebhookPayload {
     type: string;
-    /** ISO time the delivery was sent. */
+    /**
+     * ISO time the event happened: the submission's `submittedAt`, or the send
+     * time when it has none. The `webhook-timestamp` header is the send time.
+     */
     timestamp: string;
     data: {
         form: {
@@ -431,11 +538,26 @@ interface WebhookPayload {
         row: Record<string, Json>;
     };
 }
-/** The `webhook-signature` value for a message: `v1,<base64>`. */
-declare function signWebhook(secret: string, id: string, timestamp: number, body: string): Promise<string>;
+/** The shortest signing secret, decoded: Standard Webhooks recommends 24 to 64 bytes. */
+declare const MIN_WEBHOOK_SECRET_BYTES = 24;
+/**
+ * A new signing secret: `whsec_` and standard base64 of 32 random bytes, the
+ * form Standard Webhooks libraries read. Show it to the receiver once; keep it
+ * out of config.
+ */
+declare function newWebhookSecret(): string;
+/**
+ * The `webhook-signature` value for a message: `v1,<base64>`, or one such
+ * signature per secret, space-separated, when given several (a rotation).
+ */
+declare function signWebhook(secret: string | readonly string[], id: string, timestamp: number, body: string): Promise<string>;
 interface VerifyWebhookInput {
-    /** The same secret the sender signs with (base64, optionally `whsec_`-prefixed). */
-    secret: string;
+    /**
+     * The same secret the sender signs with (base64, optionally
+     * `whsec_`-prefixed), or several (new and old, during a rotation): any one
+     * matching signature passes.
+     */
+    secret: string | readonly string[];
     /** The request's headers: a `Headers` or a plain object. */
     headers: Headers | Record<string, string | string[] | undefined>;
     /** The raw body, exactly as received. */
@@ -462,4 +584,316 @@ declare function webhookPayload(submission: DeliverySubmission, definition: Form
 }): WebhookPayload;
 declare function webhookDestination(options: WebhookDestinationOptions): Destination;
 
-export { type Cell, DEDUPE_WINDOW, DEFAULT_SHEET_NAME, DeliveryError, type DeliveryFailure, type DeliveryItem, type DeliveryOptions, type DeliveryResult, type DeliverySubmission, type Destination, type DestinationConfig, type EmailConfig, type EmailContent, type EmailDestinationOptions, type EmailMessage, type EmailProvider, type EmailRenderInput, GOOGLE_TOKEN_URL, type GoogleServiceAccount, type GoogleTokenOptions, HEADER_SCAN_ROWS, type HttpDeps, MAX_RECIPIENTS, REQUEST_TIMEOUT_MS, RESEND_API, type ResendOptions, type ResponseRow, type RowOptions, SENSITIVE_MASK, SHEETS_API, SHEETS_SCOPE, type SheetConfig, type SheetState, type SheetsDestinationOptions, type VerifyWebhookInput, type WebhookConfig, type WebhookDestinationOptions, type WebhookPayload, answerCell, checkWebhookUrl, clearGoogleTokenCache, columnLetter, deliveryFailure, emailBody, emailDestination, escapeFormula, escapeHtml, googleAccessToken, headerSafe, httpError, idempotencyKey, isPrivateHost, isRetryableStatus, isSafeAddress, isSafeFrom, mergeHeader, renderEmail, resendProvider, responseRow, retryAfterSeconds, rowFor, sheetsDestination, signJwt, signWebhook, verifyWebhook, visibleInputs, webhookDestination, webhookPayload };
+/**
+ * The Slack destination: one message per submission to a Slack incoming
+ * webhook (the channel is the webhook's). The message is a heading (the
+ * form's title), each answer as "label: value" in form order, and a footer
+ * with a link back to the app when one is given. Every value is escaped, so
+ * text a respondent typed can't mention `@channel` or make a link.
+ *
+ * The webhook URL is itself the credential, so it is usually kept out of
+ * config: pass `url` to look it up. It must be a Slack incoming webhook
+ * (`https://hooks.slack.com/services/…`); redirects are not followed.
+ */
+
+/** Longest answer shown in full; longer ones are cut (the app has the rest). */
+declare const SLACK_VALUE_LIMIT = 1500;
+/** Text for Slack's mrkdwn: `&`, `<` and `>` escaped, which is all Slack asks. */
+declare function escapeSlack(text: string): string;
+interface SlackMessageOptions {
+    /** The heading, as plain text (it is escaped). Default `New response: <title>`, or `Updated response: …` for an update. */
+    heading?: string | undefined;
+    /** An update of a submission delivered before. */
+    update?: boolean | undefined;
+    /** Lines shown before the answers, as `[label, value]` plain text (a location, a session). */
+    lines?: readonly (readonly [string, string])[] | undefined;
+    /** A link back to the response in the app: http(s) only. */
+    link?: {
+        url: string;
+        text?: string | undefined;
+    } | null | undefined;
+    /** Sensitive fields: `"mask"` (default), `"omit"` or `"include"`. A channel is usually wider than an inbox. */
+    sensitive?: RowOptions["sensitive"];
+    /** Field keys left out (contact details, say). */
+    omit?: readonly string[] | undefined;
+}
+/** The message Slack gets for one submission: `{ text }` in Slack mrkdwn. */
+declare function slackMessage(submission: DeliverySubmission, definition: FormDefinition, options?: SlackMessageOptions): {
+    text: string;
+};
+interface SlackMessageInput {
+    submission: DeliverySubmission;
+    definition: FormDefinition;
+    config: DestinationConfig;
+    /** `DeliveryOptions.update`. */
+    update: boolean;
+    destinationId?: string | undefined;
+}
+interface SlackDestinationOptions extends HttpDeps {
+    /**
+     * The incoming webhook URL, when it is not `config.url`. Gets the config
+     * and `{ destinationId }`.
+     */
+    url?: OptionResolver<string> | undefined;
+    /** Resolves the host before every request; the delivery is refused unless every address is public. */
+    resolveHost?: ResolveHost | undefined;
+    /** The message's options per delivery (heading, extra lines, a link back). */
+    message?: ((input: SlackMessageInput) => SlackMessageOptions | Promise<SlackMessageOptions>) | undefined;
+}
+declare function slackDestination(options?: SlackDestinationOptions): Destination;
+
+/** How deep `all` / `any` / `not` may nest in a stored condition. */
+declare const MAX_CONDITION_DEPTH = 10;
+/** Whether a stored value has a `Condition`'s shape, nested at most `MAX_CONDITION_DEPTH` deep. */
+declare function isCondition(v: unknown, depth?: number): v is Condition;
+/**
+ * The destination's condition (`config.when`), or null when it has none. One
+ * that can't be read throws a permanent `DeliveryError` rather than meaning
+ * "send everything" or "send nothing".
+ */
+declare function conditionOf(config: DestinationConfig): Condition | null;
+/**
+ * Whether a submission matches its destination's condition (true when there
+ * is none). Throws a `DeliveryError` when the condition can't be read.
+ */
+declare function passesCondition(submission: Pick<DeliverySubmission, "answers" | "hidden" | "context">, definition: FormDefinition, config: DestinationConfig): boolean;
+
+/** Google's scope for files the person picked or created through the app. */
+declare const DRIVE_FILE_SCOPE = "https://www.googleapis.com/auth/drive.file";
+/** The app's OAuth client, from the Google Cloud console. Server-side only. */
+interface GoogleOAuthClient {
+    clientId: string;
+    clientSecret: string;
+}
+interface GoogleOAuthTokenOptions extends HttpDeps {
+    now?: (() => number) | undefined;
+    signal?: AbortSignal | undefined;
+}
+interface RefreshedGoogleToken {
+    accessToken: string;
+    /** Seconds the access token is good for. */
+    expiresIn: number;
+    /** The scopes granted, space-separated. */
+    scope: string;
+}
+/**
+ * Trades a refresh token for an access token, uncached. `invalid_grant`
+ * (access revoked, or the account gone) is a permanent failure saying to
+ * connect the sheet again; 429 and 5xx are retryable. Never puts a token in
+ * an error message.
+ */
+declare function refreshGoogleAccessToken(client: GoogleOAuthClient, refreshToken: string, options?: GoogleOAuthTokenOptions): Promise<RefreshedGoogleToken>;
+/** Forgets cached OAuth access tokens (tests, or after a sheet is disconnected). */
+declare function clearGoogleOAuthTokenCache(): void;
+/** A cached or fresh access token for a refresh token, cached until a minute before it expires. */
+declare function googleOAuthAccessToken(client: GoogleOAuthClient, refreshToken: string | null | undefined, options?: GoogleOAuthTokenOptions): Promise<string>;
+
+/**
+ * Keeping a destination's secrets at rest: a webhook or Slack URL, a signing
+ * secret, a Google refresh token. AES-256-GCM (WebCrypto) under a key derived
+ * with HKDF-SHA-256 from one 32-byte app secret and a purpose string, so no
+ * two purposes share a key; each ciphertext is bound to associated data (the
+ * row it belongs to), so one moved onto another row does not decrypt.
+ *
+ * The sealed form is `v1.<iv>.<ciphertext and tag>`, base64url. Where it is
+ * stored is the app's; the key never is.
+ */
+
+/**
+ * The 32 key bytes from base64 or base64url text (as `openssl rand -base64 32`
+ * prints), or the bytes themselves. Throws a `DeliveryError` naming the
+ * problem, never the key.
+ */
+declare function secretKeyBytes(key: string | Uint8Array): Uint8Array<ArrayBuffer>;
+/** Options for `deriveSecretKey`. */
+interface DeriveSecretKeyOptions {
+    /**
+     * The HKDF salt: bytes, or text taken as its UTF-8 bytes. Default empty,
+     * which is what every key derived before this option existed used, so
+     * leave it out to open those. For new keys a fixed, app-wide random value
+     * (say 32 bytes from `openssl rand -base64 32`, kept as config) is
+     * recommended (RFC 5869). It need not be secret, but must never change
+     * once anything is sealed with it.
+     */
+    salt?: string | Uint8Array | undefined;
+}
+/**
+ * An AES-GCM key for one purpose, derived from the app secret with HKDF-SHA-256
+ * (`info` naming the purpose; the salt empty unless `options.salt` is given).
+ * Use a different `info` for each kind of secret; keep it, and the salt,
+ * fixed once anything is sealed with them.
+ */
+declare function deriveSecretKey(key: string | Uint8Array, info: string, options?: DeriveSecretKeyOptions): Promise<WebCryptoKey>;
+/** Encrypts `plaintext` bound to `aad` (the row it belongs to): `v1.<iv>.<ciphertext>`. */
+declare function sealSecret(key: WebCryptoKey, plaintext: string, aad: string): Promise<string>;
+/**
+ * Decrypts what `sealSecret` sealed with the same key and `aad`. Throws a
+ * permanent `DeliveryError` for an unknown format, a wrong key (rotated?) or
+ * a ciphertext from another row; never echoes the ciphertext.
+ */
+declare function openSecret(key: WebCryptoKey, sealed: string, aad: string): Promise<string>;
+
+/**
+ * The outbox runner: claim a batch of due deliveries, send each to its
+ * destination, and record what happened. The store is the app's (a SQL
+ * outbox, a queue, a KV list): it hands over claimed deliveries and takes
+ * back outcomes, and decides how claims and leases work. The runner owns the
+ * rest: the destination's condition (`config.when`), batching deliveries to
+ * one destination into one request where the destination can, keeping its
+ * state, and turning each result into an outcome with a retry time.
+ *
+ * Outcomes:
+ * - `sent`: delivered (or already there, on a redelivery).
+ * - `filtered`: the submission doesn't match the destination's condition; nothing was sent, nothing to retry.
+ * - `skipped`: the destination deliberately sent nothing (`notSent`); never retried.
+ * - `retry`: a retryable failure. With the service's own Retry-After it is
+ *   deferred without counting an attempt (`counted: false`); otherwise it backs
+ *   off by attempt (`counted: true`), until `maxAttempts`.
+ * - `failed`: permanent, an unknown kind, or out of attempts. With `disable:
+ *   true` the receiver asked to be switched off (a webhook's 410 Gone): the
+ *   app should disable the destination rather than keep sending to it.
+ *
+ * It never throws for a delivery's failure, and never logs answers, contact
+ * details or secrets: only ids, kinds and the destinations' safe messages.
+ */
+
+/** One claimed delivery, as the app's store hands it over. */
+interface ClaimedDelivery {
+    /** The delivery's id: stable across its retries (the email idempotency key, the webhook-id). */
+    id: string;
+    /** The destination's id. Deliveries to one destination are batched, and its state is kept by it. */
+    destinationId: string;
+    /** The destination's kind: a key of `destinations`. */
+    kind: string;
+    /** The destination's config (no secrets). */
+    config: DestinationConfig;
+    /** What the destination cached last time (`DeliveryResult.state`), as stored. */
+    state?: Record<string, Json> | undefined;
+    submission: DeliverySubmission;
+    definition: FormDefinition;
+    /** This delivery's attempt number, from 1 for its first. */
+    attempt: number;
+    /**
+     * How many times it was deferred so far (outcomes with `counted: false`).
+     * Keep and pass it back, so `maxDeferrals` can stop a service that answers
+     * "try later" forever. Default 0.
+     */
+    deferrals?: number | undefined;
+    /**
+     * An earlier attempt may have gone through (it was claimed before and timed
+     * out, or its lease ran out), so destinations that can look first do.
+     */
+    redelivery?: boolean | undefined;
+    /** An update of a submission delivered before (an edit). */
+    update?: boolean | undefined;
+}
+type DeliveryOutcome = {
+    status: "sent";
+    /** It was already there (a redelivery), so nothing was sent this time. */
+    alreadyThere?: boolean;
+} | {
+    status: "filtered";
+} | {
+    status: "skipped";
+    /** Why, safe to store. */
+    reason: string;
+} | {
+    status: "retry";
+    error: string;
+    /** When to try again. */
+    retryAt: Date;
+    retryAfterSeconds: number;
+    /** Whether this attempt counts toward `maxAttempts`. False when the service said when to come back. */
+    counted: boolean;
+    httpStatus?: number;
+} | {
+    status: "failed";
+    error: string;
+    httpStatus?: number;
+    /** The receiver asked to be switched off (a webhook's 410 Gone): disable the destination. */
+    disable?: true;
+};
+interface ClaimRequest<Filter> {
+    /** Most deliveries to claim. */
+    limit: number;
+    /** What `run` was given: the app's own narrowing (one response, one account). */
+    filter?: Filter | undefined;
+}
+interface DeliveryRunnerOptions<Filter = undefined> {
+    /** Claims up to `limit` due deliveries, each held (leased) so no other runner sends it meanwhile. */
+    claim(request: ClaimRequest<Filter>): Promise<readonly ClaimedDelivery[]>;
+    /**
+     * Records an outcome. Resolve `false` when the claim was no longer held
+     * (its lease ran out and another runner took it): it is counted as stale.
+     * A rejection is logged and counted as unrecorded; the lease then runs out
+     * and the delivery comes back on its own.
+     */
+    record(delivery: ClaimedDelivery, outcome: DeliveryOutcome): Promise<void | boolean>;
+    /** Keeps a destination's new state (a sheet's header and last row). Failures are logged, never fatal. */
+    saveState?: ((destinationId: string, state: Record<string, Json>) => Promise<void>) | undefined;
+    /** The destinations by kind. */
+    destinations: Readonly<Record<string, Destination>>;
+    now?: (() => number) | undefined;
+    /** Safe lines (ids, kinds, short reasons). Default: nothing is logged. */
+    log?: ((message: string) => void) | undefined;
+    /** Deliveries claimed per run. Default 25. */
+    batchSize?: number | undefined;
+    /** Counted attempts before a retryable failure is given up. Default `DEFAULT_MAX_ATTEMPTS` (8). */
+    maxAttempts?: number | undefined;
+    /**
+     * Deferrals (Retry-After, no attempt counted) allowed before a further one
+     * counts as an attempt and backs off. Default `DEFAULT_MAX_DEFERRALS` (24).
+     */
+    maxDeferrals?: number | undefined;
+    /** Seconds to wait after a counted failed attempt. Default `defaultBackoff`. */
+    backoff?: ((attempt: number) => number) | undefined;
+}
+interface DeliveryReport {
+    claimed: number;
+    sent: number;
+    filtered: number;
+    skipped: number;
+    /** Retryable failures, backed off by attempt. */
+    retrying: number;
+    /** Retryable failures the service said when to retry; no attempt used. */
+    deferred: number;
+    failed: number;
+    /** Recorded after the claim was lost (`record` resolved false). */
+    stale: number;
+    /** `record` threw. */
+    unrecorded: number;
+}
+interface RunOptions<Filter> {
+    filter?: Filter | undefined;
+    /** Overrides `batchSize` for this run. */
+    limit?: number | undefined;
+    /** Aborts the sends in flight; their outcomes are recorded as retries. */
+    signal?: AbortSignal | undefined;
+}
+interface DeliveryRunner<Filter = undefined> {
+    /** One claim, its sends and their records. Never rejects for a delivery's failure; a failing `claim` rejects. */
+    run(options?: RunOptions<Filter>): Promise<DeliveryReport>;
+}
+declare const DEFAULT_MAX_ATTEMPTS = 8;
+declare const DEFAULT_MAX_DEFERRALS = 24;
+declare const DEFAULT_BATCH_SIZE = 25;
+/**
+ * 5 minutes, quadrupling each attempt, at most 24 hours: 5m, 20m, 80m, 5h20m,
+ * 21h20m, then 24h. Across the default 8 attempts that is about 3 days, as
+ * Standard Webhooks suggests. Each wait is jittered by up to ±20%, so
+ * deliveries that failed together (a receiver's outage) don't all come back
+ * at once. `random` (default `Math.random`) is for tests.
+ */
+declare function defaultBackoff(attempt: number, random?: () => number): number;
+/** Turns a destination's result into an outcome for a delivery on its `attempt`. */
+declare function deliveryOutcome(result: DeliveryResult, attempt: number, options?: {
+    now?: number | undefined;
+    maxAttempts?: number | undefined;
+    backoff?: ((attempt: number) => number) | undefined;
+    /** Deferrals so far (`ClaimedDelivery.deferrals`). */
+    deferrals?: number | undefined;
+    maxDeferrals?: number | undefined;
+}): DeliveryOutcome;
+declare function createDeliveryRunner<Filter = undefined>(options: DeliveryRunnerOptions<Filter>): DeliveryRunner<Filter>;
+
+export { type Cell, type ClaimRequest, type ClaimedDelivery, DEDUPE_WINDOW, DEFAULT_BATCH_SIZE, DEFAULT_MAX_ATTEMPTS, DEFAULT_MAX_DEFERRALS, DEFAULT_SHEET_NAME, DRIVE_FILE_SCOPE, DeliveryError, type DeliveryFailure, type DeliveryItem, type DeliveryOptions, type DeliveryOutcome, type DeliveryReport, type DeliveryResult, type DeliveryRunner, type DeliveryRunnerOptions, type DeliverySubmission, type DeriveSecretKeyOptions, type Destination, type DestinationConfig, type EmailConfig, type EmailContent, type EmailDestinationOptions, type EmailMessage, type EmailProvider, type EmailRenderInput, GOOGLE_TOKEN_URL, type GoogleOAuthClient, type GoogleOAuthTokenOptions, type GoogleServiceAccount, type GoogleTokenOptions, HEADER_SCAN_ROWS, type HookKind, HookUrlError, type HttpDeps, MAX_CONDITION_DEPTH, MAX_HOOK_URL_LENGTH, MAX_RECIPIENTS, MIN_WEBHOOK_SECRET_BYTES, type OptionResolver, REQUEST_TIMEOUT_MS, RESEND_API, type RefreshedGoogleToken, type ResendOptions, type ResolveContext, type ResolveHost, type ResponseRow, type RowOptions, type RunOptions, SENSITIVE_MASK, SHEETS_API, SHEETS_SCOPE, SLACK_HOSTS, SLACK_VALUE_LIMIT, type SheetConfig, type SheetState, type SheetsDestinationOptions, type SlackDestinationOptions, type SlackMessageInput, type SlackMessageOptions, type VerifyWebhookInput, type WebCryptoKey, type WebhookConfig, type WebhookDestinationOptions, type WebhookPayload, answerCell, checkHookHost, checkWebhookUrl, clearGoogleOAuthTokenCache, clearGoogleTokenCache, columnLetter, conditionOf, createDeliveryRunner, defaultBackoff, deliveryFailure, deliveryOutcome, deriveSecretKey, emailBody, emailDestination, escapeFormula, escapeHtml, escapeSlack, googleAccessToken, googleOAuthAccessToken, headerSafe, hookHost, httpError, idempotencyKey, isCondition, isPrivateHost, isPublicAddress, isRetryableStatus, isSafeAddress, isSafeFrom, mergeHeader, newWebhookSecret, openSecret, parseHookUrl, passesCondition, refreshGoogleAccessToken, renderEmail, resendProvider, responseRow, retryAfterSeconds, rowFor, sealSecret, secretKeyBytes, sheetsDestination, signJwt, signWebhook, slackDestination, slackMessage, verifyWebhook, visibleInputs, webhookDestination, webhookPayload };