@usefillo/core 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -161,6 +161,11 @@ interface FormTheme {
     radius?: string;
     fontFamily?: string;
 }
+/** Workspace branding state, resolved by the server from the plan. */
+interface FormBranding {
+    /** Show the "Powered by Fillo" badge. True on free plans; paid removes it. */
+    poweredBy: boolean;
+}
 /** A completed upload, referenced from response data. */
 interface FileValue {
     fileId: string;
@@ -182,21 +187,37 @@ type FieldValue = string | number | boolean | string[] | FileValue[]
 type ResponseData = Record<string, FieldValue>;
 type UploadStatus = "pending" | "uploading" | "complete" | "aborted";
 /**
- * How the browser should move the bytes.
- * - "formwork": chunked PUTs to the Fillo API (X-Upload-Offset protocol).
+ * How the browser should move the bytes — always straight to the workspace's own
+ * storage, never through the Fillo server.
  * - "gdrive": direct to a Google Drive resumable session URL (Content-Range
- *   protocol) — bytes never touch the Fillo server.
- * - "s3-put": a single PUT to a presigned S3/R2 URL — bytes go straight to the
- *   bucket.
+ *   protocol).
+ * - "s3-put": a single PUT to a presigned S3/R2 URL — straight to the bucket.
+ * - "box": direct to Box with a folder-scoped upload token — small files via a
+ *   single multipart POST, large files via Box's chunked session (the client
+ *   computes the SHA-1 digests Box requires). The server commits/verifies in the
+ *   complete step.
  */
 type UploadTransport = {
-    type: "formwork";
-} | {
     type: "gdrive";
     uploadUrl: string;
 } | {
     type: "s3-put";
     uploadUrl: string;
+} | {
+    type: "box";
+    mode: "simple";
+    uploadUrl: string;
+    token: string;
+    folderId: string;
+    fileName: string;
+} | {
+    type: "box";
+    mode: "chunked";
+    sessionUrl: string;
+    token: string;
+    folderId: string;
+    fileName: string;
+    size: number;
 };
 interface UploadSession {
     id: string;
@@ -341,6 +362,8 @@ interface PublishedForm {
     theme: FormTheme | null;
     /** True when the form has stopped accepting responses (closed/limit reached). */
     closed?: boolean;
+    /** Workspace branding state — absent means show the badge (default). */
+    branding?: FormBranding;
 }
 interface SubmitResult {
     ok: boolean;
@@ -354,6 +377,8 @@ interface SubmitMeta {
     hp?: string;
     /** Time from first render to submit. */
     elapsedMs?: number;
+    /** Embedding surface; "headless" submissions require a paid plan (server-enforced). */
+    surface?: "default" | "headless";
 }
 interface UploadProgress {
     uploadedBytes: number;
@@ -392,6 +417,7 @@ declare class FilloClient {
     syncForm(handle: string, schema: FormSchema, theme?: FormTheme | null): Promise<{
         formId: string;
         slug: string;
+        branding?: FormBranding;
     }>;
     /** Submit a response. Returns per-field errors instead of throwing on validation failure. */
     submit(formId: string, data: ResponseData, meta?: SubmitMeta): Promise<SubmitResult>;
@@ -420,7 +446,16 @@ declare class FilloClient {
      * form owner's Drive and never touch the Fillo server.
      */
     uploadFile(formId: string, file: File | Blob, options: UploadFileOptions): Promise<FileValue>;
-    private formworkUploadLoop;
+    /**
+     * Box direct upload with a folder-scoped token (Box UI Elements pattern).
+     * Small files go up in one multipart POST; large files run Box's chunked
+     * session entirely from the client — create session, PUT each part with a
+     * SHA-1 `Digest`, then commit with the whole-file digest. Bytes go straight to
+     * Box; we return the new file id for /complete to verify server-side.
+     */
+    private boxUpload;
+    /** Retry a request with exponential backoff; never retries an aborted upload. */
+    private retry;
     /**
      * Google Drive resumable protocol: PUT chunks with Content-Range; Drive
      * answers 308 + a Range header while incomplete, 200/201 when done. On
@@ -435,21 +470,68 @@ declare class FilloClient {
     private s3PutUpload;
 }
 declare function createClient(options?: FilloClientOptions): FilloClient;
+interface ProvisionWorkspaceResult {
+    /** Publishable key (pk_…) for the new workspace. Pass to createClient({ key }). */
+    key: string;
+    organizationId: string;
+    /** A claim link was emailed here so the owner can take ownership later. */
+    claim: {
+        email: string;
+        sent: boolean;
+    };
+    /** Caps applied until the workspace is claimed. */
+    limits: {
+        responses: number;
+        expiresAt: string;
+    };
+}
+/**
+ * Provision a Fillo workspace from an email — no signup — and get a publishable
+ * key back, so a form can collect real responses immediately. A claim link is
+ * emailed to `email`; until someone claims it the workspace runs as a capped
+ * preview (limited responses, for a limited time). Built for setup automation,
+ * e.g. a coding agent wiring Fillo into an app during integration.
+ *
+ *   const { key } = await provisionWorkspace({ email: "you@co.com" });
+ *   const client = createClient({ key });
+ */
+declare function provisionWorkspace(options: {
+    email: string;
+    baseUrl?: string;
+    /** Free-form provenance label, e.g. "agent" | "cli". */
+    source?: string;
+    fetch?: typeof fetch;
+}): Promise<ProvisionWorkspaceResult>;
 
 type FormStatus = "idle" | "submitting" | "submitted" | "error";
 interface FormControllerOptions {
     form: FormSchema;
     /** Target form id — required for client submission and funnel tracking. */
     formId?: string;
-    /** Collect responses into a Fillo workspace. Omit and pass `onSubmit` to keep them yourself. */
+    /**
+     * Collect responses into a Fillo workspace. Without a client the form is
+     * render-only (previews/tests); to also deliver responses to your own
+     * backend, use webhooks.
+     */
     client?: FilloClient;
     initialData?: ResponseData;
-    onChange?: (data: ResponseData) => void;
     onSubmitted?: (responseId: string | undefined, data: ResponseData) => void;
-    /** Handle submission yourself instead of the client. */
-    onSubmit?: (data: ResponseData) => Promise<void> | void;
+    onChange?: (data: ResponseData) => void;
     /** Honeypot value, supplied by your renderer; must be empty for a human. */
     getHoneypot?: () => string;
+    /**
+     * Let page navigation (next) move forward without validating the current page.
+     * For previews/builders where you want to flip through pages without filling
+     * the form in. Submission still validates.
+     */
+    skipValidation?: boolean;
+    /**
+     * Embedding surface. "headless" (a bare engine with no Fillo-rendered layout,
+     * i.e. createFormController / <FilloProvider>) is a paid capability the server
+     * enforces at submit. The framed renderers (<FilloForm>, renderForm) are
+     * "default". Defaults to "default".
+     */
+    surface?: "default" | "headless";
 }
 interface FormControllerState {
     data: ResponseData;
@@ -493,14 +575,14 @@ interface FormController {
     /** Drop all listeners. */
     destroy(): void;
 }
-/**
- * Framework-agnostic form engine: validation, conditional logic, pages, spam
- * signals, and submission as a subscribable store — with no rendering. Drive it
- * from vanilla JS, Vue, Svelte, or any framework and lay the fields out
- * yourself. (In React, `<FilloProvider>` / `useFillo()` wrap this same engine.)
- */
 declare function createFormController(options: FormControllerOptions): FormController;
 
+/** Result of syncing a code-defined form: its canonical id, slug, and branding. */
+interface SyncedForm {
+    formId: string;
+    slug: string;
+    branding?: FormBranding;
+}
 /**
  * A form whose structure lives in user code. Framework renderers can show it
  * immediately, then sync it into a Fillo workspace when a publishable key is
@@ -511,7 +593,7 @@ interface CodeForm {
     id: string;
     schema: FormSchema;
     theme?: FormTheme;
-    readonly __formworkCodeForm: true;
+    readonly __filloCodeForm: true;
 }
 declare function defineForm(def: {
     id: string;
@@ -522,14 +604,13 @@ declare function defineForm(def: {
     theme?: FormTheme;
 }): CodeForm;
 declare function isCodeForm(form: unknown): form is CodeForm;
+/** Stable djb2 hash of a string — used to key code-form sync by content. */
+declare function contentHash(input: string): string;
 /**
  * Sync a code-defined form into a workspace at most once per session for the
  * same client, handle, schema, and theme.
  */
-declare function syncCodeForm(client: FilloClient, form: CodeForm): Promise<{
-    formId: string;
-    slug: string;
-}>;
+declare function syncCodeForm(client: FilloClient, form: CodeForm): Promise<SyncedForm>;
 
 /**
  * Build initial response data from URL query parameters — Tally-style
@@ -551,4 +632,28 @@ declare function pipeBlock(block: Block, data: ResponseData, form: FormSchema):
 /** Dependency-free nanoid-style id with an unbiased alphabet. Crypto-random. */
 declare function createId(size?: number): string;
 
-export { BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CustomField, DRAFT_KINDS, type DateField, type DividerBlock, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, FilloClient, type FilloClientOptions, FilloError, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type HeadingBlock, type HiddenField, type JsonValue, type LinearScaleField, type MatrixField, type NumberField, type ParagraphBlock, type PublishedForm, type RankingField, type RatingField, type ResponseData, type SchemaValidationResult, type SelectOption, type SignatureField, type SubmitMeta, type SubmitResult, type TextField, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, allFields, assembleForm, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, formatAnswer, isBlockVisible, isCodeForm, isField, pipeBlock, prefillFromParams, resolveText, syncCodeForm, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields };
+/**
+ * Minimal streaming SHA-1 (FIPS 180-1). Vendored so the browser can checksum
+ * large uploads incrementally — Box requires a SHA-1 `Digest` on every chunk and
+ * on commit, and Web Crypto's `digest()` has no streaming API (it would force
+ * the whole file into memory). Validated against node:crypto in test/sha1.test.mjs.
+ *
+ * Only used by the Box upload transport; nothing else depends on it.
+ */
+declare class Sha1 {
+    private h0;
+    private h1;
+    private h2;
+    private h3;
+    private h4;
+    private readonly block;
+    private blockLen;
+    private totalLen;
+    private readonly w;
+    update(data: Uint8Array): this;
+    digest(): Uint8Array;
+    private process;
+}
+declare const sha1Base64: (bytes: Uint8Array) => string;
+
+export { BLOCK_KIND_META, type BaseField, type Block, type BlockKind, CONTENT_KINDS, type CheckboxField, type ChoiceField, type CodeForm, type Condition, type ConditionOp, type ContentBlock, type ContentKind, type CustomField, DRAFT_KINDS, type DateField, type DividerBlock, type Field, type FieldKind, type FieldSpec, type FieldValue, type FileUploadField, type FileValue, FilloClient, type FilloClientOptions, FilloError, type FormBranding, type FormController, type FormControllerOptions, type FormControllerState, type FormDraftSpec, type FormPage, type FormSchema, type FormSettings, type FormStatus, type FormTheme, type HeadingBlock, type HiddenField, type JsonValue, type LinearScaleField, type MatrixField, type NumberField, type ParagraphBlock, type ProvisionWorkspaceResult, type PublishedForm, type RankingField, type RatingField, type ResponseData, type SchemaValidationResult, type SelectOption, Sha1, type SignatureField, type SubmitMeta, type SubmitResult, type SyncedForm, type TextField, type UploadFileOptions, type UploadProgress, type UploadSession, type UploadStatus, type UploadTransport, type ValidationResult, allFields, assembleForm, contentHash, createBlock, createClient, createEmptyForm, createFormController, createId, defineForm, formatAnswer, isBlockVisible, isCodeForm, isField, pipeBlock, prefillFromParams, provisionWorkspace, resolveText, sha1Base64, syncCodeForm, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields };

package/dist/index.js

@@ -553,6 +553,116 @@ function assembleForm(spec) {
   return form;
 }
 
+// src/sha1.ts
+var Sha1 = class {
+  h0 = 1732584193;
+  h1 = 4023233417;
+  h2 = 2562383102;
+  h3 = 271733878;
+  h4 = 3285377520;
+  block = new Uint8Array(64);
+  blockLen = 0;
+  totalLen = 0;
+  w = new Int32Array(80);
+  update(data) {
+    this.totalLen += data.length;
+    let i = 0;
+    if (this.blockLen > 0) {
+      while (i < data.length && this.blockLen < 64) this.block[this.blockLen++] = data[i++];
+      if (this.blockLen === 64) {
+        this.process(this.block);
+        this.blockLen = 0;
+      }
+    }
+    while (i + 64 <= data.length) {
+      this.process(data.subarray(i, i + 64));
+      i += 64;
+    }
+    while (i < data.length) this.block[this.blockLen++] = data[i++];
+    return this;
+  }
+  digest() {
+    const bitsHi = Math.floor(this.totalLen / 536870912);
+    const bitsLo = this.totalLen * 8 >>> 0;
+    const pad = [128];
+    let len = this.blockLen + 1;
+    while (len % 64 !== 56) {
+      pad.push(0);
+      len++;
+    }
+    pad.push(bitsHi >>> 24 & 255, bitsHi >>> 16 & 255, bitsHi >>> 8 & 255, bitsHi & 255);
+    pad.push(bitsLo >>> 24 & 255, bitsLo >>> 16 & 255, bitsLo >>> 8 & 255, bitsLo & 255);
+    this.update(new Uint8Array(pad));
+    const out = new Uint8Array(20);
+    const h = [this.h0, this.h1, this.h2, this.h3, this.h4];
+    for (let i = 0; i < 5; i++) {
+      out[i * 4] = h[i] >>> 24 & 255;
+      out[i * 4 + 1] = h[i] >>> 16 & 255;
+      out[i * 4 + 2] = h[i] >>> 8 & 255;
+      out[i * 4 + 3] = h[i] & 255;
+    }
+    return out;
+  }
+  process(block) {
+    const w = this.w;
+    for (let i = 0; i < 16; i++) {
+      w[i] = block[i * 4] << 24 | block[i * 4 + 1] << 16 | block[i * 4 + 2] << 8 | block[i * 4 + 3];
+    }
+    for (let i = 16; i < 80; i++) {
+      const v = w[i - 3] ^ w[i - 8] ^ w[i - 14] ^ w[i - 16];
+      w[i] = v << 1 | v >>> 31;
+    }
+    let a = this.h0;
+    let b = this.h1;
+    let c = this.h2;
+    let d = this.h3;
+    let e = this.h4;
+    for (let i = 0; i < 80; i++) {
+      let f;
+      let k;
+      if (i < 20) {
+        f = b & c | ~b & d;
+        k = 1518500249;
+      } else if (i < 40) {
+        f = b ^ c ^ d;
+        k = 1859775393;
+      } else if (i < 60) {
+        f = b & c | b & d | c & d;
+        k = 2400959708;
+      } else {
+        f = b ^ c ^ d;
+        k = 3395469782;
+      }
+      const temp = (a << 5 | a >>> 27) + f + e + k + w[i] | 0;
+      e = d;
+      d = c;
+      c = b << 30 | b >>> 2;
+      b = a;
+      a = temp;
+    }
+    this.h0 = this.h0 + a | 0;
+    this.h1 = this.h1 + b | 0;
+    this.h2 = this.h2 + c | 0;
+    this.h3 = this.h3 + d | 0;
+    this.h4 = this.h4 + e | 0;
+  }
+};
+var B64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function bytesToBase64(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    out += B64[b0 >> 2];
+    out += B64[(b0 & 3) << 4 | b1 >> 4];
+    out += i + 1 < bytes.length ? B64[(b1 & 15) << 2 | b2 >> 6] : "=";
+    out += i + 2 < bytes.length ? B64[b2 & 63] : "=";
+  }
+  return out;
+}
+var sha1Base64 = (bytes) => bytesToBase64(new Sha1().update(bytes).digest());
+
 // src/client.ts
 var FilloError = class extends Error {
   constructor(message, status) {
@@ -570,6 +680,14 @@ function makeReporter(totalBytes, options) {
     fraction: totalBytes === 0 ? 1 : uploadedBytes / totalBytes
   });
 }
+async function digestPartBase64(bytes) {
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    const buf = await subtle.digest("SHA-1", bytes);
+    return bytesToBase64(new Uint8Array(buf));
+  }
+  return sha1Base64(bytes);
+}
 var DEFAULT_BASE_URL = "https://fillo.so";
 var FilloClient = class {
   /** Server origin this client targets, normalized (no trailing slash). */
@@ -702,63 +820,129 @@ var FilloClient = class {
         }
       );
     }
+    let completeBody;
     if (session.transport?.type === "gdrive") {
       await this.driveUploadLoop(session, session.transport.uploadUrl, file, options);
     } else if (session.transport?.type === "s3-put") {
       await this.s3PutUpload(session.transport.uploadUrl, file, options);
+    } else if (session.transport?.type === "box") {
+      completeBody = await this.boxUpload(session.transport, file, options);
     } else {
-      await this.formworkUploadLoop(session, file, options);
+      throw new FilloError("This form's storage doesn't support uploads \u2014 connect Drive, S3, or Box.");
     }
     const done = await this.json(
       `/uploads/${encodeURIComponent(session.id)}/complete`,
-      { method: "POST", headers: session.token ? { "X-Fillo-Upload-Token": session.token } : void 0 }
+      {
+        method: "POST",
+        headers: session.token ? { "X-Fillo-Upload-Token": session.token } : void 0,
+        ...completeBody ? { body: JSON.stringify(completeBody) } : {}
+      }
     );
     if (!done.file) throw new FilloError("Upload completed but no file was returned");
     return done.file;
   }
-  async formworkUploadLoop(session, file, options) {
-    let offset = session.uploadedBytes;
+  /**
+   * Box direct upload with a folder-scoped token (Box UI Elements pattern).
+   * Small files go up in one multipart POST; large files run Box's chunked
+   * session entirely from the client — create session, PUT each part with a
+   * SHA-1 `Digest`, then commit with the whole-file digest. Bytes go straight to
+   * Box; we return the new file id for /complete to verify server-side.
+   */
+  async boxUpload(transport, file, options) {
     const report = makeReporter(file.size, options);
-    report(offset);
+    report(0);
+    const auth = { Authorization: `Bearer ${transport.token}` };
+    if (transport.mode === "simple") {
+      const form = new FormData();
+      form.append(
+        "attributes",
+        JSON.stringify({ name: transport.fileName, parent: { id: transport.folderId } })
+      );
+      form.append("file", file, transport.fileName);
+      const res = await this.retry(
+        options,
+        () => this.fetch(transport.uploadUrl, { method: "POST", headers: auth, body: form, signal: options.signal })
+      );
+      if (!res.ok) throw new FilloError(`Box upload failed: ${res.status}`, res.status);
+      const body = await res.json();
+      report(file.size);
+      return { providerFileId: body.entries?.[0]?.id };
+    }
+    if (transport.size !== file.size) {
+      throw new FilloError(
+        `File size changed since the upload was requested (${file.size} vs ${transport.size}).`,
+        400
+      );
+    }
+    const sessionRes = await this.retry(
+      options,
+      () => this.fetch(transport.sessionUrl, {
+        method: "POST",
+        headers: { ...auth, "Content-Type": "application/json" },
+        body: JSON.stringify({
+          folder_id: transport.folderId,
+          file_size: transport.size,
+          file_name: transport.fileName
+        }),
+        signal: options.signal
+      })
+    );
+    if (!sessionRes.ok) throw new FilloError(`Box session failed: ${sessionRes.status}`, sessionRes.status);
+    const session = await sessionRes.json();
+    const whole = new Sha1();
+    const parts = [];
+    let offset = 0;
     while (offset < file.size) {
       options.signal?.throwIfAborted();
-      const chunk = file.slice(offset, offset + session.chunkSize);
-      let attempt = 0;
-      for (; ; ) {
-        try {
-          const res = await this.fetch(
-            this.url(`/uploads/${encodeURIComponent(session.id)}/chunk`),
-            {
-              method: "PUT",
-              headers: {
-                "Content-Type": "application/octet-stream",
-                "X-Upload-Offset": String(offset),
-                ...session.token ? { "X-Fillo-Upload-Token": session.token } : {}
-              },
-              body: chunk,
-              signal: options.signal
-            }
-          );
-          if (res.status === 409) {
-            const body2 = await res.json();
-            offset = body2.uploadedBytes;
-            break;
-          }
-          if (!res.ok) throw new FilloError(`Chunk failed: ${res.status}`, res.status);
-          const body = await res.json();
-          offset = body.uploadedBytes;
-          break;
-        } catch (err) {
-          if (options.signal?.aborted) throw err;
-          attempt += 1;
-          if (attempt >= MAX_CHUNK_RETRIES) throw err;
-          await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
-          const fresh = await this.getUploadSession(session.id, session.token);
-          offset = fresh.uploadedBytes;
-        }
-      }
+      const end = Math.min(offset + session.part_size, file.size);
+      const bytes = new Uint8Array(await file.slice(offset, end).arrayBuffer());
+      whole.update(bytes);
+      const partDigest = await digestPartBase64(bytes);
+      const res = await this.retry(
+        options,
+        () => this.fetch(session.session_endpoints.upload_part, {
+          method: "PUT",
+          headers: {
+            ...auth,
+            "Content-Type": "application/octet-stream",
+            Digest: `sha=${partDigest}`,
+            "Content-Range": `bytes ${offset}-${end - 1}/${file.size}`
+          },
+          body: bytes,
+          signal: options.signal
+        })
+      );
+      if (!res.ok) throw new FilloError(`Box part failed: ${res.status}`, res.status);
+      parts.push((await res.json()).part);
+      offset = end;
       report(offset);
     }
+    const commitRes = await this.retry(
+      options,
+      () => this.fetch(session.session_endpoints.commit, {
+        method: "POST",
+        headers: { ...auth, "Content-Type": "application/json", Digest: `sha=${bytesToBase64(whole.digest())}` },
+        body: JSON.stringify({ parts }),
+        signal: options.signal
+      })
+    );
+    if (!commitRes.ok) throw new FilloError(`Box commit failed: ${commitRes.status}`, commitRes.status);
+    const committed = await commitRes.json();
+    return { providerFileId: committed.entries?.[0]?.id };
+  }
+  /** Retry a request with exponential backoff; never retries an aborted upload. */
+  async retry(options, fn) {
+    let attempt = 0;
+    for (; ; ) {
+      try {
+        return await fn();
+      } catch (err) {
+        if (options.signal?.aborted) throw err;
+        attempt += 1;
+        if (attempt >= MAX_CHUNK_RETRIES) throw err;
+        await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
+      }
+    }
   }
   /**
    * Google Drive resumable protocol: PUT chunks with Content-Range; Drive
@@ -788,7 +972,9 @@ var FilloClient = class {
           if (res.status === 308) {
             const range = res.headers.get("Range") ?? res.headers.get("range");
             const match = range?.match(/bytes=0-(\d+)/);
-            offset = match ? Number(match[1]) + 1 : 0;
+            if (match) offset = Number(match[1]) + 1;
+            else if (range == null) offset = 0;
+            else offset = (await this.getUploadSession(session.id, session.token)).uploadedBytes;
             break;
           }
           if (res.ok) {
@@ -839,11 +1025,33 @@ var FilloClient = class {
 function createClient(options = {}) {
   return new FilloClient(options);
 }
+async function provisionWorkspace(options) {
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+  const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
+  const res = await doFetch(`${baseUrl}/api/v1/workspaces/provision`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ email: options.email, source: options.source ?? "sdk" })
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new FilloError(body || `Provision failed: ${res.status}`, res.status);
+  }
+  return await res.json();
+}
 
 // src/controller.ts
 var EMPTY_PAGE = { id: "empty", blocks: [] };
+var warnedNoClient = false;
+function warnNoClient() {
+  if (warnedNoClient) return;
+  warnedNoClient = true;
+  console.warn(
+    "[fillo] This form has no `client`, so responses can't be submitted \u2014 it's render-only. Pass a client (createClient) to collect responses in Fillo, or forward them to your own backend with webhooks: https://fillo.so/docs"
+  );
+}
 function createFormController(options) {
-  const { onChange, onSubmitted, onSubmit } = options;
+  const { onChange, onSubmitted } = options;
   let form = options.form;
   let formId = options.formId;
   let client = options.client;
@@ -878,6 +1086,13 @@ function createFormController(options) {
     snapshot = computeSnapshot();
     for (const listener of listeners) listener();
   }
+  function emitSubmitted(responseId, submitted) {
+    try {
+      onSubmitted?.(responseId, submitted);
+    } catch (err) {
+      console.error("[fillo] onSubmitted handler threw:", err);
+    }
+  }
   function validatePage(index) {
     const target = form.pages[index];
     if (!target) return {};
@@ -909,11 +1124,13 @@ function createFormController(options) {
   function next() {
     const pageCount = form.pages.length;
     const clamped = Math.min(pageIndex, Math.max(pageCount - 1, 0));
-    const pageErrors = validatePage(clamped);
-    errors = pageErrors;
-    if (Object.keys(pageErrors).length > 0) {
-      notify();
-      return;
+    if (!options.skipValidation) {
+      const pageErrors = validatePage(clamped);
+      errors = pageErrors;
+      if (Object.keys(pageErrors).length > 0) {
+        notify();
+        return;
+      }
     }
     pageIndex = Math.min(clamped + 1, pageCount - 1);
     if (sessionId && client) client.reportProgress(sessionId, { furthestPage: pageIndex });
@@ -934,39 +1151,42 @@ function createFormController(options) {
       notify();
       return;
     }
-    status = "submitting";
-    notify();
-    try {
-      if (onSubmit) {
-        await onSubmit(result.data);
-        status = "submitted";
-        notify();
-        onSubmitted?.(void 0, result.data);
-      } else if (client && formId) {
-        const res = await client.submit(formId, result.data, {
+    if (client && formId) {
+      status = "submitting";
+      notify();
+      let res;
+      try {
+        res = await client.submit(formId, result.data, {
           hp: options.getHoneypot?.() ?? "",
-          elapsedMs: Date.now() - mountedAt
+          elapsedMs: Date.now() - mountedAt,
+          surface: options.surface ?? "default"
         });
-        if (!res.ok) {
-          errors = res.errors ?? {};
-          status = "idle";
-          notify();
-          return;
-        }
-        if (sessionId) client.reportProgress(sessionId, { completed: true });
-        status = "submitted";
+      } catch (err) {
+        status = "idle";
         notify();
-        onSubmitted?.(res.responseId, result.data);
-      } else {
-        status = "submitted";
+        throw err;
+      }
+      if (!res.ok) {
+        errors = res.errors ?? {};
+        status = "idle";
         notify();
-        onSubmitted?.(void 0, result.data);
+        return;
       }
-    } catch (err) {
-      status = "idle";
+      if (sessionId) client.reportProgress(sessionId, { completed: true });
+      status = "submitted";
       notify();
-      throw err;
+      emitSubmitted(res.responseId, result.data);
+      return;
     }
+    if (options.skipValidation) {
+      status = "submitted";
+      notify();
+      emitSubmitted(void 0, result.data);
+      return;
+    }
+    warnNoClient();
+    status = "error";
+    notify();
   }
   return {
     getState: () => snapshot,
@@ -1007,11 +1227,11 @@ function defineForm(def) {
       pages: def.pages,
       settings: def.settings ?? {}
     },
-    __formworkCodeForm: true
+    __filloCodeForm: true
   };
 }
 function isCodeForm(form) {
-  return typeof form === "object" && form !== null && "__formworkCodeForm" in form;
+  return typeof form === "object" && form !== null && "__filloCodeForm" in form;
 }
 var syncCache = /* @__PURE__ */ new Map();
 function contentHash(input) {
@@ -1119,8 +1339,10 @@ export {
   DRAFT_KINDS,
   FilloClient,
   FilloError,
+  Sha1,
   allFields,
   assembleForm,
+  contentHash,
   createBlock,
   createClient,
   createEmptyForm,
@@ -1133,7 +1355,9 @@ export {
   isField,
   pipeBlock,
   prefillFromParams,
+  provisionWorkspace,
   resolveText,
+  sha1Base64,
   syncCodeForm,
   validateField,
   validateFormSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/core",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Form schema, validation, logic engine and JS client for Fillo. Framework-agnostic.",
   "license": "MIT",
   "keywords": [
@@ -10,11 +10,7 @@
     "headless",
     "typescript"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/jacobfunch/fillo.git",
-    "directory": "packages/core"
-  },
+  "homepage": "https://fillo.so",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",