@thinremote/thinr-cli 1.2.0-alpha.1 → 1.3.0

package/lib/agent-releases.js

@@ -0,0 +1,59 @@
+// @ts-check
+
+/**
+ * Small helper that talks to the public release CDN at
+ * `https://get.thinremote.io/<channel>.json`. Same file the agent itself
+ * polls to decide whether a self-update is available — keeping a single
+ * source of truth between what the CLI offers and what a device would
+ * actually download if the user ran `thinr device update apply`.
+ *
+ * Why a dedicated module: the TUI hook (`useLatestAgentVersion`) needed
+ * React-aware polling, the CLI just wants a one-shot fetch. Sharing the
+ * URL and the response shape here avoids drift if we ever add fields
+ * (signing keys, min-supported-version, etc.) to the JSON.
+ */
+
+const CDN_BASE = 'https://get.thinremote.io';
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+/**
+ * Fetch the release descriptor for a channel.
+ * @param {object} [opts]
+ * @param {string} [opts.channel='latest']  Release channel — matches the
+ *   filenames under get.thinremote.io (`latest.json`, `main.json`,
+ *   `develop.json`). Per-version archives are not exposed here; devices
+ *   resolve those through the channel metadata themselves.
+ * @param {number} [opts.timeoutMs]  Hard cap on the network call. 5s is
+ *   plenty for a 1 KB JSON off a global CDN; anything slower is a DNS or
+ *   connectivity issue that should fail fast rather than stall the CLI.
+ * @returns {Promise<{version: string, checksums?: Record<string,string>}>}
+ */
+export async function fetchReleaseDescriptor({
+    channel = 'latest',
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+    const url = `${CDN_BASE}/${encodeURIComponent(channel)}.json`;
+    const controller = new AbortController();
+    const to = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { signal: controller.signal });
+        if (!res.ok) {
+            throw new Error(
+                `release descriptor fetch failed: ${res.status} ${res.statusText}`,
+            );
+        }
+        const data = await res.json();
+        if (!data?.version) {
+            throw new Error('release descriptor missing `version` field');
+        }
+        return data;
+    } finally {
+        clearTimeout(to);
+    }
+}
+
+/** Convenience: just the version string. */
+export async function fetchLatestAgentVersion(opts) {
+    const { version } = await fetchReleaseDescriptor(opts);
+    return version;
+}

package/lib/agent-versions.js

@@ -0,0 +1,73 @@
+// @ts-check
+
+/**
+ * Agent-version helpers shared between the TUI (`src/dashboard/`) and the
+ * CLI commands. Kept in plain Node-compatible JS so both the bundled
+ * dashboard and the un-bundled CLI can import directly.
+ *
+ * The agent reports its version as a git-describe string (e.g.
+ * `v1.6.5-2-g7c3d192` for a dev build off `v1.6.5`). Grouping those
+ * together by release tag gives a readable rollout picture without an
+ * explosion of near-identical rows.
+ */
+
+/** Drop the git-describe suffix so dev builds group with their release. */
+export function normalizeAgentVersion(raw) {
+    if (!raw) return null;
+    const m = String(raw).match(/^(v?\d+\.\d+\.\d+)/);
+    return m ? m[1] : raw;
+}
+
+function semverTriple(v) {
+    if (!v) return null;
+    const m = String(v).match(/^v?(\d+)\.(\d+)\.(\d+)/);
+    if (!m) return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * Descending comparator — newer first. Non-semver values sink to the
+ * bottom alphabetically, so rogue strings never claim "newest".
+ */
+export function compareAgentVersions(a, b) {
+    const ta = semverTriple(a);
+    const tb = semverTriple(b);
+    if (ta && tb) {
+        for (let i = 0; i < 3; i++) {
+            if (ta[i] !== tb[i]) return tb[i] - ta[i];
+        }
+        return 0;
+    }
+    if (ta) return -1;
+    if (tb) return 1;
+    return String(b).localeCompare(String(a));
+}
+
+/**
+ * Partition a map of `deviceId -> reported-version-string` against a
+ * target version.
+ *
+ * Returns:
+ *   - `outdated`: device IDs strictly older than `target`
+ *   - `current`:  device IDs already at `target`
+ *   - `unknown`:  device IDs we have no version for (never reported a
+ *     sample, or reported a non-parseable string). These are *not*
+ *     upgraded by default — we don't want to "fix" something we can't
+ *     identify.
+ */
+export function classifyAgainst(target, deviceVersions) {
+    const outdated = [];
+    const current = [];
+    const unknown = [];
+    for (const [id, raw] of Object.entries(deviceVersions)) {
+        const v = normalizeAgentVersion(raw);
+        if (!v) {
+            unknown.push(id);
+            continue;
+        }
+        const d = compareAgentVersions(v, target);
+        if (d > 0) outdated.push(id);
+        else current.push(id);
+    }
+    return { outdated, current, unknown };
+}

package/lib/alarms.js

@@ -0,0 +1,252 @@
+import api from './api.js';
+import { apiError } from './errors.js';
+import { requireConfig } from './config.js';
+
+function resolveUser(user) {
+    return user || requireConfig().username;
+}
+
+// Backend enums (see backend/src/thinger/features/alarms/alarm_rule.hpp).
+// Exported so the dashboard can render labels/colors without re-deriving
+// them from string heuristics.
+export const ALARM_STATE = {
+    NONE: 0,
+    ACTIVATED: 1,
+    ACKNOWLEDGED: 2,
+    LATCHED: 3,
+    SHELVED: 4,
+    CLEARED: 5,
+};
+
+export const ALARM_SEVERITY = {
+    NONE: 0,
+    LOW: 1,
+    MEDIUM: 2,
+    HIGH: 3,
+    CRITICAL: 4,
+};
+
+export const ALARM_STATE_LABEL = {
+    0: 'none',
+    1: 'active',
+    2: 'ack',
+    3: 'latched',
+    4: 'shelved',
+    5: 'cleared',
+};
+
+export const ALARM_SEVERITY_LABEL = {
+    0: 'none',
+    1: 'low',
+    2: 'med',
+    3: 'high',
+    4: 'crit',
+};
+
+// Reverse maps so callers can pass human-readable strings ("ack", "shelved",
+// "high", …) instead of remembering the numeric enum values.
+const STATE_FROM_LABEL = {
+    none: ALARM_STATE.NONE,
+    active: ALARM_STATE.ACTIVATED,
+    activated: ALARM_STATE.ACTIVATED,
+    ack: ALARM_STATE.ACKNOWLEDGED,
+    acknowledged: ALARM_STATE.ACKNOWLEDGED,
+    latched: ALARM_STATE.LATCHED,
+    shelved: ALARM_STATE.SHELVED,
+    cleared: ALARM_STATE.CLEARED,
+};
+
+const SEVERITY_FROM_LABEL = {
+    none: ALARM_SEVERITY.NONE,
+    low: ALARM_SEVERITY.LOW,
+    med: ALARM_SEVERITY.MEDIUM,
+    medium: ALARM_SEVERITY.MEDIUM,
+    high: ALARM_SEVERITY.HIGH,
+    crit: ALARM_SEVERITY.CRITICAL,
+    critical: ALARM_SEVERITY.CRITICAL,
+};
+
+export function parseAlarmState(value) {
+    if (value == null) return undefined;
+    if (typeof value === 'number') return value;
+    const key = String(value).trim().toLowerCase();
+    return STATE_FROM_LABEL[key];
+}
+
+export function parseAlarmSeverity(value) {
+    if (value == null) return undefined;
+    if (typeof value === 'number') return value;
+    const key = String(value).trim().toLowerCase();
+    return SEVERITY_FROM_LABEL[key];
+}
+
+// Repeats a query param as the server expects (`?state=1&state=2`).
+function appendMulti(params, key, values) {
+    if (values == null) return;
+    const arr = Array.isArray(values) ? values : [values];
+    for (const v of arr) params.append(key, String(v));
+}
+
+/**
+ * Query alarm instances from /v1/users/{user}/alarms/instances.
+ *
+ * `state` and `severity` are repeated query params — pass numbers or
+ * arrays of numbers (matching the ALARM_STATE / ALARM_SEVERITY enums).
+ *
+ * @param {{
+ *   user?: string | null,
+ *   count?: number,
+ *   index?: number,
+ *   name?: string,
+ *   state?: number | number[],
+ *   severity?: number | number[],
+ *   sort?: string,
+ *   order?: string,
+ * }} [opts]
+ */
+export async function getAlarmInstances({
+    user = null,
+    count = 100,
+    index = 0,
+    name,
+    state,
+    severity,
+    sort,
+    order,
+} = {}) {
+    const apiUser = resolveUser(user);
+    const params = new URLSearchParams();
+    params.set('count', String(count));
+    params.set('index', String(index));
+    if (name) params.set('name', name);
+    if (sort) params.set('sort', sort);
+    if (order) params.set('order', order);
+    appendMulti(params, 'state', state);
+    appendMulti(params, 'severity', severity);
+    try {
+        const res = await api.get(
+            `/v1/users/${apiUser}/alarms/instances?${params.toString()}`,
+        );
+        return Array.isArray(res.data) ? res.data : [];
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+// Counter per state, e.g. { activated: 3, acknowledged: 1, ... }. The
+// server seeds zeros for every known state so consumers can render a
+// stable layout without null-checks.
+export async function getAlarmInstanceStats({ user = null } = {}) {
+    const apiUser = resolveUser(user);
+    try {
+        const res = await api.get(`/v1/users/${apiUser}/alarms/instances/stats`);
+        return res.data || {};
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function getAlarmInstance(instance, { user = null } = {}) {
+    const apiUser = resolveUser(user);
+    try {
+        const res = await api.get(
+            `/v1/users/${apiUser}/alarms/instances/${encodeURIComponent(instance)}`,
+        );
+        return res.data;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm instance not found: ${instance}` });
+    }
+}
+
+// PUT-style update. The server accepts only a small whitelist of fields
+// (see UPDATE_SCHEMA in alarms_instances.cpp): name, description, state,
+// annotation, reactivation. Anything else is rejected.
+export async function updateAlarmInstance(instance, body, { user = null } = {}) {
+    const apiUser = resolveUser(user);
+    try {
+        const res = await api.put(
+            `/v1/users/${apiUser}/alarms/instances/${encodeURIComponent(instance)}`,
+            body,
+        );
+        return res.data;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm instance not found: ${instance}` });
+    }
+}
+
+export async function deleteAlarmInstance(instance, { user = null } = {}) {
+    const apiUser = resolveUser(user);
+    try {
+        await api.delete(
+            `/v1/users/${apiUser}/alarms/instances/${encodeURIComponent(instance)}`,
+        );
+        return true;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm instance not found: ${instance}` });
+    }
+}
+
+export async function getAlarmRules({ user = null, count = 200, index = 0 } = {}) {
+    const apiUser = resolveUser(user);
+    const params = new URLSearchParams();
+    params.set('count', String(count));
+    params.set('index', String(index));
+    try {
+        const res = await api.get(
+            `/v1/users/${apiUser}/alarms/rules?${params.toString()}`,
+        );
+        return Array.isArray(res.data) ? res.data : [];
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function getAlarmRule(rule, { user = null } = {}) {
+    const apiUser = resolveUser(user);
+    try {
+        const res = await api.get(
+            `/v1/users/${apiUser}/alarms/rules/${encodeURIComponent(rule)}`,
+        );
+        return res.data;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm rule not found: ${rule}` });
+    }
+}
+
+// POST /v1/users/{user}/alarms/rules. The body must include `rule`,
+// `name`, `enabled` and an optional `config` object — see CREATE_SCHEMA
+// in alarms_rules.cpp for the full shape.
+export async function createAlarmRule(body, { user = null } = {}) {
+    const apiUser = resolveUser(user);
+    try {
+        const res = await api.post(`/v1/users/${apiUser}/alarms/rules`, body);
+        return res.data;
+    } catch (e) {
+        throw apiError(e);
+    }
+}
+
+export async function updateAlarmRule(rule, body, { user = null } = {}) {
+    const apiUser = resolveUser(user);
+    try {
+        const res = await api.put(
+            `/v1/users/${apiUser}/alarms/rules/${encodeURIComponent(rule)}`,
+            body,
+        );
+        return res.data;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm rule not found: ${rule}` });
+    }
+}
+
+export async function deleteAlarmRule(rule, { user = null } = {}) {
+    const apiUser = resolveUser(user);
+    try {
+        await api.delete(
+            `/v1/users/${apiUser}/alarms/rules/${encodeURIComponent(rule)}`,
+        );
+        return true;
+    } catch (e) {
+        throw apiError(e, { notFound: `Alarm rule not found: ${rule}` });
+    }
+}

package/lib/api.js

@@ -1,6 +1,7 @@
 import axios from 'axios';
 import { refreshToken, getAccessToken } from './auth.js';
 import { readConfig } from './config.js';
+import { TIMEOUTS } from './constants.js';
 import http from 'http';
 import https from 'https';
 
@@ -13,7 +14,7 @@ const insecureAgent = new https.Agent({ keepAlive: true, rejectUnauthorized: fal
 
 const api = axios.create({
     // You can leave baseURL undefined initially
-    timeout: 10000,
+    timeout: TIMEOUTS.API_DEFAULT_MS,
     httpAgent,
     httpsAgent,
 });
@@ -31,6 +32,9 @@ api.interceptors.request.use(
 
         // Allow self-signed TLS against localhost / 127.0.0.1 or when the user
         // opts in explicitly. Anything else keeps default certificate validation.
+        // A malformed URL here is not worth aborting the request over — the
+        // HTTPS layer will surface the real error downstream; we only care
+        // about detecting localhost cheaply.
         try {
             const base = request.baseURL || api.defaults.baseURL || '';
             const url = new URL(request.url || '', base || 'https://placeholder/');
@@ -38,7 +42,9 @@ api.interceptors.request.use(
             if (url.protocol === 'https:' && (isLocal || process.env.THINR_INSECURE === '1')) {
                 request.httpsAgent = insecureAgent;
             }
-        } catch {}
+        } catch {
+            // Intentionally swallowed — see note above.
+        }
 
         return request;
     },

package/lib/auth.js

@@ -1,25 +1,25 @@
 import { Buffer } from 'node:buffer';
 import { input, select } from '@inquirer/prompts';
-import chalk from 'chalk';
 import ora from 'ora';
 import open, { apps } from 'open';
 import { writeConfig, readConfig, mergeConfig } from './config.js';
+import { label, success, warning, error as errorStyle, info } from './format.js';
 
 import api, { setBaseURL } from './api.js';
+import { OAUTH, TIMEOUTS } from './constants.js';
 
-// OAuth device-flow client identifier registered for this CLI on the
-// ThinRemote OAuth provider. Stable across versions.
-const OAUTH_CLIENT_ID = '3b40164d28730e416cbd';
-
-// Hard ceiling on how long to keep polling for the user to finish the
-// device-code flow in the browser before we give up (10 minutes).
-const OAUTH_DEVICE_CODE_TIMEOUT_MS = 10 * 60 * 1000;
+const OAUTH_CLIENT_ID = OAUTH.CLIENT_ID;
+const OAUTH_DEVICE_CODE_TIMEOUT_MS = TIMEOUTS.OAUTH_DEVICE_CODE_MS;
 
 /**
  * Authenticate user
  * @returns {Promise<void>}
  */
 export async function authenticate() {
+    // When re-authenticating an existing profile, default the server prompt
+    // to the one already stored so `thinr login` is a couple of keystrokes.
+    const existing = readConfig();
+
     // Ask for authentication method
     const method = await select({
         message: 'How would you like to authenticate?',
@@ -33,7 +33,7 @@ export async function authenticate() {
     // Ask for server URL
     const server = await input({
         message: 'Enter server URL:',
-        default: 'console.thinr.io',
+        default: existing?.server || 'console.thinr.io',
         validate: (input) => {
             return input ? true : 'Server URL is required';
         },
@@ -134,12 +134,29 @@ async function authenticateWithUserPass() {
  * when the OAuth server rejects the refresh — both cases mean the
  * caller has to re-authenticate.
  *
+ * Concurrent callers share a single in-flight refresh: refresh tokens
+ * are rotated on use, so issuing two refreshes in parallel makes the
+ * second one fail against an already-consumed token. The shared
+ * promise lets every awaiter see the same result and lets the next
+ * caller (after completion) start a new refresh against the freshly
+ * persisted token.
+ *
  * @returns {Promise<string>} The new access token.
  */
+let inFlightRefresh = null;
+
 export async function refreshToken() {
+    if (inFlightRefresh) return inFlightRefresh;
+    inFlightRefresh = doRefresh().finally(() => {
+        inFlightRefresh = null;
+    });
+    return inFlightRefresh;
+}
+
+async function doRefresh() {
     const config = readConfig();
     if (!config.refresh_token) {
-        const err = new Error('No refresh token available; re-authenticate with `thinr`.');
+        const err = new Error('Session expired. Run `thinr login` to sign in again.');
         err.code = 'unauthorized';
         throw err;
     }
@@ -159,7 +176,7 @@ export async function refreshToken() {
             _isRefresh: true,
         });
     } catch (_error) {
-        const err = new Error('Token refresh failed; re-authenticate with `thinr`.');
+        const err = new Error('Session expired. Run `thinr login` to sign in again.');
         err.code = 'unauthorized';
         throw err;
     }
@@ -171,6 +188,37 @@ export async function refreshToken() {
     return response.data.access_token;
 }
 
+/**
+ * Milliseconds-since-epoch expiry of a JWT access token, or null when
+ * the token is not a decodable JWT (permanent API tokens have no exp).
+ */
+function jwtExpiryMs(token) {
+    try {
+        const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64').toString());
+        return typeof payload.exp === 'number' ? payload.exp * 1000 : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Return a currently-valid access token, refreshing first when the
+ * stored one is an expired (or about-to-expire) JWT. HTTP requests
+ * recover from expiry through the api.js response interceptor, but
+ * WebSocket handshakes have no retry layer: callers opening a WS use
+ * this to start from a valid token. Tokens without a decodable `exp`
+ * and profiles without a refresh_token pass through untouched.
+ */
+export async function ensureFreshToken() {
+    const config = readConfig();
+    if (!config?.token || !config.refresh_token) return config?.token ?? null;
+    const expiresAt = jwtExpiryMs(config.token);
+    if (expiresAt === null || expiresAt - Date.now() > TIMEOUTS.TOKEN_EXPIRY_SLACK_MS) {
+        return config.token;
+    }
+    return refreshToken();
+}
+
 /**
  * Delete user token from server
  * @returns {Promise<void>}
@@ -179,7 +227,7 @@ export async function deleteToken() {
     try {
         const config = readConfig();
         if (!config || !config.username || !config.server || !config.token) {
-            console.log(chalk.yellow('No configuration found'));
+            console.log(warning('No configuration found'));
             return;
         }
 
@@ -193,11 +241,11 @@ export async function deleteToken() {
                 spinner.succeed('Token was already deleted');
             } else {
                 spinner.fail('Failed to delete token');
-                console.error(chalk.red(`Error: ${error.message}`));
+                console.error(errorStyle(`Error: ${error.message}`));
             }
         }
     } catch (error) {
-        console.error(chalk.red(`Error: ${error.message}`));
+        console.error(errorStyle(`Error: ${error.message}`));
     }
 }
 
@@ -258,9 +306,9 @@ async function authenticateWithOAuth() {
         throw error;
     }
 
-    console.log('\nYour one time device code is: ' + chalk.bold(data.user_code));
+    console.log('\nYour one time device code is: ' + label(data.user_code));
     console.log(
-        chalk.blue('Press ' + chalk.bold('ENTER')) +
+        info('Press ' + label('ENTER')) +
             ' to open your browser or submit your device code here: ' +
             data.verification_uri +
             '\n',
@@ -342,9 +390,9 @@ async function authenticateWithOAuth() {
             },
         ).catch((error) => {
             if (error.cause === 'timeout') {
-                console.log(chalk.yellow('Polling aborted due to timeout'));
+                console.log(warning('Polling aborted due to timeout'));
             } else if (error.cause === 'validated') {
-                console.log(chalk.green('Device authenticated successfully'));
+                console.log(success('Device authenticated successfully'));
             }
             // 'error' cause falls through; we surface pollError below.
         });
@@ -362,7 +410,7 @@ async function authenticateWithOAuth() {
     const username = decodedJWT.usr;
 
     mergeConfig({ username, token, refresh_token });
-    console.log(chalk.green('OAuth token validation successful\n'));
+    console.log(success('OAuth token validation successful\n'));
 }
 
 /**
@@ -372,7 +420,7 @@ async function authenticateWithOAuth() {
 export function getAccessToken() {
     const config = readConfig();
     if (!config || !config.token) {
-        console.log(chalk.yellow('No token found in configuration'));
+        console.log(warning('No token found in configuration'));
         return null;
     }
     return config.token;

package/lib/bucket.js

@@ -0,0 +1,87 @@
+import api from './api.js';
+import { apiError } from './errors.js';
+import { requireConfig } from './config.js';
+
+function resolveUser(user) {
+    return user || requireConfig().username;
+}
+
+/**
+ * Query an arbitrary time-series bucket declared in a product profile.
+ * When `device` is provided, scopes to that device's bucket; otherwise
+ * queries the user-level bucket across every device of the account.
+ *
+ * Buckets are the mechanism products use to persist structured samples
+ * over time — the platform ships a `monitoring` bucket by default, and
+ * users can declare custom ones for their own metrics.
+ *
+ * Time range:
+ *   - `minutes`: shortcut for "last N minutes" (sets min_ts to
+ *     `Date.now() - minutes * 60_000`, max_ts to 0).
+ *   - `min_ts` / `max_ts`: explicit unix-millis range when `minutes`
+ *     is not supplied; either may be omitted for an open bound.
+ *
+ * Aggregation: `agg` is the time-window size (e.g. "5m"), `agg_type`
+ * the reducer (e.g. "mean"), and `fields` a comma-separated allowlist
+ * to trim the response down.
+ *
+ * `group_by` is passed through verbatim — no default. Custom buckets
+ * may not even expose a `device` tag, so the caller decides whether
+ * to group (e.g. `group_by=device` for a fleet view) or read raw
+ * interleaved samples.
+ *
+ * @param {{
+ *   bucket: string,
+ *   device?: string | null,
+ *   user?: string | null,
+ *   items?: number,
+ *   sort?: string,
+ *   minutes?: number,
+ *   min_ts?: number,
+ *   max_ts?: number,
+ *   agg?: string,
+ *   agg_type?: string,
+ *   fields?: string,
+ *   group_by?: string | null,
+ * }} opts
+ */
+export async function getBucketData({
+    bucket,
+    device = null,
+    user = null,
+    items = 10,
+    sort = 'desc',
+    minutes,
+    min_ts,
+    max_ts,
+    agg,
+    agg_type,
+    fields,
+    group_by,
+} = {}) {
+    if (!bucket) throw new Error('bucket is required');
+    const apiUser = resolveUser(user);
+    const params = { items, sort };
+    if (minutes) {
+        params.min_ts = Date.now() - minutes * 60 * 1000;
+        params.max_ts = 0;
+    } else {
+        if (min_ts) params.min_ts = min_ts;
+        if (max_ts !== undefined) params.max_ts = max_ts;
+    }
+    if (agg) params.agg = agg;
+    if (agg_type) params.agg_type = agg_type;
+    if (group_by) params.group_by = group_by;
+    if (fields) params.fields = fields;
+
+    const url = device
+        ? `/v3/users/${apiUser}/devices/${device}/buckets/${bucket}/data`
+        : `/v2/users/${apiUser}/buckets/${bucket}/data`;
+
+    try {
+        const res = await api.get(url, { params });
+        return res.data;
+    } catch (e) {
+        throw apiError(e);
+    }
+}