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

package/README.md

@@ -0,0 +1,63 @@
+# Surface Forms SDK
+
+Build Surface forms as **your own pages**. The form record on Surface stays the
+data model — steps, questions, validation, enrichment, tracking settings — while
+your HTML/CSS/JS owns every pixel and every navigation decision. The SDK binds
+the two: a headless, dependency-free engine over Surface's public runtime
+endpoints, a `data-*` DOM binding layer, a React adapter, an unstyled booking
+widget for Surface schedulers, and settings-driven tag/conversion tracking
+(GTM/GA4/Meta/HubSpot + ad conversions). ~18 kB gzipped, zero runtime
+dependencies.
+
+> **Working with an AI agent?** This package ships agent-ready docs:
+> [`llms.txt`](llms.txt) is the binding contract and boot guide,
+> [`docs/api.md`](docs/api.md) is the complete public API reference (every
+> export with semantics), and
+> [`skills/surface-forms-sdk/SKILL.md`](skills/surface-forms-sdk/SKILL.md) is
+> the full authoring workflow (create the record → bind HTML → validate →
+> preview → publish → verify) with a starter template, HTML patterns, an
+> editing sync-loop, and a debugging runbook. Point your agent at these before
+> it writes a line of HTML — or install the skill into your agent runner
+> (e.g. copy the folder into `.claude/skills/`).
+
+## Quick start
+
+```js
+import { SurfaceForms } from "<this package>"; // import from the name you installed
+
+const form = await SurfaceForms.init({
+  environmentId: "env_…", // from the get_sdk_binding_map MCP tool
+  formId: "form_…",
+  apiBaseUrl: "https://…", // ALSO from get_sdk_binding_map — required off the default host
+  container: document.querySelector("#form"),
+});
+```
+
+Mark up your page with `data-question-id` / `data-field-name` /
+`data-question-type` / `data-step-id` and the SDK captures answers, saves
+progress, and reveals your thank-you step on submit. Routing is yours:
+`surface-next-button` / `data-surface-goto-step` markers for the declarative
+cases, `form.next()` / `form.goToStep()` / `form.disqualify()` when your code
+decides. See `llms.txt` for the full contract.
+
+Highlights beyond binding:
+
+- **Headless + React** — drive everything with `setAnswer`/`submit`/`state`,
+  or `useSurfaceForm` from `<package>/react`.
+- **Resume** — persist the `saved` event's `{ responseId, resumeToken }` and
+  pass `resume:` to continue a response later.
+- **Email validation** — `form.validateEmail()` on demand, or
+  `emailValidation: true` for automatic native-parity verdict meta.
+- **Real-time enrichment** — automatic when the environment has an enabled
+  provider; check `form.capabilities.enrichment`.
+- **Preview mode** — `preview: true` (+ `previewToken` for unpublished drafts)
+  renders and navigates with zero network writes.
+- **Reliable finish** — the terminal write is awaited; `await form.flush()`
+  before programmatic teardown.
+
+## Authoring loop (with the Surface MCP tools)
+
+`create_form (sdk: true)` → `get_sdk_binding_map` → author HTML →
+`validate_form_html` → preview → `publish_form` → submit a test response →
+`get_response` to confirm every answer landed. Each tool reply carries the next
+step; the skill file documents the loop end-to-end.