@formo/cli 1.2.1 → 1.3.1

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`:
@@ -142,7 +148,8 @@ Merge-update identity properties on a wallet profile.
 
 | Option | Description |
 |---|---|
-| `--properties` | JSON object of properties to merge |
+| `--properties` | JSON object of properties to merge; use `null` to unset a property |
+| `--unset` | Comma-separated property keys to unset (`user_id` cannot be unset) |
 
 **Allowed property keys:** `user_id`, `display_name`, `email`, `farcaster`, `discord`, `twitter`, `telegram`, `instagram`, `website`, `github`, `linkedin`, `facebook`, `tiktok`, `youtube`, `reddit`, `avatar`, `description`, `location`, `ens`, `lens`, `basenames`, `linea`. Unknown keys are rejected server-side.
 
@@ -151,6 +158,8 @@ formo profiles update 0xd8dA... --properties '{"display_name":"Vitalik","twitter
 formo profiles update vitalik.eth --properties '{"email":"alice@example.com"}'
 ```
 
+`--unset` takes precedence over matching keys in `--properties`. Deletions also mask enriched fallback values and historical snapshot reads until a new value is set.
+
 > Requires `profiles:write` scope.
 
 ### `profiles properties batch`
@@ -241,13 +250,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`
@@ -266,7 +268,7 @@ Get a single board by ID.
 |---|---|
 | `--title` | Board title |
 | `--description` | Optional board description |
-| `--is-public` | Make the board publicly viewable |
+| `--is-public` | Make the board publicly viewable. Omit to keep it private (the default). |
 
 ```bash
 formo boards create --title "Revenue Metrics" --description "Weekly revenue tracking"
@@ -278,7 +280,7 @@ formo boards create --title "Revenue Metrics" --description "Weekly revenue trac
 |---|---|
 | `--title` | New board title |
 | `--description` | New board description |
-| `--is-public` | Update public visibility |
+| `--is-public` | Make the board publicly viewable. Omit to keep the stored setting; pass `--is-public=false` to make it private. |
 
 ### `boards delete <boardId>`
 Delete a board.
@@ -290,7 +292,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 +344,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`
 
@@ -354,8 +354,8 @@ List contracts the project already interacts with but has not added yet.
 | `--name` | Human-readable contract name |
 | `--abi` | Contract ABI as a JSON string; sent stringified to the API |
 | `--events` | JSON array of ABI event objects to monitor |
-| `--start-block` | Optional start block |
-| `--include-in-pipeline` | Include this contract in the Goldsky events pipeline (`true` by default in the API) |
+| `--start-block` | Non-negative safe integer recorded on the contract; does not backfill historical events |
+| `--include-in-pipeline` | Deploy this contract to the events pipeline. Omit for decode-only (the default). |
 
 ```bash
 formo contracts create --address 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 --chain 1 \
@@ -370,11 +370,9 @@ formo contracts create --address 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 --ch
 | `--name` | Updated contract name |
 | `--abi` | Updated ABI |
 | `--events` | Updated JSON array of ABI event objects |
-| `--start-block` | Optional start block |
-| `--include-in-pipeline` | Include or exclude this contract from the Goldsky events pipeline |
+| `--start-block` | Non-negative safe integer recorded on the contract; does not backfill historical events |
+| `--include-in-pipeline` | Deploy this contract to the events pipeline. Omit to keep the stored setting; pass `--include-in-pipeline=false` to exclude it. |
 
-### `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.
@@ -440,6 +438,12 @@ formo analytics retention --filters '[{"field":"location","op":"eq","value":"US"
 
 On `kpis`, `top_*`, `revenue_*` and `volume_by_metric`, `--params '{"page_scope":"session"}'` widens a `page` filter from page-scoped metrics (the default) to the legacy session scope.
 
+On user-aggregate pipes such as `lifecycle` and `frequency`, either-touch attribution filters can use a `fields` pair in place of `field`, e.g. `{"fields":["first_utm_source","last_utm_source"],"op":"eq","value":"twitter"}`.
+
+Overview Data source filters use `field: "channel"` with `web`, `mobile`, `api`, `import`, `server`, or `onchain`; acquisition channel uses `channel_type`. User/lifecycle source filters use `source_filter` through `--params` with `field: "source"`.
+
+Retention defaults to rolling (active in week N or later); use `--params '{"retention_type":"recurring"}'` for activity in exactly week N. Funnel steps accept `events` OR alternatives with member-level `filters`; the primary `type`/`event` is always included and step-level `filters` apply to the whole group.
+
 All user-attribute, profile, social, lifecycle and resource predicates go in the single `--filters` array, using the canonical envelope with named qualifiers (`chain_id`, `app_id`, `token_address`, `scope`, `tag_id`). The retired per-family params — `socials`, `chain_filters`, `app_filters`, `token_filters`, `label_filters`, `profile_filters`, `lifecycle_filter` — are rejected with a `400` if passed through `--params`.
 
 ---
@@ -554,7 +558,7 @@ Every command supports the standard incur output flags:
 | `--verbose` | Include the full envelope (`ok`, `data`, `meta`) |
 | `--filter-output <keys>` | Filter output by key paths (e.g. `data,meta.duration`) |
 
-Every list endpoint returns a `PaginatedResponse<T>` envelope: `{ data: [...], total, page, size, has_more }`. Every error follows: `{ error: { code, message, doc_url, param?, details? } }` — branch on `error.code`, not `message`.
+Every list endpoint returns a `PaginatedResponse<T>` envelope: `{ data: [...], total, page, size, has_more }`. Most API errors follow: `{ error: { code, message, doc_url, param?, details? } }` — branch on `error.code` when available. Event-ingestion errors can be `{error:"..."}`, and rate-limit responses can be plain text; HTTP status is authoritative.
 
 ---
 

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

@@ -17,15 +17,15 @@ exports.analytics = incur_1.Cli.create('analytics', {
 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, group_by, limit, attribution' },
+    { name: 'funnel', description: 'Conversion funnel across ordered steps. --params: steps (JSON array of {type,event,name,filters?,events?}; events adds OR alternatives with member filters), window_seconds, funnel_type, group_by, limit, attribution' },
     { 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: 'lifecycle', description: 'User lifecycle stages (New, Returning, Power user, At Risk, Churned, Resurrected)' },
+    { name: 'retention', description: 'Retention cohort analysis (params: retention_type — rolling by default or recurring, id_type, event_type, event_name, min_users)' },
+    { 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)' },
@@ -45,8 +45,11 @@ const RESERVED_PARAM_KEYS = new Set([
     'dateTo',
     'filters',
 ]);
-const ANALYTICS_FILTER_KEYS = new Set(['field', 'op', 'value', 'filters']);
-const ANALYTICS_NESTED_FILTER_KEYS = new Set(['field', 'op', 'value']);
+const ANALYTICS_FILTER_KEYS = new Set([
+    'field', 'fields', 'op', 'value', 'filters',
+    'chain_id', 'app_id', 'token_address', 'scope', 'tag_id',
+]);
+const ANALYTICS_NESTED_FILTER_KEYS = new Set(['field', 'fields', 'op', 'value']);
 function validateAnalyticsFilter(filter, path, allowNested) {
     if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
         throw new Error(`${path} must be a {field, op, value} object`);
@@ -59,11 +62,19 @@ function validateAnalyticsFilter(filter, path, allowNested) {
         ? ANALYTICS_FILTER_KEYS
         : ANALYTICS_NESTED_FILTER_KEYS;
     if (Object.keys(record).some((key) => !allowedKeys.has(key))) {
-        throw new Error(`${path} may only contain field, op, value${allowNested ? ', and filters' : ''}`);
+        throw new Error(`${path} may only contain field, op, value, fields${allowNested ? ', filters, and resource qualifiers (chain_id, app_id, token_address, scope, tag_id)' : ''}`);
+    }
+    if (record.field !== undefined && record.fields !== undefined) {
+        throw new Error(`${path} must use only one of field or fields`);
+    }
+    if (record.fields !== undefined && (!Array.isArray(record.fields) || record.fields.length !== 2 ||
+        !record.fields.every((field) => typeof field === 'string' && field.length > 0))) {
+        throw new Error(`${path}.fields must name exactly two non-empty columns`);
     }
-    if (typeof record.field !== 'string' || record.field.length === 0) {
-        throw new Error(`${path} requires a non-empty string "field"`);
+    if (record.fields === undefined && (typeof record.field !== 'string' || record.field.length === 0)) {
+        throw new Error(`${path} requires a non-empty string "field" or a "fields" pair`);
     }
+    (0, filters_1.validateQualifiers)(record, typeof record.field === 'string' ? record.field : '', path);
     if (!(0, filters_1.isCanonicalFilterOperator)(record.op)) {
         throw new Error(`${path} requires a canonical "op"`);
     }
@@ -163,7 +174,7 @@ const sharedOptions = incur_1.z.object({
         .string()
         .optional()
         .describe('JSON array of filter conditions: [{"field","op","value"}]. ' +
-        'Use op "in"/"nin" with an array value (e.g. ["chrome","firefox"]); pipe-delimited strings are also accepted. Array string members cannot contain "|".'),
+        'Use op "in"/"nin" with an array value (e.g. ["chrome","firefox"]); pipe-delimited strings are also accepted. Array string members cannot contain "|". Resource filters accept chain_id, app_id, token_address, scope, and tag_id qualifiers.'),
     params: incur_1.z
         .string()
         .optional()

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);
@@ -25,6 +22,12 @@ function parseChain(chain) {
     }
     return value;
 }
+function parseStartBlock(value) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        throw new Error('--start-block must be a non-negative safe integer');
+    }
+    return value;
+}
 // ── List contracts ──
 function listContractsRun(options = {}) {
     (0, client_1.requireApiKey)();
@@ -48,25 +51,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({
@@ -98,7 +82,7 @@ function buildCreateContractBody(options) {
         events: parsedEvents,
     };
     if (options.startBlock !== undefined)
-        body.start_block = options.startBlock;
+        body.start_block = parseStartBlock(options.startBlock);
     if (options.includeInPipeline !== undefined) {
         body.include_in_pipeline = options.includeInPipeline;
     }
@@ -151,7 +135,7 @@ function buildUpdateContractBody(chain, address, options) {
         events: parsedEvents,
     };
     if (options.startBlock !== undefined)
-        body.start_block = options.startBlock;
+        body.start_block = parseStartBlock(options.startBlock);
     if (options.includeInPipeline !== undefined) {
         body.include_in_pipeline = options.includeInPipeline;
     }
@@ -197,41 +181,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/import.js

@@ -15,6 +15,8 @@ function buildImportBody(options) {
     }
     if (options.rows) {
         const rows = (0, json_1.parseJsonArrayOfObjects)(options.rows, '--rows');
+        if (rows.length === 0)
+            throw new Error('--rows must contain at least one wallet');
         const addresses = rows.map((row) => row.address);
         if (addresses.some((address) => typeof address !== 'string' || !address)) {
             throw new Error('--rows entries must each include a non-empty string address');
@@ -28,6 +30,8 @@ function buildImportBody(options) {
         throw new Error('Provide --addresses or --rows');
     }
     const addresses = (0, json_1.parseJsonArray)(options.addresses, '--addresses');
+    if (addresses.length === 0)
+        throw new Error('--addresses must contain at least one wallet');
     if (addresses.some((address) => typeof address !== 'string' || !address)) {
         throw new Error('--addresses must be a JSON array of wallet address strings');
     }

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;
@@ -33,7 +35,8 @@ export interface SearchProfilesOptions extends LifecycleThresholdOptions {
 export declare function parseSearchFilters(raw: string): unknown[];
 export declare function searchProfilesRun(options: SearchProfilesOptions): Promise<unknown>;
 export interface UpdateProfileOptions {
-    properties: string;
+    properties?: string;
+    unset?: string;
 }
 export declare function buildUpdateProfileBody(options: UpdateProfileOptions): Record<string, unknown>;
 export declare function updateProfileRun(address: string, options: UpdateProfileOptions): Promise<unknown>;

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 }) {
@@ -138,72 +150,12 @@ const RESOURCE_FIELD_PREFIXES = new Set([
     'label',
     'labels',
 ]);
-const QUALIFIER_KEYS = [
-    'chain_id',
-    'app_id',
-    'token_address',
-    'tag_id',
-    'scope',
-];
 const FILTER_ENTRY_KEYS = new Set([
     'field',
     'op',
     'value',
-    ...QUALIFIER_KEYS,
+    ...filters_1.QUALIFIER_KEYS,
 ]);
-/**
- * Enforce the per-field qualifier rules, mirroring the API's schema. Sending a
- * qualifier the field does not accept — or omitting a required one — is a 400,
- * so we fail here with a message that names the offending key.
- */
-function validateQualifiers(record, field) {
-    const present = (key) => record[key] !== undefined;
-    const required = (key) => {
-        if (!present(key)) {
-            throw new Error(`--filters: "${key}" is required for "${field}"`);
-        }
-    };
-    const forbidden = (keys) => {
-        for (const key of keys) {
-            if (present(key)) {
-                throw new Error(`--filters: "${key}" is not valid for "${field}"`);
-            }
-        }
-    };
-    switch (field) {
-        case 'chains.balance':
-            // chain_id optional — omit it to match any chain.
-            forbidden(['app_id', 'token_address', 'tag_id', 'scope']);
-            break;
-        case 'apps.balance':
-            required('app_id');
-            forbidden(['token_address', 'tag_id', 'scope']);
-            break;
-        case 'tokens.balance':
-            required('token_address');
-            required('scope');
-            if (record.scope !== 'any' && record.scope !== 'protocol') {
-                throw new Error(`--filters: "scope" must be "any" or "protocol"`);
-            }
-            // app_id identifies the protocol, so it is required by (and only by)
-            // scope: "protocol".
-            if (record.scope === 'protocol') {
-                required('app_id');
-            }
-            else {
-                forbidden(['app_id']);
-            }
-            forbidden(['tag_id']);
-            break;
-        case 'labels.value':
-            required('tag_id');
-            forbidden(['app_id', 'token_address', 'scope']);
-            break;
-        default:
-            // users.* — a user attribute carries no resource identity.
-            forbidden(QUALIFIER_KEYS);
-    }
-}
 /**
  * Parse and validate the --filters JSON. Ensures it is an array of
  * `{ field, op, value }` objects carrying a canonical `field` — either
@@ -251,7 +203,7 @@ function parseSearchFilters(raw) {
                     '(a bare name is silently ignored by the API and returns the entire unfiltered dataset)');
             }
         }
-        validateQualifiers(record, field);
+        (0, filters_1.validateQualifiers)(record, field);
         // The balance fields compare numerically; a stringified number is a 400.
         if (field !== 'labels.value' &&
             RESOURCE_FILTER_FIELDS.has(field) &&
@@ -275,6 +227,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 +237,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 +270,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 +331,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',
@@ -417,9 +382,26 @@ exports.profiles.command('search', {
     },
 });
 function buildUpdateProfileBody(options) {
-    const body = (0, json_1.parseJsonObject)(options.properties, '--properties');
+    const body = options.properties
+        ? (0, json_1.parseJsonObject)(options.properties, '--properties')
+        : {};
+    if (options.unset) {
+        const keys = options.unset
+            .split(',')
+            .map((key) => key.trim())
+            .filter((key) => key.length > 0);
+        if (keys.length === 0) {
+            throw new Error('--unset must list at least one property key');
+        }
+        for (const key of keys) {
+            if (key === 'user_id') {
+                throw new Error('user_id cannot be unset (it participates in identity stitching)');
+            }
+            body[key] = null;
+        }
+    }
     if (Object.keys(body).length === 0) {
-        throw new Error('--properties must contain at least one key');
+        throw new Error('provide --properties and/or --unset with at least one key');
     }
     return body;
 }
@@ -436,7 +418,12 @@ exports.profiles.command('update', {
     options: incur_1.z.object({
         properties: incur_1.z
             .string()
-            .describe('JSON object of properties to merge. Allowed keys: user_id, display_name, email, farcaster, discord, twitter, telegram, instagram, website, github, linkedin, facebook, tiktok, youtube, reddit, avatar, description, location, ens, lens, basenames, linea'),
+            .optional()
+            .describe('JSON object of properties to merge; a null value unsets (deletes) that property. Allowed keys: user_id, display_name, email, farcaster, discord, twitter, telegram, instagram, website, github, linkedin, facebook, tiktok, youtube, reddit, avatar, description, location, ens, lens, basenames, linea'),
+        unset: incur_1.z
+            .string()
+            .optional()
+            .describe('Comma-separated property keys to unset (delete), e.g. "email,twitter". Shorthand for null values in --properties. user_id cannot be unset.'),
     }),
     examples: [
         {
@@ -451,8 +438,18 @@ exports.profiles.command('update', {
             options: { properties: '{"email":"alice@example.com"}' },
             description: 'Set just the email',
         },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { unset: 'email,twitter' },
+            description: 'Delete the email and Twitter properties',
+        },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { properties: '{"display_name":"alice.eth"}', unset: 'email' },
+            description: 'Set a new display name and delete the email in one call',
+        },
     ],
-    hint: 'Requires profiles:write scope on your API key. Only the listed keys are accepted; unknown keys are rejected.',
+    hint: 'Requires profiles:write scope on your API key. Only the listed keys are accepted; unknown keys are rejected. Deleting a property hides any globally-enriched fallback value too; user_id cannot be unset.',
     run({ args, options }) {
         return updateProfileRun(args.address, options);
     },
@@ -482,7 +479,7 @@ exports.profilesProperties.command('batch', {
     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.'),
+            .describe('JSON array of flat {address,...properties} objects; a null value unsets (deletes) that property (user_id cannot be unset). ENS names are not resolved in batch requests.'),
     }),
     examples: [
         {
@@ -491,6 +488,12 @@ exports.profilesProperties.command('batch', {
             },
             description: 'Batch set display names and emails',
         },
+        {
+            options: {
+                rows: '[{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","email":null}]',
+            },
+            description: 'Batch delete emails (null unsets a property)',
+        },
     ],
     hint: 'Requires profiles:write scope on your API key. Unknown keys are ignored by the API; invalid rows are quarantined.',
     run({ options }) {

package/dist/lib/client.d.ts

@@ -4,7 +4,7 @@ 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?: {
+    error?: string | {
         code?: string;
         message?: string;
         doc_url?: string;

package/dist/lib/client.js

@@ -30,8 +30,14 @@ function getEventsBaseUrl() {
 function parseApiError(error) {
     const status = error.response?.status;
     const body = error.response?.data;
-    const apiError = body?.error;
-    const baseMessage = apiError?.message ?? error.message;
+    const rawError = body?.error;
+    const apiError = rawError && typeof rawError === 'object' ? rawError : undefined;
+    const plainMessage = typeof rawError === 'string'
+        ? rawError
+        : typeof error.response?.data === 'string'
+            ? error.response.data
+            : undefined;
+    const baseMessage = apiError?.message ?? plainMessage ?? error.message;
     const parts = [];
     parts.push(apiError?.code ? `[${apiError.code}] ${baseMessage}` : baseMessage);
     if (apiError?.param)

package/dist/lib/filters.d.ts

@@ -4,3 +4,10 @@ export declare function isValuelessFilterOperator(op: unknown): boolean;
 export declare function isCanonicalFilterValue(value: unknown): boolean;
 export declare function isEmptyMembershipArray(value: unknown): boolean;
 export declare function hasTinybirdMembershipDelimiter(value: unknown): boolean;
+export declare const QUALIFIER_KEYS: readonly ["chain_id", "app_id", "token_address", "tag_id", "scope"];
+/**
+ * Enforce the per-field qualifier rules, mirroring the API's schema. Sending a
+ * qualifier the field does not accept — or omitting a required one — is a 400,
+ * so we fail here with a message that names the offending key.
+ */
+export declare function validateQualifiers(record: Record<string, unknown>, field: string, path?: string): void;

package/dist/lib/filters.js

@@ -1,11 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANONICAL_FILTER_OPERATORS = void 0;
+exports.QUALIFIER_KEYS = exports.CANONICAL_FILTER_OPERATORS = void 0;
 exports.isCanonicalFilterOperator = isCanonicalFilterOperator;
 exports.isValuelessFilterOperator = isValuelessFilterOperator;
 exports.isCanonicalFilterValue = isCanonicalFilterValue;
 exports.isEmptyMembershipArray = isEmptyMembershipArray;
 exports.hasTinybirdMembershipDelimiter = hasTinybirdMembershipDelimiter;
+exports.validateQualifiers = validateQualifiers;
 exports.CANONICAL_FILTER_OPERATORS = [
     'eq',
     'neq',
@@ -43,3 +44,71 @@ function hasTinybirdMembershipDelimiter(value) {
     return (Array.isArray(value) &&
         value.some((item) => typeof item === 'string' && item.includes('|')));
 }
+exports.QUALIFIER_KEYS = [
+    'chain_id',
+    'app_id',
+    'token_address',
+    'tag_id',
+    'scope',
+];
+/**
+ * Enforce the per-field qualifier rules, mirroring the API's schema. Sending a
+ * qualifier the field does not accept — or omitting a required one — is a 400,
+ * so we fail here with a message that names the offending key.
+ */
+function validateQualifiers(record, field, path = '--filters') {
+    for (const key of exports.QUALIFIER_KEYS) {
+        if (record[key] !== undefined && (typeof record[key] !== 'string' || record[key] === '')) {
+            throw new Error(`${path}.${key} must be a non-empty string`);
+        }
+    }
+    if (record.scope !== undefined && record.scope !== 'any' && record.scope !== 'protocol') {
+        throw new Error(`${path}.scope must be any or protocol`);
+    }
+    const present = (key) => record[key] !== undefined;
+    const required = (key) => {
+        if (!present(key)) {
+            throw new Error(`${path}: "${key}" is required for "${field}"`);
+        }
+    };
+    const forbidden = (keys) => {
+        for (const key of keys) {
+            if (present(key)) {
+                throw new Error(`${path}: "${key}" is not valid for "${field}"`);
+            }
+        }
+    };
+    switch (field) {
+        case 'chains.balance':
+            // chain_id optional — omit it to match any chain.
+            forbidden(['app_id', 'token_address', 'tag_id', 'scope']);
+            break;
+        case 'apps.balance':
+            required('app_id');
+            forbidden(['token_address', 'tag_id', 'scope']);
+            break;
+        case 'tokens.balance':
+            required('token_address');
+            required('scope');
+            if (record.scope !== 'any' && record.scope !== 'protocol') {
+                throw new Error(`${path}: "scope" must be "any" or "protocol"`);
+            }
+            // app_id identifies the protocol, so it is required by (and only by)
+            // scope: "protocol".
+            if (record.scope === 'protocol') {
+                required('app_id');
+            }
+            else {
+                forbidden(['app_id']);
+            }
+            forbidden(['tag_id']);
+            break;
+        case 'labels.value':
+            required('tag_id');
+            forbidden(['app_id', 'token_address', 'scope']);
+            break;
+        default:
+            // users.* — a user attribute carries no resource identity.
+            forbidden(exports.QUALIFIER_KEYS);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formo/cli",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "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",