@formo/cli 1.0.0 → 1.0.2

package/dist/commands/profiles.js

@@ -1,26 +1,89 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.profilesLabels = exports.profiles = void 0;
+exports.profilesLabels = exports.profilesProperties = exports.profiles = void 0;
 exports.getProfileRun = getProfileRun;
 exports.parseSearchConditions = parseSearchConditions;
 exports.searchProfilesRun = searchProfilesRun;
 exports.buildUpdateProfileBody = buildUpdateProfileBody;
 exports.updateProfileRun = updateProfileRun;
+exports.buildBatchUpdateProfilesBody = buildBatchUpdateProfilesBody;
+exports.batchUpdateProfilesRun = batchUpdateProfilesRun;
 exports.buildCreateLabelBody = buildCreateLabelBody;
 exports.createProfileLabelRun = createProfileLabelRun;
+exports.buildBatchCreateLabelsBody = buildBatchCreateLabelsBody;
+exports.batchCreateProfileLabelsRun = batchCreateProfileLabelsRun;
 exports.buildDeleteLabelBody = buildDeleteLabelBody;
 exports.deleteProfileLabelRun = deleteProfileLabelRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const json_1 = require("../lib/json");
 exports.profiles = incur_1.Cli.create('profiles', {
     description: 'Wallet profile commands',
 });
-function getProfileRun(address, expand) {
+function addLifecycleThresholdParams(params, options) {
+    if (options.newWindowDays !== undefined) {
+        params.new_window_days = options.newWindowDays;
+    }
+    if (options.churnWindowDays !== undefined) {
+        params.churn_window_days = options.churnWindowDays;
+    }
+    if (options.powerUserMinActiveDays !== undefined) {
+        params.power_user_min_active_days = options.powerUserMinActiveDays;
+    }
+    if (options.powerUserWindowDays !== undefined) {
+        params.power_user_window_days = options.powerUserWindowDays;
+    }
+    if (options.resurrectedGapDays !== undefined) {
+        params.resurrected_gap_days = options.resurrectedGapDays;
+    }
+    if (options.atRiskMinDaysInactive !== undefined) {
+        params.at_risk_min_days_inactive = options.atRiskMinDaysInactive;
+    }
+    if (options.atRiskPriorActiveDaysThreshold !== undefined) {
+        params.at_risk_prior_active_days_threshold =
+            options.atRiskPriorActiveDaysThreshold;
+    }
+}
+const lifecycleThresholdOptions = {
+    newWindowDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle new-user window in days'),
+    churnWindowDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle churn window in days'),
+    powerUserMinActiveDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle power-user minimum active days'),
+    powerUserWindowDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle power-user window in days'),
+    resurrectedGapDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle resurrected gap in days'),
+    atRiskMinDaysInactive: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle at-risk minimum inactive days'),
+    atRiskPriorActiveDaysThreshold: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle at-risk prior active days threshold'),
+};
+function getProfileRun(address, optionsOrExpand = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
+    const options = typeof optionsOrExpand === 'string'
+        ? { expand: optionsOrExpand }
+        : optionsOrExpand;
     const params = {};
-    if (expand)
-        params.expand = expand;
+    if (options.expand)
+        params.expand = options.expand;
+    addLifecycleThresholdParams(params, options);
     return client.get(`/v0/profiles/${encodeURIComponent(address)}`, { params });
 }
 exports.profiles.command('get', {
@@ -33,6 +96,7 @@ exports.profiles.command('get', {
             .string()
             .optional()
             .describe('Comma-separated list of fields to expand: apps,chains,tokens,labels'),
+        ...lifecycleThresholdOptions,
     }),
     examples: [
         { args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' }, description: 'Get a wallet profile' },
@@ -44,7 +108,7 @@ exports.profiles.command('get', {
     ],
     hint: 'Requires profiles:read scope on your API key.',
     run({ args, options }) {
-        return getProfileRun(args.address, options.expand);
+        return getProfileRun(args.address, options);
     },
 });
 // Accepted first segments for a FilterCondition `field`, mirroring the API's
@@ -102,6 +166,8 @@ function searchProfilesRun(options) {
     const params = {};
     if (options.address)
         params.address = options.address;
+    if (options.search)
+        params.search = options.search;
     if (options.page !== undefined)
         params.page = options.page;
     if (options.size !== undefined)
@@ -112,6 +178,7 @@ function searchProfilesRun(options) {
         params.order_dir = options.orderDir;
     if (options.expand)
         params.expand = options.expand;
+    addLifecycleThresholdParams(params, options);
     let body;
     if (options.conditions) {
         body = {
@@ -119,12 +186,19 @@ function searchProfilesRun(options) {
             logic: options.logic ?? 'and',
         };
     }
+    // INTENTIONAL: the Formo search API is `GET /v0/profiles` with the
+    // `{ conditions, logic }` filter object in the *request body* (see
+    // docs.formo.so/api/profiles/search — it has a "Request Body (Filters)"
+    // section under a GET endpoint). This GET-with-body shape is the
+    // documented, server-supported contract. Do NOT "fix" it to POST — that
+    // breaks the API. Filter-less searches still go over query params only.
     return client.request({ method: 'get', url: '/v0/profiles/', params, data: body });
 }
 exports.profiles.command('search', {
     description: 'Search wallet profiles with optional filters',
     options: incur_1.z.object({
         address: incur_1.z.string().optional().describe('Filter by wallet address'),
+        search: incur_1.z.string().optional().describe('Free-text search across address and identity fields'),
         page: incur_1.z.coerce.number().optional().describe('Page number (1-indexed, default 1)'),
         size: incur_1.z.coerce.number().optional().describe('Page size (default 100, max 1000)'),
         orderBy: incur_1.z
@@ -161,6 +235,7 @@ exports.profiles.command('search', {
             .enum(['and', 'or'])
             .optional()
             .describe('Logic operator for combining conditions: "and" (default) or "or"'),
+        ...lifecycleThresholdOptions,
     }),
     examples: [
         { options: { size: 10 }, description: 'List first 10 profiles' },
@@ -201,15 +276,7 @@ exports.profiles.command('search', {
     },
 });
 function buildUpdateProfileBody(options) {
-    let body;
-    try {
-        body = JSON.parse(options.properties);
-        if (!body || typeof body !== 'object' || Array.isArray(body))
-            throw new Error('not an object');
-    }
-    catch {
-        throw new Error('--properties must be a JSON object of property keys');
-    }
+    const body = (0, json_1.parseJsonObject)(options.properties, '--properties');
     if (Object.keys(body).length === 0) {
         throw new Error('--properties must contain at least one key');
     }
@@ -249,6 +316,46 @@ exports.profiles.command('update', {
         return updateProfileRun(args.address, options);
     },
 });
+function buildBatchUpdateProfilesBody(options) {
+    const rows = (0, json_1.parseJsonArrayOfObjects)(options.rows, '--rows');
+    if (rows.length === 0) {
+        throw new Error('--rows must contain at least one item');
+    }
+    for (const row of rows) {
+        if (typeof row.address !== 'string' || row.address.length === 0) {
+            throw new Error('--rows entries must each include a non-empty string address');
+        }
+    }
+    return rows;
+}
+function batchUpdateProfilesRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/profiles/properties', buildBatchUpdateProfilesBody(options));
+}
+exports.profilesProperties = incur_1.Cli.create('properties', {
+    description: 'Manage first-party profile properties in bulk',
+});
+exports.profilesProperties.command('batch', {
+    description: 'Batch update first-party profile properties for up to 100 wallets',
+    options: incur_1.z.object({
+        rows: incur_1.z
+            .string()
+            .describe('JSON array of flat {address,...properties} objects. ENS names are not resolved in batch requests.'),
+    }),
+    examples: [
+        {
+            options: {
+                rows: '[{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","display_name":"alice.eth","email":"alice@example.com"}]',
+            },
+            description: 'Batch set display names and emails',
+        },
+    ],
+    hint: 'Requires profiles:write scope on your API key. Unknown keys are ignored by the API; invalid rows are quarantined.',
+    run({ options }) {
+        return batchUpdateProfilesRun(options);
+    },
+});
 // ── Labels sub-resource ──
 exports.profilesLabels = incur_1.Cli.create('labels', {
     description: 'Manage labels on a wallet profile',
@@ -267,10 +374,15 @@ function buildCreateLabelBody(options) {
     }
     if (options.tagId) {
         const single = { tag_id: options.tagId };
-        if (options.value)
+        if (options.value !== undefined)
             single.value = options.value;
         if (options.chainId)
             single.chain_id = options.chainId;
+        if (options.timestamp)
+            single.timestamp = options.timestamp;
+        if (options.isDeleted !== undefined) {
+            single._is_deleted = options.isDeleted ? 1 : 0;
+        }
         return single;
     }
     throw new Error('Provide --tag-id (single label) or --labels (batch JSON array)');
@@ -292,10 +404,18 @@ exports.profilesLabels.command('create', {
             .describe('Label identifier (e.g. "vip", "airdrop_eligible")'),
         value: incur_1.z.string().optional().describe('Optional label value (e.g. tier name, country code)'),
         chainId: incur_1.z.string().optional().describe('Optional chain identifier the label applies to'),
+        timestamp: incur_1.z
+            .string()
+            .optional()
+            .describe('Optional historical ISO-8601 timestamp for the label row'),
+        isDeleted: incur_1.z
+            .boolean()
+            .optional()
+            .describe('Set true with --timestamp to backfill a label removal tombstone'),
         labels: incur_1.z
             .string()
             .optional()
-            .describe('JSON array of UserLabelInput objects for batch upsert'),
+            .describe('JSON array of UserLabelInput objects for this wallet'),
     }),
     examples: [
         {
@@ -308,6 +428,11 @@ exports.profilesLabels.command('create', {
             options: { tagId: 'tier', value: 'gold', chainId: '1' },
             description: 'Apply a tiered label scoped to a chain',
         },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { tagId: 'tier', timestamp: '2024-03-15T00:00:00.000Z', isDeleted: true },
+            description: 'Backfill a historical label removal',
+        },
         {
             args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
             options: { labels: '[{"tag_id":"vip"},{"tag_id":"airdrop_eligible","chain_id":"1"}]' },
@@ -319,6 +444,46 @@ exports.profilesLabels.command('create', {
         return createProfileLabelRun(args.address, options);
     },
 });
+function buildBatchCreateLabelsBody(options) {
+    const labels = (0, json_1.parseJsonArrayOfObjects)(options.labels, '--labels');
+    if (labels.length === 0) {
+        throw new Error('--labels must contain at least one item');
+    }
+    for (const label of labels) {
+        if (typeof label.address !== 'string' || label.address.length === 0) {
+            throw new Error('--labels entries must each include a non-empty string address');
+        }
+        if (typeof label.tag_id !== 'string' || label.tag_id.length === 0) {
+            throw new Error('--labels entries must each include a non-empty string tag_id');
+        }
+    }
+    return labels;
+}
+function batchCreateProfileLabelsRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/profiles/labels', buildBatchCreateLabelsBody(options));
+}
+exports.profilesLabels.command('batch', {
+    description: 'Batch upsert labels across up to 100 wallets',
+    options: incur_1.z.object({
+        labels: incur_1.z
+            .string()
+            .describe('JSON array of {address,tag_id,value?,chain_id?,timestamp?,_is_deleted?} objects'),
+    }),
+    examples: [
+        {
+            options: {
+                labels: '[{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","tag_id":"vip","value":"tier-1"}]',
+            },
+            description: 'Batch upsert labels for multiple wallets',
+        },
+    ],
+    hint: 'Requires profiles:write scope on your API key. ENS names are not resolved in batch requests.',
+    run({ options }) {
+        return batchCreateProfileLabelsRun(options);
+    },
+});
 function buildDeleteLabelBody(options) {
     if (!options.tagId) {
         throw new Error('--tag-id is required');
@@ -359,4 +524,5 @@ exports.profilesLabels.command('delete', {
         return deleteProfileLabelRun(args.address, options);
     },
 });
+exports.profiles.command(exports.profilesProperties);
 exports.profiles.command(exports.profilesLabels);

package/dist/commands/query.js

@@ -4,13 +4,17 @@ exports.query = void 0;
 exports.queryRunRun = queryRunRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const sql_1 = require("../lib/sql");
 exports.query = incur_1.Cli.create('query', {
     description: 'SQL analytics query commands',
 });
 function queryRunRun(sql) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.post('/v0/query/', { query: sql });
+    // The API wraps the query in a paginating subquery with its own
+    // `FORMAT JSON`. ClickHouse forbids a `FORMAT` clause inside a subquery, so
+    // strip any trailing `FORMAT`/semicolon before sending to avoid a 400.
+    return client.post('/v0/query/', { query: (0, sql_1.stripTrailingFormatClause)(sql) });
 }
 exports.query.command('run', {
     description: 'Run a SQL query against your Formo analytics data',

package/dist/commands/segments.d.ts

@@ -1,13 +1,17 @@
 import { Cli } from 'incur';
 export declare const segments: Cli.Cli<{}, undefined, undefined>;
-export declare function listSegmentsRun(): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface PaginationOptions {
+    page?: number;
+    size?: number;
+}
+export declare function listSegmentsRun(options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface CreateSegmentOptions {
     title: string;
     filterSets: string;
 }
 export declare function buildCreateSegmentBody(options: CreateSegmentOptions): {
     title: string;
-    filterSets: unknown;
+    filterSets: any[];
 };
 export declare function createSegmentRun(options: CreateSegmentOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export declare function deleteSegmentRun(segmentId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/segments.js

@@ -10,24 +10,38 @@ const client_1 = require("../lib/client");
 exports.segments = incur_1.Cli.create('segments', {
     description: 'User segment commands — create, list, and delete audience segments',
 });
-// ── List segments ──
-function listSegmentsRun() {
+function buildPaginationParams(options = {}) {
+    const params = {};
+    if (options.page !== undefined)
+        params.page = options.page;
+    if (options.size !== undefined)
+        params.size = options.size;
+    return params;
+}
+function listSegmentsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/segments/');
+    return client.get('/v0/segments/', { params: buildPaginationParams(options) });
 }
 exports.segments.command('list', {
     description: 'List all user segments for the project',
+    options: incur_1.z.object({
+        page: incur_1.z.coerce.number().optional().describe('Page number (1-indexed, default 1)'),
+        size: incur_1.z.coerce.number().optional().describe('Page size (default 100, max 200)'),
+    }),
     examples: [{ description: 'List all project segments' }],
     hint: 'Requires segments:read scope on your API key.',
-    run() {
-        return listSegmentsRun();
+    run({ options }) {
+        return listSegmentsRun(options);
     },
 });
 function buildCreateSegmentBody(options) {
     let parsedFilterSets;
     try {
         parsedFilterSets = JSON.parse(options.filterSets);
+        if (!Array.isArray(parsedFilterSets)) {
+            throw new Error('not an array');
+        }
     }
     catch {
         throw new Error('--filter-sets must be a valid JSON array');

package/dist/index.js

@@ -7,15 +7,16 @@ const analytics_1 = require("./commands/analytics");
 const boards_1 = require("./commands/boards");
 const charts_1 = require("./commands/charts");
 const contracts_1 = require("./commands/contracts");
+const events_1 = require("./commands/events");
 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 client_1 = require("./lib/client");
 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 [
         "",
@@ -38,7 +39,7 @@ function loginGuide() {
 }
 async function validateAndFetchWorkspace(apiKey) {
     try {
-        const res = await fetch(`${API_BASE_URL}/api/validate-api-key`, {
+        const res = await fetch(`${(0, client_1.getApiBaseUrl)()}/api/validate-api-key`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ apiKey }),
@@ -58,7 +59,7 @@ async function validateAndFetchWorkspace(apiKey) {
     }
 }
 const cli = incur_1.Cli.create("formo", {
-    version: "0.2.0",
+    version: "1.0.1",
     description: "Formo API CLI — Web3 analytics from the terminal",
     sync: {
         suggestions: [
@@ -72,10 +73,15 @@ const cli = incur_1.Cli.create("formo", {
             "list all project alerts",
             "create an alert for high-value transactions",
             "list charts in a board",
+            "create a line chart in a board",
+            "move or duplicate a dashboard chart",
             "list all tracked contracts",
             "register a new smart contract",
             "list user segments",
             "import wallet addresses",
+            "batch update profile properties with profiles properties batch",
+            "batch upsert labels for wallets",
+            "send raw analytics events",
         ],
     },
 });
@@ -243,6 +249,7 @@ cli.command(alerts_1.alerts);
 cli.command(boards_1.boards);
 cli.command(charts_1.charts);
 cli.command(contracts_1.contracts);
+cli.command(events_1.events);
 cli.command(segments_1.segments);
 cli.command(import_1.importCmd);
 // Show banner when run with no args (root help)

package/dist/lib/client.d.ts

@@ -1,4 +1,8 @@
 import { AxiosError } 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;
+export declare function getEventsBaseUrl(): string;
 export interface ApiErrorBody {
     error?: {
         code?: string;
@@ -24,6 +28,11 @@ export interface DecoratedApiError extends Error {
  * Exported for unit testing — used by the response interceptor below.
  */
 export declare function parseApiError(error: AxiosError): DecoratedApiError;
-declare function createClient(): import("axios").AxiosInstance;
+export interface ClientOptions {
+    baseURL?: string;
+    apiKey?: string;
+}
+declare function createClient(options?: ClientOptions): import("axios").AxiosInstance;
+export declare function createEventsClient(writeKey: string): import("axios").AxiosInstance;
 export declare function requireApiKey(): void;
 export { createClient };

package/dist/lib/client.js

@@ -3,12 +3,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_EVENTS_BASE_URL = exports.DEFAULT_API_BASE_URL = void 0;
+exports.getApiBaseUrl = getApiBaseUrl;
+exports.getEventsBaseUrl = getEventsBaseUrl;
 exports.parseApiError = parseApiError;
+exports.createEventsClient = createEventsClient;
 exports.requireApiKey = requireApiKey;
 exports.createClient = createClient;
 const axios_1 = __importDefault(require("axios"));
 const config_1 = require("./config");
-const BASE_URL = 'https://api.formo.so';
+exports.DEFAULT_API_BASE_URL = 'https://api.formo.so';
+exports.DEFAULT_EVENTS_BASE_URL = 'https://events.formo.so';
+function getApiBaseUrl() {
+    return process.env.FORMO_API_BASE_URL ?? exports.DEFAULT_API_BASE_URL;
+}
+function getEventsBaseUrl() {
+    return process.env.FORMO_EVENTS_BASE_URL ?? exports.DEFAULT_EVENTS_BASE_URL;
+}
 /**
  * Translate an AxiosError into a thrown Error with the API's structured
  * `{ error: { code, message, doc_url, param, details } }` envelope decoded
@@ -25,6 +36,12 @@ function parseApiError(error) {
     parts.push(apiError?.code ? `[${apiError.code}] ${baseMessage}` : baseMessage);
     if (apiError?.param)
         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)}`)
+            .join('; ');
+        parts.push(`Details: ${details}`);
+    }
     if (apiError?.doc_url)
         parts.push(`Docs:  ${apiError.doc_url}`);
     const message = parts.join('\n   ');
@@ -37,9 +54,9 @@ function parseApiError(error) {
         transportCode: error.code,
     });
 }
-function createClient() {
-    const apiKey = (0, config_1.getApiKey)();
-    const baseURL = BASE_URL;
+function createClient(options = {}) {
+    const apiKey = options.apiKey ?? (0, config_1.getApiKey)();
+    const baseURL = options.baseURL ?? getApiBaseUrl();
     const instance = axios_1.default.create({
         baseURL,
         timeout: 30000,
@@ -53,6 +70,12 @@ function createClient() {
     });
     return instance;
 }
+function createEventsClient(writeKey) {
+    if (!writeKey) {
+        throw new Error('No event write key configured. Pass --write-key or set FORMO_WRITE_KEY.');
+    }
+    return createClient({ baseURL: getEventsBaseUrl(), apiKey: writeKey });
+}
 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.js

@@ -24,10 +24,17 @@ function readConfig() {
 function saveConfig(updates) {
     const existing = readConfig();
     const merged = { ...existing, ...updates };
+    // The `mode` option on mkdir/writeFile is honored ONLY when the path is
+    // newly created. A pre-existing dir/file (older CLI version, dotfile-sync
+    // 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), {
         mode: 0o600,
     });
+    fs_1.default.chmodSync(CONFIG_FILE, 0o600);
 }
 function clearConfig() {
     try {
@@ -35,6 +42,9 @@ function clearConfig() {
             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);
         }
     }
     catch {

package/dist/lib/json.d.ts

@@ -0,0 +1,5 @@
+export declare function parseJson(raw: string, flagName: string): unknown;
+export declare function parseJsonObject(raw: string, flagName: string): Record<string, unknown>;
+export declare function parseJsonArray(raw: string, flagName: string): unknown[];
+export declare function parseJsonArrayOfObjects(raw: string, flagName: string): Record<string, unknown>[];
+export declare function parseStringArray(raw: string, flagName: string): string[];

package/dist/lib/json.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJson = parseJson;
+exports.parseJsonObject = parseJsonObject;
+exports.parseJsonArray = parseJsonArray;
+exports.parseJsonArrayOfObjects = parseJsonArrayOfObjects;
+exports.parseStringArray = parseStringArray;
+function parseJson(raw, flagName) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${flagName} must be valid JSON`);
+    }
+}
+function parseJsonObject(raw, flagName) {
+    const parsed = parseJson(raw, flagName);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${flagName} must be a valid JSON object`);
+    }
+    return parsed;
+}
+function parseJsonArray(raw, flagName) {
+    const parsed = parseJson(raw, flagName);
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${flagName} must be a valid JSON array`);
+    }
+    return parsed;
+}
+function parseJsonArrayOfObjects(raw, flagName) {
+    const parsed = parseJsonArray(raw, flagName);
+    if (parsed.some((item) => !item || typeof item !== 'object' || Array.isArray(item))) {
+        throw new Error(`${flagName} must be a valid JSON array of objects`);
+    }
+    return parsed;
+}
+function parseStringArray(raw, flagName) {
+    const value = raw.trim();
+    if (value.startsWith('[')) {
+        const parsed = parseJsonArray(value, flagName);
+        if (parsed.some((item) => typeof item !== 'string')) {
+            throw new Error(`${flagName} must be a JSON array of strings`);
+        }
+        return parsed;
+    }
+    const parts = value
+        .split(',')
+        .map((part) => part.trim())
+        .filter(Boolean);
+    if (parts.length === 0) {
+        throw new Error(`${flagName} must contain at least one value`);
+    }
+    return parts;
+}

package/dist/lib/sql.d.ts

@@ -0,0 +1,31 @@
+/**
+ * SQL helpers for the query command.
+ *
+ * The Formo query API wraps the SQL you submit so it can paginate the result
+ * set and force a machine-readable response:
+ *
+ *     SELECT * FROM (<your query>) LIMIT <n> FORMAT JSON
+ *
+ * ClickHouse does not allow a `FORMAT` clause inside a subquery, so if your
+ * query ends in its own `FORMAT` clause the wrapped statement becomes:
+ *
+ *     SELECT * FROM (SELECT ... FORMAT CSV) LIMIT 100 FORMAT JSON
+ *
+ * which ClickHouse rejects with a 400. A trailing `FORMAT` (or a trailing
+ * semicolon) can never take effect through this endpoint anyway — the outer
+ * `FORMAT JSON` always wins, and output shaping is the CLI's `--format` job —
+ * so we remove it before sending and let the server wrap a clean query.
+ */
+/**
+ * Strip a trailing, top-level `FORMAT <name>` clause and any trailing
+ * semicolons from a SQL statement.
+ *
+ * The scan is aware of string literals, quoted identifiers, and comments, so
+ * `FORMAT`-looking text inside them is never mistaken for a real clause. The
+ * match is anchored to the end of the statement, so a `FORMAT` nested inside
+ * parentheses (a subquery) or part of an identifier/function such as
+ * `formatDateTime(...)` — or a column aliased `format` — is left untouched.
+ *
+ * Returns the original input unchanged when there is nothing to strip.
+ */
+export declare function stripTrailingFormatClause(sql: string): string;