@uptimizr/db 0.1.0

package/dist/query/types.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Shared, dialect-agnostic types for the analytics query layer (ADR 0020).
+ *
+ * These option and row shapes describe *what* an aggregation needs, independent
+ * of any SQL dialect. Aggregations are authored once against these types in
+ * `aggregations.ts` and rendered per engine via a {@link Dialect}; the OSS
+ * default engine is DuckDB, with a single-tenant ClickHouse dialect available to
+ * the optional scale tier.
+ */
+/** A parameterized query, ready to hand to a dialect-specific runner. */
+export interface QuerySpec {
+    query: string;
+    query_params: Record<string, unknown>;
+}
+export interface RangeOptions {
+    /** Inclusive lower bound (epoch ms). */
+    since?: number;
+    /** Exclusive upper bound (epoch ms). */
+    until?: number;
+}
+/** Optional scene/area filter (ADR 0010). */
+export interface SceneOptions {
+    /** Restrict to a single developer-assigned scene id. Omit for all scenes. */
+    scene?: string;
+}
+/** Optional input-source filter (ADR 0011). */
+export interface SourceOptions {
+    /** Restrict to a single input source (e.g. `"mouse"`, `"hand"`). Omit for all. */
+    source?: string;
+}
+/** Optional single-session filter. */
+export interface SessionOptions {
+    /** Restrict the aggregate to one session id. Omit for all sessions. */
+    session?: string;
+}
+/**
+ * Optional camera/navigation-model filter (ADR 0026). Segments aggregates by the
+ * `scene.cameraType` declared on each session's `session_start` — e.g.
+ * `"arc-rotate"` (orbit viewer) vs. `"free"` (first-person walkthrough). Omit for
+ * all camera types. Implemented as a `session_id IN (…)` sub-select over
+ * `session_start`, so it composes with every other filter.
+ */
+export interface CameraModeOptions {
+    /** Restrict to sessions whose `scene.cameraType` equals this value. */
+    cameraType?: string;
+}
+/** Time-series bucketing options. */
+export interface TimeseriesOptions {
+    /** Bucket width in seconds (default 3600 = 1h). */
+    interval?: number;
+    /** Restrict the volume to a single event type. Omit to count all events. */
+    type?: string;
+}
+export interface SessionSummaryRow {
+    session_id: string;
+    visitor_id: string;
+    events: number;
+    started_at: string;
+    ended_at: string;
+}
+export interface HeatmapBinRow {
+    gx: number;
+    gy: number;
+    count: number;
+}
+export interface WorldHeatmapBinRow {
+    vx: number;
+    vy: number;
+    vz: number;
+    count: number;
+}
+/**
+ * One bin of the top-down "floor plan" camera-position heatmap (ADR 0026): camera
+ * positions binned on the X/Z ground plane into `cellSize`-sized cells, with the
+ * cell-average Y for reference. Reveals where visitors stand/dwell in a walkable scene.
+ */
+export interface PositionBinRow {
+    gx: number;
+    gz: number;
+    /** Mean Y (height) of camera samples in the cell. */
+    avg_y: number;
+    count: number;
+}
+/** One ordered point of a session's walked path (ADR 0026). */
+export interface TrajectoryPointRow {
+    ts: string;
+    x: number;
+    y: number;
+    z: number;
+}
+export interface DirectionBinRow {
+    azimuth_bin: number;
+    elevation_bin: number;
+    count: number;
+}
+export interface ClickGazeRayRow {
+    cam_vx: number;
+    cam_vy: number;
+    cam_vz: number;
+    origin_x: number;
+    origin_y: number;
+    origin_z: number;
+    hit_vx: number;
+    hit_vy: number;
+    hit_vz: number;
+    hit_x: number;
+    hit_y: number;
+    hit_z: number;
+    mesh: string;
+    count: number;
+}
+export interface FlowLinkRow {
+    azimuth_bin: number;
+    elevation_bin: number;
+    mesh: string;
+    count: number;
+    /**
+     * Standpoint voxel indices — the click-time camera-position cell (design §7.8).
+     * Present only in the position-aware mode (`groupByOrigin`/`originVoxel`);
+     * omitted by the default direction-only §7.5 flow.
+     */
+    origin_vx?: number;
+    origin_vy?: number;
+    origin_vz?: number;
+    /** Averaged standpoint world point for the voxel (position-aware mode, §7.8). */
+    origin_x?: number;
+    origin_y?: number;
+    origin_z?: number;
+}
+export interface MeshCountRow {
+    mesh: string;
+    count: number;
+}
+/** Per-object attention summary from `mesh_visibility` events (#37). */
+export interface MeshDwellRow {
+    mesh: string;
+    /** Total on-screen time across the range, in ms. */
+    visible_ms: number;
+    /** Total time the object was near the view centre (gaze proxy), in ms. */
+    centered_ms: number;
+    /** Largest screen fraction the object reached (prominence proxy), 0..1. */
+    max_screen_fraction: number;
+    /** Number of bucketed summary events contributing to the totals. */
+    samples: number;
+}
+/** Dead-click rate summary from `pointer_click` events (#46). */
+export interface DeadClickRow {
+    /** Total clicks in range. */
+    total_clicks: number;
+    /** Clicks that hit no mesh (empty space) — the dead clicks. */
+    dead_clicks: number;
+}
+/** A rage-click cluster: rapid repeats on one mesh in a time window (#47). */
+export interface RageClickRow {
+    session_id: string;
+    mesh: string;
+    /** Window start as epoch milliseconds. */
+    bucket: number;
+    /** Number of clicks on the mesh within the window (>= minRepeats). */
+    clicks: number;
+}
+/** Per-object hover-hesitation summary from `hover_dwell` events (#48). */
+export interface HoverDwellRow {
+    mesh: string;
+    /** Total time visitors hovered the object without clicking it, in ms. */
+    dwell_ms: number;
+    /** Longest single hover episode on the object, in ms. */
+    max_dwell_ms: number;
+    /** Number of hover episodes contributing to the totals. */
+    episodes: number;
+}
+/** Per-phase shader/pipeline compile-stall summary from `compile_stall` events (#42). */
+export interface CompileStallRow {
+    /** Coarse compile phase (`shader` / `pipeline` / `material` / `other`); `""` if unattributed. */
+    phase: string;
+    /** Number of compile stalls in the phase. */
+    stalls: number;
+    /** Total main-thread time spent compiling, in ms. */
+    total_ms: number;
+    /** Average compile-stall duration, in ms. */
+    avg_ms: number;
+    /** Worst single compile-stall duration, in ms. */
+    max_ms: number;
+}
+/** GPU / memory footprint summary from `resource_sample` samples (#44). */
+export interface ResourceSummaryRow {
+    /** Number of footprint samples in the range. */
+    samples: number;
+    /** Average used JS heap in bytes (unreported samples excluded). */
+    avg_js_heap_bytes: number;
+    /** Peak used JS heap in bytes. */
+    max_js_heap_bytes: number;
+    /** Average triangles submitted per sampled frame. */
+    avg_triangles: number;
+    /** Peak triangles submitted in a sampled frame. */
+    max_triangles: number;
+    /** Average vertices submitted per sampled frame. */
+    avg_vertices: number;
+    /** Peak vertices submitted in a sampled frame. */
+    max_vertices: number;
+    /** Average resident texture memory in bytes. */
+    avg_texture_bytes: number;
+    /** Peak resident texture memory in bytes. */
+    max_texture_bytes: number;
+    /** Average resident geometry memory in bytes. */
+    avg_geometry_bytes: number;
+    /** Peak resident geometry memory in bytes. */
+    max_geometry_bytes: number;
+}
+/** Per-transition capability fallback/recovery summary from `capability_change` events (#49). */
+export interface CapabilityChangeRow {
+    /** Capability class (`graphics-backend` / `quality` / `device-recovery` / `feature` / `other`). */
+    kind: string;
+    /** Previous capability token (e.g. `webgpu`); `""` if unreported. */
+    from: string;
+    /** New capability token (e.g. `webgl2`); `""` if unreported. */
+    to: string;
+    /** Number of times this transition was reported. */
+    changes: number;
+}
+/** Per-kind camera-navigation gesture summary from `camera_gesture` events (ADR 0025). */
+export interface CameraGestureRow {
+    /** Gesture class (`orbit` / `pan` / `dolly` / `zoom` / `roll` / `fly` / `navigate`). */
+    kind: string;
+    /** Number of gestures of this kind. */
+    gestures: number;
+    /** Total time spent in this gesture kind, in ms. */
+    total_ms: number;
+    /** Average gesture duration, in ms. */
+    avg_ms: number;
+    /** Longest single gesture, in ms. */
+    max_ms: number;
+}
+export interface PerfSummaryRow {
+    samples: number;
+    avg_fps: number;
+    min_fps: number;
+    p50_fps: number;
+}
+/** Per-session-then-aggregate FPS percentiles (ADR 0028 §1). */
+export interface PerfDistributionRow {
+    sessions: number;
+    samples: number;
+    p05_fps: number;
+    p50_fps: number;
+    p95_fps: number;
+}
+/** One bin of the per-session-median FPS histogram (ADR 0028 §1). */
+export interface FpsHistogramRow {
+    /** Inclusive lower bound (FPS) of the bin. */
+    bucket: number;
+    sessions: number;
+}
+/** Per-session-then-aggregate frame-time percentiles, in ms (ADR 0028 §1). */
+export interface FrameTimePercentileRow {
+    sessions: number;
+    samples: number;
+    p50_ms: number;
+    p95_ms: number;
+}
+/** Per-session-then-aggregate jank rate (ADR 0028 §1). */
+export interface JankRateRow {
+    sessions: number;
+    total_long_frames: number;
+    /** Median per-session long-frames-per-window rate. */
+    median_rate: number;
+    /** Worst-decile (p90) per-session rate. */
+    worst_decile_rate: number;
+}
+/** FPS segmented by device class from `session_start.device` (ADR 0028 §2). */
+export interface PerfByDeviceRow {
+    engine: string;
+    is_mobile: string;
+    renderer: string;
+    sessions: number;
+    samples: number;
+    p50_fps: number;
+}
+/** FPS segmented by scene, per-session-then-aggregate (ADR 0028 §1). */
+export interface PerfBySceneRow {
+    scene_id: string;
+    sessions: number;
+    samples: number;
+    p50_fps: number;
+}
+/** Per-session-then-aggregate GPU/memory footprint percentiles (ADR 0028 §1). */
+export interface ResourcePercentileRow {
+    sessions: number;
+    samples: number;
+    p50_js_heap_bytes: number;
+    p95_js_heap_bytes: number;
+    p50_texture_bytes: number;
+    p95_texture_bytes: number;
+    p50_triangles: number;
+    p95_triangles: number;
+}
+/** Stability-incident counts (context losses, compile stalls). */
+export interface StabilityCountRow {
+    context_losses: number;
+    compile_stalls: number;
+    incidents: number;
+}
+export interface PerfDailyRow {
+    day: string;
+    samples: number;
+    avg_fps: number;
+    min_fps: number;
+    p50_fps: number;
+}
+export interface EventsDailyRow {
+    day: string;
+    event_type: string;
+    events: number;
+}
+export interface SceneRow {
+    scene_id: string;
+    events: number;
+    last_seen: string;
+}
+export interface TimeseriesBucketRow {
+    /** Start of the bucket as epoch milliseconds. */
+    bucket: number;
+    events: number;
+    avg_fps: number;
+}
+export interface EventTypeCountRow {
+    event_type: string;
+    count: number;
+}
+/** One occupied camera-position voxel for scene coverage / dead-zone analysis. */
+export interface CoverageVoxelRow {
+    vx: number;
+    vy: number;
+    vz: number;
+    count: number;
+}
+/** One distance-histogram bucket: `bucket * bucketSize` world units from center. */
+export interface CameraDistanceBucketRow {
+    bucket: number;
+    count: number;
+}
+/** Per-session navigation-effort summary (travel distance, active vs idle). */
+export interface NavigationStatsRow {
+    session_id: string;
+    segments: number;
+    total_distance: number;
+    active_segments: number;
+    active_distance: number;
+}
+/** Per-session XR motion-sickness proxy: view-rotation rate over the pose stream. */
+export interface XrRotationRateRow {
+    session_id: string;
+    samples: number;
+    avg_turn_rad: number;
+    max_turn_rad: number;
+    total_turn_rad: number;
+    rapid_segments: number;
+}
+/** One XR input source (`hand`, `xr-controller`, …) with its usage counts. */
+export interface XrSourceUsageRow {
+    source: string;
+    interactions: number;
+    sessions: number;
+}
+/**
+ * One `(event_type, source)` pairing from the input-source breakdown (ADR 0011):
+ * how many interactions of that type came from that input source, and across how
+ * many distinct sessions.
+ */
+export interface InteractionSourceRow {
+    /** The interaction event type (e.g. `mesh_interaction`, `pointer_click`). */
+    event_type: string;
+    /** The input source that triggered it (e.g. `mouse`, `xr-controller`, `hand`). */
+    source: string;
+    /** Number of events of this `(event_type, source)` pairing. */
+    count: number;
+    /** Number of distinct sessions that produced this pairing. */
+    sessions: number;
+}
+/** Per-XR-session abandonment row: time bounds and event/interaction counts. */
+export interface XrAbandonmentRow {
+    session_id: string;
+    events: number;
+    xr_interactions: number;
+    started_at: string;
+    ended_at: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/query/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/query/types.ts"],"names":[],"mappings":"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"}

package/dist/query/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared, dialect-agnostic types for the analytics query layer (ADR 0020).
+ *
+ * These option and row shapes describe *what* an aggregation needs, independent
+ * of any SQL dialect. Aggregations are authored once against these types in
+ * `aggregations.ts` and rendered per engine via a {@link Dialect}; the OSS
+ * default engine is DuckDB, with a single-tenant ClickHouse dialect available to
+ * the optional scale tier.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/query/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/query/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/llms.txt

@@ -0,0 +1,21 @@
+# @uptimizr/db
+
+> OSS storage contracts + the single-file DuckDB store (events + metadata in one `.duckdb` file;
+> ADR 0020). Dialect-agnostic query builders defined once and emitted per engine. No
+> ClickHouse/Postgres dependency — those live with a separately-licensed scale store. Server/Node
+> only. Query-time aggregation; forward-only, additive migrations. Single-writer store.
+
+## Docs
+
+- [Package reference](./README.md): DuckDB usage, the spec-once/emit-per-dialect extension point, single-writer constraint.
+- [Agent guide](./AGENTS.md): rules and canonical usage for AI agents.
+- [Integration & API reference](https://github.com/RaananW/Uptimizr/blob/main/docs/integration.md): how queries surface to consumers.
+- [Architecture Decision Records](https://github.com/RaananW/Uptimizr/tree/main/docs/adr): database choice (0002), migrations (0007), open-core storage boundary (0020).
+
+## Key exports
+
+- DuckDB store: `createDuckdbClient`, `migrateDuckdb`, `duckdbInsertEvents`, `duckdbGetSessionEvents`, `duckdbResolveApiKey`, `runDuckdbQuery`.
+- Query layer: `buildX(projectId, opts, dialect)` builders, `duckdbDialect`, `Dialect`/`QuerySpec` types.
+- Neutral helpers: `toEventRow`, `formatUtcTimestamp`, api-key helpers, `Project`/`ApiKeyRecord`/`SceneRepresentation*` types.
+- Parity: `PARITY_CASES`, `diffParity` (DuckDB-vs-ClickHouse cross-engine equality).
+- `readDbSettings()` — environment-driven DuckDB settings with a local-dev default (`DUCKDB_PATH`).

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@uptimizr/db",
+  "version": "0.1.0",
+  "description": "OSS storage contracts (dialect-agnostic query layer, neutral event/metadata types) and the single-file DuckDB store for Uptimizr.",
+  "keywords": [
+    "uptimizr",
+    "analytics",
+    "duckdb",
+    "clickhouse",
+    "postgres",
+    "storage",
+    "query",
+    "events"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RaananW/Uptimizr.git",
+    "directory": "oss/packages/db"
+  },
+  "bugs": {
+    "url": "https://github.com/RaananW/Uptimizr/issues"
+  },
+  "homepage": "https://github.com/RaananW/Uptimizr/tree/main/oss/packages/db#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./query": {
+      "types": "./dist/query/index.d.ts",
+      "import": "./dist/query/index.js"
+    }
+  },
+  "bin": {
+    "uptimizr-db-migrate": "./dist/cli/migrate.js",
+    "uptimizr-db-new-project": "./dist/cli/createProject.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "AGENTS.md",
+    "llms.txt"
+  ],
+  "dependencies": {
+    "@duckdb/node-api": "^1.5.4-r.1",
+    "@uptimizr/schema": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "tsx": "^4.22.4",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "migrate": "tsx src/cli/migrate.ts",
+    "seed": "tsx src/cli/seed.ts",
+    "new-project": "tsx src/cli/createProject.ts",
+    "clean": "rm -rf dist"
+  }
+}