@lotics/app-sdk 0.46.0 → 0.47.0

package/docs/mutations.md

@@ -0,0 +1,438 @@
+# Mutations — writing data through workflows
+
+Everything about writing data from an app: `useWorkflow` (the only write path), the
+`WorkflowResult` contract and its resolve-never-throw failure model, declaring typed workflow
+inputs (file/member/optional inputs), returning structured data with `return({ data })`,
+refetching after a mutation, the diff-before-update discipline, locked records
+(`readLocked` + `request_locked_record_change`), and optimistic reconciliation
+(`useOptimistic`). Read this before building any screen that creates, updates, or deletes
+records. Reading data is [queries](./queries.md) + [data_fetching](./data_fetching.md);
+uploads are [files](./files.md); who a write runs as is [security](./security.md).
+
+## The write model
+
+An app holds no credentials and never writes records directly — there is no
+`createRecord`/`updateRecord` API in the SDK. Every write is a **workflow** bound to an alias
+on the server and invoked by that alias:
+
+```tsx
+import { useWorkflow } from "@lotics/app-sdk";
+
+const createOrder = useWorkflow("createOrder");
+const result = await createOrder({ customer_id, quantity: 3 });
+```
+
+- The server resolves the alias against the app's bound workflows, validates the payload
+  against the alias's declared input schema, and executes the workflow under the **app
+  owner's** authority (never the viewer's — see [security](./security.md) for attribution,
+  privilege gates, and public-app semantics).
+- Binding is server-side (`set_app_workflow`, or `lotics app workflow set <alias>` from the
+  app project). `lotics app deploy` ships code, queries, and capabilities — it never binds
+  workflows.
+  The `package.json#lotics.workflows` map is a *pulled reflection* of the live bindings, used
+  purely to type `useWorkflow` (below); hand-editing it changes nothing on the server.
+- Invoking an alias that is not bound resolves with `status: "error"` and a message naming
+  the missing binding.
+- Anonymous visitors to a publicly shared app can invoke workflows too; the triggering
+  member is then `null` inside the body. See [security](./security.md).
+
+## `useWorkflow(alias)` — signature and typing
+
+Exact signature: `dist/src/hooks.d.ts`. `useWorkflow(alias)` returns a stable async callable:
+`(inputs) => Promise<WorkflowResult<TData>>`.
+
+Typing comes from per-app codegen: `lotics app pull` / `app dev` / `app deploy` /
+`app codegen` write `.lotics/app_workflows.d.ts`, augmenting the SDK's `AppWorkflows` and
+`AppWorkflowResults` interfaces from the manifest's alias declarations. The result:
+
+| Declaration | Call-site type |
+|---|---|
+| Alias not declared | Compile-time error at `useWorkflow("...")` |
+| Declared with `inputs` | `(inputs: <declared shape>) => Promise<WorkflowResult<TData>>` — inputs required and shaped |
+| Declared with an empty `inputs: {}` | `(inputs?: Record<string, never>)` — call with `{}` or nothing |
+| Declared without `inputs` | Untyped `Record<string, unknown>` payload (and unvalidated server-side — declare inputs for any real workflow) |
+| Declared with `outputs` | `result.data` typed as the declared shape (`TData`); otherwise `unknown` |
+
+## `WorkflowResult` — the result contract
+
+Every call resolves to a `WorkflowResult<TData>` (type exported from the package root;
+`dist/src/hooks.d.ts`):
+
+| Field | Type | Meaning |
+|---|---|---|
+| `status` | `"success" \| "error"` | The one field to branch on — see the failure model below |
+| `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 |
+
+### The failure model: check `status`, never just try/catch
+
+**Every failure resolves — the promise (almost) never rejects.** All three transports
+(embedded product host, standalone `<slug>.lotics.app`, and the `lotics app dev` harness)
+convert every failure into a resolved `{ status: "error", message }`:
+
+| Failure | What resolves |
+|---|---|
+| Workflow ends with `return({ status: "error", message })` | That status + message |
+| Workflow crashes mid-run (unhandled tool/expression error) | `status: "error"` with a failure message |
+| Input validation rejected (missing required, extra key, type mismatch) | `status: "error"` with the server's structured field-level message |
+| Alias not bound / workflow deleted | `status: "error"` with the explanatory message |
+| Gateway timeout (a 524 on a long run), any 5xx, a non-JSON error page | `status: "error"` with a friendly, **body-free** message — never raw gateway HTML |
+
+So the correct handling is:
+
+```tsx
+const result = await createOrder({ customer_id, quantity });
+if (result.status === "error") {
+  showError(result.message ?? "Something went wrong.");
+  return;
+}
+orders.refetch();
+```
+
+**Warning:** a `try/catch` with no `status` check silently treats every workflow failure as
+success — the promise resolves either way. Conversely, `status: "success"` on a
+transport-timeout retry is not guaranteed to mean "ran once": a 524 means the run *may still
+be executing* server-side; design retried workflows to be idempotent or re-check state via a
+query before retrying.
+
+**Warning:** a gateway timeout's message is deliberately body-free and generic. Don't parse
+`message` to distinguish failure kinds — it is display text, not a machine-readable code. If
+the app must branch on failure kinds, make the workflow return them:
+`return({ status: "error", data: { code: "OUT_OF_STOCK" } })` (an *error* return's `data`
+passes through unvalidated).
+
+### Generated files come back in `files[]`
+
+Any step in the run whose tool output carries a `file_id` (most commonly the
+`generate_*_from_template` document tools) is collected automatically into
+`result.files[]` — each an `UploadedFile`
+`{ id, filename, mime_type, url?, thumbnail_url? }` with a presigned `url` (24-hour TTL) the
+app can open directly:
+
+```tsx
+const gen = useWorkflow("generateInvoice");
+const { status, files } = await gen({ order_id });
+const url = files?.[0]?.url;
+if (status === "success" && url) await openExternal(url);
+```
+
+Files travel **only** via `files[]` — never hand a `file_id`/`url` back through
+`return({ data })`, and never `update_records` a file onto a record solely to make it
+downloadable. A download-only workflow generates and returns; attaching to a record is a
+separate, optional step. Previewing/downloading files: [files](./files.md).
+
+### Structured results: `return({ data })`
+
+A workflow body ends with `return({ status, message?, data? })`. `data` is arbitrary
+structured data (computed totals, row lists, status objects) the app reads back as
+`result.data`:
+
+- **Typed for free.** The alias's `outputs` schema is derived at save time from the inferred
+  TypeScript type of the body's `return({ data })` — the return *is* the declaration. Codegen
+  then types `result.data` per alias. Declare an explicit `outputs` on the alias (same
+  recursive vocabulary as inputs: scalars plus nested `object`/`array`, no member/file/
+  date_range) only to narrow beyond what's inferred; a shape the checker can't pin down
+  degrades to untyped `json`, never to a wrong schema.
+- **Validated at run.** On a success return, the returned `data` is validated against the
+  schema at the app boundary — a mismatch resolves as `status: "error"` with a field-level
+  message, so a declared output is a real contract. An *error* return's `data` passes through
+  unvalidated.
+- **`data` is optional even when typed.** A workflow that completes without hitting a
+  `return` step resolves `status: "success"` with no `data` (and no validation). If the app
+  depends on `data`, make every success path in the body end in `return({ data })` — and
+  still guard `result.data` at the call site.
+
+```tsx
+const quote = useWorkflow("computeQuote"); // outputs: { total: number, lines: [...] }
+const r = await quote({ order_id });
+if (r.status === "success" && r.data) {
+  render(r.data.total, r.data.lines);
+}
+```
+
+## Declaring workflow inputs
+
+An alias's declaration is `{ workflow_id, inputs?, outputs? }`. `inputs` maps each input name
+to a typed declaration; it is authored when the workflow is bound (`set_app_workflow` /
+`lotics app workflow set` reads it from `package.json#lotics.workflows.<alias>`), and the
+schema the body was verified against is canonical — the manifest reflection cannot silently
+weaken it. It drives three things at once: compile-time typing of the `useWorkflow` payload,
+compile-time typing of `trigger.app_workflow.inputs.*` inside the body, and runtime payload
+validation at the execute boundary.
+
+### Input vocabulary
+
+Every declaration takes optional `description` and `required` (default **true**).
+
+| `type` | Extra declaration fields | Payload value | Codegen TS type |
+|---|---|---|---|
+| `text` | — | any string | `string` |
+| `number` | — | a number | `number` |
+| `boolean` | — | a boolean | `boolean` |
+| `date` | — | `"YYYY-MM-DD"`, or a TZ-bearing ISO datetime (projected to the workspace day) | `string` |
+| `datetime` | — | `"YYYY-MM-DDTHH:mm"` naive workspace wall-clock (what the platform DatePicker emits), or TZ-bearing ISO | `string` |
+| `email` | — | a valid email | `string` |
+| `select` | `options: [{label, value}]` (min 1), `multi?` | an option key (array when `multi`) | union of declared `value` literals; `ReadonlyArray<…>` when `multi` |
+| `record_link` | `table_id` (required), `multi?` | a record id — must exist **in the declared table** | `string` / `ReadonlyArray<string>` |
+| `member` | `group?`, `multi?` | a member id — with `group`, must belong to that group | `string` / `ReadonlyArray<string>` |
+| `file` | `multi?` | a file id from an upload — must live in the app's workspace | `string` / `ReadonlyArray<string>` |
+| `date_range` | `include_time?` | `{ start, end }` strings | `{ start: string; end: string }` |
+| `object` | `fields: { name: declaration }` | a nested object (strict — undeclared keys rejected) | nested object type |
+| `array` | `items: declaration` | an array of the item shape | `ReadonlyArray<…>` |
+| `json` | — | anything (unvalidated escape hatch) | `unknown` |
+
+`object`/`array` nest the full vocabulary (max depth 8), so a structured payload — an array
+of line-item objects — arrives in the body as a typed `ReadonlyArray<{…}>` instead of being
+smuggled through `json`. The per-leaf security bindings (record_link → table, member → group,
+file → workspace) are enforced at **every nesting depth**.
+
+### Validation at the execute boundary
+
+When the alias declares `inputs`, the server validates the payload before the workflow runs
+(a rejection resolves as `status: "error"` with per-field messages):
+
+- **Strict object** — a payload key not in the schema is rejected. Want forward-compatible
+  payloads? Declare a `json` input.
+- **Missing required input** — rejected. `required` defaults to true.
+- **Optional inputs and `""`** — a top-level optional input whose value is the empty string
+  is treated as *omitted* (HTML form controls emit `""` for "left blank"). Nested optional
+  object fields are plain-optional: omit the key. A required `text` input does accept `""` —
+  emptiness is not a type error; validate non-emptiness in the workflow body if it matters.
+- **Server-side reference bindings** — every `record_link` id must reference an existing
+  record in its declared `table_id`; every group-scoped `member` id must belong to the
+  declared group; every `file` id must live in the app's workspace. These are real write-time
+  constraints, not picker cosmetics — a hand-crafted request can't redirect the workflow.
+  Rationale and the full caller-boundary model: [security](./security.md).
+- **`select` accepts any well-formed option key at runtime**, not only the deploy-declared
+  `options`. **Limitation:** the declared options are frozen into the codegen literal union,
+  so an option added to the live field after deploy is valid at runtime but fails the
+  compile-time type. Populate pickers from `useFieldOptions` (the live option set — see
+  [members_and_options](./members_and_options.md)) and widen or redeploy the declaration when
+  the type gets in the way.
+
+If the alias declares **no** `inputs`, the payload passes through opaquely — no validation,
+no typing, no reference binding. Fine for a zero-input action; declare inputs for anything
+that carries data.
+
+### File inputs
+
+A `file` input is how an upload becomes data: the app uploads bytes first (`useFileUpload` /
+`useAttachments` — [files](./files.md)), then passes the returned id(s) to the workflow. An
+uploaded file is **inert** until a workflow attaches it to a record's `files` field.
+
+- Single `file` input → one file id; wrap in an array (`[id]`) when the body writes it to a
+  `files` field (files fields are always arrays).
+- `multi: true` → the body receives `ReadonlyArray<FileId>`, directly assignable to a `files`
+  field — the way to persist several attachments onto one record in one write.
+
+### Member inputs
+
+A `member` input is for genuine member *selection* (assign an order to a teammate) — never
+for actor identity, which the client can't be trusted to supply
+([security](./security.md) → `runtime.triggered_by_member_id`). Declaring one also unlocks
+the roster: `useMembers()` (and `useMembers({ group })` for a declared `group`) only works
+when the app declares a member-typed input somewhere — a workflow input or a query param —
+see [members_and_options](./members_and_options.md).
+
+### What the body sees
+
+Inside the workflow body, the payload is `trigger.app_workflow.inputs.<name>`, typed per the
+declaration (optional inputs may be absent). The triggering member is
+`runtime.triggered_by_member_id` (`null` for an anonymous public caller). An omitted optional
+input should mean "don't write that field" — guard each write:
+
+```js
+const i = trigger.app_workflow.inputs;
+if (i.title != null) {
+  await update_records({ table_id: "tbl_items", record_ids: [i.record_id], set: { fld_title: i.title } });
+}
+```
+
+## Refetch after a mutation
+
+Query hooks cache through SWR and know nothing about your workflows — a successful mutation
+does **not** invalidate any query. After a known mutation point, call the owning query hook's
+`refetch()`:
+
+```tsx
+const items = useQuery("items");
+const closeItem = useWorkflow("closeItem");
+
+const onClose = async (recordId: string) => {
+  const r = await closeItem({ record_id: recordId });
+  if (r.status === "error") { showError(r.message); return; }
+  items.refetch();
+};
+```
+
+`refetch` re-runs the query in the background while the current rows stay on screen (no
+flash to a spinner — `loading` stays false during revalidation). `usePaginatedQuery`'s
+`refetch` re-runs both the current page and the total count. Focus revalidation
+(`revalidateOnFocus`, default on) eventually self-corrects stale data, but never rely on it
+in place of an explicit refetch after a write the user is watching for.
+
+## Diff before update — send only what changed
+
+An edit form snapshots the record's values when it loads, and on save sends **only the fields
+the user actually changed** to its update workflow. Declare each updatable input
+`required: false`; an omitted input means "not written" (the body guards each write as shown
+above). "Changed" is decided at the edit surface that loaded the before-state — compare
+against the load-time snapshot, not against a re-fetch.
+
+Why a full-form snapshot save is a bug, not a style choice — three independent mechanisms:
+
+1. **Locks block touched fields regardless of value.** A locked record rejects a write the
+   moment *any* field is touched — there is no value-equality pass (deep equality over stored
+   shapes would be a silent lock bypass). A snapshot touches every field, so it turns every
+   save against a locked record into a total rejection even when nothing changed.
+2. **`before_update` table workflows fire on the write.** Tables can carry `before_update`
+   workflows (autofills, validations, side effects). They run on every write that touches the
+   record — a snapshot save fires them for fields the user never edited.
+3. **Snapshots clobber concurrent edits.** An update writes exactly the fields present in the
+   payload; unsent fields keep their current value. A diff therefore coexists with a
+   colleague's concurrent edit to a *different* field — a snapshot overwrites it with the
+   stale load-time value.
+
+```tsx
+// load: snapshot the editable fields from the row
+const initial = useMemo(() => ({
+  title: row.text(r.title),
+  status: readSelect(r.status)[0]?.key ?? "",
+}), [r]);
+
+// save: send only the diff
+const changes: Record<string, unknown> = {};
+if (draft.title !== initial.title) changes.title = draft.title;
+if (draft.status !== initial.status) changes.status = draft.status;
+if (Object.keys(changes).length === 0) return;         // nothing to save
+const result = await updateItem({ record_id, ...changes });
+```
+
+## Locked records
+
+A record can be locked (frozen) on the platform; direct writes to it are rejected and edits
+route through an approval flow.
+
+### Detecting the lock: `readLocked`
+
+Row-level query results carry a `__source_locked` addressing column automatically (alongside
+`__source_record_id` — no projection needed; like all source addressing it survives
+project/filter/sort/join but not grouping, where rows stop being records).
+`readLocked(row)` — pass the **whole row**, not a cell — returns `true` for a locked record,
+`false` when the flag is absent (`dist/src/row.d.ts`). Use it to render a locked state and to
+switch the save path.
+
+### What a write against a locked record does
+
+**Warning — the skip is silent at the workflow level.** When a workflow's `update_records`
+hits a locked record, the record's write is *skipped*, not failed: the tool returns the
+skipped records in its `blocked` output and the run otherwise proceeds — so the workflow
+resolves `status: "success"` while nothing was written, unless the body checks:
+
+```js
+const res = await update_records({ table_id: "tbl_orders", record_ids: [i.record_id], set: { fld_status: [i.status] } });
+if (res.blocked.length > 0) {
+  return({ status: "error", message: "This record is locked — submit a change request instead." });
+}
+return({ status: "success", message: "Updated." });
+```
+
+`update_records` has no bypass flag — a locked record's values change only through the
+approval flow below (or an admin explicitly unlocking the record first; `unlock_records` is
+admin-gated, so don't build an unlock→edit→relock workflow around the approval flow — the
+lock exists to route changes through review).
+
+### The change-request path: `request_locked_record_change`
+
+For a locked record, the save becomes one approval request carrying the **diffed** change set
+plus a reason. The workflow body calls the `request_locked_record_change` tool:
+
+```js
+// alias e.g. "requestOrderChange" — inputs: record_id (record_link), changes (json), reason (text)
+const i = trigger.app_workflow.inputs;
+const req = await request_locked_record_change({
+  table_id: "tbl_orders",
+  record_id: i.record_id,
+  changes: i.changes,          // { fld_key: new value } — the app-side diff
+  reason: i.reason,
+});
+return({ status: "success", message: "Change request submitted for approval.", data: { request_id: req.approval_request_id } });
+```
+
+Contract points:
+
+- **One request per record, covering the whole diff.** The `changes` map (`field_key` → new
+  value) is reviewed and applied **atomically** — the approver accepts or rejects the set as
+  a whole. Include every changed field in the same call; don't submit per-field requests.
+- **Nothing changes immediately.** The tool returns
+  `{ approval_request_id, status: "pending" }`; the record's values update only when an
+  approver (the table's configured approvers, else org admins) accepts. A `refetch()` right
+  after submitting shows the *old* values — render a "pending approval" state from the
+  result, don't poll for the new values.
+- **Requires a member actor.** The request is attributed to the triggering member; an
+  anonymous caller through a public app is rejected. Gate the affordance on a signed-in
+  viewer.
+
+App-side, the save handler branches on the lock:
+
+```tsx
+const save = async () => {
+  const changes = diff(initial, draft);              // field_key → new value, changed only
+  if (readLocked(r)) {
+    const res = await requestOrderChange({ record_id, changes, reason });
+    if (res.status === "success") showPending();
+  } else {
+    const res = await updateOrder({ record_id, ...changes });
+    if (res.status === "success") orders.refetch();
+  }
+};
+```
+
+## Optimistic reconciliation: `useOptimistic`
+
+For interactive data-bound views (calendar drag, gantt resize, kanban move) where waiting for
+the round-trip feels broken, `useOptimistic` overlays pending patches on the query result
+(`dist/src/use_optimistic.d.ts`):
+
+```ts
+const { items, patch } = useOptimistic(base, keyOf);
+patch(id, next, persist, opts?);
+```
+
+- `base` is the already-mapped item list (derived from `useQuery` rows); `keyOf` extracts each
+  item's stable key. `items` is `base` with pending patches merged per key (`{ ...item,
+  ...patch }`); repeated patches on the same key merge.
+- `patch(id, next, persist, { onSettled })` applies `next` immediately, then runs the
+  `persist` thunk. On **resolve**, the patch is *kept* (it should match the refetched value —
+  no flicker) and `onSettled` runs — pass the owning query's `refetch`. On **reject**, the
+  patch is *reverted*.
+
+**Warning — the persist thunk must throw on `status: "error"`.** `useWorkflow` resolves on
+failure (the failure model above), and a resolved promise means "kept" to `useOptimistic` —
+so a bare `() => reschedule({...})` thunk keeps the optimistic value on screen even when the
+workflow failed. Convert the status into a rejection:
+
+```tsx
+const q = useQuery("events");
+const reschedule = useWorkflow("rescheduleEvent");
+const { items, patch } = useOptimistic(mapped, (e) => e.id);
+
+const onEventDrop = (ev: CalendarEvent, newStart: Date) =>
+  patch(
+    ev.id,
+    { start: newStart },
+    async () => {
+      // toISODate: the `@lotics/ui` local-date formatter → "YYYY-MM-DD"
+      const r = await reschedule({ record_id: ev.recordId, new_date: toISODate(newStart) });
+      if (r.status === "error") throw new Error(r.message ?? "Reschedule failed");
+    },
+    { onSettled: q.refetch },
+  );
+```
+
+This is the full read → mutate → reconcile loop: `useQuery` reads, `row.*` coerces,
+`useWorkflow` mutates, `useOptimistic` bridges the gap until `refetch` converges. Declare
+one workflow per (table, field) you mutate — typed and narrow, never a generic
+`setField(any_field)` that hands the client write access to every field
+([security](./security.md)).