@lotics/app-sdk 0.5.0 → 0.6.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

@@ -13,5 +13,5 @@
  * Bumping protocol version requires a coordinated change in the parent.
  * Add new ops alongside existing ones; never repurpose them.
  */
-export type RpcOp = "query" | "workflow";
+export type RpcOp = "query" | "workflow" | "upload";
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;

package/package.json

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