@duffcloudservices/site-forms 0.5.0 → 0.7.0

package/src/__tests__/submission.test.ts

@@ -4,6 +4,17 @@ import DcsForm from '../DcsForm.vue'
 import { submitFormValues } from '../composables/useFormSubmission'
 import type { PortalFormDefinition } from '../types'
 
+// The REAL managed-form success shape (PublicSiteFormSubmissionResponse,
+// types.gen.ts:14845 / public_site_forms.go:509). C-310 requires a genuine
+// receipt before any success state, so these doubles must answer with one —
+// they previously returned invented shapes ({leadId}, {status:'ok'}) that the
+// server cannot produce.
+const MANAGED_FORM_RECEIPT = {
+  id: '07438812886145977836-dd5a5baf3835082c',
+  status: 'accepted',
+  submittedAt: '2026-07-26T14:52:30Z',
+}
+
 const def: PortalFormDefinition = {
   formId: 'contact',
   submission: { kind: 'lead' },
@@ -19,7 +30,7 @@ describe('submission happy path', () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
       status: 200,
-      json: async () => ({ leadId: 'L-1' }),
+      json: async () => MANAGED_FORM_RECEIPT,
     })
     const originalFetch = globalThis.fetch
     ;(globalThis as unknown as { fetch: typeof fetch }).fetch =
@@ -42,8 +53,14 @@ describe('submission happy path', () => {
     await wrapper.find('form').trigger('submit')
     await flushPromises()
 
-    expect(fetchMock).toHaveBeenCalledTimes(1)
-    const [url, init] = fetchMock.mock.calls[0]
+    // Exactly one SUBMISSION. Filtered to POST because the mount also issues the
+    // C-415 form-compliance GET; asserting on total fetch calls would conflate
+    // "the form submitted twice" with "the form read its PHI posture".
+    const posts = fetchMock.mock.calls.filter(
+      ([, init]) => (init as RequestInit | undefined)?.method === 'POST',
+    )
+    expect(posts).toHaveLength(1)
+    const [url, init] = posts[0]
     expect(url).toBe('https://api.example.com/sites/kept/forms/contact/submissions')
     expect((init as RequestInit).method).toBe('POST')
     expect(((init as RequestInit).headers as Record<string, string>)['Content-Type']).toBe(
@@ -79,7 +96,7 @@ describe('submission happy path', () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
       status: 202,
-      json: async () => ({ status: 'ok' }),
+      json: async () => MANAGED_FORM_RECEIPT,
     })
 
     await submitFormValues({
@@ -103,7 +120,7 @@ describe('submission happy path', () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
       status: 202,
-      json: async () => ({ status: 'ok' }),
+      json: async () => MANAGED_FORM_RECEIPT,
     })
     const file = new File(['hello'], 'estimate.txt', { type: 'text/plain' })
 
@@ -141,7 +158,7 @@ describe('submission happy path', () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
       status: 202,
-      json: async () => ({ status: 'ok' }),
+      json: async () => MANAGED_FORM_RECEIPT,
     })
     const photo1 = new File(['one'], 'one.jpg', { type: 'image/jpeg' })
     const photo2 = new File(['two'], 'two.png', { type: 'image/png' })

package/src/__tests__/visible-if.test.ts

@@ -27,12 +27,21 @@ const def: PortalFormDefinition = {
   ],
 }
 
+// C-310: a success state now requires the endpoint's real receipt
+// (PublicSiteFormSubmissionResponse, types.gen.ts:14845), so these doubles must
+// answer with one rather than an arbitrary object.
+const MANAGED_FORM_RECEIPT = {
+  id: '07438812886145977836-dd5a5baf3835082c',
+  status: 'accepted',
+  submittedAt: '2026-07-26T14:52:30Z',
+}
+
 describe('visibleIf', () => {
   it('skips validation and submission for hidden gated fields', async () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
       status: 200,
-      json: async () => ({ id: '1' }),
+      json: async () => MANAGED_FORM_RECEIPT,
     })
     // Stub global fetch
     const originalFetch = globalThis.fetch
@@ -56,8 +65,12 @@ describe('visibleIf', () => {
     await wrapper.find('form').trigger('submit')
     await flushPromises()
 
-    expect(fetchMock).toHaveBeenCalledTimes(1)
-    const [, init] = fetchMock.mock.calls[0]
+    // POST-filtered: the mount also issues the C-415 form-compliance GET.
+    const posts = fetchMock.mock.calls.filter(
+      ([, init]) => (init as RequestInit | undefined)?.method === 'POST',
+    )
+    expect(posts).toHaveLength(1)
+    const [, init] = posts[0]
     const body = JSON.parse((init as RequestInit).body as string)
     expect(body.values).toEqual({ kind: 'a' })
     expect('detail' in body.values).toBe(false)
@@ -69,7 +82,7 @@ describe('visibleIf', () => {
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
       status: 200,
-      json: async () => ({}),
+      json: async () => MANAGED_FORM_RECEIPT,
     })
     const originalFetch = globalThis.fetch
     ;(globalThis as unknown as { fetch: typeof fetch }).fetch =

package/src/composables/readExpectedJson.ts

@@ -0,0 +1,360 @@
+/**
+ * CANONICAL receipt primitive for DCS form-submission clients (C-310).
+ *
+ * This module is the single definition of "did the submission actually get
+ * stored?" for the whole fleet. Site-local copies (lamphere's
+ * `theme/lib/readOkBody.ts`, iron-oak's `src/lib/submissionResponse.ts`, and the
+ * first-party `web/`+`portal/` helpers) are BACKPORTS of this file and say so in
+ * their headers. Change the contract here first.
+ *
+ * ── Two layers, deliberately separate ──────────────────────────────────────
+ *
+ * `readOkBody(response)` is TRANSPORT validation: did a DCS API answer at all?
+ * `readExpectedJson(response, validator)` adds RECEIPT validation: does the
+ * body it answered with actually prove a row exists?
+ *
+ * Transport validation alone is not enough (Codex cross-model review §c,
+ * 2026-07-26). Before C-310 any syntactically valid JSON passed — `{}`, `[]`,
+ * `"ok"`, `{"hello":"world"}` — so a 2xx from anything that speaks JSON was
+ * reported to the visitor as a stored lead. The endpoints all return a real
+ * receipt; requiring one is cheap and materially stronger.
+ *
+ * ── Why 204 is NOT exempt any more (C-310, was the last hole) ──────────────
+ *
+ * C-301/C-302 trusted an empty body when the STATUS asserted the emptiness
+ * (`204 No Content`). That was defensible in the abstract and wrong in fact:
+ * `204` proves only that *the responder* deliberately sent no content. It does
+ * not prove the DCS API ran, and every guarded endpoint returns a JSON receipt:
+ *
+ *   - managed forms          `202` + `PublicSiteFormSubmissionResponse`
+ *                            (server/internal/handlers/public_site_forms.go)
+ *   - site contact           `201` + `ContactFormResponse`
+ *                            (server/internal/handlers/contact_form.go)
+ *   - estimate creation      `201` + estimate JSON
+ *                            (server/internal/handlers/revenue_estimate_visitor.go)
+ *   - passwordless verify    `200` + `{success, redirectTo}`
+ *                            (server/internal/handlers/site_auth_multi.go:401)
+ *   - booking cancellation   `200` + `CancelBookingResponse`
+ *                            (server/internal/handlers/revenue_public.go:2134)
+ *
+ * No guarded operation needs `204`. Keeping the exemption meant a bodyless 204
+ * from a proxy, a CDN, or a CORS-mangled hop still read as "sent". Removed. If a
+ * future endpoint genuinely contracts `204`, add it back for that endpoint only,
+ * with its own predicate — not as a blanket transport exemption.
+ *
+ * ── Failures are TERMINAL ──────────────────────────────────────────────────
+ *
+ * Every throw here means "we cannot confirm this was stored", which is NOT the
+ * same as "this was not stored". Callers must surface it as a visible failure
+ * and must never retry: if the request *did* reach the API, a retry double-stores
+ * the lead; if it did not, a retry cannot help. Wording shown to the visitor says
+ * "could not confirm", never "not received".
+ */
+
+/** A caller-supplied type predicate describing one endpoint's receipt. */
+export type ReceiptValidator<T> = (value: unknown) => value is T
+
+/**
+ * Error thrown when a submission cannot be confirmed. `receiptRejected`
+ * distinguishes the two causes, because they have different remedies:
+ *
+ * - `false` — transport failure. The body was not JSON at all (HTML shell,
+ *   proxy interstitial, empty body, unreadable stream). Check routing.
+ * - `true`  — the body WAS valid JSON but did not carry a receipt. Check that
+ *   the endpoint contract and the predicate still agree.
+ */
+export interface UnconfirmedSubmissionError extends Error {
+  receiptRejected?: boolean
+}
+
+/**
+ * Reads the body of an **ok** (2xx) submission response and refuses to treat a
+ * non-JSON body as a successful submission.
+ *
+ * Contract:
+ * - JSON body      -> parsed value
+ * - anything else  -> throws (empty, non-JSON content-type, unparseable,
+ *                     unreadable stream — including on `204`)
+ *
+ * @param label prefix for the console diagnostic, so a site copy can name itself.
+ */
+export async function readOkBody(res: Response, label = LOG_PREFIX): Promise<unknown> {
+  // Non-`Response` fetch implementations (older test doubles) may expose only
+  // `json()`. Preserve the historical behaviour for them rather than throwing on
+  // a shape this package never controlled. NOTE: this path used to be a silent
+  // success hole — a rejected `json()` became `null`. It no longer is, because
+  // `readExpectedJson` runs a receipt predicate over whatever comes back and
+  // `null` satisfies no receipt.
+  if (typeof res.text !== 'function') {
+    try {
+      return await res.json()
+    } catch {
+      return null
+    }
+  }
+
+  const contentType = readContentType(res)
+  // Read as text FIRST: a body can only be consumed once, so calling `json()`
+  // first would leave nothing to inspect when it fails.
+  let raw: string
+  try {
+    raw = (await res.text()).trim()
+  } catch (readError) {
+    // We never saw the body — never claim success from that.
+    throw unreadableBodyError(label, res.status, readError)
+  }
+
+  if (raw === '') {
+    // C-310: `204` used to be exempt here. It is not any more — see the header.
+    throw emptyBodyError(label, res.status)
+  }
+
+  if (contentType && !contentType.includes('json')) {
+    throw nonJsonBodyError(label, res.status, contentType, raw)
+  }
+  try {
+    return JSON.parse(raw)
+  } catch {
+    throw nonJsonBodyError(label, res.status, contentType, raw)
+  }
+}
+
+/**
+ * Reads an **ok** (2xx) response and requires it to carry the receipt the
+ * endpoint contracts. Throws an {@link UnconfirmedSubmissionError} otherwise.
+ *
+ * Zero dependencies and no schema library on purpose: `site-forms` is a leaf
+ * package that sites pin independently, so anything that adds a dependency is
+ * unshippable to exactly the sites that need the fix most.
+ */
+export async function readExpectedJson<T>(
+  res: Response,
+  validator: ReceiptValidator<T>,
+  options: { label?: string; receiptName?: string } = {},
+): Promise<T> {
+  const label = options.label ?? LOG_PREFIX
+  const body = await readOkBody(res, label)
+  if (validator(body)) return body
+  throw invalidReceiptError(label, res.status, options.receiptName ?? 'submission', body)
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Per-endpoint receipt predicates.
+//
+// One shared success contract across contact, estimate, authentication and
+// cancellation would be a fiction, so transport parsing is shared and the
+// receipt shape stays per-endpoint (Codex §a). Shapes are pinned to the REAL
+// generated contract types in contracts/generated/typescript/types.gen.ts —
+// deliberately re-declared here rather than imported, because customer sites
+// install this package from npm and do not have @dcs/contracts.
+// ───────────────────────────────────────────────────────────────────────────
+
+/**
+ * NO LEGACY SPAM-QUARANTINE EXEMPTION — removed by C-319, deliberately.
+ *
+ * C-310 widened both predicates below to accept a bare `{"status":"ok"}`,
+ * because two of the five spam-quarantine paths answered that instead of their
+ * endpoint's real receipt (C-307 held every quarantine response byte-identical
+ * to its pre-change self, and two of those shapes were already wrong). Without
+ * the widening, every quarantined submitter — including an AI false-positive
+ * victim whose message really was stored — would have seen a visible failure.
+ *
+ * C-319 removed the cause: all five quarantine paths now answer their route's
+ * GENUINE success receipt, built by the same writer the success path uses and
+ * populated from the row C-307 stores. So the widening is gone with it. A
+ * `{"status":"ok"}` body from any of these endpoints is now what it always
+ * looked like — a misroute — and must fail.
+ *
+ * ORDERING NOTE, because this package ships independently of the server: this
+ * removal is only safe while no DEPLOYED client carries these predicates.
+ * Verified at removal time — the predicates were introduced in 0.6.0 (C-310)
+ * and 0.6.0 has never been published (npm latest: 0.5.0), so every deployed
+ * site is on a version with no receipt validation at all. site-forms must not
+ * be published AHEAD of the server roll that carries C-319; both ride the same
+ * attended C-239 train.
+ */
+
+/** `PublicSiteFormSubmissionResponse` — types.gen.ts:14845. */
+export interface ManagedFormReceipt {
+  id?: string
+  status: string
+  submittedAt?: string
+  message?: string
+  contactMessageId?: string | null
+  notificationQueued?: boolean
+}
+
+const MANAGED_FORM_STATUSES = ['submitted', 'accepted', 'queued']
+
+export function isManagedFormReceipt(value: unknown): value is ManagedFormReceipt {
+  return (
+    isRecord(value) &&
+    isNonEmptyString(value['id']) &&
+    isOneOf(value['status'], MANAGED_FORM_STATUSES) &&
+    isTimestamp(value['submittedAt'])
+  )
+}
+
+/** `ContactFormResponse` — types.gen.ts:19831. */
+export interface SiteContactReceipt {
+  id?: string
+  status: string
+  submittedAt?: string
+  message?: string
+}
+
+const CONTACT_STATUSES = ['submitted', 'processing', 'responded']
+
+export function isSiteContactReceipt(value: unknown): value is SiteContactReceipt {
+  return (
+    isRecord(value) &&
+    isNonEmptyString(value['id']) &&
+    isOneOf(value['status'], CONTACT_STATUSES)
+  )
+}
+
+/**
+ * Visitor estimate creation — `201` + the mapped estimate row
+ * (revenue_estimate_visitor.go:1419 `mapSiteVisitorEstimateResponse`). The
+ * estimate honeypot's decoy is built by the same row constructor and answered
+ * by the same writer a genuine estimate uses (C-319), so it carries a real ULID
+ * `id` and passes — which is the point: the honeypot must stay
+ * indistinguishable from a genuine submission.
+ */
+export interface EstimateReceipt {
+  id: string
+  status?: string
+}
+
+export function isEstimateReceipt(value: unknown): value is EstimateReceipt {
+  return isRecord(value) && isNonEmptyString(value['id'])
+}
+
+/** `PasswordlessVerifyCodeResponse` — types.gen.ts:20780. */
+export interface PasswordlessVerifyReceipt {
+  success: true
+  redirectTo?: string
+}
+
+export function isPasswordlessVerifyReceipt(value: unknown): value is PasswordlessVerifyReceipt {
+  return isRecord(value) && value['success'] === true
+}
+
+/** `CancelBookingResponse` — types.gen.ts:21486. */
+export interface BookingCancellationReceipt {
+  success: true
+  refundAmountCents?: number | null
+  message?: string
+}
+
+export function isBookingCancellationReceipt(value: unknown): value is BookingCancellationReceipt {
+  return isRecord(value) && value['success'] === true
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Internals
+// ───────────────────────────────────────────────────────────────────────────
+
+const LOG_PREFIX = '[@duffcloudservices/site-forms]'
+
+/**
+ * The one honest sentence a visitor is shown for any unconfirmable 2xx. The
+ * technical diagnosis belongs in the console for whoever maintains the site —
+ * never on the page. "Could not confirm" is deliberate: a post-storage body
+ * failure means UNKNOWN, not "not stored".
+ */
+const VISITOR_UNCONFIRMED_MESSAGE =
+  'We could not confirm your message was received. Please try again, or contact us directly.'
+
+function readContentType(res: Response): string {
+  const get = res.headers?.get
+  if (typeof get !== 'function') return ''
+  return (res.headers.get('content-type') ?? '').toLowerCase()
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function isOneOf(value: unknown, allowed: string[]): boolean {
+  return typeof value === 'string' && allowed.includes(value)
+}
+
+function isTimestamp(value: unknown): boolean {
+  return isNonEmptyString(value) && Number.isFinite(Date.parse(value))
+}
+
+function unconfirmed(message: string, receiptRejected: boolean): UnconfirmedSubmissionError {
+  const err = new Error(message) as UnconfirmedSubmissionError
+  err.receiptRejected = receiptRejected
+  return err
+}
+
+function unreadableBodyError(label: string, status: number, cause: unknown): UnconfirmedSubmissionError {
+  const detail = cause instanceof Error ? cause.message : String(cause)
+  // eslint-disable-next-line no-console
+  console.error(
+    `${label} Submission could not be confirmed: the server answered ${status} but the response ` +
+      `body could not be read (${detail}). The submission may or may not have been stored, so it ` +
+      `is reported as a failure rather than risk telling the visitor it was sent.`,
+  )
+  return unconfirmed(VISITOR_UNCONFIRMED_MESSAGE, false)
+}
+
+function emptyBodyError(label: string, status: number): UnconfirmedSubmissionError {
+  // eslint-disable-next-line no-console
+  console.error(
+    `${label} Submission NOT confirmed: the server answered ${status} with an empty body. ` +
+      `EVERY DCS submission endpoint returns a JSON receipt — including on 204, which is why the ` +
+      `old 204 exemption was removed (C-310) — so an empty body means the request was answered by ` +
+      `something other than the DCS API (a misrouted POST).`,
+  )
+  return unconfirmed(VISITOR_UNCONFIRMED_MESSAGE, false)
+}
+
+function nonJsonBodyError(
+  label: string,
+  status: number,
+  contentType: string,
+  raw: string,
+): UnconfirmedSubmissionError {
+  const looksLikeHtml = contentType.includes('html') || /^\s*<(?:!doctype|html)/i.test(raw)
+  // eslint-disable-next-line no-console
+  console.error(
+    `${label} Submission NOT stored: the server answered ${status} ` +
+      `with a ${contentType || 'bodyless/unknown'} body instead of JSON` +
+      (looksLikeHtml
+        ? ' — this is an HTML page, so the POST did not reach the DCS API (check the resolved api-base and the host routing for /api/v1/*).'
+        : '.') +
+      ` First 200 bytes: ${raw.slice(0, 200)}`,
+  )
+  return unconfirmed(VISITOR_UNCONFIRMED_MESSAGE, false)
+}
+
+function invalidReceiptError(
+  label: string,
+  status: number,
+  receiptName: string,
+  body: unknown,
+): UnconfirmedSubmissionError {
+  // eslint-disable-next-line no-console
+  console.error(
+    `${label} Submission NOT confirmed: the server answered ${status} with JSON that is not a ` +
+      `valid ${receiptName} receipt. A 2xx and parseable JSON prove only that SOMETHING answered; ` +
+      `only the endpoint's receipt proves a row was stored. Received: ` +
+      `${safeStringify(body).slice(0, 200)}`,
+  )
+  return unconfirmed(VISITOR_UNCONFIRMED_MESSAGE, true)
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? String(value)
+  } catch {
+    return String(value)
+  }
+}

package/src/composables/useFormSubmission.ts

@@ -3,6 +3,11 @@ import type {
   DcsFormSubmitSuccess,
   DcsFormSubmitError,
 } from '../types'
+import {
+  isManagedFormReceipt,
+  readExpectedJson,
+  type UnconfirmedSubmissionError,
+} from './readExpectedJson'
 
 export interface SubmitOptions {
   apiBase: string
@@ -45,16 +50,43 @@ export async function submitFormValues(
   for (let attempt = 0; attempt <= retries; attempt++) {
     try {
       const init: RequestInit = hasFile
-        ? { method: 'POST', body: buildFormData(payload) }
+        ? { method: 'POST', redirect: REDIRECT_MODE, body: buildFormData(payload) }
         : {
             method: 'POST',
+            redirect: REDIRECT_MODE,
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(payload),
           }
       const res = await fetchImpl(url, init)
       lastStatus = res.status
       if (res.ok) {
-        const body = await safeJson(res)
+        let body: unknown
+        try {
+          body = await readExpectedJson(res, isManagedFormReceipt, {
+            receiptName: 'managed-form submission',
+          })
+        } catch (bodyError) {
+          // TERMINAL — never retried. A 2xx that does not carry the endpoint's
+          // receipt means either the POST was answered by something that is not
+          // the DCS API (SPA shell, proxy interstitial, gateway error page) or
+          // the API answered with something that does not prove a row exists.
+          // Retrying could double-store the lead if the request *did* reach the
+          // API, and cannot help if it did not. Surface it as a failure so the
+          // visitor is never told "sent" without a receipt (C-301 / C-310).
+          const receiptRejected = Boolean(
+            (bodyError as UnconfirmedSubmissionError)?.receiptRejected,
+          )
+          throw {
+            payload,
+            status: res.status,
+            error: bodyError as Error,
+            // `nonJsonResponse` keeps its original literal meaning (the body was
+            // not JSON at all); a JSON body that failed the receipt predicate is
+            // reported through the additive `unconfirmedReceipt` flag instead.
+            nonJsonResponse: !receiptRejected,
+            unconfirmedReceipt: receiptRejected,
+          } satisfies DcsFormSubmitError
+        }
         return { payload, response: body }
       }
       // Retry only on 5xx
@@ -117,13 +149,27 @@ function valueHasFile(value: unknown): boolean {
   return Array.isArray(value) && value.some((item) => item instanceof File)
 }
 
-async function safeJson(res: Response): Promise<unknown> {
-  try {
-    return await res.json()
-  } catch {
-    return null
-  }
-}
+/**
+ * A submission POST must never FOLLOW a redirect (C-310, Codex review §b).
+ *
+ * Browser `fetch` follows redirects by default, so the guard only ever sees the
+ * FINAL response. An HTML landing page is caught by the receipt check, but a
+ * redirect that terminates at some other host's valid JSON would not be — and a
+ * `301`/`302` also silently rewrites a POST into a GET, so the submission body
+ * is dropped on the way.
+ *
+ * Verified against production routing before enabling: the Front Door `api`
+ * route (`infrastructure/partner/front-door-routes.bicep:1626`) and the portal
+ * `/api/*` route (`:2318`) carry NO rule sets — their only redirect is
+ * `httpsRedirect`, which cannot fire because every fleet site resolves an
+ * absolute `https://` api-base (C-301 live-bundle sweep). The one `/*`-scoped
+ * 301 in the profile (`kduff-homes-www-redirect`, `:2125`) applies to
+ * `www.kimduffhomes.com` and is a MISROUTE by definition for a submission POST.
+ *
+ * So on the intended path this changes nothing, and on every unintended path it
+ * converts a silent, body-losing hop into a visible failure.
+ */
+const REDIRECT_MODE: RequestRedirect = 'error'
 
 async function safeText(res: Response): Promise<string> {
   try {