@lotics/app-sdk 0.13.0 → 0.16.0

package/dist/src/analytics.d.ts

@@ -0,0 +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

@@ -0,0 +1,128 @@
+/**
+ * PostHog analytics for custom-code apps.
+ *
+ * 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.
+ *
+ * **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.
+ *
+ * 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() {
+    // 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 must never break the app.
+        disable();
+        return;
+    }
+    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 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);
+        },
+    });
+}

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/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 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) {
     const showError = (message) => {

package/dist/src/rpc.d.ts

@@ -18,5 +18,25 @@
  *   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, 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.
+ *  - **Standalone** — the public `/by-subdomain` endpoint returns identity;
+ *    `member_id` is null (anonymous visitor).
+ *
+ * The PostHog key/host are not here — they're the public project key, hardcoded
+ * in `analytics.ts`.
+ */
+export interface AppContext {
+    app_id: string;
+    app_name: string;
+    workspace_id: string;
+    organization_id: string;
+    member_id: string | null;
+}
 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,21 @@ 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,
+    };
+}
 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.16.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",