@onabl/js 0.1.0

package/README.md

@@ -0,0 +1,25 @@
+# `@onabl/js`
+
+Framework-agnostic core of the onabl SDK. No React, no DOM assumptions —
+`@onabl/react` and `@onabl/next` build on top of this.
+
+**Status:** skeleton only (Phase 14 §14.5.2, in progress). See
+`docs/SDK-DESIGN.md` for the full intended API surface before adding to this
+package, and `docs/INTEGRATION-LAYER-TODO.md` for current build status.
+
+## What belongs here
+
+- `createOnablClient()` — the typed API client
+- `OnablError` and its subclasses (`OnablNotFound`, `OnablUnauthorized`,
+  `OnablValidation`, `OnablNetwork`)
+- The condition evaluator and form state machine, extracted from
+  `apps/web/components/form/MultiStepForm.tsx`
+- `presentQuote` / `groupLineItems`, re-exported (and bundled — see
+  `tsup.config.ts`) from `@onabl/engine`, which is never published on its own
+
+## Build
+
+Built with `tsup`, not plain `tsc` — `@onabl/engine`'s presentation code has
+to be bundled into this package's output since `@onabl/engine` itself is
+private and never installable on its own. See the comment in
+`tsup.config.ts` before changing the dependency/build setup.

package/dist/index.d.mts

@@ -0,0 +1,146 @@
+import { PublicForm, ValidateCodeResponse, Quote, Invoice, PresignResponse, PublicFormField } from '@onabl/contracts/public-api';
+export { Invoice, PublicForm, PublicFormConfig, PublicFormField, Quote, ValidateCodeResponse } from '@onabl/contracts/public-api';
+import { AnswerMap, FormStep } from '@onabl/types/config';
+export { GroupedItems, PresentQuoteInput, QuotePresentation, QuoteRow, SeparateSection, groupLineItems, presentQuote } from '@onabl/engine/presentation';
+
+interface OnablClientConfig {
+    handle: string;
+    secretKey: string;
+    baseUrl?: string;
+    apiVersion?: string;
+    /** Path template for the quote view page on the integrator's own site — see submissions.create()'s returned quoteUrl. */
+    quotePath?: string;
+}
+interface CallOpts {
+    /** Slug of a specific form, for tenants running more than one. Omitted, resolves to the tenant's dashboard-configured default. */
+    slug?: string;
+}
+/**
+ * Customer-token-scoped calls need a bearer token — @onabl/next supplies one
+ * automatically from its managed cookie (SDK-DESIGN.md §3, "Access cookie").
+ * Used directly (e.g. a Vite/plain-React app per SDK-DESIGN.md §4, "Route
+ * handler only" decision), the caller supplies it explicitly.
+ */
+interface TokenOpts {
+    token: string;
+}
+interface OnablClient {
+    forms: {
+        get(opts?: CallOpts): Promise<PublicForm>;
+        validateDiscountCode(code: string, opts?: CallOpts): Promise<ValidateCodeResponse>;
+    };
+    quotes: {
+        get(uuid: string, opts: TokenOpts): Promise<Quote>;
+        accept(uuid: string, opts: TokenOpts): Promise<void>;
+        decline(uuid: string, reason: string, note: string | undefined, opts: TokenOpts): Promise<void>;
+    };
+    invoices: {
+        get(uuid: string, opts: TokenOpts): Promise<Invoice>;
+        /** milestone "deposit" saves the deposit POP; "balance"/"full" save the balance/full-payment POP. */
+        savePopUrl(uuid: string, key: string, milestone: "deposit" | "balance" | "full", opts: TokenOpts): Promise<void>;
+    };
+    storage: {
+        /** Presigns an upload for a customer-facing flow (currently only invoice POP uploads — pathPrefix is always "pop"). */
+        presignPop(resourceId: string, filename: string, contentType: string, fileSize: number, opts: TokenOpts): Promise<PresignResponse>;
+    };
+    submissions: {
+        /** isTenantSource marks a submission taken by the tenant on the customer's behalf (the on-site quote tool) rather than the customer directly — see docs/ROADMAP.md Phase 2.11. */
+        create(answers: AnswerMap, opts?: CallOpts & {
+            consentGiven?: boolean;
+            discountCode?: string;
+            isTenantSource?: boolean;
+        }): Promise<{
+            quoteId: string;
+            quoteUrl: string;
+            token: string;
+        }>;
+    };
+}
+declare function createOnablClient(config: OnablClientConfig): OnablClient;
+
+/**
+ * Typed error classes so a catch block can discriminate without matching on
+ * HTTP status numbers or string messages. See docs/SDK-DESIGN.md §3.
+ */
+declare class OnablError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** 404, or a customer token that doesn't grant access to this resource. */
+declare class OnablNotFound extends OnablError {
+    constructor(message?: string);
+}
+/** Missing or invalid secret key / customer token. */
+declare class OnablUnauthorized extends OnablError {
+    constructor(message?: string);
+}
+/** 400 — carries field-level detail from the API's Zod validation errors. */
+declare class OnablValidation extends OnablError {
+    readonly fieldErrors?: Record<string, string[]> | undefined;
+    constructor(message: string, fieldErrors?: Record<string, string[]> | undefined);
+}
+/** Transport failure — network error, timeout, or an unparseable response. */
+declare class OnablNetwork extends OnablError {
+    constructor(message?: string, cause?: unknown);
+}
+
+/**
+ * The form state machine, extracted from apps/web/components/form/MultiStepForm.tsx
+ * (§14.5.2, part 2). Pure functions only — no React, no framework of any kind —
+ * so any UI layer (a React hook in @onabl/react, or something else entirely)
+ * can drive the same tested logic. Renders nothing; every function here takes
+ * a snapshot of state and returns a value, never mutates.
+ *
+ * Deliberately excludes three things apps/web's current implementation
+ * handles that the documented useOnablForm surface (docs/SDK-DESIGN.md §3)
+ * does not — decided 2026-08-24, see docs/INTEGRATION-LAYER-TODO.md:
+ *
+ * - Intro screen: not modeled as a step here at all. It's pure presentation
+ *   (config.meta.intro) with no fields to collect or validate — the
+ *   integrator reads it directly and renders it before ever touching this
+ *   module's step navigation.
+ * - Auto-advance (single radio/toggle field steps skipping the Continue
+ *   click): not built in here. It's a UI/interaction choice, not form logic —
+ *   the render layer calls next() itself after setAnswer() when it wants
+ *   that behavior, using visibleFields to detect the single-field case.
+ * - Discount code: folded in as ordinary state here (getDiscountCode-style
+ *   handling lives in @onabl/react's hook, not this module) rather than
+ *   modeled as a synthetic step the way apps/web's current buildSteps() does.
+ *   Where to render the discount input within the step flow (inline on the
+ *   last step, or as a separate screen before submit) is left to the
+ *   integrator — this module has no opinion on it.
+ */
+
+/** A step that currently has at least one visible field — steps a conditional field emptied out entirely are skipped. */
+interface VisibleStep extends FormStep {
+    fields: PublicFormField[];
+}
+/**
+ * Every step the visitor can currently navigate to, in order, filtered to
+ * only those with ≥1 visible field. Ungrouped fields (stepId: null) are
+ * collected into a synthetic trailing step, matching apps/web's current
+ * behavior — labeled "Details" there today; integrators using this directly
+ * can relabel as they see fit since this is just a FormStep-shaped value.
+ */
+declare function getVisibleSteps(form: PublicForm, answers: AnswerMap): VisibleStep[];
+/** Every field on the form, regardless of visibility — for debugging a field that won't appear. */
+declare function getAllFields(form: PublicForm): PublicFormField[];
+/**
+ * Seeds the initial AnswerMap from field defaults, using @onabl/engine's
+ * canonical applyDefaults — including its type-based fallback (unset number
+ * fields → 0, unset toggle → false). This is a deliberate choice for this
+ * new implementation, not a port of apps/web's current (leaner) local
+ * version — see docs/INTEGRATION-LAYER-TODO.md's Stage 3 pre-work note for
+ * why apps/web wasn't swapped onto this same behavior directly. Verify this
+ * during apps/web's own SDK migration (§14.5.5), since it is a real,
+ * intentional behavior difference from what's live today.
+ */
+declare function getInitialAnswers(form: PublicForm): AnswerMap;
+/**
+ * Validates one step's fields against the current answers. Same rules as
+ * apps/web's current validateStep(), generalized to a plain field list
+ * rather than coupled to a Step union type.
+ */
+declare function validateFields(fields: PublicFormField[], answers: AnswerMap): Record<string, string>;
+
+export { type CallOpts, type OnablClient, type OnablClientConfig, OnablError, OnablNetwork, OnablNotFound, OnablUnauthorized, OnablValidation, type TokenOpts, type VisibleStep, createOnablClient, getAllFields, getInitialAnswers, getVisibleSteps, validateFields };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import { PublicForm, ValidateCodeResponse, Quote, Invoice, PresignResponse, PublicFormField } from '@onabl/contracts/public-api';
+export { Invoice, PublicForm, PublicFormConfig, PublicFormField, Quote, ValidateCodeResponse } from '@onabl/contracts/public-api';
+import { AnswerMap, FormStep } from '@onabl/types/config';
+export { GroupedItems, PresentQuoteInput, QuotePresentation, QuoteRow, SeparateSection, groupLineItems, presentQuote } from '@onabl/engine/presentation';
+
+interface OnablClientConfig {
+    handle: string;
+    secretKey: string;
+    baseUrl?: string;
+    apiVersion?: string;
+    /** Path template for the quote view page on the integrator's own site — see submissions.create()'s returned quoteUrl. */
+    quotePath?: string;
+}
+interface CallOpts {
+    /** Slug of a specific form, for tenants running more than one. Omitted, resolves to the tenant's dashboard-configured default. */
+    slug?: string;
+}
+/**
+ * Customer-token-scoped calls need a bearer token — @onabl/next supplies one
+ * automatically from its managed cookie (SDK-DESIGN.md §3, "Access cookie").
+ * Used directly (e.g. a Vite/plain-React app per SDK-DESIGN.md §4, "Route
+ * handler only" decision), the caller supplies it explicitly.
+ */
+interface TokenOpts {
+    token: string;
+}
+interface OnablClient {
+    forms: {
+        get(opts?: CallOpts): Promise<PublicForm>;
+        validateDiscountCode(code: string, opts?: CallOpts): Promise<ValidateCodeResponse>;
+    };
+    quotes: {
+        get(uuid: string, opts: TokenOpts): Promise<Quote>;
+        accept(uuid: string, opts: TokenOpts): Promise<void>;
+        decline(uuid: string, reason: string, note: string | undefined, opts: TokenOpts): Promise<void>;
+    };
+    invoices: {
+        get(uuid: string, opts: TokenOpts): Promise<Invoice>;
+        /** milestone "deposit" saves the deposit POP; "balance"/"full" save the balance/full-payment POP. */
+        savePopUrl(uuid: string, key: string, milestone: "deposit" | "balance" | "full", opts: TokenOpts): Promise<void>;
+    };
+    storage: {
+        /** Presigns an upload for a customer-facing flow (currently only invoice POP uploads — pathPrefix is always "pop"). */
+        presignPop(resourceId: string, filename: string, contentType: string, fileSize: number, opts: TokenOpts): Promise<PresignResponse>;
+    };
+    submissions: {
+        /** isTenantSource marks a submission taken by the tenant on the customer's behalf (the on-site quote tool) rather than the customer directly — see docs/ROADMAP.md Phase 2.11. */
+        create(answers: AnswerMap, opts?: CallOpts & {
+            consentGiven?: boolean;
+            discountCode?: string;
+            isTenantSource?: boolean;
+        }): Promise<{
+            quoteId: string;
+            quoteUrl: string;
+            token: string;
+        }>;
+    };
+}
+declare function createOnablClient(config: OnablClientConfig): OnablClient;
+
+/**
+ * Typed error classes so a catch block can discriminate without matching on
+ * HTTP status numbers or string messages. See docs/SDK-DESIGN.md §3.
+ */
+declare class OnablError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/** 404, or a customer token that doesn't grant access to this resource. */
+declare class OnablNotFound extends OnablError {
+    constructor(message?: string);
+}
+/** Missing or invalid secret key / customer token. */
+declare class OnablUnauthorized extends OnablError {
+    constructor(message?: string);
+}
+/** 400 — carries field-level detail from the API's Zod validation errors. */
+declare class OnablValidation extends OnablError {
+    readonly fieldErrors?: Record<string, string[]> | undefined;
+    constructor(message: string, fieldErrors?: Record<string, string[]> | undefined);
+}
+/** Transport failure — network error, timeout, or an unparseable response. */
+declare class OnablNetwork extends OnablError {
+    constructor(message?: string, cause?: unknown);
+}
+
+/**
+ * The form state machine, extracted from apps/web/components/form/MultiStepForm.tsx
+ * (§14.5.2, part 2). Pure functions only — no React, no framework of any kind —
+ * so any UI layer (a React hook in @onabl/react, or something else entirely)
+ * can drive the same tested logic. Renders nothing; every function here takes
+ * a snapshot of state and returns a value, never mutates.
+ *
+ * Deliberately excludes three things apps/web's current implementation
+ * handles that the documented useOnablForm surface (docs/SDK-DESIGN.md §3)
+ * does not — decided 2026-08-24, see docs/INTEGRATION-LAYER-TODO.md:
+ *
+ * - Intro screen: not modeled as a step here at all. It's pure presentation
+ *   (config.meta.intro) with no fields to collect or validate — the
+ *   integrator reads it directly and renders it before ever touching this
+ *   module's step navigation.
+ * - Auto-advance (single radio/toggle field steps skipping the Continue
+ *   click): not built in here. It's a UI/interaction choice, not form logic —
+ *   the render layer calls next() itself after setAnswer() when it wants
+ *   that behavior, using visibleFields to detect the single-field case.
+ * - Discount code: folded in as ordinary state here (getDiscountCode-style
+ *   handling lives in @onabl/react's hook, not this module) rather than
+ *   modeled as a synthetic step the way apps/web's current buildSteps() does.
+ *   Where to render the discount input within the step flow (inline on the
+ *   last step, or as a separate screen before submit) is left to the
+ *   integrator — this module has no opinion on it.
+ */
+
+/** A step that currently has at least one visible field — steps a conditional field emptied out entirely are skipped. */
+interface VisibleStep extends FormStep {
+    fields: PublicFormField[];
+}
+/**
+ * Every step the visitor can currently navigate to, in order, filtered to
+ * only those with ≥1 visible field. Ungrouped fields (stepId: null) are
+ * collected into a synthetic trailing step, matching apps/web's current
+ * behavior — labeled "Details" there today; integrators using this directly
+ * can relabel as they see fit since this is just a FormStep-shaped value.
+ */
+declare function getVisibleSteps(form: PublicForm, answers: AnswerMap): VisibleStep[];
+/** Every field on the form, regardless of visibility — for debugging a field that won't appear. */
+declare function getAllFields(form: PublicForm): PublicFormField[];
+/**
+ * Seeds the initial AnswerMap from field defaults, using @onabl/engine's
+ * canonical applyDefaults — including its type-based fallback (unset number
+ * fields → 0, unset toggle → false). This is a deliberate choice for this
+ * new implementation, not a port of apps/web's current (leaner) local
+ * version — see docs/INTEGRATION-LAYER-TODO.md's Stage 3 pre-work note for
+ * why apps/web wasn't swapped onto this same behavior directly. Verify this
+ * during apps/web's own SDK migration (§14.5.5), since it is a real,
+ * intentional behavior difference from what's live today.
+ */
+declare function getInitialAnswers(form: PublicForm): AnswerMap;
+/**
+ * Validates one step's fields against the current answers. Same rules as
+ * apps/web's current validateStep(), generalized to a plain field list
+ * rather than coupled to a Step union type.
+ */
+declare function validateFields(fields: PublicFormField[], answers: AnswerMap): Record<string, string>;
+
+export { type CallOpts, type OnablClient, type OnablClientConfig, OnablError, OnablNetwork, OnablNotFound, OnablUnauthorized, OnablValidation, type TokenOpts, type VisibleStep, createOnablClient, getAllFields, getInitialAnswers, getVisibleSteps, validateFields };