@formo/cli 0.1.0 → 1.0.0

package/dist/commands/analytics.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analytics = void 0;
+exports.buildAnalyticsParams = buildAnalyticsParams;
+exports.runAnalytics = runAnalytics;
+const incur_1 = require("incur");
+const client_1 = require("../lib/client");
+exports.analytics = incur_1.Cli.create('analytics', {
+    description: 'Pre-built analytics query commands — KPIs, funnels, retention, revenue, and top-N breakdowns',
+});
+// The pre-built analytics pipes exposed at GET /v0/<pipe>. Each requires the
+// query:read scope. Common params (date_from, date_to, filters) are shared;
+// pipe-specific params (e.g. funnel `steps`, kpis `group_by`, `limit`) are
+// passed through the generic --params JSON object.
+const PIPES = [
+    { name: 'kpis', description: 'Traffic KPIs: visitors, pageviews, bounce rate, session duration' },
+    { name: 'event_timeseries', description: 'Event counts over time' },
+    { name: 'funnel', description: 'Conversion funnel across ordered steps. --params: steps (JSON array of {type,event,name,filters?}), window_seconds, funnel_type, breakdown' },
+    { name: 'flow', description: 'User path/flow analysis. --params: start_step / end_step (JSON {type,event,...}), global_filters, window_seconds, max_steps' },
+    { name: 'frequency', description: 'Engagement frequency distribution' },
+    { name: 'lifecycle', description: 'User lifecycle stages (new, returning, power, resurrected, churned)' },
+    { name: 'retention', description: 'Retention cohort analysis (params: id_type, event_type, event_name, min_users)' },
+    { name: 'revenue_overview', description: 'Revenue overview with optional breakdown (params: group_by, rank_by)' },
+    { name: 'revenue_by_metric', description: 'Revenue ranked by a metric column (params: metric_column, limit, offset)' },
+    { name: 'revenue_timeseries', description: 'Revenue over time (params: address)' },
+    { name: 'volume_by_metric', description: 'Trading volume ranked by a metric column (params: metric_column, limit, offset)' },
+    { name: 'top_chains', description: 'Top chains by activity (params: limit, offset)' },
+    { name: 'top_events', description: 'Top events by count (params: limit, offset, type)' },
+    { name: 'top_locations', description: 'Top locations (params: limit, offset)' },
+    { name: 'top_pages', description: 'Top pages by traffic (params: limit, offset, mode)' },
+    { name: 'top_sources', description: 'Top acquisition sources (params: metric_column, limit, offset)' },
+    { name: 'top_wallets', description: 'Top wallets by activity (params: limit, offset)' },
+];
+// Keys --params is not allowed to set: they have dedicated, validated flags
+// (--date-from/--date-to/--filters). Rejecting them prevents --params from
+// silently overriding validated input or pushing an invalid `filters` value
+// (e.g. a non-JSON string) over the wire. Both casings of the date keys are
+// rejected so a stray camelCase key can't slip through unvalidated.
+const RESERVED_PARAM_KEYS = new Set([
+    'date_from',
+    'date_to',
+    'dateFrom',
+    'dateTo',
+    'filters',
+]);
+/**
+ * Build the query-string params for an analytics pipe request.
+ *
+ * - `dateFrom`/`dateTo` map to the API's snake_case `date_from`/`date_to`.
+ *   All pipes, including `funnel` and `flow`, use snake_case.
+ * - `filters` is a JSON array of `{ field, op, value }` objects, re-serialized
+ *   as a JSON string (the pipe expects a JSON-encoded array in the query).
+ * - `params` is a JSON object of any pipe-specific params (e.g. funnel
+ *   `steps`, kpis `group_by`, `limit`). Object/array values are JSON-encoded
+ *   (pipes like funnel expect `steps` as a JSON-encoded string); primitives
+ *   pass through unchanged. Reserved keys (the date/filters flags) are
+ *   rejected, and the validated flags below always take precedence.
+ *
+ * Exported for unit testing.
+ */
+function buildAnalyticsParams(options) {
+    const out = {};
+    // --params first, so the validated flags below override it.
+    if (options.params) {
+        let parsed;
+        try {
+            parsed = JSON.parse(options.params);
+        }
+        catch {
+            throw new Error('--params must be a valid JSON object');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('--params must be a valid JSON object');
+        }
+        for (const [key, value] of Object.entries(parsed)) {
+            if (RESERVED_PARAM_KEYS.has(key)) {
+                throw new Error(`--params may not set "${key}" — use the --date-from/--date-to/--filters flags instead`);
+            }
+            if (value === null || value === undefined)
+                continue;
+            if (typeof value === 'object') {
+                out[key] = JSON.stringify(value);
+            }
+            else {
+                out[key] = value;
+            }
+        }
+    }
+    if (options.dateFrom)
+        out.date_from = options.dateFrom;
+    if (options.dateTo)
+        out.date_to = options.dateTo;
+    if (options.filters) {
+        let parsed;
+        try {
+            parsed = JSON.parse(options.filters);
+        }
+        catch {
+            throw new Error('--filters must be a valid JSON array of {field,op,value} objects');
+        }
+        if (!Array.isArray(parsed)) {
+            throw new Error('--filters must be a valid JSON array of {field,op,value} objects');
+        }
+        out.filters = JSON.stringify(parsed);
+    }
+    return out;
+}
+function runAnalytics(pipe, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get(`/v0/${pipe}`, { params: buildAnalyticsParams(options) });
+}
+const sharedOptions = incur_1.z.object({
+    dateFrom: incur_1.z
+        .string()
+        .optional()
+        .describe('Inclusive start date YYYY-MM-DD (default: 7 days before --date-to)'),
+    dateTo: incur_1.z
+        .string()
+        .optional()
+        .describe('Inclusive end date YYYY-MM-DD (default: today)'),
+    filters: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON array of filter conditions: [{"field","op","value"}]. ' +
+        'Use op "in"/"notIn" with a pipe-delimited value (e.g. "chrome|firefox").'),
+    params: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON object of pipe-specific params merged into the query, e.g. ' +
+        '{"limit":10,"group_by":"device"} or funnel ' +
+        '{"steps":[{"type":"event","event":"page","name":"page::0","filters":[]}]}. ' +
+        'May not set date_from/date_to/filters; use the dedicated --date-from/--date-to/--filters flags.'),
+});
+for (const pipe of PIPES) {
+    exports.analytics.command(pipe.name, {
+        description: pipe.description,
+        options: sharedOptions,
+        examples: [
+            {
+                description: `Get ${pipe.name} for the last 7 days (default range)`,
+            },
+            {
+                options: { dateFrom: '2026-04-01', dateTo: '2026-04-30' },
+                description: `Get ${pipe.name} for April 2026`,
+            },
+        ],
+        hint: 'Requires query:read scope on your API key. Pass pipe-specific params via --params.',
+        run({ options }) {
+            return runAnalytics(pipe.name, options);
+        },
+    });
+}

package/dist/commands/contracts.d.ts

@@ -8,11 +8,23 @@ export interface CreateContractOptions {
     abi: string;
     events: string;
 }
+export declare function buildCreateContractBody(options: CreateContractOptions): {
+    address: string;
+    chain: number;
+    name: string;
+    abi: unknown;
+    events: unknown;
+};
 export declare function createContractRun(options: CreateContractOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface UpdateContractOptions {
     name: string;
     abi: string;
     events: string;
 }
+export declare function buildUpdateContractBody(options: UpdateContractOptions): {
+    name: string;
+    abi: unknown;
+    events: unknown;
+};
 export declare function updateContractRun(chain: string, address: string, options: UpdateContractOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export declare function deleteContractRun(chain: string, address: string): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/contracts.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.contracts = void 0;
 exports.listContractsRun = listContractsRun;
+exports.buildCreateContractBody = buildCreateContractBody;
 exports.createContractRun = createContractRun;
+exports.buildUpdateContractBody = buildUpdateContractBody;
 exports.updateContractRun = updateContractRun;
 exports.deleteContractRun = deleteContractRun;
 const incur_1 = require("incur");
@@ -24,9 +26,7 @@ exports.contracts.command('list', {
         return listContractsRun();
     },
 });
-function createContractRun(options) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
+function buildCreateContractBody(options) {
     let parsedAbi;
     try {
         parsedAbi = JSON.parse(options.abi);
@@ -41,13 +41,18 @@ function createContractRun(options) {
     catch {
         throw new Error('--events must be valid JSON');
     }
-    return client.post('/v0/contracts/', {
+    return {
         address: options.address,
         chain: options.chain,
         name: options.name,
         abi: parsedAbi,
         events: parsedEvents,
-    });
+    };
+}
+function createContractRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/contracts/', buildCreateContractBody(options));
 }
 exports.contracts.command('create', {
     description: 'Register a new smart contract to track',
@@ -75,9 +80,7 @@ exports.contracts.command('create', {
         return createContractRun(options);
     },
 });
-function updateContractRun(chain, address, options) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
+function buildUpdateContractBody(options) {
     let parsedAbi;
     try {
         parsedAbi = JSON.parse(options.abi);
@@ -92,11 +95,16 @@ function updateContractRun(chain, address, options) {
     catch {
         throw new Error('--events must be valid JSON');
     }
-    return client.put(`/v0/contracts/${encodeURIComponent(chain)}/${encodeURIComponent(address)}`, {
+    return {
         name: options.name,
         abi: parsedAbi,
         events: parsedEvents,
-    });
+    };
+}
+function updateContractRun(chain, address, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.put(`/v0/contracts/${encodeURIComponent(chain)}/${encodeURIComponent(address)}`, buildUpdateContractBody(options));
 }
 exports.contracts.command('update', {
     description: 'Update a tracked contract',

package/dist/commands/import.d.ts

@@ -4,4 +4,8 @@ export interface ImportWalletsOptions {
     addresses: string;
     writeKey: string;
 }
+export declare function buildImportBody(options: ImportWalletsOptions): {
+    addresses: any[];
+    writeKey: string;
+};
 export declare function importWalletsRun(options: ImportWalletsOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/import.js

@@ -1,15 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.importCmd = void 0;
+exports.buildImportBody = buildImportBody;
 exports.importWalletsRun = importWalletsRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
 exports.importCmd = incur_1.Cli.create('import', {
     description: 'Import commands — bulk import wallet addresses into your project',
 });
-function importWalletsRun(options) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
+function buildImportBody(options) {
     let parsedAddresses;
     try {
         parsedAddresses = JSON.parse(options.addresses);
@@ -20,10 +19,15 @@ function importWalletsRun(options) {
     catch {
         throw new Error('--addresses must be a valid JSON array of wallet address strings');
     }
-    return client.post('/v0/import/', {
+    return {
         addresses: parsedAddresses,
         writeKey: options.writeKey,
-    });
+    };
+}
+function importWalletsRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/import/', buildImportBody(options));
 }
 exports.importCmd.command('wallets', {
     description: 'Bulk import wallet addresses into the project',

package/dist/commands/profiles.d.ts

@@ -3,12 +3,39 @@ export declare const profiles: Cli.Cli<{}, undefined, undefined>;
 export declare function getProfileRun(address: string, expand?: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface SearchProfilesOptions {
     address?: string;
-    limit?: number;
-    offset?: number;
+    page?: number;
+    size?: number;
     orderBy?: string;
     orderDir?: string;
     expand?: string;
     conditions?: string;
     logic?: 'and' | 'or';
 }
+/**
+ * Parse and validate the --conditions JSON. Ensures it is an array of
+ * `{ field, op, value }` objects whose `field` is a typed path (e.g.
+ * `users.net_worth_usd`) — a bare name like `net_worth_usd` is silently
+ * dropped by the API, so it is rejected here. Exported for unit testing.
+ */
+export declare function parseSearchConditions(raw: string): unknown[];
 export declare function searchProfilesRun(options: SearchProfilesOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface UpdateProfileOptions {
+    properties: string;
+}
+export declare function buildUpdateProfileBody(options: UpdateProfileOptions): Record<string, unknown>;
+export declare function updateProfileRun(address: string, options: UpdateProfileOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare const profilesLabels: Cli.Cli<{}, undefined, undefined>;
+export interface CreateProfileLabelOptions {
+    tagId?: string;
+    value?: string;
+    chainId?: string;
+    labels?: string;
+}
+export declare function buildCreateLabelBody(options: CreateProfileLabelOptions): unknown;
+export declare function createProfileLabelRun(address: string, options: CreateProfileLabelOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface DeleteProfileLabelOptions {
+    tagId: string;
+    chainId?: string;
+}
+export declare function buildDeleteLabelBody(options: DeleteProfileLabelOptions): Record<string, string>;
+export declare function deleteProfileLabelRun(address: string, options: DeleteProfileLabelOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;