@formo/cli 0.2.0 → 1.0.2

package/README.md

@@ -26,6 +26,13 @@ export FORMO_API_KEY=formo_abc123
 
 Get your API key from `Settings → API Keys` in the [Formo dashboard](https://app.formo.so).
 
+For local development or proxying, override API hosts with:
+
+```bash
+export FORMO_API_BASE_URL=http://localhost:3001
+export FORMO_EVENTS_BASE_URL=http://localhost:3002
+```
+
 ---
 
 ## Auth commands
@@ -82,18 +89,19 @@ Search wallet profiles with filters, sorting, and pagination. Returns a `Paginat
 | `--address` | Filter by wallet address |
 | `--page` | Page number (1-indexed, default `1`) |
 | `--size` | Page size (default `100`, max `1000`) |
-| `--orderBy` | `last_onchain`, `first_onchain`, `net_worth_usd`, `updated_at`, `tx_count`, `first_seen`, `last_seen`, `num_sessions`, `revenue`, `volume`, `points` |
-| `--orderDir` | `asc` or `desc` |
+| `--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` |
 
 ```bash
 formo profiles search --size 10
-formo profiles search --orderBy net_worth_usd --orderDir desc --size 5
+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":"net_worth_usd","op":"gt","value":10000}]' --size 20
-formo profiles search --conditions '[{"field":"net_worth_usd","op":"gt","value":10000},{"field":"tx_count","op":"gt","value":50}]' --logic or --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
 ```
 
 ### `profiles update <address>`
@@ -113,21 +121,34 @@ formo profiles update vitalik.eth --properties '{"email":"alice@example.com"}'
 
 > Requires `profiles:write` scope.
 
+### `profiles properties batch`
+
+Batch update first-party properties for up to 100 wallets.
+
+```bash
+formo profiles properties batch \
+  --rows '[{"address":"0xd8dA...","display_name":"alice.eth","email":"alice@example.com"}]'
+```
+
 ### `profiles labels create <address>`
 
-Upsert one or more labels on a wallet profile. Provide either a single label via `--tagId` or a batch via `--labels`.
+Upsert one or more labels on a wallet profile. Provide either a single label via `--tag-id` or a batch via `--labels`.
 
 | Option | Description |
 |---|---|
-| `--tagId` | Label identifier (e.g. `vip`, `airdrop_eligible`) |
+| `--tag-id` | Label identifier (e.g. `vip`, `airdrop_eligible`) |
 | `--value` | Optional label value (e.g. tier name, country code) |
-| `--chainId` | Optional chain identifier the label applies to |
+| `--chain-id` | Optional chain identifier the label applies to |
+| `--timestamp` | Optional historical ISO-8601 timestamp |
+| `--is-deleted` | Backfill a historical label removal tombstone |
 | `--labels` | JSON array of `UserLabelInput` objects for batch upsert |
 
 ```bash
-formo profiles labels create 0xd8dA... --tagId vip
-formo profiles labels create 0xd8dA... --tagId tier --value gold --chainId 1
+formo profiles labels create 0xd8dA... --tag-id vip
+formo profiles labels create 0xd8dA... --tag-id tier --value gold --chain-id 1
 formo profiles labels create 0xd8dA... --labels '[{"tag_id":"vip"},{"tag_id":"airdrop_eligible","chain_id":"1"}]'
+formo profiles labels create 0xd8dA... --tag-id tier --timestamp 2024-03-15T00:00:00.000Z --is-deleted
+formo profiles labels batch --labels '[{"address":"0xd8dA...","tag_id":"vip","value":"tier-1"}]'
 ```
 
 ### `profiles labels delete <address>`
@@ -136,12 +157,12 @@ Delete a label from a wallet profile.
 
 | Option | Description |
 |---|---|
-| `--tagId` | Label identifier to delete (required) |
-| `--chainId` | Optional chain identifier to scope the deletion |
+| `--tag-id` | Label identifier to delete (required) |
+| `--chain-id` | Optional chain identifier to scope the deletion |
 
 ```bash
-formo profiles labels delete 0xd8dA... --tagId vip
-formo profiles labels delete 0xd8dA... --tagId tier --chainId 1
+formo profiles labels delete 0xd8dA... --tag-id vip
+formo profiles labels delete 0xd8dA... --tag-id tier --chain-id 1
 ```
 
 > Requires `profiles:write` scope.
@@ -163,14 +184,14 @@ Get a single alert by ID.
 | Option | Description |
 |---|---|
 | `--name` | Alert name |
-| `--triggerType` | Trigger type (e.g. `event`, `threshold`) |
-| `--triggerFilters` | JSON array of trigger filter objects |
+| `--trigger-type` | Trigger type: `event` or `user` |
+| `--trigger-filters` | JSON array of trigger filter objects |
 | `--recipient` | JSON array of recipient objects |
 | `--secret` | Webhook secret |
 
 ```bash
-formo alerts create --name "High value tx" --triggerType event \
-  --triggerFilters '[{"name":"event","operator":"equals","value":"transaction"}]' \
+formo alerts create --name "High value tx" --trigger-type event \
+  --trigger-filters '[{"name":"event","operator":"equals","value":"transaction"}]' \
   --recipient '[{"type":"email","value":["alerts@myapp.com"]}]'
 ```
 
@@ -180,11 +201,18 @@ Same options as `create`. Replaces the alert configuration.
 ### `alerts delete <alertId>`
 Delete an alert.
 
-### `alerts toggle <alertId> --status <active|paused>`
-Toggle an alert between `active` and `paused`.
+### `alerts toggle <alertId> --status <active|inactive>`
+Toggle an alert between `active` and `inactive`.
 
 ```bash
-formo alerts toggle alert_abc123 --status paused
+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}'
 ```
 
 ---
@@ -203,19 +231,21 @@ Get a single board by ID.
 
 | Option | Description |
 |---|---|
-| `--name` | Board name |
+| `--title` | Board title |
 | `--description` | Optional board description |
+| `--is-public` | Make the board publicly viewable |
 
 ```bash
-formo boards create --name "Revenue Metrics" --description "Weekly revenue tracking"
+formo boards create --title "Revenue Metrics" --description "Weekly revenue tracking"
 ```
 
 ### `boards update <boardId>`
 
 | Option | Description |
 |---|---|
-| `--name` | New board name |
+| `--title` | New board title |
 | `--description` | New board description |
+| `--is-public` | Update public visibility |
 
 ### `boards delete <boardId>`
 Delete a board.
@@ -226,19 +256,37 @@ Delete a board.
 
 Chart commands. Charts live inside a board. Requires `charts:read` / `charts:write`.
 
-### `charts list --boardId <boardId>`
+### `charts list --board-id <boardId>`
 List all charts in a board.
 
-### `charts get <chartId> --boardId <boardId>`
+### `charts get <chartId> --board-id <boardId>`
 Get a single chart by ID.
 
-### `charts create --boardId <boardId> --body '<json>'`
-Create a chart from a JSON config string.
+### `charts meta --board-id <boardId>`
+List lightweight chart metadata without executing chart queries.
+
+### `charts create --board-id <boardId> [options]`
+Create a chart from typed flags or a raw JSON body.
+
+```bash
+formo charts create --board-id brd_123 --title "Daily Active Users" \
+  --chart-type line \
+  --query "SELECT toDate(timestamp) AS date, countDistinct(address) AS users FROM events GROUP BY date ORDER BY date" \
+  --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"}'
+```
 
-### `charts update <chartId> --boardId <boardId> --body '<json>'`
+### `charts update <chartId> --board-id <boardId> --body '<json>'`
 Update a chart.
 
-### `charts delete <chartId> --boardId <boardId>`
+### `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.
+
+### `charts move|duplicate|reorder`
+Move a chart to another board, duplicate a chart, or reorder charts in a board.
+
+### `charts delete <chartId> --board-id <boardId>`
 Delete a chart.
 
 ---
@@ -250,6 +298,12 @@ Smart contract commands. Requires `contracts:read` / `contracts:write`.
 ### `contracts list`
 List all tracked contracts. Returns `{ data: Contract[], deploy: { last_deployed_at, diff }, total, page, size, has_more }`.
 
+### `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`
 
 | Option | Description |
@@ -257,13 +311,15 @@ List all tracked contracts. Returns `{ data: Contract[], deploy: { last_deployed
 | `--address` | Contract address (`0x…`) |
 | `--chain` | Chain ID (e.g. `1`, `137`) |
 | `--name` | Human-readable contract name |
-| `--abi` | Contract ABI as a JSON string |
-| `--events` | Events configuration as a JSON string |
+| `--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) |
 
 ```bash
 formo contracts create --address 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 --chain 1 \
   --name "UNI Token" --abi '[{"type":"event","name":"Transfer","inputs":[]}]' \
-  --events '{"Transfer":true}'
+  --events '[{"type":"event","name":"Transfer","inputs":[]}]'
 ```
 
 ### `contracts update <chain> <address>`
@@ -272,7 +328,12 @@ formo contracts create --address 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 --ch
 |---|---|
 | `--name` | Updated contract name |
 | `--abi` | Updated ABI |
-| `--events` | Updated events config |
+| `--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 |
+
+### `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.
@@ -291,7 +352,7 @@ List all user segments.
 | Option | Description |
 |---|---|
 | `--title` | Segment title |
-| `--filterSets` | JSON array of filter set strings defining the segment |
+| `--filter-sets` | JSON array of filter set strings defining the segment |
 
 ### `segments delete <segmentId>`
 Delete a user segment.
@@ -313,6 +374,31 @@ formo query run "SELECT address, net_worth_usd FROM wallet_profiles ORDER BY net
 
 ---
 
+## `formo analytics`
+
+Pre-built analytics pipes — the same data that powers the Formo dashboard — without writing SQL. Each pipe is a subcommand: `formo analytics <pipe>`.
+
+**Pipes:** `kpis`, `event_timeseries`, `funnel`, `flow`, `frequency`, `lifecycle`, `retention`, `revenue_overview`, `revenue_by_metric`, `revenue_timeseries`, `volume_by_metric`, `top_chains`, `top_events`, `top_locations`, `top_pages`, `top_sources`, `top_wallets`
+
+| Option | Description |
+|---|---|
+| `--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`/`notIn` with a pipe-delimited value (e.g. `"chrome\|firefox"`) |
+| `--params` | JSON object of pipe-specific params merged into the query (e.g. `{"limit":10,"group_by":"device"}`) |
+
+```bash
+formo analytics kpis
+formo analytics kpis --date-from 2026-04-01 --date-to 2026-04-30 --params '{"group_by":"device"}'
+formo analytics funnel --date-from 2026-04-01 --date-to 2026-04-30 --params '{"steps":[{"type":"event","event":"page","name":"page::0","filters":[]},{"type":"track","event":"connect","name":"connect::1","filters":[]}],"window_seconds":86400}'
+formo analytics top_wallets --date-from 2026-04-01 --date-to 2026-04-30 --params '{"limit":10}'
+formo analytics retention --filters '[{"field":"location","op":"equals","value":"US"}]'
+```
+
+> Requires `query:read` scope. Run `formo analytics <pipe> --help` for the pipe-specific params accepted via `--params`.
+
+---
+
 ## `formo import`
 
 ### `import wallets`
@@ -322,10 +408,24 @@ Bulk-import wallet addresses into the project via the events API.
 | Option | Description |
 |---|---|
 | `--addresses` | JSON array of wallet address strings |
-| `--writeKey` | Project write SDK key |
+| `--rows` | JSON array of `{address,properties?}` objects |
 
 ```bash
-formo import wallets --addresses '["0xabc...","0xdef..."]' --writeKey write_key_xyz
+formo import wallets --addresses '["0xabc...","0xdef..."]'
+formo import wallets --rows '[{"address":"0xabc...","properties":{"display_name":"Alice"}}]'
+```
+
+---
+
+## `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.
+
+```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"}'
 ```
 
 ---
@@ -336,16 +436,30 @@ formo import wallets --addresses '["0xabc...","0xdef..."]' --writeKey write_key_
 
 ```json
 [
-  { "field": "net_worth_usd", "op": "gt", "value": 10000 },
-  { "field": "tx_count", "op": "gte", "value": 5 }
+  { "field": "users.net_worth_usd", "op": "gt", "value": 10000 },
+  { "field": "chains.1.balance", "op": "gte", "value": 1000 }
 ]
 ```
 
+> **The `field` must be a typed 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.
+
 | Field | Type | Description |
 |---|---|---|
-| `field` | `string` | Profile field to filter on |
+| `field` | `string` | Typed path (see prefixes below) |
 | `op` | `string` | `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `nin` |
 | `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` |
+
+| 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` |
 
 Combine multiple conditions with `--logic and` (default) or `--logic or`.
 

package/dist/commands/alerts.d.ts

@@ -1,23 +1,36 @@
 import { Cli } from 'incur';
 export declare const alerts: Cli.Cli<{}, undefined, undefined>;
-export declare function listAlertsRun(): Promise<import("axios").AxiosResponse<any, any, {}>>;
+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: 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 {
     name: string;
-    triggerType: string;
+    triggerType: 'event' | 'user' | 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 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, {}>>;

package/dist/commands/alerts.js

@@ -8,23 +8,37 @@ 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 json_1 = require("../lib/json");
 exports.alerts = incur_1.Cli.create('alerts', {
     description: 'Project alert commands — create, list, update, and delete alerts',
 });
-// ── List alerts ──
-function listAlertsRun() {
+function buildPaginationParams(options = {}) {
+    const params = {};
+    if (options.page !== undefined)
+        params.page = options.page;
+    if (options.size !== undefined)
+        params.size = options.size;
+    return params;
+}
+function listAlertsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/alerts/');
+    return client.get('/v0/alerts/', { params: 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)'),
+    }),
     examples: [{ description: 'List all project alerts' }],
     hint: 'Requires alerts:read scope on your API key.',
-    run() {
-        return listAlertsRun();
+    run({ options }) {
+        return listAlertsRun(options);
     },
 });
 // ── Get a single alert ──
@@ -50,26 +64,20 @@ function buildAlertBody(options) {
     const body = {
         name: options.name,
         trigger_type: options.triggerType,
+        trigger_filters: [],
     };
     if (options.triggerFilters) {
-        try {
-            body.trigger_filters = JSON.parse(options.triggerFilters);
-        }
-        catch {
-            throw new Error('--triggerFilters must be a valid JSON array');
-        }
+        body.trigger_filters = (0, json_1.parseJsonArray)(options.triggerFilters, '--trigger-filters');
     }
     if (options.recipient) {
-        try {
-            body.recipient = JSON.parse(options.recipient);
-        }
-        catch {
-            throw new Error('--recipient must be a valid JSON array');
-        }
+        body.recipient = (0, json_1.parseJsonArray)(options.recipient, '--recipient');
     }
     if (options.secret !== undefined) {
         body.secret = options.secret;
     }
+    if (options.slackPropertyKeys !== undefined) {
+        body.slack_property_keys = (0, json_1.parseJsonArray)(options.slackPropertyKeys, '--slack-property-keys');
+    }
     return body;
 }
 function createAlertRun(options) {
@@ -81,7 +89,7 @@ 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.string().describe('Trigger type (e.g. "event", "threshold")'),
+        triggerType: incur_1.z.enum(['event', 'user']).describe('Trigger type'),
         triggerFilters: incur_1.z
             .string()
             .optional()
@@ -91,6 +99,10 @@ exports.alerts.command('create', {
             .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'),
     }),
     examples: [
         {
@@ -115,7 +127,7 @@ exports.alerts.command('update', {
     }),
     options: incur_1.z.object({
         name: incur_1.z.string().describe('Alert name'),
-        triggerType: incur_1.z.string().describe('Trigger type'),
+        triggerType: incur_1.z.enum(['event', 'user']).describe('Trigger type'),
         triggerFilters: incur_1.z
             .string()
             .optional()
@@ -125,6 +137,10 @@ exports.alerts.command('update', {
             .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'),
     }),
     examples: [
         {
@@ -161,21 +177,24 @@ exports.alerts.command('delete', {
 function toggleAlertRun(alertId, status) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.patch(`/v0/alerts/${encodeURIComponent(alertId)}`, { status });
+    const normalizedStatus = status === 'paused' ? 'inactive' : status;
+    return client.patch(`/v0/alerts/${encodeURIComponent(alertId)}`, {
+        status: normalizedStatus,
+    });
 }
 exports.alerts.command('toggle', {
-    description: 'Toggle an alert status (active/paused)',
+    description: 'Toggle an alert status (active/inactive)',
     args: incur_1.z.object({
         alertId: incur_1.z.string().describe('Alert ID to toggle'),
     }),
     options: incur_1.z.object({
-        status: incur_1.z.enum(['active', 'paused']).describe('New status'),
+        status: incur_1.z.enum(['active', 'inactive', 'paused']).describe('New status. "paused" is accepted as a deprecated alias for "inactive".'),
     }),
     examples: [
         {
             args: { alertId: 'alert_abc123' },
-            options: { status: 'paused' },
-            description: 'Pause an alert',
+            options: { status: 'inactive' },
+            description: 'Deactivate an alert',
         },
     ],
     hint: 'Requires alerts:write scope on your API key.',
@@ -183,3 +202,54 @@ 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.d.ts

@@ -0,0 +1,25 @@
+import { Cli } from 'incur';
+export declare const analytics: Cli.Cli<{}, undefined, undefined>;
+export interface AnalyticsOptions {
+    dateFrom?: string;
+    dateTo?: string;
+    filters?: string;
+    params?: string;
+}
+/**
+ * Build the query-string params for an analytics pipe request.
+ *
+ * - `dateFrom`/`dateTo` map to the API's snake_case `date_from`/`date_to`.
+ *   All pipes, including `funnel` and `flow`, use snake_case.
+ * - `filters` is a JSON array of `{ field, op, value }` objects, re-serialized
+ *   as a JSON string (the pipe expects a JSON-encoded array in the query).
+ * - `params` is a JSON object of any pipe-specific params (e.g. funnel
+ *   `steps`, kpis `group_by`, `limit`). Object/array values are JSON-encoded
+ *   (pipes like funnel expect `steps` as a JSON-encoded string); primitives
+ *   pass through unchanged. Reserved keys (the date/filters flags) are
+ *   rejected, and the validated flags below always take precedence.
+ *
+ * Exported for unit testing.
+ */
+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, {}>>;