@usefillo/core 0.1.0 → 0.2.1

package/dist/index.d.ts

@@ -212,6 +212,11 @@ interface UploadSession {
     status: UploadStatus;
     /** Defaults to the Fillo protocol when omitted. */
     transport?: UploadTransport;
+    /**
+     * Per-session bearer returned at creation; sent back (X-Fillo-Upload-Token)
+     * on chunk/complete/status so only the creator can drive this upload.
+     */
+    token?: string;
     /** Set when status is "complete". */
     file?: FileValue;
 }
@@ -316,8 +321,12 @@ interface FormDraftSpec {
 declare function assembleForm(spec: FormDraftSpec): FormSchema;
 
 interface FilloClientOptions {
-    /** Origin of the Fillo server, e.g. "https://forms.example.com". */
-    baseUrl: string;
+    /**
+     * Where the SDK sends requests. Defaults to the hosted API (https://fillo.so).
+     * Only set this if you reverse-proxy Fillo through your own domain — e.g. to
+     * keep traffic first-party or dodge ad-blockers, like PostHog's api_host.
+     */
+    baseUrl?: string;
     /**
      * Publishable workspace key (pk_…) — safe to ship in client code. Required
      * only for syncing code-defined forms into the workspace.
@@ -358,6 +367,8 @@ interface UploadFileOptions {
     signal?: AbortSignal;
     /** Resume an interrupted session instead of starting fresh. */
     sessionId?: string;
+    /** Ownership token for the resumed session (from the original create call). */
+    uploadToken?: string;
 }
 declare class FilloError extends Error {
     status?: number | undefined;
@@ -369,7 +380,7 @@ declare class FilloClient {
     private fetch;
     /** Publishable workspace key, when configured. */
     readonly key?: string;
-    constructor(options: FilloClientOptions);
+    constructor(options?: FilloClientOptions);
     private url;
     private json;
     /** Fetch a published form definition by id or slug. */
@@ -395,7 +406,7 @@ declare class FilloClient {
         completed?: boolean;
     }): void;
     /** Current state of an upload session — used to resume after interruption. */
-    getUploadSession(sessionId: string): Promise<UploadSession>;
+    getUploadSession(sessionId: string, token?: string): Promise<UploadSession>;
     /**
      * Resumable chunked upload. Creates (or resumes) a session, streams the file
      * chunk by chunk with progress callbacks, and finalizes into a FileValue that
@@ -423,7 +434,72 @@ declare class FilloClient {
      */
     private s3PutUpload;
 }
-declare function createClient(options: FilloClientOptions): FilloClient;
+declare function createClient(options?: FilloClientOptions): FilloClient;
+
+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. */
+    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;
+    /** Honeypot value, supplied by your renderer; must be empty for a human. */
+    getHoneypot?: () => string;
+}
+interface FormControllerState {
+    data: ResponseData;
+    errors: Record<string, string>;
+    status: FormStatus;
+    pageIndex: number;
+    pageCount: number;
+    /** The current page (after clamping). */
+    page: FormPage;
+    /** Blocks visible on the current page, after conditional logic. */
+    blocks: Block[];
+    isFirstPage: boolean;
+    isLastPage: boolean;
+    /** True while any file field is uploading. */
+    uploading: boolean;
+}
+interface FormController {
+    /** Stable snapshot — same reference until something changes (safe for useSyncExternalStore). */
+    getState(): FormControllerState;
+    /** Subscribe to state changes; returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    setValue(fieldId: string, value: FieldValue): void;
+    /** Mark a file field busy/idle so `state.uploading` reflects it. */
+    setUploading(fieldId: string, busy: boolean): void;
+    /** Validate the current page, then advance. No-op on the last page or with errors. */
+    next(): void;
+    back(): void;
+    submit(): Promise<void>;
+    /**
+     * Late-bind inputs after creation, keeping current answers/page/status:
+     * - `form` updates the rendered schema in place (a builder live preview being
+     *   edited), recomputing visible blocks and re-notifying.
+     * - `formId`/`client` set the submission target (e.g. a code-defined form id
+     *   that resolves asynchronously).
+     */
+    setContext(ctx: {
+        form?: FormSchema;
+        formId?: string;
+        client?: FilloClient;
+    }): void;
+    /** 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;
 
 /**
  * A form whose structure lives in user code. Framework renderers can show it
@@ -472,7 +548,7 @@ declare function resolveText(text: string, data: ResponseData, form: FormSchema)
 /** Return a copy of a block with its visible text fields piped, or the block unchanged. */
 declare function pipeBlock(block: Block, data: ResponseData, form: FormSchema): Block;
 
-/** Dependency-free nanoid-style id. Crypto-random where available. */
+/** 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 FormDraftSpec, type FormPage, type FormSchema, type FormSettings, 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, createId, defineForm, formatAnswer, isBlockVisible, isCodeForm, isField, pipeBlock, prefillFromParams, resolveText, syncCodeForm, validateField, validateFormSchema, validateResponse, visibleBlocks, visibleFields };
+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 };

package/dist/index.js

@@ -335,15 +335,21 @@ function formatAnswer(field, value) {
 
 // src/ids.ts
 var ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+var MASK = 256 - 256 % ALPHABET.length;
 function createId(size = 12) {
-  const bytes = new Uint8Array(size);
-  if (typeof globalThis.crypto !== "undefined") {
-    globalThis.crypto.getRandomValues(bytes);
-  } else {
-    for (let i = 0; i < size; i++) bytes[i] = Math.floor(Math.random() * 256);
-  }
   let id = "";
-  for (let i = 0; i < size; i++) id += ALPHABET[bytes[i] % ALPHABET.length];
+  while (id.length < size) {
+    const bytes = new Uint8Array(size);
+    if (typeof globalThis.crypto !== "undefined") {
+      globalThis.crypto.getRandomValues(bytes);
+    } else {
+      for (let i = 0; i < size; i++) bytes[i] = Math.floor(Math.random() * 256);
+    }
+    for (let i = 0; i < size && id.length < size; i++) {
+      const b = bytes[i];
+      if (b < MASK) id += ALPHABET[b % ALPHABET.length];
+    }
+  }
   return id;
 }
 
@@ -564,14 +570,15 @@ function makeReporter(totalBytes, options) {
     fraction: totalBytes === 0 ? 1 : uploadedBytes / totalBytes
   });
 }
+var DEFAULT_BASE_URL = "https://fillo.so";
 var FilloClient = class {
   /** Server origin this client targets, normalized (no trailing slash). */
   baseUrl;
   fetch;
   /** Publishable workspace key, when configured. */
   key;
-  constructor(options) {
-    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
     this.key = options.key;
     this.fetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
   }
@@ -657,8 +664,11 @@ var FilloClient = class {
     }
   }
   /** Current state of an upload session — used to resume after interruption. */
-  getUploadSession(sessionId) {
-    return this.json(`/uploads/${encodeURIComponent(sessionId)}`);
+  getUploadSession(sessionId, token) {
+    return this.json(
+      `/uploads/${encodeURIComponent(sessionId)}`,
+      token ? { headers: { "X-Fillo-Upload-Token": token } } : void 0
+    );
   }
   /**
    * Resumable chunked upload. Creates (or resumes) a session, streams the file
@@ -677,7 +687,7 @@ var FilloClient = class {
     const mime = file.type || "application/octet-stream";
     let session;
     if (options.sessionId) {
-      session = await this.getUploadSession(options.sessionId);
+      session = await this.getUploadSession(options.sessionId, options.uploadToken);
     } else {
       session = await this.json(
         `/forms/${encodeURIComponent(formId)}/uploads`,
@@ -701,7 +711,7 @@ var FilloClient = class {
     }
     const done = await this.json(
       `/uploads/${encodeURIComponent(session.id)}/complete`,
-      { method: "POST" }
+      { method: "POST", headers: session.token ? { "X-Fillo-Upload-Token": session.token } : void 0 }
     );
     if (!done.file) throw new FilloError("Upload completed but no file was returned");
     return done.file;
@@ -722,7 +732,8 @@ var FilloClient = class {
               method: "PUT",
               headers: {
                 "Content-Type": "application/octet-stream",
-                "X-Upload-Offset": String(offset)
+                "X-Upload-Offset": String(offset),
+                ...session.token ? { "X-Fillo-Upload-Token": session.token } : {}
               },
               body: chunk,
               signal: options.signal
@@ -742,7 +753,7 @@ var FilloClient = class {
           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);
+          const fresh = await this.getUploadSession(session.id, session.token);
           offset = fresh.uploadedBytes;
         }
       }
@@ -790,7 +801,7 @@ var FilloClient = class {
           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);
+          const fresh = await this.getUploadSession(session.id, session.token);
           offset = fresh.uploadedBytes;
         }
       }
@@ -825,10 +836,165 @@ var FilloClient = class {
     }
   }
 };
-function createClient(options) {
+function createClient(options = {}) {
   return new FilloClient(options);
 }
 
+// src/controller.ts
+var EMPTY_PAGE = { id: "empty", blocks: [] };
+function createFormController(options) {
+  const { onChange, onSubmitted, onSubmit } = options;
+  let form = options.form;
+  let formId = options.formId;
+  let client = options.client;
+  let data = { ...options.initialData ?? {} };
+  let errors = {};
+  let pageIndex = 0;
+  let status = "idle";
+  const uploadingFields = /* @__PURE__ */ new Set();
+  const listeners = /* @__PURE__ */ new Set();
+  const mountedAt = Date.now();
+  let sessionId = null;
+  let sessionStarted = false;
+  function computeSnapshot() {
+    const pageCount = form.pages.length;
+    const clamped = Math.min(pageIndex, Math.max(pageCount - 1, 0));
+    const page = form.pages[clamped] ?? EMPTY_PAGE;
+    return {
+      data,
+      errors,
+      status,
+      pageIndex: clamped,
+      pageCount,
+      page,
+      blocks: visibleBlocks(page, data),
+      isFirstPage: clamped === 0,
+      isLastPage: clamped === pageCount - 1,
+      uploading: uploadingFields.size > 0
+    };
+  }
+  let snapshot = computeSnapshot();
+  function notify() {
+    snapshot = computeSnapshot();
+    for (const listener of listeners) listener();
+  }
+  function validatePage(index) {
+    const target = form.pages[index];
+    if (!target) return {};
+    const pageErrors = {};
+    for (const block of visibleBlocks(target, data)) {
+      if (!isField(block)) continue;
+      const error = validateField(block, data[block.id]);
+      if (error) pageErrors[block.id] = error;
+    }
+    return pageErrors;
+  }
+  function setValue(fieldId, value) {
+    if (!sessionStarted && client && formId) {
+      sessionStarted = true;
+      void client.startSession(formId, form.pages.length).then((id) => sessionId = id);
+    }
+    data = { ...data, [fieldId]: value };
+    onChange?.(data);
+    if (fieldId in errors) {
+      errors = Object.fromEntries(Object.entries(errors).filter(([k]) => k !== fieldId));
+    }
+    notify();
+  }
+  function setUploading(fieldId, busy) {
+    if (busy) uploadingFields.add(fieldId);
+    else uploadingFields.delete(fieldId);
+    notify();
+  }
+  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;
+    }
+    pageIndex = Math.min(clamped + 1, pageCount - 1);
+    if (sessionId && client) client.reportProgress(sessionId, { furthestPage: pageIndex });
+    notify();
+  }
+  function back() {
+    errors = {};
+    pageIndex = Math.max(Math.min(pageIndex, form.pages.length - 1) - 1, 0);
+    notify();
+  }
+  async function submit() {
+    if (status === "submitting" || status === "submitted") return;
+    const result = validateResponse(form, data);
+    if (!result.ok) {
+      errors = result.errors;
+      const firstBad = form.pages.findIndex((p) => p.blocks.some((b) => b.id in result.errors));
+      if (firstBad >= 0) pageIndex = firstBad;
+      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, {
+          hp: options.getHoneypot?.() ?? "",
+          elapsedMs: Date.now() - mountedAt
+        });
+        if (!res.ok) {
+          errors = res.errors ?? {};
+          status = "idle";
+          notify();
+          return;
+        }
+        if (sessionId) client.reportProgress(sessionId, { completed: true });
+        status = "submitted";
+        notify();
+        onSubmitted?.(res.responseId, result.data);
+      } else {
+        status = "submitted";
+        notify();
+        onSubmitted?.(void 0, result.data);
+      }
+    } catch (err) {
+      status = "idle";
+      notify();
+      throw err;
+    }
+  }
+  return {
+    getState: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    setValue,
+    setUploading,
+    next,
+    back,
+    submit,
+    setContext(ctx) {
+      if ("formId" in ctx) formId = ctx.formId;
+      if ("client" in ctx) client = ctx.client;
+      if (ctx.form && ctx.form !== form) {
+        form = ctx.form;
+        notify();
+      }
+    },
+    destroy() {
+      listeners.clear();
+    }
+  };
+}
+
 // src/define.ts
 function defineForm(def) {
   return {
@@ -958,6 +1124,7 @@ export {
   createBlock,
   createClient,
   createEmptyForm,
+  createFormController,
   createId,
   defineForm,
   formatAnswer,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefillo/core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Form schema, validation, logic engine and JS client for Fillo. Framework-agnostic.",
   "license": "MIT",
   "keywords": [
@@ -42,6 +42,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
     "dev": "tsup src/index.ts --format esm --dts --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "node --test test/*.test.mjs"
   }
 }