@lotics/app-sdk 0.75.2 → 0.77.1

package/AGENTS.md

@@ -14,6 +14,7 @@ signature; open the file.**
 
 | Doc | Read it for |
 |---|---|
+| [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos for the actions whose mechanism is not guessable from the hooks — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. The templates a generated file is filled from are registered through the CLI, not the app — `lotics docs document_templates`. |
 | [docs/queries.md](./docs/queries.md) | **The query engine authoring reference** — AST node kinds, per-field-type operator support, filters/params/pruning, free-text search, combining tables (join/union/link/`unnest`/`record_id`), shaping (aggregates, date buckets, windows), runtime refinement bounds, limits & the efficiency playbook. |
 | [docs/data_fetching.md](./docs/data_fetching.md) | The three read hooks (`useQuery`/`useInfiniteQuery`/`usePaginatedQuery`), the `QueryRow` shape (projected columns `unknown`; `__source_record_id`/`__source_table_id` typed but optional), cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`), `useFieldOptions`, caching — **arrival revalidates** (a re-mount renders cache *and* refreshes it in the background, `loading` never flips) — data discipline, the pagination count as a second full execution (and `total` to suppress it), the search-as-you-type + record-picker patterns. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract, typed inputs, diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |

package/docs/ai.md

@@ -27,8 +27,8 @@ A declaration carries:
 | `model_tier` | Optional model tier — `haiku` \| `sonnet` \| `opus`. Omit (preferred) to follow the platform default tier, resolved at run time. A tier names capability, not a version, so the agent tracks model generations with no rewrite. Pin only a deliberate, tested choice |
 | `effort_level` | Optional reasoning depth for adaptive-thinking tiers. Requires an explicit `model_tier` pin — effort is tuned per tier |
 | `prefix_cache_ttl` | Optional prompt-cache window for the agent's stable prefix (tools + system). **Omit it** — the default (`"5m"`, Anthropic's own) is right for essentially every agent. `"1h"` is a leveraged bet: it doubles the write price (2x the input rate against 1.25x, both reading back at 0.1x) to buy only the five-minute-to-one-hour band, and an entry nothing re-reads inside the hour was paid for twice over. Declining it is never "uncached" — the same prefix stays cached at the default window. Set `"1h"` only with measured cadence showing runs reliably land in that band, such as a scheduled sweep |
-| `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it |
-| `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose) |
+| `inputs` | Optional typed input schema for one run — the same vocabulary as workflow inputs (`text`, `number`, `file`, `member`, `record_link`, `select`, …). The server validates every run payload against it. **Every field defaults to `required: true`**, exactly as `outputs` does — the two extend the same base — so an input the caller may legitimately omit needs `"required": false`, or the run is rejected before the agent sees it |
+| `outputs` | Optional typed output schema. Declared → **structured agent** (the run must emit a matching result); omitted → **free-text agent** (the answer is the final prose). **Every field defaults to `required: true`** (the same base schema as `inputs` above) — mark `"required": false` on anything the source may legitimately not carry. It matters most for `number`, which has no blank: text can answer `""`, but a required number leaves only a wrong value or a rejected submission, and an agent handed that dilemma spends the run resolving it instead of doing the rest of its instructions |
 
 **Structured vs free-text is the load-bearing split.** A structured agent's result arrives in `run.output` (the server strictly validates the submitted result against the declared schema — see the `output` typing section for the exact guarantee); a free-text agent's answer is the transcript's prose (`run.text`) and its `output` stays `undefined` — never a stray string, so a consumer reading `output.<field>` can't crash on a free-text answer.
 
@@ -358,12 +358,34 @@ gated per turn on `app:use` for the app in the member's workspace, and runs
 under the app's OWNER authority with `is_current_member` bound to the MEMBER
 (exactly as the app's own UI does).
 
-The agent is handed a **catalog** of those aliases — each one's params and its
-`description` (a query's own, [declared in the manifest](./queries.md); a
-workflow's, off its workflow row) — so it picks the right one instead of
-guessing an alias and learning the list from a refusal. Your descriptions are
-what it reads, on this surface and inside your own agents' runs. They enter the
-prompt as a capability listing, never as instructions.
+The agent is handed a **catalog** of those aliases — each one's `description`
+(a query's own, [declared in the manifest](./queries.md); a workflow's, off its
+workflow row) and its **complete input contract** — so it picks the right one
+and calls it correctly instead of guessing and learning from a refusal. Every
+alias you declare appears, however large the manifest, and every input appears
+with it:
+
+```
+workflows (run_app_workflow):
+- updateOrder(reference?: text, shipped_on?: date, owner?: member,
+    status?: select(In progress=opt_a1b2c3|Complete=opt_d4e5f6),
+    attachments?: file[], customer_id?: record_link(Customers)) — …
+```
+
+`?` marks an input the caller may omit, `[]` one that takes a list, a
+`select` spells out every legal value as `label=value` — **the agent sends the
+value** — and a `record_link` names the table an id must come from. This is the
+only place any of it is legible: both tools take an opaque
+inputs object, and a select's legal values are your DECLARATION's — usually an
+inline set that matches no table field — so an agent reading option values off
+the underlying table would send ones your write rejects.
+
+Two things follow for you as an author. **Your descriptions are what it reads**,
+on this surface and inside your own agents' runs — they enter the prompt as a
+capability listing, never as instructions. And **a `select` input's options are
+part of the contract the agent sees**, so prefer the `field: "fld_…"` form when
+the values come from a real field: it resolves to that field's CURRENT options
+at both render and validation time, and can never drift out of sync with them.
 
 **Writes carry a second gate that reads do not: `run_app_workflow` asks the
 member to approve every call from chat.** A wrong read is fixed by asking

package/docs/recipes.md

@@ -0,0 +1,190 @@
+# Recipes — the app actions that are not obvious
+
+The other area docs describe contracts. This one is task-shaped: **"how do I do X"**, for the
+handful of actions whose mechanism is not guessable from the hooks alone. Each was worked out
+against the running platform once — the point of writing them down is that nobody re-derives them.
+
+---
+
+## Generate a document and let the user download it
+
+A button that produces a file — a quotation, a debit note, a label — and hands it over, touching
+**no** record.
+
+**The mechanism is the return channel, and it is not the one you would guess.** Any workflow tool
+whose step output carries a `file_id` (`generate_pdf_from_template`, `generate_excel_from_template`,
+`generate_word_from_template`) is auto-collected by the execute endpoint and comes back in
+**`result.files[]`**, each with a servable `url`.
+
+So the workflow only *generates*. It does not `update_records` — attaching the file to a record is a
+separate, optional step. And you cannot hand the file back through `return({...})`; that channel is
+for values, not files.
+
+```js
+// workflow body — alias `genDebit`, input `record_id`
+const rid = trigger.app_workflow.inputs.record_id;
+const rec = await get_record({ table_id: "tbl_x", record_id: rid });
+await generate_excel_from_template({
+  data: { /* … */ }, filename: `Debit_${code}`, document_template_id: "dtl_x",
+});
+return({ status: "success", message: `Đã tạo ${code}` });   // the file is extracted, not returned
+```
+
+```tsx
+import { useWorkflow, openExternal } from "@lotics/app-sdk";
+
+const gen = useWorkflow("genDebit");
+const { files } = await gen({ record_id: rid });
+const url = files?.[0]?.url;
+if (url) await openExternal(url);
+```
+
+The `dtl_…` is a template you registered **once**, ahead of the app, through the CLI — see
+`lotics docs document_templates` for the five types and how each is created. An app fills
+templates; it never authors them.
+
+**`openExternal` is the download primitive, not `window.open`.** The app runs in a sandboxed iframe
+with no `allow-popups`, so a bare `window.open` is dropped — no error, no navigation, nothing to
+debug. `openExternal` routes the open through the host frame.
+
+## Return structured data from a workflow
+
+A workflow can hand back a computed total, a list of rows, a status object — read by the app as a
+typed `result.data`, validated server-side against the alias's `outputs`.
+
+**You usually declare nothing.** `outputs` are derived at save time from the inferred type of your
+`return({ data })`, and `lotics app workflow set` writes that derived schema back into the manifest
+and refreshes the types in place — so `result.data` is typed immediately, with no hand-copy and no
+second `codegen`. Declare an explicit `outputs` only to narrow beyond what is inferred; it is then
+authoritative and never overwritten.
+
+```js
+const rows = await query_records({ table_id: "tbl_x", filters: { /* … */ } });
+const items = rows.map((r) => ({ id: r["fld_id"], amount: r["fld_amount"] }));
+return({ status: "success", message: "ok", data: { total: items.length, items } });
+```
+
+```tsx
+const result = await summarize({ /* inputs */ });
+if (result.status === "success") {
+  result.data.total;            // number
+  result.data.items[0].amount;  // number
+}
+```
+
+A `data` expression the checker cannot pin down degrades to untyped `json`, so keep the shape
+literal enough to infer. Files still travel via `result.files`.
+
+## Look up one record by a code the user types
+
+Filter **server-side** so the app never receives another row. A full-table query loaded and filtered
+in JS ships every record to the client.
+
+```jsonc
+"lookupShipment": {
+  "ast": {
+    "kind": "from_table", "table_id": "tbl_x",
+    "filter": { "node_type": "condition", "field_key": "fld_code",
+                "operator": "equals", "value": "{{params.code}}" }
+  },
+  "params": { "code": { "type": "text", "required": true } }
+}
+```
+
+- `{{params.<name>}}` resolves **only in value positions**. A token in `table_id` or `field_key` is
+  not a real identifier and fails the deploy.
+- `useQuery("lookupShipment", { code })` is reactive on `code`. Gate on a *submitted* code — an
+  empty one matches nothing, so render a prompt rather than an empty table.
+- An **autonumber** field stores the composed string (`DL-2026-0006`), so `equals` / `contains`
+  filter it directly as text. No reverse mapping.
+
+**A code lookup carries no viewer identity, so it is an enumerable IDOR.** Fine for an internal or
+embedded app; never ship it as a public per-user portal — see `lotics docs security`.
+
+## Compose many optional filter axes in one query
+
+Filtering by several independent criteria in any combination does **not** need a query per
+combination. Declare each axis gated on a `required: false` param: the server prunes every condition
+whose `{{params.x}}` the caller did not pass, and collapses emptied groups to match-all.
+
+So `useQuery("search", { keyword })` filters by keyword alone, and `{}` returns everything. A
+missing *required* param still fails.
+
+Full pattern, including the date-param trick for range filters: `lotics docs queries` →
+"Composable optional filters".
+
+## Decode cells with the accessors, never by hand
+
+A query cell is `unknown` with a per-type serialized shape:
+
+- `row.opt` / `row.text` / `row.num` / `row.bool` / `row.date` — scalars and the first value of a
+  select. `row.date` keeps only the calendar day; use **`row.datetime`** when the time matters.
+- `readSelect` — the full `{ key, label }[]` of a multi-select.
+- `readMembers` — `select_member` cells.
+- `row.link` / `readLinks` — `select_record_link` → `{ id, display }`. Read `.display` to render,
+  `.id` to correlate or filter.
+
+A hand-rolled `firstOpt` / `linkDisplay` is the most common drift in app code: it re-implements the
+serialization contract and rots silently when that changes. A select cell is `[{key,label}]`, so a
+reader that grabs the wrong half is *plausible and wrong* rather than broken.
+
+**Project what you render.** A bare `{ kind: "from_table", table_id }` with no `project` ships every
+column of every row — including `files` fields and any cost or PII column the UI never shows.
+Projecting file fields also mass-presigns, which 500s on a large result and survives only on tiny
+tables.
+
+## Set the icon and colour
+
+Two **separate** layers; set both.
+
+**Launcher chrome** — `lotics run update_app '{"app_id":"…","icon":"truck","theme":{"color":"blue"}}'`.
+`icon` is any Lucide name (the full library, validated at write time — a wrong name is rejected, not
+silently boxed). Don't guess the kebab spelling:
+
+```
+lotics run search_app_icons '{"query":"shipping"}'   → ["truck","ship","package",…]
+```
+
+`theme.color` is a named palette colour: `red orange amber yellow lime green emerald teal cyan sky
+blue indigo violet purple fuchsia pink rose slate gray zinc neutral stone`. `null` clears either.
+There is no `lotics app icon` subcommand; a deploy warns while they are unset.
+
+**In-app palette** — the app's own `src/theme.ts`, exact hex. This is what the app *renders* with;
+the launcher colour does not feed it. Pick the named colour closest to your brand hex.
+
+## Test an AI action without spending credits
+
+An app's `useAgentRun` runs the **real** agent even under `lotics app dev` — the dev harness proxies
+to the production endpoint, so every dev click spends the app org's credits. The SDK's fixture mode
+(`?__mock=1`) covers `useQuery` only; it does not mock an agent run. Iterating on a review screen
+would re-bill on every reload.
+
+**Replay one captured run.** Capture a real `run.output` once, paste it as a constant, and gate on
+the same `?__mock=1` flag — so mocked rows and a mocked run activate together and dev is one
+consistent state.
+
+```tsx
+const MOCK = new URLSearchParams(window.location.search).get("__mock") === "1";
+const OUTPUT_FIXTURE = { /* …one real run's structured result… */ } as ReviewProposal;
+
+function Action({ input }: { input: AgentInput }) {
+  const agent = useAgentRun("proposeChanges");
+  const [proposal, setProposal] = useState<ReviewProposal>();
+
+  async function propose() {
+    if (MOCK) { setProposal(OUTPUT_FIXTURE); return; }   // no run, no credits
+    const output = await agent.run(input, { sessionId: mySessionKey });
+    if (agent.status === "error" || output === undefined) return;
+    setProposal(output);
+  }
+  return proposal ? <ChangeReview /* … */ /> : /* trigger propose */;
+}
+```
+
+Hold the proposal in local state rather than reading `agent.output`, since `run()` never fires in
+mock mode. Capture the fixture with
+`run(input, { sessionId }).then((o) => console.log(JSON.stringify(o)))`.
+
+**This is not a substitute for one real end-to-end run before shipping.** The fixture exercises the
+UI downstream of the model and nothing else — not the agent, not its tools, not the server-side
+validation of its output.

package/package.json

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