@stapel/forms-react 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# @stapel/forms-react
+
+## 0.1.0
+
+### Minor Changes
+
+- b1f9a4e: `@stapel/forms-react` — the frontend pair for stapel-forms.
+
+  A host page says "put form `<id>` here" and gets a rendered form:
+
+  ```tsx
+  const runtime = createFormsRuntime({ baseUrl: "/forms/api/v1/" });
+  <FormsProvider runtime={runtime}>
+    <StapelForm publicId="k3J…x9" />
+  </FormsProvider>;
+  ```
+
+  No session, no workspace id, no auth client — the two public endpoints are
+  anonymous, so a marketing page can embed a form and nothing else.
+
+  **A failed schema fetch is never "no form here."** The skin distinguishes "this
+  link is not valid" (404), "this form is closed" (410) and "we could not load it,
+  our problem, not your link" (network/5xx, with a retry). The data sits behind
+  `LoadState`'s discriminant, so the empty-state lie is a compile error rather
+  than a code-review note.
+
+  **Three override levers, none of them a fork.** `registerFormFieldWidget(kind, C)`
+  replaces how one field kind draws and outranks the skin's builtin;
+  `registerFormsSkinComponent(slot, C)` replaces a piece of the skin across eight
+  typed slots; and retheming through the token JSON reaches every surface with
+  zero code. A field kind nothing can draw renders a loud notice _and_ blocks the
+  submit — quietly skipping a possibly-required field would fabricate an invalid
+  submission and get the person refused for a question they never saw.
+
+  Ten builtin antd widgets, one per kind stapel-forms allows. Headless
+  `FormFill` / `FormBuilder` / `ResponsesTable` / `FormList` under the main entry;
+  `StapelForm` / `FormBuilderPane` / `ResponsesPane` / `FormsListPane` under
+  `./default`; `ru` and `es` as opt-in `./i18n/*` subpaths.
+
+  The submit path echoes `version_id` (a racing publish becomes a clean 409),
+  routes per-field `error.400.feature_*` onto controls by `params.field`, folds a
+  409 supersede into a refetch that preserves compatible answers and _says so_,
+  and threads `captcha_token` through. CSV export follows the
+  `X-Forms-Next-Before` header cursor verbatim.
+
+  Built against stapel-forms 0.2.0: the builder reads its field-kind catalogue
+  from `GET /forms/api/v1/field-kinds` (no mirrored table in the client), and
+  the `error.400.feature_*` family comes from the backend's own error contract.
+  `stapel_attributes` ships English only, so the generated ru/es bundles are
+  `Partial` and the pair layers authored strings for those 12 keys over them.
+
+  Enrollment note for consumers of other pairs: the `stapel-core` contract pin
+  moves v0.23.1 → v0.32.0 to pick up `error.503.mandate_unavailable`. Verified a
+  one-key delta — no already-enrolled pair's locale bundle changes.
+
+## 0.0.0
+
+- Scaffolded by `stapel-new-react-lib` from the auth-react etalon
+  (frontend-standard §9, frontend-core-architecture §4 checklist). Layers
+  api → model → flows → headless → i18n; drift-gated generated surfaces
+  (flows registry, backend error map, manifest + llms.txt) via the shared
+  monorepo `gen:*` drivers.

package/MODULE.md

@@ -0,0 +1,172 @@
+# @stapel/forms-react — module guide
+
+The human companion to the generated `llms.txt` (agent context) and
+`manifest.json` (machine catalog). `README.md` is the how-to; this is the
+why-it-is-shaped-this-way.
+
+Built against **stapel-forms 0.2.0** (contract pin
+`d66a1fb048feebebebaf98ec971fb41ab60f820b`), which closed both upstream asks
+this pair filed against 0.1.0 — so two workarounds were deleted rather than
+carried. See "What 0.2.0 deleted" below.
+
+## Layers
+
+- **api/** — `createFormsApi(client)`, one method per endpoint a JS client may
+  call (18 operations over 14 paths), over the generated `components["schemas"]` from this pair's own
+  package-local `api/generated/schema.ts` (`pnpm gen:api` ← stapel-forms
+  `docs/schema.json`). Two families, and the split is load-bearing:
+  `getPublicForm`/`submit` are **anonymous**; everything else is
+  `IsNotAnonymousUser` + `authorize()` + an explicit `workspace_id`.
+  `api/export.ts` is the raw-`fetch` carve-out (see below).
+- **model/** — `formsQueryKeys` (one key factory, `["forms"]` namespace),
+  `createFormsRuntime`, context/hooks, and the read/write hooks.
+- **flows/** — `toFlowError` + the zero-flow `FORMS_FLOWS` registry shim.
+  stapel-forms annotates no `@flow_step`, so `docs/flows.json` carries no
+  `forms.*` flow and `gen:flows` emits nothing. When the backend annotates
+  flows, swap the shim for re-exports of `generated/flows.gen.ts`.
+- **widgets/** — the field-widget registry and the client-side validation
+  mirror. Main entry, not `/default`: a host building its own renderer uses the
+  same seam the skin does. (The config-form declarations used to live here too,
+  as `configForms.ts`; they come off the wire now.)
+- **headless/** — `FormFill`, `FormBuilder`, `ResponsesTable`, `FormList`.
+- **i18n/** — the en floor + generated backend error bundles; `ru`/`es` as
+  their own subpaths so a host that does not need them carries nothing.
+- **default/** — the antd skin, a separate entry point.
+
+## Why the CSV export does not use core's client
+
+`GET /forms/<id>/submissions/export` cannot ride `StapelClient` for two
+independent reasons: the body is a CSV **file**, and the continuation cursor
+rides the **`X-Forms-Next-Before` response header**, which `StapelClient.request`
+does not surface at all. So `api/export.ts` speaks `fetch` directly — the same
+hand-authored carve-out docs-react's `api/content.ts` and recordings-react's
+`uploadRecordingBlob` use, and the one legal home of `fetch` under
+`stapel/no-raw-fetch`.
+
+The cursor is passed back **verbatim**. It is Z-suffixed rather than isoformat
+because a bare `+00:00` in a query string decodes to a space, which made the
+second page a silent 400 during the backend build; re-formatting it here would
+reintroduce exactly that.
+
+**v1 limitation, stated:** the bearer-refresh and verification-403 seams of
+`createStapelClient` do NOT run on this raw surface. A 401 here throws like any
+other error status instead of triggering a refresh-and-retry. `credentials` and
+`defaultHeaders` from the runtime ARE forwarded, so cookie-mode hosts work
+unchanged. Closing this properly is a core change (a response-returning
+primitive on `StapelClient`), not a per-module workaround.
+
+## What 0.2.0 deleted
+
+**`widgets/configForms.ts` — the pinned TypeScript mirror — is gone.**
+stapel-forms 0.2.0 serves `stapel_attributes.config_form()` at
+`GET /forms/api/v1/field-kinds`, so the declaration is the single source of
+truth again: a type registered through `EXTRA_TYPES` shows up in the builder
+with no client release, and there is no table left to drift. The builder reads
+it through `useFieldKinds`.
+
+Three things about that route are easy to get wrong and are pinned by
+`test/contract.test.ts`: **no `admin/` prefix**, **no trailing slash** (unlike
+the two anonymous routes, which require one), and `?workspace_id=` is
+**required**. It carries `forms.manage`, not `forms.view` — the catalogue names
+host types whose slugs are internal vocabulary, and a principal who cannot build
+a form has no use for the builder's dictionary.
+
+Reading the real declarations also corrected a detail the mirror had wrong:
+widget params (`step`, `placeholder`, inline `options`) live **under
+`spec.params`**, not flattened onto the spec. `ConfigField` reads them from
+there now.
+
+**The hand-carried `error.400.feature_*` English is gone.** 0.2.0's
+`docs/errors.json` grew 63 → 75 keys, the 12 new ones owned by
+`stapel_attributes`, so the family arrives through `gen:errors` like every other
+backend code. The self-deleting test that asserted the registry omitted them is
+deleted with it; its inverse now asserts the family IS generated, so nobody
+re-adds a hand copy.
+
+## Why the ru/es bundles are `Partial`
+
+`stapel_attributes` ships English only — it has no `translations/` directory at
+all — so its 12 keys can appear in NO locale catalog, and demanding them made
+the ru/es bundles unbuildable while stapel-forms' own catalog was perfectly
+correct. `scripts/gen-errors.mjs` gained a general knob for exactly this shape
+(a module inheriting an L1 library's keys):
+`ERRORS_LOCALE_EXEMPT_OWNERS=stapel_attributes` for this pair.
+
+Exempted keys are not required in a locale catalog and are left OUT of that
+locale's generated bundle, which widens its type to
+`Partial<Record<FormsErrorCode, string>>` — so the gap is visible to TypeScript
+instead of silently falling back to English. The pair's own `i18n/ru.ts` /
+`i18n/es.ts` layer authored strings for all 12 over the generated bundle.
+English is unaffected: it comes from the registry artifact, which is
+authoritative for every owner.
+
+This is opt-in per pair, so a module that DOES own a key and dropped it from its
+catalog still goes red. Upstream localization is logged as stapel-forms
+MODULE.md §12.6; when it lands, drop the env knob and the authored strings.
+
+## Deviations from the spec's sketch, with reasons
+
+1. **`date` renders a native input, not antd's `DatePicker`.** `DatePicker`
+   speaks Dayjs; adopting it would add a runtime dependency for one widget and
+   insert a format-guessing step where the native control already yields the ISO
+   string the attributes date type parses. `precision` picks the input type.
+2. **Builder-less is now a SERVER signal, not a pair opinion** (§12 risk 5,
+   applied). Two distinct facts arrive from `/field-kinds` and the bag reports
+   them separately so a skin can word them differently:
+   `registered: false` (the host allowlisted a kind the attributes registry
+   does not carry) and `fields: []` (registered, but declares no config form —
+   how `convertible_unit` arrives). Either way the field stays LISTED,
+   reorderable and removable, and authorable through the draft PUT: a builder
+   that dropped an unknown kind would silently drop the field from a stored
+   schema. Separately, two of upstream's 13 config WIDGETS are not implemented
+   in this skin (`hierarchical_options`, `timestamp_array`); those individual
+   rows say so, and the rest of the kind stays editable.
+3. **The submit-blocked key is `forms.submit.blocked.unsupported_kind`**, not
+   the spec's illustrative `forms.unsupported_kind` — every other blocked reason
+   in this pair is `forms.<surface>.blocked.<why>`, and one key in a different
+   shape is a key somebody will mistype.
+4. **Error params are NOT narrowed to the artifact's declared list.** The
+   registry declares only the slots a message interpolates
+   (`feature_mandatory_missing` declares `["feature"]`), but the runtime also
+   sets `field`, `slug` and `ref_value` — and `params.field` is precisely what
+   routes a refusal onto a control. Typing `params` to the declared list would
+   make the pair's own field-error routing a type error against a payload the
+   server really sends.
+5. **The client-side mirror emits the SERVER's error keys.** A "too long" caught
+   locally and one caught by the server render the same sentence in the same
+   language. Pair-invented copy for the local half would give one problem two
+   wordings and become a lie the moment the backend's rule moved.
+
+## Seams
+
+| Seam | Call | Beats |
+|---|---|---|
+| Field widget | `registerFormFieldWidget(kind, C)` | the skin's builtin |
+| Skin slot | `registerFormsSkinComponent(slot, C)` | the skin's own part |
+| Theme | regenerate the token JSON | everything, with zero code |
+| Client | `clients={{ forms: runtime.client }}` | the default client |
+| i18n | register a bundle last | any pair copy |
+
+## Query keys and invalidation
+
+Everything under `["forms"]`. Admin mutations invalidate the module ROOT rather
+than guessing which entries moved — `rotateLink` changes the very `public_id`
+the anonymous read is cached under, so a targeted invalidation would leave a
+stale schema under a token that no longer resolves.
+
+`useSubmitForm` invalidates nothing (an anonymous respondent holds no admin
+cache) and does not retry (a resubmit is not idempotent — a retried POST the
+server actually received is a duplicate row in somebody's spreadsheet).
+
+## Session gating
+
+Every admin read is gated on `useActiveSessionReady`. `usePublicForm` is
+deliberately NOT — core's own doc comment carves out "a public GET", and gating
+it would make an embedded form on a marketing page wait for a login bootstrap it
+has no stake in.
+
+## Live counts
+
+Refetch only. A `forms:ws:<workspace_id>` Signal stream is reserved naming for
+when the stapel-realtime substrate lands; forms does not build a socket, and
+that is a lint boundary rather than an unfinished feature.

package/README.md

@@ -0,0 +1,207 @@
+# @stapel/forms-react
+
+The frontend pair for **stapel-forms**: an admin defines a form's schema, a host
+page says *"put form `<id>` here"*, and this library fetches the schema and
+renders it — default skin, or your own.
+
+Business + state in the main entry, zero visual opinion; the antd skin lives
+behind `./default` so a host that renders its own visuals never carries it.
+Built on `@stapel/core` (typed client + `StapelApiError` envelope, token
+refresh, verification-403 interception, i18n engine, analytics seam, TanStack
+Query).
+
+## Install
+
+```
+pnpm add @stapel/forms-react @stapel/core @tanstack/react-query react
+# for the default skin:
+pnpm add antd @stapel/tokens-antd
+```
+
+## Put a form on a page
+
+The whole ask, in five lines. **No session, no workspace id, no auth client** —
+the two public endpoints are anonymous, so a marketing page can embed a form and
+nothing else:
+
+```tsx
+import { createFormsRuntime, FormsProvider } from "@stapel/forms-react";
+import { StapelForm } from "@stapel/forms-react/default";
+
+const runtime = createFormsRuntime({ baseUrl: "/forms/api/v1/" });
+
+export function ContactPage() {
+  return (
+    <FormsProvider runtime={runtime}>
+      <StapelForm publicId="k3JhQ2Zt8uY1sVb7cD9xLg" />
+    </FormsProvider>
+  );
+}
+```
+
+The handle you embed is the **`public_id`** — the same non-enumerable token the
+backend serves anonymously. The pair never needs the row UUID or a workspace id
+to render.
+
+In an app that already has a session, put the forms client on core's provider
+alongside the others and keep one client per module:
+
+```tsx
+<StapelProvider client={authRuntime.client} clients={{ forms: runtime.client }} i18n={i18n}>
+  <FormsProvider runtime={runtime}>{app}</FormsProvider>
+</StapelProvider>
+```
+
+## A failed fetch is never "no form here"
+
+The one rule this pair is built around. A schema read has **three** outcomes and
+the skin says a different thing for each:
+
+| What happened | What the person sees |
+|---|---|
+| `404 error.404.forms_not_found` | "This form link is not valid." |
+| `410 error.410.forms_closed` | "This form is closed and is no longer accepting responses." |
+| network fault / 5xx | "We could not load this form. This is a problem on our side, not with your link." **+ a retry button** |
+
+The bag exposes `state: LoadState<PublicForm>`, so the data is *behind* the
+discriminant — there is no `.data` to read on a failed load, and the
+`no-flattened-load-state` lint rule enforces it mechanically. Branch on the
+verdicts with core's `hasErrorCode`.
+
+## Headless
+
+`<StapelForm>` is one renderer over `<FormFill>`. Write another and lose nothing:
+
+```tsx
+<FormFill publicId="k3J…x9">
+  {(bag) => matchLoad(bag.state, {
+    loading: () => <Spinner />,
+    failed: (e) => <MyError error={e} onRetry={bag.refetch} />,
+    ready: (form) => <MyFields form={form} bag={bag} />,
+  })}
+</FormFill>
+```
+
+The bag carries `values` / `setValue`, `fieldErrors` keyed by slug, an
+`ActionAvailability` submit gate that always states *why* it is off,
+`superseded`, `unsupportedKinds`, and `setCaptchaToken`.
+
+Also headless: `<FormBuilder>`, `<ResponsesTable>`, `<FormList>`.
+
+## Three ways to override, none of them a fork
+
+**1. Props** — `mode`, `showTitle`, `submitLabel`.
+
+**2. The field-widget registry.** The backend's field vocabulary is an open
+registry (`stapel_attributes`), so the frontend's is too:
+
+```tsx
+registerFormFieldWidget("signature", SignaturePad);
+```
+
+Resolution is *your registration → the skin's antd builtin → an
+"unsupported field" notice*. A host registration always wins. A kind nothing can
+draw renders the notice **and blocks the submit** — silently skipping a
+possibly-required field would fabricate an invalid submission and get the person
+refused for a field they never saw.
+
+**3. The skin-slot registry** — replace a piece of the skin itself:
+
+```tsx
+registerFormsSkinComponent("fill.submitBar", MySubmitBar);
+```
+
+Slots: `fill.fieldRow`, `fill.submitBar`, `fill.confirmation`,
+`fill.unsupportedField`, `responses.cell`, `responses.toolbar`,
+`builder.fieldRow`, `builder.toolbar`.
+
+**And underneath all three: retheming.** Every `/default` surface wraps itself in
+`<FormsSkinTheme>`, which reads `@stapel/tokens` through `@stapel/tokens-antd`.
+Regenerate your `--stapel-*` custom properties from the token JSON and the form
+follows, with zero code.
+
+## Builtin widgets
+
+| Kind | Widget |
+|---|---|
+| `string` | `Input`, or `Input.TextArea` when `config.multiline` |
+| `int` / `float` | `InputNumber` (min/max/precision/prefix/postfix) |
+| `bool` | `Switch` with the config's `trueLabel`/`falseLabel` |
+| `select` | `Segmented` at ≤4 single choices, else `Select` (multi/tags) |
+| `date` | native `<input type=date\|month\|datetime-local>`, or a year `InputNumber` |
+| `header` | `Typography.Title` — a caption, never a control |
+| `hex_color` | `ColorPicker` |
+| `hierarchical_select` | `Cascader` |
+| `convertible_unit` | `InputNumber` + a unit `Select` |
+
+`date` deliberately uses a native input rather than antd's `DatePicker`: the
+picker speaks Dayjs, which would add a runtime dependency for one widget and put
+a format-guessing step between the person and a wire format the backend already
+parses. Register the picker yourself if you want it.
+
+## Captcha
+
+The netintel tier decides whether a token is required at all, so the pair only
+transports one. Render your challenge through the `captcha` prop and hand the bag
+a token:
+
+```tsx
+<StapelForm
+  publicId="k3J…x9"
+  captcha={(bag) => <Turnstile onVerify={(t) => bag.setCaptchaToken(t)} />}
+/>
+```
+
+## Admin surface
+
+Capability-gated over REST (`forms.view`, `forms.manage`,
+`forms.responses.view`, `forms.responses.manage`):
+
+```tsx
+<FormsListPane workspaceId={ws} onOpen={(form) => navigate(form.id)} />
+<FormBuilderPane workspaceId={ws} formId={id} />
+<ResponsesPane workspaceId={ws} formId={id} />
+```
+
+`<FormBuilderPane>` is **data-driven**: a field's options come from
+`GET /field-kinds`, which serves the config declarations `stapel_attributes`
+publishes per type. There is no hand-written form per kind and no mirrored table
+— register a feature type upstream and it appears in the builder with no client
+release.
+
+A kind arrives *builder-less* for either of two reasons the server distinguishes:
+`registered: false` (this deployment allowlisted a type the attributes registry
+does not carry) or `fields: []` (registered, but it declares no config form —
+`convertible_unit`). Either way the field is still listed, still renders, still
+submits, and stays authorable through the draft API — a builder that dropped an
+unknown kind would silently drop the field from a stored schema.
+
+`<ResponsesPane>` draws **per-version columns** (a response records which schema
+it answered, so an old row shows the questions actually asked), keyset paging,
+resend, and CSV export.
+
+### Resend overrides REPLACE
+
+An explicit destination on a resend replaces the form's configured recipients for
+that one send — "send this one to legal" must not also re-send it to everybody
+who already received it.
+
+## i18n
+
+```tsx
+registerFormsI18n(i18n);                    // en floor, always
+registerFormsI18nRu(i18n);                  // from @stapel/forms-react/i18n/ru
+registerFormsI18nEs(i18n);                  // from @stapel/forms-react/i18n/es
+```
+
+Registration order is override priority — a host bundle registered last wins.
+
+**Field labels are not i18n keys.** They are admin-authored content carried in
+the schema and render verbatim in whatever language the admin typed. Translating
+form *content* is a separate problem from translating the pair's chrome.
+
+## Docs
+
+`MODULE.md` — layer map, seams, and the deliberate deviations, with reasons.
+`llms.txt` / `manifest.json` — the generated agent/machine views, drift-gated
+against the backend contract.

package/dist/api/export.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Raw-transport binding forwarded from the runtime. Declared here rather than
+ * in `formsApi.ts` so the two modules do not import each other's types in a
+ * cycle — `formsApi.ts` re-exports it as part of its public surface.
+ */
+export interface FormsApiOptions {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly credentials?: RequestCredentials;
+    readonly defaultHeaders?: Record<string, string>;
+}
+/**
+ * Response header carrying the keyset cursor for the NEXT export page.
+ * Absent (or empty) means this was the last page.
+ */
+export declare const FORMS_NEXT_BEFORE_HEADER = "X-Forms-Next-Before";
+/** The raw-transport binding `createFormsApi` closes over. */
+export interface FormsRawTransport {
+    /** e.g. `/forms/api/v1` — the same base the pair's `StapelClient` uses. */
+    readonly baseUrl: string;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly credentials?: RequestCredentials;
+    /** Merged into every raw request (e.g. a tenant id / auth header). */
+    readonly headers?: Record<string, string>;
+}
+/** One page of the CSV export. */
+export interface CsvExportPage {
+    /** The page's CSV text, header row included. */
+    readonly csv: string;
+    /**
+     * The cursor to pass as the next call's `before`, or `null` when the export
+     * is complete. Opaque — pass it back verbatim (see the module header).
+     */
+    readonly nextBefore: string | null;
+}
+/** Build the transport from the runtime options, dropping absent keys so
+ * `exactOptionalPropertyTypes` stays satisfied. */
+export declare function createExportTransport(baseUrl: string, options: FormsApiOptions): FormsRawTransport;
+/**
+ * Fetch one page of a form's CSV export.
+ *
+ * Drive it to completion by feeding {@link CsvExportPage.nextBefore} back in
+ * as `before` until it is `null`, concatenating the pages MINUS the repeated
+ * header row (see `useCsvExport`, which does exactly that).
+ */
+export declare function exportSubmissionsCsv(transport: FormsRawTransport, params: {
+    readonly workspaceId: string;
+    readonly formId: string;
+    readonly before?: string;
+    readonly version?: number;
+    readonly signal?: AbortSignal;
+}): Promise<CsvExportPage>;
+/**
+ * Concatenate export pages into one CSV, keeping the header row exactly once.
+ *
+ * Every page the server streams carries its own header row (it is a standalone
+ * CSV file); pasting the pages verbatim would sprinkle header rows through the
+ * middle of the spreadsheet. Splitting on the first newline is safe here
+ * because a stapel-forms header row is a list of field slugs — slugs cannot
+ * contain a newline, so the first line is always exactly the header.
+ *
+ * Each retained chunk is newline-terminated before the join: a page whose last
+ * row has no trailing newline would otherwise be glued to the next page's
+ * first row, silently producing one corrupt record per page boundary.
+ */
+export declare function concatCsvPages(pages: readonly string[]): string;
+//# sourceMappingURL=export.d.ts.map

package/dist/api/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../src/api/export.ts"],"names":[],"mappings":"AA6BA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED;;;GAGG;AACH,eAAO,MAAM,wBAAwB,wBAAwB,CAAC;AAE9D,8DAA8D;AAC9D,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;mDACmD;AACnD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,GACvB,iBAAiB,CAWnB;AAkCD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE;IACN,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B,GACA,OAAO,CAAC,aAAa,CAAC,CA8BxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAgB/D"}

package/dist/api/export.js

@@ -0,0 +1,138 @@
+/**
+ * The CSV half of the stapel-forms surface — hand-authored api/ carve-out
+ * (the docs-react `api/content.ts` / recordings-react `uploadRecordingBlob`
+ * precedent, the one legal home of `fetch` per `stapel/no-raw-fetch`).
+ *
+ * `GET /forms/<id>/submissions/export` is not a JSON operation and cannot ride
+ * core's `StapelClient` for two independent reasons:
+ *
+ *  1. the body is a CSV file, and `StapelClient.request` parses/returns a
+ *     decoded JSON value;
+ *  2. the CONTINUATION CURSOR rides a response header,
+ *     `X-Forms-Next-Before` — which `StapelClient` does not surface at all.
+ *
+ * Backend delta note 6 explains why the cursor is a header rather than a
+ * trailing body field: the body is a spreadsheet, and a cursor appended to it
+ * lands as a row in somebody's export. The same note records why the value is
+ * **Z-suffixed** rather than isoformat — a bare `+00:00` in a query string
+ * decodes to a space, which made the second page a silent 400. This module
+ * therefore round-trips the header value VERBATIM into the next `?before=`
+ * and never re-formats it.
+ *
+ * Auth: the runtime's `credentials` / `defaultHeaders` are forwarded here, so
+ * a cookie-mode host works unchanged. The bearer-refresh and verification-403
+ * seams of `createStapelClient` do NOT run on this raw surface (the same v1
+ * limitation docs-react's raw transport documents); a 401 here throws like any
+ * other error status rather than triggering a refresh-and-retry.
+ */
+import { parseErrorEnvelope } from "@stapel/core";
+/**
+ * Response header carrying the keyset cursor for the NEXT export page.
+ * Absent (or empty) means this was the last page.
+ */
+export const FORMS_NEXT_BEFORE_HEADER = "X-Forms-Next-Before";
+/** Build the transport from the runtime options, dropping absent keys so
+ * `exactOptionalPropertyTypes` stays satisfied. */
+export function createExportTransport(baseUrl, options) {
+    return {
+        baseUrl,
+        ...(options.fetch !== undefined ? { fetch: options.fetch } : {}),
+        ...(options.credentials !== undefined
+            ? { credentials: options.credentials }
+            : {}),
+        ...(options.defaultHeaders !== undefined
+            ? { headers: options.defaultHeaders }
+            : {}),
+    };
+}
+function exportUrl(transport, formId, query) {
+    const base = transport.baseUrl.endsWith("/")
+        ? transport.baseUrl.slice(0, -1)
+        : transport.baseUrl;
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined)
+            search.set(key, String(value));
+    }
+    const qs = search.toString();
+    return (`${base}/forms/${encodeURIComponent(formId)}/submissions/export` +
+        (qs.length > 0 ? `?${qs}` : ""));
+}
+async function throwEnvelope(response) {
+    const text = await response.text();
+    let body = text.length > 0 ? text : undefined;
+    if (text.length > 0) {
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            /* a non-JSON error body stays the raw text */
+        }
+    }
+    throw parseErrorEnvelope(response.status, body);
+}
+/**
+ * Fetch one page of a form's CSV export.
+ *
+ * Drive it to completion by feeding {@link CsvExportPage.nextBefore} back in
+ * as `before` until it is `null`, concatenating the pages MINUS the repeated
+ * header row (see `useCsvExport`, which does exactly that).
+ */
+export async function exportSubmissionsCsv(transport, params) {
+    const fetchImpl = transport.fetch ?? globalThis.fetch.bind(globalThis);
+    const headers = new Headers({ Accept: "text/csv" });
+    if (transport.headers) {
+        for (const [key, value] of Object.entries(transport.headers)) {
+            if (!headers.has(key))
+                headers.set(key, value);
+        }
+    }
+    const init = { method: "GET", headers };
+    if (transport.credentials !== undefined)
+        init.credentials = transport.credentials;
+    if (params.signal)
+        init.signal = params.signal;
+    const response = await fetchImpl(exportUrl(transport, params.formId, {
+        workspace_id: params.workspaceId,
+        ...(params.before !== undefined ? { before: params.before } : {}),
+        ...(params.version !== undefined ? { version: params.version } : {}),
+    }), init);
+    if (!response.ok)
+        return throwEnvelope(response);
+    const raw = response.headers.get(FORMS_NEXT_BEFORE_HEADER);
+    return {
+        csv: await response.text(),
+        // An empty header is "no more pages", not a cursor of "".
+        nextBefore: raw !== null && raw.length > 0 ? raw : null,
+    };
+}
+/**
+ * Concatenate export pages into one CSV, keeping the header row exactly once.
+ *
+ * Every page the server streams carries its own header row (it is a standalone
+ * CSV file); pasting the pages verbatim would sprinkle header rows through the
+ * middle of the spreadsheet. Splitting on the first newline is safe here
+ * because a stapel-forms header row is a list of field slugs — slugs cannot
+ * contain a newline, so the first line is always exactly the header.
+ *
+ * Each retained chunk is newline-terminated before the join: a page whose last
+ * row has no trailing newline would otherwise be glued to the next page's
+ * first row, silently producing one corrupt record per page boundary.
+ */
+export function concatCsvPages(pages) {
+    const nonEmpty = pages.filter((page) => page.length > 0);
+    const first = nonEmpty[0];
+    if (first === undefined)
+        return "";
+    const chunks = [
+        first,
+        ...nonEmpty.slice(1).map((page) => {
+            const newline = page.indexOf("\n");
+            return newline === -1 ? "" : page.slice(newline + 1);
+        }),
+    ].filter((chunk) => chunk.length > 0);
+    return chunks
+        .map((chunk, index) => index === chunks.length - 1 || chunk.endsWith("\n") ? chunk : `${chunk}\n`)
+        .join("");
+}
+//# sourceMappingURL=export.js.map

package/dist/api/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../src/api/export.ts"],"names":[],"mappings":"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"}

package/dist/api/extensions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hand-authored API surface the codegen does not (yet) cover — browser-redirect
+ * URL builders, open-redirect guards, narrow domain type-guards, header
+ * conventions. Everything that CAN be derived from schema.json belongs in the
+ * generated operations (`api/formsApi.ts`), not here.
+ */
+export {};
+//# sourceMappingURL=extensions.d.ts.map

package/dist/api/extensions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.d.ts","sourceRoot":"","sources":["../../src/api/extensions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC"}