@duffcloudservices/site-forms 0.5.0 → 0.7.0

package/README.md

@@ -165,10 +165,34 @@ import { dcsFormsModules } from '@/dcs-forms'
 
 | Event              | Payload                | When                                        |
 | ------------------ | ---------------------- | ------------------------------------------- |
-| `submit-success`   | `DcsFormSubmitSuccess` | API responded `2xx`.                        |
-| `submit-error`     | `DcsFormSubmitError`   | Network or non-2xx response after retries.  |
+| `submit-success`   | `DcsFormSubmitSuccess` | API responded `2xx` **with a JSON (or empty) body**. |
+| `submit-error`     | `DcsFormSubmitError`   | Network error, non-2xx after retries, **or a 2xx whose body is not JSON** (`nonJsonResponse: true`). |
 | `validation-error` | `FormErrors`           | Submit attempted with invalid required/regex/etc. fields. |
 
+### A 2xx with a non-JSON body is a FAILURE (0.6.0, C-301)
+
+Before 0.6.0 the submission helper swallowed every body-parse failure and
+returned `null`, so a POST answered by **HTTP 200 `text/html`** — a static
+host's SPA shell, a Front Door catch-all, a captive-portal or corporate-proxy
+interstitial — was indistinguishable from a quiet success. The visitor saw the
+success state and the success chime while **nothing was stored**: silent lead
+loss.
+
+Now:
+
+| Response                       | Behaviour                                              |
+| ------------------------------ | ------------------------------------------------------ |
+| `2xx` + JSON body              | success, `response` = parsed JSON (unchanged)           |
+| `2xx` + empty body (incl. 204) | success, `response` = `null` (unchanged)                |
+| `2xx` + any other body         | **`submit-error`** with `nonJsonResponse: true`, **never retried** (retrying could double-store a lead), plus a `console.error` naming the resolved base |
+| non-2xx                        | unchanged error contract                                |
+
+The assertion is inlined here on purpose rather than delegated to
+`@duffcloudservices/cms-core`'s `platformFetch`: `site-forms` is a leaf package
+that sites pin independently (coron8 sits on `0.1.4`), and a new cms-core
+dependency would make the fix unpublishable to exactly the sites that most need
+it.
+
 ## Slots
 
 Every slot exposes scoped data so consumers (KT Braun, Kept) can swap
@@ -207,6 +231,11 @@ import {
 - `submitFormValues({ apiBase, siteSlug, payload })` — one-shot POST
   with a single retry on 5xx and `multipart/form-data` when files are
   present.
+- `fetchSiteHandlesPhi({ apiBase, siteSlug })` — the site's PHI posture
+  (C-415), memoized per site. `<DcsForm/>` already calls it; a custom
+  layout should use it rather than inventing a second HIPAA signal.
+  `PHI_GUIDANCE_COPY` is the standard wording, `resetSitePhiPostureCache()`
+  clears the memo (tests / the portal preview iframe).
 
 File fields emit a single `File` by default. When `attachmentPolicy.maxFiles`
 is greater than `1`, the file field emits `File[]`, enables multiple
@@ -285,7 +314,17 @@ Use the **Legal Intake — Standard** form template (created via the portal Form
 - Automatically sets `isSensitive: true`
 - Includes matter-type and adverse-parties fields for conflict screening
 
-For healthcare intake, mark the form as `FormKind: "hipaa"` so the submission handler applies PHI-aware redaction for notification emails.
+For healthcare intake, mark each PHI-bearing field `phi: true` in the YAML. There is no `hipaa` form kind (the kinds are `freeform`, `contact`, `revenue-contractor`, `resume-submission`); PHI handling is driven by the per-field `phi` marker plus the **site-level** predicate below.
+
+### PHI guidance on HIPAA-mode tenants (C-415)
+
+On a HIPAA-mode tenant, `<DcsForm/>` renders a standard guidance line immediately above the first free-text field:
+
+> **Please don't include personal health details.** A general description of what you need is enough — we'll go over anything specific with you directly.
+
+It is on by default and there is deliberately **no prop and no YAML flag** to force it on or off. The verdict comes from the platform: on mount the component GETs `/api/v1/sites/{slug}/forms/compliance` (memoized per site; the slug-free `/api/v1/forms/compliance` when the build has no baked slug), which is a boolean projection of the server's one site-level PHI predicate, `portal.Service.SiteHandlesPHI` — authoritative input `SiteAgentConfigs/{slug}/default.HipaaMode`, the same row the C-352 redaction gate reads. A site-local switch could disagree with the tenant's real posture, which is exactly the class C-352 fixed.
+
+If the read fails the component renders nothing; the server-side redactions remain the actual control. Style it via `.dcs-form__phi-guidance`; probe for it with `[data-form-phi-guidance]` (the copy contains no "HIPAA"/"protected health information" legalese by design — it is guidance for a visitor, not a legal notice).
 
 ---
 

package/dist/composables/readExpectedJson.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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 declare function readOkBody(res: Response, label?: string): Promise<unknown>;
+/**
+ * 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 declare function readExpectedJson<T>(res: Response, validator: ReceiptValidator<T>, options?: {
+    label?: string;
+    receiptName?: string;
+}): Promise<T>;
+/**
+ * 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;
+}
+export declare function isManagedFormReceipt(value: unknown): value is ManagedFormReceipt;
+/** `ContactFormResponse` — types.gen.ts:19831. */
+export interface SiteContactReceipt {
+    id?: string;
+    status: string;
+    submittedAt?: string;
+    message?: string;
+}
+export declare function isSiteContactReceipt(value: unknown): value is SiteContactReceipt;
+/**
+ * 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 declare function isEstimateReceipt(value: unknown): value is EstimateReceipt;
+/** `PasswordlessVerifyCodeResponse` — types.gen.ts:20780. */
+export interface PasswordlessVerifyReceipt {
+    success: true;
+    redirectTo?: string;
+}
+export declare function isPasswordlessVerifyReceipt(value: unknown): value is PasswordlessVerifyReceipt;
+/** `CancelBookingResponse` — types.gen.ts:21486. */
+export interface BookingCancellationReceipt {
+    success: true;
+    refundAmountCents?: number | null;
+    message?: string;
+}
+export declare function isBookingCancellationReceipt(value: unknown): value is BookingCancellationReceipt;

package/dist/composables/useSitePhiPosture.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Site PHI posture — the ONE platform signal that decides whether a managed
+ * form shows PHI guidance to the visitor.
+ *
+ * WHY THIS EXISTS (C-415 / KEPT re-review F1). On a HIPAA-mode tenant the AI
+ * chat widget already opens with "please don't include personal health
+ * details", because `/agent/config` projects `hipaaMode` to it. The managed
+ * form on the same tenant — the higher-volume intake path, with a required
+ * free-text message box — projected nothing, so the platform was doing the
+ * hard half of the problem (redacting PHI it had already received) and
+ * skipping the cheap half (asking the visitor not to send it).
+ *
+ * THE SIGNAL, AND ONLY THIS SIGNAL. `GET {apiBase}/sites/{slug}/forms/compliance`
+ * returns `{ siteHandlesPhi }`, the server's projection of
+ * `portal.Service.SiteHandlesPHI` — whose authoritative input is
+ * `SiteAgentConfigs/{slug}/default.HipaaMode`, the same admin-pinned row the
+ * C-352 redaction gate reads. There is no second signal, no YAML flag, and no
+ * per-site opt-in: a site-local switch could drift from the tenant's real HIPAA
+ * posture, which is the exact class of bug C-352 fixed.
+ *
+ * NOT `/agent/config`, which already carries `hipaaMode`: that endpoint 404s
+ * unless the `aiAgent` feature, the per-site toggle, and the global kill switch
+ * are all on. Reading the flag from there would silently give no guidance to a
+ * HIPAA-mode tenant that does not run the chat widget — a fail-OPEN gate hidden
+ * behind an unrelated feature flag.
+ *
+ * FAIL DIRECTION. The server side fails CLOSED (an unresolvable HipaaMode
+ * reports `true`, so the guidance shows). The client cannot: a transport
+ * failure or an offline build has no verdict at all, and defaulting to "show"
+ * would put a health-privacy line on every non-medical customer's contact form.
+ * So the client defaults to `false` on any failure, and the server-side
+ * redactions (C-352) remain the actual control — this module is guidance, not
+ * enforcement.
+ */
+export interface SitePhiPostureOptions {
+    /** API base URL, e.g. `https://api.duffcloudservices.com/api/v1`. */
+    apiBase: string;
+    /**
+     * Site slug. When empty the slug-free `/forms/compliance` route is used and
+     * the server infers the site from the request origin/host — the same
+     * fallback `submitFormValues` uses, so a build with no baked slug still gets
+     * a verdict instead of requesting the broken `/sites//forms/...` shape.
+     */
+    siteSlug: string;
+    /** Optional fetch implementation override (tests). */
+    fetchImpl?: typeof fetch;
+}
+/** Clears the memoized verdicts. Exported for tests and the portal preview iframe. */
+export declare function resetSitePhiPostureCache(): void;
+/**
+ * Resolves whether this site's managed-form submissions are PHI-bearing.
+ *
+ * Returns `false` on any failure (network, non-2xx, non-JSON, or a body whose
+ * `siteHandlesPhi` is not a boolean). A missing/garbled body is treated as "no
+ * verdict", never as an implicit yes — see the fail-direction note above.
+ */
+export declare function fetchSiteHandlesPhi(opts: SitePhiPostureOptions): Promise<boolean>;
+/**
+ * The standard PHI guidance copy. It lives in the package, not in the API
+ * response and not in any site's YAML, so one platform decision renders the
+ * same sentence on every HIPAA-mode tenant.
+ *
+ * It is guidance, not a legal notice: it tells the visitor what to do instead
+ * of what the law requires, and it deliberately mirrors the sentence the AI
+ * chat already ships on these tenants ("please don't include personal health
+ * details") so the two surfaces read as one product.
+ */
+export declare const PHI_GUIDANCE_COPY: {
+    readonly lead: "Please don't include personal health details.";
+    readonly detail: "A general description of what you need is enough — we'll go over anything specific with you directly.";
+};

package/dist/index.d.ts

@@ -16,6 +16,10 @@ export type { UseDcsFormOptions, UseDcsFormReturn } from './composables/useDcsFo
 export { validateField, validateForm, isFieldVisible, hasErrors, } from './composables/useFormValidation';
 export { submitFormValues } from './composables/useFormSubmission';
 export type { SubmitOptions } from './composables/useFormSubmission';
+export { fetchSiteHandlesPhi, resetSitePhiPostureCache, PHI_GUIDANCE_COPY, } from './composables/useSitePhiPosture';
+export type { SitePhiPostureOptions } from './composables/useSitePhiPosture';
+export { readOkBody, readExpectedJson, isManagedFormReceipt, isSiteContactReceipt, isEstimateReceipt, isPasswordlessVerifyReceipt, isBookingCancellationReceipt, } from './composables/readExpectedJson';
+export type { ReceiptValidator, UnconfirmedSubmissionError, ManagedFormReceipt, SiteContactReceipt, EstimateReceipt, PasswordlessVerifyReceipt, BookingCancellationReceipt, } from './composables/readExpectedJson';
 export { loadFormDefinitions, parseFormYaml } from './loaders/yaml';
 export { buildStandardFormDefinition, STANDARD_FORM_PRESET_META, } from './presets';
 export type { StandardFormPreset, BuildStandardFormOptions, } from './presets';