@lotics/app-sdk 0.17.0 → 0.18.0

package/dist/src/hooks.d.ts

@@ -25,9 +25,9 @@ interface QueryState<R> {
  * alias → input-type map. Result:
  *   - Undeclared alias → compile-time error at the `useWorkflow("...")` site
  *   - Declared with full `{workflow_id, inputs}` form → callable typed as
- *     `(inputs: <DeclaredShape>) => Promise<unknown>`
+ *     `(inputs: <DeclaredShape>) => Promise<WorkflowResult>`
  *   - Declared with shorthand (bare workflow_id) → callable typed as
- *     `(inputs?: Record<string, unknown>) => Promise<unknown>` (untyped)
+ *     `(inputs?: Record<string, unknown>) => Promise<WorkflowResult>` (untyped inputs)
  *
  * ```tsx
  * const issue = useWorkflow("issueInvoiceStorageDrop");
@@ -35,8 +35,19 @@ interface QueryState<R> {
  * ```
  */
 export declare function useWorkflow<K extends keyof AppWorkflows & string>(alias: K): UseWorkflowFn<K>;
-export declare function useWorkflow(alias: string): (inputs?: Record<string, unknown>) => Promise<unknown>;
-type UseWorkflowFn<K extends keyof AppWorkflows & string> = AppWorkflows[K] extends Record<string, unknown> ? AppWorkflows[K] extends Record<string, never> ? (inputs?: Record<string, never>) => Promise<unknown> : (inputs: AppWorkflows[K]) => Promise<unknown> : (inputs?: Record<string, unknown>) => Promise<unknown>;
+export declare function useWorkflow(alias: string): (inputs?: Record<string, unknown>) => Promise<WorkflowResult>;
+type UseWorkflowFn<K extends keyof AppWorkflows & string> = AppWorkflows[K] extends Record<string, unknown> ? AppWorkflows[K] extends Record<string, never> ? (inputs?: Record<string, never>) => Promise<WorkflowResult> : (inputs: AppWorkflows[K]) => Promise<WorkflowResult> : (inputs?: Record<string, unknown>) => Promise<WorkflowResult>;
+/**
+ * Result of an app-workflow run — the execute endpoint's response. `files` holds
+ * any document a workflow step generated (e.g. via a `generate_*_from_template`
+ * tool), resolved for download: read `files[0].url` and pass it to `openExternal`.
+ * A workflow that generates no file resolves with `files` absent.
+ */
+export interface WorkflowResult {
+    status: "success" | "error";
+    message?: string;
+    files?: UploadedFile[];
+}
 type UseQueryParams<K extends keyof AppQueries & string> = AppQueries[K] extends Record<string, never> ? [params?: Record<string, never>] : [params: AppQueries[K]];
 /**
  * Read rows from a query the app's author declared in `lotics.queries`.

package/dist/src/index.d.ts

@@ -17,7 +17,7 @@
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
-export type { UploadedFile } from "./hooks.js";
+export type { UploadedFile, WorkflowResult } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export type { RpcOp } from "./rpc.js";
 export { openExternal } from "./open_external.js";
@@ -27,6 +27,7 @@ export { readSelect } from "./select.js";
 export type { ResolvedOption } from "./select.js";
 export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";
-export { row } from "./row.js";
+export { row, readLinks } from "./row.js";
+export type { ResolvedLink } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";
 export type { OptimisticApi } from "./use_optimistic.js";

package/dist/src/index.js

@@ -20,5 +20,5 @@ export { rpc } from "./rpc.js";
 export { openExternal } from "./open_external.js";
 export { readMembers } from "./members.js";
 export { readSelect } from "./select.js";
-export { row } from "./row.js";
+export { row, readLinks } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";

package/dist/src/row.d.ts

@@ -28,11 +28,28 @@ declare function bool(v: unknown): boolean;
  * fields are not handled here — they have no consumer yet.)
  */
 declare function date(v: unknown): Date | null;
+/** A linked record cell entry — the target record's id + its display text. */
+export interface ResolvedLink {
+    /** The linked record's id (e.g. "rec_…"). Use to correlate/filter. */
+    id: string;
+    /** The linked record's display text (its primary-field value). Use to render. */
+    display: string;
+}
+/**
+ * select_record_link → the FIRST linked record as `{ id, display }` (or null).
+ * The common single-link case: read `.display` to render the linked record's
+ * name, `.id` to correlate/filter (e.g. group rows by a parent record). Use
+ * `readLinks` for the full list on multi-link fields.
+ */
+declare function link(v: unknown): ResolvedLink | null;
+/** select_record_link → ALL linked records as `{ id, display }[]` (empty if none). */
+export declare function readLinks(v: unknown): ResolvedLink[];
 export declare const row: {
     opt: typeof opt;
     text: typeof text;
     num: typeof num;
     bool: typeof bool;
     date: typeof date;
+    link: typeof link;
 };
 export {};

package/dist/src/row.js

@@ -60,4 +60,33 @@ function date(v) {
     const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(text(v));
     return m ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3])) : null;
 }
-export const row = { opt, text, num, bool, date };
+/** One `{ id, display }` object → ResolvedLink, or null if absent/malformed. */
+function asLink(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const id = v.id;
+    if (typeof id !== "string" || !id)
+        return null;
+    const display = v.display;
+    return { id, display: typeof display === "string" ? display : "" };
+}
+/**
+ * select_record_link → the FIRST linked record as `{ id, display }` (or null).
+ * The common single-link case: read `.display` to render the linked record's
+ * name, `.id` to correlate/filter (e.g. group rows by a parent record). Use
+ * `readLinks` for the full list on multi-link fields.
+ */
+function link(v) {
+    if (Array.isArray(v))
+        return v.length ? asLink(v[0]) : null;
+    return asLink(v);
+}
+/** select_record_link → ALL linked records as `{ id, display }[]` (empty if none). */
+export function readLinks(v) {
+    if (!Array.isArray(v)) {
+        const one = asLink(v);
+        return one ? [one] : [];
+    }
+    return v.map(asLink).filter((x) => x !== null);
+}
+export const row = { opt, text, num, bool, date, link };

package/package.json

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