@lotics/app-sdk 0.2.0 → 0.5.0

package/dist/src/hooks.d.ts

@@ -1,57 +1,59 @@
-import type { AppWorkflows, QueryAst, TableRow, WorkspaceTables } from "./types.js";
+import type { AppWorkflows, AppQueries } from "./types.js";
 interface QueryState<R> {
     rows: R[];
     loading: boolean;
     error: string | null;
+    /**
+     * Re-run the underlying query against the current AST. Use after a known
+     * mutation point — a successful `useWorkflow(alias)()` call — to pull the
+     * latest state.
+     *
+     * The iframe SDK does not subscribe to realtime invalidation channels in
+     * v1; refetch is the explicit refresh path. Future SDK versions may add a
+     * `subscribe` RPC op for push-based invalidation.
+     */
+    refetch: () => void;
 }
-/**
- * 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>;
 /**
  * Trigger a workflow by alias from the app's manifest.
  *
  * The alias must be declared in `package.json` "lotics.workflows" and synced
- * to `apps.workflows` on the last deploy. Returns a callable; pass whatever
- * inputs the workflow expects (the workflow's own trigger schema gates them
- * server-side).
+ * to `apps.workflows` on the last deploy.
  *
- * Per-app `lotics types` codegen augments `AppWorkflows` with the declared
- * alias keys — passing an undeclared alias is a compile-time error.
+ * Per-app CLI codegen (`lotics app pull` / `app dev` / `app deploy`) writes
+ * `.lotics/app_workflows.d.ts` augmenting `AppWorkflows` with the declared
+ * alias → input-type map. Result:
+ *   - Undeclared alias → compile-time error at the `useWorkflow("...")` site
+ *   - Declared with full `{workflow_id, inputs}` form → callable typed as
+ *     `(inputs: <DeclaredShape>) => Promise<unknown>`
+ *   - Declared with shorthand (bare workflow_id) → callable typed as
+ *     `(inputs?: Record<string, unknown>) => Promise<unknown>` (untyped)
  *
  * ```tsx
  * const issue = useWorkflow("issueInvoiceStorageDrop");
  * await issue({ record_id: row.__source_record_id });
  * ```
  */
-export declare function useWorkflow<K extends keyof AppWorkflows & string>(alias: K): (inputs?: Record<string, unknown>) => Promise<unknown>;
+export declare function useWorkflow<K extends keyof AppWorkflows & string>(alias: K): UseWorkflowFn<K>;
 export declare function useWorkflow(alias: string): (inputs?: Record<string, unknown>) => Promise<unknown>;
+type UseWorkflowFn<K extends keyof AppWorkflows & string> = AppWorkflows[K] extends Record<string, unknown> ? AppWorkflows[K] extends Record<string, never> ? (inputs?: Record<string, never>) => Promise<unknown> : (inputs: AppWorkflows[K]) => Promise<unknown> : (inputs?: Record<string, unknown>) => Promise<unknown>;
+type UseQueryParams<K extends keyof AppQueries & string> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>] : [params: AppQueries[K]];
 /**
- * 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.
+ * Read rows from a query the app's author declared in `lotics.queries`.
+ *
+ * The app never sends a raw query AST — it invokes a named query by alias and
+ * fills the template's declared `{{params.x}}` value holes. The server holds
+ * the canonical AST; this is what bounds a public app's data exposure to
+ * exactly the queries the manifest declares.
+ *
+ * ```tsx
+ * const { rows, loading } = useQuery("openOrders", { status: "open" });
+ * ```
+ *
+ * Per-app CLI codegen writes `.lotics/app_queries.d.ts` augmenting `AppQueries`
+ * with the declared alias → param-type map, so an undeclared alias is a
+ * compile-time error and params are typed per the manifest.
  */
-export declare function useQuery(ast: QueryAst): QueryState<Record<string, unknown>>;
+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>>;
 export {};

package/dist/src/hooks.js

@@ -1,71 +1,29 @@
 /**
  * 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.
+ * 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.
  *
- * 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.
+ * 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
+ * their own local cache via `useState`; we intentionally don't ship a global
+ * store in v1.
  */
 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]);
-}
 export function useWorkflow(alias) {
     return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
 }
-/**
- * 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);
+export function useQuery(alias, params) {
+    // Stringified params key — structurally-equal-but-new param objects don't
+    // re-fire the effect every render.
+    const paramsKey = JSON.stringify(params ?? {});
+    // Bumping this token re-fires the effect without changing alias/params. The
+    // 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,
@@ -74,7 +32,7 @@ export function useQuery(ast) {
     useEffect(() => {
         let cancelled = false;
         setState((s) => ({ rows: s.rows, loading: true, error: null }));
-        rpc("query", { ast })
+        rpc("query", { alias, params: params ?? {} })
             .then((result) => {
             if (cancelled)
                 return;
@@ -88,9 +46,10 @@ export function useQuery(ast) {
         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;
+    }, [alias, paramsKey, refetchToken]);
+    const refetch = useCallback(() => {
+        setRefetchToken((n) => n + 1);
+    }, []);
+    return { ...state, refetch };
 }

package/dist/src/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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`.
+ * app at build time. Apps `import { mount, useQuery, useWorkflow } 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`
@@ -10,7 +10,7 @@
  * depending on packages/ui's React Native Web setup.
  */
 export { mount } from "./mount.js";
-export { useTable, useMutate, useAction, useWorkflow, useQuery } from "./hooks.js";
+export { useWorkflow, useQuery } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
-export type { WorkspaceTables, AppWorkflows, RowOf, TableRow, SourceAddressing, QueryAst, } from "./types.js";
+export type { AppWorkflows, AppQueries } from "./types.js";

package/dist/src/index.js

@@ -1,7 +1,7 @@
 /**
  * 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`.
+ * app at build time. Apps `import { mount, useQuery, useWorkflow } 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`
@@ -10,5 +10,5 @@
  * depending on packages/ui's React Native Web setup.
  */
 export { mount } from "./mount.js";
-export { useTable, useMutate, useAction, useWorkflow, useQuery } from "./hooks.js";
+export { useWorkflow, useQuery } from "./hooks.js";
 export { rpc } from "./rpc.js";

package/dist/src/rpc.d.ts

@@ -10,9 +10,8 @@
  *   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.
+ * Bumping protocol version requires a coordinated change in the parent.
+ * Add new ops alongside existing ones; never repurpose them.
  */
-export type RpcOp = "query" | "mutate" | "action" | "workflow" | "filter";
+export type RpcOp = "query" | "workflow";
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;

package/dist/src/rpc.js

@@ -10,9 +10,8 @@
  *   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.
+ * Bumping protocol version requires a coordinated change in the parent.
+ * Add new ops alongside existing ones; never repurpose them.
  */
 const pending = new Map();
 let nextRpcId = 0;

package/dist/src/types.d.ts

@@ -1,71 +1,49 @@
 /**
- * Workspace-specific type augmentation point.
+ * App-specific workflow 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:
+ * The base SDK ships `AppWorkflows` empty — `useWorkflow(alias)` accepts any
+ * string at runtime. Per-app codegen (folded into `lotics app pull`) emits a
+ * file that augments this interface with the aliases declared in the app's
+ * `package.json` lotics.workflows, giving compile-time autocomplete +
+ * "undeclared alias" errors:
  *
  * ```ts
- * // .lotics/types.ts (generated)
+ * // .lotics/app_workflows.d.ts (generated)
  * import "@lotics/app-sdk";
  * declare module "@lotics/app-sdk" {
- *   interface WorkspaceTables {
- *     "tbl_orders": { container_no: string; status: "active" | "closed" };
+ *   interface AppWorkflows {
+ *     "issueInvoiceStorageDrop": { record_id: string };
+ *     "issueInvoiceReuseLift": Record<string, never>;
  *   }
  * }
  * ```
  *
- * 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.
+ * The value type is the workflow's declared input shape — `Record<string, never>`
+ * for a workflow that takes no typed inputs, the typed object otherwise.
  */
-export interface WorkspaceTables {
+export interface AppWorkflows {
 }
 /**
- * App-specific workflow augmentation point. Same pattern as WorkspaceTables.
+ * App-specific named-query augmentation point. Same pattern as AppWorkflows.
  *
- * The base SDK ships `AppWorkflows` empty — `useWorkflow(alias)` accepts any
- * string at runtime. Per-app codegen (folded into `lotics app pull`) emits a
- * file that augments this interface with the aliases declared in the app's
- * `package.json` lotics.workflows, giving compile-time autocomplete +
- * "undeclared alias" errors:
+ * The base SDK ships `AppQueries` empty — `useQuery(alias)` accepts any string
+ * at runtime. Per-app codegen (`lotics app pull`) emits a file that augments
+ * this interface with the queries declared in the app's `package.json`
+ * lotics.queries, mapping each alias to its declared param type:
  *
  * ```ts
- * // .lotics/types.ts (generated)
+ * // .lotics/app_queries.d.ts (generated)
  * import "@lotics/app-sdk";
  * declare module "@lotics/app-sdk" {
- *   interface AppWorkflows {
- *     "issueInvoiceStorageDrop": never;
- *     "issueInvoiceReuseLift": never;
+ *   interface AppQueries {
+ *     "openOrders": { status: string };
+ *     "allContainers": Record<string, never>;
  *   }
  * }
  * ```
  *
- * The `never` value is a placeholder for v2 input/output typing — when the
- * codegen learns to extract workflow trigger schemas, the value becomes the
- * input type. For now the hook's runtime signature is unaffected.
+ * The value type is the query's declared param shape — `Record<string, never>`
+ * for a query that takes no params, the typed object otherwise.
  */
-export interface AppWorkflows {
+export interface AppQueries {
 }
-/**
- * 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/package.json

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