@marktiderman/genesis-forms 0.8.0 → 0.9.0

package/dist/submit-protocol-CFi-0Qd0.d.ts

@@ -0,0 +1,840 @@
+import { H as HostOptions, A as AnswerSnapshot, F as FieldValidator } from './validate-DpmBssFk.js';
+import { a as FieldBlock, J as Json, F as FormDefinition, e as FormEvent } from './types-C0pUfew3.js';
+
+/**
+ * The `photo` field type: a respondent attaches up to a few photos, such as a
+ * picture of broken equipment. The answer holds references the host's storage
+ * handed back (`PhotoRef`), never the bytes: the renderer uploads through the
+ * host (`onUpload` on genesis-forms-web's `Form`), so the engine and the
+ * server stay storage-agnostic. A host's server should check that each
+ * reference is a file it stored for this respondent before saving.
+ *
+ * Opt-in in a builder palette (`UPLOAD_FIELD_TYPES`), since a host must be
+ * able to store the files.
+ */
+declare const PHOTO_TYPE = "photo";
+/** Field types that need the host to store files; a builder offers them only when the host names them. */
+declare const UPLOAD_FIELD_TYPES: readonly ["photo"];
+/** One stored photo, as the host's upload returned it. */
+type PhotoRef = {
+    /** The host's id for the stored file. */
+    id: string;
+    /** The file's name on the respondent's device. */
+    name: string;
+    /** Its MIME type, such as `image/jpeg`. */
+    type: string;
+    /** Bytes. */
+    size: number;
+};
+type PhotoFormat = "jpeg" | "png" | "heic" | "webp";
+/** The MIME types each format covers. */
+declare const PHOTO_FORMATS: Record<PhotoFormat, readonly string[]>;
+declare const DEFAULT_PHOTO_FILES = 3;
+declare const MAX_PHOTO_FILES = 5;
+declare const DEFAULT_PHOTO_SIZE_MB = 10;
+declare const MAX_PHOTO_SIZE_MB = 25;
+/** The longest reference id and file name a photo answer may carry. */
+declare const MAX_PHOTO_ID_LENGTH = 200;
+declare const MAX_PHOTO_NAME_LENGTH = 255;
+declare const isPhotoFormat: (v: unknown) => v is PhotoFormat;
+interface PhotoLimits {
+    maxFiles: number;
+    maxSizeMb: number;
+    maxBytes: number;
+    formats: PhotoFormat[];
+    /** Every MIME type the formats cover. */
+    mimeTypes: string[];
+}
+/** A photo field's limits; a prop that is missing or out of range uses its default. */
+declare function photoLimits(field: FieldBlock): PhotoLimits;
+/** Whether `v` has a photo reference's shape (any type and size). */
+declare function isPhotoRef(v: unknown): v is PhotoRef;
+/** The well-formed references in a photo answer, as `{ id, name, type, size }` only. */
+declare function photoRefs(value: Json | undefined): PhotoRef[];
+/** "JPEG, PNG or WebP". */
+declare function photoFormatList(formats: readonly PhotoFormat[]): string;
+/** The message for a file of a type the field doesn't take. */
+declare const photoTypeMessage: (field: FieldBlock) => string;
+/** The message for a file over the field's size limit. */
+declare const photoSizeMessage: (field: FieldBlock) => string;
+/** The message for more photos than the field takes. */
+declare const photoCountMessage: (field: FieldBlock) => string;
+
+/**
+ * The upload handshake's JSON, shared by the server (`createUploadHandler` in
+ * `/server`) and the browser (genesis-forms-web's `signedUploadHost`). A
+ * respondent's browser asks the app's server for one signed upload per file,
+ * then sends the bytes straight to storage with it; the answer keeps only the
+ * reference the server handed back.
+ *
+ * Moved up from the host app's feedback photo uploads; the field names and
+ * status codes are the ones it used, so its browsers and server keep talking.
+ */
+
+/**
+ * What the browser POSTs (`content-type: application/json`, at most
+ * `MAX_UPLOAD_REQUEST_BYTES`). Exactly one of `attemptId` (a new response: the
+ * visit's attempt id, a UUID) and `edit` (an edit link's token, while changing
+ * a sent response).
+ */
+interface UploadRequest {
+    /** The upload field's id. */
+    fieldId: string;
+    /** The file's name on the respondent's device. */
+    name: string;
+    /** Its MIME type. */
+    type: string;
+    /** Bytes. */
+    size: number;
+    attemptId?: string | undefined;
+    edit?: string | undefined;
+}
+/**
+ * Where the browser sends the bytes, as the app's storage signed it. Supabase
+ * Storage hands back `path` and `token` (with `bucket`, for
+ * `uploadToSignedUrl`); a store that signs a plain URL sets `url`, which
+ * `signedUploadHost` PUTs the file to when no `send` is given.
+ */
+interface SignedUpload {
+    path: string;
+    token: string;
+    bucket?: string | undefined;
+    url?: string | undefined;
+}
+/** 200: the reference the answer keeps, and where to send the bytes. */
+interface UploadGrant {
+    ref: PhotoRef;
+    upload: SignedUpload;
+}
+/**
+ * Any other status: words to show the respondent, and for some a `code`:
+ * `closed` (409, an edit while the form takes no changes), `bad_link` (403, an
+ * edit link that doesn't check out) or `too_many_photos` (429, the attempt or
+ * edit has as many uploads as the store allows; the name the host app's
+ * browsers already know, kept for every upload field type).
+ */
+interface UploadRefusal {
+    error: string;
+    code?: string | undefined;
+}
+/** The longest upload request body: a few fields of JSON. */
+declare const MAX_UPLOAD_REQUEST_BYTES = 4000;
+
+interface MergeOptions {
+    /** Hidden inputs by name, when logic reads them (the same ones the form runs with). */
+    hidden?: Record<string, Json | undefined> | undefined;
+    /** The app's option lists, for choice fields with `optionsFrom` (see `withHostOptions`). */
+    hostOptions?: HostOptions | undefined;
+    /**
+     * Answers to questions the merged answers no longer reach (hidden by logic, jumped over):
+     * `"drop"` them, or `"keep"` them. Default: the form's own rule, `"keep"` only with
+     * `settings.clearHiddenValues: false`, as `validateSubmission` does.
+     */
+    offPath?: "drop" | "keep" | undefined;
+}
+/**
+ * `base` with `patch` on top, by field id, as the answers to store. The rules, in order:
+ *
+ * 1. A field in `patch` takes the patch's value; `null` (or `undefined`) clears it.
+ * 2. Only the definition's fields are kept: unknown ids, `calculated` fields (worked out
+ *    again from the answers) and, on an anonymous form, identifying fields are dropped.
+ * 3. Empty answers (`""`, blank text, `[]`) are dropped.
+ * 4. A pick a filtered list no longer shows (`props.optionsFrom.filter`, after the answer it
+ *    depends on changed) is dropped, as the engine drops it.
+ * 5. Branching: the path is worked out from the merged answers. Answers on the path are kept;
+ *    answers off it are dropped, unless `offPath` is `"keep"` (default: kept only when the form
+ *    has `settings.clearHiddenValues: false`).
+ *
+ * Values are kept as given, in the definition's order: nothing is checked or normalized here, so
+ * pass the result to `validateSubmission` (or `createForm`'s `initialValues`) as usual.
+ */
+declare function mergeResponses(definition: FormDefinition, base: Readonly<Record<string, Json | undefined>>, patch: Readonly<Record<string, Json | undefined>>, options?: MergeOptions): Record<string, Json>;
+
+/**
+ * Edit links for a sent response: `<id>.<nonce>.<expires>.<sig>`, where sig is the
+ * base64url HMAC-SHA256 of `edit-link:v2:<id>.<nonce>.<expires>` under a server-only
+ * secret of at least 32 bytes.
+ *
+ * - id: the response's uuid.
+ * - nonce: the response's current edit nonce, kept by the app. The app refuses a link
+ *   whose nonce is no longer the response's, so changing the nonce revokes every link
+ *   made before (change it after each edit: only the newest link works).
+ * - expires: when the link stops working, in Unix seconds, about 30 days after it was
+ *   made (`EDIT_LINK_TTL_SECONDS`).
+ *
+ * Without a usable secret (missing, or shorter than `MIN_EDIT_SECRET_BYTES`) there are no
+ * edit links: signing returns null and every token fails to verify.
+ *
+ * Web Crypto only, no storage: the app keeps the nonce and checks it. Moved up from
+ * The host app's src/lib/forms/edit-link.ts unchanged, so links it signed still verify.
+ */
+/** How long a new edit link works: 30 days. */
+declare const EDIT_LINK_TTL_SECONDS: number;
+/** The shortest secret edit links are signed with: 32 bytes (UTF-8), as long as the HMAC. */
+declare const MIN_EDIT_SECRET_BYTES = 32;
+/** The query parameter an edit link's token travels in: `?edit=<token>`. */
+declare const EDIT_LINK_PARAM = "edit";
+/** Whether `secret` can sign edit links: a string of at least `MIN_EDIT_SECRET_BYTES` bytes. */
+declare function isUsableEditSecret(secret: string | null | undefined): secret is string;
+/** What an edit link says: the response, its nonce when the link was made, and when it stops working. */
+interface EditLinkClaims {
+    /** The response's id, in lower case. */
+    id: string;
+    nonce: string;
+    /** Unix seconds. */
+    expiresAt: number;
+}
+interface EditLinkOptions {
+    /** The current time in milliseconds (tests); `Date.now()` by default. */
+    now?: number | undefined;
+    /** How long the link works, in seconds; `EDIT_LINK_TTL_SECONDS` by default. */
+    ttlSeconds?: number | undefined;
+}
+/**
+ * The edit token for a response and its current nonce, working for `ttlSeconds` from
+ * now; null when there is no usable secret (no edit links) or the id or nonce is malformed.
+ */
+declare function signEditToken(link: {
+    id: string;
+    nonce: string;
+}, secret: string | null | undefined, options?: EditLinkOptions): Promise<string | null>;
+/**
+ * What a token says, or null when it is malformed, its signature does not match, it has
+ * expired (or claims to last longer than `ttlSeconds` from now), or there is no usable
+ * secret. Whether the nonce is still the response's is the caller's check. The
+ * comparison is Web Crypto's HMAC verify, which runs in constant time.
+ */
+declare function verifyEditToken(token: string | null | undefined, secret: string | null | undefined, options?: EditLinkOptions): Promise<EditLinkClaims | null>;
+/**
+ * A form link with the edit token added: `<formUrl>?edit=<token>` (or `&edit=` when it
+ * has a query). `param` names the parameter; `EDIT_LINK_PARAM` by default.
+ */
+declare function withEditToken(formUrl: string, token: string, param?: string): string;
+interface EditLinkUrlOptions extends EditLinkOptions {
+    /** The query parameter; `EDIT_LINK_PARAM` by default. */
+    param?: string | undefined;
+}
+/**
+ * The link that reopens a response for editing: `formUrl` (the page that shows the form,
+ * with any query it needs) plus a token signed for the response's current nonce. Null
+ * when there are no edit links (no usable secret) or the id or nonce is malformed.
+ */
+declare function editLinkUrl(formUrl: string, link: {
+    id: string;
+    nonce: string;
+}, secret: string | null | undefined, options?: EditLinkUrlOptions): Promise<string | null>;
+/** Where the edit-secret reader reports a missing or short secret. */
+type EditSecretLog = (message: string) => void;
+/** Reads the edit-link secret from an environment, warning once when there is none. */
+interface EditSecretReader {
+    /** The secret, or null (no edit links) when it is missing or too short; warns once, never with the secret. */
+    (env: Record<string, string | undefined>, log?: EditSecretLog): string | null;
+    /** Tests only: warn again. */
+    reset(): void;
+}
+/**
+ * A reader for the environment variable that holds the edit-link secret (such as
+ * `FEEDBACK_EDIT_SECRET`). Without one of at least `MIN_EDIT_SECRET_BYTES` bytes there are
+ * no edit links, and the first read says so through `log` (the call's, else the
+ * reader's, else `console.warn`); later reads stay quiet until `reset()`.
+ */
+declare function createEditSecretReader(options: {
+    variable: string;
+    log?: EditSecretLog | undefined;
+}): EditSecretReader;
+interface EditLinkRequestOptions {
+    /** The query parameter; `EDIT_LINK_PARAM` by default. */
+    param?: string | undefined;
+    /**
+     * Whether the URL is a page that shows a form (an edit link is only honoured there,
+     * such as `/f/<slug>`). Every URL by default.
+     */
+    isFormPage?: ((url: URL) => boolean) | undefined;
+}
+/** Whether this request is a form page opened with an edit link (the parameter present, even empty). */
+declare function isEditLinkRequest(url: URL, options?: EditLinkRequestOptions): boolean;
+/**
+ * The response, with `Referrer-Policy: no-referrer` and `Cache-Control: private, no-store`
+ * added when the request carried an edit link; otherwise the same response, untouched.
+ * The link is a credential, so it never leaves in a Referer header (an HTTP header, not
+ * only the page's meta tag, so it holds before the page has parsed and for every request
+ * the page makes), and the page, prefilled with the response, is never cached.
+ */
+declare function withEditLinkHeaders(request: Request, response: Response, options?: EditLinkRequestOptions): Response;
+
+/**
+ * The pieces of a submit endpoint's rate limit that aren't storage: the client's
+ * address, the part of it that names one client, a key that never holds the address,
+ * and a check that fails open. The counter itself is the app's (`RateLimitStore`), so
+ * every server instance can share it (a row in Postgres, a key in Redis).
+ *
+ * Web Crypto only. Moved up from the host app's src/lib/feedback/rate-limit.server.ts;
+ * keys made here equal the ones it made, so a deploy doesn't reset anyone's count.
+ */
+/**
+ * The headers a platform reports the client's address in, most trusted first: Vercel's
+ * `x-vercel-forwarded-for` and Cloudflare's `cf-connecting-ip`, which the platform sets
+ * itself. `x-forwarded-for` is not read by default: its leftmost entries are whatever the
+ * client sent (MDN), so only the hop your own proxy appended can be trusted; opt in with
+ * `forwardedForHops`. A header is only trustworthy behind the platform that sets it: on any
+ * other host a client can send it, so pass the list your host actually has.
+ */
+declare const DEFAULT_TRUSTED_IP_HEADERS: readonly string[];
+/** Where `clientIp` looks for the address. */
+interface ClientIpOptions {
+    /** Headers your platform sets (and overwrites), most trusted first. Default `DEFAULT_TRUSTED_IP_HEADERS`. */
+    headers?: readonly string[] | undefined;
+    /**
+     * Read `x-forwarded-for` too, after `headers`: the number of proxies you run in front of
+     * the app that each append the address they saw. The entry that many places from the
+     * right is the client (1: the rightmost). Entries left of it are the client's own and
+     * never read. Unset (the default), `x-forwarded-for` is ignored. Behind only your own
+     * proxies, pass `headers: []` as well, so a client can't send a platform header.
+     */
+    forwardedForHops?: number | undefined;
+}
+/**
+ * How many submits, saves as they go and photo uploads one client may make per scope
+ * (a practice, an account) in a window.
+ *
+ * - submit: 60 responses per 10 minutes: a class at one gym's Wi-Fi fits.
+ * - progress: saving answers as they go. A visit counts once, against `submit`, at its
+ *   first save; its later saves (each Next, the send, a reload picking up where it was)
+ *   count here, in the same window: 60 people answering 10 questions each on one Wi-Fi fit.
+ * - upload: 120 photos per 10 minutes: that class, a couple of photos each.
+ */
+declare const RATE_LIMIT_DEFAULTS: {
+    readonly submit: {
+        readonly limit: 60;
+        readonly windowSeconds: 600;
+    };
+    readonly progress: {
+        readonly limit: 900;
+        readonly windowSeconds: 600;
+    };
+    readonly upload: {
+        readonly limit: 120;
+        readonly windowSeconds: 600;
+    };
+};
+/**
+ * The client's address as the platform reports it, used only as a rate-limit key: the
+ * first entry of the first trusted header that is set (`DEFAULT_TRUSTED_IP_HEADERS` by
+ * default), then, only when `forwardedForHops` is set, the `x-forwarded-for` entry that
+ * many places from the right; else `"unknown"`. The second argument may also be the
+ * header list alone.
+ */
+declare function clientIp(headers: Pick<Headers, "get">, options?: readonly string[] | ClientIpOptions): string;
+/** The part of an address that names one client: an IPv4 address whole, an IPv6 address by its /64. */
+declare function addressPrefix(ip: string): string;
+/**
+ * The stored key, `<kind>:<scope>:<hex HMAC-SHA256 of the address prefix>`: what is
+ * counted (such as `submit`, `progress`, `upload`), whose count it is (a practice id),
+ * and the client, which is never stored as its address. `secret` is a server secret.
+ */
+declare function rateLimitKey(input: {
+    kind: string;
+    scope: string;
+    ip: string;
+    secret: string;
+}): Promise<string>;
+/** The app's shared counter. */
+interface RateLimitStore {
+    /**
+     * Count one hit on `key` in its current `windowSeconds` window: true while the count is
+     * within `limit`, false past it, null when it could not count.
+     */
+    hit(key: string, limit: number, windowSeconds: number): Promise<boolean | null>;
+}
+/**
+ * True when the request may go on. Fails open: when the store can't count (it answers
+ * null or throws) the request goes on and `log` says so with `message`.
+ */
+declare function allow(store: RateLimitStore, check: {
+    key: string;
+    limit: number;
+    windowSeconds: number;
+}, options?: {
+    log?: ((message: string) => void) | undefined;
+    message?: string | undefined;
+}): Promise<boolean>;
+
+/** What the store records when an upload begins. */
+interface BeginUploadInput {
+    formId: string;
+    fieldId: string;
+    name: string;
+    contentType: string;
+    size: number;
+    /** A new response's attempt (`attemptHash` of its attempt id), or… */
+    attemptHash: string | null;
+    /** …the id of the sent response an edit link is changing. Exactly one of the two. */
+    editOf: string | null;
+}
+/** One upload as the store reads it back, with what storage holds for it. */
+interface StoredUpload {
+    id: string;
+    fieldId: string;
+    attemptHash: string | null;
+    editOf: string | null;
+    /** The response that took it, once one did. */
+    responseId: string | null;
+    name: string;
+    contentType: string;
+    size: number;
+    /** Whether the file is in storage (the respondent's browser finished sending it). */
+    stored: boolean;
+    /** The type and size storage holds, which are trusted over what the browser said. */
+    storedType: string | null;
+    storedSize: number | null;
+}
+/** What uploads need from the app's database and storage; the app's service-role client, say. */
+interface UploadStore {
+    /**
+     * Records one upload and names its object in storage; `{ tooMany: true }` once the
+     * attempt or edit has as many as the app allows (the host app: 20).
+     */
+    beginUpload(input: BeginUploadInput): Promise<{
+        id: string;
+        objectName: string;
+    } | {
+        tooMany: true;
+    }>;
+    /** Signs an upload of that object, sent to the browser as `upload` (`SignedUpload`). */
+    signUpload(objectName: string): Promise<SignedUpload>;
+    /** This form's uploads with these ids; others are left out. */
+    uploadRefs(formId: string, ids: string[]): Promise<StoredUpload[]>;
+}
+/** Who may use an upload: a new response's attempt, or an edit of a sent response. */
+type UploadOwner = {
+    attemptHash: string;
+} | {
+    responseId: string;
+};
+/** The form's upload fields (`UPLOAD_FIELD_TYPES`: photo). */
+declare function uploadFields(definition: FormDefinition): FieldBlock[];
+/** An upload field type's limits and its words for a file it doesn't take. */
+interface UploadRules {
+    maxFiles: number;
+    maxBytes: number;
+    mimeTypes: readonly string[];
+    typeMessage: string;
+    sizeMessage: string;
+    countMessage: string;
+}
+/** The rules for an upload field, or null when the field doesn't take files. */
+declare function uploadRules(field: FieldBlock): UploadRules | null;
+/** Said when a reference isn't a file this respondent finished uploading here. */
+declare const NOT_UPLOADED_MESSAGE = "A photo didn't finish uploading. Remove it and add it again.";
+interface CheckUploadsOptions {
+    /** The form's id, as the store keys its uploads. */
+    formId: string;
+    owner: UploadOwner;
+    /** Needed only when the answers name a file. */
+    store?: Pick<UploadStore, "uploadRefs"> | undefined;
+}
+type CheckedUploads = {
+    ok: true;
+    answers: Record<string, Json>;
+} | {
+    ok: false;
+    errors: Record<string, string>;
+};
+/**
+ * Checks every file the answers name: uploaded by this attempt (or for this edit) to this
+ * form's field, in storage, of a type and size the field takes, and no more files than it
+ * takes. The stored name, type and size replace what the browser sent. Answers without
+ * files are returned as they are, without asking the store. Errors are keyed by field id;
+ * a store that throws throws (answer 503: nothing can be checked).
+ */
+declare function checkUploads(definition: FormDefinition, answers: Record<string, Json>, options: CheckUploadsOptions): Promise<CheckedUploads>;
+/**
+ * The stored hash of a visit's attempt id: hex SHA-256 (Web Crypto). It equals
+ * The host app's `resumeTokenHash`, so uploads recorded before the move still match.
+ */
+declare function attemptHash(attemptId: string): Promise<string>;
+
+/** The form an upload is for, as the app found it from the request. */
+interface UploadForm {
+    /** The form's id, as the store keys uploads. */
+    id: string;
+    /** The published definition respondents answer. */
+    definition: FormDefinition;
+    /** Whether it takes responses now (not paused, closed, full…). */
+    open: boolean;
+    /** Whose rate-limit count this is: a practice, an account. */
+    scope: string;
+    /** Whether its edit links work. Default false: no uploads for an edit. */
+    allowsEdits?: boolean | undefined;
+    /** Names the form in logs, such as its slug. */
+    label?: string | undefined;
+}
+/** A sent response an edit link may change, as the app loads it. */
+interface EditableResponse {
+    id: string;
+    /** The response's current nonce: only a link made with it works. */
+    editNonce: string;
+}
+/** The handler's words; each default is what the host app said. */
+interface UploadMessages {
+    /** 415 / 400: not a JSON object. */
+    notJson: string;
+    /** 413: past `maxRequestBytes`. */
+    tooLong: string;
+    /** 400: no attempt id, or not a UUID. */
+    reload: string;
+    /** 404: `resolveForm` found no form. */
+    unavailable: string;
+    /** 409: the form isn't open. */
+    notOpen: string;
+    /** 409 (`code: "closed"`): an edit while the form isn't open. */
+    notTakingChanges: string;
+    /** 403 (`code: "bad_link"`): an edit link that doesn't check out, or a form without edits. */
+    badEditLink: string;
+    /** 400: the field isn't an upload field of this form. */
+    notUploadField: string;
+    /** 429: the rate limit. */
+    rateLimited: string;
+    /** 429 (`code: "too_many_photos"`): the store has as many uploads for this attempt or edit as it allows. */
+    tooMany: string;
+    /** 503 / 500: something failed on the server; nothing more is said. */
+    failed: string;
+}
+declare const UPLOAD_MESSAGES: UploadMessages;
+type Secret = string | null | undefined;
+interface UploadHandlerOptions<P = void> {
+    /**
+     * The form the request is for (from its host, path or `params`), or null (404). A throw
+     * answers 503 and logs the error's message.
+     */
+    resolveForm(request: Request, params: P): Promise<UploadForm | null>;
+    store: UploadStore;
+    /**
+     * Uploads for an edit link (`edit` in the request). Without it, or without a usable
+     * secret, every edit link is refused (403).
+     */
+    edit?: {
+        /** The edit-link secret, or a reader of it (`createEditSecretReader`). */
+        secret: Secret | (() => Secret);
+        /**
+         * The sent response with this id, of this form (and its scope), or null (403).
+         * A throw answers 503.
+         */
+        response(id: string, form: UploadForm): Promise<EditableResponse | null>;
+    } | undefined;
+    /** Counted per scope and client address, as `kind: "upload"`. Without it, nothing is counted. */
+    rateLimit?: {
+        store: RateLimitStore;
+        /** The server secret the address is hashed with (`rateLimitKey`). */
+        secret: string;
+        /** Default `RATE_LIMIT_DEFAULTS.upload`: 120 per 600 seconds. */
+        limit?: number | undefined;
+        windowSeconds?: number | undefined;
+        /** Default `DEFAULT_TRUSTED_IP_HEADERS`. */
+        trustedIpHeaders?: readonly string[] | undefined;
+        /** Read `x-forwarded-for` at this many proxies from the right (`ClientIpOptions.forwardedForHops`). Default unset: never read. */
+        forwardedForHops?: number | undefined;
+    } | undefined;
+    /** The stored hash of an attempt id. Default `attemptHash` (hex SHA-256). */
+    hashAttempt?: ((attemptId: string) => string | Promise<string>) | undefined;
+    /** Default `MAX_UPLOAD_REQUEST_BYTES` (4,000). */
+    maxRequestBytes?: number | undefined;
+    /** The current time (tests): edit links expire. */
+    now?: (() => Date) | undefined;
+    /** Where failures are said; `console.error` with an `[upload]` prefix by default. Never sent to the browser. */
+    log?: ((message: string) => void) | undefined;
+    messages?: Partial<UploadMessages> | undefined;
+}
+/**
+ * The upload endpoint: `(request, params) => Response`, for a POST route. `params` is
+ * whatever the route has (a form slug, say), passed to `resolveForm`. See the README's
+ * "Uploads" for the JSON and every status.
+ */
+declare function createUploadHandler<P = void>(options: UploadHandlerOptions<P>): (request: Request, params: P) => Promise<Response>;
+
+/** What the store keeps for one response: everything `submitResponse` checked, as JSON. */
+interface SubmissionRecord {
+    /** `options.formId`, else the definition's id. */
+    formId: string;
+    /** The device's key. The store keeps one response per `formId` and key (a unique index). */
+    idempotencyKey: string;
+    /**
+     * Hex SHA-256 of the answers, events and hidden inputs as sent. A retry sends the same
+     * body, so the same hash; the store hands it back with a duplicate so a key reused for
+     * other answers is refused instead of being taken as delivered.
+     */
+    inputHash: string;
+    /** `options.version`, else `fingerprint` of the published definition. */
+    definitionVersion: string;
+    /** The server's time, ISO 8601. */
+    receivedAt: string;
+    /** The device's time of submitting, ISO 8601, or null. Untrusted. */
+    clientSubmittedAt: string | null;
+    /** Checked answers by field id: visible ones only, uploads as stored, calculated fields worked out here. */
+    answers: Record<string, Json>;
+    /** Untrusted URL and host inputs, coerced to their types. */
+    hidden: Record<string, Json>;
+    /** Trusted server inputs (`options.context`). */
+    context: Record<string, Json>;
+    ending: string | null;
+    /** Client-sent keys that were dropped (see `CheckedSubmission.ignored`). */
+    ignored: string[];
+    /** Each answer to a question with options from the app, as `{ value, label }` now (`answerSnapshots`). */
+    snapshots: Record<string, AnswerSnapshot>;
+    /** The ids of the uploads the answers name, checked: mark them taken by this response in the same transaction. */
+    uploadIds: string[];
+}
+/** A response the store already holds under an idempotency key. */
+interface StoredSubmissionRef {
+    id: string;
+    /** ISO 8601, as it was saved. */
+    receivedAt: string;
+    /** `SubmissionRecord.inputHash` as it was saved. */
+    inputHash: string;
+}
+/** Where responses go: the app's database (a service-role client, say). */
+interface SubmissionStore {
+    /**
+     * Store one response. Exactly one response per `formId` and `idempotencyKey`: when one is
+     * already there (a unique index refused the insert), answer `{ duplicate }` with it rather
+     * than storing again. Throw when it can't store (answered `store_failed`, and the device
+     * retries). Save the response and queue its deliveries in one transaction, so a stored
+     * response is always delivered.
+     */
+    save(record: SubmissionRecord): Promise<{
+        id: string;
+    } | {
+        duplicate: StoredSubmissionRef;
+    }>;
+    /**
+     * The response stored under this key, or null. Asked first, so a retry of a response that
+     * went through is answered `duplicate` even after the form has closed, the client is rate
+     * limited, the definition changed or its uploads were taken. `save` must still refuse a
+     * duplicate on its own (two retries can race).
+     */
+    find(formId: string, idempotencyKey: string): Promise<StoredSubmissionRef | null>;
+}
+interface SubmitResponseOptions extends Omit<SubmissionOptions, "complete" | "hostOptions"> {
+    /** The published definition respondents answer, loaded by the server. */
+    definition: FormDefinition;
+    store: SubmissionStore;
+    /**
+     * The option lists for `optionsFrom: { source: "host" }` questions, loaded here afresh
+     * (never taken from the client): an answer must be one of them.
+     */
+    hostOptions?: SubmissionOptions["hostOptions"];
+    /** The id the store keys this form's responses (and uploads) by. Default `definition.id`. */
+    formId?: string | undefined;
+    /** The published version's label, stored as `definitionVersion`. Default `fingerprint(definition)`. */
+    version?: string | undefined;
+    /** Whether the form takes responses now (not paused, closed, full). Default true; false answers `closed`. */
+    open?: boolean | undefined;
+    /**
+     * The rate limit: true lets the submission on; false, or `{ retryAfterSeconds }`, answers
+     * `rate_limited`. Typically
+     * `() => allow(store, { key: await rateLimitKey(...), ...RATE_LIMIT_DEFAULTS.submit })`.
+     * A throw lets it on (fails open, as `allow` does) and is logged.
+     */
+    rateLimit?: (() => RateLimitAnswer | Promise<RateLimitAnswer>) | undefined;
+    /**
+     * Needed when the form has upload fields: where uploads are recorded, and who may use the
+     * ones named. `owner` defaults to the request's attempt (`attemptHash(input.attemptId)`);
+     * without either, answers that name files are refused. Without `uploads` such a form
+     * throws, on every submit.
+     */
+    uploads?: {
+        store: Pick<UploadStore, "uploadRefs">;
+        owner?: UploadOwner | undefined;
+    } | undefined;
+    /** The current time (tests). */
+    now?: (() => Date) | undefined;
+    /** Where failures are said; `console.error` with a `[submit]` prefix by default. Never holds an answer. */
+    log?: ((message: string) => void) | undefined;
+}
+/** What `rateLimit` answers: true to let the submission on. */
+type RateLimitAnswer = boolean | {
+    retryAfterSeconds: number;
+};
+declare function submitResponse(input: SubmitRequest, options: SubmitResponseOptions): Promise<SubmitResult>;
+
+interface SubmissionInput {
+    /** Answers keyed by field id. Ignored when `events` is given. */
+    answers?: Record<string, Json> | undefined;
+    /** The respondent's event log. Replayed instead of trusting `answers`. */
+    events?: FormEvent[] | undefined;
+    /** URL and host inputs sent by the client. Server inputs here are ignored. */
+    hidden?: Record<string, Json> | undefined;
+}
+interface SubmissionOptions {
+    /** Values for `source: "server"` inputs, resolved by the server (account id, location, user id…). */
+    context?: Record<string, Json> | undefined;
+    /** `false` checks a draft: formats only, nothing required. Default true. */
+    complete?: boolean | undefined;
+    validators?: Record<string, FieldValidator> | undefined;
+    /**
+     * Most events accepted, counted after `compactEvents`. Default `MAX_EVENTS`
+     * (10,000). At most `RAW_EVENTS_PER_EVENT` (10) times as many may be sent.
+     */
+    maxEvents?: number | undefined;
+    /**
+     * Most JSON values in the answers, answer events and hidden inputs
+     * together (each number, text, true / false, list item, row and cell
+     * counts one; a run of answers to one field, as typing in a table sends,
+     * counts its last only). Default `MAX_SUBMISSION_VALUES` (200,000).
+     */
+    maxValues?: number | undefined;
+    /**
+     * Most work replaying the events may take: one unit per block each time
+     * the path is walked, one per calculated field each time the answers
+     * settle, and a formula's size (its numbers, answers and operators) each
+     * time it is worked out. Default `MAX_REPLAY_WORK` (1,000,000). Only the
+     * replay counts: the submit that follows it does not.
+     */
+    maxReplayWork?: number | undefined;
+    /**
+     * The option lists the app supplies for `optionsFrom: { source: "host" }`
+     * choice fields, loaded here on the server (never taken from the client):
+     * an answer must be one of the field's own options or of these. Pass what
+     * the form was shown with, loaded afresh, such as the current staff.
+     */
+    hostOptions?: HostOptions | undefined;
+}
+interface CheckedSubmission {
+    status: "draft" | "completed";
+    /**
+     * Visible answers only, keyed by field id (kept hidden answers too, with
+     * `clearHiddenValues: false`). Calculated fields hold the value worked out
+     * here from these answers.
+     */
+    answers: Record<string, Json>;
+    /** Untrusted URL and host inputs, coerced to their declared types. Identifying ones are left out on anonymous forms. */
+    hidden: Record<string, Json>;
+    /** Trusted server inputs. Identifying ones are left out on anonymous forms. */
+    context: Record<string, Json>;
+    ending: string | null;
+    /** Client-sent keys that were dropped, each once: unknown fields, server inputs, undeclared or withheld hidden names. */
+    ignored: string[];
+}
+type SubmissionResult = {
+    ok: true;
+    submission: CheckedSubmission;
+} | {
+    ok: false;
+    errors: Record<string, string>;
+};
+/** Default for `SubmissionOptions.maxEvents`. */
+declare const MAX_EVENTS = 10000;
+/** Default for `SubmissionOptions.maxValues`. */
+declare const MAX_SUBMISSION_VALUES = 200000;
+/** Default for `SubmissionOptions.maxReplayWork`. */
+declare const MAX_REPLAY_WORK = 1000000;
+/**
+ * Most events sent, before compaction, as a multiple of `maxEvents`: a
+ * keystroke log compacts to far fewer, but every event sent is looked at.
+ */
+declare const RAW_EVENTS_PER_EVENT = 10;
+/**
+ * Check a submission against the published definition. Never throws on a
+ * malformed submission: it returns `{ ok: false, errors: { "": … } }`.
+ */
+declare function validateSubmission(published: FormDefinition, submission: SubmissionInput, options?: SubmissionOptions): SubmissionResult;
+/**
+ * The definition as respondents may see it. R1 forms hold nothing secret;
+ * assessment answer keys (R4) will be stripped here.
+ */
+declare function publicDefinition(definition: FormDefinition): FormDefinition;
+
+/**
+ * What a respondent's device sends to submit a response, and what comes back. Shared by
+ * `submitResponse` (server) and `createSubmitOutbox` (client), so both sides read one
+ * definition. Plain JSON both ways: a host's endpoint passes the request body to
+ * `submitResponse` and answers with its result as it is.
+ */
+
+/**
+ * One submission as the device sends it: the answers (or the event log) and hidden inputs
+ * `validateSubmission` takes, plus a key that stays the same across every retry of it.
+ */
+interface SubmitRequest extends SubmissionInput {
+    /**
+     * Made once, on the device, when the respondent submits (a UUID), and sent again on every
+     * retry, so the server stores the response once however often it arrives.
+     * 16 to 128 characters: letters, digits, `-` and `_` (`isIdempotencyKey`).
+     */
+    idempotencyKey: string;
+    /**
+     * When the respondent submitted, by the device's clock (milliseconds since 1970). Untrusted
+     * and informational: an outbox may deliver it hours later. The server's own time is
+     * `receivedAt`.
+     */
+    clientSubmittedAt?: number | undefined;
+    /**
+     * The visit's attempt id (a UUID made when the form opened), when the form has upload
+     * fields: the server hashes it (`attemptHash`) to find the uploads this visit made. Sent in
+     * the body so a retry from the outbox, after a restart or from a native app, still carries it.
+     */
+    attemptId?: string | undefined;
+}
+/** Why a submission was not stored as a new response. */
+type SubmitFailureReason = "invalid" | "duplicate" | "conflict" | "closed" | "rate_limited" | "store_failed";
+/**
+ * What `submitResponse` answers. A new response was stored only when `ok` is true.
+ *
+ * - `invalid`: the submission (or its idempotency key) doesn't pass; `errors` is keyed by
+ *   field id, `""` for the submission as a whole. Sending it again won't help.
+ * - `duplicate`: a response with this idempotency key and these answers is already stored,
+ *   as `id`. The device's earlier attempt went through: treat it as delivered, and deliver
+ *   nothing again.
+ * - `conflict`: a response with this idempotency key is stored, with other answers. The
+ *   device must not take it as delivered, and sending it again won't help.
+ * - `closed`: the form isn't taking responses. Sending it again won't help.
+ * - `rate_limited`: too many from this client; try again later, after `retryAfterSeconds`
+ *   when it is given.
+ * - `store_failed`: it couldn't be checked or stored this time; try again later.
+ *
+ * More reasons may be added. A device treats one it doesn't know as `retry`
+ * (`submitOutcome`), so it keeps the submission.
+ */
+type SubmitResult = {
+    ok: true;
+    id: string;
+    receivedAt: string;
+} | {
+    ok: false;
+    reason: "duplicate";
+    id: string;
+    receivedAt: string;
+} | {
+    ok: false;
+    reason: "invalid";
+    errors: Record<string, string>;
+} | {
+    ok: false;
+    reason: "conflict";
+} | {
+    ok: false;
+    reason: "closed";
+} | {
+    ok: false;
+    reason: "rate_limited";
+    retryAfterSeconds?: number;
+} | {
+    ok: false;
+    reason: "store_failed";
+};
+/** What an idempotency key matches: 16 to 128 letters, digits, `-` and `_`. */
+declare const IDEMPOTENCY_KEY_PATTERN: RegExp;
+declare function isIdempotencyKey(value: unknown): value is string;
+/** What a device does with an answer to a submit. */
+type SubmitOutcome = "delivered" | "retry" | "rejected";
+/**
+ * What a device does with an answer: `delivered` (stored now or before: drop it from the
+ * outbox), `retry` (keep it and try again later) or `rejected` (keep it, marked failed, for
+ * the respondent to fix or discard). Anything that isn't a `SubmitResult` is `retry`, so an
+ * unexpected answer (a proxy's error page, say) never loses a submission.
+ */
+declare function submitOutcome(result: unknown): SubmitOutcome;
+/** Whether `value` is a `SubmitResult`, for a device reading an endpoint's JSON. */
+declare function isSubmitResult(value: unknown): value is SubmitResult;
+
+export { MAX_SUBMISSION_VALUES as $, photoRefs as A, photoSizeMessage as B, photoTypeMessage as C, DEFAULT_PHOTO_FILES as D, submitOutcome as E, type BeginUploadInput as F, type CheckUploadsOptions as G, type CheckedSubmission as H, IDEMPOTENCY_KEY_PATTERN as I, type CheckedUploads as J, type ClientIpOptions as K, DEFAULT_TRUSTED_IP_HEADERS as L, MAX_PHOTO_FILES as M, EDIT_LINK_PARAM as N, EDIT_LINK_TTL_SECONDS as O, type PhotoFormat as P, type EditLinkClaims as Q, type EditLinkOptions as R, type SubmissionInput as S, type EditLinkRequestOptions as T, UPLOAD_FIELD_TYPES as U, type EditLinkUrlOptions as V, type EditSecretLog as W, type EditSecretReader as X, type EditableResponse as Y, MAX_EVENTS as Z, MAX_REPLAY_WORK as _, type PhotoRef as a, MIN_EDIT_SECRET_BYTES as a0, NOT_UPLOADED_MESSAGE as a1, RATE_LIMIT_DEFAULTS as a2, RAW_EVENTS_PER_EVENT as a3, type RateLimitAnswer as a4, type RateLimitStore as a5, type StoredSubmissionRef as a6, type StoredUpload as a7, type SubmissionOptions as a8, type SubmissionRecord as a9, validateSubmission as aA, verifyEditToken as aB, withEditLinkHeaders as aC, withEditToken as aD, type SubmissionResult as aa, type SubmissionStore as ab, type SubmitResponseOptions as ac, UPLOAD_MESSAGES as ad, type UploadForm as ae, type UploadHandlerOptions as af, type UploadMessages as ag, type UploadOwner as ah, type UploadRules as ai, type UploadStore as aj, addressPrefix as ak, allow as al, attemptHash as am, checkUploads as an, clientIp as ao, createEditSecretReader as ap, createUploadHandler as aq, editLinkUrl as ar, isEditLinkRequest as as, isUsableEditSecret as at, publicDefinition as au, rateLimitKey as av, signEditToken as aw, submitResponse as ax, uploadFields as ay, uploadRules as az, type SubmitRequest as b, type SubmitFailureReason as c, type SubmitResult as d, DEFAULT_PHOTO_SIZE_MB as e, MAX_PHOTO_ID_LENGTH as f, MAX_PHOTO_NAME_LENGTH as g, MAX_PHOTO_SIZE_MB as h, MAX_UPLOAD_REQUEST_BYTES as i, type MergeOptions as j, PHOTO_FORMATS as k, PHOTO_TYPE as l, type PhotoLimits as m, type SignedUpload as n, type SubmitOutcome as o, type UploadGrant as p, type UploadRefusal as q, type UploadRequest as r, isIdempotencyKey as s, isPhotoFormat as t, isPhotoRef as u, isSubmitResult as v, mergeResponses as w, photoCountMessage as x, photoFormatList as y, photoLimits as z };