@lotics/app-sdk 0.1.0 → 0.3.0

package/dist/src/hooks.d.ts

@@ -1,8 +1,18 @@
-import type { QueryAst, TableRow, WorkspaceTables } from "./types.js";
+import type { AppWorkflows, QueryAst, TableRow, WorkspaceTables } from "./types.js";
 interface QueryState<R> {
     rows: R[];
     loading: boolean;
     error: string | null;
+    /**
+     * Re-run the underlying query against the current AST / table_id. Use after
+     * known mutation points — `useMutate.update`, `useAction(...)`, or a
+     * successful `useWorkflow(alias)()` — 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.
@@ -30,6 +40,29 @@ export declare function useMutate(table_id: string): {
 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.
+ *
+ * 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): 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>;
 /**
  * Escape hatch — pass a raw query AST. Same shape the server validates via
  * `parseQueryNode`. Use for joins, group-by, projections, and other shapes

package/dist/src/hooks.js

@@ -14,6 +14,7 @@
 import { useCallback, useEffect, useState } from "react";
 import { rpc } from "./rpc.js";
 export function useTable(table_id) {
+    const [refetchToken, setRefetchToken] = useState(0);
     const [state, setState] = useState({
         rows: [],
         loading: true,
@@ -41,8 +42,12 @@ export function useTable(table_id) {
         return () => {
             cancelled = true;
         };
-    }, [table_id]);
-    return state;
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [table_id, refetchToken]);
+    const refetch = useCallback(() => {
+        setRefetchToken((n) => n + 1);
+    }, []);
+    return { ...state, refetch };
 }
 export function useMutate(table_id) {
     return {
@@ -56,6 +61,9 @@ export function useMutate(table_id) {
 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
@@ -63,6 +71,10 @@ export function useAction(action_id) {
  */
 export function useQuery(ast) {
     const astKey = JSON.stringify(ast);
+    // Bumping this token re-fires the effect without changing the AST. 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,
@@ -86,8 +98,12 @@ export function useQuery(ast) {
             cancelled = true;
         };
         // Dep is the stringified AST so structurally-equal-but-referentially-new
-        // objects don't re-fetch on every render.
+        // objects don't re-fetch on every render. refetchToken lets the consumer
+        // explicitly retrigger without changing the AST identity.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [astKey]);
-    return state;
+    }, [astKey, refetchToken]);
+    const refetch = useCallback(() => {
+        setRefetchToken((n) => n + 1);
+    }, []);
+    return { ...state, refetch };
 }

package/dist/src/index.d.ts

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

package/dist/src/rpc.d.ts

@@ -14,5 +14,5 @@
  * 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 type RpcOp = "query" | "mutate" | "action" | "workflow" | "filter";
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;

package/dist/src/types.d.ts

@@ -22,6 +22,32 @@
  */
 export interface WorkspaceTables {
 }
+/**
+ * App-specific workflow augmentation point. Same pattern as WorkspaceTables.
+ *
+ * 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)
+ * import "@lotics/app-sdk";
+ * declare module "@lotics/app-sdk" {
+ *   interface AppWorkflows {
+ *     "issueInvoiceStorageDrop": never;
+ *     "issueInvoiceReuseLift": 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.
+ */
+export interface AppWorkflows {
+}
 /**
  * Helper: row type for a known table id, or fallback for unknown ones.
  * Currently unused by exported hooks (useRecord deferred to v2) but kept

package/package.json

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