@parag.more.withsurface.com/forms-sdk 0.1.4 → 0.1.5

package/dist/types/core/engine/formEngine.d.ts

@@ -3,37 +3,6 @@ import { type Unsubscribe } from "../events/emitter";
 import type { FormJourneyTracker, FormJourneyTransitionReason } from "../events/formJourneyTracker";
 import { type PushEventClient } from "../events/pushEvents";
 import { type AnswerStates, type ExternalStates } from "./responsePayload";
-/**
- * The headless step engine (forms-sdk-plan.md §2.2): answers, traversal,
- * response writes, and lifecycle events over the modules this stack built.
- * Native semantics preserved:
- *
- * - **Partial saves on forward step change only** (row 23): first forward
- *   move creates the response, later moves update it, and every write sends
- *   the id of the step being *left* — all gated by
- *   `settings.trackPartialResponses` except the finishing write, which always
- *   happens.
- * - **Finished/invalid derivation** (row 27): a resolved next step of
- *   `"END"`/`"INVALID"`/`undefined` finishes the form; `"INVALID"`
- *   disqualifies.
- * - **Step transition events** (row 31): the `form_step_submitted` +
- *   `form_step_viewed` batch with `stepCompletionTime` in seconds since the
- *   engine was created (native's `initialRenderTime`), skipped when the form
- *   finishes (native returns before emitting on `"END"`).
- * - `markViewed` mirrors native's view actions: `form_viewed` + first-step
- *   `form_step_viewed`, once.
- * - Backward navigation never writes (native only re-arms `stepIdToSubmit`).
- *
- * **The engine does not evaluate routing** (Decisions #6): the customer's own
- * code owns navigation. `next()`/`back()` are linear conveniences,
- * `goToStep()` is the explicit move — forward jumps carry full forward
- * semantics (step events, journey transition, partial write), jumps to an
- * already-visited step rewind like `back()` (no write). Disqualification is
- * the explicit `disqualify()` verb — in native it was a routing outcome (the
- * `INVALID` sentinel), so without routing it needs its own API. The pluggable
- * `resolveNextStep` remains as the headless hook for callers who express
- * their routing as a resolver instead of imperative `goToStep` calls.
- */
 export type ResolvedNextStep = {
     stepId: string;
     reason?: FormJourneyTransitionReason;
@@ -72,30 +41,23 @@ export type FormEngineEvents = {
 export type FormEngineState = {
     currentStepId: string;
     answers: AnswerStates;
-    /** Pseudo-answer states riding every write (URL_DATA attribution, enrichment results, …). */
     externalStates: ExternalStates;
     responseId: string | null;
-    /** From the create reply; with the responseId it authorizes a later resume (persist both). */
     resumeToken: string | null;
     finished: boolean;
 };
 export type FormEngine = {
     setAnswer: (questionId: string, state: Record<string, unknown>) => void;
-    /** Writes a pseudo-answer external state (enrichment results, custom attribution) that rides every subsequent save. */
     setExternalState: (id: string, state: {
         type: string;
     } & Record<string, unknown>) => void;
-    /** Merges keys into the response `meta` object carried by every subsequent save (post-finish it amends the stored response). */
     mergeMeta: (partial: Record<string, unknown>) => void;
     next: () => Promise<void>;
     back: () => void;
-    /** Customer-owned navigation (Decisions #6): forward jumps save like next(), visited-step jumps rewind like back(). */
     goToStep: (stepId: string) => Promise<void>;
     submit: () => Promise<void>;
-    /** Finishes the form as disqualified (`invalidResponse: true`) — the explicit replacement for native's INVALID routing outcome. */
     disqualify: () => Promise<void>;
     savePartial: () => Promise<void>;
-    /** Resolves when every write queued so far has settled — await it before tearing the page down (test harnesses, SPA unmounts). */
     flush: () => Promise<void>;
     markViewed: () => void;
     on: <K extends keyof FormEngineEvents>(event: K, handler: (payload: FormEngineEvents[K]) => void) => Unsubscribe;
@@ -105,7 +67,6 @@ export type FormEngine = {
 export declare const createFormEngine: ({ formId, environmentId, steps, transport, resolveNextStep, trackPartialResponses, trackCookies, externalStates, meta, identity, pushEvents, formJourney, preview, resume, }: {
     formId: string;
     environmentId?: string;
-    /** Ordered logical steps of the form record (the data contract). */
     steps: Array<{
         id: string;
         endStepKind?: "thank_you" | "disqualified";
@@ -116,11 +77,6 @@ export declare const createFormEngine: ({ formId, environmentId, steps, transpor
     trackCookies?: boolean;
     externalStates?: ExternalStates;
     meta?: Record<string, unknown>;
-    /**
-     * Read at every write/event, not captured at construction — a re-identify
-     * (SurfaceForm.identify after cache expiry) must attribute subsequent
-     * responses and events to the current visitor, not the boot-time one.
-     */
     identity?: () => {
         fingerprint?: string;
         leadSessionId?: string;
@@ -128,18 +84,9 @@ export declare const createFormEngine: ({ formId, environmentId, steps, transpor
     };
     pushEvents?: PushEventClient;
     formJourney?: FormJourneyTracker;
-    /** Preview mode never writes (§2.2): traversal and events run, responses are never created. */
     preview?: boolean;
-    /**
-     * Resume a stored response (row 28): the seeded responseId turns every write
-     * into an update (no duplicate row), and the seeded answers ride along in
-     * the full-answer-set resend. Answers are keyed by questionId and seeded
-     * under the first step — the wire flattens steps, and presentation (which
-     * step to show) is the caller's own navigation.
-     */
     resume?: {
         responseId: string;
         answers?: Record<string, Record<string, unknown>>;
     };
 }) => FormEngine;
-//# sourceMappingURL=formEngine.d.ts.map

package/dist/types/core/engine/formEngine.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=formEngine.test.d.ts.map

package/dist/types/core/engine/redirect.d.ts

@@ -1,25 +1,3 @@
-/**
- * Redirect handling (forms-sdk-plan.md rows 17/48), mirroring form-render's
- * `handleRedirect.ts`:
- *
- * - Identity handoff: `leadId` and `sessionId` are appended as query params so
- *   the destination page's tag/SDK resolves the same visitor (row 17).
- * - Protocol default matches `addProtocolToUrl` verbatim, including its quirk:
- *   the check is `startsWith("https")`, so an explicit `http://` URL gets
- *   double-prefixed. Replicated, not fixed — it's on the plan's
- *   replicate-then-review list territory (Phase 0 item 5); the parity harness
- *   compares against native.
- * - Unparseable URLs pass through unchanged, blank URLs redirect nowhere.
- * - `CurrentWindow` navigates `window.location` — the SDK runs first-party,
- *   which is exactly what native's `window.parent.location` resolves to on a
- *   top-level page. `NewTab` opens `_blank`.
- * - Preview never navigates (native gates on preview/editing screens).
- *
- * The step engine owns *when* to redirect (per-step + thank-you triggers and
- * the `redirectTimeout ?? 400 ms` delay — the default is exported here);
- * parent-param forwarding via `redirectUrlParams` templating lands with the
- * external-state store work (row 56).
- */
 export type RedirectType = "NewTab" | "CurrentWindow";
 export declare const DEFAULT_REDIRECT_TIMEOUT_MS = 400;
 export declare const buildRedirectUrl: (url: string, { leadId, sessionId }?: {
@@ -33,4 +11,3 @@ export declare const performRedirect: ({ url, redirectType, leadId, sessionId, p
     sessionId?: string;
     preview?: boolean;
 }) => void;
-//# sourceMappingURL=redirect.d.ts.map

package/dist/types/core/engine/redirect.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=redirect.test.d.ts.map

package/dist/types/core/engine/responsePayload.contract.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=responsePayload.contract.test.d.ts.map

package/dist/types/core/engine/responsePayload.d.ts

@@ -1,34 +1,8 @@
-/**
- * Response payload builders (forms-sdk-plan.md rows 24-26), mirroring
- * form-render's `createResponseApiPayload` exactly — the semantics here are
- * load-bearing server contracts:
- *
- * - **Full answer-set resend on every write** (row 26): all steps' answers
- *   plus every external-state entry as a pseudo-answer keyed by its stateId.
- *   Server-side UTM preservation depends on the URL_DATA entry riding every
- *   update.
- * - `SCHEDULER_AVAILABILITY_DATA` entries are transient client-only data and
- *   are never persisted.
- * - Surface-native booking detection: the first answer with
- *   `eventScheduled: true` and a non-Calendly/Cal.com `uri` stamps
- *   `meta.bookingId`.
- * - `enrichedFields` precedence: person-attribute enrichment wins over the
- *   processed APOLLO_EMAIL_ENRICHMENT external state, `{}` as the floor.
- * - `meta.cookies` is stripped when `trackCookies` is off.
- * - Creates pin `responseShapeVersion: "2.0"`; updates carry `responseId`.
- *
- * Types are local structural mirrors of `ZFormResponseData` /
- * `ZFormUpdateResponseData` (zero-runtime-deps); the contract test validates
- * built payloads against the real schemas. Answer/external-state entry shapes
- * are pass-through records — component state shapes belong to the engine.
- */
 export type SingleFormResponse = {
     questionId: string;
     response: Record<string, unknown>;
 };
-/** Answers grouped per step, keyed stepId → questionId → component state. */
 export type AnswerStates = Record<string, Record<string, Record<string, unknown>>>;
-/** External state entries keyed by stateId; `type` discriminates (URL_DATA, enrichment, …). */
 export type ExternalStates = Record<string, {
     type: string;
 } & Record<string, unknown>>;
@@ -61,7 +35,6 @@ type BuildPayloadOptions = {
     invalidResponse: boolean;
     trackCookies: boolean;
     meta?: Record<string, unknown>;
-    /** Person-attribute enrichment; wins over external-state enrichment like native. */
     personAttributeEnrichedFields?: Record<string, unknown>;
     fingerprint?: string;
     leadSessionId?: string;
@@ -71,4 +44,3 @@ export declare const createUpdateResponsePayload: (options: BuildPayloadOptions
     responseId: string;
 }) => FormUpdateResponsePayload;
 export {};
-//# sourceMappingURL=responsePayload.d.ts.map

package/dist/types/core/engine/responsePayload.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=responsePayload.test.d.ts.map

package/dist/types/core/engine/urlData.contract.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=urlData.contract.test.d.ts.map

package/dist/types/core/engine/urlData.d.ts

@@ -1,18 +1,3 @@
-/**
- * Attribution capture (forms-sdk-plan.md row 56): the `URL_DATA`
- * external-state entry that rides every response write and feeds UTM/source
- * attribution. Mirrors the URL-config branch of form-render's
- * `buildExternalStateStore` — same shape (`fullUrl`/`params`/`referrer`/
- * `cookies`, wire-validated against `ZURLData` in the contract test), same
- * `defaultUrl` precedence, same swallow-on-malformed behavior.
- *
- * One structural simplification the self-hosted model earns (plan §4.1): the
- * SDK runs in the page it measures, so `fullUrl`/`referrer`/`cookies` are
- * read directly from `location`/`document` — native needs them relayed
- * through `?url=`/`?referrer=`/`?cookies=` query params by the tag, including
- * cookies as a JSON blob. Cookie capture stays gated by the same
- * `trackCookies` setting.
- */
 export type UrlData = {
     type: "URL_DATA";
     fullUrl?: string;
@@ -23,8 +8,6 @@ export type UrlData = {
 export declare const constructUrlParamsObject: (url: string) => Record<string, string>;
 export declare const parseCookiesObject: (cookieString: string) => Record<string, string>;
 export declare const buildUrlData: ({ defaultUrl, trackCookies, }?: {
-    /** Config-pinned URL that wins over the live page URL, like native. */
     defaultUrl?: string;
     trackCookies?: boolean;
 }) => UrlData;
-//# sourceMappingURL=urlData.d.ts.map

package/dist/types/core/engine/urlData.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=urlData.test.d.ts.map

package/dist/types/core/engine/urlPrefill.d.ts

@@ -1,11 +1,3 @@
-/**
- * URL prefill parsing (forms-sdk-plan.md row 19), same syntax as the native
- * runtime's `useFormUrlParameters`/`parseQuestionId`: any
- * `?<questionId>_<fieldName>=value` query param prefills a field. The param
- * name splits on the FIRST underscore (field names may contain more), both
- * sides are trimmed, `url`/`referrer`/`cookies` are reserved for attribution,
- * and params without an underscore are ignored (no field to target).
- */
 export type ParsedUrlQuestionId = {
     originalId: string;
     questionId: string;
@@ -18,4 +10,3 @@ export declare const parseQuestionId: (input: string) => {
     fieldName: string | null;
 };
 export declare const parsePrefillParams: (search: string | URLSearchParams) => Record<string, ParsedUrlQuestionId[]> | null;
-//# sourceMappingURL=urlPrefill.d.ts.map

package/dist/types/core/engine/urlPrefill.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=urlPrefill.test.d.ts.map

package/dist/types/core/events/dropoffDetection.d.ts

@@ -1,21 +1,7 @@
 import type { PushEventClient } from "./pushEvents";
-/**
- * `form_step_dropoff` beacon (forms-sdk-plan.md row 32), form-render's
- * `useBeforeUnload` semantics without React: on `pagehide` — the only
- * teardown event that still delivers beacons reliably — emit the drop-off
- * event for the step the visitor abandoned, but only after the form was
- * started and never for bfcache suspensions (`event.persisted`), which are
- * not abandonment.
- *
- * State is read through a getter at fire time because the current step and
- * session change after the listener attaches (native reads refs for the same
- * reason). Delivery rides the pushEvent client, whose transport is
- * sendBeacon-first — the property that makes a pagehide send survivable.
- */
 export declare const observeDropoff: (pushEventClient: PushEventClient, getState: () => {
     started: boolean;
     formId: string;
     stepId: string;
     sessionId?: string;
 }) => (() => void);
-//# sourceMappingURL=dropoffDetection.d.ts.map

package/dist/types/core/events/dropoffDetection.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=dropoffDetection.test.d.ts.map

package/dist/types/core/events/emitter.d.ts

@@ -1,23 +1,6 @@
-/**
- * Instance-scoped typed event emitter — the primitive behind the SDK's
- * public `form.on(...)` lifecycle surface (forms-sdk-plan.md §2.2) and the
- * store-subscription contract adapters build on (§2.9).
- *
- * Exists because the SDK cannot use Node's EventEmitter (zero runtime deps,
- * browser bundle) and must not reproduce form-render's module-level
- * singleton listeners, which break multi-form pages (§2.7). Handler
- * exceptions are isolated per handler: a throwing host callback never breaks
- * the engine or sibling handlers — the never-break-the-host-page guarantee
- * applied to the callback boundary.
- *
- * The concrete SDK event map (viewed/started/stepChanged/…) is owned by the
- * step engine, which defines the payload shapes it emits; this module is
- * deliberately payload-agnostic.
- */
 export type Unsubscribe = () => void;
 export type Emitter<TEventMap extends Record<string, unknown>> = {
     on: <K extends keyof TEventMap>(event: K, handler: (payload: TEventMap[K]) => void) => Unsubscribe;
     emit: <K extends keyof TEventMap>(event: K, payload: TEventMap[K]) => void;
 };
 export declare const createEmitter: <TEventMap extends Record<string, unknown>>() => Emitter<TEventMap>;
-//# sourceMappingURL=emitter.d.ts.map

package/dist/types/core/events/emitter.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=emitter.test.d.ts.map

package/dist/types/core/events/formJourneyTracker.contract.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=formJourneyTracker.contract.test.d.ts.map

package/dist/types/core/events/formJourneyTracker.d.ts

@@ -1,22 +1,4 @@
 import type { Transport } from "../client/transport";
-/**
- * Form-journey step telemetry (forms-sdk-plan.md row 30): visits, transitions,
- * and outcomes beaconed to `POST /api/v1/form-journey/track`. A direct port of
- * form-render's `createFormJourneyTracker` — same ordinal bookkeeping, same
- * close-previous-visit timing, same 50-visit cap with `truncated`, same
- * freeze-on-terminal-outcome, same microtask coalescing (a transition
- * immediately followed by a terminal sends one beacon, so an in-progress
- * write can't race the disqualified one), and the same synchronous flush for
- * the `in_progress` terminal, which only fires from pagehide and cannot
- * depend on a microtask racing page teardown.
- *
- * Wire types are local structural mirrors of the Zod schemas in
- * `@surface/types/v1/formJourney` (zero-runtime-deps); the contract test
- * validates them against the real `ZFormJourneyTrackPayload`. The
- * `transitionMeta`/`matched` payloads are typed opaque here — they are
- * constructed by routing evaluation, which lands with the routing extraction,
- * and the tracker only passes them through.
- */
 export type FormJourneyOutcome = "in_progress" | "completed" | "partial" | "disqualified" | "dropped_off";
 export type FormJourneyTransitionReason = "initial" | "linear" | "conditional_match" | "default_fallback" | "prefill_jump" | "back_nav" | "auto_skip";
 export type FormJourneyVisit = {
@@ -66,4 +48,3 @@ export declare const createFormJourneyTracker: ({ transport, preview, }: {
     transport: Transport;
     preview?: boolean;
 }) => FormJourneyTracker;
-//# sourceMappingURL=formJourneyTracker.d.ts.map

package/dist/types/core/events/formJourneyTracker.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=formJourneyTracker.test.d.ts.map

package/dist/types/core/events/pushEvents.contract.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=pushEvents.contract.test.d.ts.map

package/dist/types/core/events/pushEvents.d.ts

@@ -1,18 +1,4 @@
 import type { Transport } from "../client/transport";
-/**
- * Client for the internal event pipeline `POST /api/v1/pushEvent`
- * (forms-sdk-plan.md row 33), mirroring form-render's `callPushEventApi`:
- * same wire shapes, same client-side bot filter, same required-field guard
- * (any invalid event drops the whole request), same beacon-first delivery.
- * Two deliberate departures, both decided in the plan: no PostHog mirror
- * (Surface-internal telemetry — §1D row 33) and a `preview` flag that blocks
- * every send so agent preview loops never pollute data (§2.2).
- *
- * The wire types below are structural mirrors of the Zod schemas in
- * `@surface/types/v1/surfaceEvent/model/types.ts` — local because the SDK
- * ships with zero runtime dependencies; the contract test in this directory
- * validates them against the real schemas.
- */
 export type SurfaceEventType = "form_viewed" | "form_started" | "form_completed" | "form_step_viewed" | "form_step_submitted" | "form_step_dropoff" | "form_question_submitted" | "response_submission_created" | "response_submission_error" | "script_initiated";
 export type SurfaceEventEntityType = "form" | "form_step" | "response";
 export type PushEventProperty = {
@@ -29,7 +15,6 @@ export type PushEventPayload = {
     leadId?: string;
     environmentId?: string;
 };
-/** The server accepts exactly one batch shape: a step transition pair. */
 export type PushEventBatch = {
     events: [
         PushEventPayload & {
@@ -59,4 +44,3 @@ export declare const createPushEventClient: ({ transport, preview, }: {
     transport: Transport;
     preview?: boolean;
 }) => PushEventClient;
-//# sourceMappingURL=pushEvents.d.ts.map

package/dist/types/core/events/pushEvents.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=pushEvents.test.d.ts.map

package/dist/types/core/events/startedDetection.d.ts

@@ -1,11 +1 @@
-/**
- * `form_started` detection (forms-sdk-plan.md row 22): native fires it on the
- * first deep-inequality between the current answer state and the snapshot
- * taken at mount, once per form instance (`DualPaneAdjustableForm`'s
- * `startedForm` ref + lodash `isEqual`). The detector captures the snapshot at
- * creation; `check(current)` returns true exactly once, on the first
- * divergence. The local deep-equal covers the answer-state shape (plain
- * objects, arrays, primitives) — key order insensitive, like lodash.
- */
 export declare const createStartedDetector: <T>(initial: T) => ((current: T) => boolean);
-//# sourceMappingURL=startedDetection.d.ts.map

package/dist/types/core/events/startedDetection.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=startedDetection.test.d.ts.map

package/dist/types/core/events/viewDetection.d.ts

@@ -1,15 +1 @@
-/**
- * `form_viewed` detection (forms-sdk-plan.md row 21): an IntersectionObserver
- * on the bound form root, firing the callback exactly once per observer —
- * form-render's `useDetectFormView` semantics with its React scaffolding
- * removed. The once-guard replaces native's belt-and-braces 1 s throttle:
- * with a single fire per instance there is nothing left to throttle. The
- * caller (bind layer / engine) emits `form_viewed` + first-step
- * `form_step_viewed`, exactly what native's throttled callback did.
- *
- * If `IntersectionObserver` is unavailable the callback fires immediately —
- * losing view analytics entirely is worse than counting a below-fold mount,
- * and native never handled this case (it would throw).
- */
 export declare const observeFormView: (element: Element, onViewed: () => void) => (() => void);
-//# sourceMappingURL=viewDetection.d.ts.map

package/dist/types/core/events/viewDetection.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=viewDetection.test.d.ts.map

package/dist/types/core/identity/browserFingerprint.d.ts

@@ -1,19 +1,3 @@
-/**
- * Canonical browser-fingerprint implementation for Surface lead identity.
- *
- * The lead-identity pipeline keys on the SHA-256 of `JSON.stringify` over the
- * collected fields, so the object's insertion order, value shapes, and falsy
- * fallbacks (`||`, not `??`) ARE the wire contract: any deviation produces a
- * different hash and splits one visitor into two leads. Do not reorder fields,
- * rename keys, or change fallback behavior here without a coordinated
- * migration.
- *
- * This module supersedes the two byte-identical copies it was lifted from —
- * `packages/form-render/src/lib/client/leads/browserFingerprint.ts` and the
- * public tag's `src/lead/fingerprint.ts` (trysurface/scripts) — which consume
- * it over time (forms-sdk-plan.md, parity row 9). The identity test in this
- * directory pins hash equality against the form-render copy.
- */
 export type Fingerprint = {
     deviceType: "Mobile" | "Desktop";
     screen: {
@@ -28,13 +12,10 @@ export type Fingerprint = {
     }>;
     os: string;
     language: string;
-    /** Absent (never null/empty) when `navigator.plugins` is null. */
     plugins?: string[];
     timezone: string;
     environmentId: string;
-    /** SHA-256 hex of the serialized fields above. */
     id: string;
 };
 export declare function getHash(input: string): Promise<string>;
 export declare const getBrowserFingerprint: (environmentId: string) => Promise<Fingerprint>;
-//# sourceMappingURL=browserFingerprint.d.ts.map

package/dist/types/core/identity/browserFingerprint.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=browserFingerprint.test.d.ts.map

package/dist/types/core/identity/ensureIdentified.d.ts

@@ -1,21 +1,6 @@
 import type { Transport } from "../client/transport";
 import { type LeadSource } from "./identify";
 import { type CachedLeadData } from "./leadDataCache";
-/**
- * The boot-sequence identity step (forms-sdk-plan.md §2.2): resolve the
- * visitor before any response write, since attribute sync silently no-ops for
- * responses whose lead was never identified (row 60). Mirrors the tag's
- * `identifyLead` flow: a fresh cache entry with a session and fingerprint
- * skips the network entirely; otherwise compute the fingerprint, carry any
- * cached leadId/session forward so the server can preserve identity, and
- * cache the result under the shared tag key.
- *
- * `preview: true` blocks the identify call outright — the preview contract
- * (§2.2) is that drafts never create leads. Concurrent calls (multi-form
- * pages) may race one identify each; that is safe — the server find-or-creates
- * by fingerprint, so both resolve to the same lead — and avoids the tag's
- * module-level in-flight flag, which the SDK's instance-scoped rule forbids.
- */
 export declare const ensureIdentified: ({ transport, environmentId, formId, pageUrl, source, preview, }: {
     transport: Transport;
     environmentId: string;
@@ -24,4 +9,3 @@ export declare const ensureIdentified: ({ transport, environmentId, formId, page
     source?: LeadSource;
     preview?: boolean;
 }) => Promise<CachedLeadData | null>;
-//# sourceMappingURL=ensureIdentified.d.ts.map

package/dist/types/core/identity/ensureIdentified.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=ensureIdentified.test.d.ts.map

package/dist/types/core/identity/identify.contract.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=identify.contract.test.d.ts.map

package/dist/types/core/identity/identify.d.ts

@@ -1,18 +1,4 @@
 import type { Transport } from "../client/transport";
-/**
- * Wrapper for `POST /api/v1/lead/identify` (forms-sdk-plan.md row 10),
- * mirroring form-render's `identifyLeadForFormRequest`: same payload fields,
- * same URL normalization (trailing slashes stripped from href and pathname),
- * same keepalive delivery, same `data.data` response unwrap, null on any
- * failure. The wire types are structural mirrors of `ZLeadIdentifyPayload`
- * (`@surface/types/v1/lead/app/types.ts`) — local because the SDK ships with
- * zero runtime dependencies; the contract test validates them against the
- * real schema.
- *
- * `source` defaults to `"sdkForm"` — the dedicated SDK value (Decisions #8),
- * so SDK-originated leads stay distinguishable from the native runtime's
- * `"surfaceForm"` in the leads hub and analytics.
- */
 export type LeadSource = "surfaceForm" | "htmlForm" | "websiteDeAnon" | "webhook" | "website" | "imported" | "scheduler" | "linkedin" | "sdkForm";
 export type IdentifyPayload = {
     environmentId: string;
@@ -45,4 +31,3 @@ export declare const buildIdentifyPayload: ({ environmentId, fingerprintId, page
     referrer?: string | null;
 }) => IdentifyPayload;
 export declare const identifyLead: (transport: Transport, payload: IdentifyPayload) => Promise<IdentifyResult | null>;
-//# sourceMappingURL=identify.d.ts.map

package/dist/types/core/identity/identify.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=identify.test.d.ts.map

package/dist/types/core/identity/journey.contract.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=journey.contract.test.d.ts.map

package/dist/types/core/identity/journey.d.ts

@@ -1,28 +1,12 @@
 import type { Transport } from "../client/transport";
-/**
- * Opt-in user-journey page-view tracking (forms-sdk-plan.md row 16), the
- * SDK's `journey: true` module. Mirrors the public tag's implementation
- * (trysurface/scripts `src/store/{user-journey,journey-cookies}.ts`, verified
- * at HEAD): same cookies (`surface_journey_id`, 60 d, eTLD+1 domain;
- * `surface_recent_visit`, 1 d), same duplicate-URL skip, same delivery split —
- * beacon when the journey id is already known (nothing to read back), fetch
- * when it isn't so the server-issued id can be captured — and the same
- * history-patching SPA route detection.
- *
- * Journey→response stitching stays server-side (UTM backfill on response
- * create); the client's only job is delivering page views under a stable id.
- */
 export declare const JOURNEY_COOKIE_NAME = "surface_journey_id";
 export declare const RECENT_VISIT_COOKIE_NAME = "surface_recent_visit";
 export type JourneyTracker = {
     trackPageView: (url?: string) => Promise<void>;
-    /** Patches history + popstate; returns a teardown restoring the originals. */
     observeRouteChanges: () => () => void;
-    /** Deletes both journey cookies — the native clear-on-first-step-completion hook. */
     clear: () => void;
 };
 export declare const createJourneyTracker: ({ transport, environmentId, }: {
     transport: Transport;
     environmentId: string;
 }) => JourneyTracker;
-//# sourceMappingURL=journey.d.ts.map

package/dist/types/core/identity/journey.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=journey.test.d.ts.map

package/dist/types/core/identity/journey.testStubs.d.ts

@@ -1,5 +1,3 @@
-/** Minimal DOM stub for journey tests: cookie jar honoring max-age deletion, location, referrer. */
 export declare const stubJourneyDom: ({ href }?: {
     href?: string;
 }) => Map<string, string>;
-//# sourceMappingURL=journey.testStubs.d.ts.map

package/dist/types/core/identity/leadDataCache.d.ts

@@ -1,18 +1,3 @@
-/**
- * TTL-stamped lead-identity cache (forms-sdk-plan.md row 11), byte-compatible
- * with the public tag's `surfaceLeadData` localStorage entry — same key, same
- * shape, same 10-minute TTL, same remove-on-expiry read semantics
- * (trysurface/scripts `src/lead/identify.ts`).
- *
- * Sharing the tag's key IS the interop rule (plan §4.1): on a page where the
- * tag is also installed, the SDK reads the identity the tag already resolved
- * and skips its own identify — and vice versa — so both agree on the visitor
- * without any cross-component protocol.
- *
- * Every access is guarded: no localStorage (SSR) reads as a cache miss, and
- * storage exceptions (Safari private mode, quota) are swallowed — cache loss
- * only costs an extra identify round-trip.
- */
 export declare const LEAD_DATA_STORAGE_KEY = "surfaceLeadData";
 export declare const LEAD_DATA_TTL_MS: number;
 export type CachedLeadData = {
@@ -24,4 +9,3 @@ export type CachedLeadData = {
 };
 export declare const readLeadData: () => CachedLeadData | null;
 export declare const writeLeadData: (data: Omit<CachedLeadData, "expiry">) => void;
-//# sourceMappingURL=leadDataCache.d.ts.map

package/dist/types/core/identity/leadDataCache.test.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=leadDataCache.test.d.ts.map

package/dist/types/enrichment/attachEnrichment.d.ts

@@ -1,25 +1,5 @@
 import type { Transport } from "../core/client/transport";
 import type { FormEngine } from "../core/engine/formEngine";
-/**
- * Real-time identity enrichment for SDK forms (field-run finding 4.10): the
- * native renderer fires `/api/v1/services/enrichment/realtime` on blur of the
- * IdentityInfo `enrichmentSourceField` (or `websiteUrl`, or EmailForm's email)
- * and stores the result as the `selfServeEnrichment` APOLLO_EMAIL_ENRICHMENT
- * external state — which the response payload forwards as `enrichedFields`
- * and which drives field autofill. The SDK has no blur moment (headless
- * callers have no DOM at all), so the trigger is a debounced answer-watch: a
- * candidate value that is a valid email/domain and has been stable for
- * `DEBOUNCE_MS` fires once (deduped per value, native semantics); completing
- * a step flushes the pending debounce so a type-then-advance never loses the
- * window. The request is never awaited — submission must not block on the
- * vendor API — so a result can resolve after the finishing write; the engine
- * persists it anyway by amending the stored response on setExternalState.
- * Results merge existing-keys-win, exactly like native's G2 rule — a later
- * trigger only fills gaps.
- *
- * The provider key never reaches the page: the endpoint resolves it
- * server-side and is rate-limited per-IP and per-form.
- */
 export type EnrichmentSource = {
     questionId: string;
     fieldNames: string[];
@@ -32,4 +12,3 @@ export type AttachEnrichmentOptions = {
     sources: EnrichmentSource[];
 };
 export declare const attachEnrichment: ({ engine, transport, formId, sources, }: AttachEnrichmentOptions) => (() => void);
-//# sourceMappingURL=attachEnrichment.d.ts.map