@lotics/app-sdk 0.77.3 → 0.78.0

package/dist/src/analytics.d.ts

@@ -1,7 +1 @@
-/**
- * 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

@@ -9,12 +9,20 @@
  * values — and Điều 3.2 of the service contract warrants that our telemetry
  * carries no record or document content. The flags below are what enforce
  * that; the project-level setting is NOT a backstop, since it is server-side
- * and fails open when the config fetch fails. The SDK emits explicit events
- * for genuine user actions only: `app_opened`, `app_file_uploaded`, and
- * `app_comment_*`. System signals — data-read mechanics (a `useQuery` refetch)
- * and workflow/agent run outcomes — are not events: the backend already logs
- * and persists every run (`workflow_executions`, `app_agent_runs`), so a client
- * event would be redundant system telemetry, not a gesture.
+ * and fails open when the config fetch fails.
+ *
+ * **What earns an event:** who KNOWS the fact. An effect the platform performs
+ * or persists is the platform's — a comment, an upload, a workflow or agent run
+ * all leave rows, and a client copy would duplicate one AND keep arriving from
+ * apps pinned to an old SDK long after the code is deleted. A FAILURE is not a
+ * gesture either; it is system telemetry, and this bundle has no log sink to
+ * carry it, so it is not an event here by default.
+ *
+ * That leaves exactly one: `app_opened`. Apps are a separate origin the
+ * product's own analytics cannot see, and the app-host gate log records gate
+ * DECISIONS rather than routine serves, so nothing else counts an app being
+ * used. Everything a run does is already in `app_agent_runs` — including a
+ * user's Stop, which stamps `cancel_requested_at`.
  *
  * Every event is tagged with app identity and rolls up under the existing
  * `organization` group; embedded apps `identify` the member the host passes
@@ -33,34 +41,6 @@ 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);
@@ -73,17 +53,14 @@ 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();
+    if (hasMockFlag() || !onDeployedAppHost())
         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, {
@@ -113,9 +90,12 @@ export async function bootstrapAnalytics() {
         // Tag + capture from `loaded` (once PostHog has initialized) — the robust
         // point to register super-properties and emit the first event.
         loaded: (ph) => {
+            // Ids only. A super-property rides every event and every `$exception`
+            // the session sends, and an app's NAME is the customer's own words —
+            // routinely a counterparty — which Điều 3.2 keeps out of telemetry. The
+            // id resolves to the name for anyone entitled to it.
             ph.register({
                 app_id: ctx.app_id,
-                app_name: ctx.app_name,
                 workspace_id: ctx.workspace_id,
                 organization_id: ctx.organization_id,
             });
@@ -127,10 +107,7 @@ export async function bootstrapAnalytics() {
             // 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/comments.js

@@ -25,7 +25,6 @@
 import { useCallback } from "react";
 import useSWR from "swr";
 import { rpc } from "./rpc.js";
-import { captureAppEvent } from "./analytics.js";
 import { useAppContext } from "./viewer.js";
 /** The reduced storage shape the update endpoint accepts for `files`. */
 function toStorageFiles(files) {
@@ -101,7 +100,6 @@ export function useComments(args) {
             revalidate: false,
             populateCache: true,
         });
-        captureAppEvent("app_comment_created", { has_files: fileIds.length > 0 });
     }, [available, memberId, record_id, swr]);
     const updateComment = useCallback(async (id, input) => {
         if (!available)
@@ -129,7 +127,6 @@ export function useComments(args) {
             revalidate: false,
             populateCache: true,
         });
-        captureAppEvent("app_comment_updated", {});
     }, [available, record_id, swr]);
     const deleteComment = useCallback(async (id) => {
         if (!available)
@@ -145,7 +142,6 @@ export function useComments(args) {
             revalidate: false,
             populateCache: true,
         });
-        captureAppEvent("app_comment_deleted", {});
     }, [available, record_id, swr]);
     return {
         comments,

package/dist/src/hooks.js

@@ -22,7 +22,6 @@ import useSWRInfinite from "swr/infinite";
 import { rpc, rpcAgentRun, rpcAgentRunContinue, postHostNotification, subscribeHostRefetch, } from "./rpc.js";
 import { initialAgentRunState, reduceAgentChunk, parseSseChunks, adoptSettledRun, pendingInteractiveCall, buildChoiceOutput, applyInteractiveAnswer, landingOf, proseOf, ABORTED, } from "./agent_stream.js";
 import { getMockRows, hasMockFlag } from "./mock.js";
-import { captureAppEvent } from "./analytics.js";
 export { buildChoiceOutput } from "./agent_stream.js";
 export function useWorkflow(alias) {
     return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
@@ -288,7 +287,6 @@ export function useFileUpload() {
         setError(null);
         try {
             const uploaded = await rpc("upload", { file, fidelity });
-            captureAppEvent("app_file_uploaded", { mime_type: file.type, fidelity });
             return uploaded;
         }
         catch (err) {
@@ -601,14 +599,6 @@ export function useAgentRun(alias) {
                         error: "The run was interrupted and its result could not be confirmed. Run it again.",
                     };
                 safeSetState(acc);
-                // Fleet visibility: how often edges cut agent SSE streams. One
-                // event per truncation, with whether the row rescued the result.
-                captureAppEvent("app_agent_stream_truncated", {
-                    kind: "clean_end",
-                    recovered: settled != null,
-                    settled_status: settled?.status ?? null,
-                    has_output: acc.output !== undefined,
-                });
             }
             return landingOf(acc);
         })
@@ -635,16 +625,6 @@ export function useAgentRun(alias) {
                     acc = adoptGuarded(acc, settled);
                     safeSetState(acc);
                 }
-                // The same fleet-visibility beacon as the clean-end path — a dropped
-                // connection is the OTHER way a stream dies mid-run, and it was
-                // previously invisible (the beacon fired only on clean-end
-                // truncations, undercounting every network-error cut).
-                captureAppEvent("app_agent_stream_truncated", {
-                    kind: "connection_error",
-                    recovered: settled != null,
-                    settled_status: settled?.status ?? null,
-                    has_output: acc.output !== undefined,
-                });
                 if (settled)
                     return landingOf(acc);
             }
@@ -663,7 +643,6 @@ export function useAgentRun(alias) {
         // in-flight promise makes a double-click resolve with the first run's
         // result; `replace: true` is the explicit opt-in to abort-and-restart.
         if (inflightRef.current && !opts.replace) {
-            captureAppEvent("app_agent_run_deduped", { alias });
             return inflightRef.current;
         }
         handleRef.current?.abort();
@@ -710,6 +689,10 @@ export function useAgentRun(alias) {
     const abort = useCallback(() => handleRef.current?.abort(), []);
     const cancel = useCallback(() => {
         // Stop server-side too (saves tokens on an unwanted run), then locally.
+        // No analytics event here: the cancel RPC stamps `app_agent_runs
+        // .cancel_requested_at`, which is what separates a user's Stop from the
+        // unmount/tab-close that `abort` also serves — a client event would only
+        // duplicate a column, and would go stale the moment an app pins an old SDK.
         const runId = runIdRef.current;
         if (runId)
             void rpc("agentRun.cancel", { run_id: runId }).catch(() => { });

package/docs/ai.md

@@ -57,8 +57,8 @@ await recognize.run({ image_file_id: fileId }, { sessionId });
 
 | Member | Type | What it is |
 |---|---|---|
-| `run` | `(input, { sessionId, replace? }) => Promise<AgentRunLanding<TOutput>>` | Start a run. Streams progress into the hook's state and resolves with **how the leg ended** — `{kind:"settled", output?, text}`, `{kind:"parked"}`, `{kind:"failed", error}` or `{kind:"aborted"}`. Switch on `kind`; do NOT read the hook's state to tell them apart, because it has not committed when the promise resolves (that race closed dialogs over live, answerable runs). A run failure is DATA here, so no try/catch is needed for it. **Single-flight:** while a run is in flight, calling it again returns the in-flight run's promise — an accidental double-press joins the first run instead of billing a second one (each dedup emits the `app_agent_run_deduped` analytics event). Pass `replace: true` to deliberately abort-and-restart; the replaced run still executes and bills server-side |
-| `cancel` | `() => void` | Stop the run **server-side** (saves tokens) and locally. Wire a user-facing Stop button to this |
+| `run` | `(input, { sessionId, replace? }) => Promise<AgentRunLanding<TOutput>>` | Start a run. Streams progress into the hook's state and resolves with **how the leg ended** — `{kind:"settled", output?, text}`, `{kind:"parked"}`, `{kind:"failed", error}` or `{kind:"aborted"}`. Switch on `kind`; do NOT read the hook's state to tell them apart, because it has not committed when the promise resolves (that race closed dialogs over live, answerable runs). A run failure is DATA here, so no try/catch is needed for it. **Single-flight:** while a run is in flight, calling it again returns the in-flight run's promise — an accidental double-press joins the first run instead of billing a second one. Pass `replace: true` to deliberately abort-and-restart; the replaced run still executes and bills server-side |
+| `cancel` | `() => void` | Stop the run **server-side** (saves tokens) and locally. Wire a user-facing Stop button to this. The platform stamps `app_agent_runs.cancel_requested_at`, which is what distinguishes a user Stop from the unmount that `abort` also serves — so there is no client analytics event for it |
 | `abort` | `() => void` | Stop listening **locally only** — the run keeps executing server-side and its result is still persisted. This is the unmount path (the hook calls it automatically on unmount) |
 | `status` | `"idle" \| "streaming" \| "awaiting_input" \| "completed" \| "error"` | Whole-run state. `awaiting_input` = the run is PARKED on a question the agent asked (see the ask-back section below). `abort`/`cancel` reset it to `"idle"` (and clear the partial transcript) |
 | `pendingChoice` | `PendingChoice \| null` | The agent's pending question(s) — non-null exactly while `status` is `awaiting_input`. `questions` maps 1:1 onto `@lotics/ui`'s `ClarifyWizard` (`{question, options: {label, description}[], allow_custom}`) |
@@ -184,7 +184,7 @@ The run's lifetime is decoupled from the stream: the server drives it to complet
 - **The connection drops with an error** → the hook polls the persisted run to completion (every 2.5 s) and resolves with the settled result instead of surfacing a network error.
 - **The stream ends cleanly WITHOUT a `finish` frame** — an edge/proxy can close a long SSE gracefully mid-run, which looks like completion but swallowed the trailing frames (including the structured result). The hook detects the missing `finish` and polls the row the same way.
 
-Both truncation shapes emit the `app_agent_stream_truncated` analytics event (`kind: "connection_error" | "clean_end"`, with whether the row rescued the result), so edge-cut frequency is visible fleet-wide.
+Either way the run itself is unaffected — it keeps executing server-side and settles in `app_agent_runs`, which is where its outcome is read.
 
 **Anonymous runs poll with a capability token, handled for you.** On a publicly-shared app a visitor has no member identity, so the server cannot authorize their poll by ownership — `triggered_by_member_id` is null by design. Instead the run response carries a per-run token (`x-app-agent-run-token`); the SDK stores it against that run id and replays it on the poll, on `cancel`, and on `answerChoice`. It is transport-level, like the password-session token — never surfaced to app code, and never issued for a member run (identity already authorizes those). Nothing to wire: an app calls `useAgentRun` the same way on both. The token is bound to ONE run, so it cannot read another visitor's, and it is why a dropped connection on a public app recovers rather than losing the answer.
 

package/docs/data_fetching.md

@@ -407,15 +407,30 @@ pieces. Compose these — don't hand-roll search:
   search constraint and would dump the table on first paint. `enabled` makes "nothing loads until
   you type" true. Add `revalidateOnFocus: false` — re-running an ephemeral search on refocus is
   wasted work.
+- **Debounce the term — `enabled` is not a substitute.** `enabled` decides *whether* to ask, not
+  *how often*: wire an input's own state into `params` and every keystroke past the first is a
+  fresh cache key and a fresh request. A six-letter name costs six, and on a list screen each one
+  is several — `usePaginatedQuery` re-counts whenever `params` change, and any sibling query
+  taking the same term goes with it. Keep the input's value in one state and debounce the COMMIT
+  into a second (`useDebouncedCallback` from `@lotics/ui/use_debounced_callback`, ~250 ms). The
+  two values are genuinely different — what is being typed, and what the rows on screen answer —
+  and anything reporting on the results (an empty state, a count, a "showing N for X" line) reads
+  the committed one, or it describes a set the server was never asked for. `Combobox` already
+  debounces its own `onSearchChange`; this is for a search box you built yourself.
 - **`useRecents(key, { max })`** — persist the picked option locally; pass its list as
   `recentOptions` ([./navigation_and_state.md](./navigation_and_state.md)).
 
 ```tsx
-const [term, setTerm] = useState("");            // live input stays local
+const [typed, setTyped] = useState("");          // the input's own value, every keystroke
+const [term, setTerm] = useState("");            // what the server is asked, once typing settles
+const commit = useDebouncedCallback(setTerm, 250);
+
+<SearchInput value={typed} onChangeText={(v) => { setTyped(v); commit(v.trim()); }} />;
+
 const { rows, loading } = useQuery(
   "searchCustomers",
   { q: term },
-  { enabled: term.trim().length > 0, revalidateOnFocus: false },
+  { enabled: term.length > 0, revalidateOnFocus: false },
 );
 ```
 

package/docs/runtime.md

@@ -344,37 +344,29 @@ await checkIn({ latitude: r.coords.latitude, longitude: r.coords.longitude });
 ## Automatic analytics (PostHog)
 
 `mount()` boots a PostHog instance per app — apps are a separate cross-origin
-bundle, invisible to the product's own analytics. **No per-app wiring**: don't
-install `posthog-js` or call any analytics API from app code.
-
-- **Explicit events only — user gestures.** Autocapture, pageviews, and session
-  replay are off (autocapture is disabled at the project level — a client flag
-  could not re-enable it). System signals are deliberately not events: data
-  reads (`useQuery` fetches) and workflow/agent run outcomes. The backend
-  already logs and persists every run (`workflow_executions`, `app_agent_runs`).
-- Events the SDK emits automatically:
-
-| Event | Fired when | Properties |
-|---|---|---|
-| `app_opened` | analytics finished initializing after `mount()` | — |
-| `app_file_uploaded` | a `useFileUpload` upload succeeds | `mime_type` |
-| `app_comment_created` | a comment is created via `useComments` | `has_files` |
-| `app_comment_updated` / `app_comment_deleted` | comment edit/delete succeeds | — |
-
-- Every event carries the app identity as super-properties (`app_id`,
-  `app_name`, `workspace_id`, `organization_id`) and rolls up under the
-  `organization` group. Embedded apps `identify` the signed-in member — app and
+bundle, invisible to the product's own analytics. It is entirely automatic:
+don't install `posthog-js` or call any analytics API from app code, and there is
+no hook for app-defined events. If a bespoke funnel matters, request the surface
+as a platform change.
+
+The SDK emits one event, `app_opened`, once PostHog finishes initializing.
+Everything an app *does* is already recorded by the platform — a comment, an
+upload, a workflow or agent run each leave a row, and a run's outcome, including
+a user's Stop (`cancel_requested_at`), lands in `app_agent_runs`.
+
+- Autocapture, pageviews, dead clicks, and session replay are all off, set at
+  init rather than relied on project-wide: the server-side setting fails open,
+  and an app screen renders the customer's own records.
+- `app_opened` carries the app identity as super-properties — `app_id`,
+  `workspace_id`, `organization_id`, ids only, since a name is the customer's
+  own words — and rolls up under the `organization` group. Embedded apps `identify` the signed-in member — app and
   product events share one person; standalone visitors stay anonymous.
 - Uncaught exceptions are captured (PostHog error tracking) in addition to
-  `mount()`'s visible banner.
+  `mount()`'s visible banner — the app's one error channel.
 - **Tracking is gated to the deployed app host** (`*.lotics.app`). `lotics app
   dev` (localhost) and any `?__mock=1` load emit nothing. Best-effort
-  throughout: a failed init or a failed `context` resolution disables tracking
-  and never breaks the app. Events fired before init completes are buffered
-  (bounded) and drained on init.
-- **Limitation:** there is no public API for custom app events — the capture
-  function is internal to the SDK. If a bespoke funnel matters, request the
-  surface as a platform change.
+  throughout: a failed init or a failed `context` resolution leaves the app
+  fully working and untracked.
 - **Limitation:** PostHog's default bot/user-agent filter applies — headless
   browsers (e.g. Playwright) are never tracked, so analytics cannot be verified
   through headless automation.

package/package.json

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