@lotics/app-sdk 0.12.0 → 0.15.0

package/dist/src/analytics.d.ts

@@ -0,0 +1 @@
+export declare function bootstrapAnalytics(): Promise<void>;

package/dist/src/analytics.js

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import posthog from "posthog-js";
+import { rpc } from "./rpc.js";
+import { hasMockFlag } from "./mock.js";
+export async function bootstrapAnalytics() {
+    // A design-time / screenshot load (?__mock=1) is never real usage.
+    if (hasMockFlag())
+        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.
+        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.
+        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.
+        disable_session_recording: true,
+    });
+    // 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/index.d.ts

@@ -3,11 +3,16 @@
  * app at build time. Apps `import { mount, useQuery, useWorkflow } from
  * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
  *
- * Curated UI primitive re-exports from `@lotics/ui` are deliberately NOT
- * included here. Users import them separately from a published `@lotics/ui`
- * package once that's ready, or compose with vanilla HTML/CSS in the
- * meantime. Splitting the package boundaries lets the SDK ship without
- * depending on packages/ui's React Native Web setup.
+ * This SDK is data + RPC only — it deliberately does NOT re-export any
+ * `@lotics/ui` components, so it ships without pulling in packages/ui's
+ * React Native Web dependency tree. That is a packaging choice, NOT a
+ * limitation on apps: apps import `@lotics/ui` directly as a normal dep.
+ * The starter scaffold (`packages/sdk/src/starter_template.ts`) wires the
+ * full setup — `@lotics/ui` + react-native + react-native-web, the
+ * react-native→react-native-web Vite alias, `@lotics/ui/index.css` +
+ * `fonts.css`, and a `PortalHost` for overlays. Build dashboards by
+ * composing `@lotics/ui` components (Card, KpiCard, charts, DataGrid, …),
+ * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
 export type { MountOptions } from "./mount.js";
@@ -19,3 +24,6 @@ export { readMembers } from "./members.js";
 export type { ResolvedMember } from "./members.js";
 export type { AppFixture } from "./mock.js";
 export type { AppWorkflows, AppQueries } from "./types.js";
+export { row } from "./row.js";
+export { useOptimistic } from "./use_optimistic.js";
+export type { OptimisticApi } from "./use_optimistic.js";

package/dist/src/index.js

@@ -3,13 +3,20 @@
  * app at build time. Apps `import { mount, useQuery, useWorkflow } from
  * "@lotics/app-sdk"` and ship the resulting bundle via `lotics app deploy`.
  *
- * Curated UI primitive re-exports from `@lotics/ui` are deliberately NOT
- * included here. Users import them separately from a published `@lotics/ui`
- * package once that's ready, or compose with vanilla HTML/CSS in the
- * meantime. Splitting the package boundaries lets the SDK ship without
- * depending on packages/ui's React Native Web setup.
+ * This SDK is data + RPC only — it deliberately does NOT re-export any
+ * `@lotics/ui` components, so it ships without pulling in packages/ui's
+ * React Native Web dependency tree. That is a packaging choice, NOT a
+ * limitation on apps: apps import `@lotics/ui` directly as a normal dep.
+ * The starter scaffold (`packages/sdk/src/starter_template.ts`) wires the
+ * full setup — `@lotics/ui` + react-native + react-native-web, the
+ * react-native→react-native-web Vite alias, `@lotics/ui/index.css` +
+ * `fonts.css`, and a `PortalHost` for overlays. Build dashboards by
+ * composing `@lotics/ui` components (Card, KpiCard, charts, DataGrid, …),
+ * not raw HTML/CSS. See `docs/apps.md` → "Styling & components".
  */
 export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useFileUpload } from "./hooks.js";
 export { rpc } from "./rpc.js";
 export { readMembers } from "./members.js";
+export { row } from "./row.js";
+export { useOptimistic } from "./use_optimistic.js";

package/dist/src/mock.d.ts

@@ -36,6 +36,14 @@ export interface AppFixture {
  * for HMR.
  */
 export declare function registerMockFixture(fixture: AppFixture | undefined): void;
+/**
+ * True iff the iframe URL carries the `__mock=1` activation flag. Throws never;
+ * a malformed URL or missing `window` (SSR / jsdom without location) silently
+ * returns false. Distinct from `isMockMode`: analytics keys off the raw flag
+ * (a design-time / screenshot load emits no events regardless of fixtures),
+ * while query mocking additionally requires a registered fixture.
+ */
+export declare function hasMockFlag(): boolean;
 /**
  * Returns the fixture rows for an alias when mock mode is active *and* the
  * fixture has an entry for that alias. Otherwise null — the hook falls

package/dist/src/mock.js

@@ -36,14 +36,13 @@ export function registerMockFixture(fixture) {
     registeredFixture = fixture;
 }
 /**
- * True iff the iframe URL carries the `__mock=1` activation flag AND a
- * fixture was registered. Safe to call before mount — returns false when no
- * fixture exists. Throws never; a malformed URL or missing `window` (SSR /
- * jsdom without location) silently returns false.
+ * True iff the iframe URL carries the `__mock=1` activation flag. Throws never;
+ * a malformed URL or missing `window` (SSR / jsdom without location) silently
+ * returns false. Distinct from `isMockMode`: analytics keys off the raw flag
+ * (a design-time / screenshot load emits no events regardless of fixtures),
+ * while query mocking additionally requires a registered fixture.
  */
-function isMockMode() {
-    if (!registeredFixture)
-        return false;
+export function hasMockFlag() {
     try {
         return new URLSearchParams(window.location.search).get("__mock") === "1";
     }
@@ -51,6 +50,14 @@ function isMockMode() {
         return false;
     }
 }
+/**
+ * True iff the iframe URL carries the `__mock=1` activation flag AND a
+ * fixture was registered. Safe to call before mount — returns false when no
+ * fixture exists.
+ */
+function isMockMode() {
+    return Boolean(registeredFixture) && hasMockFlag();
+}
 /**
  * Returns the fixture rows for an alias when mock mode is active *and* the
  * fixture has an entry for that alias. Otherwise null — the hook falls

package/dist/src/mount.d.ts

@@ -26,8 +26,8 @@
  *
  * `mount` wires up React 19's createRoot against `#root` in the iframe shell,
  * sets up window.onerror/unhandledrejection forwarding so runtime crashes
- * surface in the parent's debug pane, registers the fixture (if any), and
- * renders the user's tree.
+ * surface in the parent's debug pane, registers the fixture (if any), renders
+ * the user's tree, and bootstraps PostHog analytics (see `./analytics.ts`).
  *
  * If the bundler doesn't ship #root in the user's `index.html`, we create it
  * — Vite's default scaffold provides one, but defensive creation keeps the

package/dist/src/mount.js

@@ -1,5 +1,6 @@
 import { createRoot } from "react-dom/client";
 import { registerMockFixture } from "./mock.js";
+import { bootstrapAnalytics } from "./analytics.js";
 export function mount(element, options = {}) {
     registerMockFixture(options.fixture);
     let container = document.getElementById("root");
@@ -13,6 +14,11 @@ 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.
+    void bootstrapAnalytics();
 }
 function installVisibleErrorHandlers(container) {
     const showError = (message) => {

package/dist/src/row.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ *
+ * 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 }`. */
+declare function opt(v: unknown): string | null;
+/** Text/markdown/autonumber → string (numbers stringified; everything else ""). */
+declare function text(v: unknown): string;
+/** Number → number (NaN/Infinity and unparseable strings → 0). */
+declare function num(v: unknown): number;
+/** Checkbox/boolean → boolean (accepts the string "true"). */
+declare function bool(v: unknown): boolean;
+/**
+ * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
+ * calendar/gantt placement never shifts across timezones. Parses the leading
+ * `YYYY-MM-DD` of the serialized string; null if absent or unparseable. (Range
+ * fields are not handled here — they have no consumer yet.)
+ */
+declare function date(v: unknown): Date | null;
+export declare const row: {
+    opt: typeof opt;
+    text: typeof text;
+    num: typeof num;
+    bool: typeof bool;
+    date: typeof date;
+};
+export {};

package/dist/src/row.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ *
+ * 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 }`. */
+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 id = v.id;
+        return typeof id === "string" ? id : null;
+    }
+    return null;
+}
+/** Text/markdown/autonumber → string (numbers stringified; everything else ""). */
+function text(v) {
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" && Number.isFinite(v))
+        return String(v);
+    return "";
+}
+/** Number → number (NaN/Infinity and unparseable strings → 0). */
+function num(v) {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : 0;
+    if (typeof v === "string" && v.trim()) {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : 0;
+    }
+    return 0;
+}
+/** Checkbox/boolean → boolean (accepts the string "true"). */
+function bool(v) {
+    return v === true || v === "true";
+}
+/**
+ * Date/datetime field → a LOCAL-midnight Date for the stored calendar day, so
+ * calendar/gantt placement never shifts across timezones. Parses the leading
+ * `YYYY-MM-DD` of the serialized string; null if absent or unparseable. (Range
+ * fields are not handled here — they have no consumer yet.)
+ */
+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 };

package/dist/src/rpc.d.ts

@@ -18,5 +18,27 @@
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "workflow" | "upload";
+export type RpcOp = "query" | "workflow" | "upload" | "context";
+/**
+ * The app's identity + analytics config, resolved once at startup to bootstrap
+ * PostHog. 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).
+ *
+ * `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.
+ */
+export interface AppContext {
+    app_id: string;
+    app_name: string;
+    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

@@ -3,11 +3,10 @@ import { runUploadPipeline } from "./upload/pipeline.js";
 /**
  * The embedding Lotics host's origin — present iff the app is bridged.
  *
- * Lazy + memoized so the module's top level doesn't touch `window`. The SDK
- * gets imported by `frontend/lib/download.ts`, which Jest pulls in at module
- * evaluation time before its jsdom environment finishes setting up
- * `window.location` — eager reads crash every test suite that transitively
- * imports the SDK.
+ * Lazy + memoized so the module's top level doesn't touch `window`. A test
+ * runner can pull this module in at evaluation time before its jsdom
+ * environment finishes setting up `window.location` — an eager read would
+ * crash every suite that transitively imports the SDK.
  *
  * `undefined` = not yet computed; `string | null` = computed result.
  */
@@ -69,6 +68,7 @@ const PASSWORD_REQUIRED_CODE = "PASSWORD_REQUIRED";
  * `/by-subdomain` fetch and at most one password prompt.
  */
 let bootPromise = null;
+let appInfoPromise = null;
 let sessionToken = null;
 function sessionStorageKey(appId) {
     return `lotics_app_session:${appId}`;
@@ -109,12 +109,32 @@ function clearStoredSession(appId) {
         // ignore
     }
 }
+/**
+ * Resolve the app's identity + analytics config from its own subdomain. Shared
+ * promise so the context bootstrap and the first data call coalesce into one
+ * `/by-subdomain` fetch. Does NOT touch the password gate — identity is needed
+ * for analytics regardless of whether the visitor has unlocked the data, so a
+ * password-gated app still resolves (and tracks) before the prompt.
+ */
+function resolveAppInfo() {
+    if (appInfoPromise)
+        return appInfoPromise;
+    const slug = window.location.hostname.split(".")[0];
+    const attempt = apiCall("GET", `/v1/apps/by-subdomain/${encodeURIComponent(slug)}`);
+    // Don't cache a rejection — a transient failure on first load would brick
+    // every later data call. Clear the slot so the next call retries.
+    attempt.catch(() => {
+        if (appInfoPromise === attempt)
+            appInfoPromise = null;
+    });
+    appInfoPromise = attempt;
+    return attempt;
+}
 async function boot() {
     if (bootPromise)
         return bootPromise;
-    const slug = window.location.hostname.split(".")[0];
     const attempt = (async () => {
-        const info = (await apiCall("GET", `/v1/apps/by-subdomain/${encodeURIComponent(slug)}`));
+        const info = await resolveAppInfo();
         if (info.requires_password) {
             const stored = readStoredSession(info.app_id);
             if (stored) {
@@ -126,8 +146,6 @@ async function boot() {
         }
         return info;
     })();
-    // Don't cache a rejection — a transient failure on first load would brick
-    // every later data call. Clear the slot so the next call retries.
     attempt.catch(() => {
         if (bootPromise === attempt)
             bootPromise = null;
@@ -199,8 +217,23 @@ function rpcStandalone(op, payload) {
             return standaloneWorkflow(payload);
         case "upload":
             return standaloneUpload(payload.file);
+        case "context":
+            return standaloneContext();
     }
 }
+async function standaloneContext() {
+    const info = await resolveAppInfo();
+    return {
+        app_id: info.app_id,
+        app_name: info.app_name,
+        workspace_id: info.workspace_id,
+        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) {
     const { app_id } = await boot();
     const r = (await apiCall("POST", `/v1/apps/${app_id}/query`, { alias: p.alias, params: p.params }, { appId: app_id }));

package/dist/src/use_optimistic.d.ts

@@ -0,0 +1,22 @@
+export interface OptimisticApi<T> {
+    /** `base` with any pending optimistic patches applied. */
+    items: T[];
+    /**
+     * Optimistically merge `next` into the item keyed `id`, then run `persist`.
+     * On resolve → `onSettled?.()` (pass your query's `refetch`); the patch is
+     * kept (it already matches the refetched value, so no flicker). On reject →
+     * the patch is reverted.
+     */
+    patch: (id: string, next: Partial<T>, persist: () => Promise<unknown>, opts?: {
+        onSettled?: () => void;
+    }) => void;
+}
+/**
+ * Optimistic list overrides for a `useQuery` result feeding an interactive view
+ * (calendar drag, gantt resize, kanban move). Pure React state: it takes the
+ * already-mapped items + a key function + a caller-supplied `persist` thunk, so
+ * it has no coupling to any specific mutation transport (the app threads its own
+ * `useWorkflow` call + `refetch`). It lives in app-sdk as the *reconcile* leg of
+ * the read (`useQuery`) → mutate (`useWorkflow`) → reconcile loop.
+ */
+export declare function useOptimistic<T>(base: T[], keyOf: (item: T) => string): OptimisticApi<T>;

package/dist/src/use_optimistic.js

@@ -0,0 +1,27 @@
+import { useCallback, useMemo, useState } from "react";
+/**
+ * Optimistic list overrides for a `useQuery` result feeding an interactive view
+ * (calendar drag, gantt resize, kanban move). Pure React state: it takes the
+ * already-mapped items + a key function + a caller-supplied `persist` thunk, so
+ * it has no coupling to any specific mutation transport (the app threads its own
+ * `useWorkflow` call + `refetch`). It lives in app-sdk as the *reconcile* leg of
+ * the read (`useQuery`) → mutate (`useWorkflow`) → reconcile loop.
+ */
+export function useOptimistic(base, keyOf) {
+    const [overrides, setOverrides] = useState({});
+    const items = useMemo(() => base.map((item) => {
+        const o = overrides[keyOf(item)];
+        return o ? { ...item, ...o } : item;
+    }), [base, overrides, keyOf]);
+    const patch = useCallback((id, next, persist, opts) => {
+        setOverrides((m) => ({ ...m, [id]: { ...m[id], ...next } }));
+        persist().then(() => opts?.onSettled?.(), () => setOverrides((m) => {
+            if (!(id in m))
+                return m;
+            const cleared = { ...m };
+            delete cleared[id];
+            return cleared;
+        }));
+    }, []);
+    return { items, patch };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -14,17 +14,21 @@
   "scripts": {
     "build": "tsgo",
     "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
     "prepublishOnly": "npm run build"
   },
+  "dependencies": {
+    "posthog-js": "^1.352.0"
+  },
   "peerDependencies": {
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
   },
   "keywords": [
     "lotics",