@lotics/app-sdk 0.47.1 → 0.49.0

package/dist/src/analytics.js

@@ -8,10 +8,11 @@
  * 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.
+ * 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.
  *
  * Every event is tagged with app identity and rolls up under the existing
  * `organization` group; embedded apps `identify` the member the host passes
@@ -93,6 +94,10 @@ export async function bootstrapAnalytics() {
         autocapture: false,
         capture_pageview: false,
         capture_pageleave: false,
+        // Dead-click autocapture (enabled by the defaults preset) is a UX-research
+        // signal nobody consumes; explicit user actions + exception capture cover
+        // the app's monitoring needs.
+        capture_dead_clicks: 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,

package/dist/src/hooks.js

@@ -23,17 +23,7 @@ import { initialAgentRunState, reduceAgentChunk, parseSseChunks, } from "./agent
 import { getMockRows } from "./mock.js";
 import { captureAppEvent } from "./analytics.js";
 export function useWorkflow(alias) {
-    return useCallback(async (inputs) => {
-        try {
-            const result = await rpc("workflow", { alias, inputs: inputs ?? {} });
-            captureAppEvent("app_workflow_run", { alias, ok: result.status !== "error" });
-            return result;
-        }
-        catch (err) {
-            captureAppEvent("app_workflow_run", { alias, ok: false });
-            throw err;
-        }
-    }, [alias]);
+    return useCallback((inputs) => rpc("workflow", { alias, inputs: inputs ?? {} }), [alias]);
 }
 // Shared SWR config: surface a failed query immediately, keep the last good
 // rows (no retry loop that masks the error), and honor the focus/reconnect
@@ -111,21 +101,28 @@ export function useInfiniteQuery(alias, params, opts) {
     const sort = opts?.sort && opts.sort.length > 0 ? opts.sort : undefined;
     const filter = opts?.filter;
     const mockRows = getMockRows(alias);
+    // Keyset (seek) pagination: each page seeks past the previous page's
+    // `next_cursor` instead of an increasing OFFSET, so deep scrolls stay O(page)
+    // and never skip/duplicate a row as the set shifts. The cursor is opaque; the
+    // server keysets a sortable key (or the id default) and falls back to offset
+    // transparently. `loadMore`/`rows` are unchanged — the cursor is internal.
     const getKey = (index, prev) => {
         if (mockRows || !enabled)
             return null;
-        // Stop once a short page returns.
-        if (index > 0 && (prev == null || prev.rows.length < pageSize))
+        // Stop once a page reports no next cursor (the end).
+        if (index > 0 && (prev == null || prev.next_cursor == null))
             return null;
-        return ["app-query-infinite", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, index];
+        const cursor = index === 0 ? null : (prev?.next_cursor ?? null);
+        return ["app-query-infinite", alias, params ?? {}, pageSize, sort ?? null, filter ?? null, cursor];
     };
     const swr = useSWRInfinite(getKey, (key) => {
-        const index = Number(key[6]);
+        const cursor = key[6];
         return rpc("query", {
             alias,
             params: params ?? {},
             limit: pageSize,
-            offset: index * pageSize,
+            keyset: true,
+            cursor: cursor ?? undefined,
             sort,
             filter,
         });
@@ -136,7 +133,8 @@ export function useInfiniteQuery(alias, params, opts) {
     const pages = (swr.data ?? []).filter((p) => p != null);
     const rows = mockRows ?? pages.flatMap((p) => p.rows ?? []);
     const lastPage = pages.length > 0 ? pages[pages.length - 1] : undefined;
-    const hasMore = lastPage != null && (lastPage.rows?.length ?? 0) === pageSize;
+    // A non-null next_cursor means another page exists; null/absent = the end.
+    const hasMore = lastPage != null && lastPage.next_cursor != null;
     const loadingMore = swr.isValidating && swr.size > pages.length;
     const refetch = useCallback(() => {
         void swr.mutate();
@@ -413,7 +411,6 @@ export function useAgentRun(alias) {
                 acc = { ...acc, status: "completed" };
                 safeSetState(acc);
             }
-            captureAppEvent("app_agent_run", { alias, ok: acc.status !== "error" });
             return acc.output;
         })
             .catch(async (err) => {
@@ -431,7 +428,6 @@ export function useAgentRun(alias) {
                             ? { ...acc, status: "completed", output: settled.output ?? acc.output }
                             : { ...acc, status: "error", error: settled.error_message ?? "The run was stopped." };
                     safeSetState(acc);
-                    captureAppEvent("app_agent_run", { alias, ok: settled.status === "completed" });
                     return acc.output;
                 }
                 if (aborted)
@@ -439,7 +435,6 @@ export function useAgentRun(alias) {
             }
             acc = { ...acc, status: "error", error: err.message };
             safeSetState(acc);
-            captureAppEvent("app_agent_run", { alias, ok: false });
             throw err;
         });
     }, [alias, safeSetState]);

package/docs/queries.md

@@ -246,17 +246,21 @@ addressing is dropped.
 { "kind": "window", "from": { … },
   "partition_by": ["customer_id"],
   "order_by": [{ "field_key": "created", "order": "asc" }],
-  "frame": { "type": "rows", "following": 0 },     // optional
+  "frame": { "type": "rows", "following": 0 },     // optional; frames `aggregates` only
   "aggregates": [{ "output": "running_total", "type": "number",
-                   "operation": "sum", "input_column": "total" }] }
+                   "operation": "sum", "input_column": "total" }],
+  "functions":  [{ "output": "rnk", "fn": "rank" }] }   // ranking / navigation (§8)
 ```
 
-Appends aggregate columns to every input row (input columns pass through). Only the
-**OVER-legal** operation subset is accepted (§8). Frame is `rows`-type only:
-`preceding`/`following` omitted = unbounded, `0` = current row, `N` = N rows. Omitting `frame`
-uses the SQL default — with `order_by` that is a *running* frame (partition start → current
-row, ties included); without `order_by`, the whole partition. Output names must not collide
-with input columns.
+Appends columns to every input row (input columns pass through) from two independent lists:
+**`aggregates`** (frame aggregates — the OVER-legal operation subset, §8) and **`functions`**
+(ranking / navigation: `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`,
+`ntile`, `lag`, `lead` — §8). At least one list must be non-empty; both may be present. `frame`
+is `rows`-type only (`preceding`/`following` omitted = unbounded, `0` = current row, `N` = N
+rows) and applies **only** to `aggregates`; omitting it uses the SQL default (with `order_by`, a
+*running* frame partition start → current row, ties included; without, the whole partition).
+`functions` are never framed and need a non-empty `order_by`. Output names must not collide with
+input columns.
 
 ### `sort` / `limit` — order and page a derived set
 
@@ -633,17 +637,30 @@ Sort by the bucket column for a time series; filter it with date operators for a
 window. **Always bucket server-side** — shipping raw rows to bucket in JS burns the row cap and
 the timeout for nothing.
 
-### Window functions — the OVER-legal subset
+A `window` node carries two independent column lists — **`aggregates`** (frame aggregates) and
+**`functions`** (ranking / navigation). At least one must be non-empty; a node may carry both.
 
-Only operations that compile to a single legal SQL window call are accepted in `window`:
-**`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`, `filled`, `checked`,
-`unchecked`.** The rest cannot take an OVER clause (`median` is an ordered-set aggregate;
-`unique`/`percent_unique` need DISTINCT; `range`/`empty`/`date_range`/`percent_*` compose
-multiple calls) — rejected at deploy.
+**`aggregates` — the OVER-legal aggregate subset.** Only operations that compile to a single
+legal SQL window call are accepted: **`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`,
+`filled`, `checked`, `unchecked`.** The rest cannot take an OVER clause (`median` is an
+ordered-set aggregate; `unique`/`percent_unique` need DISTINCT; `range`/`empty`/`date_range`/
+`percent_*` compose multiple calls) — rejected at deploy. The optional `frame` applies **only**
+to these; a `frame` on a window with no `aggregates` is rejected as dead config.
 
-**There are no ranking or navigation functions** — no `row_number`, `rank`, `dense_rank`,
-`lag`, `lead`, `first_value`. **Top-N per group** is emulated with a running count over a
-frame:
+**`functions` — ranking / navigation.** Each is `{ "output", "fn", … }` (its own arg shape, no
+`operation`/`type` — the output type is fixed or inherited). They never take a `frame` and
+**require a non-empty `order_by`** (ranking without an order is nondeterministic):
+
+| `fn` | args | output |
+| --- | --- | --- |
+| `row_number` | — | `number`, non-null. Total order 1..N within the partition; ties broken arbitrarily. |
+| `rank` | — | `number`, non-null. Ties share a rank; the next rank **skips** (1,2,2,4). |
+| `dense_rank` | — | `number`, non-null. Ties share a rank; the next rank does **not** skip (1,2,2,3). |
+| `percent_rank` / `cume_dist` | — | `number`, non-null. Relative position in [0, 1]. |
+| `ntile` | `buckets` (positive int) | `number`, non-null. The row's bucket (1..buckets) splitting the partition into equal groups. |
+| `lag` / `lead` | `input_column`, `offset?` (int ≥ 1, default 1), `default?` (literal) | the input column's type, **nullable**. The value `offset` rows before / after this one; at the partition edge, `default` if given else NULL. `default`'s type must match the input column (checked at deploy). |
+
+**Top-N per group** — rank within each partition, then filter on the derived rank column:
 
 ```jsonc
 { "kind": "filter",
@@ -651,14 +668,15 @@ frame:
     "from": { "kind": "from_table", "table_id": "tbl_orders" },
     "partition_by": ["customer_id"],
     "order_by": [{ "field_key": "total", "order": "desc" }],
-    "frame": { "type": "rows", "following": 0 },        // partition start → current row
-    "aggregates": [{ "output": "rank", "type": "number", "operation": "count" }] },
-  "predicate": { "node_type": "condition", "field_key": "rank",
+    "functions": [{ "output": "rnk", "fn": "rank" }] },
+  "predicate": { "node_type": "condition", "field_key": "rnk",
                  "operator": "less_than_or_equal_to", "value": 3 } }
 ```
 
-`count` over a `ROWS … CURRENT ROW` frame is a row position (`row_number`-like; ties are
-ordered arbitrarily unless the `order_by` is total — add a tiebreaker key for determinism).
+`rank` keeps ties (a 3-way tie for 3rd returns all three). For exactly N rows regardless of
+ties, use `row_number` (with a total `order_by` — add a tiebreaker key for determinism).
+**Delta vs the previous row/period** is `lag` (e.g. a project column `{ "expression": "input.total
+- input.prev_total" }` over a `lag` output).
 
 ### unpivot vs unnest
 
@@ -885,9 +903,9 @@ Consolidated from the sections above — these describe present engine behavior:
 
 - **No pivot/crosstab node.** Row-values-to-columns happens client-side over grouped results
   (§8).
-- **No ranking or navigation window functions** (`row_number`, `rank`, `lag`, `lead`, …).
-  Top-N per group = the count-over-frame emulation (§8). Window ops are the 10-item OVER-legal
-  subset.
+- **No `first_value`/`last_value`/`nth_value` navigation** — the `functions` set is `row_number`,
+  `rank`, `dense_rank`, `percent_rank`, `cume_dist`, `ntile`, `lag`, `lead` (§8). Frame aggregates
+  remain the 10-item OVER-legal subset.
 - **Offset-only pagination.** Deep pages cost the full skipped prefix; pages can shift under
   concurrent writes (§9).
 - **No collation control.** Text ORDER BY uses the database default collation —

package/docs/runtime.md

@@ -333,17 +333,18 @@ await checkIn({ latitude: r.coords.latitude, longitude: r.coords.longitude });
 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.** Autocapture, pageviews, and session replay are off
-  (autocapture is disabled at the project level — a client flag could not
-  re-enable it). Data reads (`useQuery` fetches) are deliberately not events.
+- **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`),
+  so a client run event would be redundant system telemetry, not a gesture.
 - Events the SDK emits automatically:
 
 | Event | Fired when | Properties |
 |---|---|---|
 | `app_opened` | analytics finished initializing after `mount()` | — |
-| `app_workflow_run` | each `useWorkflow` call settles | `alias`, `ok` |
 | `app_file_uploaded` | a `useFileUpload` upload succeeds | `mime_type` |
-| `app_agent_run` | a `useAgentRun` run finishes | `alias`, `ok` |
 | `app_comment_created` | a comment is created via `useComments` | `has_files` |
 | `app_comment_updated` / `app_comment_deleted` | comment edit/delete succeeds | — |
 
@@ -359,9 +360,8 @@ install `posthog-js` or call any analytics API from app code.
   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, model it as a
-  workflow (which produces `app_workflow_run`) or request the surface as a
-  platform change.
+  function is internal to the SDK. If a bespoke funnel matters, request the
+  surface as a platform change.
 - **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.47.1",
+  "version": "0.49.0",
   "description": "Runtime SDK for Lotics custom-code apps — typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {