@lotics/app-sdk 0.2.0 → 0.3.0

package/dist/src/hooks.d.ts

@@ -3,6 +3,16 @@ 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.
@@ -34,20 +44,25 @@ export declare function useAction(action_id: string): (inputs?: Record<string, u
  * 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>;
 /**
  * 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 {
@@ -66,6 +71,10 @@ export function useWorkflow(alias) {
  */
 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,
@@ -89,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/package.json

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