@lotics/app-sdk 0.7.0 → 0.8.0

package/dist/src/hooks.js

@@ -15,6 +15,7 @@
  */
 import { useCallback, useEffect, useState } from "react";
 import { rpc } from "./rpc.js";
+import { getMockRows } from "./mock.js";
 export function useWorkflow(alias) {
     return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
 }
@@ -26,12 +27,25 @@ export function useQuery(alias, params) {
     // refetch callback mutates only this counter; state transitions still
     // happen inside the effect so loading / error / rows flow consistently.
     const [refetchToken, setRefetchToken] = useState(0);
-    const [state, setState] = useState({
-        rows: [],
-        loading: true,
-        error: null,
+    // Initialize from the fixture when mock mode is on and the app registered
+    // rows for this alias — avoids a flash of `loading: true` on first paint.
+    // Computed lazily so subsequent renders don't re-read `window.location`.
+    const [state, setState] = useState(() => {
+        const mockRows = getMockRows(alias);
+        if (mockRows)
+            return { rows: mockRows, loading: false, error: null };
+        return { rows: [], loading: true, error: null };
     });
     useEffect(() => {
+        // Re-check on every effect run so HMR updates to the fixture (mount-time
+        // re-registration) propagate without a hard reload. When the fixture has
+        // an entry we short-circuit the RPC — partial mocking still works because
+        // aliases without fixture entries fall through to the live path below.
+        const mockRows = getMockRows(alias);
+        if (mockRows) {
+            setState({ rows: mockRows, loading: false, error: null });
+            return;
+        }
         let cancelled = false;
         setState((s) => ({ rows: s.rows, loading: true, error: null }));
         rpc("query", { alias, params: params ?? {} })

package/dist/src/index.d.ts

@@ -10,8 +10,10 @@
  * depending on packages/ui's React Native Web setup.
  */
 export { mount } from "./mount.js";
+export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
 export type { UploadedFile } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
+export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";

package/dist/src/mock.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Demo / design-time fixture support for `useQuery`.
+ *
+ * Activation contract:
+ *
+ *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
+ *      is a `{ queries: { alias: Row[] } }` map keyed by the same aliases the
+ *      app declared in `package.json#lotics.queries`.
+ *   2. At runtime, the user (or a screenshot script) loads the app with the
+ *      `?__mock=1` URL search param. Without that param the SDK ignores the
+ *      fixture entirely and `useQuery` flows through the RPC bridge as usual.
+ *
+ * The two-step gate keeps demo data shipping in the bundle from leaking into
+ * normal traffic — the param namespace (`__mock` prefix) is reserved and
+ * unlikely to collide with app-side query state. Apps that don't pass a
+ * fixture pay nothing: `getMockRows` returns `null` for every alias and the
+ * hook path is unchanged.
+ *
+ * What's deliberately *not* mocked yet:
+ *   - `useWorkflow` — mutations have side effects (notifications, audit
+ *     trail). A workflow mock would have to also produce realistic followup
+ *     state, which is more design than this iteration warrants.
+ *   - `useFileUpload` — same reason.
+ *
+ * If those become needed, extend `AppFixture` with `workflows`/`uploads` and
+ * route from each hook.
+ */
+export interface AppFixture {
+    /** Map of query alias → rows the hook should return when mock mode is on. */
+    queries?: Record<string, Array<Record<string, unknown>>>;
+}
+/**
+ * Called by `mount({ fixture })`. Module-level state because the SDK has no
+ * React context boundary around the iframe — every hook resolves against the
+ * same registration. Calling twice replaces (last-write-wins) which is fine
+ * for HMR.
+ */
+export declare function registerMockFixture(fixture: AppFixture | undefined): void;
+/**
+ * Returns the fixture rows for an alias when mock mode is active *and* the
+ * fixture has an entry for that alias. Otherwise null — the hook falls
+ * through to the real RPC path. The distinction matters: an app may mock
+ * only some queries and let the rest flow through to real data.
+ */
+export declare function getMockRows(alias: string): Array<Record<string, unknown>> | null;

package/dist/src/mock.js

@@ -0,0 +1,65 @@
+/**
+ * Demo / design-time fixture support for `useQuery`.
+ *
+ * Activation contract:
+ *
+ *   1. App passes `{ fixture }` to `mount(<App />, { fixture })`. The fixture
+ *      is a `{ queries: { alias: Row[] } }` map keyed by the same aliases the
+ *      app declared in `package.json#lotics.queries`.
+ *   2. At runtime, the user (or a screenshot script) loads the app with the
+ *      `?__mock=1` URL search param. Without that param the SDK ignores the
+ *      fixture entirely and `useQuery` flows through the RPC bridge as usual.
+ *
+ * The two-step gate keeps demo data shipping in the bundle from leaking into
+ * normal traffic — the param namespace (`__mock` prefix) is reserved and
+ * unlikely to collide with app-side query state. Apps that don't pass a
+ * fixture pay nothing: `getMockRows` returns `null` for every alias and the
+ * hook path is unchanged.
+ *
+ * What's deliberately *not* mocked yet:
+ *   - `useWorkflow` — mutations have side effects (notifications, audit
+ *     trail). A workflow mock would have to also produce realistic followup
+ *     state, which is more design than this iteration warrants.
+ *   - `useFileUpload` — same reason.
+ *
+ * If those become needed, extend `AppFixture` with `workflows`/`uploads` and
+ * route from each hook.
+ */
+let registeredFixture;
+/**
+ * Called by `mount({ fixture })`. Module-level state because the SDK has no
+ * React context boundary around the iframe — every hook resolves against the
+ * same registration. Calling twice replaces (last-write-wins) which is fine
+ * for HMR.
+ */
+export function registerMockFixture(fixture) {
+    registeredFixture = fixture;
+}
+/**
+ * True iff the iframe URL carries the `__mock=1` activation flag AND a
+ * fixture was registered. Safe to call before mount — returns false when no
+ * fixture exists. Throws never; a malformed URL or missing `window` (SSR /
+ * jsdom without location) silently returns false.
+ */
+function isMockMode() {
+    if (!registeredFixture)
+        return false;
+    try {
+        return new URLSearchParams(window.location.search).get("__mock") === "1";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Returns the fixture rows for an alias when mock mode is active *and* the
+ * fixture has an entry for that alias. Otherwise null — the hook falls
+ * through to the real RPC path. The distinction matters: an app may mock
+ * only some queries and let the rest flow through to real data.
+ */
+export function getMockRows(alias) {
+    if (!isMockMode())
+        return null;
+    const rows = registeredFixture?.queries?.[alias];
+    return rows ?? null;
+}

package/dist/src/mount.d.ts

@@ -10,9 +10,23 @@
  * mount(<App />);
  * ```
  *
+ * Optional second argument registers a demo/design-time fixture. When the
+ * iframe is loaded with `?__mock=1`, `useQuery` returns rows from the
+ * fixture instead of hitting the RPC bridge. Without the URL flag the
+ * fixture is inert — useful for taking screenshots or iterating on
+ * dashboard layouts before real data exists.
+ *
+ * ```tsx
+ * mount(<App />, {
+ *   fixture: {
+ *     queries: { customers: MOCK_CUSTOMERS, deals: MOCK_DEALS },
+ *   },
+ * });
+ * ```
+ *
  * `mount` wires up React 19's createRoot against `#root` in the iframe shell,
  * sets up window.onerror/unhandledrejection forwarding so runtime crashes
- * surface in the parent's debug pane (PR 2 of the debug-loop phase), and
+ * surface in the parent's debug pane, registers the fixture (if any), and
  * renders the user's tree.
  *
  * If the bundler doesn't ship #root in the user's `index.html`, we create it
@@ -20,4 +34,14 @@
  * mount resilient.
  */
 import type { ReactNode } from "react";
-export declare function mount(element: ReactNode): void;
+import { type AppFixture } from "./mock.js";
+export interface MountOptions {
+    /**
+     * Optional demo fixture. When the iframe URL contains `?__mock=1`,
+     * `useQuery(alias)` returns `fixture.queries[alias]` instead of calling
+     * the RPC bridge. Aliases not present in the fixture still flow through
+     * the real path — partial mocking is supported.
+     */
+    fixture?: AppFixture;
+}
+export declare function mount(element: ReactNode, options?: MountOptions): void;

package/dist/src/mount.js

@@ -1,5 +1,7 @@
 import { createRoot } from "react-dom/client";
-export function mount(element) {
+import { registerMockFixture } from "./mock.js";
+export function mount(element, options = {}) {
+    registerMockFixture(options.fixture);
     let container = document.getElementById("root");
     if (!container) {
         container = document.createElement("div");

package/dist/src/password_gate.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Vanilla DOM password overlay for password-protected public apps.
+ *
+ * The SDK can't assume the host app's React tree has mounted yet (this fires
+ * before any data call resolves), so the overlay is built with plain DOM
+ * APIs and self-contained inline styles. It rejects the boot promise only
+ * on `cancel()` — which is currently never wired to a button; the visitor
+ * either enters the correct password or leaves the page.
+ *
+ * One overlay at a time. Concurrent calls reuse the in-flight promise so a
+ * burst of failing API calls produces a single modal, not several stacked.
+ */
+interface OverlayController {
+    showError(message: string): void;
+    setSubmitting(submitting: boolean): void;
+}
+export interface PasswordPromptArgs {
+    /**
+     * Validates the entered password. Resolve to keep the overlay open on a
+     * wrong password (the SDK calls `controller.showError(...)` afterwards),
+     * or `accept()` to dismiss the overlay and resolve the prompt with the
+     * password the visitor typed.
+     */
+    authenticate: (password: string, controller: OverlayController) => Promise<{
+        ok: boolean;
+    }>;
+}
+export declare function promptForPassword(args: PasswordPromptArgs): Promise<string>;
+export {};

package/dist/src/password_gate.js

@@ -0,0 +1,142 @@
+/**
+ * Vanilla DOM password overlay for password-protected public apps.
+ *
+ * The SDK can't assume the host app's React tree has mounted yet (this fires
+ * before any data call resolves), so the overlay is built with plain DOM
+ * APIs and self-contained inline styles. It rejects the boot promise only
+ * on `cancel()` — which is currently never wired to a button; the visitor
+ * either enters the correct password or leaves the page.
+ *
+ * One overlay at a time. Concurrent calls reuse the in-flight promise so a
+ * burst of failing API calls produces a single modal, not several stacked.
+ */
+let activePrompt = null;
+export function promptForPassword(args) {
+    if (activePrompt)
+        return activePrompt;
+    activePrompt = new Promise((resolve) => {
+        const root = document.createElement("div");
+        root.dataset.loticsAppPasswordGate = "true";
+        root.style.cssText = [
+            "position:fixed",
+            "inset:0",
+            "z-index:2147483647",
+            "background:rgba(15,23,42,0.55)",
+            "backdrop-filter:blur(8px)",
+            "-webkit-backdrop-filter:blur(8px)",
+            "display:flex",
+            "align-items:center",
+            "justify-content:center",
+            "padding:24px",
+            "font:14px/1.5 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Inter,sans-serif",
+            "color:#0f172a",
+        ].join(";");
+        const card = document.createElement("form");
+        card.setAttribute("role", "dialog");
+        card.setAttribute("aria-modal", "true");
+        card.setAttribute("aria-labelledby", "lotics-app-password-title");
+        card.style.cssText = [
+            "background:#fff",
+            "border-radius:14px",
+            "padding:28px",
+            "max-width:380px",
+            "width:100%",
+            "box-shadow:0 25px 50px -12px rgba(0,0,0,0.25)",
+            "display:flex",
+            "flex-direction:column",
+            "gap:16px",
+        ].join(";");
+        const title = document.createElement("h2");
+        title.id = "lotics-app-password-title";
+        title.textContent = "Password required";
+        title.style.cssText = "margin:0;font-size:18px;font-weight:600;letter-spacing:-0.01em;";
+        const subtitle = document.createElement("p");
+        subtitle.textContent = "Enter the password to access this app.";
+        subtitle.style.cssText = "margin:0;color:#475569;font-size:13.5px;";
+        const input = document.createElement("input");
+        input.type = "password";
+        input.autocomplete = "current-password";
+        input.required = true;
+        input.placeholder = "Password";
+        input.setAttribute("aria-label", "Password");
+        input.style.cssText = [
+            "width:100%",
+            "box-sizing:border-box",
+            "padding:10px 12px",
+            "border:1px solid #cbd5e1",
+            "border-radius:8px",
+            "font-size:14px",
+            "outline:none",
+            "transition:border-color 0.15s,box-shadow 0.15s",
+        ].join(";");
+        input.addEventListener("focus", () => {
+            input.style.borderColor = "#2563eb";
+            input.style.boxShadow = "0 0 0 3px rgba(37,99,235,0.18)";
+        });
+        input.addEventListener("blur", () => {
+            input.style.borderColor = "#cbd5e1";
+            input.style.boxShadow = "none";
+        });
+        const error = document.createElement("div");
+        error.setAttribute("role", "alert");
+        error.style.cssText = "color:#dc2626;font-size:13px;min-height:18px;";
+        const submit = document.createElement("button");
+        submit.type = "submit";
+        submit.textContent = "Continue";
+        submit.style.cssText = [
+            "padding:10px 12px",
+            "background:#0f172a",
+            "color:#fff",
+            "border:none",
+            "border-radius:8px",
+            "font-size:14px",
+            "font-weight:500",
+            "cursor:pointer",
+            "transition:background 0.15s,opacity 0.15s",
+        ].join(";");
+        const setSubmitting = (s) => {
+            submit.disabled = s;
+            input.disabled = s;
+            submit.textContent = s ? "Checking…" : "Continue";
+            submit.style.opacity = s ? "0.7" : "1";
+            submit.style.cursor = s ? "wait" : "pointer";
+        };
+        const showError = (message) => {
+            error.textContent = message;
+        };
+        card.append(title, subtitle, input, error, submit);
+        root.append(card);
+        document.body.append(root);
+        // Defer focus until the element is in layout — some browsers ignore focus
+        // on freshly-attached inputs without a microtask break.
+        queueMicrotask(() => input.focus());
+        card.addEventListener("submit", (e) => {
+            e.preventDefault();
+            const value = input.value;
+            if (!value) {
+                showError("Enter a password.");
+                return;
+            }
+            showError("");
+            setSubmitting(true);
+            args
+                .authenticate(value, { showError, setSubmitting })
+                .then((res) => {
+                if (res.ok) {
+                    root.remove();
+                    activePrompt = null;
+                    resolve(value);
+                }
+                else {
+                    setSubmitting(false);
+                    input.select();
+                }
+            })
+                .catch((err) => {
+                setSubmitting(false);
+                showError(err instanceof Error ? err.message : "Something went wrong.");
+            });
+        });
+    });
+    return activePrompt;
+}

package/dist/src/rpc.js

@@ -1,23 +1,4 @@
-/**
- * RPC bridge for a custom-code app's data operations.
- *
- * An app reaches the Lotics API one of two ways, chosen automatically:
- *
- *  - **Bridged** — the app is embedded by a Lotics host (the authenticated
- *    product, or `lotics app dev`), which passes its origin via the
- *    `?lotics_host=` query param. The host holds the session; the app posts
- *    ops over postMessage and the host makes the API call. Used by internal
- *    apps — the member's credentials must never reach the app.
- *
- *  - **Standalone** — the app is served on its own at `<slug>.lotics.app`
- *    with no host. It calls the public `/v1/apps/{id}/*` endpoints directly;
- *    those are anonymous-accessible for a publicly-shared app. The app holds
- *    no credentials, so there is nothing to protect.
- *
- * Wire protocol (bridged — must match `app_iframe_host.tsx`):
- *   app  → host: { id, op, payload }
- *   host → app:  { id, type: "result", data } | { id, type: "error", message }
- */
+import { promptForPassword } from "./password_gate.js";
 /** The embedding Lotics host's origin — present iff the app is bridged. */
 const hostOrigin = new URLSearchParams(window.location.search).get("lotics_host");
 export function rpc(op, payload) {
@@ -63,41 +44,134 @@ function rpcBridged(op, payload, host) {
 // Standalone apps run only at `<slug>.lotics.app` (production); dev apps are
 // always bridged by the `lotics app dev` wrapper.
 const API_BASE = "https://api.lotics.ai";
-/** Resolved once — the app_id this standalone app's data calls are keyed by. */
-let appIdPromise = null;
-function resolveAppId() {
-    if (!appIdPromise) {
-        const slug = window.location.hostname.split(".")[0];
-        const attempt = apiCall("GET", `/v1/apps/by-subdomain/${encodeURIComponent(slug)}`).then((r) => r.app_id);
-        // Don't cache a rejection — a transient failure on first load would
-        // otherwise brick every later data call for the session. Clear the slot
-        // so the next call retries.
-        attempt.catch(() => {
-            if (appIdPromise === attempt)
-                appIdPromise = null;
-        });
-        appIdPromise = attempt;
+const PASSWORD_REQUIRED_CODE = "PASSWORD_REQUIRED";
+/**
+ * Boot-time resolution result. Promise is shared so concurrent first calls
+ * (e.g. two `useQuery` hooks rendering simultaneously) coalesce into one
+ * `/by-subdomain` fetch and at most one password prompt.
+ */
+let bootPromise = null;
+let sessionToken = null;
+function sessionStorageKey(appId) {
+    return `lotics_app_session:${appId}`;
+}
+function readStoredSession(appId) {
+    try {
+        const raw = window.localStorage.getItem(sessionStorageKey(appId));
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (!parsed.token || !parsed.expires_at)
+            return null;
+        if (Date.parse(parsed.expires_at) <= Date.now()) {
+            window.localStorage.removeItem(sessionStorageKey(appId));
+            return null;
+        }
+        return parsed.token;
+    }
+    catch {
+        return null;
+    }
+}
+function writeStoredSession(appId, token, expiresAt) {
+    try {
+        window.localStorage.setItem(sessionStorageKey(appId), JSON.stringify({ token, expires_at: expiresAt }));
+    }
+    catch {
+        // localStorage unavailable (Safari private mode, quota): the token still
+        // lives in memory for this page lifetime — that's good enough for a single
+        // session, the next reload simply re-prompts.
     }
-    return appIdPromise;
 }
-async function apiCall(method, path, body) {
+function clearStoredSession(appId) {
+    try {
+        window.localStorage.removeItem(sessionStorageKey(appId));
+    }
+    catch {
+        // ignore
+    }
+}
+async function boot() {
+    if (bootPromise)
+        return bootPromise;
+    const slug = window.location.hostname.split(".")[0];
+    const attempt = (async () => {
+        const info = (await apiCall("GET", `/v1/apps/by-subdomain/${encodeURIComponent(slug)}`));
+        if (info.requires_password) {
+            const stored = readStoredSession(info.app_id);
+            if (stored) {
+                sessionToken = stored;
+            }
+            else {
+                await acquireSessionToken(info.app_id);
+            }
+        }
+        return info;
+    })();
+    // Don't cache a rejection — a transient failure on first load would brick
+    // every later data call. Clear the slot so the next call retries.
+    attempt.catch(() => {
+        if (bootPromise === attempt)
+            bootPromise = null;
+    });
+    bootPromise = attempt;
+    return attempt;
+}
+async function acquireSessionToken(appId) {
+    await promptForPassword({
+        authenticate: async (password, controller) => {
+            try {
+                const res = (await apiCall("POST", `/v1/apps/${appId}/public/authenticate`, { password }, { skipAuth: true }));
+                sessionToken = res.session_token;
+                writeStoredSession(appId, res.session_token, res.expires_at);
+                return { ok: true };
+            }
+            catch (err) {
+                const message = err instanceof Error && err.message ? err.message : "Incorrect password.";
+                controller.showError(message);
+                return { ok: false };
+            }
+        },
+    });
+}
+async function apiCall(method, path, body, opts) {
+    const headers = {};
+    if (body)
+        headers["content-type"] = "application/json";
+    if (sessionToken && !opts?.skipAuth) {
+        headers["authorization"] = `Bearer ${sessionToken}`;
+    }
     const res = await fetch(`${API_BASE}${path}`, {
         method,
-        headers: body ? { "content-type": "application/json" } : undefined,
+        headers,
         body: body ? JSON.stringify(body) : undefined,
     });
     const text = await res.text();
-    if (!res.ok) {
-        let message = text;
+    let parsed = null;
+    if (text) {
         try {
-            message = JSON.parse(text).message ?? text;
+            parsed = JSON.parse(text);
         }
         catch {
-            // response body is not JSON — use it verbatim
+            // not JSON — body left as raw text
+        }
+    }
+    if (!res.ok) {
+        const errorBody = parsed;
+        // Password gate (re-)prompt: the stored token went stale because the owner
+        // rotated or cleared the password, or it was never present. Drop the
+        // current token, ask the visitor again, and retry the original call once.
+        if (res.status === 401 && errorBody?.error_code === PASSWORD_REQUIRED_CODE && !opts?.skipAuth) {
+            const appId = opts?.appId ?? (await boot()).app_id;
+            sessionToken = null;
+            clearStoredSession(appId);
+            await acquireSessionToken(appId);
+            return apiCall(method, path, body, { ...opts, appId });
         }
+        const message = errorBody?.message ?? text;
         throw new Error(message || `HTTP ${res.status}`);
     }
-    return text ? JSON.parse(text) : {};
+    return parsed ?? (text ? text : {});
 }
 function rpcStandalone(op, payload) {
     switch (op) {
@@ -110,27 +184,24 @@ function rpcStandalone(op, payload) {
     }
 }
 async function standaloneQuery(p) {
-    const appId = await resolveAppId();
-    const r = (await apiCall("POST", `/v1/apps/${appId}/query`, {
-        alias: p.alias,
-        params: p.params,
-    }));
+    const { app_id } = await boot();
+    const r = (await apiCall("POST", `/v1/apps/${app_id}/query`, { alias: p.alias, params: p.params }, { appId: app_id }));
     return { rows: r.rows ?? [] };
 }
 async function standaloneWorkflow(p) {
-    const appId = await resolveAppId();
-    return apiCall("POST", `/v1/apps/${appId}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs });
+    const { app_id } = await boot();
+    return apiCall("POST", `/v1/apps/${app_id}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs }, { appId: app_id });
 }
 async function standaloneUpload(file) {
     if (!(file instanceof File)) {
         throw new Error("upload payload must include a File");
     }
-    const appId = await resolveAppId();
-    const init = (await apiCall("POST", `/v1/apps/${appId}/files/upload-url`, {
+    const { app_id } = await boot();
+    const init = (await apiCall("POST", `/v1/apps/${app_id}/files/upload-url`, {
         filename: file.name,
         mime_type: file.type,
         file_size: file.size,
-    }));
+    }, { appId: app_id }));
     const put = await fetch(init.upload_url, {
         method: "PUT",
         body: file,
@@ -139,10 +210,10 @@ async function standaloneUpload(file) {
     if (!put.ok) {
         throw new Error(`Storage upload failed (${put.status})`);
     }
-    const done = (await apiCall("POST", `/v1/apps/${appId}/files/complete`, {
+    const done = (await apiCall("POST", `/v1/apps/${app_id}/files/complete`, {
         file_id: init.file_id,
         file_storage_key: init.file_storage_key,
         filename: file.name,
-    }));
+    }, { appId: app_id }));
     return done.file;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {