@marktiderman/genesis-forms 0.2.0 → 0.3.1

package/dist/destinations.d.ts

@@ -0,0 +1,465 @@
+import { J as Json, F as FormDefinition, a as FieldBlock } from './types-BBKBQ8sp.js';
+
+/**
+ * The contract every destination keeps. A destination sends one checked
+ * submission somewhere (an inbox, a spreadsheet, a URL) and says whether a
+ * failure is worth retrying. It never throws, never logs, and never puts a
+ * secret, an answer or contact details in an error message.
+ *
+ * Storage is the app's: it keeps the outbox, claims due deliveries, counts
+ * attempts and schedules retries. A destination only reports what happened.
+ */
+
+/** One cell of a flat response row. */
+type Cell = string | number | boolean;
+/**
+ * What a destination delivers: a submission `validateSubmission` checked,
+ * plus the id the app stored it under. `{ id, ...result.submission }` fits.
+ */
+interface DeliverySubmission {
+    /** The stored response's id. Every destination records it, so a resend is recognised. */
+    id: string;
+    /** Answers keyed by field id. */
+    answers: Record<string, Json>;
+    /** Untrusted URL and host inputs. */
+    hidden?: Record<string, Json> | undefined;
+    /** Trusted server inputs (account id, location…). */
+    context?: Record<string, Json> | undefined;
+    ending?: string | null | undefined;
+    /** When it was submitted, as the app wants it shown: an ISO time, or a day such as `2026-10-22`. */
+    submittedAt?: string | undefined;
+    /**
+     * Extra leading columns the app adds, in order, after `id` and `submitted_at`:
+     * the form's slug and version, an account id, a location. Rows and emails show them;
+     * the webhook sends them.
+     */
+    meta?: Record<string, Cell> | undefined;
+    /** Labels the app attached, such as `low_rating`. The webhook sends them; a custom email can read them. */
+    tags?: readonly string[] | undefined;
+}
+interface DeliveryOptions {
+    /**
+     * This delivery's id, stable across its retries. The email destination's
+     * idempotency key and the webhook's `webhook-id`. Defaults to the submission id.
+     */
+    deliveryId?: string | undefined;
+    /** What this destination cached last time (`DeliveryResult.state`). */
+    state?: Record<string, Json> | undefined;
+    /**
+     * An earlier attempt of this delivery may have gone through (it timed out,
+     * or its lease ran out). Destinations that can look first do: the sheet
+     * skips rows whose id is already there.
+     */
+    redelivery?: boolean | undefined;
+    /** Aborts the delivery. Each request also has its own timeout. */
+    signal?: AbortSignal | undefined;
+}
+/** One submission in a batch: each carries its own definition and delivery id. */
+interface DeliveryItem {
+    submission: DeliverySubmission;
+    definition: FormDefinition;
+    deliveryId?: string | undefined;
+}
+type DeliveryResult = {
+    ok: true;
+    /** New state to keep for this destination, when it changed. */
+    state?: Record<string, Json>;
+    /** Submission ids already there (a redelivery), so nothing was sent for them. */
+    skipped?: string[];
+} | DeliveryFailure;
+interface DeliveryFailure {
+    ok: false;
+    /**
+     * `true`: the same request may succeed later (rate limited, the service
+     * down, a timeout). `false`: it will not until someone changes the config
+     * or credentials (a bad key, an unshared sheet, a 404 URL).
+     */
+    retryable: boolean;
+    /**
+     * Set when the service said when to come back (429, 503) or is plainly
+     * down: retry after this many seconds. An app may choose not to count the
+     * attempt, since it says nothing about the delivery itself.
+     */
+    retryAfterSeconds?: number;
+    /** The HTTP status that refused it, if one did. */
+    status?: number;
+    /** Safe to store and log: a status and a short reason, never secrets, answers or contact details. */
+    error: string;
+}
+/** Config is plain JSON the app stores per destination. Secrets never go in it. */
+type DestinationConfig = Readonly<Record<string, unknown>>;
+interface Destination {
+    /** `"email"`, `"sheet"`, `"webhook"`, or an app's own. */
+    readonly kind: string;
+    /** Deliver one submission. Never throws. */
+    deliver(submission: DeliverySubmission, definition: FormDefinition, config: DestinationConfig, options?: DeliveryOptions): Promise<DeliveryResult>;
+    /**
+     * Deliver several submissions to the same destination in one request where
+     * the service allows it. All succeed or all fail together. Never throws.
+     */
+    deliverBatch?(items: readonly DeliveryItem[], config: DestinationConfig, options?: Omit<DeliveryOptions, "deliveryId">): Promise<DeliveryResult>;
+}
+/**
+ * A failure with a message that is safe to store. Destinations throw it
+ * internally and `deliveryFailure` turns it into a result; app-written
+ * destinations may do the same.
+ */
+declare class DeliveryError extends Error {
+    name: string;
+    readonly retryable: boolean;
+    readonly retryAfterSeconds: number | undefined;
+    readonly status: number | undefined;
+    constructor(message: string, options?: {
+        retryable?: boolean | undefined;
+        retryAfterSeconds?: number | undefined;
+        status?: number | undefined;
+    });
+}
+/** Every outbound request gives up after this long, unless the destination is given another `timeoutMs`. */
+declare const REQUEST_TIMEOUT_MS = 10000;
+/**
+ * Seconds to wait from a Retry-After header, else the fallback. Only the
+ * two forms RFC 9110 defines are read: delta-seconds (digits only) and an
+ * IMF-fixdate (`Wed, 21 Oct 2026 07:28:00 GMT`); anything else (`-5`,
+ * `1.5`, a loose date) gets the fallback. At least 1 second, at most a day.
+ */
+declare function retryAfterSeconds(header: string | null | undefined, fallback?: number, now?: number): number;
+/** Whether an HTTP status is worth retrying unchanged: 408, 425, 429 and 5xx. */
+declare function isRetryableStatus(status: number): boolean;
+/**
+ * The error for a refused request. Retryable statuses (see
+ * `isRetryableStatus`) wait for the Retry-After header, else 60 seconds;
+ * every other status is permanent.
+ */
+declare function httpError(what: string, response: Response, detail?: string): DeliveryError;
+/**
+ * Any error as a failed result with a safe message. A `DeliveryError` keeps
+ * its message; anything else is reduced to its kind ("Timed out", "Network
+ * error"), because a raw message may hold a URL with a token in it.
+ * Timeouts and aborts are retryable. A `TypeError` is permanent: it is
+ * almost always a bug that a retry would only repeat. `timedFetch` turns
+ * fetch's own network `TypeError` into a retryable `DeliveryError` first, so
+ * an app destination that calls `fetch` directly should do the same.
+ */
+declare function deliveryFailure(error: unknown): DeliveryFailure;
+/** Shared by the built-in destinations. */
+interface HttpDeps {
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch | undefined;
+    /** Per request. Default `REQUEST_TIMEOUT_MS`. */
+    timeoutMs?: number | undefined;
+}
+
+interface RowOptions {
+    /**
+     * Fields marked `sensitive`: `"include"` their values (default), `"mask"`
+     * them as `[sensitive]`, or `"omit"` their columns.
+     */
+    sensitive?: "include" | "mask" | "omit" | undefined;
+}
+interface ResponseRow {
+    /** Cells by column key. */
+    row: Record<string, Cell>;
+    /** The column keys in order: `id`, `submitted_at`, the meta keys, then one per field key. */
+    columns: string[];
+    /** Field labels by key, recall filled in from this submission. */
+    labels: Record<string, string>;
+}
+declare const SENSITIVE_MASK = "[sensitive]";
+/**
+ * One answer as a cell: numbers stay numbers (ratings, NPS), choices show
+ * their labels, a list is joined with ", ", yes/no reads "Yes"/"No", and a
+ * plugin type's `summarize` is used where it has one.
+ */
+declare function answerCell(field: FieldBlock, value: Json | undefined): Cell;
+/**
+ * The row for one submission. Columns: `id` (the response id), then
+ * `submitted_at` when given, then the app's `meta` columns in order, then
+ * one per field key in form order (blank when unanswered or hidden by
+ * logic). Content blocks get no column. On an anonymous form, identifying
+ * fields get no column at all, whatever the answers hold.
+ */
+declare function responseRow(submission: DeliverySubmission, definition: FormDefinition, options?: RowOptions): ResponseRow;
+/**
+ * Hidden and server inputs as recall and the webhook may show them: on an
+ * anonymous form identifying ones are left out, and sensitive ones are left
+ * out unless `sensitive` is `"include"`.
+ */
+declare function visibleInputs(submission: DeliverySubmission, definition: FormDefinition, sensitive?: RowOptions["sensitive"]): Record<string, Json>;
+/**
+ * A cell that a spreadsheet will never run as a formula when the text is
+ * opened elsewhere (a CSV export opened in Excel). Opt-in: use it when
+ * writing CSV, not for the sheet destination, whose RAW writes are already
+ * safe and would store the `'` literally. Text starting with `=`,
+ * `@`, a tab or a carriage return gets a leading `'`, as OWASP recommends;
+ * so does text starting with `+` or `-` unless it is only digits and
+ * number punctuation (a phone number such as `+1 (555) 010-0000`, `-2.5`),
+ * which cannot call a function or name a cell. Numbers and booleans are
+ * returned as they are.
+ */
+declare function escapeFormula(cell: Cell): Cell;
+
+/** One message, ready to send. Addresses are already checked. */
+interface EmailMessage {
+    from: string;
+    to: string[];
+    replyTo?: string | undefined;
+    subject: string;
+    text: string;
+    html: string;
+    /** Stable across retries of one delivery: a provider that supports it sends once. */
+    idempotencyKey: string;
+}
+/** Sends one message. Throws a `DeliveryError` (or any error) on failure. */
+interface EmailProvider {
+    readonly name: string;
+    send(message: EmailMessage, options: {
+        signal?: AbortSignal | undefined;
+    }): Promise<void>;
+}
+interface EmailContent {
+    subject: string;
+    text: string;
+    html: string;
+}
+interface EmailRenderInput {
+    submission: DeliverySubmission;
+    definition: FormDefinition;
+    config: DestinationConfig;
+    /** The submission as a row (sensitive values masked unless `sensitive: "include"`). */
+    row: ResponseRow;
+}
+/** What the email destination reads from a destination's config. */
+interface EmailConfig {
+    /** One address or a list (at most 50). */
+    to: string | string[];
+    /** Overrides the default subject (still stripped of line breaks). */
+    subject?: string;
+}
+interface EmailDestinationOptions {
+    provider: EmailProvider;
+    /** `"Feedback <feedback@send.example.com>"` or a bare address. */
+    from: string;
+    /**
+     * The Reply-To address: the key of an email field whose answer is used, or
+     * a function returning an address (or null for none). Only a valid single
+     * address is ever used.
+     */
+    replyTo?: string | ((input: EmailRenderInput) => string | null | undefined) | undefined;
+    /** Builds the subject and bodies. Defaults to `renderEmail`. The subject is sanitized afterwards either way. */
+    render?: ((input: EmailRenderInput) => EmailContent) | undefined;
+    /** Sensitive fields: `"mask"` (default), `"omit"` or `"include"`. */
+    sensitive?: RowOptions["sensitive"];
+}
+/** Resend allows 50 recipients per email. */
+declare const MAX_RECIPIENTS = 50;
+declare function escapeHtml(text: string): string;
+/**
+ * A header value on one line: control characters (CR, LF, NUL…) and Unicode
+ * line separators become spaces, runs of spaces collapse, and it is cut to
+ * `max` characters.
+ */
+declare function headerSafe(text: string, max?: number): string;
+/** A bare address that is safe as a header value: valid, one line, no display name. */
+declare function isSafeAddress(value: unknown): value is string;
+/**
+ * A From value: a bare address, or `Name <address>` where the name has no
+ * quotes, angle brackets or line breaks.
+ */
+declare function isSafeFrom(value: string): boolean;
+/** Plain text and HTML bodies from label/value lines, every value escaped. */
+declare function emailBody(lines: readonly (readonly [string, Cell])[], footer?: string): {
+    text: string;
+    html: string;
+};
+/**
+ * The default notification: subject `"<form title>: new response"` (or
+ * `config.subject`), then the meta columns, each answered field by label,
+ * the ending's title when the form has several, and the response id.
+ */
+declare function renderEmail(input: EmailRenderInput): EmailContent;
+/**
+ * The idempotency key: the delivery id and the first 16 hex digits of
+ * SHA-256 of the sorted recipients, so a retried delivery never sends twice
+ * and one whose recipients changed meanwhile is a new send.
+ */
+declare function idempotencyKey(deliveryId: string, to: readonly string[]): Promise<string>;
+declare function emailDestination(options: EmailDestinationOptions): Destination;
+declare const RESEND_API = "https://api.resend.com/emails";
+interface ResendOptions extends HttpDeps {
+    apiKey: string;
+    /** Default `RESEND_API`. */
+    endpoint?: string | undefined;
+}
+/**
+ * Resend's REST API. Sends the idempotency key, so a retry within Resend's
+ * 24-hour window never sends twice. A 409 for a concurrent request with the
+ * same key is retried; one for a key reused with a different body is not.
+ */
+declare function resendProvider(options: ResendOptions): EmailProvider;
+
+/**
+ * An access token for a Google service account by the OAuth 2.0 JWT bearer
+ * flow: sign a JWT with the account's private key (RS256, WebCrypto) and
+ * trade it at Google's token endpoint. No googleapis dependency, so it runs
+ * on Node 20+, edge runtimes and Workers alike.
+ */
+
+declare const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+declare const SHEETS_SCOPE = "https://www.googleapis.com/auth/spreadsheets";
+interface GoogleServiceAccount {
+    /** The service account's `client_email`. */
+    clientEmail: string;
+    /** Its `private_key`: a PKCS#8 PEM. The `\n`-escaped form env vars often hold is accepted. */
+    privateKey: string;
+}
+/** A signed RS256 JWT. Throws a `DeliveryError` when the key is not a valid PKCS#8 RSA key. */
+declare function signJwt(claims: Record<string, unknown>, privateKeyPem: string): Promise<string>;
+/** Forgets cached tokens (tests, or after rotating a key). */
+declare function clearGoogleTokenCache(): void;
+interface GoogleTokenOptions extends HttpDeps {
+    scope?: string | undefined;
+    now?: (() => number) | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** A cached or fresh access token. Throws a `DeliveryError` with a safe message on failure. */
+declare function googleAccessToken(account: GoogleServiceAccount, options?: GoogleTokenOptions): Promise<string>;
+
+declare const SHEETS_API = "https://sheets.googleapis.com/v4/spreadsheets";
+declare const DEFAULT_SHEET_NAME = "Responses";
+/** How many of the latest rows a redelivery checks for its id. */
+declare const DEDUPE_WINDOW = 500;
+/**
+ * How many rows the header read looks at to find the columns in use: the
+ * header row and the first responses under it. Bounded, so a tab with years
+ * of responses is never read whole just to learn its header.
+ */
+declare const HEADER_SCAN_ROWS = 100;
+/** What the sheet destination reads from a destination's config. */
+interface SheetConfig {
+    spreadsheetId: string;
+    /** Default `"Responses"`. */
+    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>);
+    /**
+     * Prefix text a spreadsheet could run as a formula with `'` (see
+     * `escapeFormula`), headers included. Default false: writes are RAW, so
+     * Sheets never runs text as a formula, and the `'` would be stored as part
+     * of the text. Turn it on only if the sheet is exported as CSV and opened
+     * in another spreadsheet. Keep one setting per sheet: header keys are
+     * escaped too, so switching it later adds new columns for escaped keys.
+     */
+    escapeFormulas?: boolean | undefined;
+    /** Sensitive fields: `"include"` (default), `"mask"` or `"omit"`. */
+    sensitive?: RowOptions["sensitive"];
+    now?: (() => number) | undefined;
+}
+/**
+ * The existing header plus any keys it does not have yet, in the order they
+ * arrive. A blank header cell keeps its place (dropping it would shift every
+ * later column away from the values stored under it), as do blank header
+ * cells over the `width` columns that hold responses; only blanks beyond
+ * those are trimmed.
+ */
+declare function mergeHeader(existing: readonly unknown[], keys: readonly string[], width?: number): string[];
+/** One cell per header column, blank where the row has no value; `escape` applies `escapeFormula` (default false). */
+declare function rowFor(header: readonly string[], row: Record<string, Cell>, escape?: boolean): Cell[];
+/** A1 column letters: 0 → A, 25 → Z, 26 → AA. */
+declare function columnLetter(index: number): string;
+/** What the destination keeps between deliveries. Opaque to the app: store and pass it back. */
+interface SheetState {
+    spreadsheet_id: string;
+    sheet_name: string;
+    sheet_id: number;
+    header: string[];
+    columns: number;
+    /** The last row an append wrote (1-based), 0 when unknown. */
+    last_row: number;
+}
+declare function sheetsDestination(options: SheetsDestinationOptions): Destination;
+
+/** 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.
+     */
+    secret: string | ((config: DestinationConfig) => string | Promise<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"`. */
+    type?: string | undefined;
+    now?: (() => number) | undefined;
+}
+/** The JSON body a webhook receives. */
+interface WebhookPayload {
+    type: string;
+    /** ISO time the delivery was sent. */
+    timestamp: string;
+    data: {
+        form: {
+            id: string;
+            title: string;
+        };
+        submission: {
+            id: string;
+            /** Answers keyed by field id. */
+            answers: Record<string, Json>;
+            hidden: Record<string, Json>;
+            context: Record<string, Json>;
+            ending: string | null;
+            submittedAt: string | null;
+            meta: Record<string, Json>;
+            tags: string[];
+        };
+        /** The same submission as a flat row by column key: labels for choices, as the sheet shows it. */
+        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>;
+interface VerifyWebhookInput {
+    /** The same secret the sender signs with (base64, optionally `whsec_`-prefixed). */
+    secret: string;
+    /** The request's headers: a `Headers` or a plain object. */
+    headers: Headers | Record<string, string | string[] | undefined>;
+    /** The raw body, exactly as received. */
+    body: string;
+    /** Default 300: a timestamp further off than this is refused. */
+    toleranceSeconds?: number | undefined;
+    now?: (() => number) | undefined;
+}
+/**
+ * Checks a Standard Webhooks request: the timestamp is recent and one of the
+ * space-separated `v1` signatures matches. Compares in constant time (by
+ * WebCrypto `verify`). Never throws on a malformed request: returns false.
+ */
+declare function verifyWebhook(input: VerifyWebhookInput): Promise<boolean>;
+/** Whether a URL hostname is localhost or a private, loopback, link-local or unspecified address literal. */
+declare function isPrivateHost(hostname: string): boolean;
+/** The URL from config, checked. Throws a `DeliveryError` naming the rule it broke (never the URL, which may hold a token). */
+declare function checkWebhookUrl(raw: string, options?: Pick<WebhookDestinationOptions, "allowInsecureUrls" | "allowPrivateHosts">): URL;
+/** The payload for one submission. Identifying answers stay out on anonymous forms. */
+declare function webhookPayload(submission: DeliverySubmission, definition: FormDefinition, options?: {
+    sensitive?: RowOptions["sensitive"];
+    type?: string | undefined;
+    now?: number | undefined;
+}): 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 };