@formo/cli 0.2.0 → 1.0.2

package/dist/commands/contracts.js

@@ -2,52 +2,117 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.contracts = void 0;
 exports.listContractsRun = listContractsRun;
+exports.getContractRun = getContractRun;
+exports.getContractRecommendationsRun = getContractRecommendationsRun;
 exports.buildCreateContractBody = buildCreateContractBody;
 exports.createContractRun = createContractRun;
 exports.buildUpdateContractBody = buildUpdateContractBody;
 exports.updateContractRun = updateContractRun;
+exports.updateContractPipelineRun = updateContractPipelineRun;
+exports.buildUpdateContractPipelineBody = buildUpdateContractPipelineBody;
 exports.deleteContractRun = deleteContractRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const json_1 = require("../lib/json");
 exports.contracts = incur_1.Cli.create('contracts', {
-    description: 'Smart contract commands — register, list, update, and remove tracked contracts',
+    description: 'Smart contract commands — register, list, recommend, update, toggle pipeline inclusion, and remove tracked contracts',
 });
+function buildPaginationParams(options = {}) {
+    const params = {};
+    if (options.page !== undefined)
+        params.page = options.page;
+    if (options.size !== undefined)
+        params.size = options.size;
+    return params;
+}
+function parseChain(chain) {
+    const value = typeof chain === 'number' ? chain : Number(chain);
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error('chain must be a positive integer');
+    }
+    return value;
+}
 // ── List contracts ──
-function listContractsRun() {
+function listContractsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/contracts/');
+    return client.get('/v0/contracts/', {
+        params: buildPaginationParams(options),
+    });
 }
 exports.contracts.command('list', {
     description: 'List all tracked contracts 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 contracts' }],
     hint: 'Requires contracts:read scope on your API key.',
+    run({ options }) {
+        return listContractsRun(options);
+    },
+});
+// ── Get a contract ──
+function getContractRun(chain, address) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get(`/v0/contracts/${encodeURIComponent(chain)}/${encodeURIComponent(address)}`);
+}
+// ── Recommended contracts ──
+function getContractRecommendationsRun() {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.get('/v0/contracts/recommendations');
+}
+exports.contracts.command('recommendations', {
+    description: 'List contracts the project already interacts with but has not added yet',
+    options: incur_1.z.object({}),
+    examples: [
+        {
+            description: 'Show recommended contracts to add for decoding/monitoring',
+        },
+    ],
+    hint: 'Requires contracts:read scope on your API key.',
     run() {
-        return listContractsRun();
+        return getContractRecommendationsRun();
+    },
+});
+exports.contracts.command('get', {
+    description: 'Get a tracked contract by chain and address',
+    args: incur_1.z.object({
+        chain: incur_1.z.string().describe('Chain ID'),
+        address: incur_1.z.string().describe('Contract address (0x...)'),
+    }),
+    examples: [
+        {
+            args: {
+                chain: '1',
+                address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+            },
+            description: 'Get a tracked USDC contract',
+        },
+    ],
+    hint: 'Requires contracts:read scope on your API key.',
+    run({ args }) {
+        return getContractRun(args.chain, args.address);
     },
 });
 function buildCreateContractBody(options) {
-    let parsedAbi;
-    try {
-        parsedAbi = JSON.parse(options.abi);
-    }
-    catch {
-        throw new Error('--abi must be a valid JSON array');
-    }
-    let parsedEvents;
-    try {
-        parsedEvents = JSON.parse(options.events);
-    }
-    catch {
-        throw new Error('--events must be valid JSON');
-    }
-    return {
+    const parsedAbi = (0, json_1.parseJsonArray)(options.abi, '--abi');
+    const parsedEvents = (0, json_1.parseJsonArray)(options.events, '--events');
+    const body = {
         address: options.address,
-        chain: options.chain,
+        chain: parseChain(options.chain),
         name: options.name,
-        abi: parsedAbi,
+        abi: JSON.stringify(parsedAbi),
         events: parsedEvents,
     };
+    if (options.startBlock !== undefined)
+        body.start_block = options.startBlock;
+    if (options.includeInPipeline !== undefined) {
+        body.include_in_pipeline = options.includeInPipeline;
+    }
+    return body;
 }
 function createContractRun(options) {
     (0, client_1.requireApiKey)();
@@ -57,20 +122,25 @@ function createContractRun(options) {
 exports.contracts.command('create', {
     description: 'Register a new smart contract to track',
     options: incur_1.z.object({
-        address: incur_1.z.string().describe('Contract address (0x…)'),
+        address: incur_1.z.string().describe('Contract address (0x...)'),
         chain: incur_1.z.coerce.number().describe('Chain ID (e.g. 1 for Ethereum, 137 for Polygon)'),
         name: incur_1.z.string().describe('Human-readable contract name'),
         abi: incur_1.z.string().describe('Contract ABI as a JSON string'),
-        events: incur_1.z.string().describe('Events configuration as a JSON string'),
+        events: incur_1.z.string().describe('JSON array of ABI event objects to monitor (max 10)'),
+        startBlock: incur_1.z.coerce.number().optional().describe('Optional start block'),
+        includeInPipeline: incur_1.z
+            .boolean()
+            .optional()
+            .describe('Whether to include this contract in the Goldsky events pipeline'),
     }),
     examples: [
         {
             options: {
-                address: '0x1234…',
+                address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
                 chain: 1,
-                name: 'My Token',
-                abi: '[{"type":"event","name":"Transfer"}]',
-                events: '{"Transfer":true}',
+                name: 'USDC',
+                abi: '[{"anonymous":false,"type":"event","name":"Transfer","inputs":[]}]',
+                events: '[{"anonymous":false,"type":"event","name":"Transfer","inputs":[]}]',
             },
             description: 'Register an ERC-20 contract on Ethereum',
         },
@@ -80,50 +150,54 @@ exports.contracts.command('create', {
         return createContractRun(options);
     },
 });
-function buildUpdateContractBody(options) {
-    let parsedAbi;
-    try {
-        parsedAbi = JSON.parse(options.abi);
-    }
-    catch {
-        throw new Error('--abi must be a valid JSON array');
-    }
-    let parsedEvents;
-    try {
-        parsedEvents = JSON.parse(options.events);
-    }
-    catch {
-        throw new Error('--events must be valid JSON');
-    }
-    return {
+function buildUpdateContractBody(chain, address, options) {
+    const parsedAbi = (0, json_1.parseJsonArray)(options.abi, '--abi');
+    const parsedEvents = (0, json_1.parseJsonArray)(options.events, '--events');
+    const body = {
+        address,
+        chain: parseChain(chain),
         name: options.name,
-        abi: parsedAbi,
+        abi: JSON.stringify(parsedAbi),
         events: parsedEvents,
     };
+    if (options.startBlock !== undefined)
+        body.start_block = options.startBlock;
+    if (options.includeInPipeline !== undefined) {
+        body.include_in_pipeline = options.includeInPipeline;
+    }
+    return body;
 }
 function updateContractRun(chain, address, options) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.put(`/v0/contracts/${encodeURIComponent(chain)}/${encodeURIComponent(address)}`, buildUpdateContractBody(options));
+    return client.put(`/v0/contracts/${encodeURIComponent(chain)}/${encodeURIComponent(address)}`, buildUpdateContractBody(chain, address, options));
 }
 exports.contracts.command('update', {
     description: 'Update a tracked contract',
     args: incur_1.z.object({
         chain: incur_1.z.string().describe('Chain ID'),
-        address: incur_1.z.string().describe('Contract address (0x…)'),
+        address: incur_1.z.string().describe('Contract address (0x...)'),
     }),
     options: incur_1.z.object({
         name: incur_1.z.string().describe('Updated contract name'),
         abi: incur_1.z.string().describe('Updated ABI as a JSON string'),
-        events: incur_1.z.string().describe('Updated events configuration as a JSON string'),
+        events: incur_1.z.string().describe('Updated JSON array of ABI event objects to monitor'),
+        startBlock: incur_1.z.coerce.number().optional().describe('Optional start block'),
+        includeInPipeline: incur_1.z
+            .boolean()
+            .optional()
+            .describe('Whether to include this contract in the Goldsky events pipeline'),
     }),
     examples: [
         {
-            args: { chain: '1', address: '0x1234…' },
+            args: {
+                chain: '1',
+                address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+            },
             options: {
-                name: 'Renamed Token',
-                abi: '[{"type":"event","name":"Transfer"}]',
-                events: '{"Transfer":true}',
+                name: 'USD Coin',
+                abi: '[{"anonymous":false,"type":"event","name":"Transfer","inputs":[]}]',
+                events: '[{"anonymous":false,"type":"event","name":"Transfer","inputs":[]}]',
             },
             description: 'Update a contract',
         },
@@ -133,6 +207,41 @@ exports.contracts.command('update', {
         return updateContractRun(args.chain, args.address, options);
     },
 });
+// ── Toggle contract pipeline inclusion ──
+function updateContractPipelineRun(chain, address, includeInPipeline) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.patch(`/v0/contracts/${encodeURIComponent(chain)}/${encodeURIComponent(address)}/pipeline`, buildUpdateContractPipelineBody(includeInPipeline));
+}
+function buildUpdateContractPipelineBody(includeInPipeline) {
+    return { include_in_pipeline: includeInPipeline };
+}
+exports.contracts.command('pipeline', {
+    description: 'Toggle whether a tracked contract is included in the project events pipeline',
+    args: incur_1.z.object({
+        chain: incur_1.z.string().describe('Chain ID'),
+        address: incur_1.z.string().describe('Contract address (0x...)'),
+    }),
+    options: incur_1.z.object({
+        includeInPipeline: incur_1.z
+            .boolean()
+            .describe('true to include the contract in the pipeline, false to exclude it'),
+    }),
+    examples: [
+        {
+            args: {
+                chain: '1',
+                address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+            },
+            options: { includeInPipeline: false },
+            description: 'Keep ABI decoding but exclude this contract from pipeline deploys',
+        },
+    ],
+    hint: 'Requires contracts:write scope on your API key.',
+    run({ args, options }) {
+        return updateContractPipelineRun(args.chain, args.address, options.includeInPipeline);
+    },
+});
 // ── Delete a contract ──
 function deleteContractRun(chain, address) {
     (0, client_1.requireApiKey)();
@@ -143,11 +252,14 @@ exports.contracts.command('delete', {
     description: 'Remove a tracked contract',
     args: incur_1.z.object({
         chain: incur_1.z.string().describe('Chain ID'),
-        address: incur_1.z.string().describe('Contract address (0x…)'),
+        address: incur_1.z.string().describe('Contract address (0x...)'),
     }),
     examples: [
         {
-            args: { chain: '1', address: '0x1234…' },
+            args: {
+                chain: '1',
+                address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+            },
             description: 'Delete a contract',
         },
     ],

package/dist/commands/events.d.ts

@@ -0,0 +1,9 @@
+import { Cli } from 'incur';
+export declare const events: Cli.Cli<{}, undefined, undefined>;
+export interface IngestEventsOptions {
+    events?: string;
+    event?: string;
+    writeKey?: string;
+}
+export declare function buildIngestEventsBody(options: IngestEventsOptions): Record<string, unknown>[];
+export declare function ingestEventsRun(options: IngestEventsOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/events.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.events = void 0;
+exports.buildIngestEventsBody = buildIngestEventsBody;
+exports.ingestEventsRun = ingestEventsRun;
+const incur_1 = require("incur");
+const client_1 = require("../lib/client");
+const json_1 = require("../lib/json");
+exports.events = incur_1.Cli.create('events', {
+    description: 'Event ingestion commands — send raw analytics events with a project SDK write key',
+});
+function getWriteKey(options) {
+    return options.writeKey ?? process.env.FORMO_WRITE_KEY;
+}
+function buildIngestEventsBody(options) {
+    if (options.events) {
+        const events = (0, json_1.parseJsonArrayOfObjects)(options.events, '--events');
+        if (events.length === 0) {
+            throw new Error('--events must contain at least one event');
+        }
+        return events;
+    }
+    if (options.event) {
+        return [(0, json_1.parseJsonObject)(options.event, '--event')];
+    }
+    throw new Error('Provide --event or --events');
+}
+function ingestEventsRun(options) {
+    const writeKey = getWriteKey(options);
+    if (!writeKey) {
+        throw new Error('No event write key configured. Pass --write-key or set FORMO_WRITE_KEY.');
+    }
+    const client = (0, client_1.createEventsClient)(writeKey);
+    return client.post('/v0/raw_events', buildIngestEventsBody(options));
+}
+exports.events.command('ingest', {
+    description: 'Send one or more raw events to the Formo events API',
+    options: incur_1.z.object({
+        event: incur_1.z
+            .string()
+            .optional()
+            .describe('Single event as a JSON object; wrapped in an array before sending'),
+        events: incur_1.z
+            .string()
+            .optional()
+            .describe('JSON array of event objects to send'),
+        writeKey: incur_1.z
+            .string()
+            .optional()
+            .describe('Project SDK write key. Defaults to FORMO_WRITE_KEY.'),
+    }),
+    examples: [
+        {
+            options: {
+                event: '{"type":"track","channel":"cli","version":"1","anonymous_id":"anon_123","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","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"}',
+            },
+            description: 'Send one custom event using FORMO_WRITE_KEY',
+        },
+    ],
+    hint: 'Uses the events.formo.so API and requires a project SDK write key, not a workspace API key.',
+    run({ options }) {
+        return ingestEventsRun(options);
+    },
+});

package/dist/commands/import.d.ts

@@ -1,11 +1,15 @@
 import { Cli } from 'incur';
 export declare const importCmd: Cli.Cli<{}, undefined, undefined>;
 export interface ImportWalletsOptions {
-    addresses: string;
-    writeKey: string;
+    addresses?: string;
+    rows?: string;
+    writeKey?: string;
 }
 export declare function buildImportBody(options: ImportWalletsOptions): {
-    addresses: any[];
-    writeKey: string;
+    addresses: unknown[];
+    rows: Record<string, unknown>[];
+} | {
+    addresses: unknown[];
+    rows?: undefined;
 };
 export declare function importWalletsRun(options: ImportWalletsOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/import.js

@@ -5,23 +5,31 @@ exports.buildImportBody = buildImportBody;
 exports.importWalletsRun = importWalletsRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const json_1 = require("../lib/json");
 exports.importCmd = incur_1.Cli.create('import', {
     description: 'Import commands — bulk import wallet addresses into your project',
 });
 function buildImportBody(options) {
-    let parsedAddresses;
-    try {
-        parsedAddresses = JSON.parse(options.addresses);
-        if (!Array.isArray(parsedAddresses)) {
-            throw new Error('not an array');
+    if (options.rows) {
+        const rows = (0, json_1.parseJsonArrayOfObjects)(options.rows, '--rows');
+        const addresses = rows.map((row) => row.address);
+        if (addresses.some((address) => typeof address !== 'string' || !address)) {
+            throw new Error('--rows entries must each include a non-empty string address');
         }
+        return {
+            addresses,
+            rows,
+        };
     }
-    catch {
-        throw new Error('--addresses must be a valid JSON array of wallet address strings');
+    if (!options.addresses) {
+        throw new Error('Provide --addresses or --rows');
+    }
+    const addresses = (0, json_1.parseJsonArray)(options.addresses, '--addresses');
+    if (addresses.some((address) => typeof address !== 'string' || !address)) {
+        throw new Error('--addresses must be a JSON array of wallet address strings');
     }
     return {
-        addresses: parsedAddresses,
-        writeKey: options.writeKey,
+        addresses,
     };
 }
 function importWalletsRun(options) {
@@ -34,17 +42,31 @@ exports.importCmd.command('wallets', {
     options: incur_1.z.object({
         addresses: incur_1.z
             .string()
+            .optional()
             .describe('JSON array of wallet address strings to import'),
-        writeKey: incur_1.z.string().describe('Project write SDK key'),
+        rows: incur_1.z
+            .string()
+            .optional()
+            .describe('JSON array of {address,properties?} objects for imports with profile properties'),
+        writeKey: incur_1.z
+            .string()
+            .optional()
+            .describe('Deprecated; import now uses the project write key server-side')
+            .meta({ deprecated: true }),
     }),
     examples: [
         {
             options: {
                 addresses: '["0xabc…","0xdef…"]',
-                writeKey: 'write_key_xxx',
             },
             description: 'Import two wallet addresses',
         },
+        {
+            options: {
+                rows: '[{"address":"0xabc…","properties":{"display_name":"Alice"}}]',
+            },
+            description: 'Import wallets with profile properties',
+        },
     ],
     hint: 'Requires profiles:write scope. Only available on Scale and Enterprise plans.',
     run({ options }) {

package/dist/commands/profiles.d.ts

@@ -1,8 +1,21 @@
 import { Cli } from 'incur';
 export declare const profiles: Cli.Cli<{}, undefined, undefined>;
-export declare function getProfileRun(address: string, expand?: string): Promise<import("axios").AxiosResponse<any, any, {}>>;
-export interface SearchProfilesOptions {
+export interface LifecycleThresholdOptions {
+    newWindowDays?: number;
+    churnWindowDays?: number;
+    powerUserMinActiveDays?: number;
+    powerUserWindowDays?: number;
+    resurrectedGapDays?: number;
+    atRiskMinDaysInactive?: number;
+    atRiskPriorActiveDaysThreshold?: number;
+}
+export interface GetProfileOptions extends LifecycleThresholdOptions {
+    expand?: string;
+}
+export declare function getProfileRun(address: string, optionsOrExpand?: GetProfileOptions | string): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface SearchProfilesOptions extends LifecycleThresholdOptions {
     address?: string;
+    search?: string;
     page?: number;
     size?: number;
     orderBy?: string;
@@ -11,21 +24,41 @@ export interface SearchProfilesOptions {
     conditions?: 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.
+ */
+export declare function parseSearchConditions(raw: string): unknown[];
 export declare function searchProfilesRun(options: SearchProfilesOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface UpdateProfileOptions {
     properties: string;
 }
 export declare function buildUpdateProfileBody(options: UpdateProfileOptions): Record<string, unknown>;
 export declare function updateProfileRun(address: string, options: UpdateProfileOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface BatchUpdateProfilesOptions {
+    rows: string;
+}
+export declare function buildBatchUpdateProfilesBody(options: BatchUpdateProfilesOptions): Record<string, unknown>[];
+export declare function batchUpdateProfilesRun(options: BatchUpdateProfilesOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export declare const profilesProperties: Cli.Cli<{}, undefined, undefined>;
 export declare const profilesLabels: Cli.Cli<{}, undefined, undefined>;
 export interface CreateProfileLabelOptions {
     tagId?: string;
     value?: string;
     chainId?: string;
+    timestamp?: string;
+    isDeleted?: boolean;
     labels?: string;
 }
 export declare function buildCreateLabelBody(options: CreateProfileLabelOptions): unknown;
 export declare function createProfileLabelRun(address: string, options: CreateProfileLabelOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface BatchCreateProfileLabelsOptions {
+    labels: string;
+}
+export declare function buildBatchCreateLabelsBody(options: BatchCreateProfileLabelsOptions): Record<string, unknown>[];
+export declare function batchCreateProfileLabelsRun(options: BatchCreateProfileLabelsOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface DeleteProfileLabelOptions {
     tagId: string;
     chainId?: string;