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

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

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

package/dist/types/index.d.ts

@@ -25,4 +25,3 @@ export { LEAD_DATA_STORAGE_KEY, LEAD_DATA_TTL_MS, readLeadData, writeLeadData, t
 export { ENRICHMENT_STATE_ID, attachEnrichment, type AttachEnrichmentOptions, type EnrichmentSource, } from "./enrichment/attachEnrichment";
 export { SurfaceForms, type SurfaceForm, type SurfaceFormsInitOptions } from "./surfaceForms";
 export { attachEmailValidation, type AttachEmailValidationOptions } from "./validation/attachEmailValidation";
-//# sourceMappingURL=index.d.ts.map

package/dist/types/react/index.d.ts

@@ -1,2 +1 @@
 export { useSurfaceForm, type UseSurfaceFormResult } from "./useSurfaceForm";
-//# sourceMappingURL=index.d.ts.map

package/dist/types/react/ssr.test.d.ts

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

package/dist/types/react/useSurfaceForm.d.ts

@@ -1,14 +1,4 @@
 import type { FormEngine, FormEngineState } from "../core/engine/formEngine";
-/**
- * React adapter (forms-sdk-plan.md §2.9): a thin `useSyncExternalStore`
- * subscription over the headless engine's store contract. The host renders
- * the current step from `state` with controlled inputs; every action is the
- * engine's own method, so engine semantics are identical to the `bind/` mode
- * by construction — only who applies visibility differs.
- *
- * Server snapshots reuse `engine.state()`: the engine is SSR-safe to create
- * (no DOM access until interaction), so hydration sees the initial step.
- */
 export type UseSurfaceFormResult = {
     state: FormEngineState;
     setAnswer: FormEngine["setAnswer"];
@@ -22,4 +12,3 @@ export type UseSurfaceFormResult = {
     on: FormEngine["on"];
 };
 export declare const useSurfaceForm: (engine: FormEngine) => UseSurfaceFormResult;
-//# sourceMappingURL=useSurfaceForm.d.ts.map

package/dist/types/react/useSurfaceForm.test.d.ts

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

package/dist/types/surfaceForms.d.ts

@@ -3,118 +3,46 @@ import { type RuntimeConfig } from "./core/client/runtimeConfig";
 import { type FormEngine, type ResolveNextStep } from "./core/engine/formEngine";
 import type { LeadSource } from "./core/identity/identify";
 import { type TrackingSettings } from "./tracking/attachTracking";
-/**
- * The public entry point (forms-sdk-plan.md §2.2): composes the boot sequence
- * in the native, load-bearing order — identify before the first write (row
- * 60: attribute sync silently no-ops otherwise) — then wires events, journey,
- * drop-off, and the optional DOM binding around one engine instance.
- *
- * **The form definition boots from the runtime-config endpoint** (§2.3,
- * Decisions #7): when `steps` is omitted, init fetches the published record
- * and derives the step order, the behavioral settings gates, and the expected
- * questionIds for the §4.3 drift warning. Caller-provided `steps`/`settings`/
- * `expectedQuestionIds` still win — offline tests and agents that already
- * hold the record skip the fetch entirely.
- *
- * `preview: true` replicates the native guarantee that previews never pollute
- * data (§2.2): identify, response writes, pushEvents, form-journey, and the
- * journey module are all blocked client-side.
- */
 export type SurfaceFormsInitOptions = {
     environmentId: string;
     formId: string;
-    /** Ordered logical steps of the form record; omitted = fetched from runtime-config. */
     steps?: Array<{
         id: string;
         endStepKind?: "thank_you" | "disqualified";
     }>;
-    /**
-     * Behavioral gates + customer-tag config (rows 51–55). Omitted values fill
-     * from runtime-config ONLY when `steps` is also omitted (the record fetch) —
-     * caller-provided `steps` skip the fetch entirely, so pass tracking settings
-     * explicitly in that offline mode.
-     */
     settings?: {
         trackPartialResponses?: boolean;
         trackCookies?: boolean;
     } & TrackingSettings;
     apiBaseUrl?: string;
-    /** Enables the bind/ layer + view detection on this root. */
     container?: Element;
-    /** Stateful questionIds from the record; unbound ones get the §4.3 runtime warning. */
     expectedQuestionIds?: string[];
-    /** Routing evaluation; defaults to linear order until the extracted routing module lands. */
     resolveNextStep?: ResolveNextStep;
-    /** Seeds a URL_DATA external-state entry under this id (attribution, row 56). */
     urlDataStateId?: string;
     source?: LeadSource;
-    /** Page-view tracking module (tag parity), default off. */
     journey?: boolean;
-    /**
-     * Automatic waterfall email validation (row 37), default off: watches
-     * email answers (debounced, per-address verdicts, fail-open) and annotates
-     * the response `meta` with native's `isEmailValid`/`emailValidation`/
-     * `emailValidationFailed` keys. Opt-in because verdicts spend the form
-     * owner's validator quota. The on-demand `validateEmail` on the handle is
-     * always available and shares the same per-address cache.
-     */
     emailValidation?: boolean;
     preview?: boolean;
-    /**
-     * Signed token from the create_form / get_sdk_binding_map replies; with
-     * `preview: true` it unlocks the DRAFT config of a never-published form.
-     * Without it, preview serves the published config.
-     */
     previewToken?: string;
-    /**
-     * Resume a stored response: pass the `responseId` + `resumeToken` pair a
-     * previous session's create returned (`state().resumeToken`, or the `saved`
-     * event). Boot fetches the stored answers through the token-gated read-back
-     * and seeds the engine — writes become updates and earlier answers are
-     * preserved; a failed fetch warns and starts fresh. Ignored in preview.
-     */
     resume?: {
         responseId: string;
         resumeToken: string;
     };
-    /** Logs every captured answer and warns on states the server would reject (unknown questionId, wrong/missing type, malformed choices). Development aid; never enable in production. */
     debug?: boolean;
     meta?: Record<string, unknown>;
 };
 export type SurfaceForm = Pick<FormEngine, "setAnswer" | "setExternalState" | "next" | "back" | "goToStep" | "submit" | "disqualify" | "savePartial" | "flush" | "markViewed" | "on" | "state" | "subscribe"> & {
-    /** Re-runs identify (e.g. after an SPA route change); cache makes it cheap. */
     identify: () => Promise<unknown>;
-    /**
-     * On-demand waterfall email validation (row 37): resolves a per-address
-     * deliverability verdict, cached for the form's lifetime and fail-open on
-     * validator outage. Use it to gate your own navigation:
-     * `if ((await form.validateEmail(value)).isValid) form.next()`.
-     * In preview it resolves a synthetic valid verdict without network.
-     */
     validateEmail: (email: string) => Promise<EmailValidationResult>;
-    /**
-     * Records caller-computed values (a qualification score, an A/B bucket, …)
-     * onto the response `meta` — they ride the next save, or amend the stored
-     * response when the form already finished. SDK-owned keys
-     * (`surfaceTagStatus` and the email-validation verdicts) are dropped with a
-     * console warning: dashboards trust those.
-     */
     mergeMeta: (partial: Record<string, unknown>) => void;
-    /**
-     * What actually runs in THIS environment — the record can declare features
-     * (an enrichment source field) that the environment does not back with a
-     * provider, and nothing else surfaces that.
-     */
     capabilities: {
         enrichment: boolean;
         emailValidation: boolean;
         tracking: boolean;
     };
-    /** The fetched published record (labels, component types); undefined when `steps` was caller-provided. */
     runtimeConfig?: RuntimeConfig;
     destroy: () => void;
 };
 export declare const SurfaceForms: {
     init: ({ environmentId, formId, steps, settings, apiBaseUrl, container, expectedQuestionIds, resolveNextStep, urlDataStateId, source, journey, emailValidation, preview, previewToken, debug, resume, meta, }: SurfaceFormsInitOptions) => Promise<SurfaceForm>;
 };
-//# sourceMappingURL=surfaceForms.d.ts.map

package/dist/types/surfaceForms.test.d.ts

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

package/dist/types/tracking/attachTracking.d.ts

@@ -1,27 +1,6 @@
 import type { FormEngine } from "../core/engine/formEngine";
 import { type AdConversionRule } from "./conversionRules";
 import { type VendorSettings } from "./vendors";
-/**
- * Phase-2 tracking runtime (forms-sdk-plan.md rows 51–55): binds one engine
- * instance to the customer-tag lifecycle events and the ad-conversion rule
- * engine. Trigger moments mirror `useConversionRules`' semantics translated
- * from React effects to engine events:
- *
- * - `form_started`: the response row landing (first `saved`) in a session that
- *   began without a responseId — a resume never refires.
- * - `step_submitted`: the first `stepCompleted` of the session.
- * - `reached_step`: every step that becomes current (including the initial
- *   one), once per step — back-nav never refires.
- * - terminal (`reached_qualified` + `form_submitted` union, deduped by rule):
- *   the `completed` event; a disqualified finish never fires.
- * - `email_provided` / `meeting_booked`: first non-empty email answer / first
- *   scheduler state with `eventScheduled` — detected via `subscribe`.
- *
- * Every rule fires once per instance; `responseId` stays the platform-side
- * dedupe key, so moments reached before the first write queue and flush when
- * `saved` delivers the id (native's pending-refs, minus the React plumbing).
- * All state is instance-scoped (§2.7) — two forms on one page track separately.
- */
 export type TrackingSettings = VendorSettings & {
     adsConversions?: AdConversionRule[];
 };
@@ -32,4 +11,3 @@ export type AttachTrackingOptions = {
     win?: Window;
 };
 export declare const attachTracking: ({ engine, formId, settings, win }: AttachTrackingOptions) => (() => void);
-//# sourceMappingURL=attachTracking.d.ts.map

package/dist/types/tracking/attachTracking.test.d.ts

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

package/dist/types/tracking/conversionRules.contract.test.d.ts

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

package/dist/types/tracking/conversionRules.d.ts

@@ -1,12 +1,3 @@
-/**
- * Ad-conversion rule engine (forms-sdk-plan.md row 55): a dependency-free port
- * of form-render's `adConversions/{evaluateRules,fireConversion}.ts` and the
- * `ZAdConversionRule` settings schema. The SDK always runs first-party, so the
- * native parent-page/postMessage/ack hop disappears — matching rules fire
- * directly on this window. Rule semantics, provider payloads, and the
- * `responseId` dedupe key are identical by construction; the contract test
- * validates these local types against the real Zod schema.
- */
 export type AdConversionProvider = "x" | "meta" | "openai" | "ga4" | "linkedin";
 export type AdConversionTrigger = "reached_qualified" | "form_submitted" | "reached_step" | "form_started" | "step_submitted" | "email_provided" | "meeting_booked";
 export type AdConversionCondition = {
@@ -77,11 +68,8 @@ export declare const DEFAULT_OPENAI_EVENT_NAME = "lead_created";
 export declare const matchesCondition: (condition: AdConversionCondition, params: TrackingParams) => boolean;
 export declare const matchesConditions: (conditions: AdConversionCondition[], params: TrackingParams, operator?: "and" | "or") => boolean;
 export declare const ruleToConversionEvent: (rule: AdConversionRule) => ConversionEvent | null;
-/** Rules firing for this trigger given the page's tracking params; `reached_step` also needs the step id to match. */
 export declare const selectFiringEvents: (rules: AdConversionRule[], trigger: AdConversionTrigger, params: TrackingParams, stepId?: string) => {
     rule: AdConversionRule;
     conversion: ConversionEvent;
 }[];
-/** Fire one conversion on this window. Best-effort: silent under ad blockers, never throws into the form. */
 export declare const fireConversion: (win: Window, conversion: ConversionEvent, ctx: FireContext) => boolean;
-//# sourceMappingURL=conversionRules.d.ts.map

package/dist/types/tracking/conversionRules.test.d.ts

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

package/dist/types/tracking/vendors.d.ts

@@ -1,17 +1,3 @@
-/**
- * Customer-tag bootstrap + lifecycle emission (forms-sdk-plan.md rows 51–54,
- * 58): GTM container, GA4, Meta Pixel, and HubSpot from the form's settings,
- * with the same don't-double-inject guards as the native runtime and the
- * parent tag. No React, no react-gtm-module / react-facebook-pixel — direct
- * global bootstraps like the parent tag's providers.
- *
- * Three native quirks are FIXED here by decision (2026-08-10, memory +
- * plan rows 51–52) — the parity harness whitelists them as intentional diffs:
- * - GTM `SurfaceFormSubmitEvent` carries `formId` (native omits it).
- * - `stepId` in `SurfaceFormStepSubmitted` is the real step id (native sends
- *   the step *name*) — migration note for name-keyed GTM triggers.
- * - GA4 config does NOT hardcode `debug_mode: true`.
- */
 export type LifecycleUrlData = {
     url: string;
     urlParams: Record<string, string>;
@@ -25,22 +11,14 @@ export type VendorSettings = {
     };
 };
 export type StepSubmittedPayload = LifecycleUrlData & {
-    /** Quirk fix: the real step id — native sends the step name here. */
     stepId: string;
     formId: string;
     emailProvided: boolean;
     meetingBooked: boolean;
 };
-/**
- * One instance per SurfaceForms.init (no module-level singletons — §2.7):
- * injects the configured vendors immediately, exposes the three lifecycle
- * emitters with native event names/payload keys (they are customers' GTM
- * trigger contracts).
- */
 export declare const createVendorTracker: (win: Window, settings: VendorSettings) => {
     formStarted: (formId: string, urlData: LifecycleUrlData) => void;
     stepSubmitted: (payload: StepSubmittedPayload) => void;
     formCompleted: (formId: string, urlData: LifecycleUrlData) => void;
 };
 export type VendorTracker = ReturnType<typeof createVendorTracker>;
-//# sourceMappingURL=vendors.d.ts.map

package/dist/types/tracking/vendors.test.d.ts

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

package/dist/types/validation/attachEmailValidation.d.ts

@@ -5,4 +5,3 @@ export type AttachEmailValidationOptions = {
     validator: EmailValidator;
 };
 export declare const attachEmailValidation: ({ engine, validator }: AttachEmailValidationOptions) => (() => void);
-//# sourceMappingURL=attachEmailValidation.d.ts.map

package/dist/types/validation/attachEmailValidation.test.d.ts

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

package/docs/reference/identity.md

@@ -5,9 +5,8 @@ Exhaustive reference for the `core/identity` domain. Map of everything: [`../api
 ## Fingerprint (`core/identity/browserFingerprint`)
 
 - **`getBrowserFingerprint(environmentId): Promise<Fingerprint>`** — the canonical Surface
-  fingerprint. The serialization (field insertion order, value shapes, falsy fallbacks) IS the
-  wire contract: the lead pipeline keys on `SHA-256(JSON.stringify(fields))`, so never derive
-  your own variant — a different serialization splits one visitor into two leads.
+  fingerprint. Its serialization is a server-side identity contract: always use this function
+  as-is — a hand-rolled variant produces a different `id` and splits one visitor into two leads.
 - **`getHash(input): Promise<string>`** — SHA-256 hex via Web Crypto.
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parag.more.withsurface.com/forms-sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Thin-client Surface Forms SDK: headless core over the public runtime endpoints (field-test build).",
   "license": "MIT",
   "sideEffects": false,