@lotics/app-sdk 0.44.0 → 0.46.0

package/AGENTS.md

@@ -112,6 +112,15 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
   **`openExternal(url)`** opens a link in a new tab (scheme-validated; host-mediated in the embed).
   **`downloadFile(name, data, mime?)`** saves browser-built bytes (a `Uint8Array | Blob | string`) —
   call it synchronously from the click that produced them.
+- **Chat handoff** — **`askAi({ prompt?, file_ids?, record_ids?, context? })`** opens the Lotics
+  messenger on a FRESH chat seeded with the given files (attached + previewed beside the chat),
+  records (the agent can read/act on them under the viewer's authority), a prefilled *editable*
+  prompt, and free-text grounding; the host stamps the app's identity automatically. Nothing runs
+  until the user presses send. **The razor**: outcome lands in *fields* → `useAgentRun` + a
+  review surface (the app's own structured commit path); outcome is a *file or an open-ended
+  answer* (edit this invoice, draft an email about this shipment) → `askAi`. Embedded-only —
+  rejects in standalone/dev. Name the task in `prompt` (Word/Excel bytes aren't inlined; a clear
+  brief makes the agent read the file first).
 
 ### Decoding query cells — never hand-roll the serialization contract
 
@@ -124,7 +133,12 @@ Pick by intent. (→ open the `.d.ts` for the exact signature.)
 - **`readSelect(cell)`** → `ResolvedOption[]` `{ key, label, color? }` (a cell carries key+label; the
   `color` is populated by `useFieldOptions`, not the cell). **`readMembers(cell)`** → `{ id, name,
   email? }[]`. **`readLinks(cell)` / `row.link`** → `{ id, display }`. **`readFiles(cell)`** →
-  `AppFile[]` with presigned `url` + `thumbnail_url` (24 h). **`readLocked(row)`** → `boolean` from the
+  `AppFile[]` with presigned `url` + `thumbnail_url` (24 h) **+ `size` (bytes) + `created_at` (ISO
+  date-added), resolved from the file object at read**. Surface size/date as **dedicated sortable
+  `Table` columns over the RAW numeric** — the `tpl_documents` document-register pattern (a `Size`
+  column `align:"right"` + an `Added` column, formatted only at display; NOT a crammed `FileRow` `meta`
+  string, which sorts wrong — "8.4 MB" < "96 KB"). `size` is absent for older files until backfilled —
+  render it only when present. **`readLocked(row)`** → `boolean` from the
   `__source_locked` addressing column.
 - **`project` only what you render** and `filter` server-side: a bare `from_table` ships every column
   — incl. `files` with storage keys — to the client (over-exposure + presign-500 at scale). A code

package/dist/src/ask_ai.d.ts

@@ -0,0 +1,40 @@
+export interface AskAiArgs {
+    /** Prefills the chat composer — the user sees, edits, and sends it
+     *  themselves. Nothing runs until they do. */
+    prompt?: string;
+    /** Files to attach to the chat (by id, from `readFiles(cell)`). The host
+     *  resolves each id itself and opens the file preview beside the chat. */
+    file_ids?: string[];
+    /** Records the chat should know about (ids from query rows). The host
+     *  resolves them to table context — the agent can then read and act on
+     *  them under the signed-in user's authority. */
+    record_ids?: string[];
+    /** Free-text grounding for the agent ("Shipment SGN-2481, customer …").
+     *  The host stamps the app's identity alongside it automatically. */
+    context?: string;
+}
+/**
+ * Hand off to the Lotics chat agent — opens the messenger on a FRESH chat
+ * seeded with the given files, records, and prompt.
+ *
+ * Use this for dialogue-shaped work: iterating on a document ("edit this
+ * invoice"), drafting from record context, open-ended questions. For
+ * structured judgment that commits back into the app's own data
+ * (extract/check/match/rank), use `useAgentRun` with a review surface
+ * instead — the outcome of `askAi` lands in chat, not in your workflows.
+ *
+ * The user stays in control: the prompt is only prefilled, attachments are
+ * visible in the composer, and nothing is sent until they press send.
+ *
+ * ```tsx
+ * import { askAi } from "@lotics/app-sdk";
+ * await askAi({
+ *   file_ids: [file.id],
+ *   record_ids: [row.id],
+ *   prompt: "Update the header of this invoice to match our letterhead.",
+ * });
+ * ```
+ *
+ * Only available embedded in Lotics — rejects in standalone/dev mode.
+ */
+export declare function askAi(args: AskAiArgs): Promise<void>;

package/dist/src/ask_ai.js

@@ -0,0 +1,35 @@
+import { rpc } from "./rpc.js";
+/**
+ * Hand off to the Lotics chat agent — opens the messenger on a FRESH chat
+ * seeded with the given files, records, and prompt.
+ *
+ * Use this for dialogue-shaped work: iterating on a document ("edit this
+ * invoice"), drafting from record context, open-ended questions. For
+ * structured judgment that commits back into the app's own data
+ * (extract/check/match/rank), use `useAgentRun` with a review surface
+ * instead — the outcome of `askAi` lands in chat, not in your workflows.
+ *
+ * The user stays in control: the prompt is only prefilled, attachments are
+ * visible in the composer, and nothing is sent until they press send.
+ *
+ * ```tsx
+ * import { askAi } from "@lotics/app-sdk";
+ * await askAi({
+ *   file_ids: [file.id],
+ *   record_ids: [row.id],
+ *   prompt: "Update the header of this invoice to match our letterhead.",
+ * });
+ * ```
+ *
+ * Only available embedded in Lotics — rejects in standalone/dev mode.
+ */
+export function askAi(args) {
+    const hasPayload = (args.prompt ?? "") !== "" ||
+        (args.file_ids?.length ?? 0) > 0 ||
+        (args.record_ids?.length ?? 0) > 0 ||
+        (args.context ?? "") !== "";
+    if (!hasPayload) {
+        return Promise.reject(new Error("askAi requires at least one of prompt, file_ids, record_ids, context"));
+    }
+    return rpc("askAi", args);
+}

package/dist/src/index.d.ts

@@ -26,6 +26,7 @@ export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "
 export { rpc, isEmbedded } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";
+export { askAi, type AskAiArgs } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";

package/dist/src/index.js

@@ -21,6 +21,7 @@ export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export { rpc, isEmbedded } from "./rpc.js";
 export { openExternal } from "./open_external.js";
+export { askAi } from "./ask_ai.js";
 export { downloadFile } from "./download.js";
 export { readMembers } from "./members.js";
 export { readSelect } from "./select.js";

package/dist/src/row.d.ts

@@ -68,6 +68,16 @@ export interface AppFile {
     url: string;
     /** Presigned thumbnail URL for images, when the server produced one. */
     thumbnail_url?: string;
+    /** Byte size of the file, resolved from the file object at serving time. Absent
+     *  for older files not yet backfilled — show a size only when present. Prefer a
+     *  dedicated sortable `Table` column over the RAW number (the `tpl_documents`
+     *  register: a right-aligned "Size" column, formatted at display) — not a crammed
+     *  `FileRow` meta string, which sorts wrong ("8.4 MB" < "96 KB"). */
+    size?: number | null;
+    /** ISO upload timestamp (date-added), resolved at serving time. Show as a
+     *  dedicated "Added" `Table` column (format with `formatDate`), sortable over the
+     *  raw ISO value. */
+    created_at?: string;
 }
 /**
  * files field → the attached files with their presigned `url` (empty if none).

package/dist/src/row.js

@@ -123,12 +123,16 @@ export function readFiles(v) {
         const filename = f.filename;
         const mime = f.mime_type;
         const thumb = f.thumbnail_url;
+        const size = f.size;
+        const created_at = f.created_at;
         out.push({
             id,
             filename: typeof filename === "string" ? filename : "",
             mime_type: typeof mime === "string" ? mime : "",
             url,
             thumbnail_url: typeof thumb === "string" ? thumb : undefined,
+            size: typeof size === "number" ? size : undefined,
+            created_at: typeof created_at === "string" ? created_at : undefined,
         });
     }
     return out;

package/dist/src/rpc.d.ts

@@ -19,7 +19,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /** Payload for starting a streaming agent run. */
 export interface AgentRunPayload {
     alias: string;

package/dist/src/rpc.js

@@ -427,6 +427,10 @@ function rpcStandalone(op, payload) {
             return standaloneContext();
         case "openExternal":
             return standaloneOpenExternal(payload);
+        case "askAi":
+            // The chat surface lives in the Lotics host — a standalone page has
+            // nowhere to hand off to.
+            return Promise.reject(new Error("askAi is only available when the app runs inside Lotics"));
         case "urlState.get":
             // Standalone is a top-level page — its own query string IS the store.
             return Promise.resolve(parseSearch(window.location.search));

package/package.json

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