@lotics/app-sdk 0.122.9 → 0.123.0

package/dist/index.js

@@ -516,7 +516,7 @@ import { useCallback as useCallback2, useEffect as useEffect2, useRef, useSyncEx
 var slots = /* @__PURE__ */ new Map();
 var clock = 0;
 var nextStaging = 1;
-var FOCUS_THROTTLE_MS = 5e3;
+var FOCUS_THROTTLE_MS = 6e4;
 var PAINT_CAP_MS = 1e3;
 function draw(paint) {
   if (paint.drawn) return;
@@ -32762,7 +32762,7 @@ async function queryAll(alias, params = {}, opts = {}) {
 async function exportQuery(alias, call) {
   const sort = call.sort === void 0 || call.sort.length === 0 ? void 0 : [...call.sort];
   const tabs = call.tabs?.map((tab) => ({ ...tab, sort: tab.sort === void 0 || tab.sort.length === 0 ? void 0 : [...tab.sort] }));
-  const body = { alias, params: call.params ?? {}, filter: call.filter, sort, ...tabs === void 0 ? {} : { tabs }, report: call.report, file: call.file };
+  const body = { alias, params: call.params ?? {}, filter: call.filter, sort, ...tabs === void 0 ? {} : { tabs }, report: call.report, file: call.file, ...call.labels === void 0 ? {} : { labels: call.labels } };
   const mocked = getMockExport(alias);
   if (mocked !== null) return mocked(body);
   return (await rpc("export", body)).file;

package/dist/queries.d.ts

@@ -3,7 +3,7 @@ import type { AppQueries, AppQueryColumns } from "./types.js";
 import type { ResolvedOption } from "./select.js";
 import type { ReportLanguage } from "./shared_types.js";
 import type { ExportedFile } from "./shared_types.js";
-import type { ReportColumn, ReportReading } from "./shared_types.js";
+import type { ReportColumn, ReportLabels, ReportReading } from "./shared_types.js";
 /**
  * One row of a query whose columns codegen could not read (a dynamic alias, a
  * bare `from_table`). Values stay `unknown` — the cell readers narrow them.
@@ -249,6 +249,9 @@ export interface ExportCall {
     tabs?: readonly ExportTab[];
     report: ExportReport;
     file: ExportFile;
+    /** The words each option key of a select column prints as, by the column, in either file: a cell the server names
+     *  by its field's option prints as that. */
+    labels?: ReportLabels;
 }
 /**
  * Every row a declared query matches — narrowed by `filter` and ordered by `sort` as a page of it is — made into one

package/dist/shared_types.d.ts

@@ -35,9 +35,12 @@ export type ReportColumn = {
   header: string;
   /** A `date` cell is an ISO day or moment. */
   type: "number" | "date" | "text";
-  /** A select whose cells hold bare option keys, no field of the query naming them: the words each key prints as. */
-  labels?: { readonly [x: string]: string; };
 };
+/**
+ * The words each option key of a select column prints as, by the column: a cell no field of the query names arrives
+ * as its bare key.
+ */
+export type ReportLabels = { readonly [x: string]: Readonly<Record<string, string>>; };
 export type ReportLanguage = "vi" | "en";
 export type ReportPart = {
   label: string;

package/dist/store.d.ts

@@ -1,5 +1,11 @@
 /** How a key is read: from when the request was sent and the answer it holds now (a feed grows from it). */
 export type Fetcher<T> = (askedAt: number, current: T | undefined) => Promise<T>;
+/**
+ * A focus or reconnect within this long of a key's last ask asks nothing: returns to the tab a minute apart are one
+ * visit. A push asks at once whatever this says, so what this bounds is only what no push carries — a dead channel, a
+ * value the clock moves.
+ */
+export declare const FOCUS_THROTTLE_MS = 60000;
 /** The read clock: every request stamps when it was sent, so an answer is known to carry what settled before it. */
 export declare function tick(): number;
 /** Ask again every key reading one of `aliases` — every query key where none is named; an unmounted one on its next mount. */

package/docs/data_fetching.md

@@ -24,7 +24,7 @@ untyped. It is written from the app's live bindings by `lotics app create --cust
 | `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` or `total: { where: { name: filter } }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
 | `useQueries(calls, opts?)` | one state per `{ alias, params?, filter?, sort?, aggregate?, total?, rows? }`, in order — a `sort` orders that call's rows before the cap cuts them | reads that are DATA — a list known only at render, one read per item, or one count per stage (`rows: false, total: true`, each state's `.total`); the deploy's alias scan reads a list as dynamic, so every alias in it is still declared. With `aggregate` a call answers the groups of its filtered rows instead of the rows ([queries](./queries.md)) |
 | `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set in the browser (the ids an act runs on): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
-| `exportQuery(alias, { params, filter, sort, tabs?, report, file })` | a promise of an `ExportedFile`: `{ filename, mime_type, url, size, created_at }` | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type, labels? }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; `labels` the words each bare option key of a `select` column no field names prints as, refused on any other column and for a key it lacks; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file has no `id` — it is a download, not a workspace file a workflow or a field takes: its `url` is signed for the caller for at most an hour, so open it with `openExternal` when the promise resolves; the server deletes the file a day after it is made |
+| `exportQuery(alias, { params, filter, sort, tabs?, report, file, labels? })` | a promise of an `ExportedFile`: `{ filename, mime_type, url, size, created_at }` | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). `labels`, by `select` output column, the words each option key prints as in either file — a cell no field of the query names (a union's literal column) arrives as its bare key; a cell its field's option names prints as that, a key the map lacks as itself, and a column no select of the query holds as it is. Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file has no `id` — it is a download, not a workspace file a workflow or a field takes: its `url` is signed for the caller for at most an hour, so download it with `downloadFileFromUrl(url, filename)` (`@lotics/ui/download`) when the promise resolves — a tab `openExternal` opens seconds after the click is a pop-up the browser blocks; the server deletes the file a day after it is made |
 
 Every hook answers the same `QueryState`: `rows`, `truncated`, `total`, `counts`, `loading`,
 `isValidating`, `answeredAt`, `error`, `pending`, `refetch`, `page`, `setPage`, `pageCount`, `hasMore`,
@@ -146,7 +146,7 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
   renders the cached rows instantly *and* re-reads them in the background, so a list reflects what
   another screen changed while you were away. Identical concurrent reads share one request, and reads asked within a few milliseconds of each other go to the server together, each answered or refused on its own.
   Freshness comes from four places — arrival, window focus / tab return / network reconnect
-  (`revalidateOnFocus`, default on; a read asked within the last few seconds is not asked again,
+  (`revalidateOnFocus`, default on; a read asked within the last minute is not asked again,
   and the reads it asks again re-render together, as a push's do — so what changed while the tab
   was hidden or offline lands in one piece), a **realtime push**, and **this app's own successful
   write**, which re-reads the mounted queries over the tables its body names without being asked

package/docs/files.md

@@ -247,7 +247,7 @@ Decode with `readFiles(cell)` → `AppFile[]` (`dist/row.d.ts`):
 | `id` | `string` | The stored file id |
 | `filename` | `string` | Original filename (post-optimization name for converted images) |
 | `mime_type` | `string` | |
-| `url` | `string` | Presigned serving URL — render, or pass to `openExternal` |
+| `url` | `string` | Presigned serving URL — render it, or download it with `downloadFileFromUrl` |
 | `thumbnail_url` | `string?` | Presigned image thumbnail (see the 404 note below) |
 | `size` | `number?` | Byte size — **absent on older files not yet backfilled**; render only when present |
 | `created_at` | `string?` | ISO upload timestamp |
@@ -320,22 +320,25 @@ dedupes them, and returns them on the execute response as `WorkflowResult.files?
 with `files` absent.
 
 ```tsx
+import { downloadFileFromUrl } from "@lotics/ui/download";
+
 const generate = useWorkflow("generateInvoice");
 // `__source_record_id` is `null` on a grouped row — so narrow it rather than
 // handing the workflow no id where it declares a record.
 if (!row.__source_record_id) return;
 const result = await generate({ record_id: row.__source_record_id });
-if (result.status === "success" && result.files?.length) {
-  await openExternal(result.files[0].url);
-}
+const [file] = result.status === "success" ? (result.files ?? []) : [];
+if (file?.url) await downloadFileFromUrl(file.url, file.filename);
 ```
 
 - **Don't hand back a `url` or `file_id` via `return({ data })`** — extraction is automatic, and
   the extracted entry is presigned while a hand-returned id is not.
 - The presigned URLs work for **anonymous public-app viewers** — a public visitor can download a
   document the workflow generated for them.
-- Open one with `openExternal(url)`, never `window.open`; bytes the app builds *in the browser*
-  leave through `downloadFile` — both [runtime](./runtime.md).
+- Download one with `downloadFileFromUrl(url, filename)` (`@lotics/ui/download`): it fetches the
+  presigned URL and saves it, and the iframe allows downloads. A tab `openExternal` opens once the
+  run answers is a pop-up the browser blocks. Bytes the app builds *in the browser* leave through
+  `downloadFile` ([runtime](./runtime.md)).
 
 ### Naming what goes into a zip
 

package/docs/members_and_options.md

@@ -428,8 +428,9 @@ const { reverted, kept } = await undoRecordChange("job", recordId, entry.id);
   before is in neither. The write is the viewer's own save: they hold `write_data` on the table as
   the call arrives, on a row their own row rule covers, and the record's lock, the table's checks
   and its write rules answer as for any save of theirs. `undoable` is `false`, and the call
-  refused, for the entry that made the record, an entry that is an undo, one already put back, and
-  a viewer who may not write the record; a record in the trash is refused until it is restored.
+  refused, for the entry that made the record, an entry that is an undo, one already put back, a
+  viewer who may not write the record, and a JSON app that saves no record of the entity (an undo is
+  a save); a record in the trash is refused until it is restored.
   The undo is an entry of its own; the answer arrives once the record's reads are read anew.
 - **Pages**: newest first, about thirty entries each; `next` is where the trail goes on —
   `undefined` at its end. A page may hold fewer entries and still say `next` where the trail it read

package/docs/mutations.md

@@ -142,13 +142,15 @@ Any step in the run whose tool output carries a `file_id` (most commonly
 `generate_document`) 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:
+app downloads directly — a tab opened once the run answers is a pop-up the browser blocks:
 
 ```tsx
+import { downloadFileFromUrl } from "@lotics/ui/download";
+
 const gen = useWorkflow("generateInvoice");
 const { status, files } = await gen({ order_id });
-const url = files?.[0]?.url;
-if (status === "success" && url) await openExternal(url);
+const file = files?.[0];
+if (status === "success" && file?.url) await downloadFileFromUrl(file.url, file.filename);
 ```
 
 The same run reached through the `run_app_workflow` tool — from chat, from MCP, from an app

package/docs/recipes.md

@@ -28,19 +28,21 @@ return({ status: "success", message: `Đã tạo ${code}` });   // the file is e
 ```
 
 ```tsx
-import { useWorkflow, openExternal } from "@lotics/app-sdk";
+import { useWorkflow } from "@lotics/app-sdk";
+import { downloadFileFromUrl } from "@lotics/ui/download";
 
 const gen = useWorkflow("genDebit");
 const { files } = await gen({ record_id: rid });
-const url = files?.[0]?.url;
-if (url) await openExternal(url);
+const file = files?.[0];
+if (file?.url) await downloadFileFromUrl(file.url, file.filename);
 ```
 
 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`**, which the sandbox drops silently
+**A generated file downloads with `downloadFileFromUrl`, never a tab.** The sandbox drops `window.open`
+silently, and a tab `openExternal` opens seconds after the click is a pop-up the browser blocks
 ([runtime](./runtime.md)).
 
 ## Return structured data from a workflow

package/docs/runtime.md

@@ -293,7 +293,7 @@ nobody stated.
 
 ```tsx
 import { openExternal } from "@lotics/app-sdk";
-await openExternal(result.files[0].url);
+await openExternal(invoiceUrl);
 ```
 
 `openExternal(url: string): Promise<void>` (`dist/open_external.d.ts`). The
@@ -376,7 +376,7 @@ function onExportClick() {
 string): void` (`dist/download.d.ts`) saves bytes the app generated **in the
 browser** (an exported .xlsx, a CSV, generated text) to the visitor's device.
 It is the client-side counterpart to the server path (workflow generates a file
-→ `WorkflowResult.files[].url` → `openExternal`).
+→ `WorkflowResult.files[].url` → `downloadFileFromUrl` from `@lotics/ui/download`).
 
 - **Pure DOM, no RPC.** The embed sandbox includes `allow-downloads`, so a
   same-origin blob download triggered from a user gesture needs no host

package/docs/security.md

@@ -103,7 +103,7 @@ A publicly-shared app (its own origin, or its public link) is reachable by **any
 | Agent runs (`useAgentRun`) | **No** — rejected: agent runs require an authenticated member, and each member's run history is private to them (a guessed session id cannot read another member's thread) |
 | Comments (`useComments`) | **No** — members-only |
 | Record activity (`useRecordActivity`) | **No** — the app's organization's members only |
-| Undo of a record's change (`undoRecordChange`) | **No** — a member of the app's organization holding `write_data` on the record's table, on a row their own row rule covers |
+| Undo of a record's change (`undoRecordChange`) | **No** — a member of the app's organization holding `write_data` on the record's table, on a row their own row rule covers, in an app that saves records of that entity |
 | Member roster (`useMembers`) | **No** — same-org members only (below) |
 
 **Warning — `is_current_member` on a public app resolves to the app owner.** An anonymous request has no viewer to bind, so both `is_current_member` and `current_member in_any_group` fall back to the owner's identity and the owner's groups. A "my items" query shows every anonymous visitor the *owner's* items, and a manager-only read template gated on a group the owner belongs to **passes for every anonymous visitor**. Never rely on viewer-bound predicates in a public app.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.122.9",
+  "version": "0.123.0",
   "description": "The SDK a Lotics custom-code app reads and writes through — typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {