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

package/dist/types/core/engine/answerStates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"answerStates.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/answerStates.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,145 @@
+import type { Transport } from "../client/transport";
+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;
+};
+export type ResolveNextStep = (currentStepId: string, answers: AnswerStates) => ResolvedNextStep | "END" | "INVALID";
+export type FormEngineEvents = {
+    viewed: {
+        formId: string;
+    };
+    started: {
+        formId: string;
+    };
+    stepChanged: {
+        fromStepId: string;
+        toStepId: string;
+    };
+    stepCompleted: {
+        stepId: string;
+    };
+    completed: {
+        formId: string;
+    };
+    disqualified: {
+        stepId: string;
+    };
+    saved: {
+        responseId: string;
+        finished: boolean;
+        resumeToken: string | null;
+    };
+    error: {
+        scope: "submit";
+        error: unknown;
+    };
+};
+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;
+    state: () => FormEngineState;
+    subscribe: (listener: () => void) => Unsubscribe;
+};
+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";
+    }>;
+    transport: Transport;
+    resolveNextStep?: ResolveNextStep;
+    trackPartialResponses?: boolean;
+    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;
+        leadId?: string;
+    };
+    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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formEngine.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/formEngine.ts"],"names":[],"mappings":"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"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"formEngine.test.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/formEngine.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,36 @@
+/**
+ * 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 }?: {
+    leadId?: string;
+    sessionId?: string;
+}) => string;
+export declare const performRedirect: ({ url, redirectType, leadId, sessionId, preview, }: {
+    url: string;
+    redirectType?: RedirectType;
+    leadId?: string;
+    sessionId?: string;
+    preview?: boolean;
+}) => void;
+//# sourceMappingURL=redirect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/redirect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,eAAe,CAAC;AAEtD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAQ/C,eAAO,MAAM,gBAAgB,QACtB,MAAM,0BACY;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,KAC7D,MAUF,CAAC;AAEF,eAAO,MAAM,eAAe,uDAMzB;IACD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,KAAG,IAaH,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"redirect.test.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/redirect.test.ts"],"names":[],"mappings":""}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"responsePayload.contract.test.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/responsePayload.contract.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,74 @@
+/**
+ * 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>>;
+export type FormResponsePayload = {
+    formId: string;
+    responses: SingleFormResponse[];
+    enrichedFields: Record<string, unknown>;
+    finished: boolean;
+    invalidResponse: boolean;
+    stepId: string;
+    fingerprint?: string;
+    leadSessionId?: string;
+    meta: Record<string, unknown>;
+    responseShapeVersion: "2.0";
+};
+export type FormUpdateResponsePayload = Omit<FormResponsePayload, "responseShapeVersion"> & {
+    responseId: string;
+};
+export declare const buildResponsesArray: (answers: AnswerStates, externalStates: ExternalStates) => {
+    responses: SingleFormResponse[];
+    enrichedFields: Record<string, unknown>;
+    bookingId?: string;
+};
+type BuildPayloadOptions = {
+    formId: string;
+    answers: AnswerStates;
+    externalStates: ExternalStates;
+    submittingOnStepId: string;
+    finished: boolean;
+    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;
+};
+export declare const createSubmitResponsePayload: (options: BuildPayloadOptions) => FormResponsePayload;
+export declare const createUpdateResponsePayload: (options: BuildPayloadOptions & {
+    responseId: string;
+}) => FormUpdateResponsePayload;
+export {};
+//# sourceMappingURL=responsePayload.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"responsePayload.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/responsePayload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;AAEnF,+FAA+F;AAC/F,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAExF,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,oBAAoB,EAAE,KAAK,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,mBAAmB,EAAE,sBAAsB,CAAC,GAAG;IAC1F,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,mBAAmB,YACrB,YAAY,kBACL,cAAc,KAC7B;IAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAiChG,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;IACtB,cAAc,EAAE,cAAc,CAAC;IAC/B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,OAAO,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,oFAAoF;IACpF,6BAA6B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAkCF,eAAO,MAAM,2BAA2B,YAAa,mBAAmB,KAAG,mBAGzE,CAAC;AAEH,eAAO,MAAM,2BAA2B,YAC7B,mBAAmB,GAAG;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,KACpD,yBAGD,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"responsePayload.test.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/responsePayload.test.ts"],"names":[],"mappings":""}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"urlData.contract.test.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/urlData.contract.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,30 @@
+/**
+ * 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;
+    params?: Record<string, string>;
+    referrer?: string;
+    cookies?: Record<string, string>;
+};
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlData.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/urlData.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,UAAU,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAEF,eAAO,MAAM,wBAAwB,QAAS,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAQ3E,CAAC;AAEF,eAAO,MAAM,kBAAkB,iBAAkB,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAc9E,CAAC;AAEF,eAAO,MAAM,YAAY,mCAGtB;IACD,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,KAAQ,OAwBR,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"urlData.test.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/urlData.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,21 @@
+/**
+ * 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;
+    fieldName: string;
+    value: string;
+};
+export declare const parseQuestionId: (input: string) => {
+    originalId: string;
+    questionId: 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"urlPrefill.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/urlPrefill.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,eAAO,MAAM,eAAe,UAAW,MAAM;IAGzC,UAAU;IACV,UAAU;IACV,SAAS;CAEZ,CAAC;AAIF,eAAO,MAAM,kBAAkB,WACrB,MAAM,GAAG,eAAe,KAC/B,MAAM,CAAC,MAAM,EAAE,mBAAmB,EAAE,CAAC,GAAG,IAqB1C,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"urlPrefill.test.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/urlPrefill.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,21 @@
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dropoffDetection.d.ts","sourceRoot":"","sources":["../../../../src/core/events/dropoffDetection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,oBACR,eAAe,YACtB,MAAM;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,KACA,CAAC,MAAM,IAAI,CAkBb,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"dropoffDetection.test.d.ts","sourceRoot":"","sources":["../../../../src/core/events/dropoffDetection.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,23 @@
+/**
+ * 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.d.ts","sourceRoot":"","sources":["../../../../src/core/events/emitter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,MAAM,MAAM,OAAO,CAAC,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC/D,EAAE,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,KAAK,WAAW,CAAC;IACnG,IAAI,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CAC5E,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,OAAK,OAAO,CAAC,SAAS,CAsB5F,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.test.d.ts","sourceRoot":"","sources":["../../../../src/core/events/emitter.test.ts"],"names":[],"mappings":""}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"formJourneyTracker.contract.test.d.ts","sourceRoot":"","sources":["../../../../src/core/events/formJourneyTracker.contract.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,69 @@
+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 = {
+    ordinal: number;
+    stepId: string;
+    enteredAt: string;
+    exitedAt?: string | null;
+    durationMs?: number | null;
+    fromStepId?: string | null;
+    transitionReason: FormJourneyTransitionReason;
+    transitionMeta?: unknown;
+};
+export type FormJourneyTrackPayload = {
+    responseId: string;
+    formId: string;
+    outcome?: FormJourneyOutcome;
+    disqualification?: {
+        reason: "conditional_match" | "default_fallback";
+        matched?: unknown;
+    } | null;
+    disqualifiedAtStepId?: string | null;
+    disqualifiedTriggerStepId?: string | null;
+    events: FormJourneyVisit[];
+};
+export interface FormJourneyTracker {
+    recordEntry: (stepId: string) => void;
+    recordTransition: (args: {
+        fromStepId: string;
+        toStepId: string;
+        reason: FormJourneyTransitionReason;
+        transitionMeta?: unknown;
+    }) => void;
+    recordTerminal: (args: {
+        outcome: FormJourneyOutcome;
+        disqualification?: {
+            reason: "conditional_match" | "default_fallback";
+            atStepId: string;
+            triggerStepId?: string;
+            matched?: unknown;
+        };
+    }) => void;
+    setResponseId: (responseId: string) => void;
+    setFormId: (formId: string) => void;
+    hasRecordedTransition: () => boolean;
+}
+export declare const createFormJourneyTracker: ({ transport, preview, }: {
+    transport: Transport;
+    preview?: boolean;
+}) => FormJourneyTracker;
+//# sourceMappingURL=formJourneyTracker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"formJourneyTracker.d.ts","sourceRoot":"","sources":["../../../../src/core/events/formJourneyTracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,cAAc,GAAG,aAAa,CAAC;AAE1G,MAAM,MAAM,2BAA2B,GACnC,SAAS,GACT,QAAQ,GACR,mBAAmB,GACnB,kBAAkB,GAClB,cAAc,GACd,UAAU,GACV,WAAW,CAAC;AAEhB,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,EAAE,2BAA2B,CAAC;IAC9C,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAC7B,gBAAgB,CAAC,EAAE;QAAE,MAAM,EAAE,mBAAmB,GAAG,kBAAkB,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAClG,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,yBAAyB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,gBAAgB,EAAE,CAAC,IAAI,EAAE;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,2BAA2B,CAAC;QACpC,cAAc,CAAC,EAAE,OAAO,CAAC;KAC1B,KAAK,IAAI,CAAC;IACX,cAAc,EAAE,CAAC,IAAI,EAAE;QACrB,OAAO,EAAE,kBAAkB,CAAC;QAC5B,gBAAgB,CAAC,EAAE;YACjB,MAAM,EAAE,mBAAmB,GAAG,kBAAkB,CAAC;YACjD,QAAQ,EAAE,MAAM,CAAC;YACjB,aAAa,CAAC,EAAE,MAAM,CAAC;YACvB,OAAO,CAAC,EAAE,OAAO,CAAC;SACnB,CAAC;KACH,KAAK,IAAI,CAAC;IACX,aAAa,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,qBAAqB,EAAE,MAAM,OAAO,CAAC;CACtC;AAkCD,eAAO,MAAM,wBAAwB,4BAGlC;IACD,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,KAAG,kBA2HH,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"formJourneyTracker.test.d.ts","sourceRoot":"","sources":["../../../../src/core/events/formJourneyTracker.test.ts"],"names":[],"mappings":""}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"pushEvents.contract.test.d.ts","sourceRoot":"","sources":["../../../../src/core/events/pushEvents.contract.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,62 @@
+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 = {
+    key: string;
+    value: unknown;
+};
+export type PushEventPayload = {
+    type: SurfaceEventType;
+    entityType: SurfaceEventEntityType;
+    entityId: string;
+    stepId?: string | null;
+    leadSessionId?: string | null;
+    properties?: PushEventProperty[];
+    leadId?: string;
+    environmentId?: string;
+};
+/** The server accepts exactly one batch shape: a step transition pair. */
+export type PushEventBatch = {
+    events: [
+        PushEventPayload & {
+            type: "form_step_submitted";
+            entityType: "form_step";
+            stepId: string;
+        },
+        PushEventPayload & {
+            type: "form_step_viewed";
+            entityType: "form_step";
+            stepId: string;
+        }
+    ];
+};
+export type PushEventRequest = PushEventPayload | PushEventBatch;
+export declare const buildStepTransitionEventBatch: ({ sessionId, formId, currentStepId, nextStepId, stepCompletionTime, }: {
+    sessionId: string | undefined;
+    formId: string;
+    currentStepId: string;
+    nextStepId: string;
+    stepCompletionTime: number;
+}) => PushEventBatch;
+export type PushEventClient = {
+    push: (request: PushEventRequest) => void;
+};
+export declare const createPushEventClient: ({ transport, preview, }: {
+    transport: Transport;
+    preview?: boolean;
+}) => PushEventClient;
+//# sourceMappingURL=pushEvents.d.ts.map