@lotics/app-sdk 0.16.0 → 0.17.0

package/dist/src/index.d.ts

@@ -20,8 +20,11 @@ export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
 export type { UploadedFile } 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";

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 { readSelect } from "./select.js";
 export { row } 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;

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;
 }

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.17.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {