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

package/dist/types/bind/bindForm.d.ts

@@ -0,0 +1,43 @@
+import type { FormEngine } from "../core/engine/formEngine";
+/**
+ * The `data-*` binding layer (forms-sdk-plan.md §2.1/§5.2): makes plain
+ * agent-authored HTML drive the headless engine with zero authored JS. The
+ * attribute contract is a superset of the conventions the public tag's
+ * external-form path already uses (`data-question-id` / `data-field-name`
+ * discovery, `input[type=email]` → `emailAddress` inference,
+ * `surface-next-button` / `surface-submit-button` classes), plus
+ * customer-owned routing affordances (`data-surface-goto-step` branch buttons,
+ * `surface-disqualify-button` — Decisions #6) and the
+ * stepped-only rule: `data-step-id` containers matching the record's steps,
+ * which the SDK shows/hides itself — a multi-step record presents one step at
+ * a time (§2.9). A single-step record may omit containers entirely.
+ *
+ * Fields merge into one component state per question (`{ [fieldName]: value }`
+ * accumulates firstName/lastName style groups); `data-field-name` defaults to
+ * `"input"` — ShortInput's state key — and email inputs without it default to
+ * `"email"`, EmailForm's; a `<select>` on a Dropdown defaults to `"selected"`,
+ * its state key. Every state carries its `type` discriminator
+ * (`data-question-type`, inferred for the two text states) because the wire
+ * schema validates states as a discriminated union.
+ *
+ * Choice questions are captured per GROUP, not per control: their wire states
+ * are structural (`MultipleOptionsQuestion` wants the ENTIRE option list as
+ * `{key, index, value}` entries, `GraphicOptions` wants `{value, index}`),
+ * which no single radio's string value can express — the 2026-08 field run
+ * shipped exactly that and ingest rejected it. Every change rebuilds the full
+ * answer from all radios/checkboxes under the binding (key = the control's
+ * `value` attribute, index = DOM order, so author options in record order).
+ *
+ * Runtime drift guard (§4.3): Surface never sees the customer's HTML, so on
+ * bind the record's stateful questionIds are compared against what the DOM
+ * actually bound — unbound ids get a console warning, the publish-gate-less
+ * counterpart of `validate_form_html`.
+ */
+export type BindFormOptions = {
+    engine: FormEngine;
+    root: Element;
+    /** Stateful questionIds from the form record; unbound ones are warned about. */
+    expectedQuestionIds?: string[];
+};
+export declare const bindForm: ({ engine, root, expectedQuestionIds }: BindFormOptions) => (() => void);
+//# sourceMappingURL=bindForm.d.ts.map

package/dist/types/bind/bindForm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bindForm.d.ts","sourceRoot":"","sources":["../../../src/bind/bindForm.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAG5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;IACd,gFAAgF;IAChF,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC,CAAC;AA2EF,eAAO,MAAM,QAAQ,0CAA2C,eAAe,KAAG,CAAC,MAAM,IAAI,CA4G5F,CAAC"}

package/dist/types/bind/bindForm.test.d.ts

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

package/dist/types/bind/bindForm.test.d.ts.map

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

package/dist/types/bind/bookingWidget.d.ts

@@ -0,0 +1,35 @@
+import type { Booking, SchedulerClient, TimeSlot } from "../core/client/scheduler";
+export type BookingWidgetOptions = {
+    container: Element;
+    scheduler: SchedulerClient;
+    eventTypeId: string;
+    timezone?: string;
+    duration?: number;
+    prefill?: {
+        name?: string;
+        email?: string;
+    };
+    /** Threads booking↔response linkage into the booking meta block. */
+    identity?: {
+        responseId?: string;
+        leadSessionId?: string;
+        fingerprint?: string;
+    };
+    /**
+     * Overrides for the widget's human-readable copy. Defaults use
+     * `Intl.DateTimeFormat` in the visitor's locale; every button also carries
+     * the raw value in `data-value` (`YYYY-MM` months, `YYYY-MM-DD` dates, ISO
+     * instants for slots), so relabeling never needs to parse the text back.
+     */
+    formatters?: {
+        /** `month` is `YYYY-MM`. */
+        month?: (month: string) => string;
+        /** `date` is `YYYY-MM-DD`. */
+        date?: (date: string) => string;
+        /** `slot.start`/`slot.end` are ISO instants; format in the widget's timezone. */
+        time?: (slot: TimeSlot) => string;
+    };
+    onComplete: (booking: Booking) => void;
+};
+export declare const mountBookingWidget: ({ container, scheduler, eventTypeId, timezone, duration, prefill, identity, formatters, onComplete, }: BookingWidgetOptions) => (() => void);
+//# sourceMappingURL=bookingWidget.d.ts.map

package/dist/types/bind/bookingWidget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bookingWidget.d.ts","sourceRoot":"","sources":["../../../src/bind/bookingWidget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAkBnF,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,eAAe,CAAC;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,oEAAoE;IACpE,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjF;;;;;OAKG;IACH,UAAU,CAAC,EAAE;QACX,4BAA4B;QAC5B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;QAClC,8BAA8B;QAC9B,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;QAChC,iFAAiF;QACjF,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,MAAM,CAAC;KACnC,CAAC;IACF,UAAU,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACxC,CAAC;AA8BF,eAAO,MAAM,kBAAkB,0GAU5B,oBAAoB,KAAG,CAAC,MAAM,IAAI,CA0LpC,CAAC"}

package/dist/types/bind/bookingWidget.test.d.ts

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

package/dist/types/bind/bookingWidget.test.d.ts.map

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

package/dist/types/core/client/emailValidation.d.ts

@@ -0,0 +1,23 @@
+import type { Transport } from "./transport";
+export type EmailValidationResult = {
+    email: string;
+    /** Deliverable per the waterfall + blacklist; fail-open true when validation could not run. */
+    isValid: boolean;
+    status?: string;
+    reason?: string;
+    blacklistEntryIds?: string[];
+    /** Validation did not actually run (network/server failure) — `isValid` is the fail-open default. */
+    failed?: boolean;
+};
+export type EmailValidator = {
+    validate: (email: string) => Promise<EmailValidationResult>;
+    validateBatch: (emails: string[]) => Promise<EmailValidationResult[]>;
+};
+export type CreateEmailValidatorOptions = {
+    transport: Transport;
+    environmentId: string;
+    /** Preview never spends validator quota: every email reports a synthetic valid result. */
+    preview?: boolean;
+};
+export declare const createEmailValidator: ({ transport, environmentId, preview, }: CreateEmailValidatorOptions) => EmailValidator;
+//# sourceMappingURL=emailValidation.d.ts.map

package/dist/types/core/client/emailValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emailValidation.d.ts","sourceRoot":"","sources":["../../../../src/core/client/emailValidation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAkB7C,MAAM,MAAM,qBAAqB,GAAG;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,qGAAqG;IACrG,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAWF,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5D,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,SAAS,EAAE,SAAS,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAsBF,eAAO,MAAM,oBAAoB,2CAI9B,2BAA2B,KAAG,cAmChC,CAAC"}

package/dist/types/core/client/emailValidation.test.d.ts

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

package/dist/types/core/client/emailValidation.test.d.ts.map

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

package/dist/types/core/client/responses.d.ts

@@ -0,0 +1,35 @@
+import type { FormResponsePayload, FormUpdateResponsePayload } from "../engine/responsePayload";
+import type { Transport, TransportResult } from "./transport";
+export type CreateResponseResult = {
+    responseId: string;
+    leadId: string | null;
+    /** Authorizes the token-gated read-back (resume); persist alongside the responseId. */
+    resumeToken: string | null;
+};
+export declare const submitResponse: (transport: Transport, payload: FormResponsePayload) => Promise<TransportResult<CreateResponseResult>>;
+export declare const updateResponse: (transport: Transport, payload: FormUpdateResponsePayload) => void;
+/**
+ * Awaited delivery for the FINISHING update (the 2026-08 field run measured
+ * the beacon path silently dropping the terminal write on fast page close:
+ * `submit()` resolved, `saved` fired, and the server kept a step-1 partial).
+ * `keepalive` lets the request survive an immediate navigation; credentials
+ * match the beacon path's `${formId}_pa` cookie round-trip.
+ */
+export declare const updateResponseConfirmed: (transport: Transport, payload: FormUpdateResponsePayload) => Promise<TransportResult<unknown>>;
+export type StoredAnswerRow = {
+    questionId: string;
+    response: Record<string, unknown>;
+};
+/**
+ * Read-back of a stored response for resume (Decisions #11: the route is
+ * token-gated; the create reply issued the token). External-state
+ * pseudo-answers (URL_DATA) are stripped — they are attribution snapshots the
+ * engine re-derives from its own page context, not visitor answers.
+ */
+export declare const fetchStoredResponse: (transport: Transport, { responseId, resumeToken }: {
+    responseId: string;
+    resumeToken: string;
+}) => Promise<TransportResult<{
+    answers: StoredAnswerRow[];
+}>>;
+//# sourceMappingURL=responses.d.ts.map

package/dist/types/core/client/responses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../../src/core/client/responses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAChG,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAe9D,MAAM,MAAM,oBAAoB,GAAG;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,uFAAuF;IACvF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAMF,eAAO,MAAM,cAAc,cACd,SAAS,WACX,mBAAmB,KAC3B,OAAO,CAAC,eAAe,CAAC,oBAAoB,CAAC,CAiB/C,CAAC;AAEF,eAAO,MAAM,cAAc,cAAe,SAAS,WAAW,yBAAyB,KAAG,IAEzF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,cACvB,SAAS,WACX,yBAAyB,KACjC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAC2C,CAAC;AAE/E,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAaxF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,cACnB,SAAS,+BACS;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,KACvE,OAAO,CAAC,eAAe,CAAC;IAAE,OAAO,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC,CAUzD,CAAC"}

package/dist/types/core/client/responses.test.d.ts

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

package/dist/types/core/client/responses.test.d.ts.map

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

package/dist/types/core/client/runtimeConfig.contract.test.d.ts

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

package/dist/types/core/client/runtimeConfig.contract.test.d.ts.map

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

package/dist/types/core/client/runtimeConfig.d.ts

@@ -0,0 +1,72 @@
+import type { Transport, TransportResult } from "./transport";
+/**
+ * Boot-time fetch of the published form record (forms-sdk-plan.md §2.3,
+ * Decisions #7): `GET /api/v1/public/forms/[formId]/runtime-config` serves the
+ * same `TCachedForm` payload the hosted `/s/[formId]` page reads — config
+ * (steps + components, the data contract) and settings (behavioral gates like
+ * `trackPartialResponses`; tracking ids for the Phase-2 tracking module).
+ * `settings.password` never arrives — the server strips it and the SDK
+ * validates gated forms through `/api/v1/check-password`.
+ *
+ * The step/question extraction mirrors `extractFlatComponentsFromStep`
+ * (form-render gridLayoutUtils): a step's `components` is either a flat
+ * component array or a ComponentGridLayout whose rows hold components or
+ * `GridLayoutRowItem` wrappers; stateful components carry `state.questionId` —
+ * the same discriminator the MCP validator's `collectQuestionIds` uses.
+ */
+type RuntimeStep = {
+    id: string;
+    endStepKind?: "thank_you" | "disqualified";
+    components?: unknown;
+};
+export type RuntimeConfig = {
+    id: string;
+    name?: string;
+    environmentId?: string;
+    config: {
+        steps?: RuntimeStep[];
+    } & Record<string, unknown>;
+    settings?: ({
+        trackPartialResponses?: boolean;
+        trackCookie?: boolean;
+    } & Record<string, unknown>) | null;
+};
+/** `preview` asks the server for the draft config of a never-published form (authoring loop); published forms serve live either way. */
+export declare const fetchRuntimeConfig: (transport: Transport, formId: string, { preview, previewToken }?: {
+    preview?: boolean;
+    previewToken?: string;
+}) => Promise<TransportResult<{
+    data?: RuntimeConfig;
+}>>;
+/** Step order + ending kinds — the engine's traversal contract, including where submit/disqualify land. */
+export declare const stepsOf: (config: RuntimeConfig["config"]) => Array<{
+    id: string;
+    endStepKind?: "thank_you" | "disqualified";
+}>;
+export declare const statefulQuestionsOf: (config: RuntimeConfig["config"]) => Array<{
+    questionId: string;
+    componentType?: string;
+}>;
+export declare const statefulQuestionIdsOf: (config: RuntimeConfig["config"]) => string[];
+/**
+ * Questions whose answers can trigger real-time enrichment, with the state
+ * keys to watch — the native renderer's blur triggers translated to data
+ * (identityInfo.tsx handleOnBlur): IdentityInfo fires on its configured
+ * `enrichmentSourceField` (default emailAddress) and always on `websiteUrl`;
+ * EmailForm fires on its email.
+ */
+export declare const enrichmentSourcesOf: (config: RuntimeConfig["config"]) => Array<{
+    questionId: string;
+    fieldNames: string[];
+}>;
+/**
+ * True when a component EXPLICITLY declares `enrichmentSourceField` — the
+ * authoring-time signal that the owner expects enrichment to run. Implicit
+ * sources (every EmailForm / IdentityInfo default) don't count: they make any
+ * form with an email question look enrichment-configured.
+ */
+export declare const hasDeclaredEnrichmentSource: (config: RuntimeConfig["config"]) => boolean;
+/** Mirrors form-render's provider gate (buildExternalStateStore): v2 config with at least one enabled provider exposing fields. */
+export declare const hasEnabledEnrichmentProvider: (settings: RuntimeConfig["settings"]) => boolean;
+export {};
+//# sourceMappingURL=runtimeConfig.d.ts.map

package/dist/types/core/client/runtimeConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtimeConfig.d.ts","sourceRoot":"","sources":["../../../../src/core/client/runtimeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9D;;;;;;;;;;;;;;GAcG;AAEH,KAAK,WAAW,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpG,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE;QAAE,KAAK,CAAC,EAAE,WAAW,EAAE,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5D,QAAQ,CAAC,EAAE,CAAC;QAAE,qBAAqB,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAC1G,CAAC;AAEF,wIAAwI;AACxI,eAAO,MAAM,kBAAkB,cAClB,SAAS,UACZ,MAAM,8BACqB;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,KAC9E,OAAO,CAAC,eAAe,CAAC;IAAE,IAAI,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC,CAQjD,CAAC;AAkBJ,2GAA2G;AAC3G,eAAO,MAAM,OAAO,WACV,aAAa,CAAC,QAAQ,CAAC,KAC9B,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,WAAW,GAAG,cAAc,CAAA;CAAE,CAI9D,CAAC;AAEN,eAAO,MAAM,mBAAmB,WACtB,aAAa,CAAC,QAAQ,CAAC,KAC9B,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAUnD,CAAC;AAEL,eAAO,MAAM,qBAAqB,WAAY,aAAa,CAAC,QAAQ,CAAC,KAAG,MAAM,EACV,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,WACtB,aAAa,CAAC,QAAQ,CAAC,KAC9B,KAAK,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAqBjD,CAAC;AAEL;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,WAAY,aAAa,CAAC,QAAQ,CAAC,KAAG,OAOzE,CAAC;AAEN,mIAAmI;AACnI,eAAO,MAAM,4BAA4B,aAAc,aAAa,CAAC,UAAU,CAAC,KAAG,OAUlF,CAAC"}

package/dist/types/core/client/runtimeConfig.test.d.ts

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

package/dist/types/core/client/runtimeConfig.test.d.ts.map

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

package/dist/types/core/client/scheduler.contract.test.d.ts

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

package/dist/types/core/client/scheduler.contract.test.d.ts.map

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

package/dist/types/core/client/scheduler.d.ts

@@ -0,0 +1,121 @@
+import type { Transport, TransportResult } from "./transport";
+/**
+ * Thin wrap of the public Surface-native scheduler endpoints (forms-sdk-plan.md
+ * row 46 — Phase-1 MVP scope by product decision). Query and payload shapes
+ * mirror `@surface/scheduler-ui`'s hooks byte-for-byte (that package is
+ * AGPL-tree and cannot ship in the MIT SDK — plan §2.9), including the split
+ * of `YYYY-MM` into numeric month/year params and the booking `meta` block
+ * that drives server-side booking↔response linkage.
+ *
+ * `preview: true` mirrors the native BookingForm exactly: queries carry
+ * `preview=true`, and `book()` resolves a fabricated preview booking without
+ * any network call — draft interactions never create real bookings.
+ *
+ * `toSchedulerAnswerState` reproduces `SurfaceScheduler.handleBookingComplete`:
+ * the persisted DynamicScheduler component state whose `eventScheduled`/`uri`
+ * pair the payload builder's bookingId detection and the server's booking
+ * meta injection key on. `googleMeetLink` is the frozen persisted key even
+ * though the API field is `meetingJoinLink`.
+ */
+export type BookingAttendee = {
+    name: string;
+    email: string;
+    isHost: boolean;
+};
+export type Booking = {
+    id: string;
+    startTime: string;
+    endTime: string;
+    timezone: string;
+    inviteeName: string;
+    inviteeEmail: string;
+    meetingJoinLink: string | null;
+    cancelToken: string;
+    rescheduleToken: string;
+    attendees: BookingAttendee[];
+};
+export type TimeSlot = {
+    start: string;
+    end: string;
+};
+export type AvailabilitySummary = {
+    has_availability: boolean;
+    available_slots_7d: number;
+    available_slots_14d: number;
+    available_slots_30d: number;
+    available_days_7d: number;
+    next_available_date: string | null;
+    total_available_slots: number;
+    rep_meeting_count_today: number;
+};
+type HostScope = {
+    hostId?: string;
+    ownerEmail?: string;
+};
+export type SchedulerClient = {
+    getPublicEventType: <TEventType = unknown>(eventTypeId: string) => Promise<TransportResult<TEventType>>;
+    getAvailabilitySummary: (args: {
+        eventTypeId: string;
+        timezone?: string;
+    }) => Promise<TransportResult<{
+        data?: AvailabilitySummary;
+    }>>;
+    getMonthAvailability: (args: {
+        eventTypeId: string;
+        /** Calendar month as `YYYY-MM`; split into numeric month/year params like native. */
+        month: string;
+        timezone: string;
+        duration?: number;
+    } & HostScope) => Promise<TransportResult<{
+        data?: {
+            dates?: unknown[];
+            resolvedHost?: unknown;
+        };
+    }>>;
+    getSlots: (args: {
+        eventTypeId: string;
+        date: string;
+        timezone: string;
+        duration?: number;
+    } & HostScope) => Promise<TransportResult<{
+        data?: {
+            slots?: TimeSlot[];
+        };
+    }>>;
+    book: (args: {
+        eventTypeId: string;
+        startTime: string;
+        /**
+         * The selected slot's end. Required — every booking comes from a picked
+         * slot, and a fallback would fabricate zero-length preview meetings. Only
+         * preview fabrication reads it (the server derives real end times); it is
+         * never sent on the wire.
+         */
+        endTime: string;
+        timezone: string;
+        inviteeName: string;
+        inviteeEmail: string;
+        duration?: number;
+        intakeResponses?: Record<string, string>;
+        guestEmails?: string[];
+        captchaToken?: string;
+        responseId?: string;
+        leadSessionId?: string;
+        fingerprint?: string;
+        hostRouting?: unknown;
+    }) => Promise<TransportResult<Booking>>;
+    reschedule: (args: {
+        bookingId: string;
+        rescheduleToken: string;
+        newStartTime: string;
+        timezone: string;
+    }) => Promise<TransportResult<Booking>>;
+};
+export declare const createSchedulerClient: ({ transport, preview, }: {
+    transport: Transport;
+    preview?: boolean;
+}) => SchedulerClient;
+/** The persisted DynamicScheduler component state for a completed booking. */
+export declare const toSchedulerAnswerState: (booking: Booking) => Record<string, unknown>;
+export {};
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/types/core/client/scheduler.d.ts.map

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

package/dist/types/core/client/scheduler.test.d.ts

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

package/dist/types/core/client/scheduler.test.d.ts.map

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

package/dist/types/core/client/transport.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Delivery layer for the SDK's first-party requests, mirroring the native
+ * runtime's two transports (forms-sdk-plan.md §2.4):
+ *
+ * - `post` — plain `fetch` for calls whose response body the engine needs
+ *   (response create returns `responseId`/`meta`, identify returns
+ *   `leadId`/`sessionId`). Never throws: resolves to a typed result so
+ *   callers keep the never-break-the-host-page guarantee (§2.6).
+ * - `beacon` — `sendBeacon`-first with `fetch(keepalive)` fallback for
+ *   fire-and-forget writes (response updates, events, journey), the same
+ *   semantics as form-render's `updateResponse.ts` / `sendPushEventRequest.ts`.
+ *   Failures are swallowed by design: the server's drop-off sweep reconciles
+ *   missed updates, and events are best-effort.
+ *
+ * Unlike form-render (relative paths, same-origin only), every request is
+ * absolute against a configurable base URL — SDK pages are customer-hosted
+ * and always cross-origin (§4.1).
+ */
+/** The host the public tag already targets (scripts:src/constants.ts). */
+export declare const DEFAULT_API_BASE_URL = "https://forms.withsurface.com";
+/**
+ * Sent as `X-Surface-Sdk-Version` on every fetch-path request (Decisions #14:
+ * SDK 429s must be measurable before rate limits are revisited). `sendBeacon`
+ * cannot carry headers, so beacon deliveries carry the version as the `sdv`
+ * query param instead — the server reads both. Bumped manually until
+ * extraction wires it to package.json at build time.
+ */
+export declare const SDK_VERSION = "0.1.0";
+export type TransportResult<TData> = {
+    ok: true;
+    data: TData;
+} | {
+    ok: false;
+    error: TransportError;
+};
+export type TransportError = {
+    kind: "network";
+    cause: unknown;
+} | {
+    kind: "http";
+    status: number;
+    body?: unknown;
+};
+export type Transport = {
+    get: <TData>(path: string) => Promise<TransportResult<TData>>;
+    post: <TData>(path: string, payload: unknown, opts?: {
+        keepalive?: boolean;
+        credentials?: boolean;
+    }) => Promise<TransportResult<TData>>;
+    /** Returns true only when `sendBeacon` queued the payload; the fire-and-forget fetch fallback reports false. */
+    beacon: (path: string, payload: unknown) => boolean;
+};
+export declare const createTransport: ({ apiBaseUrl, }?: {
+    apiBaseUrl?: string;
+}) => Transport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/types/core/client/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../../../src/core/client/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,kCAAkC,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,UAAU,CAAC;AASnC,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAEtG,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACnC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;IAC9D,IAAI,EAAE,CAAC,KAAK,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,KAClD,OAAO,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC;IACrC,gHAAgH;IAChH,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;CACrD,CAAC;AAEF,eAAO,MAAM,eAAe,qBAEzB;IAAE,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,KAAQ,SA6EjC,CAAC"}

package/dist/types/core/client/transport.test.d.ts

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

package/dist/types/core/client/transport.test.d.ts.map

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

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

@@ -0,0 +1,21 @@
+/**
+ * `init({ debug: true })` answer auditing: the bind layer always produces
+ * valid shapes, but headless `setAnswer` callers are one label-string away
+ * from the ingest 400 that static gates cannot see (2026-08 field run). The
+ * auditor checks only facts that cannot false-positive — unknown questionId,
+ * wrong `type` discriminator, a merged state with no `type` at all, and a
+ * choice-list answer whose `choices` is not an array — and logs every
+ * captured answer so a session is replayable from the console.
+ */
+export type AuditedQuestion = {
+    questionId: string;
+    componentType?: string;
+};
+export declare const auditAnswer: ({ questions, questionId, merged, }: {
+    /** Stateful questions of the record; empty when the record wasn't fetched (caller-provided steps). */
+    questions: Map<string, AuditedQuestion>;
+    questionId: string;
+    /** The post-merge state (setAnswer patches accumulate per question). */
+    merged: Record<string, unknown>;
+}) => void;
+//# sourceMappingURL=answerAudit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"answerAudit.d.ts","sourceRoot":"","sources":["../../../../src/core/engine/answerAudit.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAcH,MAAM,MAAM,eAAe,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7E,eAAO,MAAM,WAAW,uCAIrB;IACD,sGAAsG;IACtG,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,KAAG,IAsCH,CAAC"}

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,92 @@
+/**
+ * Typed answer states for headless callers (plan §2.9): the bind layer builds
+ * these automatically, but React/headless code hands them to `setAnswer` by
+ * hand — and shipping a bare label string where a structured state belongs is
+ * the classic production 400 (2026-08 field run). These local types mirror
+ * each component's wire schema and are contract-tested against
+ * `@surface/types` (dev dependency only — the SDK ships zero runtime deps).
+ *
+ * `setAnswer` itself stays structurally typed (`Record<string, unknown>`):
+ * legacy component types not listed here remain settable, and answers merge
+ * per question, so partial patches are legal. Annotate call sites with these
+ * types to get the compiler's help.
+ */
+export type ShortInputAnswer = {
+    type: "ShortInput";
+    input: string;
+};
+export type LongInputAnswer = {
+    type: "LongInput";
+    input: string;
+};
+export type EmailFormAnswer = {
+    type: "EmailForm";
+    email: string;
+    subscriptionCheck?: boolean;
+};
+export type DropdownAnswer = {
+    type: "Dropdown";
+    selected: string | string[];
+};
+export type DisclaimerAnswer = {
+    type: "Disclaimer";
+    check?: boolean;
+};
+export type FileUploaderAnswer = {
+    type: "FileUploader";
+    fileUrl?: string;
+};
+/** The ENTIRE option list, one entry per record option — never only the picked one. */
+export type MultipleOptionsAnswer = {
+    type: "MultipleOptionsQuestion";
+    choices: Array<{
+        key: string;
+        value: boolean;
+        index: number;
+    }>;
+    selectedOther?: boolean;
+};
+export type MMChoiceAnswer = {
+    type: "MMChoiceQuestion";
+    choices: Array<{
+        key: string;
+        value: boolean;
+    }>;
+};
+export type MultipleChoiceAnswer = {
+    type: "MultipleChoiceQuestion";
+    choices: Array<{
+        key: string;
+        value: boolean;
+    }>;
+};
+export type GraphicOptionsAnswer = {
+    type: "GraphicOptions";
+    value: string;
+    index: number;
+};
+export type MultipleChoiceSingleAnswerAnswer = {
+    type: "MultipleChoiceSingleAnswer";
+    value: string;
+    index: number;
+};
+/** Canonical IdentityInfo answer keys (mirrors IdentityInfoKeysArray; contract-tested). */
+export declare const IDENTITY_INFO_ANSWER_KEYS: readonly ["firstName", "lastName", "fullName", "emailAddress", "workEmailAddress", "phoneNumber", "companyName", "numberOfEmployees", "websiteUrl", "title", "streetAddress", "aptSuiteEtc", "city", "state", "country", "zipCode", "companyRevenue", "profilePictureUrl"];
+export type IdentityInfoAnswerKey = (typeof IDENTITY_INFO_ANSWER_KEYS)[number];
+export type IdentityInfoAnswer = {
+    type: "IdentityInfo";
+} & Partial<Record<IdentityInfoAnswerKey, string>>;
+/** Booking answers; `toSchedulerAnswerState` produces this — override `type` to the record's component type. */
+export type SchedulerAnswer = {
+    type: "CalendlyScreen" | "DynamicScheduler";
+    eventScheduled: boolean;
+    uri: string;
+    meetingTime?: string;
+    meetingEndTime?: string;
+    ownerEmails?: string;
+    guestEmails?: string;
+    inviteeName?: string;
+    googleMeetLink?: string;
+};
+export type KnownAnswerState = ShortInputAnswer | LongInputAnswer | EmailFormAnswer | DropdownAnswer | DisclaimerAnswer | FileUploaderAnswer | MultipleOptionsAnswer | MMChoiceAnswer | MultipleChoiceAnswer | GraphicOptionsAnswer | MultipleChoiceSingleAnswerAnswer | IdentityInfoAnswer | SchedulerAnswer;
+//# sourceMappingURL=answerStates.d.ts.map