@formo/cli 1.1.0 → 1.2.0

package/dist/lib/client.d.ts

@@ -1,4 +1,4 @@
-import { AxiosError } from 'axios';
+import { AxiosError, type AxiosInstance, type AxiosRequestConfig } from 'axios';
 export declare const DEFAULT_API_BASE_URL = "https://api.formo.so";
 export declare const DEFAULT_EVENTS_BASE_URL = "https://events.formo.so";
 export declare function getApiBaseUrl(): string;
@@ -32,7 +32,22 @@ export interface ClientOptions {
     baseURL?: string;
     apiKey?: string;
 }
-declare function createClient(options?: ClientOptions): import("axios").AxiosInstance;
-export declare function createEventsClient(writeKey: string): import("axios").AxiosInstance;
+/**
+ * The response interceptor below unwraps every response to its body
+ * (`res.data`), so the raw AxiosInstance types would lie — they promise
+ * `AxiosResponse<T>` while the runtime value is the body itself. This
+ * interface states what actually comes back.
+ */
+export interface FormoClient {
+    get(url: string, config?: AxiosRequestConfig): Promise<unknown>;
+    post(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<unknown>;
+    put(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<unknown>;
+    patch(url: string, data?: unknown, config?: AxiosRequestConfig): Promise<unknown>;
+    delete(url: string, config?: AxiosRequestConfig): Promise<unknown>;
+    request(config: AxiosRequestConfig): Promise<unknown>;
+    defaults: AxiosInstance['defaults'];
+}
+declare function createClient(options?: ClientOptions): FormoClient;
+export declare function createEventsClient(writeKey: string): FormoClient;
 export declare function requireApiKey(): void;
 export { createClient };

package/dist/lib/client.js

@@ -38,7 +38,9 @@ function parseApiError(error) {
         parts.push(`Param: ${apiError.param}`);
     if (apiError?.details && Object.keys(apiError.details).length > 0) {
         const details = Object.entries(apiError.details)
-            .map(([key, value]) => `${key}: ${String(value)}`)
+            .map(([key, value]) => `${key}: ${typeof value === 'object' && value !== null
+            ? JSON.stringify(value)
+            : String(value)}`)
             .join('; ');
         parts.push(`Details: ${details}`);
     }
@@ -57,17 +59,24 @@ function parseApiError(error) {
 function createClient(options = {}) {
     const apiKey = options.apiKey ?? (0, config_1.getApiKey)();
     const baseURL = options.baseURL ?? getApiBaseUrl();
+    // Fail here, not with a server-side 401: every authenticated command needs
+    // a key, and this guard catches call sites that forget requireApiKey().
+    if (!apiKey) {
+        throw new Error('No API key configured. Run `formo login <apiKey>` or set FORMO_API_KEY env var.');
+    }
     const instance = axios_1.default.create({
         baseURL,
         timeout: 30000,
         headers: {
             'Content-Type': 'application/json',
-            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+            Authorization: `Bearer ${apiKey}`,
         },
     });
     instance.interceptors.response.use((res) => res.data, (error) => {
         throw parseApiError(error);
     });
+    // The interceptor changes what the promise resolves to; the cast makes the
+    // public type match the runtime behavior (see FormoClient above).
     return instance;
 }
 function createEventsClient(writeKey) {

package/dist/lib/config.d.ts

@@ -1,3 +1,4 @@
+export declare function getConfigFile(): string;
 export interface FormoConfig {
     apiKey?: string;
     workspace?: string;

package/dist/lib/config.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfigFile = getConfigFile;
 exports.readConfig = readConfig;
 exports.saveConfig = saveConfig;
 exports.clearConfig = clearConfig;
@@ -10,12 +11,24 @@ exports.getApiKey = getApiKey;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
-const CONFIG_DIR = path_1.default.join(os_1.default.homedir(), '.config', 'formo');
-const CONFIG_FILE = path_1.default.join(CONFIG_DIR, 'config.json');
+// FORMO_CONFIG_DIR lets tests (and users) redirect config away from the real
+// ~/.config/formo — resolved lazily so a test can set it after import.
+function configDir() {
+    return (process.env.FORMO_CONFIG_DIR ?? path_1.default.join(os_1.default.homedir(), '.config', 'formo'));
+}
+function getConfigFile() {
+    return path_1.default.join(configDir(), 'config.json');
+}
 function readConfig() {
     try {
-        const raw = fs_1.default.readFileSync(CONFIG_FILE, 'utf-8');
-        return JSON.parse(raw);
+        const raw = fs_1.default.readFileSync(getConfigFile(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        // JSON.parse happily returns null/"abc"/[1] — treat anything that isn't a
+        // plain object as an empty config instead of crashing later callers.
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {};
+        }
+        return parsed;
     }
     catch {
         return {};
@@ -29,26 +42,27 @@ function saveConfig(updates) {
     // tool, another app under ~/.config) keeps its old, possibly
     // group/world-readable perms — leaking the plaintext API key on a
     // multi-user host. chmod unconditionally so 0o700/0o600 always holds.
-    fs_1.default.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
-    fs_1.default.chmodSync(CONFIG_DIR, 0o700);
-    fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), {
+    fs_1.default.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    fs_1.default.chmodSync(configDir(), 0o700);
+    fs_1.default.writeFileSync(getConfigFile(), JSON.stringify(merged, null, 2), {
         mode: 0o600,
     });
-    fs_1.default.chmodSync(CONFIG_FILE, 0o600);
+    fs_1.default.chmodSync(getConfigFile(), 0o600);
 }
 function clearConfig() {
     try {
-        if (fs_1.default.existsSync(CONFIG_FILE)) {
-            fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify({}, null, 2), {
-                mode: 0o600,
-            });
-            // Same create-only-mode caveat as saveConfig: enforce 0o600 on the
-            // already-existing file so the cleared config can't be left readable.
-            fs_1.default.chmodSync(CONFIG_FILE, 0o600);
-        }
+        fs_1.default.writeFileSync(getConfigFile(), JSON.stringify({}, null, 2), {
+            mode: 0o600,
+        });
+        // Same create-only-mode caveat as saveConfig: enforce 0o600 on the
+        // already-existing file so the cleared config can't be left readable.
+        fs_1.default.chmodSync(getConfigFile(), 0o600);
     }
-    catch {
-        // Ignore errors if file doesn't exist
+    catch (err) {
+        // Nothing to clear is fine; a real write failure (EACCES, EROFS) must
+        // surface so `formo logout` can't claim success while the key remains.
+        if (err.code !== 'ENOENT')
+            throw err;
     }
 }
 function getApiKey() {

package/dist/lib/filters.d.ts

@@ -0,0 +1,6 @@
+export declare const CANONICAL_FILTER_OPERATORS: readonly ["eq", "neq", "gt", "lt", "gte", "lte", "in", "nin", "startsWith", "endsWith", "contains", "notEmpty", "isEmpty"];
+export declare function isCanonicalFilterOperator(op: unknown): op is string;
+export declare function isValuelessFilterOperator(op: unknown): boolean;
+export declare function isCanonicalFilterValue(value: unknown): boolean;
+export declare function isEmptyMembershipArray(value: unknown): boolean;
+export declare function hasTinybirdMembershipDelimiter(value: unknown): boolean;

package/dist/lib/filters.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_FILTER_OPERATORS = void 0;
+exports.isCanonicalFilterOperator = isCanonicalFilterOperator;
+exports.isValuelessFilterOperator = isValuelessFilterOperator;
+exports.isCanonicalFilterValue = isCanonicalFilterValue;
+exports.isEmptyMembershipArray = isEmptyMembershipArray;
+exports.hasTinybirdMembershipDelimiter = hasTinybirdMembershipDelimiter;
+exports.CANONICAL_FILTER_OPERATORS = [
+    'eq',
+    'neq',
+    'gt',
+    'lt',
+    'gte',
+    'lte',
+    'in',
+    'nin',
+    'startsWith',
+    'endsWith',
+    'contains',
+    'notEmpty',
+    'isEmpty',
+];
+const CANONICAL_FILTER_OPERATOR_SET = new Set(exports.CANONICAL_FILTER_OPERATORS);
+function isCanonicalFilterOperator(op) {
+    return typeof op === 'string' && CANONICAL_FILTER_OPERATOR_SET.has(op);
+}
+function isValuelessFilterOperator(op) {
+    return op === 'notEmpty' || op === 'isEmpty';
+}
+function isCanonicalFilterValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        (Array.isArray(value) &&
+            value.length > 0 &&
+            value.every((item) => typeof item === 'string' || typeof item === 'number')));
+}
+function isEmptyMembershipArray(value) {
+    return Array.isArray(value) && value.length === 0;
+}
+function hasTinybirdMembershipDelimiter(value) {
+    return (Array.isArray(value) &&
+        value.some((item) => typeof item === 'string' && item.includes('|')));
+}

package/dist/lib/pagination.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'incur';
+export interface PaginationOptions {
+    page?: number;
+    size?: number;
+}
+/**
+ * Shared zod fragments for paginated list commands.
+ * Spread into a command's options: `z.object({ ...paginationOptionsSchema })`.
+ */
+export declare const paginationOptionsSchema: {
+    page: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    size: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+};
+export declare function buildPaginationParams(options?: PaginationOptions): Record<string, number>;

package/dist/lib/pagination.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.paginationOptionsSchema = void 0;
+exports.buildPaginationParams = buildPaginationParams;
+const incur_1 = require("incur");
+/**
+ * Shared zod fragments for paginated list commands.
+ * Spread into a command's options: `z.object({ ...paginationOptionsSchema })`.
+ */
+exports.paginationOptionsSchema = {
+    page: incur_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Page number (1-indexed, default 1)'),
+    size: incur_1.z.coerce
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Page size (default 100, max 200)'),
+};
+function buildPaginationParams(options = {}) {
+    const params = {};
+    if (options.page !== undefined)
+        params.page = options.page;
+    if (options.size !== undefined)
+        params.size = options.size;
+    return params;
+}

package/dist/lib/ui.d.ts

@@ -2,8 +2,9 @@
  * Terminal UI utilities for the Formo CLI.
  *
  * Uses raw ANSI escape codes (no dependencies) for coloring and styling.
- * Colors are automatically disabled when stdout is not a TTY (piped output, CI, etc.)
- * or when the NO_COLOR environment variable is set.
+ * All decorated output is written to stderr (stdout is reserved for command
+ * results), so color is keyed to stderr being a TTY. Disabled whenever the
+ * NO_COLOR environment variable is present (any value, per the spec).
  */
 export declare const color: {
     green: (t: string) => string;
@@ -20,12 +21,12 @@ export declare const color: {
 };
 /**
  * Returns the Formo ASCII art banner in green.
- * Only shown when stdout is a TTY.
+ * Only shown when stderr is a TTY.
  */
 export declare function banner(): string;
 export declare function success(message: string): string;
 export declare function error(message: string): string;
 export declare function warn(message: string): string;
 export declare function info(message: string): string;
-export declare function keyValue(key: string, value: string): string;
-export declare function heading(text: string): string;
+/** Mask an API key for display, keeping just enough to identify it. */
+export declare function maskKey(key: string): string;

package/dist/lib/ui.js

@@ -3,8 +3,9 @@
  * Terminal UI utilities for the Formo CLI.
  *
  * Uses raw ANSI escape codes (no dependencies) for coloring and styling.
- * Colors are automatically disabled when stdout is not a TTY (piped output, CI, etc.)
- * or when the NO_COLOR environment variable is set.
+ * All decorated output is written to stderr (stdout is reserved for command
+ * results), so color is keyed to stderr being a TTY. Disabled whenever the
+ * NO_COLOR environment variable is present (any value, per the spec).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.color = void 0;
@@ -13,10 +14,9 @@ exports.success = success;
 exports.error = error;
 exports.warn = warn;
 exports.info = info;
-exports.keyValue = keyValue;
-exports.heading = heading;
-const isTTY = process.stdout.isTTY === true;
-const noColor = !!process.env.NO_COLOR;
+exports.maskKey = maskKey;
+const isTTY = process.stderr.isTTY === true;
+const noColor = process.env.NO_COLOR !== undefined;
 /** Whether color output is enabled */
 const colorEnabled = isTTY && !noColor;
 // ── ANSI helpers ──
@@ -47,7 +47,7 @@ const LOGO_LINES = [
 ];
 /**
  * Returns the Formo ASCII art banner in green.
- * Only shown when stdout is a TTY.
+ * Only shown when stderr is a TTY.
  */
 function banner() {
     if (!isTTY)
@@ -71,9 +71,7 @@ function info(message) {
     return `${exports.color.cyan('ℹ')} ${message}`;
 }
 // ── Formatting helpers ──
-function keyValue(key, value) {
-    return `${exports.color.dim(key + ':')} ${value}`;
-}
-function heading(text) {
-    return exports.color.boldGreen(text);
+/** Mask an API key for display, keeping just enough to identify it. */
+function maskKey(key) {
+    return key.length > 12 ? key.slice(0, 8) + '…' + key.slice(-4) : '***';
 }

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@formo/cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "packageManager": "pnpm@11.1.2",
+  "engines": {
+    "node": ">=22.12"
+  },
   "description": "Formo API CLI — query profiles and analytics data",
   "license": "MIT",
   "repository": {
@@ -22,19 +25,18 @@
   ],
   "scripts": {
     "build": "tsc",
-    "dev": "ts-node src/index.ts",
+    "prepublishOnly": "pnpm build",
+    "dev": "tsx src/index.ts",
     "start": "node dist/index.js",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
     "test": "mocha",
     "test:watch": "mocha --watch"
   },
   "dependencies": {
     "axios": "^1.18.0",
-    "incur": "^0.3.4"
-  },
-  "overrides": {
-    "serialize-javascript": ">=7.0.5"
+    "incur": "0.3.25"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
@@ -46,14 +48,8 @@
     "eslint": "^10.2.0",
     "globals": "^17.4.0",
     "mocha": "^11.7.5",
-    "ts-node": "^10.9.2",
     "tsx": "^4.21.0",
     "typescript": "^5.5.4",
     "typescript-eslint": "^8.58.1"
-  },
-  "pnpm": {
-    "overrides": {
-      "serialize-javascript": ">=7.0.5"
-    }
   }
 }