@wildo-ai/saas-website 1.1.1

package/src/core/anonymous-session/InboundContactForm.tsx

@@ -0,0 +1,157 @@
+/**
+ * InboundContactForm — the marketing site's real lead-capture form (React island).
+ *
+ * Self-contained + bundle-safe: uses only `react`, the website-local input schema, and
+ * a `WebsiteAnonymousSessionClient` instance (constructed by the section/bridge wiring
+ * from the site's API-origin config). On submit it validates client-side, then POSTs
+ * `/inbound-contacts` through the anonymous-session client — the FIRST submission mints
+ * the anonymous session (init header) and the backend stamps the lead's `anonymousUserId`
+ * so it can later transpose to the visitor's account on signup/login.
+ *
+ * Labels are injected (optional props with English fallbacks) rather than read from the
+ * website runtime context, so the component stays framework-light and unit-testable; the
+ * section wrapper passes i18n-resolved strings.
+ */
+
+import React, { useCallback, useMemo, useState } from "react";
+import { InboundContactFormSchema, buildInboundContactCreateBody, type InboundContactFormValues } from "./inbound-contact-form.schema";
+import type { WebsiteAnonymousSessionClient } from "./website-anonymous-session-client";
+
+export interface InboundContactFormLabels {
+  emailLabel: string;
+  firstNameLabel: string;
+  lastNameLabel: string;
+  phoneLabel: string;
+  /** OPTIONAL marketing opt-in checkbox. */
+  marketingConsentLabel: string;
+  submitLabel: string;
+  submittingLabel: string;
+  successMessage: string;
+  errorMessage: string;
+}
+
+const DEFAULT_LABELS: InboundContactFormLabels = {
+  emailLabel: "Email",
+  firstNameLabel: "First name",
+  lastNameLabel: "Last name",
+  phoneLabel: "Phone",
+  marketingConsentLabel: "Keep me updated about news and offers",
+  submitLabel: "Get in touch",
+  submittingLabel: "Sending…",
+  successMessage: "Thanks — we'll be in touch shortly.",
+  errorMessage: "Something went wrong. Please try again.",
+};
+
+type SubmitState = { status: "idle" } | { status: "submitting" } | { status: "success" } | { status: "error"; message: string };
+
+export interface InboundContactFormProps {
+  /** The anonymous-session client (constructed by the section wiring from site config). */
+  client: WebsiteAnonymousSessionClient;
+  /** Optional i18n-resolved labels; English fallbacks are used per-field when omitted. */
+  labels?: Partial<InboundContactFormLabels>;
+  /** Optional callback fired after a successful submission (e.g. analytics). */
+  onSubmitted?: () => void;
+}
+
+const EMPTY_VALUES: InboundContactFormValues = {
+  email: "",
+  firstName: "",
+  lastName: "",
+  phone: "",
+  marketingConsent: false,
+};
+
+export function InboundContactForm({ client, labels, onSubmitted }: InboundContactFormProps): React.ReactElement {
+  const resolvedLabels = useMemo(() => ({ ...DEFAULT_LABELS, ...labels }), [labels]);
+  const [values, setValues] = useState<InboundContactFormValues>(EMPTY_VALUES);
+  const [fieldErrors, setFieldErrors] = useState<Partial<Record<keyof InboundContactFormValues, string>>>({});
+  const [submit, setSubmit] = useState<SubmitState>({ status: "idle" });
+
+  const setField = useCallback(<K extends keyof InboundContactFormValues>(key: K, value: InboundContactFormValues[K]) => {
+    setValues((prev) => ({ ...prev, [key]: value }));
+  }, []);
+
+  const handleSubmit = useCallback(
+    async (event: React.FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      setFieldErrors({});
+
+      const parsed = InboundContactFormSchema.safeParse(values);
+      if (!parsed.success) {
+        const nextErrors: Partial<Record<keyof InboundContactFormValues, string>> = {};
+        for (const issue of parsed.error.issues) {
+          const key = issue.path[0] as keyof InboundContactFormValues | undefined;
+          if (key && !nextErrors[key]) nextErrors[key] = issue.message;
+        }
+        setFieldErrors(nextErrors);
+        return;
+      }
+
+      setSubmit({ status: "submitting" });
+      try {
+        await client.postAnonymous("/inbound-contacts", buildInboundContactCreateBody(parsed.data));
+        setSubmit({ status: "success" });
+        setValues(EMPTY_VALUES);
+        onSubmitted?.();
+      } catch {
+        // The backend-only `emailUserMatch` triage signal is never returned here, so a
+        // failure exposes no account-existence information — just a generic retry.
+        setSubmit({ status: "error", message: resolvedLabels.errorMessage });
+      }
+    },
+    [client, values, onSubmitted, resolvedLabels.errorMessage],
+  );
+
+  if (submit.status === "success") {
+    return (
+      <div role="status" aria-live="polite">
+        {resolvedLabels.successMessage}
+      </div>
+    );
+  }
+
+  const isSubmitting = submit.status === "submitting";
+
+  return (
+    <form onSubmit={handleSubmit} noValidate>
+      <label>
+        {resolvedLabels.emailLabel}
+        <input
+          type="email"
+          name="email"
+          required
+          value={values.email}
+          onChange={(e) => setField("email", e.target.value)}
+          aria-invalid={fieldErrors.email ? true : undefined}
+        />
+        {fieldErrors.email ? <span role="alert">{fieldErrors.email}</span> : null}
+      </label>
+
+      <label>
+        {resolvedLabels.firstNameLabel}
+        <input type="text" name="firstName" value={values.firstName ?? ""} onChange={(e) => setField("firstName", e.target.value)} />
+      </label>
+
+      <label>
+        {resolvedLabels.lastNameLabel}
+        <input type="text" name="lastName" value={values.lastName ?? ""} onChange={(e) => setField("lastName", e.target.value)} />
+      </label>
+
+      <label>
+        {resolvedLabels.phoneLabel}
+        <input type="tel" name="phone" value={values.phone ?? ""} onChange={(e) => setField("phone", e.target.value)} />
+      </label>
+
+      <label>
+        <input type="checkbox" name="marketingConsent" checked={values.marketingConsent} onChange={(e) => setField("marketingConsent", e.target.checked)} />
+        {resolvedLabels.marketingConsentLabel}
+      </label>
+
+      {submit.status === "error" ? <div role="alert">{submit.message}</div> : null}
+
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? resolvedLabels.submittingLabel : resolvedLabels.submitLabel}
+      </button>
+    </form>
+  );
+}

package/src/core/anonymous-session/__tests__/inbound-contact-form.schema.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+
+import { InboundContactFormSchema, buildInboundContactCreateBody, type InboundContactFormValues } from "../inbound-contact-form.schema";
+
+/**
+ * The inbound-contact form is the anonymous lead-capture surface. Its
+ * The form may collect contact fields and an optional marketing preference. It must
+ * not manufacture notice, contract or consent evidence without an exact governed
+ * document release and the runtime receipt boundary.
+ */
+describe("InboundContactFormSchema — contact and marketing choices", () => {
+  const minimum = { email: "Lead@Example.com" };
+
+  it("accepts email as the minimum and defaults the optional marketing choice", () => {
+    expect(InboundContactFormSchema.parse(minimum)).toEqual({ email: "Lead@Example.com", marketingConsent: false });
+  });
+
+  it("rejects a malformed email", () => {
+    expect(InboundContactFormSchema.safeParse({ ...minimum, email: "not-an-email" }).success).toBe(false);
+  });
+});
+
+describe("buildInboundContactCreateBody — no synthetic legal receipt", () => {
+  const values: InboundContactFormValues = {
+    email: "Lead@Example.com",
+    marketingConsent: false,
+  };
+
+  it("emits no embedded legal-document approval", () => {
+    const serialized = JSON.stringify(buildInboundContactCreateBody(values));
+    expect(serialized).not.toContain("Approval");
+    expect(serialized).not.toContain("acceptedAt");
+  });
+
+  it("lower-cases + trims the email", () => {
+    expect(buildInboundContactCreateBody(values).email).toBe("lead@example.com");
+  });
+
+  it("maps the OPTIONAL marketing opt-in to the dataProcessingConsent tier", () => {
+    const tier = (v: InboundContactFormValues): string => (buildInboundContactCreateBody(v).privacy as { dataProcessingConsent: string }).dataProcessingConsent;
+    expect(tier({ ...values, marketingConsent: true })).toBe("marketing");
+    expect(tier({ ...values, marketingConsent: false })).toBe("basic");
+  });
+});

package/src/core/anonymous-session/inbound-contact-form.schema.ts

@@ -0,0 +1,62 @@
+/**
+ * Inbound-contact form input schema (website-local, bundle-safe).
+ *
+ * Deliberately a SEPARATE plain-Zod schema, NOT `InboundContactSchema` from
+ * `@wildo-ai/saas-models`: that schema is decorator-bound (`.isPrimaryKey()`,
+ * `.excludeFromCreate()`, `.isBackendOnly()`, …), so importing it would boot the
+ * decorator framework into the browser bundle — forbidden by bundle discipline. The
+ * website only needs to validate the handful of client-authored CREATE fields; the
+ * backend is the authority on the full contract (it re-validates + injects the
+ * server-set fields: `_id`, `anonymousUserId`, `userId`, `emailUserMatch`, timestamps).
+ *
+ * Mirrors the non-excluded, non-backend-only CREATE inputs of `InboundContact`
+ * (`email` required; `firstName` / `lastName` / `phone` optional), plus TWO distinct
+ * privacy signal: an OPTIONAL marketing opt-in (mapped to the
+ * `privacy.dataProcessingConsent` tier). A governed notice, contract or consent
+ * interaction must use the separate exact-release receipt contract; this DTO cannot
+ * manufacture legal evidence from a checkbox and client timestamp.
+ * `relatedUserId` is intentionally absent — it is `.excludeFromCreate()` on the
+ * resource (sales/admin-only, never client-authored).
+ */
+
+import { z } from "zod";
+
+/**
+ * The wire payload POSTed to `/api/v1/inbound-contacts`. `privacy` matches the
+ * resource's `InboundContactPrivacySchema` shape (a nested consent object) so the
+ * backend accepts it verbatim.
+ */
+export const InboundContactFormSchema = z.object({
+  // Zod 4: top-level `z.email()` (not the deprecated `z.string().email()`), matching
+  // the resource schema. An empty string fails it, so it also covers "required".
+  email: z.email("Enter a valid email address"),
+  firstName: z.string().trim().max(200).optional(),
+  lastName: z.string().trim().max(200).optional(),
+  phone: z.string().trim().max(64).optional(),
+  /**
+   * OPTIONAL marketing opt-in — maps into the resource's `privacy.dataProcessingConsent`
+   * tier ('marketing' vs the BASIC default). Independent of the required agreement above.
+   */
+  marketingConsent: z.boolean().default(false),
+});
+
+export type InboundContactFormValues = z.infer<typeof InboundContactFormSchema>;
+
+/**
+ * Build the exact JSON body the backend CREATE expects from validated form values.
+ * Keeps the `privacy` nesting + the consent enum mapping in ONE place so the form
+ * component stays declarative.
+ */
+export function buildInboundContactCreateBody(values: InboundContactFormValues): Record<string, unknown> {
+  return {
+    email: values.email.trim().toLowerCase(),
+    ...(values.firstName ? { firstName: values.firstName } : {}),
+    ...(values.lastName ? { lastName: values.lastName } : {}),
+    ...(values.phone ? { phone: values.phone } : {}),
+    privacy: {
+      // OPTIONAL marketing tier: 'marketing' when the visitor opted in, else the
+      // resource's BASIC default.
+      dataProcessingConsent: values.marketingConsent ? "marketing" : "basic",
+    },
+  };
+}

package/src/core/anonymous-session/website-anonymous-session-client.ts

@@ -0,0 +1,194 @@
+/**
+ * WebsiteAnonymousSessionClient
+ *
+ * A self-contained, browser-only anonymous-session HTTP client for the marketing
+ * website. It MIRRORS the SaaS app's `AnonymousSessionContext` protocol WITHOUT
+ * importing `@wildo-ai/saas-frontend-lib` — the website ships into a browser bundle
+ * that must not pull the decorator framework / heavy frontend graph (bundle
+ * discipline). It uses ONLY browser globals (`fetch` / `crypto` / `localStorage`) and
+ * the bundle-safe `@wildo-ai/saas-models/public-runtime` atoms. No axios (axios is the
+ * SSR tier), no React — a React island context can wrap this class.
+ *
+ * Protocol (W7.3a):
+ *   1. The first anonymous request sends `x-anonymous-session-init: <clientUuid>` — the
+ *      backend mints an `AnonymousUser` (uuidRef = clientUuid) and returns a signed JWT
+ *      in the `x-anonymous-session-token` RESPONSE header.
+ *   2. Subsequent requests send `x-anonymous-session: <jwt>`.
+ *   Every request also sends `X-Frontend-Service-Name` (required by the anon backend
+ *   to accept the request and resolve the frontend identity).
+ *
+ * CORS (critical): the website is a DIFFERENT origin from the backend API, so the
+ * `x-anonymous-session-token` response header is readable by `fetch` ONLY if the
+ * backend lists it in `Access-Control-Expose-Headers` (non-safelisted response headers
+ * are hidden from cross-origin `fetch`). Without that, the captured token is `null`,
+ * the session never advances past init, and every request re-mints a session.
+ *
+ * Cross-origin continuity: the anonymous session created here (uuidRef) is what the
+ * SaaS app transposes on signup/login. It is carried across the apex↔app boundary by
+ * the backend-set parent-domain `__wildo_anon_session` cookie — hence `credentials:
+ * 'include'`, so that cookie rides same-site requests to the API.
+ */
+
+import { WildoHeaderKeys, MAIN_API_BASE_PATH } from '@wildo-ai/saas-models/public-runtime';
+
+/**
+ * localStorage keys. The website is self-contained (mirror-don't-import), so it pins
+ * the stable literal values rather than importing the decorator-adjacent shared
+ * contract. Cross-origin continuity flows through the backend cookie, NOT this
+ * localStorage, so these keys need not match the app's byte-for-byte.
+ */
+const STORAGE_KEYS = {
+  anonymousUserId: 'anonymousUserId',
+  anonymousSessionToken: 'anonymousSessionToken',
+} as const;
+
+export interface WebsiteAnonymousSessionClientOptions {
+  /** Backend API origin WITHOUT a trailing slash, e.g. `https://api.example.com`. */
+  apiOrigin: string;
+  /** `X-Frontend-Service-Name` value identifying this marketing site to the backend. */
+  frontendServiceName: string;
+}
+
+/** Thrown when an anonymous request returns a non-2xx status. */
+export class WebsiteAnonymousRequestError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly bodyText: string,
+  ) {
+    super(`Anonymous request failed with status ${status}`);
+    this.name = 'WebsiteAnonymousRequestError';
+  }
+}
+
+export class WebsiteAnonymousSessionClient {
+  private anonymousUserId: string | null = null;
+  private sessionToken: string | null = null;
+  private readonly apiBaseUrl: string;
+  private readonly frontendServiceName: string;
+
+  constructor(options: WebsiteAnonymousSessionClientOptions) {
+    this.apiBaseUrl = `${options.apiOrigin.replace(/\/+$/, '')}${MAIN_API_BASE_PATH}`;
+    this.frontendServiceName = options.frontendServiceName;
+    this.restoreFromStorage();
+  }
+
+  /** The anonymous session's relational identity (client uuidRef), or `null` if not started. */
+  getAnonymousUserId(): string | null {
+    return this.anonymousUserId;
+  }
+
+  /**
+   * Return the anonymous session's relational identity (client uuidRef),
+   * STARTING the session first if it has not begun yet. Unlike
+   * `getAnonymousUserId()` (which may return `null`), this always yields
+   * a stable uuidRef.
+   *
+   * Used by NESTED anonymous routes that must embed the id in the URL
+   * BEFORE the first request — e.g. draft-notes POSTs to
+   * `/user-anonymous-users/<uuidRef>/draft-notes`. The id generated here
+   * is the SAME one the next `postAnonymous(...)` sends as
+   * `x-anonymous-session-init`, so the URL scope and the minted session
+   * refer to one anonymous user (no split identity).
+   */
+  getOrStartAnonymousUserId(): string {
+    this.ensureSessionStarted();
+    // ensureSessionStarted() guarantees anonymousUserId is non-null.
+    return this.anonymousUserId as string;
+  }
+
+  /** `true` once an init request has succeeded and a session token is held. */
+  isSessionActive(): boolean {
+    return this.anonymousUserId !== null && this.sessionToken !== null;
+  }
+
+  /**
+   * POST `body` to an anonymous endpoint. `path` is relative to `/api/v1`
+   * (e.g. `/inbound-contacts`, or a nested `/anonymous-users/<uuidRef>/draft-notes`).
+   * Lazily starts the session on the first call, attaches the anon-session +
+   * service-name headers, captures any returned session token, and returns the parsed
+   * JSON response. Throws `WebsiteAnonymousRequestError` on a non-2xx status.
+   */
+  async postAnonymous<TResponse = unknown>(path: string, body: unknown): Promise<TResponse> {
+    this.ensureSessionStarted();
+
+    const response = await fetch(`${this.apiBaseUrl}${path}`, {
+      method: 'POST',
+      headers: this.buildHeaders(),
+      body: JSON.stringify(body),
+      // Carry the parent-domain `__wildo_anon_session` cookie to the API so the
+      // session is continuous across the apex/app/api origins.
+      credentials: 'include',
+    });
+
+    this.captureSessionToken(response);
+
+    if (!response.ok) {
+      throw new WebsiteAnonymousRequestError(response.status, await safeReadText(response));
+    }
+    return (await response.json()) as TResponse;
+  }
+
+  private ensureSessionStarted(): void {
+    if (!this.anonymousUserId) {
+      this.anonymousUserId = crypto.randomUUID();
+      this.sessionToken = null;
+      this.persist();
+    }
+  }
+
+  private buildHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+      [WildoHeaderKeys.FRONTEND_SERVICE_NAME]: this.frontendServiceName,
+    };
+    // Once we hold the JWT, restore the session; before that, the raw UUID inits it.
+    if (this.sessionToken) {
+      headers[WildoHeaderKeys.ANONYMOUS_SESSION] = this.sessionToken;
+    } else if (this.anonymousUserId) {
+      headers[WildoHeaderKeys.ANONYMOUS_SESSION_INIT] = this.anonymousUserId;
+    }
+    return headers;
+  }
+
+  private captureSessionToken(response: Response): void {
+    // Requires the backend to CORS-expose this header (see the class-level CORS note).
+    const token = response.headers.get(WildoHeaderKeys.ANONYMOUS_SESSION_TOKEN);
+    if (token && token !== this.sessionToken) {
+      this.sessionToken = token;
+      this.persist();
+    }
+  }
+
+  private restoreFromStorage(): void {
+    try {
+      const userId = localStorage.getItem(STORAGE_KEYS.anonymousUserId);
+      const token = localStorage.getItem(STORAGE_KEYS.anonymousSessionToken);
+      if (userId) this.anonymousUserId = userId;
+      if (token) this.sessionToken = token;
+    } catch {
+      // localStorage unavailable (SSR build / privacy mode) — the session stays
+      // in-memory for this page load only.
+    }
+  }
+
+  private persist(): void {
+    try {
+      if (this.anonymousUserId) {
+        localStorage.setItem(STORAGE_KEYS.anonymousUserId, this.anonymousUserId);
+      }
+      if (this.sessionToken) {
+        localStorage.setItem(STORAGE_KEYS.anonymousSessionToken, this.sessionToken);
+      }
+    } catch {
+      // Best-effort persistence; a failure only means the session won't survive reload.
+    }
+  }
+}
+
+async function safeReadText(response: Response): Promise<string> {
+  try {
+    return await response.text();
+  } catch {
+    return '';
+  }
+}

package/src/core/contexts/WebsitePageContext.tsx

@@ -0,0 +1,52 @@
+import React, { createContext, type ReactNode } from 'react';
+
+import type { WebsitePageRef } from '../../schemas/refs/page-ref.schemas';
+
+/**
+ * @wildo_source:part:start saas.website.page.context facet:layer:core facet:family:website
+ *
+ * `WebsitePageContext` — identity of the page currently rendering.
+ * Provided by `<WebsitePageLayout pageRef="…">` exactly once per
+ * page render and consumed by `useWebsiteLabel(leaf)` to compose the
+ * full label key (`website.{pageRef}.{sectionRef}.{leaf}`).
+ *
+ * **Why an isolated context (not merged into runtime)**: the runtime
+ * context is set at the host-adapter boundary and is constant per
+ * build; the page context is set per page route. Splitting them
+ * lets a single host adapter render multiple pages (preview tooling,
+ * MDX-driven blog index aggregating post excerpts, etc.) without
+ * lying about which page each subtree belongs to.
+ *
+ * **Why a separate file from the hook**: same Fast-Refresh rationale
+ * as `WebsiteRuntimeContext` — split provider/context/hook to keep
+ * HMR boundaries small.
+ */
+export interface WebsitePageContextValue {
+  /**
+   * The validated `WebsitePageRef` of the page currently rendering.
+   * MUST match a `WebsitePageManifest.pageRef` registered in the
+   * site's `WebsiteRootConfig`.
+   */
+  pageRef: WebsitePageRef;
+}
+
+export const WebsitePageContext: React.Context<WebsitePageContextValue | null> =
+  createContext<WebsitePageContextValue | null>(null);
+
+export interface WebsitePageContextProviderProps {
+  value: WebsitePageContextValue;
+  children: ReactNode;
+}
+
+export function WebsitePageContextProvider({
+  value,
+  children,
+}: WebsitePageContextProviderProps): ReactNode {
+  return (
+    <WebsitePageContext.Provider value={value}>
+      {children}
+    </WebsitePageContext.Provider>
+  );
+}
+WebsitePageContextProvider.displayName = 'WebsitePageContextProvider';
+/** @wildo_source:part:end saas.website.page.context */