@usefillo/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fillo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @usefillo/core
+
+The framework-agnostic core of [Fillo](https://fillo.so) — forms that render **inside your own product**, with your UI, no iframe.
+
+### 📚 Full documentation → **[fillo.so/docs](https://fillo.so/docs)**
+
+This package holds the shared foundation: the form schema, validation, the conditional-logic engine, response prefill/piping, and a JS client with a resumable upload protocol. It has **zero framework dependencies**.
+
+Most apps don't install this directly — you install a renderer (**[@usefillo/react](https://www.npmjs.com/package/@usefillo/react)** or **[@usefillo/dom](https://www.npmjs.com/package/@usefillo/dom)**), which re-exports everything here you need for embedding. Reach for `@usefillo/core` when you're building your own renderer or working with forms on the server.
+
+```sh
+npm i @usefillo/core
+```
+
+```ts
+import { createClient, defineForm, validateResponse, visibleBlocks } from "@usefillo/core";
+
+const client = createClient({ baseUrl: "https://fillo.so" });
+
+const form = defineForm({
+  id: "cust-feedback",
+  pages: [{ id: "p1", blocks: [
+    { id: "email", kind: "email", label: "Work email", required: true },
+    { id: "msg", kind: "long_text", label: "What should we know?" },
+  ] }],
+});
+```
+
+Key exports: `createClient` / `FilloClient`, `defineForm`, `validateResponse`, `validateField`, `visibleBlocks`, and the schema types (`FormSchema`, `Field`, `FieldKind`, `FormTheme`, `ResponseData`, …).
+
+## Links
+
+- **Docs:** [fillo.so/docs](https://fillo.so/docs)
+- **Website:** [fillo.so](https://fillo.so)
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,478 @@
+/**
+ * The Fillo form schema — the single source of truth shared by the builder,
+ * the embed SDK, the API and the responses grid.
+ */
+type ConditionOp = "eq" | "neq" | "contains" | "gt" | "lt" | "answered" | "not_answered";
+interface Condition {
+    fieldId: string;
+    op: ConditionOp;
+    value?: string | number | boolean;
+}
+type FieldKind = "short_text" | "long_text" | "email" | "url" | "phone" | "number" | "select" | "multi_select" | "dropdown" | "checkbox" | "rating" | "linear_scale" | "ranking" | "matrix" | "signature" | "date" | "file_upload" | "hidden" | "custom";
+type ContentKind = "heading" | "paragraph" | "divider";
+type BlockKind = FieldKind | ContentKind;
+interface SelectOption {
+    id: string;
+    label: string;
+}
+interface BaseBlock {
+    /** Stable id — for fields this is the key responses are stored under. */
+    id: string;
+    kind: BlockKind;
+    /** Show this block only when all conditions match (AND). Empty/undefined = always. */
+    visibleIf?: Condition[];
+}
+interface BaseField extends BaseBlock {
+    kind: FieldKind;
+    label: string;
+    description?: string;
+    required?: boolean;
+    placeholder?: string;
+}
+interface TextField extends BaseField {
+    kind: "short_text" | "long_text" | "email" | "url" | "phone";
+    maxLength?: number;
+}
+interface NumberField extends BaseField {
+    kind: "number";
+    min?: number;
+    max?: number;
+}
+interface ChoiceField extends BaseField {
+    kind: "select" | "multi_select" | "dropdown";
+    options: SelectOption[];
+    /** Append an "Other" choice with a free-text input; the typed text is stored as the value. */
+    allowOther?: boolean;
+    /** Show options in a random order per respondent (the "Other" choice stays last). */
+    shuffleOptions?: boolean;
+}
+interface CheckboxField extends BaseField {
+    kind: "checkbox";
+}
+interface RatingField extends BaseField {
+    kind: "rating";
+    /** Number of steps, default 5. */
+    max?: number;
+}
+interface DateField extends BaseField {
+    kind: "date";
+}
+interface LinearScaleField extends BaseField {
+    kind: "linear_scale";
+    /** Default 1. */
+    min?: number;
+    /** Default 10. */
+    max?: number;
+    minLabel?: string;
+    maxLabel?: string;
+}
+interface RankingField extends BaseField {
+    kind: "ranking";
+    options: SelectOption[];
+}
+interface MatrixField extends BaseField {
+    kind: "matrix";
+    /** Questions (one answer per row). */
+    rows: SelectOption[];
+    /** Answer columns. */
+    columns: SelectOption[];
+}
+interface SignatureField extends BaseField {
+    kind: "signature";
+}
+/**
+ * Never rendered. Value arrives via a URL query parameter — for campaign
+ * tags, user ids, A/B variants. Shown in the responses grid like any field.
+ */
+interface HiddenField extends BaseField {
+    kind: "hidden";
+    /** Query parameter name; defaults to the field id. */
+    paramName?: string;
+    defaultValue?: string;
+}
+interface FileUploadField extends BaseField {
+    kind: "file_upload";
+    /** Max files, default 1. */
+    maxFiles?: number;
+    /** Per-file size cap in MB. Default 500. */
+    maxFileSizeMb?: number;
+    /** Accepted types, e.g. ["image/*", ".pdf", "video/mp4"]. Empty = anything. */
+    accept?: string[];
+}
+/**
+ * A field type Fillo doesn't ship. You define it in code and supply the
+ * renderer via the SDK's `customComponents` map, keyed by `component`. The
+ * value is arbitrary JSON; core only enforces `required`. Your component does
+ * any richer validation and rendering — radios, sliders, address pickers,
+ * anything. See the embed docs.
+ */
+interface CustomField extends BaseField {
+    kind: "custom";
+    /** Key looked up in the SDK's `customComponents` map. */
+    component: string;
+    /** Arbitrary options handed to your component. */
+    config?: Record<string, unknown>;
+}
+type Field = TextField | NumberField | ChoiceField | CheckboxField | RatingField | LinearScaleField | RankingField | MatrixField | SignatureField | DateField | FileUploadField | HiddenField | CustomField;
+interface HeadingBlock extends BaseBlock {
+    kind: "heading";
+    text: string;
+}
+interface ParagraphBlock extends BaseBlock {
+    kind: "paragraph";
+    text: string;
+}
+interface DividerBlock extends BaseBlock {
+    kind: "divider";
+}
+type ContentBlock = HeadingBlock | ParagraphBlock | DividerBlock;
+type Block = Field | ContentBlock;
+declare const CONTENT_KINDS: ContentKind[];
+declare function isField(block: Block): block is Field;
+interface FormPage {
+    id: string;
+    title?: string;
+    blocks: Block[];
+}
+interface FormSettings {
+    submitLabel?: string;
+    successTitle?: string;
+    successMessage?: string;
+    redirectUrl?: string;
+    showProgress?: boolean;
+    /** Notify this address on every submission. */
+    notifyEmail?: string;
+    /** Send respondents a receipt (to the first answered email field). */
+    sendReceipt?: boolean;
+}
+interface FormSchema {
+    version: 1;
+    title: string;
+    description?: string;
+    pages: FormPage[];
+    settings: FormSettings;
+}
+interface FormTheme {
+    /** Accent for buttons, focus rings, selection. */
+    primary?: string;
+    background?: string;
+    text?: string;
+    /** Border radius scale, e.g. "8px". */
+    radius?: string;
+    fontFamily?: string;
+}
+/** A completed upload, referenced from response data. */
+interface FileValue {
+    fileId: string;
+    name: string;
+    size: number;
+    mime: string;
+    /** Download URL (may be storage-provider specific, e.g. a Drive link). */
+    url?: string;
+}
+/** Any JSON — what a custom field may hold. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+type FieldValue = string | number | boolean | string[] | FileValue[]
+/** Matrix answers: rowId → columnId. */
+ | Record<string, string>
+/** Custom fields hold arbitrary JSON. */
+ | JsonValue | null | undefined;
+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).
+ * - "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.
+ */
+type UploadTransport = {
+    type: "formwork";
+} | {
+    type: "gdrive";
+    uploadUrl: string;
+} | {
+    type: "s3-put";
+    uploadUrl: string;
+};
+interface UploadSession {
+    id: string;
+    formId: string;
+    fieldId: string;
+    fileName: string;
+    size: number;
+    mime: string;
+    /** Server-chosen chunk size in bytes. */
+    chunkSize: number;
+    /** Contiguous bytes received so far — resume from here. */
+    uploadedBytes: number;
+    status: UploadStatus;
+    /** Defaults to the Fillo protocol when omitted. */
+    transport?: UploadTransport;
+    /** Set when status is "complete". */
+    file?: FileValue;
+}
+
+/** All conditions must hold (AND). No conditions = visible. */
+declare function isBlockVisible(block: Block, data: ResponseData): boolean;
+declare function visibleBlocks(page: FormPage, data: ResponseData): Block[];
+/** Every field in the form (across pages), in order. */
+declare function allFields(form: FormSchema): Field[];
+/** Fields currently visible given the response data — the set that gets validated. */
+declare function visibleFields(form: FormSchema, data: ResponseData): Field[];
+
+/** Validate a single answered value for a field. Returns an error message or null. */
+declare function validateField(field: Field, value: FieldValue): string | null;
+interface ValidationResult {
+    ok: boolean;
+    /** fieldId -> message for every failing field. */
+    errors: Record<string, string>;
+    /** Data trimmed to the fields that are visible (hidden answers are dropped). */
+    data: ResponseData;
+}
+/**
+ * Validate a full submission against the schema. Only currently-visible fields
+ * are validated and kept — answers to fields hidden by logic are discarded.
+ */
+declare function validateResponse(form: FormSchema, data: ResponseData): ValidationResult;
+
+interface SchemaValidationResult {
+    ok: boolean;
+    /** Present when ok — a normalized, structurally-valid schema. */
+    schema?: FormSchema;
+    /** Present when !ok — a short human-readable reason. */
+    error?: string;
+}
+/** Validate an untrusted object as a FormSchema. Also enforces unique field ids. */
+declare function validateFormSchema(input: unknown): SchemaValidationResult;
+
+/**
+ * Canonical plain-text rendering of an answer — the single source of truth for
+ * the responses grid, CSV export, and notification emails. Returns "" for an
+ * empty answer. Rich per-surface rendering (links, stars, images) stays in the
+ * UI; this is the text everything agrees on.
+ *
+ * The switch is exhaustive with no `default`, so adding a field kind is a
+ * compile error here until it's handled — no silently-wrong exports/emails.
+ */
+declare function formatAnswer(field: Field, value: FieldValue): string;
+
+/** Display metadata for every block kind — drives the builder palette. */
+declare const BLOCK_KIND_META: Record<BlockKind, {
+    label: string;
+    hint: string;
+}>;
+/** A new block of the given kind with sensible defaults, ready for the builder. */
+declare function createBlock(kind: BlockKind): Block;
+/** A minimal valid empty form. */
+declare function createEmptyForm(title?: string): FormSchema;
+
+/**
+ * Turning a natural-language goal into a form: an LLM is good at choosing the
+ * right *questions*, but unreliable at the structural plumbing (stable ids,
+ * exact per-kind config). So generation targets this lossy spec, and the
+ * assembler below rebuilds a structurally-sound schema from `createBlock`
+ * defaults — the model only ever supplies the human-meaningful parts.
+ */
+/**
+ * Field kinds the generator may use. Excludes hidden/custom/signature: the
+ * first two are code-only concerns and signature is too niche to draft well.
+ */
+declare const DRAFT_KINDS: readonly BlockKind[];
+/** The LLM-friendly intermediate shape. Everything optional but `kind`. */
+interface FieldSpec {
+    kind: string;
+    label?: string;
+    required?: boolean;
+    /** Choice / ranking options, or matrix is handled by rows+columns. */
+    options?: string[];
+    min?: number;
+    max?: number;
+    minLabel?: string;
+    maxLabel?: string;
+    rows?: string[];
+    columns?: string[];
+    placeholder?: string;
+    /** Content for heading / paragraph blocks. */
+    text?: string;
+}
+interface FormDraftSpec {
+    title?: string;
+    description?: string;
+    pages?: Array<{
+        title?: string;
+        fields?: FieldSpec[];
+    }>;
+}
+/**
+ * Build a valid {@link FormSchema} from an untrusted draft spec. Unknown kinds
+ * and empty pages are dropped; if nothing survives, a single empty page is
+ * kept so the builder always has something to render. The result should still
+ * be passed through `validateFormSchema` before persisting.
+ */
+declare function assembleForm(spec: FormDraftSpec): FormSchema;
+
+interface FilloClientOptions {
+    /** Origin of the Fillo server, e.g. "https://forms.example.com". */
+    baseUrl: string;
+    /**
+     * Publishable workspace key (pk_…) — safe to ship in client code. Required
+     * only for syncing code-defined forms into the workspace.
+     */
+    key?: string;
+    fetch?: typeof fetch;
+}
+interface PublishedForm {
+    id: string;
+    slug: string;
+    schema: FormSchema;
+    theme: FormTheme | null;
+    /** True when the form has stopped accepting responses (closed/limit reached). */
+    closed?: boolean;
+}
+interface SubmitResult {
+    ok: boolean;
+    responseId?: string;
+    /** fieldId -> message when the server rejects the submission. */
+    errors?: Record<string, string>;
+}
+/** Anti-spam signals collected by the renderer. */
+interface SubmitMeta {
+    /** Honeypot value — must be empty for humans. */
+    hp?: string;
+    /** Time from first render to submit. */
+    elapsedMs?: number;
+}
+interface UploadProgress {
+    uploadedBytes: number;
+    totalBytes: number;
+    /** 0..1 */
+    fraction: number;
+}
+interface UploadFileOptions {
+    fieldId: string;
+    onProgress?: (progress: UploadProgress) => void;
+    signal?: AbortSignal;
+    /** Resume an interrupted session instead of starting fresh. */
+    sessionId?: string;
+}
+declare class FilloError extends Error {
+    status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+declare class FilloClient {
+    /** Server origin this client targets, normalized (no trailing slash). */
+    readonly baseUrl: string;
+    private fetch;
+    /** Publishable workspace key, when configured. */
+    readonly key?: string;
+    constructor(options: FilloClientOptions);
+    private url;
+    private json;
+    /** Fetch a published form definition by id or slug. */
+    getForm(idOrSlug: string): Promise<PublishedForm>;
+    /**
+     * Upsert a code-defined form into the workspace identified by the client's
+     * publishable key. Returns the canonical form id used for submissions.
+     */
+    syncForm(handle: string, schema: FormSchema, theme?: FormTheme | null): Promise<{
+        formId: string;
+        slug: string;
+    }>;
+    /** Submit a response. Returns per-field errors instead of throwing on validation failure. */
+    submit(formId: string, data: ResponseData, meta?: SubmitMeta): Promise<SubmitResult>;
+    /**
+     * Open a respondent session for funnel analysis. Fire-and-forget: returns the
+     * session id, or null if tracking is unavailable (never blocks the form).
+     */
+    startSession(formId: string, pageCount: number): Promise<string | null>;
+    /** Report progress on a session (furthest page reached, or completion). */
+    reportProgress(sessionId: string, data: {
+        furthestPage?: number;
+        completed?: boolean;
+    }): void;
+    /** Current state of an upload session — used to resume after interruption. */
+    getUploadSession(sessionId: 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
+     * goes into the response data. Survives flaky connections: each chunk is
+     * retried, and on repeated failure the true offset is re-queried so no byte
+     * is sent twice or skipped.
+     *
+     * Depending on the form's storage settings the server picks a transport:
+     * Fillo's own chunk protocol, or direct-to-Google-Drive resumable
+     * sessions — in which case the bytes go straight from this browser to the
+     * form owner's Drive and never touch the Fillo server.
+     */
+    uploadFile(formId: string, file: File | Blob, options: UploadFileOptions): Promise<FileValue>;
+    private formworkUploadLoop;
+    /**
+     * Google Drive resumable protocol: PUT chunks with Content-Range; Drive
+     * answers 308 + a Range header while incomplete, 200/201 when done. On
+     * repeated failure we re-sync through our session endpoint (the server
+     * queries Drive for the authoritative offset).
+     */
+    private driveUploadLoop;
+    /**
+     * S3-compatible single PUT to a presigned URL — bytes go straight to the
+     * bucket. Not resumable (S3 single PUT is atomic), but retried on failure.
+     */
+    private s3PutUpload;
+}
+declare function createClient(options: FilloClientOptions): FilloClient;
+
+/**
+ * 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
+ * present so responses, uploads, webhooks, and exports work normally.
+ */
+interface CodeForm {
+    /** Stable handle, unique in the workspace. */
+    id: string;
+    schema: FormSchema;
+    theme?: FormTheme;
+    readonly __formworkCodeForm: true;
+}
+declare function defineForm(def: {
+    id: string;
+    title?: string;
+    description?: string;
+    pages: FormPage[];
+    settings?: FormSchema["settings"];
+    theme?: FormTheme;
+}): CodeForm;
+declare function isCodeForm(form: unknown): form is CodeForm;
+/**
+ * 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;
+}>;
+
+/**
+ * Build initial response data from URL query parameters — Tally-style
+ * prefilling. Hidden fields read their configured paramName; every other
+ * field can be prefilled by its id. Values are coerced per kind and
+ * validated against options, so a crafted URL can't inject invalid answers.
+ */
+declare function prefillFromParams(form: FormSchema, params: Record<string, string | undefined>): ResponseData;
+
+/**
+ * Resolve `{{field_id}}` tokens in a string against the current answers —
+ * "answer piping". Choice answers resolve to their option label, not the id.
+ * Unanswered references become empty.
+ */
+declare function resolveText(text: string, data: ResponseData, form: FormSchema): string;
+/** 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. */
+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 };