@formo/cli 1.1.0 → 1.2.0

package/README.md

@@ -104,23 +104,38 @@ Search wallet profiles with filters, sorting, and pagination. Returns a `Paginat
 | Option | Description |
 |---|---|
 | `--address` | Filter by wallet address |
+| `--search` | Free-text search across address and identity fields |
 | `--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` |
 | `--order-dir` | `asc` or `desc` |
 | `--expand` | Comma-separated fields to expand |
-| `--conditions` | JSON array of `FilterCondition` objects (see below) |
-| `--logic` | Combine conditions with `and` (default) or `or` |
+| `--filters` | JSON array of canonical `{field,op,value}` filter objects (see below) |
+| `--logic` | Combine filters with `and` (default) or `or` |
 
 ```bash
 formo profiles search --size 10
 formo profiles search --order-by net_worth_usd --order-dir desc --size 5
 formo profiles search --page 2 --size 20
-formo profiles search --conditions '[{"field":"users.net_worth_usd","op":"gt","value":10000}]' --size 20
-formo profiles search --conditions '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]' --logic or --size 20
-formo profiles search --conditions '[{"field":"chains.1.balance","op":"gt","value":1000}]' --size 20
+formo profiles search --filters '[{"field":"users.net_worth_usd","op":"gt","value":10000}]' --size 20
+formo profiles search --filters '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]' --logic or --size 20
+formo profiles search --filters '[{"field":"chains.balance","op":"gt","value":1000,"chain_id":"1"}]' --size 20
 ```
 
+### Lifecycle tuning (advanced)
+
+Both `profiles get` and `profiles search` accept optional flags to override the lifecycle stage thresholds used when computing `lifecycle`:
+
+| Option | Description |
+|---|---|
+| `--new-window-days` | Override lifecycle new-user window in days |
+| `--churn-window-days` | Override lifecycle churn window in days |
+| `--power-user-min-active-days` | Override lifecycle power-user minimum active days |
+| `--power-user-window-days` | Override lifecycle power-user window in days |
+| `--resurrected-gap-days` | Override lifecycle resurrected gap in days |
+| `--at-risk-min-days-inactive` | Override lifecycle at-risk minimum inactive days |
+| `--at-risk-prior-active-days-threshold` | Override lifecycle at-risk prior active days threshold |
+
 ### `profiles update <address>`
 
 Merge-update identity properties on a wallet profile.
@@ -205,15 +220,16 @@ Get a single alert by ID.
 | `--trigger-filters` | JSON array of trigger filter objects |
 | `--recipient` | JSON array of recipient objects |
 | `--secret` | Webhook secret |
+| `--slack-property-keys` | JSON array of event/user property keys to include in Slack alerts |
 
 ```bash
 formo alerts create --name "High value tx" --trigger-type event \
-  --trigger-filters '[{"name":"event","operator":"eq","value":"transaction"}]' \
+  --trigger-filters '[{"field":"event","op":"eq","value":"transaction"}]' \
   --recipient '[{"type":"email","value":["alerts@myapp.com"]}]'
 ```
 
 ### `alerts update <alertId>`
-Same options as `create`. Replaces the alert configuration.
+Same options as `create`. Replaces the alert configuration in full — omitted options are reset to their defaults (e.g. leaving out `--trigger-filters` clears the existing trigger filters).
 
 ### `alerts delete <alertId>`
 Delete an alert.
@@ -271,7 +287,7 @@ Delete a board.
 
 ## `formo charts`
 
-Chart commands. Charts live inside a board. Requires `charts:read` / `charts:write`.
+Chart commands. Charts live inside a board. Requires `boards:read` / `boards:write`.
 
 ### `charts list --board-id <boardId>`
 List all charts in a board.
@@ -292,10 +308,18 @@ formo charts create --board-id brd_123 --title "Daily Active Users" \
   --x-axis date --y-axis users
 
 formo charts create --board-id brd_123 --body '{"title":"Recent Events","chart_type":"table","query":"SELECT * FROM events LIMIT 10"}'
+
+formo charts create --board-id brd_123 --title "Post-connect paths" \
+  --chart-type user_paths \
+  --settings '{"anchors":[{"type":"event","event":"connect"}],"maxSteps":5,"nodesPerStep":3}'
 ```
 
-### `charts update <chartId> --board-id <boardId> --body '<json>'`
-Update a chart.
+### `charts update <chartId> --board-id <boardId> [options]`
+Update a chart. Accepts the same options as `create`: a raw `--body '<json>'` and/or typed flags (`--title`, `--chart-type`, `--query`, `--description`, `--x-axis`, `--y-axis`, `--group-by`, `--steps`, `--settings`). `--steps` is for funnel steps. User Paths use `--settings` with `anchors` and optional `maxSteps` / `nodesPerStep`; retention settings require an `entryFilter` key. Typed flags override matching `--body` keys.
+
+```bash
+formo charts update chart_abc123 --board-id brd_123 --title "Renamed chart"
+```
 
 ### `charts query <chartId> --board-id <boardId> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD>`
 Execute a saved chart that uses `{{date_from}}` / `{{date_to}}` variables.
@@ -369,7 +393,7 @@ List all user segments.
 | Option | Description |
 |---|---|
 | `--title` | Segment title |
-| `--filter-sets` | JSON array of filter set strings defining the segment |
+| `--filters` | JSON array of canonical `{field,op,value}` filter objects. Array string members cannot contain `|` |
 
 ### `segments delete <segmentId>`
 Delete a user segment.
@@ -401,7 +425,7 @@ Pre-built analytics pipes — the same data that powers the Formo dashboard —
 |---|---|
 | `--date-from` | Inclusive start date `YYYY-MM-DD` (default: 7 days before `--date-to`) |
 | `--date-to` | Inclusive end date `YYYY-MM-DD` (default: today) |
-| `--filters` | JSON array of `[{field,op,value}]`. Use `in`/`nin` with a pipe-delimited value (e.g. `"chrome\|firefox"`) |
+| `--filters` | JSON array of `[{field,op,value}]`. For `in`/`nin`, array values are preferred; pipe-delimited strings are also accepted. Array string members cannot contain `|` |
 | `--params` | JSON object of pipe-specific params merged into the query (e.g. `{"limit":10,"group_by":"device"}`) |
 
 ```bash
@@ -414,13 +438,17 @@ formo analytics retention --filters '[{"field":"location","op":"eq","value":"US"
 
 > Requires `query:read` scope. Run `formo analytics <pipe> --help` for the pipe-specific params accepted via `--params`.
 
+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.
+
+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`.
+
 ---
 
 ## `formo import`
 
 ### `import wallets`
 
-Bulk-import wallet addresses into the project via the events API.
+Bulk-import wallet addresses into the project via the main Formo API, authenticated with your workspace API key.
 
 | Option | Description |
 |---|---|
@@ -432,53 +460,86 @@ formo import wallets --addresses '["0xabc...","0xdef..."]'
 formo import wallets --rows '[{"address":"0xabc...","properties":{"display_name":"Alice"}}]'
 ```
 
+> Requires `profiles:write` scope. Only available on Scale and Enterprise plans.
+
 ---
 
 ## `formo events`
 
 ### `events ingest`
 
-Send raw analytics events to `events.formo.so`. This command uses a project SDK write key, not the workspace API key.
+Send raw analytics events to `events.formo.so`. This command uses a project SDK write key, not the workspace API key — pass it via `--write-key` or the `FORMO_WRITE_KEY` environment variable.
+
+| Option | Description |
+|---|---|
+| `--event` | Single event as a JSON object; wrapped in an array before sending |
+| `--events` | JSON array of event objects to send as a batch |
+| `--write-key` | Project SDK write key (defaults to `FORMO_WRITE_KEY`) |
 
 ```bash
 export FORMO_WRITE_KEY=formo_write_key_xxx
 formo events ingest --event '{"type":"track","channel":"cli","version":"1","anonymous_id":"anon_123","event":"CLI Test","context":{},"properties":{},"original_timestamp":"2026-04-27T23:05:38.000Z","sent_at":"2026-04-27T23:05:42.000Z","message_id":"cli-test-1"}'
+formo events ingest --events '[{"type":"track","event":"First"},{"type":"track","event":"Second"}]'
 ```
 
 ---
 
 ## FilterCondition reference
 
-`profiles search --conditions` accepts a JSON array of filter condition objects:
+`profiles search --filters` accepts a JSON array of canonical filter objects:
 
 ```json
 [
   { "field": "users.net_worth_usd", "op": "gt", "value": 10000 },
-  { "field": "chains.1.balance", "op": "gte", "value": 1000 }
+  { "field": "chains.balance", "op": "gte", "value": 1000, "chain_id": "1" }
 ]
 ```
 
-> **The `field` must be a typed path.** A bare name like `net_worth_usd` is
+> **The `field` must be a canonical path.** A bare name like `net_worth_usd` is
 > silently ignored by the API (no error, no filtering — the search returns
-> everything). Always prefix the field with its type.
+> everything). Resource identity goes in the named qualifiers below, never in
+> the field path — identifier-in-path fields such as `chains.1.balance` are
+> rejected with a `400`.
 
 | Field | Type | Description |
 |---|---|---|
-| `field` | `string` | Typed path (see prefixes below) |
-| `op` | `string` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains` (social fields only), `notEmpty` / `isEmpty` (value-less existence checks). Long-form spellings (`equals`, `greater`, `includes`, …) are retired — the API rejects them with a `400` naming the token |
-| `value` | `any` | Value to compare against |
-| `scope` | `string` | _(token filters only)_ `any` or `protocol` |
-| `appId` | `string` | _(token filters with `scope: protocol`)_ e.g. `aave-v3` |
+| `field` | `string` | `users.{attribute}` or one of the four resource paths (see below) |
+| `op` | `string` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `startsWith`, `endsWith`, `notEmpty` / `isEmpty` (value-less existence checks). Support is per field — see [operator support](#operator-support). Long-form spellings (`equals`, `greater`, `includes`, …) are retired — the API rejects them with a `400` naming the token |
+| `value` | `any` | Value to compare against; must be a number on the `.balance` fields |
+| `chain_id` | `string` | _(optional on any resource filter)_ restrict to one chain; omit to match any |
+| `app_id` | `string` | _(required by `apps.balance`, and by `tokens.balance` with `scope: protocol`)_ e.g. `aave-v3` |
+| `token_address` | `string` | _(required by `tokens.balance`)_ |
+| `tag_id` | `string` | _(required by `labels.value`)_ e.g. `coinbase.verified_account` |
+| `scope` | `string` | _(required by `tokens.balance`)_ `any` or `protocol` |
+
+| Field | Required qualifiers | Example |
+|---|---|---|
+| `users.{attribute}` | none | `{"field":"users.net_worth_usd","op":"gt","value":10000}` |
+| `chains.balance` | none (`chain_id` optional) | `{"field":"chains.balance","op":"gte","value":1000,"chain_id":"1"}` |
+| `apps.balance` | `app_id` | `{"field":"apps.balance","op":"gt","value":500,"app_id":"uniswap-v3"}` |
+| `tokens.balance` | `token_address`, `scope` | `{"field":"tokens.balance","op":"gt","value":0,"token_address":"0xA0b8…48","scope":"any"}` |
+| `labels.value` | `tag_id` | `{"field":"labels.value","op":"eq","value":"true","tag_id":"coinbase.verified_account"}` |
 
-| Prefix | Examples |
-|---|---|
-| `users.` | `users.net_worth_usd`, `users.volume`, `users.revenue`, `users.points`, `users.device`, `users.location`, `users.lifecycle`, `users.ens`, `users.farcaster` |
-| `chains.` | `chains.balance` (any chain), `chains.1.balance` (Ethereum) |
-| `apps.` | `apps.uniswap-v3.balance` |
-| `tokens.` | `tokens.0xA0b8…48.balance` |
-| `labels.` | `labels.coinbase.verified_account` |
+User attributes for `users.{attribute}`: `net_worth_usd`, `volume`, `revenue`,
+`points`, `device`, `location`, `lifecycle`, `ens`, `farcaster`, and the other
+social handles.
+
+### Operator support
 
-Combine multiple conditions with `--logic and` (default) or `--logic or`.
+The canonical vocabulary is shared, but each field implements a subset. The API
+rejects an unsupported pairing with a `400`:
+
+| Field class | Supported operators |
+|---|---|
+| `chains.balance`, `apps.balance`, `tokens.balance` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte` (value must be a JSON number) |
+| `labels.value` | comparison operators plus `contains` (case-insensitive) |
+| Numeric profile metrics (`users.net_worth_usd`, `users.volume`, `users.revenue`, `users.points`) | comparison operators |
+| Routable string attributes (`users.device`, `users.os`, `users.referrer`, `users.utm_*`, `users.click_id`, and the `first_*`/`last_*` attribution variants) | full vocabulary; `contains`/`startsWith`/`endsWith` match case-sensitively |
+| Social fields (`users.twitter`, `users.email`, `users.farcaster`, …) | `contains` (case-insensitive) and `notEmpty`; `startsWith`/`endsWith`/`isEmpty` are rejected |
+| `users.paid_source` (and `first_`/`last_` variants) | `eq`, `neq`, `in`, `nin`, `notEmpty`, `isEmpty` — it is a fixed ad-network enum |
+| `users.lifecycle` | `eq` (one stage) and `in` (a list of stages) |
+
+Combine multiple filters with `--logic and` (default) or `--logic or`.
 
 ---
 

package/dist/commands/alerts.d.ts

@@ -1,36 +1,28 @@
 import { Cli } from 'incur';
+import { type PaginationOptions } from '../lib/pagination';
+export type { PaginationOptions };
 export declare const alerts: Cli.Cli<{}, undefined, undefined>;
-export interface PaginationOptions {
-    page?: number;
-    size?: number;
-}
-export declare function listAlertsRun(options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function getAlertRun(alertId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export interface CreateAlertOptions {
-    name: string;
-    triggerType: 'event' | 'user' | string;
-    triggerFilters?: string;
-    recipient?: string;
-    secret?: string;
-    slackPropertyKeys?: string;
-}
-export declare function buildAlertBody(options: CreateAlertOptions | UpdateAlertOptions): Record<string, unknown>;
-export declare function createAlertRun(options: CreateAlertOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export interface UpdateAlertOptions {
+export declare function listAlertsRun(options?: PaginationOptions): Promise<unknown>;
+export declare function getAlertRun(alertId: string): Promise<unknown>;
+export interface AlertBodyOptions {
     name: string;
-    triggerType: 'event' | 'user' | string;
+    triggerType: string;
     triggerFilters?: string;
     recipient?: string;
     secret?: string;
     slackPropertyKeys?: string;
 }
-export declare function updateAlertRun(alertId: string, options: UpdateAlertOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function deleteAlertRun(alertId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export declare function toggleAlertRun(alertId: string, status: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export type CreateAlertOptions = AlertBodyOptions;
+export type UpdateAlertOptions = AlertBodyOptions;
+export declare function buildAlertBody(options: AlertBodyOptions): Record<string, unknown>;
+export declare function createAlertRun(options: CreateAlertOptions): Promise<unknown>;
+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<import("axios").AxiosResponse<any, any, {}>>;
+export declare function testAlertRun(alertId: string, options?: TestAlertOptions): Promise<unknown>;

package/dist/commands/alerts.js

@@ -12,29 +12,21 @@ exports.buildTestAlertBody = buildTestAlertBody;
 exports.testAlertRun = testAlertRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const filters_1 = require("../lib/filters");
 const json_1 = require("../lib/json");
+const pagination_1 = require("../lib/pagination");
 exports.alerts = incur_1.Cli.create('alerts', {
     description: 'Project alert commands — create, list, update, and delete alerts',
 });
-function buildPaginationParams(options = {}) {
-    const params = {};
-    if (options.page !== undefined)
-        params.page = options.page;
-    if (options.size !== undefined)
-        params.size = options.size;
-    return params;
-}
+// ── List alerts ──
 function listAlertsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/alerts/', { params: buildPaginationParams(options) });
+    return client.get('/v0/alerts/', { params: (0, pagination_1.buildPaginationParams)(options) });
 }
 exports.alerts.command('list', {
     description: 'List all alerts 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)'),
-    }),
+    options: incur_1.z.object(pagination_1.paginationOptionsSchema),
     examples: [{ description: 'List all project alerts' }],
     hint: 'Requires alerts:read scope on your API key.',
     run({ options }) {
@@ -60,6 +52,24 @@ exports.alerts.command('get', {
         return getAlertRun(args.alertId);
     },
 });
+// Shared option fragment for `create` and `update` (same PUT/POST body).
+const alertBodyOptionsSchema = {
+    name: incur_1.z.string().describe('Alert name'),
+    triggerType: incur_1.z.enum(['event', 'user']).describe('Trigger type'),
+    triggerFilters: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON array of trigger filter objects'),
+    recipient: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON array of recipient objects'),
+    secret: incur_1.z.string().optional().describe('Webhook secret for the alert'),
+    slackPropertyKeys: incur_1.z
+        .string()
+        .optional()
+        .describe('JSON array of event/user property keys to include in Slack alerts'),
+};
 function buildAlertBody(options) {
     const body = {
         name: options.name,
@@ -67,7 +77,27 @@ function buildAlertBody(options) {
         trigger_filters: [],
     };
     if (options.triggerFilters) {
-        body.trigger_filters = (0, json_1.parseJsonArray)(options.triggerFilters, '--trigger-filters');
+        const triggerFilters = (0, json_1.parseJsonArray)(options.triggerFilters, '--trigger-filters');
+        for (const filter of triggerFilters) {
+            if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
+                throw new Error('--trigger-filters must be a JSON array of {field, op, value} objects');
+            }
+            const record = filter;
+            if (typeof record.field !== 'string' ||
+                record.field.length === 0 ||
+                typeof record.value !== 'string') {
+                throw new Error('--trigger-filters: each entry requires string "field" and "value"');
+            }
+            if (record.op !== undefined &&
+                record.op !== '' &&
+                !(0, filters_1.isCanonicalFilterOperator)(record.op)) {
+                throw new Error('--trigger-filters: "op" must use the canonical filter vocabulary');
+            }
+            if (Object.keys(record).some((key) => !['field', 'op', 'value', 'numericThreshold'].includes(key))) {
+                throw new Error('--trigger-filters entries may only contain field, op, value, and numericThreshold');
+            }
+        }
+        body.trigger_filters = triggerFilters;
     }
     if (options.recipient) {
         body.recipient = (0, json_1.parseJsonArray)(options.recipient, '--recipient');
@@ -87,23 +117,7 @@ function createAlertRun(options) {
 }
 exports.alerts.command('create', {
     description: 'Create a new project alert',
-    options: incur_1.z.object({
-        name: incur_1.z.string().describe('Alert name'),
-        triggerType: incur_1.z.enum(['event', 'user']).describe('Trigger type'),
-        triggerFilters: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of trigger filter objects'),
-        recipient: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of recipient objects'),
-        secret: incur_1.z.string().optional().describe('Webhook secret for the alert'),
-        slackPropertyKeys: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of event/user property keys to include in Slack alerts'),
-    }),
+    options: incur_1.z.object(alertBodyOptionsSchema),
     examples: [
         {
             options: { name: 'High value tx', triggerType: 'event' },
@@ -115,33 +129,18 @@ exports.alerts.command('create', {
         return createAlertRun(options);
     },
 });
+// ── Update an alert ──
 function updateAlertRun(alertId, options) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     return client.put(`/v0/alerts/${encodeURIComponent(alertId)}`, buildAlertBody(options));
 }
 exports.alerts.command('update', {
-    description: 'Update an existing alert',
+    description: 'Update an existing alert (full replace — omitted options reset to defaults)',
     args: incur_1.z.object({
         alertId: incur_1.z.string().describe('Alert ID to update'),
     }),
-    options: incur_1.z.object({
-        name: incur_1.z.string().describe('Alert name'),
-        triggerType: incur_1.z.enum(['event', 'user']).describe('Trigger type'),
-        triggerFilters: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of trigger filter objects'),
-        recipient: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of recipient objects'),
-        secret: incur_1.z.string().optional().describe('Webhook secret for the alert'),
-        slackPropertyKeys: incur_1.z
-            .string()
-            .optional()
-            .describe('JSON array of event/user property keys to include in Slack alerts'),
-    }),
+    options: incur_1.z.object(alertBodyOptionsSchema),
     examples: [
         {
             args: { alertId: 'alert_abc123' },

package/dist/commands/analytics.d.ts

@@ -22,4 +22,4 @@ export interface AnalyticsOptions {
  * Exported for unit testing.
  */
 export declare function buildAnalyticsParams(options: AnalyticsOptions): Record<string, string | number | boolean>;
-export declare function runAnalytics(pipe: string, options: AnalyticsOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare function runAnalytics(pipe: string, options: AnalyticsOptions): Promise<unknown>;

package/dist/commands/analytics.js

@@ -5,6 +5,8 @@ exports.buildAnalyticsParams = buildAnalyticsParams;
 exports.runAnalytics = runAnalytics;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const filters_1 = require("../lib/filters");
+const json_1 = require("../lib/json");
 exports.analytics = incur_1.Cli.create('analytics', {
     description: 'Pre-built analytics query commands — KPIs, funnels, retention, revenue, and top-N breakdowns',
 });
@@ -43,6 +45,52 @@ 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']);
+function validateAnalyticsFilter(filter, path, allowNested) {
+    if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
+        throw new Error(`${path} must be a {field, op, value} object`);
+    }
+    const record = filter;
+    if (!allowNested && record.filters !== undefined) {
+        throw new Error(`${path}.filters must be a one-level array of leaf filters`);
+    }
+    const allowedKeys = 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' : ''}`);
+    }
+    if (typeof record.field !== 'string' || record.field.length === 0) {
+        throw new Error(`${path} requires a non-empty string "field"`);
+    }
+    if (!(0, filters_1.isCanonicalFilterOperator)(record.op)) {
+        throw new Error(`${path} requires a canonical "op"`);
+    }
+    if ((0, filters_1.isEmptyMembershipArray)(record.value)) {
+        throw new Error(`${path}: membership arrays cannot be empty`);
+    }
+    if (!(0, filters_1.isValuelessFilterOperator)(record.op) &&
+        (record.value === undefined ||
+            record.value === null ||
+            !(0, filters_1.isCanonicalFilterValue)(record.value))) {
+        throw new Error(`${path}: "value" is required for every operator except notEmpty/isEmpty`);
+    }
+    if (record.value !== undefined &&
+        record.value !== null &&
+        !(0, filters_1.isCanonicalFilterValue)(record.value)) {
+        throw new Error(`${path}: "value" must be a string, number, boolean, or string/number array`);
+    }
+    if ((0, filters_1.hasTinybirdMembershipDelimiter)(record.value)) {
+        throw new Error(`${path}: array string members cannot contain "|" because it is the Tinybird membership separator`);
+    }
+    if (record.filters !== undefined) {
+        if (!allowNested || !Array.isArray(record.filters)) {
+            throw new Error(`${path}.filters must be a one-level array of leaf filters`);
+        }
+        record.filters.forEach((nested, index) => validateAnalyticsFilter(nested, `${path}.filters[${index}]`, false));
+    }
+}
 /**
  * Build the query-string params for an analytics pipe request.
  *
@@ -62,16 +110,7 @@ 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');
-        }
+        const parsed = (0, json_1.parseJsonObject)(options.params, '--params');
         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`);
@@ -101,6 +140,7 @@ function buildAnalyticsParams(options) {
         if (!Array.isArray(parsed)) {
             throw new Error('--filters must be a valid JSON array of {field,op,value} objects');
         }
+        parsed.forEach((filter, index) => validateAnalyticsFilter(filter, `--filters[${index}]`, true));
         out.filters = JSON.stringify(parsed);
     }
     return out;
@@ -123,7 +163,7 @@ const sharedOptions = incur_1.z.object({
         .string()
         .optional()
         .describe('JSON array of filter conditions: [{"field","op","value"}]. ' +
-        'Use op "in"/"nin" with a pipe-delimited value (e.g. "chrome|firefox").'),
+        'Use op "in"/"nin" with an array value (e.g. ["chrome","firefox"]); pipe-delimited strings are also accepted. Array string members cannot contain "|".'),
     params: incur_1.z
         .string()
         .optional()

package/dist/commands/boards.d.ts

@@ -1,11 +1,9 @@
 import { Cli } from 'incur';
+import { type PaginationOptions } from '../lib/pagination';
+export type { PaginationOptions };
 export declare const boards: Cli.Cli<{}, undefined, undefined>;
-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 declare function listBoardsRun(options?: PaginationOptions): Promise<unknown>;
+export declare function getBoardRun(boardId: string): Promise<unknown>;
 export interface CreateBoardOptions {
     title?: string;
     name?: string;
@@ -13,12 +11,12 @@ export interface CreateBoardOptions {
     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 declare function createBoardRun(options: CreateBoardOptions): Promise<unknown>;
 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, {}>>;
+export declare function updateBoardRun(boardId: string, options: UpdateBoardOptions): Promise<unknown>;
+export declare function deleteBoardRun(boardId: string): Promise<unknown>;

package/dist/commands/boards.js

@@ -9,29 +9,19 @@ exports.updateBoardRun = updateBoardRun;
 exports.deleteBoardRun = deleteBoardRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const pagination_1 = require("../lib/pagination");
 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(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/boards/', { params: buildPaginationParams(options) });
+    return client.get('/v0/boards/', { params: (0, pagination_1.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)'),
-    }),
+    options: incur_1.z.object(pagination_1.paginationOptionsSchema),
     examples: [{ description: 'List all dashboard boards' }],
     hint: 'Requires boards:read scope on your API key.',
     run({ options }) {
@@ -62,7 +52,7 @@ function buildBoardBody(options) {
     const body = {};
     if (title !== undefined) {
         if (!title)
-            throw new Error('--title must not be empty');
+            throw new Error('--title (or its deprecated alias --name) must not be empty');
         body.title = title;
     }
     if (options.description !== undefined) {