@lotics/app-sdk 0.16.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,13 +17,17 @@
 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";
 export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";
+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

@@ -17,6 +17,8 @@
 export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
 export { rpc } from "./rpc.js";
+export { openExternal } from "./open_external.js";
 export { readMembers } from "./members.js";
-export { row } from "./row.js";
+export { readSelect } from "./select.js";
+export { row, readLinks } from "./row.js";
 export { useOptimistic } from "./use_optimistic.js";

package/dist/src/open_external.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Open an external URL in a new tab.
+ *
+ * The embedded app iframe is sandboxed without `allow-popups`, so a direct
+ * `window.open` from app code is silently dropped. This routes the open to
+ * whoever can actually perform it: the un-sandboxed host frame (embedded) or
+ * the app's own top-level page (public). The URL is scheme-validated
+ * (`http`/`https` only) at the point it opens — a non-string or disallowed
+ * scheme rejects.
+ *
+ * ```tsx
+ * import { openExternal } from "@lotics/app-sdk";
+ * await openExternal(invoiceUrl);
+ * ```
+ */
+export declare function openExternal(url: string): Promise<void>;

package/dist/src/open_external.js

@@ -0,0 +1,19 @@
+import { rpc } from "./rpc.js";
+/**
+ * Open an external URL in a new tab.
+ *
+ * The embedded app iframe is sandboxed without `allow-popups`, so a direct
+ * `window.open` from app code is silently dropped. This routes the open to
+ * whoever can actually perform it: the un-sandboxed host frame (embedded) or
+ * the app's own top-level page (public). The URL is scheme-validated
+ * (`http`/`https` only) at the point it opens — a non-string or disallowed
+ * scheme rejects.
+ *
+ * ```tsx
+ * import { openExternal } from "@lotics/app-sdk";
+ * await openExternal(invoiceUrl);
+ * ```
+ */
+export function openExternal(url) {
+    return rpc("openExternal", { url });
+}

package/dist/src/row.d.ts

@@ -1,15 +1,19 @@
 /**
  * Accessors that coerce raw `useQuery` row values into typed values. Each cell
- * of a query row is `unknown`: the query layer serializes a select column as its
- * `opt_` id (and, for some shapes, a single-element array or a `{ id }` object),
- * a date/datetime as a `YYYY-MM-DD[THH:mm…]` string, a number/boolean as itself.
+ * of a query row is `unknown`: the query layer serializes a select column as a
+ * `{ key, label }` array (one entry per selected option), a date/datetime as a
+ * `YYYY-MM-DD[THH:mm…]` string, a number/boolean as itself.
  *
  * These live in app-sdk — next to `useQuery`, whose serialization contract they
  * decode — so a change to that contract updates them in one place, and so apps
  * stop re-implementing the same coercions. They are pure (`unknown` in, value
  * out) and never throw.
  */
-/** Select → option id. Handles a bare id, a single-element array, or `{ id }`. */
+/**
+ * Select → first option key. Reads the enriched `{ key, label }` shape (and the
+ * legacy bare id / single-element array / `{ id }` shapes for back-compat).
+ * Use `readSelect` for the full `{ key, label }[]` on multi-select cells.
+ */
 declare function opt(v: unknown): string | null;
 /** Text/markdown/autonumber → string (numbers stringified; everything else ""). */
 declare function text(v: unknown): string;
@@ -24,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

@@ -1,23 +1,30 @@
 /**
  * Accessors that coerce raw `useQuery` row values into typed values. Each cell
- * of a query row is `unknown`: the query layer serializes a select column as its
- * `opt_` id (and, for some shapes, a single-element array or a `{ id }` object),
- * a date/datetime as a `YYYY-MM-DD[THH:mm…]` string, a number/boolean as itself.
+ * of a query row is `unknown`: the query layer serializes a select column as a
+ * `{ key, label }` array (one entry per selected option), a date/datetime as a
+ * `YYYY-MM-DD[THH:mm…]` string, a number/boolean as itself.
  *
  * These live in app-sdk — next to `useQuery`, whose serialization contract they
  * decode — so a change to that contract updates them in one place, and so apps
  * stop re-implementing the same coercions. They are pure (`unknown` in, value
  * out) and never throw.
  */
-/** Select → option id. Handles a bare id, a single-element array, or `{ id }`. */
+/**
+ * Select → first option key. Reads the enriched `{ key, label }` shape (and the
+ * legacy bare id / single-element array / `{ id }` shapes for back-compat).
+ * Use `readSelect` for the full `{ key, label }[]` on multi-select cells.
+ */
 function opt(v) {
     if (typeof v === "string")
         return v || null;
     if (Array.isArray(v))
         return v.length ? opt(v[0]) : null;
     if (v && typeof v === "object") {
+        const key = v.key;
+        if (typeof key === "string")
+            return key || null;
         const id = v.id;
-        return typeof id === "string" ? id : null;
+        return typeof id === "string" ? id || null : null;
     }
     return null;
 }
@@ -53,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/dist/src/rpc.d.ts

@@ -18,7 +18,7 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "workflow" | "upload" | "context";
+export type RpcOp = "query" | "workflow" | "upload" | "context" | "openExternal";
 /**
  * The app's identity, resolved once at startup to tag PostHog events.
  * Assembled by whichever transport is active:

package/dist/src/rpc.js

@@ -219,8 +219,31 @@ function rpcStandalone(op, payload) {
             return standaloneUpload(payload.file);
         case "context":
             return standaloneContext();
+        case "openExternal":
+            return standaloneOpenExternal(payload);
     }
 }
+/**
+ * Open an external URL in a new tab, scheme-validated. In standalone mode the
+ * app is a normal top-level page (`<slug>.lotics.app`), so `window.open` is not
+ * sandbox-blocked — open directly. (Bridged apps route this op to the host,
+ * which opens it in the un-sandboxed parent frame; see `app_iframe_host`.)
+ * The scheme is re-validated wherever the open actually happens — never trust a
+ * URL handed across the bridge.
+ */
+function openValidatedUrl(url) {
+    if (typeof url !== "string")
+        throw new Error("openExternal requires a url string");
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new Error(`openExternal: unsupported URL scheme "${parsed.protocol}"`);
+    }
+    window.open(parsed.href, "_blank", "noopener,noreferrer");
+}
+// `async` so a synchronous validation throw surfaces as a rejected Promise.
+async function standaloneOpenExternal(p) {
+    openValidatedUrl(p.url);
+}
 async function standaloneContext() {
     const info = await resolveAppInfo();
     return {

package/dist/src/select.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reader for `select` cells in `useQuery` rows.
+ *
+ * The server (`backend/lib/select_option_resolver.ts`) rewrites every
+ * `select` column from its storage shape (`string[]` of bare `opt_*` keys)
+ * into `ResolvedOption[]` before the row reaches the app. Apps used to
+ * hardcode an `opt_* → label` map because the SDK didn't expose the resolved
+ * shape; this helper makes the right shape the obvious one.
+ *
+ * If the wire format changes, the resolver and this reader move together.
+ */
+export interface ResolvedOption {
+    key: string;
+    /** Option display name. Falls back to the key when the option was deleted
+     *  after the cell was written — surfaces the stale state explicitly. */
+    label: string;
+}
+/**
+ * Parse a `useQuery` cell value into `ResolvedOption[]`. Returns `[]` for
+ * null/undefined/empty cells and for any unexpected shape — callers iterate
+ * uniformly without null-checks. A bare-string entry (a column whose source
+ * options couldn't be resolved server-side) becomes `{ key, label: key }` so
+ * single-value reads still work. Entries that fail the shape check are
+ * dropped silently rather than corrupting the array with partial data.
+ */
+export declare function readSelect(value: unknown): ResolvedOption[];

package/dist/src/select.js

@@ -0,0 +1,40 @@
+/**
+ * Reader for `select` cells in `useQuery` rows.
+ *
+ * The server (`backend/lib/select_option_resolver.ts`) rewrites every
+ * `select` column from its storage shape (`string[]` of bare `opt_*` keys)
+ * into `ResolvedOption[]` before the row reaches the app. Apps used to
+ * hardcode an `opt_* → label` map because the SDK didn't expose the resolved
+ * shape; this helper makes the right shape the obvious one.
+ *
+ * If the wire format changes, the resolver and this reader move together.
+ */
+/**
+ * Parse a `useQuery` cell value into `ResolvedOption[]`. Returns `[]` for
+ * null/undefined/empty cells and for any unexpected shape — callers iterate
+ * uniformly without null-checks. A bare-string entry (a column whose source
+ * options couldn't be resolved server-side) becomes `{ key, label: key }` so
+ * single-value reads still work. Entries that fail the shape check are
+ * dropped silently rather than corrupting the array with partial data.
+ */
+export function readSelect(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const entry of value) {
+        if (typeof entry === "string") {
+            if (entry !== "")
+                out.push({ key: entry, label: entry });
+            continue;
+        }
+        if (!entry || typeof entry !== "object")
+            continue;
+        const obj = entry;
+        const key = obj.key;
+        if (typeof key !== "string" || key === "")
+            continue;
+        const label = typeof obj.label === "string" ? obj.label : key;
+        out.push({ key, label });
+    }
+    return out;
+}

package/package.json

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