@marktiderman/genesis-forms 0.2.0 → 0.3.0

package/README.md

@@ -12,24 +12,24 @@ server. Zero dependencies.
 ```ts
 import { defineForm, f, when } from "@marktiderman/genesis-forms";
 
-export const afterClass = defineForm({
-  id: "after-class",
-  title: "How was class?",
+export const eventFeedback = defineForm({
+  id: "event-feedback",
+  title: "How was the event?",
   layout: { mode: "focus" },
-  hidden: { coach: f.hidden.string({ source: "server" }) },
+  hidden: { owner: f.hidden.string({ source: "server" }) },
   blocks: [
-    f.rating("overall", { label: "How was today's class?", required: true }),
+    f.rating("overall", { label: "How was today's event?", required: true }),
     f.longText("improve", { label: "Anything we could do better?" }),
-    f.yesNo("contact_me", { label: "Want {{hidden:coach|a coach}} to follow up?" }),
+    f.yesNo("contact_me", { label: "Want {{hidden:owner|someone}} to follow up?" }),
     f.email("email", { label: "Best email to reach you", required: true }),
   ],
   logic: [when("contact_me").isNot(true).hide("email")],
   endings: [{ id: "default", title: "Thanks!" }],
 });
 
-type Answers = typeof afterClass.$answers; // { overall?: number; improve?: string; … }
-const json = afterClass.toJSON();          // the canonical definition
-const version = afterClass.hash();         // content fingerprint for publishing
+type Answers = typeof eventFeedback.$answers; // { overall?: number; improve?: string; … }
+const json = eventFeedback.toJSON();          // the canonical definition
+const version = eventFeedback.hash();         // content fingerprint for publishing
 ```
 
 ## The rules it keeps
@@ -76,6 +76,7 @@ const version = afterClass.hash();         // content fingerprint for publishing
 | `isFormEvent(value)` | Guard for one well-formed event-log entry. |
 | `isSensitive(block)` | `sensitive: true` on a field, or the `props.sensitive` alias. Hidden inputs take `sensitive: true` too (`f.hidden.string({ source: "server", sensitive: true })`); devtools masks both. |
 | `/server` → `validateSubmission`, `publicDefinition` | Re-check a submission against the published definition: drops unknown and logic-hidden answers, ignores client values for server inputs, checks drafts by format only. Never throws on a malformed body. No IO. |
+| `/destinations` → `emailDestination` + `resendProvider`, `sheetsDestination`, `webhookDestination`, `responseRow` | Send a checked submission to an inbox, a Google Sheet or a signed webhook. fetch and WebCrypto only. See [Destinations](#destinations). |
 | `explain(engine, blockId)` | "Why is this hidden?": the path, the jump that skipped a block, each show/hide rule with its result in plain English, and the field's validation. |
 | `/testing` → `simulate`, `coverage`, `runScenario`, `recordScenario`, `compactEvents` | Walk a form by key, enumerate its paths, and run JSON scenarios. See [Testing](#testing). |
 
@@ -84,13 +85,44 @@ space, `-`, `(`, `)` and `.`, 7 to 15 digits, at most 32 characters. Operators:
 `answered`, `empty`. Its manifest carries `autocomplete: "tel"` and `inputMode: "tel"` (email:
 `"email"` for both).
 
+### Structured field types
+
+Four built-in types collect more than one value for a question. `STRUCTURED_FIELD_TYPES` lists
+them (`["list", "table", "media-notes", "text-highlights"]`), for a builder palette or a check.
+
+| Type and builder | Value | Use it for |
+| --- | --- | --- |
+| `list`, `f.list(key, { min, max, itemMaxLength, itemPlaceholder })` | `string[]` | Several short answers: goals, action items, three wins this week. Supports `contains`. |
+| `table`, `f.table(key, { columns, minRows, maxRows })` | `Record<column, string>[]` | Rows with fixed columns (up to `MAX_TABLE_COLUMNS`, 6): an action plan (What / Who / By when), pros and cons. |
+| `media-notes`, `f.mediaNotes(key, { maxNotes, textMaxLength })` | `{ at, text }[]`, `at` in seconds | Notes pinned to moments of a video or audio: lecture notes, reviewing a recorded call. |
+| `text-highlights`, `f.textHighlights(key, { text, maxHighlights })` | `{ start, end, quote, note }[]` | Highlight passages of a text and note on each: annotating an article, a policy or a contract. Every highlight needs a note. |
+
+```ts
+const plan = defineForm({
+  id: "action-plan",
+  title: "Action plan",
+  blocks: [
+    f.list("goals", { label: "Your goals for this quarter", max: 3 }),
+    f.table("actions", {
+      label: "Actions",
+      columns: [{ key: "what", label: "What", long: true }, { key: "who", label: "Who" }, { key: "when", label: "By when" }],
+      maxRows: 5,
+    }),
+  ],
+});
+```
+
+Each type validates, normalizes (trimmed, blanks dropped, notes in time order), summarizes and has
+samples for `coverage()`. Helpers: `listLimits`, `tableColumns`, `tableLimits`, `formatTimestamp`
+and `parseTimestamp`; types `TableColumn`, `MediaNote` and `Highlight`.
+
 ## On the server
 
 ```ts
 import { validateSubmission } from "@marktiderman/genesis-forms/server";
 
 const result = validateSubmission(publishedDefinition, await request.json(), {
-  context: { coach: coachForNow() }, // server inputs, resolved here
+  context: { owner: ownerForNow() }, // server inputs, resolved here
 });
 if (!result.ok) return Response.json({ errors: result.errors }, { status: 422 });
 await store(result.submission); // answers, hidden, context, ending
@@ -102,16 +134,84 @@ Errors are keyed by field id. The `""` key is for the whole submission: `"Malfor
 client's log still replays. With `settings.clearHiddenValues: false`, a hidden field's value is kept
 only if its format is valid.
 
+## Destinations
+
+`@marktiderman/genesis-forms/destinations` sends a checked submission somewhere. No dependencies:
+fetch and WebCrypto only, so it runs on Node 20+, edge runtimes and Workers. Storage stays the
+app's (the outbox, claims, attempts, the retry schedule); a destination delivers once and reports
+what happened. It is a separate subpath, not part of `/server`, because `/server` does no IO and
+this does: it is the one entry that touches the network and credentials.
+
+```ts
+import { validateSubmission } from "@marktiderman/genesis-forms/server";
+import {
+  emailDestination,
+  resendProvider,
+  sheetsDestination,
+  webhookDestination,
+  type Destination,
+} from "@marktiderman/genesis-forms/destinations";
+
+const destinations: Record<string, Destination> = {
+  email: emailDestination({
+    provider: resendProvider({ apiKey: env.RESEND_API_KEY }),
+    from: "Feedback <feedback@send.example.com>",
+    replyTo: "email", // the key of an email field; only a single valid address is used
+  }),
+  sheet: sheetsDestination({
+    account: { clientEmail: env.GOOGLE_SERVICE_ACCOUNT_EMAIL, privateKey: env.GOOGLE_SERVICE_ACCOUNT_PRIVATE_KEY },
+  }),
+  webhook: webhookDestination({ secret: (config) => secretFor(config) }),
+};
+
+const checked = validateSubmission(definition, body);
+if (checked.ok) {
+  const submission = { id: savedId, ...checked.submission, submittedAt: "2026-10-22", meta: { form_version: 3 } };
+  const result = await destinations.sheet.deliver(submission, definition, { spreadsheetId: "1AbC…" }, {
+    deliveryId,         // stable across retries: the email idempotency key and the webhook-id
+    state: saved.state, // what the sheet cached last time
+    redelivery: claims > 1,
+  });
+  if (result.ok) saveState(result.state);
+  else if (result.retryable) retryLater(result.retryAfterSeconds); // else: needs a config fix
+}
+```
+
+**The contract.** `deliver(submission, definition, config, options?)` resolves a `DeliveryResult`
+and never throws. Failures carry `retryable` (`true` for 408, 425, 429, 5xx, timeouts and network
+errors; `false` for other statuses, bad config, a secret or account resolver that throws, and a
+`TypeError` from a bug), `retryAfterSeconds` when the service said when to come back
+(Retry-After as delta-seconds or an IMF-fixdate, else 60 s; at least 1 s, at most a day), the
+`status`, and an `error` that is safe to
+store and log: never a secret, an answer, contact details or the webhook URL. Config is plain JSON
+(recipients, a spreadsheet id, a URL); secrets go to the factory, never in config. Every request
+has a timeout (`timeoutMs`, default 10 s) and honours `options.signal`. `deliverBatch(items,
+config)` (the sheet) sends many in one request; all succeed or fail together. Write your own by
+implementing `Destination` and throwing `DeliveryError` inside; `deliveryFailure(error)` turns any
+error into a safe result.
+
+**Rows.** `responseRow(submission, definition)` flattens a submission: `id`, `submitted_at`, the
+app's `meta` columns, then one column per field key in form order. Numbers stay numbers, choices
+show their labels, lists join with `, `, yes/no reads `Yes`/`No`. Labels fill recall from the
+submission. On an anonymous form identifying fields get no column. `sensitive` fields:
+`"include"`, `"mask"` (`[sensitive]`) or `"omit"`; recall never leaks a masked value into a label.
+
+| Destination | Config | Notes |
+| --- | --- | --- |
+| `emailDestination({ provider, from, replyTo?, render?, sensitive? })` | `{ to: string \| string[], subject? }` | HTML and plain text from the definition (`renderEmail`), every value HTML-escaped. Subject, From, To and Reply-To are stripped of line breaks or refused, so no answer can add a header. At most 50 recipients. Sensitive fields masked by default. The idempotency key is the delivery id plus a hash of the recipients. `resendProvider({ apiKey })` is built in; any `EmailProvider` works. `render` and `emailBody(lines)` let an app write its own content and keep the escaping. |
+| `sheetsDestination({ account, escapeFormulas?, sensitive? })` | `{ spreadsheetId, sheetName? }` | Service-account JWT signed with WebCrypto (RS256), token cached per process. Creates the tab, writes and freezes the header, adds a column for a new key without moving others, appends with `valueInputOption=RAW`, so Sheets stores text exactly as typed and never runs it as a formula (`@team thanks` stays `@team thanks`). No `'` is added by default, since RAW would store it literally; `escapeFormulas: true` adds one (headers included) for a sheet that is exported and opened elsewhere. `escapeFormula(cell)` is the same opt-in guard for CSV you write yourself: text starting with `=`, `@`, tab or CR, or with `+`/`-` followed by anything but number punctuation, gets a leading `'`. Keeps the tab, header and last row in `state`, so a normal delivery is one request. On `redelivery`, skips ids already in the last 500 rows. A 403/404 says to share the sheet with the service account. |
+| `webhookDestination({ secret, allowInsecureUrls?, allowPrivateHosts?, sensitive? })` | `{ url }` | [Standard Webhooks](https://www.standardwebhooks.com): `webhook-id`, `webhook-timestamp`, `webhook-signature: v1,<HMAC-SHA256>`. The secret is base64 (at least 16 bytes decoded), usually `whsec_`-prefixed; as in every Standard Webhooks library the prefix is optional and the rest is always base64-decoded, so receivers verify with the same string. A secret that is not padded standard base64 (a raw passphrase, say) fails permanently rather than signing deliveries no receiver could verify. Generate one with `"whsec_" + btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(32))))`. Body `{ type: "form.submitted", timestamp, data: { form, submission, row } }`. https only, no URL credentials, no localhost or private, loopback or link-local address literals, redirects not followed. A hostname that resolves to a private address is not caught: if untrusted users pick URLs, send from a network that cannot reach internal services. Receivers check with `verifyWebhook({ secret, headers, body })` (constant-time, five-minute tolerance). |
+
 ## Testing
 
 ```ts
 import { coverage, recordScenario, runScenario, simulate } from "@marktiderman/genesis-forms/testing";
 
 // Walk a form by key.
-expect(simulate(afterClass).answer({ overall: 2 }).pathKeys()).toEqual(["overall", "improve", "contact_me"]);
+expect(simulate(eventFeedback).answer({ overall: 2 }).pathKeys()).toEqual(["overall", "improve", "contact_me"]);
 
 // Every block reachable, every rule able to fire, every ending reached.
-const report = coverage(afterClass);
+const report = coverage(eventFeedback);
 expect(report.unreachableBlocks).toEqual([]);
 expect(report.rulesNeverFired).toEqual([]);
 expect(report.endings.default.reached).toBe(true); // witness: answers that reach it
@@ -138,7 +238,7 @@ to the same field, keeping the last value; the result replays to the same state
 depends on values alone, not on how they were typed. `recordScenario` compacts by default (`compact: false` keeps every event).
 
 The **conformance suite** ships in the package: `@marktiderman/genesis-forms/conformance/*.scenario.json`
-(the R1 sample forms: after-class and monthly-pulse). Run each file through `runScenario` to hold
+(the R1 sample forms: event-feedback and monthly-check-in). Run each file through `runScenario` to hold
 another runtime, a renderer or an app's CI to the same behaviour. The fixtures are generated by
 `pnpm --filter @marktiderman/genesis-forms conformance:build`; review the diff before committing.
 

package/conformance/{after-class-back-after-a-jump.scenario.json → event-feedback-back-after-a-jump.scenario.json}

@@ -1,23 +1,23 @@
 {
   "scenarioVersion": 1,
-  "name": "after-class: back after a jump",
+  "name": "event-feedback: back after a jump",
   "description": "Back from a jump target returns to the block the jump came from; raising the rating puts went_well back on the path.",
   "tags": [
-    "after-class",
+    "event-feedback",
     "jump",
     "navigation"
   ],
   "definition": {
     "schemaVersion": 1,
-    "id": "after-class",
-    "title": "How was class?",
+    "id": "event-feedback",
+    "title": "How was the event?",
     "blocks": [
       {
         "kind": "field",
         "id": "overall",
         "key": "overall",
         "type": "rating",
-        "label": "How was today's class?",
+        "label": "How was today's event?",
         "required": true,
         "props": {
           "max": 5
@@ -32,24 +32,24 @@
         "props": {
           "options": [
             {
-              "value": "coaching",
-              "label": "Coaching"
+              "value": "hosting",
+              "label": "Hosting"
             },
             {
-              "value": "workout",
-              "label": "The workout"
+              "value": "content",
+              "label": "The content"
             },
             {
               "value": "community",
               "label": "Community"
             },
             {
-              "value": "scaling",
-              "label": "Scaling options"
+              "value": "pacing",
+              "label": "Pacing"
             },
             {
-              "value": "equipment",
-              "label": "Equipment"
+              "value": "venue",
+              "label": "The venue"
             },
             {
               "value": "cleanliness",
@@ -70,7 +70,7 @@
         "id": "contact_me",
         "key": "contact_me",
         "type": "yes-no",
-        "label": "Want {{hidden:coach|a coach}} to follow up with you?"
+        "label": "Want {{hidden:owner|someone}} to follow up with you?"
       },
       {
         "kind": "field",
@@ -94,12 +94,12 @@
     },
     "hidden": [
       {
-        "name": "class",
+        "name": "session",
         "type": "string",
         "source": "server"
       },
       {
-        "name": "coach",
+        "name": "owner",
         "type": "string",
         "source": "server"
       }
@@ -152,7 +152,7 @@
     "endings": [
       {
         "id": "default",
-        "title": "Thanks! See you at the next class."
+        "title": "Thanks! See you next time."
       }
     ],
     "settings": {
@@ -160,8 +160,8 @@
     }
   },
   "context": {
-    "class": "6:00 AM CrossFit",
-    "coach": "Sam"
+    "session": "Tuesday 6 PM workshop",
+    "owner": "Sam"
   },
   "events": [
     {
@@ -209,8 +209,8 @@
         "overall": 5
       },
       "context": {
-        "class": "6:00 AM CrossFit",
-        "coach": "Sam"
+        "session": "Tuesday 6 PM workshop",
+        "owner": "Sam"
       }
     }
   }

package/conformance/{after-class-contact-yes-completed.scenario.json → event-feedback-contact-yes-completed.scenario.json}

@@ -1,22 +1,22 @@
 {
   "scenarioVersion": 1,
-  "name": "after-class: contact yes, completed",
+  "name": "event-feedback: contact yes, completed",
   "description": "With name and email filled in, the follow-up request completes and both are stored.",
   "tags": [
-    "after-class",
+    "event-feedback",
     "show-hide"
   ],
   "definition": {
     "schemaVersion": 1,
-    "id": "after-class",
-    "title": "How was class?",
+    "id": "event-feedback",
+    "title": "How was the event?",
     "blocks": [
       {
         "kind": "field",
         "id": "overall",
         "key": "overall",
         "type": "rating",
-        "label": "How was today's class?",
+        "label": "How was today's event?",
         "required": true,
         "props": {
           "max": 5
@@ -31,24 +31,24 @@
         "props": {
           "options": [
             {
-              "value": "coaching",
-              "label": "Coaching"
+              "value": "hosting",
+              "label": "Hosting"
             },
             {
-              "value": "workout",
-              "label": "The workout"
+              "value": "content",
+              "label": "The content"
             },
             {
               "value": "community",
               "label": "Community"
             },
             {
-              "value": "scaling",
-              "label": "Scaling options"
+              "value": "pacing",
+              "label": "Pacing"
             },
             {
-              "value": "equipment",
-              "label": "Equipment"
+              "value": "venue",
+              "label": "The venue"
             },
             {
               "value": "cleanliness",
@@ -69,7 +69,7 @@
         "id": "contact_me",
         "key": "contact_me",
         "type": "yes-no",
-        "label": "Want {{hidden:coach|a coach}} to follow up with you?"
+        "label": "Want {{hidden:owner|someone}} to follow up with you?"
       },
       {
         "kind": "field",
@@ -93,12 +93,12 @@
     },
     "hidden": [
       {
-        "name": "class",
+        "name": "session",
         "type": "string",
         "source": "server"
       },
       {
-        "name": "coach",
+        "name": "owner",
         "type": "string",
         "source": "server"
       }
@@ -151,7 +151,7 @@
     "endings": [
       {
         "id": "default",
-        "title": "Thanks! See you at the next class."
+        "title": "Thanks! See you next time."
       }
     ],
     "settings": {
@@ -159,8 +159,8 @@
     }
   },
   "context": {
-    "class": "6:00 AM CrossFit",
-    "coach": "Sam"
+    "session": "Tuesday 6 PM workshop",
+    "owner": "Sam"
   },
   "events": [
     {
@@ -222,8 +222,8 @@
         "email": "ada@example.com"
       },
       "context": {
-        "class": "6:00 AM CrossFit",
-        "coach": "Sam"
+        "session": "Tuesday 6 PM workshop",
+        "owner": "Sam"
       }
     }
   }

package/conformance/{after-class-contact-yes-requires-name-and-email.scenario.json → event-feedback-contact-yes-requires-name-and-email.scenario.json}

@@ -1,23 +1,23 @@
 {
   "scenarioVersion": 1,
-  "name": "after-class: contact yes requires name and email",
+  "name": "event-feedback: contact yes requires name and email",
   "description": "Answering Yes to contact_me reveals name and email, and both are required on submit and on the server.",
   "tags": [
-    "after-class",
+    "event-feedback",
     "show-hide",
     "validation"
   ],
   "definition": {
     "schemaVersion": 1,
-    "id": "after-class",
-    "title": "How was class?",
+    "id": "event-feedback",
+    "title": "How was the event?",
     "blocks": [
       {
         "kind": "field",
         "id": "overall",
         "key": "overall",
         "type": "rating",
-        "label": "How was today's class?",
+        "label": "How was today's event?",
         "required": true,
         "props": {
           "max": 5
@@ -32,24 +32,24 @@
         "props": {
           "options": [
             {
-              "value": "coaching",
-              "label": "Coaching"
+              "value": "hosting",
+              "label": "Hosting"
             },
             {
-              "value": "workout",
-              "label": "The workout"
+              "value": "content",
+              "label": "The content"
             },
             {
               "value": "community",
               "label": "Community"
             },
             {
-              "value": "scaling",
-              "label": "Scaling options"
+              "value": "pacing",
+              "label": "Pacing"
             },
             {
-              "value": "equipment",
-              "label": "Equipment"
+              "value": "venue",
+              "label": "The venue"
             },
             {
               "value": "cleanliness",
@@ -70,7 +70,7 @@
         "id": "contact_me",
         "key": "contact_me",
         "type": "yes-no",
-        "label": "Want {{hidden:coach|a coach}} to follow up with you?"
+        "label": "Want {{hidden:owner|someone}} to follow up with you?"
       },
       {
         "kind": "field",
@@ -94,12 +94,12 @@
     },
     "hidden": [
       {
-        "name": "class",
+        "name": "session",
         "type": "string",
         "source": "server"
       },
       {
-        "name": "coach",
+        "name": "owner",
         "type": "string",
         "source": "server"
       }
@@ -152,7 +152,7 @@
     "endings": [
       {
         "id": "default",
-        "title": "Thanks! See you at the next class."
+        "title": "Thanks! See you next time."
       }
     ],
     "settings": {
@@ -160,8 +160,8 @@
     }
   },
   "context": {
-    "class": "6:00 AM CrossFit",
-    "coach": "Sam"
+    "session": "Tuesday 6 PM workshop",
+    "owner": "Sam"
   },
   "events": [
     {

package/conformance/{after-class-happy-path.scenario.json → event-feedback-happy-path.scenario.json}

@@ -1,22 +1,22 @@
 {
   "scenarioVersion": 1,
-  "name": "after-class: happy path",
+  "name": "event-feedback: happy path",
   "description": "Five stars, no follow-up wanted. Name and email stay hidden and are not required.",
   "tags": [
-    "after-class",
+    "event-feedback",
     "happy-path"
   ],
   "definition": {
     "schemaVersion": 1,
-    "id": "after-class",
-    "title": "How was class?",
+    "id": "event-feedback",
+    "title": "How was the event?",
     "blocks": [
       {
         "kind": "field",
         "id": "overall",
         "key": "overall",
         "type": "rating",
-        "label": "How was today's class?",
+        "label": "How was today's event?",
         "required": true,
         "props": {
           "max": 5
@@ -31,24 +31,24 @@
         "props": {
           "options": [
             {
-              "value": "coaching",
-              "label": "Coaching"
+              "value": "hosting",
+              "label": "Hosting"
             },
             {
-              "value": "workout",
-              "label": "The workout"
+              "value": "content",
+              "label": "The content"
             },
             {
               "value": "community",
               "label": "Community"
             },
             {
-              "value": "scaling",
-              "label": "Scaling options"
+              "value": "pacing",
+              "label": "Pacing"
             },
             {
-              "value": "equipment",
-              "label": "Equipment"
+              "value": "venue",
+              "label": "The venue"
             },
             {
               "value": "cleanliness",
@@ -69,7 +69,7 @@
         "id": "contact_me",
         "key": "contact_me",
         "type": "yes-no",
-        "label": "Want {{hidden:coach|a coach}} to follow up with you?"
+        "label": "Want {{hidden:owner|someone}} to follow up with you?"
       },
       {
         "kind": "field",
@@ -93,12 +93,12 @@
     },
     "hidden": [
       {
-        "name": "class",
+        "name": "session",
         "type": "string",
         "source": "server"
       },
       {
-        "name": "coach",
+        "name": "owner",
         "type": "string",
         "source": "server"
       }
@@ -151,7 +151,7 @@
     "endings": [
       {
         "id": "default",
-        "title": "Thanks! See you at the next class."
+        "title": "Thanks! See you next time."
       }
     ],
     "settings": {
@@ -159,8 +159,8 @@
     }
   },
   "context": {
-    "class": "6:00 AM CrossFit",
-    "coach": "Sam"
+    "session": "Tuesday 6 PM workshop",
+    "owner": "Sam"
   },
   "events": [
     {
@@ -175,7 +175,7 @@
       "type": "answer",
       "field": "went_well",
       "value": [
-        "coaching",
+        "hosting",
         "community"
       ]
     },
@@ -213,7 +213,7 @@
     "answers": {
       "overall": 5,
       "went_well": [
-        "coaching",
+        "hosting",
         "community"
       ],
       "contact_me": false
@@ -223,14 +223,14 @@
       "answers": {
         "overall": 5,
         "went_well": [
-          "coaching",
+          "hosting",
           "community"
         ],
         "contact_me": false
       },
       "context": {
-        "class": "6:00 AM CrossFit",
-        "coach": "Sam"
+        "session": "Tuesday 6 PM workshop",
+        "owner": "Sam"
       }
     }
   }