@formo/cli 1.1.1 → 1.2.0

package/README.md

@@ -110,16 +110,16 @@ Search wallet profiles with filters, sorting, and pagination. Returns a `Paginat
 | `--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)
@@ -224,7 +224,7 @@ Get a single alert by ID.
 
 ```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"]}]'
 ```
 
@@ -308,10 +308,14 @@ 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> [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`). Typed flags override matching `--body` keys.
+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"
@@ -389,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.
@@ -421,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
@@ -434,6 +438,10 @@ 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`
@@ -478,36 +486,60 @@ formo events ingest --events '[{"type":"track","event":"First"},{"type":"track",
 
 ## 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.js

@@ -12,6 +12,7 @@ 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', {
@@ -76,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');

package/dist/commands/analytics.js

@@ -5,6 +5,7 @@ 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',
@@ -44,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.
  *
@@ -93,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;
@@ -115,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/charts.js

@@ -102,11 +102,11 @@ const chartBodyOptions = incur_1.z.object({
     steps: incur_1.z
         .string()
         .optional()
-        .describe('JSON array of funnel/user-path step objects'),
+        .describe('JSON array of funnel step objects'),
     settings: incur_1.z
         .string()
         .optional()
-        .describe('JSON object of type-specific chart settings'),
+        .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 = {}) {

package/dist/commands/profiles.d.ts

@@ -21,16 +21,16 @@ export interface SearchProfilesOptions extends LifecycleThresholdOptions {
     orderBy?: string;
     orderDir?: string;
     expand?: string;
-    conditions?: string;
+    filters?: string;
     logic?: 'and' | 'or';
 }
 /**
- * Parse and validate the --conditions JSON. Ensures it is an array of
- * `{ field, op, value }` objects whose `field` is a typed path (e.g.
- * `users.net_worth_usd`) — a bare name like `net_worth_usd` is silently
- * dropped by the API, so it is rejected here. Exported for unit testing.
+ * Parse and validate the --filters JSON. Ensures it is an array of
+ * `{ field, op, value }` objects carrying a canonical `field` — either
+ * `users.{attribute}` or one of the four stable resource paths, with resource
+ * identity in named qualifier properties. Exported for unit testing.
  */
-export declare function parseSearchConditions(raw: string): unknown[];
+export declare function parseSearchFilters(raw: string): unknown[];
 export declare function searchProfilesRun(options: SearchProfilesOptions): Promise<unknown>;
 export interface UpdateProfileOptions {
     properties: string;

package/dist/commands/profiles.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.profilesLabels = exports.profilesProperties = exports.profiles = void 0;
 exports.getProfileRun = getProfileRun;
-exports.parseSearchConditions = parseSearchConditions;
+exports.parseSearchFilters = parseSearchFilters;
 exports.searchProfilesRun = searchProfilesRun;
 exports.buildUpdateProfileBody = buildUpdateProfileBody;
 exports.updateProfileRun = updateProfileRun;
@@ -16,6 +16,7 @@ exports.buildDeleteLabelBody = buildDeleteLabelBody;
 exports.deleteProfileLabelRun = deleteProfileLabelRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const filters_1 = require("../lib/filters");
 const json_1 = require("../lib/json");
 exports.profiles = incur_1.Cli.create('profiles', {
     description: 'Wallet profile commands',
@@ -111,13 +112,23 @@ exports.profiles.command('get', {
         return getProfileRun(args.address, options);
     },
 });
-// Accepted first segments for a FilterCondition `field`, mirroring the API's
-// parseField(). A field whose prefix is not one of these is silently ignored
-// server-side (no error, no filtering — the search returns everything), so we
-// reject it client-side with an actionable message instead.
-const CONDITION_FIELD_PREFIXES = new Set([
-    'user',
-    'users',
+// Prefixes that may lead a user-surface `field` (e.g. `users.net_worth_usd`).
+// A bare name like `net_worth_usd` is silently ignored server-side (no error,
+// no filtering — the search returns everything), so we reject it client-side.
+const USER_FIELD_PREFIXES = new Set(['user', 'users']);
+// The four canonical resource filter fields. Resource identity lives in named
+// qualifier properties — never in the field path. The retired
+// identifier-in-path spellings (`chains.1.balance`, `apps.uniswap-v3.balance`,
+// `tokens.0x….balance`, `labels.vip`) are rejected by the API with a 400.
+const RESOURCE_FILTER_FIELDS = new Set([
+    'chains.balance',
+    'apps.balance',
+    'tokens.balance',
+    'labels.value',
+]);
+// Prefixes owned by the resource fields above. A field that leads with one of
+// these but is not an exact canonical path is a retired dynamic path.
+const RESOURCE_FIELD_PREFIXES = new Set([
     'chain',
     'chains',
     'app',
@@ -127,35 +138,138 @@ const CONDITION_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,
+]);
 /**
- * Parse and validate the --conditions JSON. Ensures it is an array of
- * `{ field, op, value }` objects whose `field` is a typed path (e.g.
- * `users.net_worth_usd`) — a bare name like `net_worth_usd` is silently
- * dropped by the API, so it is rejected here. Exported for unit testing.
+ * 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 parseSearchConditions(raw) {
+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
+ * `users.{attribute}` or one of the four stable resource paths, with resource
+ * identity in named qualifier properties. Exported for unit testing.
+ */
+function parseSearchFilters(raw) {
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error('--conditions must be a valid JSON array of FilterCondition objects');
+        throw new Error('--filters must be a valid JSON array of FilterCondition objects');
     }
     if (!Array.isArray(parsed)) {
-        throw new Error('--conditions must be a valid JSON array of FilterCondition objects');
+        throw new Error('--filters must be a valid JSON array of FilterCondition objects');
     }
-    for (const cond of parsed) {
-        if (!cond || typeof cond !== 'object' || Array.isArray(cond)) {
-            throw new Error('--conditions: each entry must be an object with field, op, value');
+    for (const filter of parsed) {
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
+            throw new Error('--filters: each entry must be an object with field, op, value');
         }
-        const field = cond.field;
+        const record = filter;
+        const field = record.field;
         if (typeof field !== 'string' || field.length === 0) {
-            throw new Error('--conditions: each entry must have a non-empty string "field"');
+            throw new Error('--filters: each entry must have a non-empty string "field"');
+        }
+        for (const key of Object.keys(record)) {
+            if (!FILTER_ENTRY_KEYS.has(key)) {
+                // `appId` was the pre-P-2387 spelling; the API now rejects unknown keys.
+                const hint = key === 'appId' ? ' — use the snake_case "app_id" qualifier' : '';
+                throw new Error(`--filters: unknown property "${key}"${hint}`);
+            }
+        }
+        const prefix = field.split('.')[0];
+        if (!RESOURCE_FILTER_FIELDS.has(field)) {
+            if (RESOURCE_FIELD_PREFIXES.has(prefix)) {
+                throw new Error(`--filters: field "${field}" is a retired identifier-in-path spelling. ` +
+                    'Use a stable path — chains.balance, apps.balance, tokens.balance, or labels.value — ' +
+                    'and move the identifier into a qualifier (chain_id, app_id, token_address, tag_id). ' +
+                    'The API rejects the old form with a 400.');
+            }
+            if (!field.includes('.') || !USER_FIELD_PREFIXES.has(prefix)) {
+                throw new Error(`--filters: field "${field}" must be a canonical path — either ` +
+                    'users.{attribute}, or one of chains.balance, apps.balance, tokens.balance, labels.value ' +
+                    '(a bare name is silently ignored by the API and returns the entire unfiltered dataset)');
+            }
+        }
+        validateQualifiers(record, field);
+        // The balance fields compare numerically; a stringified number is a 400.
+        if (field !== 'labels.value' &&
+            RESOURCE_FILTER_FIELDS.has(field) &&
+            typeof record.value !== 'number') {
+            throw new Error(`--filters: "value" must be a number for "${field}"`);
+        }
+        if (field === 'labels.value' && record.value === '') {
+            throw new Error(`--filters: "value" must be non-empty for "labels.value"`);
+        }
+        if (!(0, filters_1.isCanonicalFilterOperator)(record.op)) {
+            throw new Error('--filters: each entry must use a canonical "op" (eq, neq, gt, lt, gte, lte, in, nin, startsWith, endsWith, contains, notEmpty, or isEmpty)');
         }
-        if (!field.includes('.') || !CONDITION_FIELD_PREFIXES.has(field.split('.')[0])) {
-            throw new Error(`--conditions: field "${field}" must be a typed path — prefix it with ` +
-                'users., chains., apps., tokens., or labels. ' +
-                '(a bare name is silently ignored by the API and returns the entire unfiltered dataset)');
+        if ((0, filters_1.isEmptyMembershipArray)(record.value)) {
+            throw new Error('--filters: membership arrays cannot be empty');
+        }
+        if (!(0, filters_1.isValuelessFilterOperator)(record.op) &&
+            (record.value === undefined || record.value === null)) {
+            throw new Error('--filters: "value" is required for every operator except notEmpty/isEmpty');
         }
     }
     return parsed;
@@ -180,14 +294,14 @@ function searchProfilesRun(options) {
         params.expand = options.expand;
     addLifecycleThresholdParams(params, options);
     let body;
-    if (options.conditions) {
+    if (options.filters) {
         body = {
-            conditions: parseSearchConditions(options.conditions),
+            filters: parseSearchFilters(options.filters),
             logic: options.logic ?? 'and',
         };
     }
     // INTENTIONAL: the Formo search API is `GET /v0/profiles` with the
-    // `{ conditions, logic }` filter object in the *request body* (see
+    // `{ filters, logic }` filter object in the *request body* (see
     // docs.formo.so/api/profiles/search — it has a "Request Body (Filters)"
     // section under a GET endpoint). This GET-with-body shape is the
     // documented, server-supported contract. Do NOT "fix" it to POST — that
@@ -229,7 +343,7 @@ exports.profiles.command('search', {
             .describe('Field to sort by'),
         orderDir: incur_1.z.enum(['asc', 'desc']).optional().describe('Sort direction'),
         expand: incur_1.z.string().optional().describe('Comma-separated fields to expand'),
-        conditions: incur_1.z
+        filters: incur_1.z
             .string()
             .optional()
             .describe('JSON array of FilterCondition objects: [{"field","op","value"}]. ' +
@@ -237,16 +351,24 @@ exports.profiles.command('search', {
             'Profile: users.net_worth_usd, users.volume, users.revenue, users.points. ' +
             'Engagement: users.device, users.browser, users.os, users.location, users.lifecycle. ' +
             'Socials: users.ens, users.farcaster, users.lens, etc. ' +
-            'Chains: chains.balance or chains.{chain_id}.balance. ' +
-            'Apps: apps.{app_id}.balance. Tokens: tokens.{address}.balance ' +
-            '(optional "scope":"any"|"protocol" + "appId"). Labels: labels.{tag_id}. ' +
-            'op: eq, neq, gt, gte, lt, lte, in, nin, contains, notEmpty, isEmpty ' +
-            '(contains = substring, social fields only; notEmpty/isEmpty = value-less existence checks on string fields). ' +
-            'Long-form spellings (equals, notEquals, greater, greaterOrEqual, less, lessOrEqual, notIn, includes) are retired; the API rejects them with a 400 naming the token.'),
+            'Resource filters use a stable field plus named qualifiers: ' +
+            'chains.balance (+ optional "chain_id"); ' +
+            'apps.balance (+ "app_id", optional "chain_id"); ' +
+            'tokens.balance (+ "token_address", "scope":"any"|"protocol", "app_id" when scope is "protocol", optional "chain_id"); ' +
+            'labels.value (+ "tag_id", optional "chain_id"). ' +
+            'op: eq, neq, gt, gte, lt, lte, in, nin, contains, startsWith, endsWith, notEmpty, isEmpty. ' +
+            'Operator support is per field: the .balance fields take comparison operators only; ' +
+            'contains works on routable string attributes (users.device, users.os, users.referrer, users.utm_*, users.click_id — case-sensitive), ' +
+            'on social fields and on labels.value (case-insensitive); ' +
+            'startsWith/endsWith are routable string attributes only; ' +
+            'notEmpty/isEmpty are value-less existence checks on string fields; ' +
+            'users.lifecycle takes only eq and in. ' +
+            'Retired and rejected with a 400: identifier-in-path fields (chains.1.balance, apps.uniswap-v3.balance, tokens.0x….balance, labels.vip), ' +
+            'the "appId" spelling, and long-form operators (equals, notEquals, greater, greaterOrEqual, less, lessOrEqual, notIn, includes).'),
         logic: incur_1.z
             .enum(['and', 'or'])
             .optional()
-            .describe('Logic operator for combining conditions: "and" (default) or "or"'),
+            .describe('Logic operator for combining filters: "and" (default) or "or"'),
         ...lifecycleThresholdOptions,
     }),
     examples: [
@@ -261,14 +383,14 @@ exports.profiles.command('search', {
         },
         {
             options: {
-                conditions: '[{"field":"users.net_worth_usd","op":"gt","value":10000}]',
+                filters: '[{"field":"users.net_worth_usd","op":"gt","value":10000}]',
                 size: 20,
             },
             description: 'Search profiles with net worth > $10k',
         },
         {
             options: {
-                conditions: '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]',
+                filters: '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]',
                 logic: 'or',
                 size: 20,
             },
@@ -276,13 +398,20 @@ exports.profiles.command('search', {
         },
         {
             options: {
-                conditions: '[{"field":"chains.1.balance","op":"gt","value":1000}]',
+                filters: '[{"field":"chains.balance","op":"gt","value":1000,"chain_id":"1"}]',
                 size: 20,
             },
             description: 'Search profiles with > $1k balance on Ethereum (chain 1)',
         },
+        {
+            options: {
+                filters: '[{"field":"labels.value","op":"eq","value":"tier-1","tag_id":"vip"}]',
+                size: 20,
+            },
+            description: 'Search profiles carrying the vip label with value tier-1',
+        },
     ],
-    hint: 'Requires profiles:read scope on your API key. Filter "field" must be a typed path (e.g. users.net_worth_usd) — bare names are ignored by the API.',
+    hint: 'Requires profiles:read scope on your API key. Filter "field" must be a canonical path (users.{attribute}, chains.balance, apps.balance, tokens.balance, labels.value) with resource identity in the chain_id/app_id/token_address/tag_id qualifiers — bare names are ignored by the API and identifier-in-path fields are rejected with a 400.',
     run({ options }) {
         return searchProfilesRun(options);
     },

package/dist/commands/segments.d.ts

@@ -5,11 +5,11 @@ export declare const segments: Cli.Cli<{}, undefined, undefined>;
 export declare function listSegmentsRun(options?: PaginationOptions): Promise<unknown>;
 export interface CreateSegmentOptions {
     title: string;
-    filterSets: string;
+    filters: string;
 }
 export declare function buildCreateSegmentBody(options: CreateSegmentOptions): {
     title: string;
-    filterSets: unknown[];
+    filters: unknown[];
 };
 export declare function createSegmentRun(options: CreateSegmentOptions): Promise<unknown>;
 export declare function deleteSegmentRun(segmentId: string): Promise<unknown>;

package/dist/commands/segments.js

@@ -7,6 +7,7 @@ exports.createSegmentRun = createSegmentRun;
 exports.deleteSegmentRun = deleteSegmentRun;
 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.segments = incur_1.Cli.create('segments', {
@@ -27,14 +28,47 @@ exports.segments.command('list', {
         return listSegmentsRun(options);
     },
 });
+const SEGMENT_FILTER_KEYS = new Set(['field', 'op', 'value']);
 function buildCreateSegmentBody(options) {
-    const parsedFilterSets = (0, json_1.parseJsonArray)(options.filterSets, '--filter-sets');
-    if (parsedFilterSets.some((item) => typeof item !== 'string')) {
-        throw new Error('--filter-sets must be a JSON array of strings');
+    const filters = (0, json_1.parseJsonArray)(options.filters, '--filters');
+    if (filters.length === 0) {
+        throw new Error('--filters must contain at least one filter');
+    }
+    for (const filter of filters) {
+        if (!filter || typeof filter !== 'object' || Array.isArray(filter)) {
+            throw new Error('--filters must be a JSON array of {field, op, value} objects');
+        }
+        const record = filter;
+        if (Object.keys(record).some((key) => !SEGMENT_FILTER_KEYS.has(key))) {
+            throw new Error('--filters entries may only contain field, op, and value');
+        }
+        if (typeof record.field !== 'string' || record.field.length === 0) {
+            throw new Error('--filters: each entry requires a non-empty string "field"');
+        }
+        if (!(0, filters_1.isCanonicalFilterOperator)(record.op)) {
+            throw new Error('--filters: each entry requires a canonical "op"');
+        }
+        if ((0, filters_1.isEmptyMembershipArray)(record.value)) {
+            throw new Error('--filters: 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('--filters: "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('--filters: "value" must be a string, number, boolean, or string/number array');
+        }
+        if ((0, filters_1.hasTinybirdMembershipDelimiter)(record.value)) {
+            throw new Error('--filters: array string members cannot contain "|" because it is the Tinybird membership separator');
+        }
     }
     return {
         title: options.title,
-        filterSets: parsedFilterSets,
+        filters,
     };
 }
 function createSegmentRun(options) {
@@ -46,15 +80,15 @@ exports.segments.command('create', {
     description: 'Create a new user segment',
     options: incur_1.z.object({
         title: incur_1.z.string().describe('Segment title'),
-        filterSets: incur_1.z
+        filters: incur_1.z
             .string()
-            .describe('JSON array of filter set strings defining the segment'),
+            .describe('JSON array of canonical filter objects: [{"field","op","value"}]. Array string members cannot contain "|".'),
     }),
     examples: [
         {
             options: {
                 title: 'Whales',
-                filterSets: '["net_worth_usd > 100000"]',
+                filters: '[{"field":"net_worth_usd","op":"gt","value":"100000"}]',
             },
             description: 'Create a high-value segment',
         },

package/dist/lib/filters.d.ts

@@ -0,0 +1,6 @@
+export declare const CANONICAL_FILTER_OPERATORS: readonly ["eq", "neq", "gt", "lt", "gte", "lte", "in", "nin", "startsWith", "endsWith", "contains", "notEmpty", "isEmpty"];
+export declare function isCanonicalFilterOperator(op: unknown): op is string;
+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;

package/dist/lib/filters.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANONICAL_FILTER_OPERATORS = void 0;
+exports.isCanonicalFilterOperator = isCanonicalFilterOperator;
+exports.isValuelessFilterOperator = isValuelessFilterOperator;
+exports.isCanonicalFilterValue = isCanonicalFilterValue;
+exports.isEmptyMembershipArray = isEmptyMembershipArray;
+exports.hasTinybirdMembershipDelimiter = hasTinybirdMembershipDelimiter;
+exports.CANONICAL_FILTER_OPERATORS = [
+    'eq',
+    'neq',
+    'gt',
+    'lt',
+    'gte',
+    'lte',
+    'in',
+    'nin',
+    'startsWith',
+    'endsWith',
+    'contains',
+    'notEmpty',
+    'isEmpty',
+];
+const CANONICAL_FILTER_OPERATOR_SET = new Set(exports.CANONICAL_FILTER_OPERATORS);
+function isCanonicalFilterOperator(op) {
+    return typeof op === 'string' && CANONICAL_FILTER_OPERATOR_SET.has(op);
+}
+function isValuelessFilterOperator(op) {
+    return op === 'notEmpty' || op === 'isEmpty';
+}
+function isCanonicalFilterValue(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        (Array.isArray(value) &&
+            value.length > 0 &&
+            value.every((item) => typeof item === 'string' || typeof item === 'number')));
+}
+function isEmptyMembershipArray(value) {
+    return Array.isArray(value) && value.length === 0;
+}
+function hasTinybirdMembershipDelimiter(value) {
+    return (Array.isArray(value) &&
+        value.some((item) => typeof item === 'string' && item.includes('|')));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@formo/cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "packageManager": "pnpm@11.1.2",
   "engines": {
     "node": ">=22.12"