@lotics/app-sdk 0.93.0 → 0.94.0

package/dist/src/hooks.d.ts

@@ -334,11 +334,16 @@ export interface WorkflowResult<TData = unknown> {
     files?: UploadedFile[];
     data?: TData;
     /**
-     * Per-input refusals the workflow returned via `return({ field_errors })`,
-     * keyed by the INPUT name it declares — what a form wires straight onto the
-     * control that is wrong (`<FormField error={result.field_errors?.ly_do}>`),
-     * where `message` can only say it at the dialog's scope. Absent when the
-     * workflow returned none.
+     * Per-input refusals, keyed by the INPUT name the alias declares — what a
+     * form wires straight onto the control that is wrong
+     * (`<FormField error={result.field_errors?.ly_do}>`), where `message` can
+     * only say it at the dialog's scope.
+     *
+     * Either half of the round trip fills it: the SERVER, when the payload does
+     * not match what the alias declares, and the workflow's own
+     * `return({ field_errors })`. One key, so a screen wires the control once
+     * rather than branching on which half refused. Absent when neither named a
+     * field — and an older server names none.
      */
     field_errors?: Record<string, string>;
 }

package/dist/src/rpc.js

@@ -568,6 +568,34 @@ export function transportErrorMessage(status, parsed) {
         parsed.code.length > 0;
     return status < 500 || authored ? jsonMessage : gatewayErrorMessage(status);
 }
+/**
+ * A failed request, carrying the per-input refusals when the API named any.
+ *
+ * A body that does not match what an alias declares is answered 400 with
+ * top-level `field_errors` — one sentence per INPUT name, which is what a form
+ * puts on the control that is wrong, where the message can only say it at the
+ * screen's scope. It rides the error because the transport's own callers are
+ * what turn a failure into the result an app reads. Optional throughout: a
+ * server that predates them sends none.
+ */
+class ApiRefusal extends Error {
+    field_errors;
+    constructor(message, field_errors) {
+        super(message);
+        this.field_errors = field_errors;
+    }
+}
+/** The `field_errors` of an error body, when it carries a well-formed one. */
+function readFieldErrors(parsed) {
+    if (parsed === null || typeof parsed !== "object" || !("field_errors" in parsed)) {
+        return undefined;
+    }
+    const raw = parsed.field_errors;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const named = Object.entries(raw).filter((entry) => typeof entry[1] === "string");
+    return named.length > 0 ? Object.fromEntries(named) : undefined;
+}
 /**
  * The error a stream that never started should throw.
  *
@@ -663,8 +691,9 @@ async function apiCall(method, path, body, opts) {
             return new Promise(() => { });
         }
         // 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));
+        // the message — emit a body-free, status-derived message instead. The
+        // per-input refusals ride along, for the caller that can place them.
+        throw new ApiRefusal(transportErrorMessage(res.status, parsed), readFieldErrors(parsed));
     }
     return parsed ?? (text ? text : {});
 }
@@ -793,7 +822,16 @@ async function standaloneWorkflow(p) {
         // 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." };
+        //
+        // A payload the alias refuses is that same shape plus the inputs it named,
+        // which is the half a form can act on — the same key a workflow's own
+        // `return({ field_errors })` arrives under, so a screen wires one control
+        // once whichever half answered.
+        return {
+            status: "error",
+            message: err instanceof Error ? err.message : "The workflow failed to run.",
+            ...(err instanceof ApiRefusal && err.field_errors ? { field_errors: err.field_errors } : {}),
+        };
     }
 }
 async function standaloneAgentRuns(p) {

package/docs/mutations.md

@@ -65,7 +65,7 @@ Every call resolves to a `WorkflowResult<TData>` (type exported from the package
 | `message` | `string?` | The workflow's `return({ message })` text, a validation/binding error, or a body-free transport message |
 | `files` | `UploadedFile[]?` | Files generated during the run (auto-collected — below). Absent when the run generated none |
 | `data` | `TData?` | Structured data from `return({ data })`. Absent when no return step ran |
-| `field_errors` | `Record<string, string>?` | Per-input refusals from `return({ field_errors })`, keyed by the INPUT name the alias declares. Absent when the workflow returned none |
+| `field_errors` | `Record<string, string>?` | Per-input refusals, keyed by the INPUT name the alias declares — from the server when the payload does not match what the alias declares, and from the workflow's own `return({ field_errors })`. Absent when neither named a field |
 
 ### The failure model: check `status`, never just try/catch
 
@@ -111,8 +111,10 @@ passes through unvalidated).
 
 ### Locating a refusal: `field_errors`
 
-A workflow that validates its own inputs refuses with both halves — a message for the dialog and a
-map for the controls:
+Two things refuse a call, and both address the input they refused. A payload that does not match
+what the alias declares — a missing required input, a value of the wrong type — is refused before
+the workflow runs, with one sentence per input name. A workflow that validates its own inputs
+refuses the same way, with both halves — a message for the dialog and a map for the controls:
 
 ```ts
 return({ status: "error", message: "Thiếu lý do.",
@@ -130,7 +132,8 @@ setErrs(result.field_errors ?? {});
 ```
 
 Keep `message` too — it is what a refusal with no field to blame says, and the two are shown
-together (a `Callout` at the dialog's scope plus the per-field text).
+together (a `Callout` at the dialog's scope plus the per-field text). One reading covers both
+refusals: the key is the same whichever half answered, so a form never branches on that.
 
 ### Generated files come back in `files[]`
 

package/package.json

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