@lotics/app-sdk 0.5.0 → 0.7.0

package/dist/src/hooks.d.ts

@@ -56,4 +56,37 @@ type UseQueryParams<K extends keyof AppQueries & string> = AppQueries[K] extends
  */
 export declare function useQuery<K extends keyof AppQueries & string>(alias: K, ...rest: UseQueryParams<K>): QueryState<Record<string, unknown>>;
 export declare function useQuery(alias: string, params?: Record<string, unknown>): QueryState<Record<string, unknown>>;
+/** A file the host has stored and resolved serving URLs for. */
+export interface UploadedFile {
+    id: string;
+    filename: string;
+    mime_type: string;
+    url?: string;
+    thumbnail_url?: string;
+}
+interface FileUploadState {
+    /**
+     * Upload one file. Resolves to the stored file; pass `UploadedFile.id` into
+     * a `useWorkflow` call to attach it to a record. Rejects on failure — the
+     * file is never partially stored.
+     */
+    upload: (file: File) => Promise<UploadedFile>;
+    /** True while any upload from this hook is in flight. */
+    uploading: boolean;
+    /** Message of the most recent failed upload, cleared when a new one starts. */
+    error: string | null;
+}
+/**
+ * Upload files from an app. The bytes are stored via a presigned
+ * direct-to-storage upload the host mediates; the API server never proxies
+ * them. Works the same in a public (anonymous) app and a member-facing one.
+ *
+ * ```tsx
+ * const { upload, uploading } = useFileUpload();
+ * const submit = useWorkflow("submitApplication");
+ * const cccd = await upload(file);
+ * await submit({ ...fields, cccd_file_id: cccd.id });
+ * ```
+ */
+export declare function useFileUpload(): FileUploadState;
 export {};

package/dist/src/hooks.js

@@ -1,10 +1,12 @@
 /**
  * Typed React hooks for Lotics app data access.
  *
- * The SDK surface is two hooks: `useQuery` for reads, `useWorkflow` for every
- * mutation. App code never writes records directly — all writes flow through
- * declared workflows, which gives the app owner a typed, audited chokepoint
- * and means a publicly-shared app exposes no anonymous direct-write path.
+ * The SDK surface is three hooks: `useQuery` for reads, `useWorkflow` for
+ * every mutation, and `useFileUpload` for attaching files. App code never
+ * writes records directly — all writes flow through declared workflows, which
+ * gives the app owner a typed, audited chokepoint and means a publicly-shared
+ * app exposes no anonymous direct-write path. An uploaded file is inert until
+ * a workflow attaches it, so file upload keeps that same property.
  *
  * Every hook is a thin wrapper over the postMessage RPC bridge — the parent
  * does the actual API calls, results stream back through `rpc()`. Hooks manage
@@ -53,3 +55,35 @@ export function useQuery(alias, params) {
     }, []);
     return { ...state, refetch };
 }
+/**
+ * Upload files from an app. The bytes are stored via a presigned
+ * direct-to-storage upload the host mediates; the API server never proxies
+ * them. Works the same in a public (anonymous) app and a member-facing one.
+ *
+ * ```tsx
+ * const { upload, uploading } = useFileUpload();
+ * const submit = useWorkflow("submitApplication");
+ * const cccd = await upload(file);
+ * await submit({ ...fields, cccd_file_id: cccd.id });
+ * ```
+ */
+export function useFileUpload() {
+    const [inFlight, setInFlight] = useState(0);
+    const [error, setError] = useState(null);
+    const upload = useCallback(async (file) => {
+        setInFlight((n) => n + 1);
+        setError(null);
+        try {
+            return await rpc("upload", { file });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Upload failed";
+            setError(message);
+            throw err;
+        }
+        finally {
+            setInFlight((n) => n - 1);
+        }
+    }, []);
+    return { upload, uploading: inFlight > 0, error };
+}

package/dist/src/index.d.ts

@@ -10,7 +10,8 @@
  * depending on packages/ui's React Native Web setup.
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery } from "./hooks.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 { AppWorkflows, AppQueries } from "./types.js";

package/dist/src/index.js

@@ -10,5 +10,5 @@
  * depending on packages/ui's React Native Web setup.
  */
 export { mount } from "./mount.js";
-export { useWorkflow, useQuery } from "./hooks.js";
+export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
 export { rpc } from "./rpc.js";

package/dist/src/rpc.d.ts

@@ -1,17 +1,22 @@
 /**
- * postMessage RPC bridge to the parent Lotics frontend.
+ * RPC bridge for a custom-code app's data operations.
  *
- * The iframe runs `sandbox="allow-scripts"` with a unique (null) origin, so
- * direct fetch with credentials isn't possible. Every data operation flows
- * through the parent: the iframe posts an op + payload, the parent makes
- * the authenticated API call and posts the result back.
+ * An app reaches the Lotics API one of two ways, chosen automatically:
  *
- * Wire protocol (must match `frontend/features/app_ui/app_iframe_host.tsx`):
- *   iframe → parent: { id: number, op: string, payload: unknown }
- *   parent → iframe: { id: number, type: "result", data } | { id, type: "error", message }
+ *  - **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.
  *
- * Bumping protocol version requires a coordinated change in the parent.
- * Add new ops alongside existing ones; never repurpose them.
+ *  - **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 }
  */
-export type RpcOp = "query" | "workflow";
+export type RpcOp = "query" | "workflow" | "upload";
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;

package/dist/src/rpc.js

@@ -1,18 +1,30 @@
 /**
- * postMessage RPC bridge to the parent Lotics frontend.
+ * RPC bridge for a custom-code app's data operations.
  *
- * The iframe runs `sandbox="allow-scripts"` with a unique (null) origin, so
- * direct fetch with credentials isn't possible. Every data operation flows
- * through the parent: the iframe posts an op + payload, the parent makes
- * the authenticated API call and posts the result back.
+ * An app reaches the Lotics API one of two ways, chosen automatically:
  *
- * Wire protocol (must match `frontend/features/app_ui/app_iframe_host.tsx`):
- *   iframe → parent: { id: number, op: string, payload: unknown }
- *   parent → iframe: { id: number, type: "result", data } | { id, type: "error", message }
+ *  - **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.
  *
- * Bumping protocol version requires a coordinated change in the parent.
- * Add new ops alongside existing ones; never repurpose them.
+ *  - **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 }
  */
+/** 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) {
+    return hostOrigin
+        ? rpcBridged(op, payload, hostOrigin)
+        : rpcStandalone(op, payload);
+}
 const pending = new Map();
 let nextRpcId = 0;
 let listenerInstalled = false;
@@ -21,10 +33,8 @@ function ensureListener() {
         return;
     listenerInstalled = true;
     window.addEventListener("message", (event) => {
-        // Trust only messages from the parent window. The iframe's origin is null
-        // (sandboxed), so we can't compare origins meaningfully — we trust the
-        // window reference instead.
-        if (event.source !== window.parent)
+        // Accept only messages from the parent window, at the host origin.
+        if (event.source !== window.parent || event.origin !== hostOrigin)
             return;
         const msg = event.data;
         if (!msg || typeof msg.id !== "number")
@@ -41,11 +51,98 @@ function ensureListener() {
         }
     });
 }
-export function rpc(op, payload) {
+function rpcBridged(op, payload, host) {
     ensureListener();
     return new Promise((resolve, reject) => {
         const id = nextRpcId++;
         pending.set(id, { resolve: resolve, reject });
-        window.parent.postMessage({ id, op, payload }, "*");
+        window.parent.postMessage({ id, op, payload }, host);
+    });
+}
+// ── Standalone transport ────────────────────────────────────────────────────
+// 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;
+    }
+    return appIdPromise;
+}
+async function apiCall(method, path, body) {
+    const res = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: body ? { "content-type": "application/json" } : undefined,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        let message = text;
+        try {
+            message = JSON.parse(text).message ?? text;
+        }
+        catch {
+            // response body is not JSON — use it verbatim
+        }
+        throw new Error(message || `HTTP ${res.status}`);
+    }
+    return text ? JSON.parse(text) : {};
+}
+function rpcStandalone(op, payload) {
+    switch (op) {
+        case "query":
+            return standaloneQuery(payload);
+        case "workflow":
+            return standaloneWorkflow(payload);
+        case "upload":
+            return standaloneUpload(payload.file);
+    }
+}
+async function standaloneQuery(p) {
+    const appId = await resolveAppId();
+    const r = (await apiCall("POST", `/v1/apps/${appId}/query`, {
+        alias: p.alias,
+        params: p.params,
+    }));
+    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 });
+}
+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`, {
+        filename: file.name,
+        mime_type: file.type,
+        file_size: file.size,
+    }));
+    const put = await fetch(init.upload_url, {
+        method: "PUT",
+        body: file,
+        headers: { "Content-Type": file.type },
     });
+    if (!put.ok) {
+        throw new Error(`Storage upload failed (${put.status})`);
+    }
+    const done = (await apiCall("POST", `/v1/apps/${appId}/files/complete`, {
+        file_id: init.file_id,
+        file_storage_key: init.file_storage_key,
+        filename: file.name,
+    }));
+    return done.file;
 }

package/package.json

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