@formo/cli 0.1.0

package/dist/index.js

@@ -0,0 +1,270 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const incur_1 = require("incur");
+const alerts_1 = require("./commands/alerts");
+const boards_1 = require("./commands/boards");
+const charts_1 = require("./commands/charts");
+const contracts_1 = require("./commands/contracts");
+const import_1 = require("./commands/import");
+const profiles_1 = require("./commands/profiles");
+const query_1 = require("./commands/query");
+const segments_1 = require("./commands/segments");
+const config_1 = require("./lib/config");
+const ui_1 = require("./lib/ui");
+const DASHBOARD_URL = 'https://app.formo.so';
+const DOCS_URL = 'https://docs.formo.so';
+const API_BASE_URL = 'https://api.formo.so';
+function loginGuide() {
+    return [
+        '',
+        ui_1.color.boldGreen('How to get your API key:'),
+        '',
+        `  ${ui_1.color.white('1.')} Go to ${ui_1.color.cyan(DASHBOARD_URL)}`,
+        `  ${ui_1.color.white('2.')} Navigate to ${ui_1.color.bold('Settings')} → ${ui_1.color.bold('API Keys')}`,
+        `  ${ui_1.color.white('3.')} Click ${ui_1.color.bold('"Create API Key"')} and copy the key`,
+        `  ${ui_1.color.white('4.')} Run:`,
+        '',
+        `     ${ui_1.color.green('formo login <formo_your_api_key_here>')}`,
+        '',
+        ui_1.color.dim(`  Or set the environment variable:`),
+        '',
+        `     ${ui_1.color.green('export FORMO_API_KEY=formo_your_api_key_here')}`,
+        '',
+        ui_1.color.dim(`  Docs: ${DOCS_URL}`),
+        '',
+    ].join('\n');
+}
+async function validateAndFetchWorkspace(apiKey) {
+    try {
+        const res = await fetch(`${API_BASE_URL}/api/validate-api-key`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ apiKey }),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        if (!body.isSuccess || !body.data)
+            return null;
+        return {
+            workspace: body.data.details,
+            projectId: body.data.scopes?.project_id ?? '',
+        };
+    }
+    catch {
+        return null;
+    }
+}
+const cli = incur_1.Cli.create('formo', {
+    version: '0.1.0',
+    description: 'Formo API CLI — Web3 analytics from the terminal',
+    sync: {
+        suggestions: [
+            'get the profile for wallet 0xabc',
+            'search profiles with net worth > 10000',
+            'run a SQL query on my analytics data',
+            'search profiles ordered by last_onchain desc',
+            'list all project alerts',
+            'create an alert for high-value transactions',
+            'list all dashboard boards',
+            'list charts in a board',
+            'list all tracked contracts',
+            'register a new smart contract',
+            'list user segments',
+            'import wallet addresses',
+        ],
+    },
+});
+// ── login ──
+cli.command('login', {
+    description: 'Authenticate with your Formo API key',
+    args: incur_1.z.object({
+        apiKey: incur_1.z.string().optional().describe('Your formo_ API key'),
+    }),
+    options: incur_1.z.object({}),
+    examples: [
+        { args: { apiKey: 'formo_abc123' }, description: 'Save API key' },
+    ],
+    async run({ args }) {
+        // No key provided → show guide
+        if (!args.apiKey) {
+            if (process.stdout.isTTY) {
+                process.stderr.write(loginGuide());
+            }
+            return { ok: false, message: 'No API key provided. See guide above.' };
+        }
+        const isTTY = process.stdout.isTTY;
+        // Validate the key against the API
+        if (isTTY) {
+            process.stderr.write('\n' + ui_1.color.dim('Validating API key…') + '\n');
+        }
+        const workspaceInfo = await validateAndFetchWorkspace(args.apiKey);
+        // Save key + workspace info (save even if validation fails — user might be offline)
+        // Only include workspace/projectId when present so offline logins don't wipe existing values
+        (0, config_1.saveConfig)({
+            apiKey: args.apiKey,
+            ...(workspaceInfo?.workspace !== undefined && { workspace: workspaceInfo.workspace }),
+            ...(workspaceInfo?.projectId !== undefined && { projectId: workspaceInfo.projectId }),
+        });
+        // Show feedback in human mode
+        if (isTTY) {
+            const masked = args.apiKey.length > 12
+                ? args.apiKey.slice(0, 8) + '…' + args.apiKey.slice(-4)
+                : '***';
+            if (workspaceInfo) {
+                process.stderr.write((0, ui_1.success)('API key validated and saved!') +
+                    '\n' +
+                    (0, ui_1.info)(`Key: ${ui_1.color.dim(masked)}`) +
+                    '\n' +
+                    (0, ui_1.info)(`Workspace: ${ui_1.color.bold(workspaceInfo.workspace)}`) +
+                    '\n' +
+                    (workspaceInfo.projectId
+                        ? (0, ui_1.info)(`Project: ${ui_1.color.dim(workspaceInfo.projectId)}`) + '\n'
+                        : '') +
+                    (0, ui_1.info)(`Config: ${ui_1.color.dim('~/.config/formo/config.json')}`) +
+                    '\n\n' +
+                    ui_1.color.dim('You can now use all formo commands.') +
+                    '\n' +
+                    ui_1.color.dim('Run ') +
+                    ui_1.color.green('formo --help') +
+                    ui_1.color.dim(' to see available commands.') +
+                    '\n\n');
+            }
+            else {
+                process.stderr.write((0, ui_1.warn)('API key saved but could not be validated.') +
+                    '\n' +
+                    (0, ui_1.info)(`Key: ${ui_1.color.dim(masked)}`) +
+                    '\n' +
+                    (0, ui_1.info)(`Config: ${ui_1.color.dim('~/.config/formo/config.json')}`) +
+                    '\n' +
+                    ui_1.color.dim('The API might be unreachable. Your key is saved and will be used for requests.') +
+                    '\n\n');
+            }
+        }
+        return {
+            ok: true,
+            message: workspaceInfo
+                ? 'API key validated and saved'
+                : 'API key saved (not validated)',
+            workspace: workspaceInfo?.workspace ?? null,
+            projectId: workspaceInfo?.projectId ?? null,
+        };
+    },
+});
+// ── logout ──
+cli.command('logout', {
+    description: 'Remove saved API key and clear authentication',
+    run() {
+        const hadKey = !!(0, config_1.readConfig)().apiKey;
+        (0, config_1.clearConfig)();
+        if (process.stdout.isTTY) {
+            process.stderr.write('\n');
+            if (hadKey) {
+                process.stderr.write((0, ui_1.success)('Logged out successfully.') +
+                    '\n' +
+                    (0, ui_1.info)('API key removed from ~/.config/formo/config.json') +
+                    '\n');
+            }
+            else {
+                process.stderr.write((0, ui_1.info)('No saved API key found — already logged out.') + '\n');
+            }
+            if (process.env.FORMO_API_KEY) {
+                process.stderr.write('\n' +
+                    (0, ui_1.warn)(`${ui_1.color.yellow('FORMO_API_KEY')} env var is still set.`) +
+                    '\n' +
+                    (0, ui_1.info)(`Run ${ui_1.color.green('unset FORMO_API_KEY')} to fully log out.`) +
+                    '\n');
+            }
+            process.stderr.write('\n');
+        }
+        return {
+            ok: true,
+            message: hadKey ? 'API key removed' : 'Already logged out',
+            envVarSet: !!process.env.FORMO_API_KEY,
+        };
+    },
+});
+// ── status ──
+cli.command('status', {
+    description: 'Show current authentication and CLI status',
+    run() {
+        const apiKey = (0, config_1.getApiKey)();
+        const config = (0, config_1.readConfig)();
+        const source = process.env.FORMO_API_KEY
+            ? 'FORMO_API_KEY env var'
+            : 'config file';
+        if (process.stdout.isTTY) {
+            process.stderr.write('\n');
+            if (apiKey) {
+                const masked = apiKey.length > 12
+                    ? apiKey.slice(0, 8) + '…' + apiKey.slice(-4)
+                    : '***';
+                process.stderr.write((0, ui_1.success)('Authenticated') +
+                    '\n' +
+                    (0, ui_1.info)(`Key: ${ui_1.color.dim(masked)}`) +
+                    '\n' +
+                    (0, ui_1.info)(`Source: ${ui_1.color.dim(source)}`) +
+                    '\n' +
+                    (config.workspace
+                        ? (0, ui_1.info)(`Workspace: ${ui_1.color.bold(config.workspace)}`) + '\n'
+                        : '') +
+                    (config.projectId
+                        ? (0, ui_1.info)(`Project ID: ${ui_1.color.dim(config.projectId)}`) + '\n'
+                        : '') +
+                    '\n');
+            }
+            else {
+                process.stderr.write((0, ui_1.error)('Not authenticated') +
+                    '\n\n' +
+                    (0, ui_1.info)(`Run ${ui_1.color.green('formo login')} to get started.`) +
+                    '\n\n');
+            }
+        }
+        return {
+            authenticated: !!apiKey,
+            source: apiKey ? source : null,
+            workspace: config.workspace ?? null,
+            projectId: config.projectId ?? null,
+            configFile: config.apiKey ? '~/.config/formo/config.json' : null,
+        };
+    },
+});
+// ── query ──
+cli.command('query', {
+    description: 'Run a SQL query against your Formo analytics data',
+    args: incur_1.z.object({
+        sql: incur_1.z.string().describe('SQL query string to execute'),
+    }),
+    options: incur_1.z.object({}),
+    examples: [
+        {
+            args: { sql: 'SELECT count(*) FROM events' },
+            description: 'Count all events',
+        },
+        {
+            args: { sql: 'SELECT address, net_worth_usd FROM wallet_profiles ORDER BY net_worth_usd DESC LIMIT 10' },
+            description: 'Top 10 wallets by net worth',
+        },
+    ],
+    hint: 'Requires query:read scope on your API key.',
+    run({ args }) {
+        return (0, query_1.queryRunRun)(args.sql);
+    },
+});
+// ── command groups ──
+cli.command(profiles_1.profiles);
+cli.command(alerts_1.alerts);
+cli.command(boards_1.boards);
+cli.command(charts_1.charts);
+cli.command(contracts_1.contracts);
+cli.command(segments_1.segments);
+cli.command(import_1.importCmd);
+// Show banner when run with no args (root help)
+const args = process.argv.slice(2);
+const isRootHelp = args.length === 0 || (args.length === 1 && args[0] === '--help');
+if (isRootHelp && process.stdout.isTTY) {
+    process.stderr.write((0, ui_1.banner)());
+}
+cli.serve();
+exports.default = cli;

package/dist/lib/client.d.ts

@@ -0,0 +1,3 @@
+declare function createClient(): import("axios").AxiosInstance;
+export declare function requireApiKey(): void;
+export { createClient };

package/dist/lib/client.js

@@ -0,0 +1,37 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireApiKey = requireApiKey;
+exports.createClient = createClient;
+const axios_1 = __importDefault(require("axios"));
+const config_1 = require("./config");
+const BASE_URL = 'https://api.formo.so';
+function createClient() {
+    const apiKey = (0, config_1.getApiKey)();
+    const baseURL = BASE_URL;
+    const instance = axios_1.default.create({
+        baseURL,
+        timeout: 30000,
+        headers: {
+            'Content-Type': 'application/json',
+            ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+        },
+    });
+    instance.interceptors.response.use((res) => res.data, (error) => {
+        const status = error.response?.status;
+        const data = error.response?.data;
+        const errorField = data?.error;
+        const message = data?.message ??
+            (typeof errorField === 'object' ? errorField?.message : errorField) ??
+            error.message;
+        throw Object.assign(new Error(message), { status, code: error.code });
+    });
+    return instance;
+}
+function requireApiKey() {
+    if (!(0, config_1.getApiKey)()) {
+        throw new Error('No API key configured. Run `formo login <apiKey>` or set FORMO_API_KEY env var.');
+    }
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,9 @@
+export interface FormoConfig {
+    apiKey?: string;
+    workspace?: string;
+    projectId?: string;
+}
+export declare function readConfig(): FormoConfig;
+export declare function saveConfig(updates: Partial<FormoConfig>): void;
+export declare function clearConfig(): void;
+export declare function getApiKey(): string | undefined;

package/dist/lib/config.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readConfig = readConfig;
+exports.saveConfig = saveConfig;
+exports.clearConfig = clearConfig;
+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');
+function readConfig() {
+    try {
+        const raw = fs_1.default.readFileSync(CONFIG_FILE, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function saveConfig(updates) {
+    const existing = readConfig();
+    const merged = { ...existing, ...updates };
+    fs_1.default.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), {
+        mode: 0o600,
+    });
+}
+function clearConfig() {
+    try {
+        if (fs_1.default.existsSync(CONFIG_FILE)) {
+            fs_1.default.writeFileSync(CONFIG_FILE, JSON.stringify({}, null, 2), {
+                mode: 0o600,
+            });
+        }
+    }
+    catch {
+        // Ignore errors if file doesn't exist
+    }
+}
+function getApiKey() {
+    return process.env.FORMO_API_KEY ?? readConfig().apiKey;
+}

package/dist/lib/ui.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+export declare const color: {
+    green: (t: string) => string;
+    brightGreen: (t: string) => string;
+    dim: (t: string) => string;
+    bold: (t: string) => string;
+    yellow: (t: string) => string;
+    red: (t: string) => string;
+    cyan: (t: string) => string;
+    gray: (t: string) => string;
+    white: (t: string) => string;
+    boldGreen: (t: string) => string;
+    boldBrightGreen: (t: string) => string;
+};
+/**
+ * Returns the Formo ASCII art banner in green.
+ * Only shown when stdout 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;

package/dist/lib/ui.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.color = void 0;
+exports.banner = banner;
+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;
+/** Whether color output is enabled */
+const colorEnabled = isTTY && !noColor;
+// ── ANSI helpers ──
+function ansi(code, text) {
+    return colorEnabled ? `\x1b[${code}m${text}\x1b[0m` : text;
+}
+exports.color = {
+    green: (t) => ansi('32', t),
+    brightGreen: (t) => ansi('92', t),
+    dim: (t) => ansi('2', t),
+    bold: (t) => ansi('1', t),
+    yellow: (t) => ansi('33', t),
+    red: (t) => ansi('31', t),
+    cyan: (t) => ansi('36', t),
+    gray: (t) => ansi('90', t),
+    white: (t) => ansi('97', t),
+    boldGreen: (t) => ansi('1;32', t),
+    boldBrightGreen: (t) => ansi('1;92', t),
+};
+// ── ASCII Art Logo ──
+const LOGO_LINES = [
+    ' ███████╗ ██████╗  ██████╗  ███╗   ███╗ ██████╗ ',
+    ' ██╔════╝██╔═══██╗██╔══██╗ ████╗ ████║██╔═══██╗',
+    ' █████╗  ██║   ██║██████╔╝ ██╔████╔██║██║   ██║',
+    ' ██╔══╝  ██║   ██║██╔══██╗ ██║╚██╔╝██║██║   ██║',
+    ' ██║     ╚██████╔╝██║  ██║ ██║ ╚═╝ ██║╚██████╔╝',
+    ' ╚═╝      ╚═════╝ ╚═╝  ╚═╝ ╚═╝     ╚═╝ ╚═════╝ ',
+];
+/**
+ * Returns the Formo ASCII art banner in green.
+ * Only shown when stdout is a TTY.
+ */
+function banner() {
+    if (!isTTY)
+        return '';
+    const logo = LOGO_LINES.map((line) => exports.color.boldGreen(line)).join('\n');
+    const tagline = exports.color.dim('  Web3 Analytics Platform — CLI');
+    const separator = exports.color.dim('─'.repeat(50));
+    return `\n${logo}\n${tagline}\n${separator}\n`;
+}
+// ── Status messages ──
+function success(message) {
+    return `${exports.color.boldGreen('✔')} ${message}`;
+}
+function error(message) {
+    return `${exports.color.red('✖')} ${message}`;
+}
+function warn(message) {
+    return `${exports.color.yellow('⚠')} ${message}`;
+}
+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);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@formo/cli",
+  "version": "0.1.0",
+  "description": "Formo API CLI — query profiles and analytics data",
+  "bin": {
+    "formo": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "test": "mocha",
+    "test:watch": "mocha --watch"
+  },
+  "dependencies": {
+    "axios": "^1.7.0",
+    "incur": "^0.3.4"
+  },
+  "overrides": {
+    "serialize-javascript": ">=7.0.5"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/chai": "^5.2.3",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^20.0.0",
+    "chai": "^6.2.2",
+    "dotenv": "^17.4.1",
+    "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"
+    }
+  }
+}