@formo/cli 0.2.0 → 1.0.2

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/boards.d.ts

@@ -1,15 +1,24 @@
 import { Cli } from 'incur';
 export declare const boards: Cli.Cli<{}, undefined, undefined>;
-export declare function listBoardsRun(): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface PaginationOptions {
+    page?: number;
+    size?: number;
+}
+export declare function listBoardsRun(options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export declare function getBoardRun(boardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface CreateBoardOptions {
-    name: string;
+    title?: string;
+    name?: string;
     description?: string;
+    isPublic?: boolean;
 }
+export declare function buildBoardBody(options: CreateBoardOptions | UpdateBoardOptions): Record<string, unknown>;
 export declare function createBoardRun(options: CreateBoardOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface UpdateBoardOptions {
+    title?: string;
     name?: string;
     description?: string;
+    isPublic?: boolean;
 }
 export declare function updateBoardRun(boardId: string, options: UpdateBoardOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export declare function deleteBoardRun(boardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/boards.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.boards = void 0;
 exports.listBoardsRun = listBoardsRun;
 exports.getBoardRun = getBoardRun;
+exports.buildBoardBody = buildBoardBody;
 exports.createBoardRun = createBoardRun;
 exports.updateBoardRun = updateBoardRun;
 exports.deleteBoardRun = deleteBoardRun;
@@ -11,18 +12,30 @@ const client_1 = require("../lib/client");
 exports.boards = incur_1.Cli.create('boards', {
     description: 'Dashboard board commands — create, list, update, and delete boards',
 });
+function buildPaginationParams(options = {}) {
+    const params = {};
+    if (options.page !== undefined)
+        params.page = options.page;
+    if (options.size !== undefined)
+        params.size = options.size;
+    return params;
+}
 // ── List boards ──
-function listBoardsRun() {
+function listBoardsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/boards/');
+    return client.get('/v0/boards/', { params: buildPaginationParams(options) });
 }
 exports.boards.command('list', {
     description: 'List all boards 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 dashboard boards' }],
     hint: 'Requires boards:read scope on your API key.',
-    run() {
-        return listBoardsRun();
+    run({ options }) {
+        return listBoardsRun(options);
     },
 });
 // ── Get a single board ──
@@ -44,28 +57,46 @@ exports.boards.command('get', {
         return getBoardRun(args.boardId);
     },
 });
+function buildBoardBody(options) {
+    const title = options.title ?? options.name;
+    const body = {};
+    if (title !== undefined) {
+        if (!title)
+            throw new Error('--title must not be empty');
+        body.title = title;
+    }
+    if (options.description !== undefined) {
+        body.description = options.description;
+    }
+    if (options.isPublic !== undefined) {
+        body.isPublic = options.isPublic;
+    }
+    return body;
+}
 function createBoardRun(options) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    const body = { name: options.name };
-    if (options.description) {
-        body.description = options.description;
+    const body = buildBoardBody(options);
+    if (!body.title) {
+        throw new Error('Provide --title for the board name');
     }
     return client.post('/v0/boards/', body);
 }
 exports.boards.command('create', {
     description: 'Create a new dashboard board',
     options: incur_1.z.object({
-        name: incur_1.z.string().describe('Board name'),
+        title: incur_1.z.string().optional().describe('Board title'),
+        name: incur_1.z.string().optional().describe('Deprecated alias for --title').meta({ deprecated: true }),
         description: incur_1.z.string().optional().describe('Board description'),
+        isPublic: incur_1.z.boolean().optional().describe('Whether the board is publicly viewable'),
     }),
     examples: [
         {
-            options: { name: 'KPI Dashboard' },
+            options: { title: 'KPI Dashboard' },
             description: 'Create a board',
         },
         {
-            options: { name: 'Revenue Metrics', description: 'Weekly revenue tracking' },
+            options: { title: 'Revenue Metrics', description: 'Weekly revenue tracking' },
             description: 'Create a board with description',
         },
     ],
@@ -77,11 +108,10 @@ exports.boards.command('create', {
 function updateBoardRun(boardId, options) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    const body = {};
-    if (options.name !== undefined)
-        body.name = options.name;
-    if (options.description !== undefined)
-        body.description = options.description;
+    const body = buildBoardBody(options);
+    if (Object.keys(body).length === 0) {
+        throw new Error('Provide at least one of --title, --description, or --is-public');
+    }
     return client.patch(`/v0/boards/${encodeURIComponent(boardId)}`, body);
 }
 exports.boards.command('update', {
@@ -90,13 +120,15 @@ exports.boards.command('update', {
         boardId: incur_1.z.string().describe('Board ID to update'),
     }),
     options: incur_1.z.object({
-        name: incur_1.z.string().optional().describe('New board name'),
+        title: incur_1.z.string().optional().describe('New board title'),
+        name: incur_1.z.string().optional().describe('Deprecated alias for --title').meta({ deprecated: true }),
         description: incur_1.z.string().optional().describe('New board description'),
+        isPublic: incur_1.z.boolean().optional().describe('Whether the board is publicly viewable'),
     }),
     examples: [
         {
             args: { boardId: 'board_abc123' },
-            options: { name: 'Renamed Board' },
+            options: { title: 'Renamed Board' },
             description: 'Rename a board',
         },
     ],

package/dist/commands/charts.d.ts

@@ -1,7 +1,34 @@
 import { Cli } from 'incur';
 export declare const charts: Cli.Cli<{}, undefined, undefined>;
-export declare function listChartsRun(boardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface PaginationOptions {
+    page?: number;
+    size?: number;
+}
+export interface ChartBodyOptions {
+    body?: string;
+    query?: string;
+    chartType?: string;
+    title?: string;
+    description?: string;
+    xAxis?: string;
+    yAxis?: string;
+    groupBy?: string;
+    steps?: string;
+    settings?: string;
+}
+export declare function buildChartBody(options: ChartBodyOptions): Record<string, unknown>;
+export declare function listChartsRun(boardId: string, options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function listChartSummariesRun(boardId: string, options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export declare function getChartRun(boardId: string, chartId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function createChartRun(boardId: string, body: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function updateChartRun(boardId: string, chartId: string, body: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface QueryChartOptions {
+    dateFrom: string;
+    dateTo: string;
+}
+export declare function queryChartRun(boardId: string, chartId: string, options: QueryChartOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function createChartRun(boardId: string, input: string | ChartBodyOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function updateChartRun(boardId: string, chartId: string, input: string | ChartBodyOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function moveChartRun(boardId: string, chartId: string, targetBoardId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function normalizeDuplicateChartResponse(result: unknown): unknown;
+export declare function duplicateChartRun(boardId: string, chartId: string): Promise<unknown>;
+export declare function reorderChartsRun(boardId: string, chartIds: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export declare function deleteChartRun(boardId: string, chartId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;