@qaflo/forms-client 1.0.0

package/form.js

@@ -0,0 +1,246 @@
+/**
+ * The whole contact form except its markup.
+ *
+ * This is the layer that exists because eight sites each hand-wrote the same
+ * two hundred lines around the same fetch: a state machine, a validator
+ * mirroring the service, the honeypot, the Turnstile plumbing, and
+ * focus-the-first-error. None of that differs between sites. All of the markup
+ * does, so none of it is here.
+ *
+ * Inputs are UNCONTROLLED and read by `name`, which is the design decision that
+ * makes integration cheap: a field needs a `name` attribute and nothing else —
+ * no `value`, no `onChange`, no state per input. Adding a question to a form is
+ * adding one `<input>`.
+ */
+
+import { useCallback, useMemo, useRef, useState } from 'react'
+
+import { DEFAULT_FIELDS, validateFields } from './validate.js'
+import { useTurnstile } from './turnstile.js'
+import { DEFAULT_ENDPOINT } from './submit.js'
+import { SECURITY_CHECK_PENDING } from './messages.js'
+
+/**
+ * Hidden from people, visible to bots. Styled away rather than `type="hidden"`:
+ * a bot reads the markup either way, but a password manager will not autofill a
+ * positioned-off-screen text input — and an autofilled honeypot is a real
+ * visitor's enquiry silently dropped.
+ */
+const HONEYPOT_STYLE = {
+  position: 'absolute',
+  left: '-9999px',
+  width: 1,
+  height: 1,
+  overflow: 'hidden',
+  opacity: 0,
+}
+
+/** Read every named input in the form, trimmed. */
+function readForm(form) {
+  const data = new FormData(form)
+  /** @type {Record<string, string>} */
+  const values = {}
+  data.forEach((value, key) => {
+    if (typeof value === 'string') values[key] = value.trim()
+  })
+  return values
+}
+
+/**
+ * What actually goes on the wire.
+ *
+ * Pure, and exported, because the shape of this object IS the contact between
+ * the form and the inbox. It regressed once already: reading every named input
+ * meant `intent`, `company` and the widget's own hidden field were sent as
+ * extra keys, and the service renders an unknown key as a labelled line — so
+ * every enquiry arrived saying everything twice.
+ *
+ * @param {Record<string, string>} values every named field, trimmed
+ * @param {{ message: string, subject?: any, honeypotName: string, exclude?: string[] }} options
+ */
+export function buildBody(values, { message, subject, honeypotName, exclude = [] }) {
+  /** @type {Record<string, unknown>} */
+  const body = { message }
+
+  // Every OTHER named field is sent as-is. The service stores it and renders it
+  // as a labelled line, so a new question on the form reaches the inbox with
+  // nothing else changed. `exclude` is for the fields that feed `compose` and
+  // would otherwise arrive twice.
+  for (const [key, value] of Object.entries(values)) {
+    if (key === 'message' || key === honeypotName) continue
+    // The widget's own hidden input. The token is added by the transport from
+    // the widget id, which is the only reading that is right when two forms
+    // share a page.
+    if (key === 'cf-turnstile-response') continue
+    if (exclude.includes(key)) continue
+    body[key] = value
+  }
+
+  if (subject) body.subject = typeof subject === 'function' ? subject(values) : subject
+  // The honeypot travels under the name the service reads.
+  body.honeypot = values[honeypotName] || ''
+  return body
+}
+
+/**
+ * @param {{ getToken: () => string, submit: (body: any) => Promise<any>, containerRef: any, ready: boolean }} widget
+ * @param {any} config
+ */
+export function useContactFormWith(widget, config = {}) {
+  const {
+    fields = DEFAULT_FIELDS,
+    messages,
+    compose,
+    subject,
+    honeypotName = 'website',
+    idPrefix = 'cf-',
+    exclude = [],
+    onSuccess,
+  } = config
+
+  const [state, setState] = useState(/** @type {'idle'|'sending'|'ok'|'error'} */ ('idle'))
+  const [errors, setErrors] = useState(/** @type {Record<string, string>} */ ({}))
+  // Nothing is marked invalid until the visitor has tried to send once. Nothing
+  // should scold you for a field you have not reached yet.
+  const [showErrors, setShowErrors] = useState(false)
+  const [error, setError] = useState('')
+  const [composed, setComposed] = useState('')
+  const lastValues = useRef(/** @type {Record<string, string>} */ ({}))
+
+  const fieldOrder = useMemo(() => Object.keys(fields), [fields])
+
+  const revalidate = useCallback(
+    (event) => {
+      // Only once errors are on screen: the message under a field then clears
+      // the moment it stops being true, rather than at the next submit.
+      if (!showErrors) return
+      setErrors(validateFields(readForm(event.currentTarget), fields, messages))
+    },
+    [showErrors, fields, messages],
+  )
+
+  const onSubmit = useCallback(
+    async (event) => {
+      event.preventDefault()
+      const form = event.currentTarget
+      const values = readForm(form)
+      lastValues.current = values
+
+      const found = validateFields(values, fields, messages)
+      setErrors(found)
+      if (Object.keys(found).length > 0) {
+        setShowErrors(true)
+        setState('idle')
+        setError('')
+        // "First error" means the first one down the page, not whichever key
+        // Object.keys happened to yield first.
+        const first = fieldOrder.find((f) => found[f])
+        const el = first ? form.querySelector(`#${idPrefix}${first}`) : null
+        if (el) {
+          el.focus()
+          el.scrollIntoView({ block: 'center', behavior: 'smooth' })
+        }
+        return
+      }
+
+      // A real person never fills a field they cannot see. Report success, so a
+      // bot learns nothing about why it failed.
+      if (values[honeypotName]) {
+        setState('ok')
+        return
+      }
+
+      // Before anything is composed or stored: an unsolved captcha is not a
+      // failure to fall back from, it is "press Submit again in a moment".
+      if (!widget.getToken()) {
+        setState('error')
+        setError(SECURITY_CHECK_PENDING)
+        return
+      }
+
+      const message = compose ? compose(values) : values.message
+      setComposed(message)
+      setState('sending')
+      setError('')
+
+      const body = buildBody(values, { message, subject, honeypotName, exclude })
+
+      const result = await widget.submit(body)
+
+      if (result.ok) {
+        setState('ok')
+        form.reset()
+        setErrors({})
+        setShowErrors(false)
+        if (onSuccess) onSuccess(values)
+        return
+      }
+      setState('error')
+      setError(result.message)
+    },
+    [fields, messages, compose, subject, honeypotName, idPrefix, exclude, onSuccess, widget, fieldOrder],
+  )
+
+  const invalid = useCallback((name) => (showErrors ? errors[name] : undefined), [showErrors, errors])
+
+  return {
+    /** Spread on the <form>. */
+    formProps: { onSubmit, onInput: revalidate, onChange: revalidate, noValidate: true },
+
+    /** Spread on an <input>/<textarea>/<select>. Your classes and labels stay yours. */
+    fieldProps: (name) => ({
+      id: `${idPrefix}${name}`,
+      name,
+      'aria-invalid': invalid(name) ? true : undefined,
+      'aria-describedby': invalid(name) ? `${idPrefix}${name}-error` : undefined,
+    }),
+
+    /** Spread on one <input>. That is the entire honeypot. */
+    honeypotProps: {
+      type: 'text',
+      name: honeypotName,
+      tabIndex: -1,
+      autoComplete: 'off',
+      'aria-hidden': true,
+      style: HONEYPOT_STYLE,
+    },
+
+    /** The id to put on your error element, so the field can point at it. */
+    errorId: (name) => `${idPrefix}${name}-error`,
+
+    containerRef: widget.containerRef,
+    ready: widget.ready,
+
+    errors: showErrors ? errors : {},
+    state,
+    error,
+    /** The composed message body, for a fallback that must not make them retype. */
+    composed,
+    values: lastValues.current,
+    reset: useCallback(() => {
+      setState('idle')
+      setError('')
+      setErrors({})
+      setShowErrors(false)
+    }, []),
+  }
+}
+
+/**
+ * The one-call form. Renders its own Turnstile widget.
+ *
+ * @param {any} clientConfig sitekey/action/endpoint, from createFormsClient
+ * @param {any} config the form's own shape
+ */
+export function useContactForm(clientConfig, config = {}) {
+  const widget = useTurnstile({
+    sitekey: clientConfig.sitekey,
+    action: clientConfig.action,
+    endpoint: clientConfig.endpoint || DEFAULT_ENDPOINT,
+    appearance: clientConfig.appearance,
+    theme: clientConfig.theme,
+    messages: clientConfig.messages,
+    fallbackEmail: clientConfig.fallbackEmail,
+  })
+  return useContactFormWith(widget, config)
+}

package/index.d.ts

@@ -0,0 +1,6 @@
+export * from './client'
+export * from './submit'
+export * from './turnstile'
+export * from './messages'
+export * from './form'
+export * from './validate'

package/index.js

@@ -0,0 +1,20 @@
+/**
+ * @qaflo/forms-client — the client half of the shared contact-form service.
+ *
+ * The service is qaflo/forms; its contract is documented in
+ * docs/FRONTEND-SNIPPET.md and enforced by internal/api/submit.go.
+ *
+ * `./submit` is the React-free entry point for a site that is not React.
+ */
+
+export { createFormsClient } from './client.js'
+export { submitTo, DEFAULT_ENDPOINT } from './submit.js'
+export { useTurnstile, loadTurnstile, honeypotStyle, TURNSTILE_SCRIPT } from './turnstile.js'
+export { useContactForm, useContactFormWith, buildBody } from './form.js'
+export { validateFields, SERVER_RULES, DEFAULT_FIELDS } from './validate.js'
+export {
+  messageForStatus,
+  DEFAULT_MESSAGES,
+  SECURITY_CHECK_PENDING,
+  NETWORK_ERROR,
+} from './messages.js'

package/messages.d.ts

@@ -0,0 +1,25 @@
+export type MessageOverrides = Record<string | number, string>
+
+export interface MessageOptions {
+  /** Override any entry by status, or `default`. Visitor-facing copy. */
+  messages?: MessageOverrides
+  /** Appends "Please email <address> while we fix it." to the default message. */
+  fallbackEmail?: string
+}
+
+export declare const DEFAULT_MESSAGES: {
+  400: string
+  403: string
+  413: string
+  429: string
+  default: string
+}
+
+export declare const SECURITY_CHECK_PENDING: string
+export declare const NETWORK_ERROR: string
+
+export declare function messageForStatus(
+  status: number,
+  serverError?: string,
+  options?: MessageOptions,
+): string

package/messages.js

@@ -0,0 +1,76 @@
+/**
+ * What a visitor is told, per status.
+ *
+ * Deliberately not one message. "Something went wrong" for every case is
+ * precisely what let the endpoint this service replaces return 500 for weeks
+ * without anyone realising the form was dead — every visitor saw the same
+ * banner whether they had mistyped an email or hit a dead mailbox.
+ *
+ * The 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 a change here is a BREAKING change: bump the major.
+ */
+
+/** Statuses the service actually returns. See ../../internal/api/submit.go. */
+
+// Only a 400 carries the server's own text, because that is the endpoint
+// naming a field ("message is required"), which the visitor can act on. Every
+// other status describes OUR problem, not theirs, so it gets our words.
+export const DEFAULT_MESSAGES = {
+  400: 'Please check the form and try again.',
+  403: 'We could not verify that you are human. Please reload the page and try again.',
+  // The service caps the body; a 413 is reachable with a long enough message,
+  // and "having trouble at our end" would be a lie about whose problem it is.
+  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.',
+  // 503, 415, and anything unexpected. NOT the visitor's fault, and worth
+  // saying so, so they reach us another way instead of retyping it.
+  default: 'Our contact form is having trouble at our end. Your message has not been sent.',
+}
+
+/**
+ * Shown when the widget has not produced a token yet.
+ *
+ * Turnstile is interaction-only, so most visitors never see it and get a token
+ * silently. Posting without one earns a 403 and a "we could not verify that you
+ * are human" pointing at a widget that is invisible — which reads as the form
+ * being broken. Say what is actually happening and make no call.
+ */
+export const SECURITY_CHECK_PENDING =
+  'The security check has not finished yet. Please wait a moment and press Submit again.'
+
+/** Shown when nothing came back at all — `fetch` only rejects for that. */
+export const NETWORK_ERROR =
+  'We could not reach the server. Please check your connection and try again.'
+
+/**
+ * Status → what the visitor reads.
+ *
+ * @param {number} status HTTP status, or 0 when the request never happened.
+ * @param {string} [serverError] The `error` field of the response body. Used
+ *   for 400 ONLY: that one is the endpoint naming a field.
+ * @param {{ messages?: Record<string|number, string>, fallbackEmail?: string }} [options]
+ *   `messages` overrides any entry by status, or `default`. `fallbackEmail`
+ *   appends the "please email us meanwhile" sentence to the default message —
+ *   the one site-specific token inside otherwise identical copy.
+ * @returns {string}
+ */
+export function messageForStatus(status, serverError, options = {}) {
+  const messages = { ...DEFAULT_MESSAGES, ...(options.messages || {}) }
+
+  if (status === 400) {
+    return serverError || messages[400]
+  }
+
+  const own = messages[status]
+  if (own) return own
+
+  const fallback = messages.default
+  // Only appended to the UNCHANGED default. A site that supplied its own
+  // wording has already said what it wants; bolting a sentence onto the end of
+  // it would be the package overruling the site.
+  if (options.fallbackEmail && fallback === DEFAULT_MESSAGES.default) {
+    return `${fallback} Please email ${options.fallbackEmail} while we fix it.`
+  }
+  return fallback
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@qaflo/forms-client",
+  "version": "1.0.0",
+  "description": "Client half of the shared qaflo contact-form service: transport, Turnstile lifecycle and visitor-facing status messages.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./submit": {
+      "types": "./submit.d.ts",
+      "default": "./submit.js"
+    },
+    "./messages": {
+      "types": "./messages.d.ts",
+      "default": "./messages.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "react": "^18.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/qaflo/forms.git",
+    "directory": "clients/js"
+  },
+  "keywords": [
+    "contact-form",
+    "turnstile"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/submit.d.ts

@@ -0,0 +1,21 @@
+import type { MessageOptions } from './messages'
+
+/** `status` is 0 when the request never reached the server. */
+export type SubmitResult = { ok: true } | { ok: false; status: number; message: string }
+
+export type SubmitBody = Record<string, unknown>
+
+export interface SubmitOptions extends MessageOptions {
+  /** Captcha token. Falls back to `captcha_token` in the body. */
+  token?: string
+  fetch?: typeof fetch
+  signal?: AbortSignal
+}
+
+export declare const DEFAULT_ENDPOINT: string
+
+export declare function submitTo(
+  endpoint: string,
+  body: SubmitBody,
+  options?: SubmitOptions,
+): Promise<SubmitResult>

package/submit.js

@@ -0,0 +1,118 @@
+/**
+ * The transport. No React, no DOM beyond `fetch` — a plain <script> site, a Vue
+ * site or a Node test can use this half on its own.
+ */
+
+import { messageForStatus, NETWORK_ERROR, SECURITY_CHECK_PENDING } from './messages.js'
+
+/** The one endpoint, for all thirty sites. */
+export const DEFAULT_ENDPOINT = 'https://forms.qaflo.com/v1/submit'
+
+/**
+ * Keys the service reads as the captcha token, in the order it reads them.
+ * See ../../internal/api/validate.go — `parseForm` takes the first non-empty.
+ */
+const TOKEN_KEYS = ['captcha_token', 'cf-turnstile-response', 'altcha']
+
+/**
+ * POST one submission.
+ *
+ * It does NOT throw for anything the server says. A caller who forgets a `try`
+ * must not lose the lead to an unhandled rejection — the whole point of this
+ * service is that an enquiry survives our mistakes. It throws only for a
+ * programming error: no endpoint, or a body that is not an object.
+ *
+ * The body is passed through UNTOUCHED apart from the token. In particular `to`,
+ * `from`, `recipient`, `cc` and `bcc` are sent exactly as given. The service
+ * stores them as ordinary unknown fields and decides the recipient from the
+ * verified Origin header, so an attempted relay shows up as a labelled line in
+ * the operator's inbox instead of happening. Sanitising them here would put a
+ * second claimant on a rule the server already owns, and one of the two would
+ * eventually be wrong.
+ *
+ * @param {string} endpoint
+ * @param {Record<string, unknown>} body
+ * @param {{ token?: string, messages?: Record<string|number, string>, fallbackEmail?: string, fetch?: typeof fetch, signal?: AbortSignal }} [options]
+ * @returns {Promise<{ ok: true } | { ok: false, status: number, message: string }>}
+ */
+export async function submitTo(endpoint, body, options = {}) {
+  if (typeof endpoint !== 'string' || endpoint === '') {
+    throw new TypeError('submitTo: endpoint is required')
+  }
+  if (body === null || typeof body !== 'object') {
+    throw new TypeError('submitTo: body must be an object')
+  }
+
+  const token = resolveToken(body, options.token)
+  if (!token) {
+    // Refused before any network call, and WITHOUT resetting anything: the
+    // widget is most likely still solving, and resetting it here would discard
+    // the solve in flight, so "press Submit again" would never start working.
+    return { ok: false, status: 0, message: SECURITY_CHECK_PENDING }
+  }
+
+  const doFetch = options.fetch || globalThis.fetch
+  if (typeof doFetch !== 'function') {
+    throw new TypeError('submitTo: no fetch available; pass options.fetch')
+  }
+
+  let response
+  try {
+    response = await doFetch(endpoint, {
+      method: 'POST',
+      // application/json is what the service requires, and it is also what
+      // makes the browser preflight — which is what makes the Origin header
+      // non-optional, which is what decides where the mail goes. No
+      // Authorization header: this endpoint is not gated by a shared secret.
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ...body, captcha_token: token }),
+      signal: options.signal,
+    })
+  } catch {
+    // fetch rejects only when nothing came back at all.
+    return { ok: false, status: 0, message: NETWORK_ERROR }
+  }
+
+  // 202 is the only success. It means "we have stored your message", not "we
+  // managed to email it" — the service writes the lead down before it tries to
+  // send, which is the distinction the outage this replaces turned on.
+  if (response.status === 202) {
+    return { ok: true }
+  }
+
+  const payload = await readJSON(response)
+  return {
+    ok: false,
+    status: response.status,
+    message: messageForStatus(response.status, payload.error, options),
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} body
+ * @param {string} [explicit]
+ * @returns {string}
+ */
+function resolveToken(body, explicit) {
+  if (typeof explicit === 'string' && explicit.trim() !== '') return explicit.trim()
+  for (const key of TOKEN_KEYS) {
+    const value = body[key]
+    if (typeof value === 'string' && value.trim() !== '') return value.trim()
+  }
+  return ''
+}
+
+/**
+ * @param {{ json: () => Promise<unknown> }} response
+ * @returns {Promise<{ error?: string }>}
+ */
+async function readJSON(response) {
+  try {
+    const parsed = await response.json()
+    if (parsed && typeof parsed === 'object') return /** @type {{ error?: string }} */ (parsed)
+  } catch {
+    // An HTML error page from something in front of the service, or an empty
+    // body. The status still tells the visitor what happened.
+  }
+  return {}
+}

package/turnstile.d.ts

@@ -0,0 +1,38 @@
+import type { CSSProperties, Ref } from 'react'
+import type { MessageOptions } from './messages'
+import type { SubmitBody, SubmitResult } from './submit'
+
+export interface TurnstileConfig extends MessageOptions {
+  sitekey: string
+  /** MUST equal the site's `site_key` in the forms registry. */
+  action: string
+  endpoint?: string
+  appearance?: string
+  theme?: string
+}
+
+export interface TurnstileWidgetProps {
+  ref: Ref<any>
+  className: string
+  'data-sitekey': string
+  'data-action': string
+  'data-appearance': string
+}
+
+export interface TurnstileHandle {
+  /** Attach to the element the widget renders into. */
+  containerRef: { current: any }
+  /** Ready-made props for a site that does not own its widget markup. */
+  widgetProps: TurnstileWidgetProps
+  /** This widget's token, or `''` if it has not solved yet. */
+  getToken: () => string
+  reset: () => void
+  /** Reads the token, refuses without one, posts, then resets this widget. */
+  submit: (body: SubmitBody) => Promise<SubmitResult>
+  ready: boolean
+}
+
+export declare const TURNSTILE_SCRIPT: string
+export declare const honeypotStyle: CSSProperties
+export declare function loadTurnstile(): Promise<any>
+export declare function useTurnstile(config: TurnstileConfig): TurnstileHandle