@formo/cli 1.2.1 → 1.3.0

package/README.md

@@ -91,10 +91,12 @@ Fetch a single wallet profile by address or ENS name.
 | Option | Description |
 |---|---|
 | `--expand` | Comma-separated fields: `apps`, `chains`, `tokens`, `labels` |
+| `--timestamp` | ISO-8601 timestamp; return the closest stored wallet-enrichment snapshot |
 
 ```bash
 formo profiles get 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
 formo profiles get vitalik.eth --expand labels,chains
+formo profiles get vitalik.eth --timestamp 2025-06-21T10:03:00Z
 ```
 
 ### `profiles search`
@@ -105,6 +107,7 @@ Search wallet profiles with filters, sorting, and pagination. Returns a `Paginat
 |---|---|
 | `--address` | Filter by wallet address |
 | `--search` | Free-text search across address and identity fields |
+| `--timestamp` | ISO-8601 timestamp; requires `--address` and returns the closest stored wallet-enrichment snapshot |
 | `--page` | Page number (1-indexed, default `1`) |
 | `--size` | Page size (default `100`, max `1000`) |
 | `--order-by` | `last_onchain`, `first_onchain`, `net_worth_usd`, `updated_at`, `tx_count`, `first_seen`, `last_seen`, `num_sessions`, `revenue`, `volume`, `points` |
@@ -115,6 +118,7 @@ Search wallet profiles with filters, sorting, and pagination. Returns a `Paginat
 
 ```bash
 formo profiles search --size 10
+formo profiles search --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --timestamp 2025-06-21T10:03:00Z
 formo profiles search --order-by net_worth_usd --order-dir desc --size 5
 formo profiles search --page 2 --size 20
 formo profiles search --filters '[{"field":"users.net_worth_usd","op":"gt","value":10000}]' --size 20
@@ -122,6 +126,8 @@ formo profiles search --filters '[{"field":"users.net_worth_usd","op":"gt","valu
 formo profiles search --filters '[{"field":"chains.balance","op":"gt","value":1000,"chain_id":"1"}]' --size 20
 ```
 
+With `--timestamp`, wallet-enrichment fields come from the stored snapshot closest to that instant. Exact ties select the later snapshot. Expanded chains, apps, and tokens come from the selected profiling batch, while project engagement fields, identity overrides, and labels remain current. `profiles search --timestamp` requires `--address`.
+
 ### Lifecycle tuning (advanced)
 
 Both `profiles get` and `profiles search` accept optional flags to override the lifecycle stage thresholds used when computing `lifecycle`:
@@ -241,13 +247,6 @@ Toggle an alert between `active` and `inactive`.
 formo alerts toggle alert_abc123 --status inactive
 ```
 
-### `alerts test <alertId>`
-Send a test alert delivery with optional sample payloads.
-
-```bash
-formo alerts test alert_abc123 --sample-event '{"event":"transaction","revenue":250}'
-```
-
 ---
 
 ## `formo boards`
@@ -290,7 +289,7 @@ Delete a board.
 Chart commands. Charts live inside a board. Requires `boards:read` / `boards:write`.
 
 ### `charts list --board-id <boardId>`
-List all charts in a board.
+List charts in a board. Returns lightweight summaries by default; pass `--results` to execute each chart’s query and include full results.
 
 ### `charts get <chartId> --board-id <boardId>`
 Get a single chart by ID.
@@ -342,8 +341,6 @@ List all tracked contracts. Returns `{ data: Contract[], deploy: { last_deployed
 ### `contracts get <chain> <address>`
 Get a single tracked contract.
 
-### `contracts recommendations`
-List contracts the project already interacts with but has not added yet.
 
 ### `contracts create`
 
@@ -373,8 +370,6 @@ formo contracts create --address 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 --ch
 | `--start-block` | Optional start block |
 | `--include-in-pipeline` | Include or exclude this contract from the Goldsky events pipeline |
 
-### `contracts pipeline <chain> <address> --include-in-pipeline <true|false>`
-Toggle pipeline inclusion without re-sending the full ABI/events payload.
 
 ### `contracts delete <chain> <address>`
 Remove a tracked contract.

package/dist/commands/alerts.d.ts

@@ -19,10 +19,3 @@ export declare function createAlertRun(options: CreateAlertOptions): Promise<unk
 export declare function updateAlertRun(alertId: string, options: AlertBodyOptions): Promise<unknown>;
 export declare function deleteAlertRun(alertId: string): Promise<unknown>;
 export declare function toggleAlertRun(alertId: string, status: string): Promise<unknown>;
-export interface TestAlertOptions {
-    sampleEvent?: string;
-    sampleUser?: string;
-    recipientOverrides?: string;
-}
-export declare function buildTestAlertBody(options: TestAlertOptions): Record<string, unknown> | undefined;
-export declare function testAlertRun(alertId: string, options?: TestAlertOptions): Promise<unknown>;

package/dist/commands/alerts.js

@@ -8,8 +8,6 @@ exports.createAlertRun = createAlertRun;
 exports.updateAlertRun = updateAlertRun;
 exports.deleteAlertRun = deleteAlertRun;
 exports.toggleAlertRun = toggleAlertRun;
-exports.buildTestAlertBody = buildTestAlertBody;
-exports.testAlertRun = testAlertRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
 const filters_1 = require("../lib/filters");
@@ -201,54 +199,3 @@ exports.alerts.command('toggle', {
         return toggleAlertRun(args.alertId, options.status);
     },
 });
-function buildTestAlertBody(options) {
-    const body = {};
-    if (options.sampleEvent !== undefined) {
-        body.sampleEvent = (0, json_1.parseJsonObject)(options.sampleEvent, '--sample-event');
-    }
-    if (options.sampleUser !== undefined) {
-        body.sampleUser = (0, json_1.parseJsonObject)(options.sampleUser, '--sample-user');
-    }
-    if (options.recipientOverrides !== undefined) {
-        body.recipientOverrides = (0, json_1.parseJsonArray)(options.recipientOverrides, '--recipient-overrides');
-    }
-    return Object.keys(body).length > 0 ? body : undefined;
-}
-function testAlertRun(alertId, options = {}) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
-    return client.post(`/v0/alerts/${encodeURIComponent(alertId)}/test`, buildTestAlertBody(options));
-}
-exports.alerts.command('test', {
-    description: 'Send a test delivery for an alert',
-    args: incur_1.z.object({
-        alertId: incur_1.z.string().describe('Alert ID to test'),
-    }),
-    options: incur_1.z.object({
-        sampleEvent: incur_1.z
-            .string()
-            .optional()
-            .describe('Optional JSON object to use as the sample event'),
-        sampleUser: incur_1.z
-            .string()
-            .optional()
-            .describe('Optional JSON object to use as the sample user/profile'),
-        recipientOverrides: incur_1.z
-            .string()
-            .optional()
-            .describe('Optional JSON array of recipient objects to test instead of saved recipients'),
-    }),
-    examples: [
-        {
-            args: { alertId: 'alert_abc123' },
-            options: {
-                sampleEvent: '{"event":"transaction","revenue":250}',
-            },
-            description: 'Send a test alert with a sample event',
-        },
-    ],
-    hint: 'Requires alerts:write scope on your API key.',
-    run({ args, options }) {
-        return testAlertRun(args.alertId, options);
-    },
-});

package/dist/commands/analytics.js

@@ -22,10 +22,10 @@ const PIPES = [
     { 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_overview', description: 'Revenue overview with optional breakdown (params: group_by — incl. channel_type and paid_source for ad network, rank_by)' },
+    { name: 'revenue_by_metric', description: 'Revenue ranked by a metric column (params: metric_column — incl. channel and paid_source for ad network, 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: 'volume_by_metric', description: 'Trading volume ranked by a metric column (params: metric_column — incl. channel and paid_source for ad network, 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)' },

package/dist/commands/charts.d.ts

@@ -15,7 +15,7 @@ export interface ChartBodyOptions {
     settings?: string;
 }
 export declare function buildChartBody(options: ChartBodyOptions): Record<string, unknown>;
-export declare function listChartsRun(boardId: string, options?: PaginationOptions): Promise<unknown>;
+export declare function listChartsRun(boardId: string, options?: PaginationOptions, results?: boolean): Promise<unknown>;
 export declare function listChartSummariesRun(boardId: string, options?: PaginationOptions): Promise<unknown>;
 export declare function getChartRun(boardId: string, chartId: string): Promise<unknown>;
 export interface QueryChartOptions {

package/dist/commands/charts.js

@@ -109,35 +109,48 @@ const chartBodyOptions = incur_1.z.object({
         .describe('JSON object of type-specific chart settings (for example, user_paths anchors/maxSteps/nodesPerStep or retention entryFilter/retentionFilter)'),
 });
 // ── List charts for a board ──
-function listChartsRun(boardId, options = {}) {
+function listChartsRun(boardId, options = {}, results = false) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     return client.get(`/v0/boards/${encodeURIComponent(boardId)}/charts/`, {
-        params: (0, pagination_1.buildPaginationParams)(options),
+        params: {
+            ...(0, pagination_1.buildPaginationParams)(options),
+            // The public API returns lightweight summaries unless asked to execute.
+            ...(results ? { include: 'results' } : {}),
+        },
     });
 }
 exports.charts.command('list', {
-    description: 'List all charts for a board, including executed results',
+    description: 'List charts for a board (summaries by default; --results executes each chart query)',
     options: incur_1.z.object({
         boardId: incur_1.z.string().describe('Board ID to list charts from'),
+        results: incur_1.z
+            .boolean()
+            .optional()
+            .describe('Execute each chart query and include results (slower)'),
         ...pagination_1.paginationOptionsSchema,
     }),
     examples: [
         {
             options: { boardId: 'board_abc123' },
-            description: 'List all charts in a board',
+            description: 'List chart summaries for a board',
+        },
+        {
+            options: { boardId: 'board_abc123', results: true },
+            description: 'List charts with executed query results',
         },
     ],
     hint: 'Requires boards:read scope on your API key.',
     run({ options }) {
-        return listChartsRun(options.boardId, options);
+        return listChartsRun(options.boardId, options, options.results ?? false);
     },
 });
 // ── List chart metadata for a board ──
 function listChartSummariesRun(boardId, options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get(`/v0/boards/${encodeURIComponent(boardId)}/charts/meta`, {
+    // Summaries are the list endpoint's default; /charts/meta is internal-only.
+    return client.get(`/v0/boards/${encodeURIComponent(boardId)}/charts/`, {
         params: (0, pagination_1.buildPaginationParams)(options),
     });
 }

package/dist/commands/contracts.d.ts

@@ -4,7 +4,6 @@ export type { PaginationOptions };
 export declare const contracts: Cli.Cli<{}, undefined, undefined, undefined>;
 export declare function listContractsRun(options?: PaginationOptions): Promise<unknown>;
 export declare function getContractRun(chain: string, address: string): Promise<unknown>;
-export declare function getContractRecommendationsRun(): Promise<unknown>;
 export interface CreateContractOptions {
     address: string;
     chain: number;
@@ -25,8 +24,4 @@ export interface UpdateContractOptions {
 }
 export declare function buildUpdateContractBody(chain: string | number, address: string, options: UpdateContractOptions): Record<string, unknown>;
 export declare function updateContractRun(chain: string, address: string, options: UpdateContractOptions): Promise<unknown>;
-export declare function updateContractPipelineRun(chain: string, address: string, includeInPipeline: boolean): Promise<unknown>;
-export declare function buildUpdateContractPipelineBody(includeInPipeline: boolean): {
-    include_in_pipeline: boolean;
-};
 export declare function deleteContractRun(chain: string, address: string): Promise<unknown>;

package/dist/commands/contracts.js

@@ -3,20 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.contracts = void 0;
 exports.listContractsRun = listContractsRun;
 exports.getContractRun = getContractRun;
-exports.getContractRecommendationsRun = getContractRecommendationsRun;
 exports.buildCreateContractBody = buildCreateContractBody;
 exports.createContractRun = createContractRun;
 exports.buildUpdateContractBody = buildUpdateContractBody;
 exports.updateContractRun = updateContractRun;
-exports.updateContractPipelineRun = updateContractPipelineRun;
-exports.buildUpdateContractPipelineBody = buildUpdateContractPipelineBody;
 exports.deleteContractRun = deleteContractRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
 const json_1 = require("../lib/json");
 const pagination_1 = require("../lib/pagination");
 exports.contracts = incur_1.Cli.create('contracts', {
-    description: 'Smart contract commands — register, list, recommend, update, toggle pipeline inclusion, and remove tracked contracts',
+    description: 'Smart contract commands — register, list, update, and remove tracked contracts',
 });
 function parseChain(chain) {
     const value = typeof chain === 'number' ? chain : Number(chain);
@@ -48,25 +45,6 @@ function getContractRun(chain, address) {
     const client = (0, client_1.createClient)();
     return client.get(`/v0/contracts/${parseChain(chain)}/${encodeURIComponent(address)}`);
 }
-// ── Recommended contracts ──
-function getContractRecommendationsRun() {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
-    return client.get('/v0/contracts/recommendations');
-}
-exports.contracts.command('recommendations', {
-    description: 'List contracts the project already interacts with but has not added yet',
-    options: incur_1.z.object({}),
-    examples: [
-        {
-            description: 'Show recommended contracts to add for decoding/monitoring',
-        },
-    ],
-    hint: 'Requires contracts:read scope on your API key.',
-    run() {
-        return getContractRecommendationsRun();
-    },
-});
 exports.contracts.command('get', {
     description: 'Get a tracked contract by chain and address',
     args: incur_1.z.object({
@@ -197,41 +175,6 @@ exports.contracts.command('update', {
         return updateContractRun(args.chain, args.address, options);
     },
 });
-// ── Toggle contract pipeline inclusion ──
-function updateContractPipelineRun(chain, address, includeInPipeline) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
-    return client.patch(`/v0/contracts/${parseChain(chain)}/${encodeURIComponent(address)}/pipeline`, buildUpdateContractPipelineBody(includeInPipeline));
-}
-function buildUpdateContractPipelineBody(includeInPipeline) {
-    return { include_in_pipeline: includeInPipeline };
-}
-exports.contracts.command('pipeline', {
-    description: 'Toggle whether a tracked contract is included in the project events pipeline',
-    args: incur_1.z.object({
-        chain: incur_1.z.string().describe('Chain ID'),
-        address: incur_1.z.string().describe('Contract address (0x...)'),
-    }),
-    options: incur_1.z.object({
-        includeInPipeline: incur_1.z
-            .boolean()
-            .describe('true to include the contract in the pipeline, false to exclude it'),
-    }),
-    examples: [
-        {
-            args: {
-                chain: '1',
-                address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
-            },
-            options: { includeInPipeline: false },
-            description: 'Keep ABI decoding but exclude this contract from pipeline deploys',
-        },
-    ],
-    hint: 'Requires contracts:write scope on your API key.',
-    run({ args, options }) {
-        return updateContractPipelineRun(args.chain, args.address, options.includeInPipeline);
-    },
-});
 // ── Delete a contract ──
 function deleteContractRun(chain, address) {
     (0, client_1.requireApiKey)();

package/dist/commands/profiles.d.ts

@@ -11,11 +11,13 @@ export interface LifecycleThresholdOptions {
 }
 export interface GetProfileOptions extends LifecycleThresholdOptions {
     expand?: string;
+    timestamp?: string;
 }
 export declare function getProfileRun(address: string, optionsOrExpand?: GetProfileOptions | string): Promise<unknown>;
 export interface SearchProfilesOptions extends LifecycleThresholdOptions {
     address?: string;
     search?: string;
+    timestamp?: string;
     page?: number;
     size?: number;
     orderBy?: string;

package/dist/commands/profiles.js

@@ -75,6 +75,10 @@ const lifecycleThresholdOptions = {
         .optional()
         .describe('Override lifecycle at-risk prior active days threshold'),
 };
+const profileTimestampOption = incur_1.z
+    .string()
+    .datetime({ offset: true })
+    .optional();
 function getProfileRun(address, optionsOrExpand = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
@@ -84,6 +88,8 @@ function getProfileRun(address, optionsOrExpand = {}) {
     const params = {};
     if (options.expand)
         params.expand = options.expand;
+    if (options.timestamp)
+        params.timestamp = options.timestamp;
     addLifecycleThresholdParams(params, options);
     return client.get(`/v0/profiles/${encodeURIComponent(address)}`, { params });
 }
@@ -97,6 +103,7 @@ exports.profiles.command('get', {
             .string()
             .optional()
             .describe('Comma-separated list of fields to expand: apps,chains,tokens,labels'),
+        timestamp: profileTimestampOption.describe('Return the wallet-enrichment snapshot closest to this ISO-8601 timestamp'),
         ...lifecycleThresholdOptions,
     }),
     examples: [
@@ -106,6 +113,11 @@ exports.profiles.command('get', {
             options: { expand: 'labels,chains' },
             description: 'Get profile with expanded labels and chains',
         },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { timestamp: '2025-06-21T10:03:00Z' },
+            description: 'Get the closest stored wallet-enrichment snapshot',
+        },
     ],
     hint: 'Requires profiles:read scope on your API key.',
     run({ args, options }) {
@@ -275,6 +287,9 @@ function parseSearchFilters(raw) {
     return parsed;
 }
 function searchProfilesRun(options) {
+    if (options.timestamp && !options.address) {
+        throw new Error('--timestamp requires --address');
+    }
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     const params = {};
@@ -282,6 +297,8 @@ function searchProfilesRun(options) {
         params.address = options.address;
     if (options.search)
         params.search = options.search;
+    if (options.timestamp)
+        params.timestamp = options.timestamp;
     if (options.page !== undefined)
         params.page = options.page;
     if (options.size !== undefined)
@@ -313,6 +330,7 @@ exports.profiles.command('search', {
     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'),
+        timestamp: profileTimestampOption.describe('Return the closest wallet-enrichment snapshot; requires --address'),
         page: incur_1.z.coerce
             .number()
             .int()
@@ -373,6 +391,13 @@ exports.profiles.command('search', {
     }),
     examples: [
         { options: { size: 10 }, description: 'List first 10 profiles' },
+        {
+            options: {
+                address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
+                timestamp: '2025-06-21T10:03:00Z',
+            },
+            description: 'Search the closest stored wallet-enrichment snapshot',
+        },
         {
             options: { orderBy: 'net_worth_usd', orderDir: 'desc', size: 5 },
             description: 'Top 5 profiles by net worth',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formo/cli",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "packageManager": "pnpm@11.1.2",
   "engines": {
     "node": ">=22.12"
@@ -23,6 +23,10 @@
     "dist",
     "README.md"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "pnpm build",