@lotics/app-sdk 0.41.0 → 0.42.1

package/AGENTS.md

@@ -39,7 +39,10 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
 - **Mutate (the ONLY write path)** — **`useWorkflow(alias)`** → an async fn returning a typed
   `WorkflowResult` `{ status, message?, files?, data? }`. `data` is whatever the workflow
   `return({ data })`'d (typed automatically from the alias contract). After a known mutation,
-  call the owning query's `refetch()`.
+  call the owning query's `refetch()`. Handle failures by checking `result.status === "error"`,
+  not just `try/catch`: a transport/gateway failure (a 524 timeout on a long run, any 5xx, a
+  non-JSON error page) **resolves** with `{ status: "error", message }` (a friendly, body-free
+  message) — it does not throw an HTML body.
 - **Upload a file** — **`useFileUpload()`** → `{ upload, uploading, error }`. Mints a presigned URL
   and PUTs the bytes straight to storage; the file is inert until a workflow attaches it to a
   `files` field. Emits `app_file_uploaded`.
@@ -52,7 +55,10 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   to a `DisplayFile` (snake → camel — `mime_type`→`mimeType`, `preview_url`→`url` — the app owns this
   data→UI adapter; the SDK never imports `@lotics/ui`) for
   `<FileThumbnail file={{ id, filename, mimeType, url }} uploading={f.status === "uploading"} />`;
-  `sendDisabled` gates on `uploading` and the send payload is `fileIds`. Don't hand-roll
+  `sendDisabled` gates on `uploading` and the send payload is `fileIds`. To persist several files into ONE
+  record, declare the workflow input `{ type: "file", multi: true }` — the body receives `fileIds` as
+  `ReadonlyArray<FileId>` and writes it straight to a `files` field (a single `file` input is one id → wrap `[id]`).
+  Don't hand-roll
   `createObjectURL`/upload/revoke per app. For a full add-files SCREEN (not the composer pill), map
   each `AttachedFile` to a `FileUpload` (ready → `{ status: "complete", id, file }`, else
   `{ status, id, filename, mimeType: mime_type, previewUrl: preview_url }`) and feed `@lotics/ui`

package/dist/src/hooks.d.ts

@@ -164,6 +164,12 @@ type UseWorkflowFn<K extends keyof AppWorkflows & string> = AppWorkflows[K] exte
  *
  * `data` is the structured value the workflow returned via `return({ data })`,
  * typed per the alias's declared `outputs` schema (`unknown` when none was declared).
+ *
+ * A transport/gateway failure (a Cloudflare 524 timeout on a long run, any 5xx,
+ * or a non-JSON error page) **resolves** with `{ status: "error", message }` —
+ * a body-free, friendly message — rather than rejecting with a raw HTML body.
+ * So an app handles every failure (handled workflow error AND transport error)
+ * by checking `result.status === "error"`; it never receives gateway HTML.
  */
 export interface WorkflowResult<TData = unknown> {
     status: "success" | "error";

package/dist/src/hooks.js

@@ -26,7 +26,7 @@ export function useWorkflow(alias) {
     return useCallback(async (inputs) => {
         try {
             const result = await rpc("workflow", { alias, inputs: inputs ?? {} });
-            captureAppEvent("app_workflow_run", { alias, ok: true });
+            captureAppEvent("app_workflow_run", { alias, ok: result.status !== "error" });
             return result;
         }
         catch (err) {

package/dist/src/rpc.d.ts

@@ -86,3 +86,11 @@ export declare function subscribeUrlParams(cb: (params: UrlParams) => void): ()
  * standalone: the SDK reads the public endpoint's body directly.
  */
 export declare function rpcAgentRun(payload: AgentRunPayload, onText: (chunk: string) => void, onRunId?: (runId: string) => void): AgentRunHandle;
+/**
+ * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
+ * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
+ * 5xx, or a JSON body without a `message` falls back to a body-free,
+ * status-derived message — so a raw HTML body never becomes the message.
+ * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
+ */
+export declare function transportErrorMessage(status: number, parsed: unknown): string;

package/dist/src/rpc.js

@@ -334,6 +334,37 @@ async function acquireSessionToken(appId) {
         },
     });
 }
+/**
+ * A user-facing message for a transport/gateway failure — derived from the HTTP
+ * status, never from the response body. A 524 (Cloudflare edge timeout on a long
+ * run), any 5xx, or a non-JSON body (an HTML error page) must NOT surface its raw
+ * body as the error message. Kept in parity (by value, no shared dep) with the
+ * dev-loop transport in `packages/sdk/src/client.ts`.
+ */
+function gatewayErrorMessage(status) {
+    if (status === 524) {
+        return "The request took too long to finish (gateway timeout). It may still be running — check back in a moment, or try again.";
+    }
+    if (status >= 500) {
+        return "The service is temporarily unavailable. Please try again shortly.";
+    }
+    return "The service returned an unexpected response. Please try again.";
+}
+/**
+ * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
+ * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
+ * 5xx, or a JSON body without a `message` falls back to a body-free,
+ * status-derived message — so a raw HTML body never becomes the message.
+ * `parsed` is the JSON.parse of the body, or `null` if it wasn't JSON.
+ */
+export function transportErrorMessage(status, parsed) {
+    const jsonMessage = parsed && typeof parsed.message === "string"
+        ? parsed.message
+        : null;
+    return parsed === null || status >= 500 || jsonMessage === null
+        ? gatewayErrorMessage(status)
+        : jsonMessage;
+}
 async function apiCall(method, path, body, opts) {
     const headers = {};
     if (body)
@@ -368,8 +399,9 @@ async function apiCall(method, path, body, opts) {
             await acquireSessionToken(appId);
             return apiCall(method, path, body, { ...opts, appId });
         }
-        const message = errorBody?.message ?? text;
-        throw new Error(message || `HTTP ${res.status}`);
+        // Never surface a non-JSON body (a gateway HTML error page) or a 5xx body as
+        // the message — emit a body-free, status-derived message instead.
+        throw new Error(transportErrorMessage(res.status, parsed));
     }
     return parsed ?? (text ? text : {});
 }
@@ -480,7 +512,16 @@ async function standaloneFieldOptions(p) {
 }
 async function standaloneWorkflow(p) {
     const { app_id } = await boot();
-    return apiCall("POST", `/v1/apps/${app_id}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs }, { appId: app_id });
+    try {
+        return await apiCall("POST", `/v1/apps/${app_id}/workflows/${encodeURIComponent(p.alias)}/execute`, { inputs: p.inputs }, { appId: app_id });
+    }
+    catch (err) {
+        // A transport/gateway failure resolves to a WorkflowResult error (never a
+        // rejection carrying a raw body) so an app reads `result.status === "error"`
+        // uniformly with a handled workflow error. `apiCall` already sanitized the
+        // message, so it never contains an HTML body.
+        return { status: "error", message: err instanceof Error ? err.message : "The workflow failed to run." };
+    }
 }
 async function standaloneAgentRuns(p) {
     const { app_id } = await boot();

package/package.json

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