@formant/formant-cli 0.3.1 → 0.4.3

package/dist/help.js

@@ -3,17 +3,17 @@ export default class FcliHelp extends Help {
     async showRootHelp() {
         const output = `
    ███████╗ ██████╗██╗     ██╗
-   ██╔════╝██╔════╝██║     ██║     🤖 Formant CLI v${this.config.version}
-   █████╗  ██║     ██║     ██║     ⚡ Manage your robot fleet
-   ██╔══╝  ██║     ██║     ██║     🚀 from the command line
+   ██╔════╝██╔════╝██║     ██║     Formant CLI v${this.config.version}
+   █████╗  ██║     ██║     ██║     Manage your robot fleet
+   ██╔══╝  ██║     ██║     ██║     from the command line
    ██║     ╚██████╗███████╗██║
    ╚═╝      ╚═════╝╚══════╝╚═╝
 
 ABOUT
   Formant is a cloud platform for monitoring, operating, and analyzing robot fleets.
   This CLI lets you interact with your robots, query telemetry data, trigger AI-powered
-  investigations, manage users and permissions, and automate fleet operations — all from
-  your terminal.
+  investigations, delegate tasks to AI personas, and automate fleet operations — all
+  from your terminal.
 
 USAGE
   $ fcli <command> [flags]
@@ -24,23 +24,25 @@ KEY CONCEPTS
   Event          An important occurrence (alert, warning, error) emitted by a device
   Signal         A point of interest that triggers investigation or analysis
   Investigation  AI-powered workflow that analyzes device data and diagnoses issues
+  Persona        An AI agent with specific tools and instructions
   Stream         Real-time telemetry data (battery, temperature, location, sensors)
   Command        Remote instruction sent to a device to perform an action
   Fleet          A logical group of devices (by location, type, or tags)
 
 COMMANDS
   org              View and update your Formant organization
-  devices          Create, list, tag, and manage robots/sensors in your fleet
-  events           View and filter important events emitted by devices
+  device           Create, list, tag, and manage robots/sensors in your fleet
+  event            View and filter important events emitted by devices
   query            Retrieve historical telemetry data and latest sensor values
   ingest           Send telemetry data to devices via the Formant ingestion API
-  signals          List, query, and analyze signals that trigger investigations
-  investigations   Trigger, monitor, and analyze AI-powered diagnostic workflows
-  commands         Send remote commands to devices and view command history
-  event-triggers   Configure rules that automatically generate events and signals
-  users            List and inspect users in your organization
-  fleets           Manage device groups and organize your fleet
-  schedules        Set up recurring tasks and one-time scheduled jobs
+  signal           List, query, and analyze signals that trigger investigations
+  investigation    Trigger, monitor, and analyze AI-powered diagnostic workflows
+  persona          Manage AI personas and delegate async tasks
+  command          Send remote commands to devices and view command history
+  event-trigger    Configure rules that automatically generate events and signals
+  user             List and inspect users in your organization
+  fleet            Manage device groups and organize your fleet
+  schedule         Set up recurring tasks and one-time scheduled jobs
   analytics        Execute custom SQL queries against your analytics database
   kv               Store and retrieve metadata in the key-value store
   help             Display help for fcli
@@ -65,16 +67,16 @@ EXAMPLES
   $ fcli org update --name "Acme Robotics"              # Update org name
 
   # Device management
-  $ fcli devices list --online                          # List all online devices
-  $ fcli devices list --tag location=warehouse          # Filter by tags
-  $ fcli devices create --name "robot-001"              # Create a new device
-  $ fcli devices tag <device-id> --key env --value prod # Add tags
-  $ fcli devices rename <device-id> --name "robot-new"  # Rename a device
+  $ fcli device list --online                           # List all online devices
+  $ fcli device list --tag location=warehouse           # Filter by tags
+  $ fcli device create --name "robot-001"               # Create a new device
+  $ fcli device tag <device-id> --key env --value prod  # Add tags
+  $ fcli device rename <device-id> --name "robot-new"   # Rename a device
 
   # Telemetry queries
   $ fcli query --device <id> --stream battery_level --start 2026-01-01 --end 2026-01-02
   $ fcli query latest-values --device <id> --stream battery_level
-  $ fcli devices streams <device-id>                    # List available streams
+  $ fcli device streams <device-id>                     # List available streams
 
   # Ingest telemetry data
   $ fcli ingest numeric 42.5 --device <id> --stream battery_level
@@ -83,37 +85,41 @@ EXAMPLES
   $ fcli ingest batch --file payload.json               # Batch ingest from file
 
   # Events and monitoring
-  $ fcli events list --severity critical --limit 50     # View critical events
-  $ fcli events list --device <id> --start 2026-01-01  # Events for one device
-  $ fcli events get <event-id>                          # Get event details
+  $ fcli event list --severity critical --limit 50      # View critical events
+  $ fcli event list --device <id> --start 2026-01-01    # Events for one device
+  $ fcli event get <event-id>                           # Get event details
 
-  # AI investigations
-  $ fcli investigations list                            # List all investigations
-  $ fcli investigations trigger <inv-id> <device-id>    # Trigger an investigation
-  $ fcli investigations runs <inv-id>                   # View investigation runs
-  $ fcli investigations stats --start 2026-01-01        # Get investigation metrics
+  # AI personas
+  $ fcli persona list                                   # List all personas
+  $ fcli persona get <persona-id>                       # View persona tools
+  $ fcli persona delegate-task <persona-id> "Analyze recent failures"
+  $ fcli persona task-status <task-id>                  # Check task results
 
-  # Signals (investigation triggers)
-  $ fcli signals list --start 2026-01-01 --end 2026-02-01
-  $ fcli signals query --start 2026-01-01              # Query by time range
-  $ fcli signals count                                  # Count signals by type
-  $ fcli signals get <signal-id>                        # Get signal details
+  # AI investigations
+  $ fcli investigation list                             # List all investigations
+  $ fcli investigation trigger <id> -i "Robot stopped"  # Trigger an investigation
+  $ fcli investigation runs <id>                        # View investigation runs
+
+  # Signals and ground truths
+  $ fcli signal create "Motor overheated on device X"   # Create a manual signal
+  $ fcli signal create "Sensor fault" -i <inv-id> -g "Should detect thermal issue"
+  $ fcli signal list                                    # List all signals
+  $ fcli signal list --investigation <inv-id>           # List with ground truths
+  $ fcli signal query --start 2026-01-01                # Query by time range
+  $ fcli signal set-ground-truth <signal-id> <inv-id> "Expected outcome"
 
   # Remote commands
-  $ fcli commands list                                  # List command templates
-  $ fcli commands for-device <device-id>                # Commands for one device
-  $ fcli commands send <device-id> <template-id> --param speed=10
-  $ fcli commands history <device-id>                   # View command history
+  $ fcli command list                                   # List command templates
+  $ fcli command for-device <device-id>                 # Commands for one device
+  $ fcli command send <device-id> <template-id> --param speed=10
 
   # Event triggers (automation)
-  $ fcli event-triggers list                            # List all trigger rules
-  $ fcli event-triggers get <trigger-id>                # View trigger details
+  $ fcli event-trigger list                             # List all trigger rules
+  $ fcli event-trigger get <trigger-id>                 # View trigger details
 
   # User and fleet management
-  $ fcli users list                                     # List all users
-  $ fcli users get <user-id>                            # View user details
-  $ fcli fleets list                                    # List device groups
-  $ fcli fleets get <fleet-id>                          # View fleet details
+  $ fcli user list                                      # List all users
+  $ fcli fleet list                                     # List device groups
 
   # Analytics and data queries
   $ fcli analytics tables                               # List available tables
@@ -125,10 +131,10 @@ EXAMPLES
   $ fcli kv set <device-id> <key> <value>               # Store a value
 
 TIPS
-  • Use --json with any command to get machine-readable output for scripting
-  • Pipe output to jq for advanced JSON processing: fcli devices list --json | jq
-  • Set --dev or --stage to target non-production environments
-  • Use fcli <command> --help to see detailed help for any command
+  * Use --json with any command to get machine-readable output for scripting
+  * Pipe output to jq for advanced JSON processing: fcli device list --json | jq
+  * Set --dev or --stage to target non-production environments
+  * Use fcli <command> --help to see detailed help for any command
 
 LEARN MORE
   Documentation:  https://formant.io/docs

package/dist/help.js.map

@@ -1 +1 @@
-{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,aAAa,CAAA;AAEhC,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,IAAI;IACrB,KAAK,CAAC,YAAY;QACnC,MAAM,MAAM,GAAG;;qDAEkC,IAAI,CAAC,MAAM,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmIvE,CAAA;QAEG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClB,CAAC;CACF"}
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../src/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,aAAa,CAAA;AAEhC,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,IAAI;IACrB,KAAK,CAAC,YAAY;QACnC,MAAM,MAAM,GAAG;;kDAE+B,IAAI,CAAC,MAAM,CAAC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyIpE,CAAA;QAEG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAClB,CAAC;CACF"}

package/dist/lib/api.d.ts

@@ -1,5 +1,5 @@
 import { type Environment } from './config.js';
-export type ApiTarget = 'admin' | 'ingest' | 'query' | 'theopolis';
+export type ApiTarget = 'admin' | 'gateway' | 'ingest' | 'query' | 'theopolis';
 interface RequestOptions {
     body?: unknown;
     method?: 'DELETE' | 'GET' | 'PATCH' | 'POST' | 'PUT';

package/dist/lib/api.js

@@ -6,6 +6,9 @@ function buildBaseUrl(env, target) {
         case 'admin': {
             return `${urls.adminApi}/v1/admin`;
         }
+        case 'gateway': {
+            return `${urls.gateway}/api`;
+        }
         case 'ingest': {
             return `${urls.adminApi}/v1/ingest`;
         }

package/dist/lib/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/lib/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,OAAO,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,EAAC,KAAK,EAAC,MAAM,WAAW,CAAA;AAU/B,SAAS,YAAY,CAAC,GAAgB,EAAE,MAAiB;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACzB,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,GAAG,IAAI,CAAC,QAAQ,WAAW,CAAA;QACpC,CAAC;QAED,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,OAAO,GAAG,IAAI,CAAC,QAAQ,YAAY,CAAA;QACrC,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,GAAG,IAAI,CAAC,QAAQ,aAAa,CAAA;QACtC,CAAC;QAED,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,OAAO,GAAG,IAAI,CAAC,SAAS,MAAM,CAAA;QAChC,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAgB,EAChB,MAAiB,EACjB,IAAY,EACZ,UAA0B,EAAE;IAE5B,MAAM,EAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,EAAC,GAAG,OAAO,CAAA;IAC7D,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAA;IAE7B,IAAI,GAAG,GAAG,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE,CAAA;IAChD,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAA;QACzC,GAAG,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAA;IAChC,CAAC;IAED,MAAM,OAAO,GAA2B;QACtC,aAAa,EAAE,UAAU,IAAI,CAAC,WAAW,EAAE;QAC3C,cAAc,EAAE,kBAAkB;KACnC,CAAA;IAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QAC7C,OAAO;QACP,MAAM;KACP,CAAC,CAAA;IAEF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;QAC7B,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,MAAM,IAAI,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC,CAAA;IACtE,CAAC;IAED,wBAAwB;IACxB,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,SAAc,CAAA;IAE7C,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAA;AAChC,CAAC"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/lib/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,OAAO,EAAC,MAAM,aAAa,CAAA;AACrD,OAAO,EAAC,KAAK,EAAC,MAAM,WAAW,CAAA;AAU/B,SAAS,YAAY,CAAC,GAAgB,EAAE,MAAiB;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAA;IACzB,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,GAAG,IAAI,CAAC,QAAQ,WAAW,CAAA;QACpC,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,OAAO,GAAG,IAAI,CAAC,OAAO,MAAM,CAAA;QAC9B,CAAC;QAED,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,OAAO,GAAG,IAAI,CAAC,QAAQ,YAAY,CAAA;QACrC,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,OAAO,GAAG,IAAI,CAAC,QAAQ,aAAa,CAAA;QACtC,CAAC;QAED,KAAK,WAAW,CAAC,CAAC,CAAC;YACjB,OAAO,GAAG,IAAI,CAAC,SAAS,MAAM,CAAA;QAChC,CAAC;IACH,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAgB,EAChB,MAAiB,EACjB,IAAY,EACZ,UAA0B,EAAE;IAE5B,MAAM,EAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,KAAK,EAAC,GAAG,OAAO,CAAA;IAC7D,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAA;IAE7B,IAAI,GAAG,GAAG,GAAG,YAAY,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,IAAI,EAAE,CAAA;IAChD,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,KAAK,CAAC,CAAA;QACzC,GAAG,IAAI,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAA;IAChC,CAAC;IAED,MAAM,OAAO,GAA2B;QACtC,aAAa,EAAE,UAAU,IAAI,CAAC,WAAW,EAAE;QAC3C,cAAc,EAAE,kBAAkB;KACnC,CAAA;IAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;QAC7C,OAAO;QACP,MAAM;KACP,CAAC,CAAA;IAEF,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;QAC7B,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,CAAC,MAAM,IAAI,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC,CAAA;IACtE,CAAC;IAED,wBAAwB;IACxB,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,SAAc,CAAA;IAE7C,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAA;AAChC,CAAC"}

package/dist/lib/config.d.ts

@@ -1,6 +1,7 @@
 export type Environment = 'dev' | 'prod' | 'stage';
 export interface EnvUrls {
     adminApi: string;
+    gateway: string;
     queryApi: string;
     theopolis: string;
 }

package/dist/lib/config.js

@@ -1,16 +1,19 @@
 const ENVIRONMENTS = {
     prod: {
         adminApi: 'https://api.formant.io',
+        gateway: 'https://gateway-service-prod-f814f074944f.herokuapp.com',
         queryApi: 'https://api.formant.io',
         theopolis: 'https://theopolis-prod-ad4d9de77f9a.herokuapp.com',
     },
     dev: {
         adminApi: 'https://api-dev.formant.io',
+        gateway: 'https://gateway-service-dev-47d47ae014aa.herokuapp.com',
         queryApi: 'https://api-dev.formant.io',
         theopolis: 'https://theopolis-dev-231bd5d86d0f.herokuapp.com',
     },
     stage: {
         adminApi: 'https://api-stage.formant.io',
+        gateway: 'https://gateway-service-stage-515bbe9b1906.herokuapp.com',
         queryApi: 'https://api-stage.formant.io',
         theopolis: 'https://theopolis-stage-80d087320b3d.herokuapp.com',
     },

package/dist/lib/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAQA,MAAM,YAAY,GAAiC;IACjD,IAAI,EAAE;QACJ,QAAQ,EAAE,wBAAwB;QAClC,QAAQ,EAAE,wBAAwB;QAClC,SAAS,EAAE,mDAAmD;KAC/D;IACD,GAAG,EAAE;QACH,QAAQ,EAAE,4BAA4B;QACtC,QAAQ,EAAE,4BAA4B;QACtC,SAAS,EAAE,kDAAkD;KAC9D;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,8BAA8B;QACxC,QAAQ,EAAE,8BAA8B;QACxC,SAAS,EAAE,oDAAoD;KAChE;CACF,CAAA;AAED,MAAM,UAAU,OAAO,CAAC,GAAgB;IACtC,OAAO,YAAY,CAAC,GAAG,CAAC,CAAA;AAC1B,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AASA,MAAM,YAAY,GAAiC;IACjD,IAAI,EAAE;QACJ,QAAQ,EAAE,wBAAwB;QAClC,OAAO,EAAE,yDAAyD;QAClE,QAAQ,EAAE,wBAAwB;QAClC,SAAS,EAAE,mDAAmD;KAC/D;IACD,GAAG,EAAE;QACH,QAAQ,EAAE,4BAA4B;QACtC,OAAO,EAAE,wDAAwD;QACjE,QAAQ,EAAE,4BAA4B;QACtC,SAAS,EAAE,kDAAkD;KAC9D;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,8BAA8B;QACxC,OAAO,EAAE,0DAA0D;QACnE,QAAQ,EAAE,8BAA8B;QACxC,SAAS,EAAE,oDAAoD;KAChE;CACF,CAAA;AAED,MAAM,UAAU,OAAO,CAAC,GAAgB;IACtC,OAAO,YAAY,CAAC,GAAG,CAAC,CAAA;AAC1B,CAAC"}

package/dist/lib/presence.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared utilities for querying per-stream per-device data presence
+ * via the analytics SQL backend.
+ *
+ * Uses a UNION ALL across all telemetry tables to discover what data
+ * exists, grouped by (device_id, stream_name, stream_type).
+ */
+export interface StreamPresenceRow {
+    data_points: number;
+    device_id: string;
+    first_seen: string;
+    last_seen: string;
+    stream_name: string;
+    stream_type: string;
+}
+/**
+ * Build a SQL query that returns per-stream per-device data presence.
+ *
+ * Returns columns: device_id, stream_name, stream_type, data_points, first_seen, last_seen
+ */
+export declare function buildPresenceSQL(options: {
+    days?: number;
+    deviceIds?: string[];
+    limit?: number;
+    streamNames?: string[];
+    streamTypes?: string[];
+}): string;
+/**
+ * Build a SQL query that returns the last time any data was seen per device.
+ *
+ * Returns columns: device_id, last_seen, total_points, stream_count
+ */
+export declare function buildLastSeenSQL(options: {
+    days?: number;
+    deviceIds?: string[];
+}): string;
+/**
+ * Normalize a timestamp string from analytics SQL (e.g. "2026-02-19 23:37:04.747")
+ * to ISO 8601 format ("2026-02-19T23:37:04.747Z").
+ */
+export declare function toIsoDateTime(sqlTimestamp: string): string;
+/**
+ * Freshness label based on how recently data was seen.
+ */
+export type FreshnessLevel = 'active' | 'dormant' | 'recent' | 'stale';
+export declare function getFreshness(lastSeenIso: string): FreshnessLevel;

package/dist/lib/presence.js

@@ -0,0 +1,95 @@
+/**
+ * Shared utilities for querying per-stream per-device data presence
+ * via the analytics SQL backend.
+ *
+ * Uses a UNION ALL across all telemetry tables to discover what data
+ * exists, grouped by (device_id, stream_name, stream_type).
+ */
+/**
+ * The telemetry tables that hold stream data.
+ * Each has: organization_id, device_id, name, tags, time, and type-specific value columns.
+ */
+const TELEMETRY_TABLES = [
+    { streamType: 'numeric', table: 'query_numeric' },
+    { streamType: 'text', table: 'query_text' },
+    { streamType: 'json', table: 'query_json' },
+    { streamType: 'location', table: 'query_location' },
+    { streamType: 'battery', table: 'query_battery' },
+    { streamType: 'health', table: 'query_health' },
+    { streamType: 'bitset', table: 'query_bitset' },
+    { streamType: 'numeric_set', table: 'query_numeric_set' },
+];
+/**
+ * Build a SQL query that returns per-stream per-device data presence.
+ *
+ * Returns columns: device_id, stream_name, stream_type, data_points, first_seen, last_seen
+ */
+export function buildPresenceSQL(options) {
+    const { days = 7, deviceIds, limit = 500, streamNames, streamTypes } = options;
+    // Filter to requested stream types or use all
+    const tables = streamTypes
+        ? TELEMETRY_TABLES.filter((t) => streamTypes.includes(t.streamType))
+        : TELEMETRY_TABLES;
+    if (tables.length === 0) {
+        throw new Error(`No matching stream types. Valid types: ${TELEMETRY_TABLES.map((t) => t.streamType).join(', ')}`);
+    }
+    const deviceFilter = deviceIds?.length
+        ? `AND device_id IN (${deviceIds.map((id) => `'${id}'`).join(', ')})`
+        : '';
+    const nameFilter = streamNames?.length
+        ? `AND name IN (${streamNames.map((n) => `'${n}'`).join(', ')})`
+        : '';
+    const subqueries = tables.map(({ streamType, table }) => `SELECT device_id, name AS stream_name, '${streamType}' AS stream_type, ` +
+        `count(*) AS data_points, min(time) AS first_seen, max(time) AS last_seen ` +
+        `FROM ${table} ` +
+        `WHERE time > now() - INTERVAL ${days} DAY ${deviceFilter} ${nameFilter} ` +
+        `GROUP BY device_id, name`);
+    return (`SELECT device_id, stream_name, stream_type, data_points, first_seen, last_seen FROM (\n` +
+        subqueries.join('\nUNION ALL\n') +
+        `\n) ORDER BY last_seen DESC LIMIT ${limit}`);
+}
+/**
+ * Build a SQL query that returns the last time any data was seen per device.
+ *
+ * Returns columns: device_id, last_seen, total_points, stream_count
+ */
+export function buildLastSeenSQL(options) {
+    const { days = 30, deviceIds } = options;
+    const deviceFilter = deviceIds?.length
+        ? `AND device_id IN (${deviceIds.map((id) => `'${id}'`).join(', ')})`
+        : '';
+    const subqueries = TELEMETRY_TABLES.map(({ table }) => `SELECT device_id, max(time) AS last_seen, count(*) AS data_points, count(DISTINCT name) AS stream_count ` +
+        `FROM ${table} ` +
+        `WHERE time > now() - INTERVAL ${days} DAY ${deviceFilter} ` +
+        `GROUP BY device_id`);
+    return (`SELECT device_id, max(last_seen) AS last_seen, sum(data_points) AS total_points, sum(stream_count) AS stream_count FROM (\n` +
+        subqueries.join('\nUNION ALL\n') +
+        `\n) GROUP BY device_id ORDER BY last_seen DESC`);
+}
+/**
+ * Normalize a timestamp string from analytics SQL (e.g. "2026-02-19 23:37:04.747")
+ * to ISO 8601 format ("2026-02-19T23:37:04.747Z").
+ */
+export function toIsoDateTime(sqlTimestamp) {
+    if (!sqlTimestamp)
+        return sqlTimestamp;
+    // Already ISO
+    if (sqlTimestamp.includes('T'))
+        return sqlTimestamp;
+    // Replace first space with T, append Z if no timezone
+    const iso = sqlTimestamp.replace(' ', 'T');
+    return iso.endsWith('Z') ? iso : iso + 'Z';
+}
+export function getFreshness(lastSeenIso) {
+    const lastSeen = new Date(lastSeenIso).getTime();
+    const now = Date.now();
+    const hoursAgo = (now - lastSeen) / (1000 * 60 * 60);
+    if (hoursAgo < 1)
+        return 'active';
+    if (hoursAgo < 24)
+        return 'recent';
+    if (hoursAgo < 7 * 24)
+        return 'stale';
+    return 'dormant';
+}
+//# sourceMappingURL=presence.js.map

package/dist/lib/presence.js.map

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