@lotics/cli 0.56.0 → 0.57.0

package/dist/app_commands.d.ts

@@ -31,7 +31,7 @@ export type AppQueryDeclaration = {
  *   `"alias": { instructions, tool_names, model_id, inputs?, outputs? }`
  *
  * A read-only reflection of the live App row (`apps.agents`, owned by
- * `set_app_agent`), refreshed by `lotics app pull` and used only to codegen
+ * `set_app_agent` / `remove_app_agent`), refreshed by `lotics app pull` and used only to codegen
  * `useAgentRun` typings. `inputs`/`outputs` drive the typed call site; the rest
  * is carried for fidelity.
  */

package/dist/client.d.ts

@@ -1,3 +1,11 @@
+/**
+ * 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. `parsed` is the JSON.parse of the body, or `null`.
+ * In parity (by value, no shared dep) with `packages/app-sdk/src/rpc.ts`.
+ */
+export declare function transportErrorMessage(status: number, parsed: unknown): string;
 /** One sort key forwarded to the app query RPC (wire shape of a `TableRecordSort` entry). */
 export interface AppQuerySortKey {
     field_key: string;

package/dist/client.js

@@ -1,5 +1,36 @@
 import fs from "node:fs";
 import path from "node:path";
+/**
+ * A user-facing message for a transport/gateway failure — derived from the HTTP
+ * status, never from the response body. A 524 (edge timeout on a long run), any
+ * 5xx, or a non-JSON body (an HTML error page) must NOT surface its raw body. In
+ * parity (by value, no shared dep) with the published transport in
+ * `packages/app-sdk/src/rpc.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. `parsed` is the JSON.parse of the body, or `null`.
+ * In parity (by value, no shared dep) with `packages/app-sdk/src/rpc.ts`.
+ */
+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;
+}
 function findAvailableFilename(dir, filename, reserved) {
     // `reserved` tracks absolute paths claimed by in-flight downloads in the same
     // batch — required for parallel callers because the file may not be on disk
@@ -200,7 +231,34 @@ export class LoticsClient {
      * Mirrors POST /v1/apps/{app_id}/workflows/{alias}/execute.
      */
     async appWorkflow(app_id, alias, inputs) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`, { inputs });
+        // Its own transport (not the generic `request`, whose `throwResponseError`
+        // shape is the CLI contract elsewhere): a transport/gateway failure resolves
+        // to a `WorkflowResult` error `{ status, message }` — never a thrown HTML
+        // body — so the dev RPC bridge forwards `{status:"error"}` to the iframe,
+        // matching the deployed standalone SDK (`@lotics/app-sdk` standaloneWorkflow).
+        const url = `${this.baseUrl}/v1/apps/${encodeURIComponent(app_id)}/workflows/${encodeURIComponent(alias)}/execute`;
+        const headers = this.buildHeaders();
+        headers["Content-Type"] = "application/json";
+        let response;
+        try {
+            response = await fetch(url, { method: "POST", headers, body: JSON.stringify({ inputs }) });
+        }
+        catch (err) {
+            return { status: "error", message: err instanceof Error ? err.message : "The workflow request failed." };
+        }
+        const text = await response.text();
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                // non-JSON body (e.g. a gateway HTML error page) — never echoed
+            }
+        }
+        if (response.ok)
+            return parsed ?? {};
+        return { status: "error", message: transportErrorMessage(response.status, parsed) };
     }
     /**
      * Open a streaming agent run and return the RAW streamed `Response` (the

package/dist/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/client.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { LoticsClient, transportErrorMessage } from "./client.js";
+describe("transportErrorMessage", () => {
+    it("returns a body-free gateway message for a non-JSON 524 (never the HTML)", () => {
+        const msg = transportErrorMessage(524, null);
+        expect(msg).not.toMatch(/<html|<!DOCTYPE/i);
+        expect(msg.toLowerCase()).toContain("gateway timeout");
+    });
+    it("returns a friendly message for any 5xx, ignoring a JSON body", () => {
+        expect(transportErrorMessage(503, { message: "internal detail" })).not.toBe("internal detail");
+        expect(transportErrorMessage(503, { message: "internal detail" })).not.toMatch(/<html/i);
+    });
+    it("surfaces a genuine 4xx JSON error message verbatim", () => {
+        expect(transportErrorMessage(400, { message: "record_id is required" })).toBe("record_id is required");
+    });
+    it("never leaks a non-JSON 4xx body (WAF / redirect HTML)", () => {
+        expect(transportErrorMessage(403, null)).not.toMatch(/<html|<!DOCTYPE/i);
+    });
+    it("falls back to a friendly message for a JSON body with no message field", () => {
+        expect(transportErrorMessage(409, { error_code: "CONFLICT" })).toBeTruthy();
+        expect(transportErrorMessage(409, { error_code: "CONFLICT" })).not.toMatch(/<html/i);
+    });
+});
+describe("LoticsClient.appWorkflow", () => {
+    afterEach(() => vi.unstubAllGlobals());
+    const client = new LoticsClient({ apiKey: "ltk_test", workspaceId: "wsp_test" });
+    it("normalizes a 524 HTML gateway response to a WorkflowResult error (no raw HTML)", async () => {
+        const html = "<!DOCTYPE html><html><head><title>error</title></head><body>524: A timeout occurred</body></html>";
+        vi.stubGlobal("fetch", vi.fn(async () => new Response(html, { status: 524 })));
+        const result = (await client.appWorkflow("app_1", "wf", {}));
+        expect(result.status).toBe("error");
+        expect(result.message).not.toMatch(/<html|<!DOCTYPE/i);
+    });
+    it("passes a 200 workflow result through unchanged", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ status: "success", data: { x: 1 } }), { status: 200 })));
+        const result = await client.appWorkflow("app_1", "wf", {});
+        expect(result).toEqual({ status: "success", data: { x: 1 } });
+    });
+    it("returns a WorkflowResult error (not a throw) on a network failure", async () => {
+        vi.stubGlobal("fetch", vi.fn(async () => {
+            throw new Error("ECONNREFUSED");
+        }));
+        const result = (await client.appWorkflow("app_1", "wf", {}));
+        expect(result.status).toBe("error");
+        expect(result.message).toContain("ECONNREFUSED");
+    });
+});