@formo/cli 0.1.0 → 1.0.0

package/dist/index.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const incur_1 = require("incur");
 const alerts_1 = require("./commands/alerts");
+const analytics_1 = require("./commands/analytics");
 const boards_1 = require("./commands/boards");
 const charts_1 = require("./commands/charts");
 const contracts_1 = require("./commands/contracts");
@@ -12,213 +13,217 @@ 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';
+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.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.green("export FORMO_API_KEY=formo_your_api_key_here")}`,
+        "",
         ui_1.color.dim(`  Docs: ${DOCS_URL}`),
-        '',
-    ].join('\n');
+        "",
+    ].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' },
+            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)
+        if (!body.validated)
             return null;
         return {
-            workspace: body.data.details,
-            projectId: body.data.scopes?.project_id ?? '',
+            workspace: body.details,
+            projectId: body.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',
+const cli = incur_1.Cli.create("formo", {
+    version: "0.2.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',
+            "get the profile for wallet 0xabc",
+            "search profiles with net worth > 10000",
+            "run a SQL query on my analytics data",
+            "show traffic KPIs for the last 7 days",
+            "get the conversion funnel for the last month",
+            "list the top wallets by activity",
+            "search profiles ordered by last_onchain desc",
+            "list all project alerts",
+            "create an alert for high-value transactions",
+            "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',
+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'),
+        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' },
-    ],
+    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.' };
+            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');
+            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 }),
+            ...(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)
-                : '***';
+                ? args.apiKey.slice(0, 8) + "…" + args.apiKey.slice(-4)
+                : "***";
             if (workspaceInfo) {
-                process.stderr.write((0, ui_1.success)('API key validated and saved!') +
-                    '\n' +
+                process.stderr.write((0, ui_1.success)("API key validated and saved!") +
+                    "\n" +
                     (0, ui_1.info)(`Key: ${ui_1.color.dim(masked)}`) +
-                    '\n' +
+                    "\n" +
                     (0, ui_1.info)(`Workspace: ${ui_1.color.bold(workspaceInfo.workspace)}`) +
-                    '\n' +
+                    "\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');
+                        ? (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' +
+                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');
+                    "\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)',
+                ? "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',
+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');
+            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');
+                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');
+                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" +
+                    (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');
+            process.stderr.write("\n");
         }
         return {
             ok: true,
-            message: hadKey ? 'API key removed' : 'Already logged out',
+            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',
+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';
+            ? "FORMO_API_KEY env var"
+            : "config file";
         if (process.stdout.isTTY) {
-            process.stderr.write('\n');
+            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' +
+                    ? 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' +
+                    "\n" +
                     (0, ui_1.info)(`Source: ${ui_1.color.dim(source)}`) +
-                    '\n' +
+                    "\n" +
                     (config.workspace
-                        ? (0, ui_1.info)(`Workspace: ${ui_1.color.bold(config.workspace)}`) + '\n'
-                        : '') +
+                        ? (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');
+                        ? (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');
+                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 {
@@ -226,34 +231,14 @@ cli.command('status', {
             source: apiKey ? source : null,
             workspace: config.workspace ?? null,
             projectId: config.projectId ?? null,
-            configFile: config.apiKey ? '~/.config/formo/config.json' : 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(query_1.query);
+cli.command(analytics_1.analytics);
 cli.command(alerts_1.alerts);
 cli.command(boards_1.boards);
 cli.command(charts_1.charts);
@@ -262,7 +247,7 @@ 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');
+const isRootHelp = args.length === 0 || (args.length === 1 && args[0] === "--help");
 if (isRootHelp && process.stdout.isTTY) {
     process.stderr.write((0, ui_1.banner)());
 }

package/dist/lib/client.d.ts

@@ -1,3 +1,29 @@
+import { AxiosError } from 'axios';
+export interface ApiErrorBody {
+    error?: {
+        code?: string;
+        message?: string;
+        doc_url?: string;
+        param?: string;
+        details?: Record<string, unknown>;
+    };
+}
+export interface DecoratedApiError extends Error {
+    status?: number;
+    code?: string;
+    docUrl?: string;
+    param?: string;
+    details?: Record<string, unknown>;
+    transportCode?: string;
+}
+/**
+ * Translate an AxiosError into a thrown Error with the API's structured
+ * `{ error: { code, message, doc_url, param, details } }` envelope decoded
+ * onto the Error instance and into a multi-line, human-readable `.message`.
+ *
+ * Exported for unit testing — used by the response interceptor below.
+ */
+export declare function parseApiError(error: AxiosError): DecoratedApiError;
 declare function createClient(): import("axios").AxiosInstance;
 export declare function requireApiKey(): void;
 export { createClient };

package/dist/lib/client.js

@@ -3,11 +3,40 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseApiError = parseApiError;
 exports.requireApiKey = requireApiKey;
 exports.createClient = createClient;
 const axios_1 = __importDefault(require("axios"));
 const config_1 = require("./config");
 const BASE_URL = 'https://api.formo.so';
+/**
+ * Translate an AxiosError into a thrown Error with the API's structured
+ * `{ error: { code, message, doc_url, param, details } }` envelope decoded
+ * onto the Error instance and into a multi-line, human-readable `.message`.
+ *
+ * Exported for unit testing — used by the response interceptor below.
+ */
+function parseApiError(error) {
+    const status = error.response?.status;
+    const body = error.response?.data;
+    const apiError = body?.error;
+    const baseMessage = apiError?.message ?? error.message;
+    const parts = [];
+    parts.push(apiError?.code ? `[${apiError.code}] ${baseMessage}` : baseMessage);
+    if (apiError?.param)
+        parts.push(`Param: ${apiError.param}`);
+    if (apiError?.doc_url)
+        parts.push(`Docs:  ${apiError.doc_url}`);
+    const message = parts.join('\n   ');
+    return Object.assign(new Error(message), {
+        status,
+        code: apiError?.code,
+        docUrl: apiError?.doc_url,
+        param: apiError?.param,
+        details: apiError?.details,
+        transportCode: error.code,
+    });
+}
 function createClient() {
     const apiKey = (0, config_1.getApiKey)();
     const baseURL = BASE_URL;
@@ -20,13 +49,7 @@ function createClient() {
         },
     });
     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 });
+        throw parseApiError(error);
     });
     return instance;
 }

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@formo/cli",
-  "version": "0.1.0",
+  "version": "1.0.0",
+  "packageManager": "pnpm@11.1.2",
   "description": "Formo API CLI — query profiles and analytics data",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/getformo/cli.git"
+  },
+  "homepage": "https://github.com/getformo/cli#readme",
+  "bugs": {
+    "url": "https://github.com/getformo/cli/issues"
+  },
   "bin": {
     "formo": "dist/index.js"
   },
@@ -20,7 +29,7 @@
     "test:watch": "mocha --watch"
   },
   "dependencies": {
-    "axios": "^1.7.0",
+    "axios": "^1.15.2",
     "incur": "^0.3.4"
   },
   "overrides": {