@flamingo-stack/openframe-frontend-core 0.0.671 → 0.0.672-snapshot.20260928034232

package/src/hooks/use-form-rescue.ts

@@ -0,0 +1,315 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useEndpointsRuntime } from '../contexts/endpoints-runtime-context';
+import { contentFetch } from '../utils/embed-content-fetch';
+import {
+  captureFormRescueEvent,
+  FORM_RESCUE_ATTEMPT_FIELD,
+  FORM_RESCUE_DEBOUNCE_MS,
+  FORM_RESCUE_EVENTS,
+  FORM_RESCUE_RESUME_FIELD,
+  FORM_RESCUE_RESUME_PARAM,
+  filledRescueFields,
+  isFormAttemptId,
+  isRescueEmail,
+  rescueCompletionPct,
+  sanitizeRescueFieldName,
+  sanitizeRescueValues,
+  type FormDraftProgress,
+  type FormDraftResumeResponse,
+  type FormDraftSaveRequest,
+  type FormRescueFormId,
+} from '../utils/form-rescue';
+
+/** A local draft older than this is ignored and replaced. */
+const LOCAL_DRAFT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const STORAGE_PREFIX = 'form-rescue:v1:';
+const UTM_KEYS = ['source', 'medium', 'campaign', 'content', 'term'] as const;
+
+interface LocalDraft {
+  attemptId: string;
+  values: Record<string, string>;
+  savedAt: number;
+}
+
+export interface UseFormRescueOptions {
+  /** Which form this is; `null` turns rescue off (e.g. a signed-in ticket form). */
+  formId: FormRescueFormId | null;
+  /** Every field the visitor can see. Hidden fields are never listed, so never sent. */
+  fieldNames: readonly string[];
+  /** Called once after mount with values from a resume link, else from this device's local draft. */
+  onRestore?: (values: Record<string, string>) => void;
+  /** The form's humanity signals, so the draft endpoint can run the same bot gate as the submit. */
+  getSignals?: () => Record<string, string | number>;
+}
+
+export interface FormRescueHandle {
+  /** Report the form's current values after a change (`lastField` = the field just edited). */
+  track: (values: Record<string, unknown>, lastField?: string | null) => void;
+  /** Keys to spread into the SUBMIT body so the host closes this attempt's draft. */
+  submitFields: () => Record<string, string>;
+  /** Call after a successful submit: clears the local draft and starts a fresh attempt. */
+  complete: () => void;
+}
+
+function newAttemptId(): string {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') return crypto.randomUUID();
+  // RFC 4122 v4 from getRandomValues for older browsers.
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+function readLocalDraft(formId: string): LocalDraft | null {
+  try {
+    const raw = window.localStorage.getItem(STORAGE_PREFIX + formId);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<LocalDraft>;
+    if (!isFormAttemptId(parsed.attemptId) || typeof parsed.savedAt !== 'number') return null;
+    if (Date.now() - parsed.savedAt > LOCAL_DRAFT_TTL_MS) return null;
+    return { attemptId: parsed.attemptId, values: sanitizeRescueValues(parsed.values), savedAt: parsed.savedAt };
+  } catch {
+    return null;
+  }
+}
+
+function writeLocalDraft(formId: string, draft: LocalDraft): void {
+  try {
+    window.localStorage.setItem(STORAGE_PREFIX + formId, JSON.stringify(draft));
+  } catch {
+    // Storage full or blocked: the server draft still works.
+  }
+}
+
+function clearLocalDraft(formId: string): void {
+  try {
+    window.localStorage.removeItem(STORAGE_PREFIX + formId);
+  } catch {
+    // Nothing to clear.
+  }
+}
+
+function readUtm(): FormDraftSaveRequest['utm'] {
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const utm: NonNullable<FormDraftSaveRequest['utm']> = {};
+    for (const key of UTM_KEYS) {
+      const value = params.get(`utm_${key}`);
+      if (value) utm[key] = value.slice(0, 200);
+    }
+    return Object.keys(utm).length ? utm : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * useFormRescue — saves a public form's progress so a visitor who leaves
+ * before submitting can be followed up with, and restores it when they return.
+ *
+ * Every public lead form calls it the same way (next to `useHumanitySignals`):
+ *
+ *   const rescue = useFormRescue({ formId: 'contact', fieldNames, onRestore, getSignals })
+ *   // on change: rescue.track(values, changedField)
+ *   // submit:    body = { ...data, ...getSignals(), ...rescue.submitFields() }
+ *   // success:   rescue.complete()
+ *
+ * Saves go to the host's `EndpointsRuntime.formDraftsUrl` (debounced, plus one
+ * final keepalive save when the tab is hidden). A host that does not provide
+ * the url gets the local draft only. Nothing here can block or delay a submit:
+ * every network and storage call is fire-and-forget and swallows its errors.
+ */
+export function useFormRescue({ formId, fieldNames, onRestore, getSignals }: UseFormRescueOptions): FormRescueHandle {
+  const draftsUrl = useEndpointsRuntime()?.formDraftsUrl;
+
+  const attemptIdRef = useRef<string | null>(null);
+  const resumeTokenRef = useRef<string | null>(null);
+  const latestRef = useRef<FormDraftProgress | null>(null);
+  const dirtyRef = useRef(false);
+  const startedRef = useRef(false);
+  const leadCapturedRef = useRef(false);
+  const completedRef = useRef(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Callers pass inline arrays and callbacks; read them through refs so the
+  // returned handle stays stable and effects run once. Written in an effect
+  // (declared first, so it runs before the restore below), never during render.
+  const fieldNamesRef = useRef(fieldNames);
+  const onRestoreRef = useRef(onRestore);
+  const getSignalsRef = useRef(getSignals);
+  useEffect(() => {
+    fieldNamesRef.current = fieldNames;
+    onRestoreRef.current = onRestore;
+    getSignalsRef.current = getSignals;
+  });
+
+  const attemptId = useCallback((): string => {
+    if (!attemptIdRef.current) attemptIdRef.current = newAttemptId();
+    return attemptIdRef.current;
+  }, []);
+
+  const send = useCallback(
+    (keepalive: boolean) => {
+      if (!formId || !draftsUrl || !dirtyRef.current || completedRef.current || !latestRef.current) return;
+      dirtyRef.current = false;
+      const body: FormDraftSaveRequest = {
+        attempt_id: attemptId(),
+        form_id: formId,
+        ...latestRef.current,
+        source_path: typeof window !== 'undefined' ? window.location.pathname : '/',
+        utm: readUtm(),
+      };
+      try {
+        void contentFetch(draftsUrl, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ ...body, ...(getSignalsRef.current?.() ?? {}) }),
+          keepalive,
+        }).catch(() => undefined);
+      } catch {
+        // A failed save is retried by the next change.
+      }
+      captureFormRescueEvent(FORM_RESCUE_EVENTS.progress, {
+        form_id: formId,
+        attempt_id: attemptId(),
+        fields_filled: body.fields_filled,
+        last_field: body.last_field,
+        completion_pct: body.completion_pct,
+      });
+    },
+    [attemptId, draftsUrl, formId],
+  );
+
+  // Restore once on mount: a resume link wins over this device's local draft.
+  useEffect(() => {
+    if (!formId || typeof window === 'undefined') return undefined;
+    let cancelled = false;
+    const token = new URLSearchParams(window.location.search).get(FORM_RESCUE_RESUME_PARAM);
+
+    const restoreLocal = () => {
+      const local = readLocalDraft(formId);
+      if (!local) return;
+      attemptIdRef.current = local.attemptId;
+      if (Object.keys(local.values).length) onRestoreRef.current?.(local.values);
+    };
+
+    if (token && draftsUrl && /^[A-Za-z0-9_-]{16,128}$/.test(token)) {
+      contentFetch(`${draftsUrl}/resume/${encodeURIComponent(token)}`)
+        .then(async res => (res.ok ? ((await res.json()) as FormDraftResumeResponse) : null))
+        .then(data => {
+          if (cancelled) return;
+          if (!data || data.form_id !== formId) {
+            restoreLocal();
+            return;
+          }
+          resumeTokenRef.current = token;
+          onRestoreRef.current?.(sanitizeRescueValues(data.values));
+          captureFormRescueEvent(FORM_RESCUE_EVENTS.resumed, { form_id: formId, attempt_id: attemptId() });
+        })
+        .catch(() => {
+          if (!cancelled) restoreLocal();
+        });
+    } else {
+      restoreLocal();
+    }
+    return () => {
+      cancelled = true;
+    };
+  }, [attemptId, draftsUrl, formId]);
+
+  // Final save when the visitor hides or leaves the tab.
+  useEffect(() => {
+    if (!formId || typeof document === 'undefined') return undefined;
+    const onHide = () => {
+      if (completedRef.current || !startedRef.current) return;
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+      send(true);
+      captureFormRescueEvent(FORM_RESCUE_EVENTS.abandoned, {
+        form_id: formId,
+        attempt_id: attemptId(),
+        last_field: latestRef.current?.last_field ?? null,
+        completion_pct: latestRef.current?.completion_pct ?? 0,
+      });
+    };
+    const onVisibility = () => {
+      if (document.visibilityState === 'hidden') onHide();
+    };
+    document.addEventListener('visibilitychange', onVisibility);
+    window.addEventListener('pagehide', onHide);
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibility);
+      window.removeEventListener('pagehide', onHide);
+      if (timerRef.current) clearTimeout(timerRef.current);
+    };
+  }, [attemptId, formId, send]);
+
+  const track = useCallback(
+    (values: Record<string, unknown>, lastField?: string | null) => {
+      if (!formId || completedRef.current) return;
+      const names = fieldNamesRef.current;
+      const visible: Record<string, unknown> = {};
+      for (const name of names) visible[name] = values[name];
+      const filled = filledRescueFields(visible, names);
+      if (!filled.length) return;
+
+      if (!startedRef.current) {
+        startedRef.current = true;
+        captureFormRescueEvent(FORM_RESCUE_EVENTS.started, { form_id: formId, attempt_id: attemptId() });
+      }
+      const clean = sanitizeRescueValues(visible);
+      if (!leadCapturedRef.current && isRescueEmail(clean.email)) {
+        leadCapturedRef.current = true;
+        captureFormRescueEvent(FORM_RESCUE_EVENTS.leadCaptured, { form_id: formId, attempt_id: attemptId() });
+      }
+      latestRef.current = {
+        values: clean,
+        fields_filled: filled,
+        last_field: sanitizeRescueFieldName(lastField),
+        completion_pct: rescueCompletionPct(filled.length, names.length),
+      };
+      dirtyRef.current = true;
+      writeLocalDraft(formId, { attemptId: attemptId(), values: clean, savedAt: Date.now() });
+
+      if (timerRef.current) clearTimeout(timerRef.current);
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        send(false);
+      }, FORM_RESCUE_DEBOUNCE_MS);
+    },
+    [attemptId, formId, send],
+  );
+
+  const submitFields = useCallback((): Record<string, string> => {
+    if (!formId) return {};
+    return {
+      [FORM_RESCUE_ATTEMPT_FIELD]: attemptId(),
+      ...(resumeTokenRef.current ? { [FORM_RESCUE_RESUME_FIELD]: resumeTokenRef.current } : {}),
+    };
+  }, [attemptId, formId]);
+
+  const complete = useCallback(() => {
+    if (!formId) return;
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    captureFormRescueEvent(FORM_RESCUE_EVENTS.submitted, { form_id: formId, attempt_id: attemptId() });
+    clearLocalDraft(formId);
+    // A fresh attempt for a second submission from the same page.
+    attemptIdRef.current = null;
+    resumeTokenRef.current = null;
+    latestRef.current = null;
+    dirtyRef.current = false;
+    startedRef.current = false;
+    leadCapturedRef.current = false;
+  }, [attemptId, formId]);
+
+  return useMemo(() => ({ track, submitFields, complete }), [track, submitFields, complete]);
+}

package/src/utils/__tests__/form-rescue.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  filledRescueFields,
+  isExcludedRescueField,
+  isFormRescueFormId,
+  isRescueEmail,
+  rescueCompletionPct,
+  sanitizeRescueFieldName,
+  sanitizeRescueValues,
+  FORM_RESCUE_MAX_VALUE_CHARS,
+} from '../form-rescue';
+
+/**
+ * These rules run on BOTH sides: the browser before a draft is sent and the
+ * host before it is stored. The cases are the ones the privacy contract rests
+ * on: nothing outside the allowlist is ever a value, and a credential field is
+ * never even reported by name.
+ */
+describe('sanitizeRescueValues', () => {
+  it('keeps only allowlisted contact fields, trimmed', () => {
+    expect(
+      sanitizeRescueValues({
+        email: '  alex@northwind-it.com ',
+        name: 'Alex',
+        company: 'Northwind IT',
+        message: 'free text never kept',
+        phone: '+15550100',
+        password: 'hunter2',
+        card_number: '4242424242424242',
+      }),
+    ).toEqual({ email: 'alex@northwind-it.com', name: 'Alex', company: 'Northwind IT' });
+  });
+
+  it('caps every value', () => {
+    const out = sanitizeRescueValues({ company: 'x'.repeat(500) });
+    expect(out.company).toHaveLength(FORM_RESCUE_MAX_VALUE_CHARS);
+  });
+
+  it('drops non-strings and empties', () => {
+    expect(sanitizeRescueValues({ email: 42, name: '   ', company: { a: 1 } })).toEqual({});
+    expect(sanitizeRescueValues(null)).toEqual({});
+  });
+});
+
+describe('filledRescueFields', () => {
+  it('reports visible filled fields by name, never credentials', () => {
+    expect(
+      filledRescueFields({ email: 'a@b.co', message: 'hi', password: 'x', companySize: '' }, [
+        'email',
+        'message',
+        'password',
+        'companySize',
+      ]),
+    ).toEqual(['email', 'message']);
+  });
+
+  it('counts a nested answer group as filled when any answer is', () => {
+    expect(filledRescueFields({ formFields: { a: '', b: 'yes' } }, ['formFields'])).toEqual(['formFields']);
+  });
+});
+
+describe('field and id checks', () => {
+  it('excludes credential and payment names', () => {
+    for (const name of [
+      'password',
+      'passcode',
+      'cardNumber',
+      'cvv',
+      'ssn',
+      'iban',
+      'apiToken',
+      'client_secret',
+      'otp',
+    ]) {
+      expect(isExcludedRescueField(name)).toBe(true);
+    }
+    for (const name of ['email', 'company', 'companySize', 'jobtitle']) {
+      expect(isExcludedRescueField(name)).toBe(false);
+    }
+  });
+
+  it('accepts only known form ids', () => {
+    expect(isFormRescueFormId('contact')).toBe(true);
+    expect(isFormRescueFormId('meeting_booking')).toBe(true);
+    expect(isFormRescueFormId('anything_else')).toBe(false);
+  });
+
+  it('validates emails the way the contact table does', () => {
+    expect(isRescueEmail('alex@northwind-it.com')).toBe(true);
+    expect(isRescueEmail('alex@')).toBe(false);
+    expect(isRescueEmail(undefined)).toBe(false);
+  });
+
+  it('bounds field names', () => {
+    expect(sanitizeRescueFieldName('company_size')).toBe('company_size');
+    expect(sanitizeRescueFieldName('<script>')).toBeNull();
+    expect(sanitizeRescueFieldName('password')).toBeNull();
+  });
+
+  it('computes completion as a bounded percentage', () => {
+    expect(rescueCompletionPct(3, 4)).toBe(75);
+    expect(rescueCompletionPct(0, 0)).toBe(0);
+    expect(rescueCompletionPct(9, 4)).toBe(100);
+  });
+});

package/src/utils/form-rescue.ts

@@ -0,0 +1,198 @@
+/**
+ * Form rescue — the shared rules for saving a half-filled public form so the
+ * team can follow up with a visitor who left before submitting.
+ *
+ * Pure and server-safe: the browser hook (`hooks/use-form-rescue`) and the
+ * host's draft endpoint import the SAME allowlist, exclusions, caps and
+ * completion math, so the server re-applies exactly the filter the client ran
+ * and a rename here reaches both sides at once. Also exported through the
+ * granular subpath `./utils/form-rescue` for server-only consumers.
+ *
+ * What a draft may carry:
+ *   - values of ALLOWLISTED contact fields only (`FORM_RESCUE_VALUE_FIELDS`),
+ *     trimmed and capped at `FORM_RESCUE_MAX_VALUE_CHARS`;
+ *   - for every other field, only whether it is filled (never its value);
+ *   - nothing whose name looks like a credential or payment field
+ *     (`isExcludedRescueField`), whatever the allowlist says.
+ *
+ * Field values go to the host only, never to analytics: the PostHog events
+ * (`captureFormRescueEvent`) carry ids, field names and percentages.
+ */
+
+/** Every public form that can be rescued. The host validates `form_id` against this list. */
+export const FORM_RESCUE_FORM_IDS = [
+  'contact',
+  'case_study_pitch',
+  'data_room_request',
+  'trust_center_request',
+  'tmcg_join',
+  'meeting_booking',
+  'waitlist',
+] as const;
+
+export type FormRescueFormId = (typeof FORM_RESCUE_FORM_IDS)[number];
+
+export function isFormRescueFormId(value: unknown): value is FormRescueFormId {
+  return typeof value === 'string' && (FORM_RESCUE_FORM_IDS as readonly string[]).includes(value);
+}
+
+/**
+ * Fields whose VALUES a draft keeps: who the visitor is and where they work.
+ * Covers both naming schemes in use (the contact form's `name` / `companySize`,
+ * the meeting booking's HubSpot `firstName` / `company` / `jobtitle`).
+ * Free text (`message`) and phone numbers are reported as filled only.
+ */
+export const FORM_RESCUE_VALUE_FIELDS = [
+  'email',
+  'name',
+  'firstName',
+  'lastName',
+  'company',
+  'jobtitle',
+  'companySize',
+  'linkedin_url',
+] as const;
+
+/** Never send or store these, whatever the allowlist says. */
+const EXCLUDED_FIELD_PATTERN =
+  /pass(word|code)?|card|cvv|cvc|ssn|social.?security|iban|bank|routing|token|secret|otp|pin$/i;
+
+export function isExcludedRescueField(name: string): boolean {
+  return EXCLUDED_FIELD_PATTERN.test(name);
+}
+
+/** Longest value a draft keeps per field. */
+export const FORM_RESCUE_MAX_VALUE_CHARS = 200;
+/** Save this long after the visitor stops typing. */
+export const FORM_RESCUE_DEBOUNCE_MS = 1500;
+/** Most fields a draft reports (filled names), a bound on the payload. */
+export const FORM_RESCUE_MAX_FIELDS = 40;
+
+/** Body keys a form's SUBMIT carries so the host can close the matching draft. */
+export const FORM_RESCUE_ATTEMPT_FIELD = 'form_attempt_id';
+export const FORM_RESCUE_RESUME_FIELD = 'form_resume_token';
+/** Every rescue key that rides in a submit body. Hosts forwarding a payload upstream strip by THIS array. */
+export const FORM_RESCUE_SUBMIT_KEYS = [FORM_RESCUE_ATTEMPT_FIELD, FORM_RESCUE_RESUME_FIELD] as const;
+
+/** Query parameter a resume link carries. */
+export const FORM_RESCUE_RESUME_PARAM = 'resume';
+
+/** Draft lifecycle. `submitted` is final; `rescued` can still become `submitted`. */
+export const FORM_DRAFT_STATUSES = ['started', 'rescuable', 'rescued', 'submitted'] as const;
+export type FormDraftStatus = (typeof FORM_DRAFT_STATUSES)[number];
+
+/** Why a due draft was settled WITHOUT alerting the team (stored on the draft). */
+export const FORM_RESCUE_SKIP_REASONS = {
+  finishedElsewhere: 'finished_elsewhere',
+  alreadyRescued: 'already_rescued',
+  internal: 'internal_email',
+} as const;
+export type FormRescueSkipReason = (typeof FORM_RESCUE_SKIP_REASONS)[keyof typeof FORM_RESCUE_SKIP_REASONS];
+
+/** Same shape the host's `contact_submissions.email` check accepts. */
+const EMAIL_PATTERN = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/;
+
+export function isRescueEmail(value: unknown): value is string {
+  return typeof value === 'string' && value.length <= FORM_RESCUE_MAX_VALUE_CHARS && EMAIL_PATTERN.test(value.trim());
+}
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isFormAttemptId(value: unknown): value is string {
+  return typeof value === 'string' && UUID_PATTERN.test(value);
+}
+
+function isFilled(value: unknown): boolean {
+  if (value == null) return false;
+  if (typeof value === 'string') return value.trim().length > 0;
+  if (typeof value === 'boolean') return value;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.values(value as Record<string, unknown>).some(isFilled);
+  return true;
+}
+
+/**
+ * Keep only allowlisted, non-excluded string values, trimmed and capped.
+ * The ONE filter, run by the browser before sending and by the host before storing.
+ */
+export function sanitizeRescueValues(values: Record<string, unknown> | null | undefined): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (!values || typeof values !== 'object') return out;
+  for (const key of FORM_RESCUE_VALUE_FIELDS) {
+    if (isExcludedRescueField(key)) continue;
+    const raw = values[key];
+    if (typeof raw !== 'string') continue;
+    const trimmed = raw.trim().slice(0, FORM_RESCUE_MAX_VALUE_CHARS);
+    if (trimmed) out[key] = trimmed;
+  }
+  return out;
+}
+
+/** Names of the given fields that hold something, credentials never included. */
+export function filledRescueFields(values: Record<string, unknown>, fieldNames: readonly string[]): string[] {
+  return fieldNames
+    .filter(name => !isExcludedRescueField(name) && isFilled(values[name]))
+    .slice(0, FORM_RESCUE_MAX_FIELDS);
+}
+
+export function rescueCompletionPct(filledCount: number, totalCount: number): number {
+  if (totalCount <= 0) return 0;
+  return Math.max(0, Math.min(100, Math.round((filledCount / totalCount) * 100)));
+}
+
+/** A field NAME the host stores (`last_field`, `fields_filled`); bounded, printable. */
+export function sanitizeRescueFieldName(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return /^[A-Za-z0-9_.-]{1,64}$/.test(trimmed) && !isExcludedRescueField(trimmed) ? trimmed : null;
+}
+
+/** A form's progress at one moment: allowlisted values, filled field names, position. */
+export interface FormDraftProgress {
+  values: Record<string, string>;
+  fields_filled: string[];
+  last_field: string | null;
+  completion_pct: number;
+}
+
+/** What the browser sends on every save (`POST <formDraftsUrl>`), beside the humanity signals. */
+export interface FormDraftSaveRequest extends FormDraftProgress {
+  /** The attempt's idempotency key: every save of one attempt updates one draft. */
+  attempt_id: string;
+  form_id: FormRescueFormId;
+  source_path: string;
+  utm?: Partial<Record<'source' | 'medium' | 'campaign' | 'content' | 'term', string>>;
+}
+
+/** What the host answers a resume link with: the allowlisted values, nothing internal. */
+export interface FormDraftResumeResponse {
+  form_id: FormRescueFormId;
+  values: Record<string, string>;
+}
+
+/** The PostHog events this feature emits. Properties are ids, names and numbers, never values. */
+export const FORM_RESCUE_EVENTS = {
+  started: 'form_started',
+  progress: 'form_progress',
+  leadCaptured: 'form_lead_captured',
+  abandoned: 'form_abandoned',
+  submitted: 'form_submitted',
+  rescued: 'form_rescued',
+  resumed: 'form_resumed',
+} as const;
+
+type AnalyticsValue = string | number | boolean | string[] | null;
+
+/**
+ * Send one form event to PostHog when the page loaded it (GTM exposes
+ * `window.posthog`); a no-op otherwise. Never throws.
+ */
+export function captureFormRescueEvent(event: string, properties: Record<string, AnalyticsValue>): void {
+  try {
+    if (typeof window === 'undefined') return;
+    const ph = (window as unknown as { posthog?: { capture?: (e: string, p: object) => void } }).posthog;
+    if (typeof ph?.capture === 'function') ph.capture(event, properties);
+  } catch {
+    // Analytics never breaks a form.
+  }
+}

package/src/utils/index.ts

@@ -387,6 +387,11 @@ export {
 // `./utils/humanity-signals` for server-only consumers.
 export * from './humanity-signals';
 
+// Form rescue rules (allowlist, exclusions, caps, lifecycle) — pure + server-safe
+// so the host's draft endpoint re-applies the same filter the browser hook runs.
+// Also exported via the granular subpath `./utils/form-rescue`.
+export * from './form-rescue';
+
 // Doc-source viewer utilities (path parsing, tree building, section extraction,
 // embed-URL conversion) — single home for all doc-viewer pure helpers across
 // hub + lib consumers (knowledge-base, data-room, and future sources).