@lotics/app-sdk 0.15.0 → 0.17.0

package/dist/src/analytics.d.ts

@@ -1 +1,7 @@
+/**
+ * Capture an app event. Buffers until PostHog is ready, then emits directly;
+ * no-ops permanently once tracking is known to be off, so the hooks can call it
+ * unconditionally.
+ */
+export declare function captureAppEvent(event: string, props?: Record<string, unknown>): void;
 export declare function bootstrapAnalytics(): Promise<void>;

package/dist/src/analytics.js

@@ -1,75 +1,128 @@
 /**
  * PostHog analytics for custom-code apps.
  *
- * Apps run as a separate cross-origin bundle at `<slug>.lotics.app`, so the
- * product's PostHog instance (on `app.lotics.ai`) can't see them — every app
- * was previously dark. `bootstrapAnalytics` runs once from `mount()` and gives
- * every app tracking for free, with no per-app wiring: PostHog **autocapture**
- * (clicks, pageview, pageleave) records the user actions, plus exception
- * capture for error visibility. Every event is tagged with app identity so it's
- * attributable per app/workspace/org and rolls up under the existing
- * `organization` group; embedded apps `identify` the authenticated member the
- * host passes down, so app + product events share one person. See `rpc.ts`
- * `AppContext` for how identity is resolved per transport.
+ * Apps are a separate cross-origin bundle at `<slug>.lotics.app`, invisible to
+ * the product's PostHog — so `mount()` boots a PostHog instance per app.
  *
- * Autocapture is the only event source. RPC/data lifecycle (query / workflow /
- * upload) is a system signal, not a user action — and the interaction that
- * triggers each is already autocaptured — so the SDK emits no custom events.
+ * **Why explicit events, not autocapture:** the Lotics PostHog project runs
+ * with autocapture OFF (the product captures explicit events, not DOM
+ * autocapture), and that project setting overrides any client `autocapture`
+ * flag — so apps can't rely on autocapture. The SDK instead emits explicit
+ * events for genuine user actions: `app_opened`, plus `app_workflow_run` /
+ * `app_file_uploaded` from the hooks. Data-read mechanics (a `useQuery`
+ * refetch) are a system signal, not a user action, and are deliberately not
+ * events.
  *
- * Best-effort: any failure (offline, an un-updated host that doesn't know the
- * `context` op, tracking disabled for the environment) leaves the app fully
- * functional and silently untracked.
+ * Every event is tagged with app identity and rolls up under the existing
+ * `organization` group; embedded apps `identify` the member the host passes
+ * down so app + product events share one person. Exception capture is on (the
+ * project opts in); session replay is off (on by default project-wide, but
+ * apps — including anonymous public visitors — were never scoped for it).
+ *
+ * The key is the public, write-only project key (already shipped in every
+ * browser), hardcoded here. Tracking is gated to the deployed app host
+ * (`*.lotics.app`); `lotics app dev` runs on localhost and stays untracked.
+ * Best-effort: any failure leaves the app fully functional and untracked.
  */
 import posthog from "posthog-js";
 import { rpc } from "./rpc.js";
 import { hasMockFlag } from "./mock.js";
+const POSTHOG_KEY = "phc_N1nyqSRdo9XMK3DODxrxX2Y9jG3dppybruOuMznbz62";
+const POSTHOG_HOST = "https://us.i.posthog.com";
+const APP_HOST_SUFFIX = ".lotics.app";
+let loaded = false;
+let disabled = false;
+/**
+ * Events fired before init completes (a hook can settle during the `context`
+ * round-trip). Drained on init; capped so a never-initializing session can't
+ * grow it unbounded.
+ */
+const preInitQueue = [];
+const MAX_QUEUE = 100;
+function disable() {
+    disabled = true;
+    preInitQueue.length = 0;
+}
+/**
+ * Capture an app event. Buffers until PostHog is ready, then emits directly;
+ * no-ops permanently once tracking is known to be off, so the hooks can call it
+ * unconditionally.
+ */
+export function captureAppEvent(event, props) {
+    if (disabled)
+        return;
+    if (loaded) {
+        posthog.capture(event, props);
+        return;
+    }
+    if (preInitQueue.length < MAX_QUEUE)
+        preInitQueue.push({ event, props });
+}
+function onDeployedAppHost() {
+    try {
+        return window.location.hostname.endsWith(APP_HOST_SUFFIX);
+    }
+    catch {
+        return false;
+    }
+}
 export async function bootstrapAnalytics() {
-    // A design-time / screenshot load (?__mock=1) is never real usage.
-    if (hasMockFlag())
+    // Only the deployed app host tracks: a design-time/screenshot load
+    // (?__mock=1) and `lotics app dev` (localhost) emit nothing. This replaces
+    // the old "no key off-prod" gate now that the key is hardcoded.
+    if (hasMockFlag() || !onDeployedAppHost()) {
+        disable();
         return;
+    }
     let ctx;
     try {
         ctx = await rpc("context", {});
     }
     catch {
-        // Best-effort: a context-resolution failure (offline, an un-updated host
-        // that doesn't know the op) must never break the app.
+        // Best-effort: a context-resolution failure must never break the app.
+        disable();
         return;
     }
-    // No key → tracking disabled for this environment (dev/preview/test, or a
-    // host running in a non-production build). Mirrors the frontend's prod gate.
-    if (!ctx.posthog_key)
-        return;
-    posthog.init(ctx.posthog_key, {
-        api_host: ctx.posthog_host,
-        autocapture: true,
-        capture_pageview: true,
-        capture_pageleave: true,
-        // Error tracking for the app: this is the app bundle's only exception
-        // channel (mount() renders a local banner but never posts), and we run
-        // customer apps — their crashes are ours to see.
+    posthog.init(POSTHOG_KEY, {
+        // Pin the modern posthog-js init contract (the product uses the same).
+        defaults: "2025-05-24",
+        api_host: POSTHOG_HOST,
+        // Autocapture is disabled project-wide (the project setting overrides this
+        // flag), so app analytics is explicit events — not DOM autocapture or
+        // pageviews.
+        autocapture: false,
+        capture_pageview: false,
+        capture_pageleave: false,
+        // Error tracking (the project opts in). mount() only renders a local
+        // banner, so this is the app's one exception channel.
         capture_exceptions: true,
-        // Session replay is on by default at the project level (docs/security.md
-        // §11.4), but apps were never scoped for it and it would silently record
-        // anonymous public-app visitors. Keep it off on this surface.
+        // Session replay is on by default project-wide; never on the app surface.
         disable_session_recording: true,
+        // posthog-js keeps its default bot/user-agent filter, so headless/bot
+        // traffic is never tracked (real users are unaffected). One consequence:
+        // analytics can't be verified through headless Playwright — it's filtered.
+        //
+        // Tag + capture from `loaded` (once PostHog has initialized) — the robust
+        // point to register super-properties and emit the first event.
+        loaded: (ph) => {
+            ph.register({
+                app_id: ctx.app_id,
+                app_name: ctx.app_name,
+                workspace_id: ctx.workspace_id,
+                organization_id: ctx.organization_id,
+            });
+            // Guarded: a bridged host that answered `context` before its auth member
+            // loaded sends an empty org — never group on an empty key.
+            if (ctx.organization_id)
+                ph.group("organization", ctx.organization_id);
+            // Embedded apps attach to the same person as the product; standalone
+            // visitors stay anonymous (member_id null).
+            if (ctx.member_id)
+                ph.identify(ctx.member_id);
+            loaded = true;
+            ph.capture("app_opened");
+            for (const e of preInitQueue.splice(0))
+                ph.capture(e.event, e.props);
+        },
     });
-    // Tag every event (autocapture included) so app traffic is attributable and
-    // filterable — any event carrying `app_id` is an app event. `app_name` spares
-    // an id lookup when debugging; the org's name lives on the `organization`
-    // group, not denormalized here.
-    posthog.register({
-        app_id: ctx.app_id,
-        app_name: ctx.app_name,
-        workspace_id: ctx.workspace_id,
-        organization_id: ctx.organization_id,
-    });
-    // Guarded: a bridged host that answered `context` before its auth member
-    // loaded sends an empty org — never group on an empty key.
-    if (ctx.organization_id)
-        posthog.group("organization", ctx.organization_id);
-    // Embedded apps attach to the same person as the product; standalone
-    // visitors stay anonymous (member_id null).
-    if (ctx.member_id)
-        posthog.identify(ctx.member_id);
 }

package/dist/src/hooks.js

@@ -16,8 +16,19 @@
 import { useCallback, useEffect, useState } from "react";
 import { rpc } from "./rpc.js";
 import { getMockRows } from "./mock.js";
+import { captureAppEvent } from "./analytics.js";
 export function useWorkflow(alias) {
-    return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
+    return useCallback(async (inputs) => {
+        try {
+            const result = await rpc("workflow", { alias, inputs: inputs ?? {} });
+            captureAppEvent("app_workflow_run", { alias, ok: true });
+            return result;
+        }
+        catch (err) {
+            captureAppEvent("app_workflow_run", { alias, ok: false });
+            throw err;
+        }
+    }, [alias]);
 }
 export function useQuery(alias, params) {
     // Stringified params key — structurally-equal-but-new param objects don't
@@ -88,7 +99,9 @@ export function useFileUpload() {
         setInFlight((n) => n + 1);
         setError(null);
         try {
-            return await rpc("upload", { file });
+            const uploaded = await rpc("upload", { file });
+            captureAppEvent("app_file_uploaded", { mime_type: file.type });
+            return uploaded;
         }
         catch (err) {
             const message = err instanceof Error ? err.message : "Upload failed";

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/mount.js

@@ -14,10 +14,10 @@ export function mount(element, options = {}) {
     // *something* even before the parent's debug telemetry is wired up.
     installVisibleErrorHandlers(container);
     createRoot(container).render(element);
-    // Fire-and-forget: resolve the app's identity + analytics config and start
-    // PostHog autocapture. Never awaited — analytics must not delay first paint,
-    // and is best-effort so its failure can't break the app. No-ops in mock mode
-    // and when tracking is disabled for the environment.
+    // Fire-and-forget: resolve the app's identity and start PostHog (explicit
+    // events — autocapture is disabled project-wide). Never awaited — analytics
+    // must not delay first paint, and is best-effort so its failure can't break
+    // the app. No-ops in mock mode and off the deployed app host.
     void bootstrapAnalytics();
 }
 function installVisibleErrorHandlers(container) {

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,19 +18,19 @@
  *   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 + analytics config, resolved once at startup to bootstrap
- * PostHog. Assembled by whichever transport is active:
+ * The app's identity, resolved once at startup to tag PostHog events.
+ * Assembled by whichever transport is active:
  *
  *  - **Bridged** — the host (authenticated) supplies `member_id` so app events
  *    attach to the same PostHog person as the product, plus org/workspace/app
- *    from its own context and the PostHog key from its env.
- *  - **Standalone** — the public `/by-subdomain` endpoint returns identity +
- *    config; `member_id` is null (anonymous visitor).
+ *    from its own context.
+ *  - **Standalone** — the public `/by-subdomain` endpoint returns identity;
+ *    `member_id` is null (anonymous visitor).
  *
- * `posthog_key` is null when tracking is disabled for the environment
- * (dev/preview/test, or a non-production host build) — the SDK then no-ops.
+ * The PostHog key/host are not here — they're the public project key, hardcoded
+ * in `analytics.ts`.
  */
 export interface AppContext {
     app_id: string;
@@ -38,7 +38,5 @@ export interface AppContext {
     workspace_id: string;
     organization_id: string;
     member_id: string | null;
-    posthog_key: string | null;
-    posthog_host: string;
 }
 export declare function rpc<T = unknown>(op: RpcOp, payload: unknown): Promise<T>;

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 {
@@ -230,8 +253,6 @@ async function standaloneContext() {
         organization_id: info.organization_id,
         // No host session in standalone mode — the visitor is anonymous.
         member_id: null,
-        posthog_key: info.posthog_key,
-        posthog_host: info.posthog_host,
     };
 }
 async function standaloneQuery(p) {

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