@qaflo/forms-client 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ishaq Sahibole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# @qaflo/forms-client
+
+The client half of the shared qaflo contact-form service. It owns the parts that
+are identical on every site and easy to get subtly wrong — the endpoint, the
+Turnstile lifecycle, the `action`/sitekey pairing, the empty-token guard, and
+what a visitor is told for each status. It owns no markup.
+
+> **Status: BUILT.** Written 2026-09-19 against the service at
+> `internal/api/submit.go`. Not yet published; qaflo.com is the pilot.
+>
+> **Sources:** ../../internal/api/submit.go, ../../internal/api/validate.go,
+> ../../docs/FRONTEND-SNIPPET.md, ../../docs/CLIENT-PACKAGE-PLAN.md
+
+**Nothing here is a security control.** The server decides the recipient from the
+verified `Origin` header, verifies the captcha against Cloudflare, and applies
+the rate limits. Every check in this package is duplicated server-side, because a
+browser can always be bypassed.
+
+## Install
+
+```sh
+yarn add @qaflo/forms-client
+```
+
+React is an optional peer dependency (`^16.8 || ^17 || ^18 || ^19`), needed only
+for `useTurnstile`. A site that is not React imports `@qaflo/forms-client/submit`
+instead and gets no React in its bundle.
+
+## A complete working example
+
+This is a whole contact form. There is no other file.
+
+```jsx
+import React from 'react'
+import { createFormsClient } from '@qaflo/forms-client'
+
+// The only per-site values. `action` MUST equal this site's `site_key` in the
+// forms registry: the service compares it with the action Cloudflare reports,
+// so a mismatch is a 403 on every submit even with a perfectly good token. The
+// sitekey is public by design — it identifies the widget and authorises nothing.
+const forms = createFormsClient({
+  action: 'newsite',
+  sitekey: '0xYOUR_SITE_KEY',
+  fallbackEmail: 'info@newsite.com',
+})
+
+export default function ContactForm() {
+  const { formProps, fieldProps, honeypotProps, containerRef, errors, state, error, reset } =
+    forms.useContactForm()
+
+  if (state === 'ok') {
+    return (
+      <div>
+        <p>Thanks — we have your message and will reply shortly.</p>
+        <button onClick={reset}>Send another</button>
+      </div>
+    )
+  }
+
+  return (
+    <form {...formProps}>
+      <input {...fieldProps('name')} placeholder="Your name" />
+      {errors.name && <p>{errors.name}</p>}
+
+      <input {...fieldProps('email')} type="email" placeholder="Email" />
+      {errors.email && <p>{errors.email}</p>}
+
+      <input {...fieldProps('phone')} type="tel" placeholder="Phone" />
+
+      <textarea {...fieldProps('message')} placeholder="How can we help?" />
+      {errors.message && <p>{errors.message}</p>}
+
+      <input {...honeypotProps} />
+      <div ref={containerRef} />
+
+      <button type="submit" disabled={state === 'sending'}>
+        {state === 'sending' ? 'Sending…' : 'Send'}
+      </button>
+
+      {state === 'error' && <p role="status">{error}</p>}
+    </form>
+  )
+}
+```
+
+That form already has: validation matching the service's own rules, errors that
+appear only after the first submit and clear as you type, focus jumping to the
+first bad field, a honeypot, the Turnstile lifecycle, the single-use token
+reset, and a different sentence for every failure the service can return.
+
+**Fields are uncontrolled and read by `name`.** That is the decision that makes
+this cheap: an input needs a `name` and nothing else — no `value`, no
+`onChange`, no state per field. Adding a question to the form is adding one
+`<input>`, and it arrives in the notification as a labelled line without the
+client being touched.
+
+### Making it yours
+
+Everything below is optional.
+
+```jsx
+const { formProps, fieldProps, errors, composed } = forms.useContactForm({
+  // Defaults to name, email, phone and message with the service's own limits.
+  fields: {
+    name: { required: true, min: 2, max: 100 },
+    email: { required: true, email: true, max: 254 },
+    phone: { required: true, min: 5, max: 32 },   // optional to the service
+    message: { required: true, min: 10, max: 5000 },
+  },
+
+  // The rules are the service's. The voice is yours.
+  messages: {
+    name: { required: 'Please tell us your name.' },
+    message: {
+      min: ({ value, limit }) => `${limit - value.length} more characters, please.`,
+    },
+  },
+
+  // Fold extra questions into the message body instead of sending them as
+  // their own lines.
+  compose: (v) => `Enquiry type: ${v.intent}\n\n${v.message}`,
+  exclude: ['intent'],          // ...and then do not ALSO send them
+  subject: (v) => `${v.intent} — ${v.name}`,
+})
+```
+
+`composed` gives you back the body that was sent, which is what a "send this on
+WhatsApp instead" fallback needs so a failure never makes anyone retype.
+
+## Not React?
+
+`useContactForm` is the easy path for a React site. Under it are two layers you
+can drop to, and neither imports React:
+
+```js
+import { submitTo } from '@qaflo/forms-client/submit'
+
+const result = await submitTo('https://forms.qaflo.com/v1/submit', body, { token })
+```
+
+## API
+
+### `createFormsClient(config)`
+
+| Option | Default | |
+|---|---|---|
+| `action` | — | **Required.** Must equal the site's `site_key` in the registry. |
+| `sitekey` | — | **Required.** The public Turnstile sitekey. |
+| `endpoint` | `https://forms.qaflo.com/v1/submit` | |
+| `appearance` | `interaction-only` | Passed to `turnstile.render`. |
+| `theme` | Turnstile's default | |
+| `messages` | see below | Override any status's wording, or `default`. |
+| `fallbackEmail` | — | Appends "Please email … while we fix it." to the default message. |
+
+Throws `TypeError` if `action` or `sitekey` is missing. Those are programming
+errors that otherwise fail silently — in an inbox that never fills.
+
+### `forms.useContactForm(config)`
+
+The whole form except its markup. Returns `formProps`, `fieldProps(name)`,
+`honeypotProps`, `errorId(name)`, `containerRef`, `errors`, `state`, `error`,
+`composed`, `values`, `ready` and `reset()`.
+
+| Option | Default | |
+|---|---|---|
+| `fields` | name, email, phone, message | Per-field rules, in focus order. `true` means "whatever the service applies to a field of this name". |
+| `messages` | plain English | Per-field wording. A function receives `{ value, limit, label, field }`. |
+| `compose` | `values.message` | Build the message body from every named field. |
+| `subject` | none | String, or computed from the values. |
+| `exclude` | `[]` | Fields that feed `compose` and must not also be sent on their own. |
+| `honeypotName` | `website` | The service reads `website` or `honeypot`. |
+| `idPrefix` | `cf-` | Must match your `<label htmlFor>`. |
+| `onSuccess` | none | Called with the submitted values. |
+
+Validation rules mirror `internal/api/validate.go`. **The server stays the
+authority** — this exists so nothing it would reject costs a round trip, because
+a rejection there arrives as one banner with no field named.
+
+### `forms.useTurnstile()`
+
+Renders one widget **explicitly**, with its own widget id.
+
+```js
+const { containerRef, widgetProps, getToken, reset, submit, ready } = forms.useTurnstile()
+```
+
+- `containerRef` — attach to the element the widget renders into.
+- `widgetProps` — spread on an empty `<div />` instead, if you would rather not
+  write the attributes yourself.
+- `getToken()` — this widget's token, or `''` if it has not solved yet.
+- `reset()` — scoped to this widget. Tokens are single-use and expire in five
+  minutes.
+- `submit(body)` — reads the token, refuses without one, posts, then resets.
+- `ready` — true once the widget has rendered.
+
+Explicit rendering rather than `class="cf-turnstile"` scanning, for two reasons
+this codebase has already met: the script never rescans after a client-side
+navigation, so a form reached by clicking a link gets no widget at all; and two
+forms on one page share an argument-less `turnstile.reset()`, so submitting one
+blanks the other's token. royalshadescurtains renders a form in its footer *and*
+on its contact page.
+
+Everything that touches `window` is inside an effect — these are Gatsby sites
+and they server-render the component.
+
+### `submitTo(endpoint, body, options)` — the React-free transport
+
+```js
+import { submitTo } from '@qaflo/forms-client/submit'
+
+const result = await submitTo('https://forms.qaflo.com/v1/submit', body, { token })
+```
+
+Returns `{ ok: true }`, or `{ ok: false, status, message }`. `status` is `0` when
+the request never reached the server — an unsolved captcha or a dead connection,
+told apart by the message.
+
+**It does not throw for anything the server says.** A caller who forgets a `try`
+must not lose the lead to an unhandled rejection. It throws only for a
+programming error: no endpoint, a body that is not an object, or no `fetch`.
+
+The body is passed through **untouched** apart from the token. `to`, `from`,
+`recipient`, `cc` and `bcc` are sent exactly as given: the service stores them as
+ordinary unknown fields and routes on the verified `Origin`, so an attempted
+relay shows up as a labelled line in the operator's inbox instead of happening.
+The client does not sanitise them, because then two places would claim to own
+that rule and one of them would eventually be wrong.
+
+### `messageForStatus(status, serverError, options)`
+
+| Status | What the visitor reads |
+|---|---|
+| `400` | the server's own `error` — it names the field at fault |
+| `403` | We could not verify that you are human. Please reload the page and try again. |
+| `413` | That message is too long. Please shorten it and try again. |
+| `429` | Too many messages have been sent from here recently. Please try again in an hour. |
+| anything else | Our contact form is having trouble at our end. Your message has not been sent. |
+| `0` | the security check has not finished, or the server could not be reached |
+
+Only `400` shows the server's text. The rest describe our problems, not the
+visitor's — the service says "temporarily unavailable" and "captcha check
+failed", and neither is for a visitor to read.
+
+This wording is lifted verbatim from the eight sites that were cut over by hand,
+which had already converged on it word-for-word. **It is visitor-facing copy, so
+changing any of it is a breaking change** — bump the major version.
+
+## Tests
+
+```sh
+npm test
+```
+
+No bundler and no test framework: plain ESM and `node --test`. The suite covers
+the status mapping, the empty-token refusal, and that a body-supplied `to`
+survives untouched. Nothing in it touches the network.
+
+## What this package cannot do
+
+It does **not** propagate a fix to the live sites. Each pins a version and has to
+be rebuilt to pick one up, so "one place to fix a bug" only pays off if somebody
+bumps and redeploys. The reliable wins are narrower: a new site takes minutes
+instead of half an hour, and it cannot drift on the day it ships.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

package/client.d.ts

@@ -0,0 +1,27 @@
+import type { MessageOptions } from './messages'
+import type { SubmitBody, SubmitOptions, SubmitResult } from './submit'
+import type { TurnstileHandle } from './turnstile'
+import type { ContactFormConfig, ContactFormHandle } from './form'
+
+export interface FormsClientConfig extends MessageOptions {
+  /** MUST equal the site's `site_key` in the forms registry. */
+  action: string
+  /** Public by design: it identifies the widget, it authorises nothing. */
+  sitekey: string
+  /** Defaults to https://forms.qaflo.com/v1/submit */
+  endpoint?: string
+  appearance?: string
+  theme?: string
+}
+
+export interface FormsClient {
+  readonly endpoint: string
+  readonly action: string
+  readonly sitekey: string
+  submit(body: SubmitBody, options?: SubmitOptions): Promise<SubmitResult>
+  messageForStatus(status: number, serverError?: string): string
+  useContactForm(config?: ContactFormConfig): ContactFormHandle
+  useTurnstile(): TurnstileHandle
+}
+
+export declare function createFormsClient(config: FormsClientConfig): FormsClient

package/client.js

@@ -0,0 +1,89 @@
+/**
+ * Ties the three halves together for one site.
+ *
+ * Headless on purpose. A shared <ContactForm /> would have to accept every
+ * site's fields, labels, classes and fallbacks as props and would end up harder
+ * to use than the copy it replaced. So this owns the part that is identical
+ * everywhere and easy to get subtly wrong — the endpoint, the Turnstile
+ * lifecycle, the action/sitekey pairing, the empty-token guard, the status
+ * mapping — and owns none of the markup.
+ *
+ * Nothing here is a security control. The server decides the recipient from the
+ * verified Origin header, verifies the captcha against Cloudflare and applies
+ * the rate limits. This package is a convenience; a browser can always be
+ * bypassed, and every check in it is duplicated server-side.
+ */
+
+import { messageForStatus } from './messages.js'
+import { submitTo, DEFAULT_ENDPOINT } from './submit.js'
+import { useTurnstile } from './turnstile.js'
+import { useContactForm } from './form.js'
+
+/**
+ * @param {{
+ *   action: string,
+ *   sitekey: string,
+ *   endpoint?: string,
+ *   appearance?: string,
+ *   theme?: string,
+ *   messages?: Record<string|number, string>,
+ *   fallbackEmail?: string,
+ * }} config
+ */
+export function createFormsClient(config) {
+  // A programming error, and the expensive kind: the widget renders, the visitor
+  // solves it, and every submit is a 403 because the action does not match the
+  // registry row. Fail at import instead of in the inbox that never fills.
+  if (!config || typeof config.action !== 'string' || config.action === '') {
+    throw new TypeError('createFormsClient: action is required and must equal the site_key in the forms registry')
+  }
+  if (typeof config.sitekey !== 'string' || config.sitekey === '') {
+    throw new TypeError('createFormsClient: sitekey is required')
+  }
+
+  const endpoint = config.endpoint || DEFAULT_ENDPOINT
+  const shared = { messages: config.messages, fallbackEmail: config.fallbackEmail }
+
+  return {
+    endpoint,
+    action: config.action,
+    sitekey: config.sitekey,
+
+    /**
+     * Post a body. The token comes from `options.token`, or from
+     * `captcha_token` / `cf-turnstile-response` / `altcha` in the body itself.
+     * Resets nothing — it owns no widget; use the hook's `submit` for that.
+     *
+     * @param {Record<string, unknown>} body
+     * @param {{ token?: string, fetch?: typeof fetch, signal?: AbortSignal }} [options]
+     */
+    submit(body, options = {}) {
+      return submitTo(endpoint, body, { ...shared, ...options })
+    },
+
+    /** @param {string} [serverError] */
+    messageForStatus(status, serverError) {
+      return messageForStatus(status, serverError, shared)
+    },
+
+    /**
+     * The whole form except its markup: validation, state, honeypot, Turnstile
+     * and submit. A site writes `<form {...formProps}>` and its own fields.
+     */
+    useContactForm(form = {}) {
+      return useContactForm({ ...config, endpoint }, form)
+    },
+
+    /** The widget on its own, for a form that wants to drive its own submit. */
+    useTurnstile() {
+      return useTurnstile({
+        sitekey: config.sitekey,
+        action: config.action,
+        endpoint,
+        appearance: config.appearance,
+        theme: config.theme,
+        ...shared,
+      })
+    },
+  }
+}

package/form.d.ts

@@ -0,0 +1,83 @@
+import type { CSSProperties, FormEvent } from 'react'
+import type { FieldSpec, MessageSpec } from './validate'
+import type { SubmitBody, SubmitResult } from './submit'
+
+export interface ContactFormConfig {
+  /** Defaults to name, email, phone and message with the service's own rules. */
+  fields?: FieldSpec
+  messages?: MessageSpec
+  /** Build the message body from every named field. Defaults to `values.message`. */
+  compose?: (values: Record<string, string>) => string
+  subject?: string | ((values: Record<string, string>) => string)
+  /** The hidden field's name. The service accepts `website` or `honeypot`. */
+  honeypotName?: string
+  /** Prefix for generated ids; must match what your <label htmlFor> uses. */
+  idPrefix?: string
+  /**
+   * Fields that feed `compose` and must NOT also be sent on their own.
+   * Without this they arrive twice: inside the message body, and again as a
+   * labelled line in the notification.
+   */
+  exclude?: string[]
+  onSuccess?: (values: Record<string, string>) => void
+}
+
+export interface ContactFormHandle {
+  formProps: {
+    onSubmit: (e: FormEvent<HTMLFormElement>) => void
+    onInput: (e: FormEvent<HTMLFormElement>) => void
+    onChange: (e: FormEvent<HTMLFormElement>) => void
+    noValidate: true
+  }
+  fieldProps: (name: string) => {
+    id: string
+    name: string
+    'aria-invalid': true | undefined
+    'aria-describedby': string | undefined
+  }
+  honeypotProps: {
+    type: string
+    name: string
+    tabIndex: number
+    autoComplete: string
+    'aria-hidden': true
+    style: CSSProperties
+  }
+  errorId: (name: string) => string
+  containerRef: { current: any }
+  ready: boolean
+  /** Empty until the visitor has tried to send once. */
+  errors: Record<string, string>
+  state: 'idle' | 'sending' | 'ok' | 'error'
+  /** The banner message when `state` is 'error'. */
+  error: string
+  /** The composed body, for a fallback that must not make them retype. */
+  composed: string
+  values: Record<string, string>
+  reset: () => void
+}
+
+export declare function useContactForm(
+  clientConfig: { sitekey: string; action: string; endpoint?: string; [k: string]: any },
+  config?: ContactFormConfig,
+): ContactFormHandle
+
+export declare function useContactFormWith(
+  widget: {
+    getToken: () => string
+    submit: (body: SubmitBody) => Promise<SubmitResult>
+    containerRef: { current: any }
+    ready: boolean
+  },
+  config?: ContactFormConfig,
+): ContactFormHandle
+
+export declare function buildBody(
+  values: Record<string, string>,
+  options: {
+    message: string
+    subject?: string | ((values: Record<string, string>) => string)
+    honeypotName: string
+    exclude?: string[]
+  },
+): Record<string, unknown>