@lotics/app-sdk 0.13.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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {
@@ -17,15 +17,18 @@
     "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",