@lotics/app-sdk 0.1.0

package/dist/src/hooks.d.ts

@@ -0,0 +1,39 @@
+import type { QueryAst, TableRow, WorkspaceTables } from "./types.js";
+interface QueryState<R> {
+    rows: R[];
+    loading: boolean;
+    error: string | null;
+}
+/**
+ * Read all rows from a table. Re-fetches when the table id changes.
+ * For derived/joined data, see `useQuery(ast)`.
+ */
+export declare function useTable<K extends keyof WorkspaceTables & string>(table_id: K): QueryState<TableRow<K>>;
+export declare function useTable(table_id: string): QueryState<TableRow<string>>;
+/**
+ * Mutation surface for a table. Returns imperative functions; doesn't manage
+ * cache invalidation in v1 — components that read via useTable will pick up
+ * changes on next remount or via realtime channels in v2.
+ */
+export declare function useMutate<K extends keyof WorkspaceTables & string>(table_id: K): {
+    update: (records: Array<{
+        id: string;
+        data: Partial<RowFor<K>>;
+    }>) => Promise<unknown>;
+};
+export declare function useMutate(table_id: string): {
+    update: (records: Array<{
+        id: string;
+        data: Record<string, unknown>;
+    }>) => Promise<unknown>;
+};
+type RowFor<K extends keyof WorkspaceTables & string> = WorkspaceTables[K];
+/** Trigger a workflow by action_id. Returns a callable that runs it. */
+export declare function useAction(action_id: string): (inputs?: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Escape hatch — pass a raw query AST. Same shape the server validates via
+ * `parseQueryNode`. Use for joins, group-by, projections, and other shapes
+ * `useTable`/`useRecord` don't express.
+ */
+export declare function useQuery(ast: QueryAst): QueryState<Record<string, unknown>>;
+export {};

package/dist/src/hooks.js

@@ -0,0 +1,93 @@
+/**
+ * Typed React hooks for Lotics app data access.
+ *
+ * Every hook is a thin wrapper over the postMessage RPC bridge — the parent
+ * does the actual API calls with the user's session, results stream back
+ * through `rpc()`. Hooks manage their own local cache via `useState`; we
+ * intentionally don't ship a global store in v1.
+ *
+ * For users with the workspace-types augmentation in tsconfig, table IDs
+ * passed to these hooks are typed against the actual schemas. Without it,
+ * IDs are plain strings and rows are `Record<string, unknown>` — code still
+ * runs, just untyped.
+ */
+import { useCallback, useEffect, useState } from "react";
+import { rpc } from "./rpc.js";
+export function useTable(table_id) {
+    const [state, setState] = useState({
+        rows: [],
+        loading: true,
+        error: null,
+    });
+    useEffect(() => {
+        let cancelled = false;
+        setState((s) => ({ rows: s.rows, loading: true, error: null }));
+        // Server's typed-query path accepts `{ kind: "from_table", table_id }`
+        // as the simplest AST; the resolver returns rows shaped per the table's
+        // schema with source-addressing columns appended.
+        rpc("query", {
+            ast: { kind: "from_table", table_id },
+        })
+            .then((result) => {
+            if (cancelled)
+                return;
+            setState({ rows: result.rows ?? [], loading: false, error: null });
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setState({ rows: [], loading: false, error: err.message });
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [table_id]);
+    return state;
+}
+export function useMutate(table_id) {
+    return {
+        // The parent's RPC bridge currently dispatches all `mutate` ops to update.
+        // We omit the `op` field here rather than ship dead data — when create /
+        // delete mutations land, we'll add `op` and a parent-side switch together.
+        update: (records) => rpc("mutate", { table_id, records }),
+    };
+}
+/** Trigger a workflow by action_id. Returns a callable that runs it. */
+export function useAction(action_id) {
+    return useCallback((inputs) => rpc("action", { action_id, inputs: inputs ?? {} }), [action_id]);
+}
+/**
+ * Escape hatch — pass a raw query AST. Same shape the server validates via
+ * `parseQueryNode`. Use for joins, group-by, projections, and other shapes
+ * `useTable`/`useRecord` don't express.
+ */
+export function useQuery(ast) {
+    const astKey = JSON.stringify(ast);
+    const [state, setState] = useState({
+        rows: [],
+        loading: true,
+        error: null,
+    });
+    useEffect(() => {
+        let cancelled = false;
+        setState((s) => ({ rows: s.rows, loading: true, error: null }));
+        rpc("query", { ast })
+            .then((result) => {
+            if (cancelled)
+                return;
+            setState({ rows: result.rows ?? [], loading: false, error: null });
+        })
+            .catch((err) => {
+            if (cancelled)
+                return;
+            setState({ rows: [], loading: false, error: err.message });
+        });
+        return () => {
+            cancelled = true;
+        };
+        // Dep is the stringified AST so structurally-equal-but-referentially-new
+        // objects don't re-fetch on every render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [astKey]);
+    return state;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Lotics App SDK — the runtime + typed hooks bundled into every custom-code
+ * app at build time. Apps `import { mount, useTable, ... } from "@lotics/app-sdk"`
+ * and ship the resulting bundle via `lotics app deploy`.
+ *
+ * Curated UI primitive re-exports from `@lotics/ui` are deliberately NOT
+ * included here. Users import them separately from a published `@lotics/ui`
+ * package once that's ready, or compose with vanilla HTML/CSS in the
+ * meantime. Splitting the package boundaries lets the SDK ship without
+ * depending on packages/ui's React Native Web setup.
+ */
+export { mount } from "./mount.js";
+export { useTable, useMutate, useAction, useQuery } from "./hooks.js";
+export { rpc } from "./rpc.js";
+export type { RpcOp } from "./rpc.js";
+export type { WorkspaceTables, RowOf, TableRow, SourceAddressing, QueryAst } from "./types.js";

package/dist/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * Lotics App SDK — the runtime + typed hooks bundled into every custom-code
+ * app at build time. Apps `import { mount, useTable, ... } from "@lotics/app-sdk"`
+ * and ship the resulting bundle via `lotics app deploy`.
+ *
+ * Curated UI primitive re-exports from `@lotics/ui` are deliberately NOT
+ * included here. Users import them separately from a published `@lotics/ui`
+ * package once that's ready, or compose with vanilla HTML/CSS in the
+ * meantime. Splitting the package boundaries lets the SDK ship without
+ * depending on packages/ui's React Native Web setup.
+ */
+export { mount } from "./mount.js";
+export { useTable, useMutate, useAction, useQuery } from "./hooks.js";
+export { rpc } from "./rpc.js";

package/dist/src/mount.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Entry point for Lotics custom-code apps.
+ *
+ * Usage in a user's `src/main.tsx`:
+ *
+ * ```tsx
+ * import { mount } from "@lotics/app-sdk";
+ * import App from "./App";
+ *
+ * mount(<App />);
+ * ```
+ *
+ * `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
+ * renders the user's tree.
+ *
+ * If the bundler doesn't ship #root in the user's `index.html`, we create it
+ * — Vite's default scaffold provides one, but defensive creation keeps the
+ * mount resilient.
+ */
+import type { ReactNode } from "react";
+export declare function mount(element: ReactNode): void;

package/dist/src/mount.js

@@ -0,0 +1,32 @@
+import { createRoot } from "react-dom/client";
+export function mount(element) {
+    let container = document.getElementById("root");
+    if (!container) {
+        container = document.createElement("div");
+        container.id = "root";
+        document.body.appendChild(container);
+    }
+    // Surface the most common silent-failure modes (a thrown render error or an
+    // unhandled rejection) as visible text in the iframe so the developer sees
+    // *something* even before the parent's debug telemetry is wired up.
+    installVisibleErrorHandlers(container);
+    createRoot(container).render(element);
+}
+function installVisibleErrorHandlers(container) {
+    const showError = (message) => {
+        const banner = document.createElement("pre");
+        banner.style.cssText =
+            "position: fixed; top: 0; left: 0; right: 0; padding: 12px 16px; " +
+                "background: #fef2f2; color: #991b1b; font: 13px/1.4 monospace; " +
+                "white-space: pre-wrap; border-bottom: 1px solid #fecaca; margin: 0; z-index: 99999;";
+        banner.textContent = message;
+        container.parentElement?.insertBefore(banner, container);
+    };
+    window.addEventListener("error", (e) => {
+        showError(`Uncaught error: ${e.message}\n${e.error?.stack ?? ""}`);
+    });
+    window.addEventListener("unhandledrejection", (e) => {
+        const reason = e.reason instanceof Error ? `${e.reason.message}\n${e.reason.stack ?? ""}` : String(e.reason);
+        showError(`Unhandled rejection: ${reason}`);
+    });
+}

package/dist/src/rpc.d.ts

@@ -0,0 +1,18 @@
+/**
+ * postMessage RPC bridge to the parent Lotics frontend.
+ *
+ * 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.
+ *
+ * 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 }
+ *
+ * Bumping protocol version requires a coordinated change in the parent —
+ * old bundles must keep working forever, since we can't force users to
+ * redeploy. Add new ops alongside existing ones; never repurpose them.
+ */
+export type RpcOp = "query" | "mutate" | "action" | "filter";
+export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;

package/dist/src/rpc.js

@@ -0,0 +1,52 @@
+/**
+ * postMessage RPC bridge to the parent Lotics frontend.
+ *
+ * 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.
+ *
+ * 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 }
+ *
+ * Bumping protocol version requires a coordinated change in the parent —
+ * old bundles must keep working forever, since we can't force users to
+ * redeploy. Add new ops alongside existing ones; never repurpose them.
+ */
+const pending = new Map();
+let nextRpcId = 0;
+let listenerInstalled = false;
+function ensureListener() {
+    if (listenerInstalled)
+        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)
+            return;
+        const msg = event.data;
+        if (!msg || typeof msg.id !== "number")
+            return;
+        const handler = pending.get(msg.id);
+        if (!handler)
+            return;
+        pending.delete(msg.id);
+        if (msg.type === "result") {
+            handler.resolve(msg.data);
+        }
+        else {
+            handler.reject(new Error(msg.message ?? "RPC failed"));
+        }
+    });
+}
+export function rpc(op, payload) {
+    ensureListener();
+    return new Promise((resolve, reject) => {
+        const id = nextRpcId++;
+        pending.set(id, { resolve: resolve, reject });
+        window.parent.postMessage({ id, op, payload }, "*");
+    });
+}

package/dist/src/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Workspace-specific type augmentation point.
+ *
+ * The base SDK ships `WorkspaceTables` empty — every table read returns rows
+ * of `Record<string, unknown>`. The `lotics types` codegen writes a file
+ * (typically `.lotics/types.ts`) that extends this interface with the user's
+ * actual table schemas via TypeScript's module augmentation:
+ *
+ * ```ts
+ * // .lotics/types.ts (generated)
+ * import "@lotics/app-sdk";
+ * declare module "@lotics/app-sdk" {
+ *   interface WorkspaceTables {
+ *     "tbl_orders": { container_no: string; status: "active" | "closed" };
+ *   }
+ * }
+ * ```
+ *
+ * After that, `useTable("tbl_orders")` is fully typed. Without the augmented
+ * file in tsconfig's include list, table IDs are typed as `string` and rows
+ * are `Record<string, unknown>` — code still runs, just untyped.
+ */
+export interface WorkspaceTables {
+}
+/**
+ * Helper: row type for a known table id, or fallback for unknown ones.
+ * Currently unused by exported hooks (useRecord deferred to v2) but kept
+ * for the eventual augmented-typing path.
+ */
+export type RowOf<K extends string> = K extends keyof WorkspaceTables ? WorkspaceTables[K] : Record<string, unknown>;
+/** Source addressing emitted by the server for every record-derived row. */
+export interface SourceAddressing {
+    __source_table_id?: string;
+    __source_record_id?: string;
+    __source_locked?: boolean;
+}
+/** A single record row plus source-addressing metadata. */
+export type TableRow<K extends string> = RowOf<K> & SourceAddressing;
+/**
+ * Query AST passed to `useQuery` for power-user composition. Mirrors
+ * `AppDataSourceQuery.root` server-side. Kept opaque (`unknown`) here
+ * because the recursive zod schema doesn't translate to a clean TS type.
+ * The server validates via `parseQueryNode`.
+ */
+export type QueryAst = unknown;

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@lotics/app-sdk",
+  "version": "0.1.0",
+  "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
+  "type": "module",
+  "exports": {
+    ".": "./dist/src/index.js"
+  },
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsgo",
+    "typecheck": "tsgo --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "keywords": [
+    "lotics",
+    "app-sdk",
+    "react",
+    "iframe"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lotics/lotics.git",
+    "directory": "packages/app-sdk"
+  }
+}