@lotics/app-sdk 0.15.0 → 0.16.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/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/rpc.d.ts

@@ -20,17 +20,17 @@
  */
 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:
+ * 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

@@ -230,8 +230,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {