@formo/cli 0.1.0 → 1.0.0

package/dist/commands/profiles.js

@@ -1,8 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.profiles = void 0;
+exports.profilesLabels = exports.profiles = void 0;
 exports.getProfileRun = getProfileRun;
+exports.parseSearchConditions = parseSearchConditions;
 exports.searchProfilesRun = searchProfilesRun;
+exports.buildUpdateProfileBody = buildUpdateProfileBody;
+exports.updateProfileRun = updateProfileRun;
+exports.buildCreateLabelBody = buildCreateLabelBody;
+exports.createProfileLabelRun = createProfileLabelRun;
+exports.buildDeleteLabelBody = buildDeleteLabelBody;
+exports.deleteProfileLabelRun = deleteProfileLabelRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
 exports.profiles = incur_1.Cli.create('profiles', {
@@ -35,20 +42,70 @@ exports.profiles.command('get', {
             description: 'Get profile with expanded labels and chains',
         },
     ],
+    hint: 'Requires profiles:read scope on your API key.',
     run({ args, options }) {
         return getProfileRun(args.address, options.expand);
     },
 });
+// 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',
+    'chain',
+    'chains',
+    'app',
+    'apps',
+    'token',
+    'tokens',
+    'label',
+    'labels',
+]);
+/**
+ * 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.
+ */
+function parseSearchConditions(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('--conditions 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');
+    }
+    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');
+        }
+        const field = cond.field;
+        if (typeof field !== 'string' || field.length === 0) {
+            throw new Error('--conditions: each entry must have a non-empty string "field"');
+        }
+        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)');
+        }
+    }
+    return parsed;
+}
 function searchProfilesRun(options) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     const params = {};
     if (options.address)
         params.address = options.address;
-    if (options.limit !== undefined)
-        params.limit = options.limit;
-    if (options.offset !== undefined)
-        params.offset = options.offset;
+    if (options.page !== undefined)
+        params.page = options.page;
+    if (options.size !== undefined)
+        params.size = options.size;
     if (options.orderBy)
         params.order_by = options.orderBy;
     if (options.orderDir)
@@ -57,15 +114,10 @@ function searchProfilesRun(options) {
         params.expand = options.expand;
     let body;
     if (options.conditions) {
-        try {
-            const conditions = JSON.parse(options.conditions);
-            if (!Array.isArray(conditions))
-                throw new Error('not an array');
-            body = { conditions, logic: options.logic ?? 'and' };
-        }
-        catch {
-            throw new Error('--conditions must be valid JSON array of FilterCondition objects');
-        }
+        body = {
+            conditions: parseSearchConditions(options.conditions),
+            logic: options.logic ?? 'and',
+        };
     }
     return client.request({ method: 'get', url: '/v0/profiles/', params, data: body });
 }
@@ -73,8 +125,8 @@ exports.profiles.command('search', {
     description: 'Search wallet profiles with optional filters',
     options: incur_1.z.object({
         address: incur_1.z.string().optional().describe('Filter by wallet address'),
-        limit: incur_1.z.coerce.number().optional().describe('Max results to return'),
-        offset: incur_1.z.coerce.number().optional().describe('Pagination offset'),
+        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 1000)'),
         orderBy: incur_1.z
             .enum([
             'last_onchain',
@@ -96,35 +148,215 @@ exports.profiles.command('search', {
         conditions: incur_1.z
             .string()
             .optional()
-            .describe('JSON array of FilterCondition objects for advanced filtering'),
+            .describe('JSON array of FilterCondition objects: [{"field","op","value"}]. ' +
+            'The "field" MUST be a typed path — a bare name like "net_worth_usd" is silently ignored. ' +
+            '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.'),
         logic: incur_1.z
             .enum(['and', 'or'])
             .optional()
             .describe('Logic operator for combining conditions: "and" (default) or "or"'),
     }),
     examples: [
-        { options: { limit: 10 }, description: 'List first 10 profiles' },
+        { options: { size: 10 }, description: 'List first 10 profiles' },
         {
-            options: { orderBy: 'net_worth_usd', orderDir: 'desc', limit: 5 },
+            options: { orderBy: 'net_worth_usd', orderDir: 'desc', size: 5 },
             description: 'Top 5 profiles by net worth',
         },
+        {
+            options: { page: 2, size: 20 },
+            description: 'Get the second page of 20 profiles',
+        },
         {
             options: {
-                conditions: '[{"field":"net_worth_usd","op":"gt","value":10000}]',
-                limit: 20,
+                conditions: '[{"field":"users.net_worth_usd","op":"gt","value":10000}]',
+                size: 20,
             },
-            description: 'Search profiles with net worth > 10000',
+            description: 'Search profiles with net worth > $10k',
         },
         {
             options: {
-                conditions: '[{"field":"net_worth_usd","op":"gt","value":10000},{"field":"tx_count","op":"gt","value":50}]',
+                conditions: '[{"field":"users.net_worth_usd","op":"gt","value":10000},{"field":"users.volume","op":"gt","value":1000}]',
                 logic: 'or',
-                limit: 20,
+                size: 20,
+            },
+            description: 'Search profiles matching either condition (net worth or volume)',
+        },
+        {
+            options: {
+                conditions: '[{"field":"chains.1.balance","op":"gt","value":1000}]',
+                size: 20,
             },
-            description: 'Search profiles matching either condition',
+            description: 'Search profiles with > $1k balance on Ethereum (chain 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.',
     run({ args: _args, options }) {
         return searchProfilesRun(options);
     },
 });
+function buildUpdateProfileBody(options) {
+    let body;
+    try {
+        body = JSON.parse(options.properties);
+        if (!body || typeof body !== 'object' || Array.isArray(body))
+            throw new Error('not an object');
+    }
+    catch {
+        throw new Error('--properties must be a JSON object of property keys');
+    }
+    if (Object.keys(body).length === 0) {
+        throw new Error('--properties must contain at least one key');
+    }
+    return body;
+}
+function updateProfileRun(address, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.put(`/v0/profiles/${encodeURIComponent(address)}/properties`, buildUpdateProfileBody(options));
+}
+exports.profiles.command('update', {
+    description: 'Merge-update identity properties on a wallet profile',
+    args: incur_1.z.object({
+        address: incur_1.z.string().describe('Wallet address (0x... or ENS name)'),
+    }),
+    options: incur_1.z.object({
+        properties: incur_1.z
+            .string()
+            .describe('JSON object of properties to merge. Allowed keys: user_id, display_name, email, farcaster, discord, twitter, telegram, instagram, website, github, linkedin, facebook, tiktok, youtube, reddit, avatar, description, location, ens, lens, basenames, linea'),
+    }),
+    examples: [
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: {
+                properties: '{"display_name":"Vitalik","twitter":"VitalikButerin"}',
+            },
+            description: 'Set display name and Twitter handle',
+        },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { properties: '{"email":"alice@example.com"}' },
+            description: 'Set just the email',
+        },
+    ],
+    hint: 'Requires profiles:write scope on your API key. Only the listed keys are accepted; unknown keys are rejected.',
+    run({ args, options }) {
+        return updateProfileRun(args.address, options);
+    },
+});
+// ── Labels sub-resource ──
+exports.profilesLabels = incur_1.Cli.create('labels', {
+    description: 'Manage labels on a wallet profile',
+});
+function buildCreateLabelBody(options) {
+    if (options.labels) {
+        try {
+            const parsed = JSON.parse(options.labels);
+            if (!Array.isArray(parsed) || parsed.length === 0)
+                throw new Error('not a non-empty array');
+            return parsed;
+        }
+        catch {
+            throw new Error('--labels must be a non-empty JSON array of UserLabelInput objects');
+        }
+    }
+    if (options.tagId) {
+        const single = { tag_id: options.tagId };
+        if (options.value)
+            single.value = options.value;
+        if (options.chainId)
+            single.chain_id = options.chainId;
+        return single;
+    }
+    throw new Error('Provide --tag-id (single label) or --labels (batch JSON array)');
+}
+function createProfileLabelRun(address, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post(`/v0/profiles/${encodeURIComponent(address)}/labels`, buildCreateLabelBody(options));
+}
+exports.profilesLabels.command('create', {
+    description: 'Upsert one or more labels on a wallet profile',
+    args: incur_1.z.object({
+        address: incur_1.z.string().describe('Wallet address (0x... or ENS name)'),
+    }),
+    options: incur_1.z.object({
+        tagId: incur_1.z
+            .string()
+            .optional()
+            .describe('Label identifier (e.g. "vip", "airdrop_eligible")'),
+        value: incur_1.z.string().optional().describe('Optional label value (e.g. tier name, country code)'),
+        chainId: incur_1.z.string().optional().describe('Optional chain identifier the label applies to'),
+        labels: incur_1.z
+            .string()
+            .optional()
+            .describe('JSON array of UserLabelInput objects for batch upsert'),
+    }),
+    examples: [
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { tagId: 'vip' },
+            description: 'Tag a wallet as VIP',
+        },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { tagId: 'tier', value: 'gold', chainId: '1' },
+            description: 'Apply a tiered label scoped to a chain',
+        },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { labels: '[{"tag_id":"vip"},{"tag_id":"airdrop_eligible","chain_id":"1"}]' },
+            description: 'Apply multiple labels in one call',
+        },
+    ],
+    hint: 'Requires profiles:write scope on your API key.',
+    run({ args, options }) {
+        return createProfileLabelRun(args.address, options);
+    },
+});
+function buildDeleteLabelBody(options) {
+    if (!options.tagId) {
+        throw new Error('--tag-id is required');
+    }
+    const body = { tag_id: options.tagId };
+    if (options.chainId)
+        body.chain_id = options.chainId;
+    return body;
+}
+function deleteProfileLabelRun(address, options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.delete(`/v0/profiles/${encodeURIComponent(address)}/labels`, { data: buildDeleteLabelBody(options) });
+}
+exports.profilesLabels.command('delete', {
+    description: 'Delete a label from a wallet profile',
+    args: incur_1.z.object({
+        address: incur_1.z.string().describe('Wallet address (0x... or ENS name)'),
+    }),
+    options: incur_1.z.object({
+        tagId: incur_1.z.string().describe('Label identifier to delete'),
+        chainId: incur_1.z.string().optional().describe('Optional chain identifier to scope the deletion'),
+    }),
+    examples: [
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { tagId: 'vip' },
+            description: 'Remove the vip label',
+        },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { tagId: 'tier', chainId: '1' },
+            description: 'Remove a chain-scoped label',
+        },
+    ],
+    hint: 'Requires profiles:write scope on your API key.',
+    run({ args, options }) {
+        return deleteProfileLabelRun(args.address, options);
+    },
+});
+exports.profiles.command(exports.profilesLabels);

package/dist/commands/query.d.ts

@@ -1 +1,3 @@
+import { Cli } from 'incur';
+export declare const query: Cli.Cli<{}, undefined, undefined>;
 export declare function queryRunRun(sql: string): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/query.js

@@ -1,9 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.query = void 0;
 exports.queryRunRun = queryRunRun;
+const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+exports.query = incur_1.Cli.create('query', {
+    description: 'SQL analytics query commands',
+});
 function queryRunRun(sql) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
     return client.post('/v0/query/', { query: sql });
 }
+exports.query.command('run', {
+    description: 'Run a SQL query against your Formo analytics data',
+    args: incur_1.z.object({
+        sql: incur_1.z.string().describe('SQL query string to execute'),
+    }),
+    examples: [
+        {
+            args: { sql: 'SELECT count(*) FROM events' },
+            description: 'Count all events',
+        },
+        {
+            args: { sql: 'SELECT address, net_worth_usd FROM wallet_profiles ORDER BY net_worth_usd DESC LIMIT 10' },
+            description: 'Top 10 wallets by net worth',
+        },
+    ],
+    hint: 'Requires query:read scope on your API key.',
+    run({ args }) {
+        return queryRunRun(args.sql);
+    },
+});

package/dist/commands/segments.d.ts

@@ -5,5 +5,9 @@ export interface CreateSegmentOptions {
     title: string;
     filterSets: string;
 }
+export declare function buildCreateSegmentBody(options: CreateSegmentOptions): {
+    title: string;
+    filterSets: unknown;
+};
 export declare function createSegmentRun(options: CreateSegmentOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export declare function deleteSegmentRun(segmentId: string): Promise<import("axios").AxiosResponse<any, any, {}>>;

package/dist/commands/segments.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.segments = void 0;
 exports.listSegmentsRun = listSegmentsRun;
+exports.buildCreateSegmentBody = buildCreateSegmentBody;
 exports.createSegmentRun = createSegmentRun;
 exports.deleteSegmentRun = deleteSegmentRun;
 const incur_1 = require("incur");
@@ -23,20 +24,23 @@ exports.segments.command('list', {
         return listSegmentsRun();
     },
 });
-function createSegmentRun(options) {
-    (0, client_1.requireApiKey)();
-    const client = (0, client_1.createClient)();
+function buildCreateSegmentBody(options) {
     let parsedFilterSets;
     try {
         parsedFilterSets = JSON.parse(options.filterSets);
     }
     catch {
-        throw new Error('--filterSets must be a valid JSON array');
+        throw new Error('--filter-sets must be a valid JSON array');
     }
-    return client.post('/v0/segments/', {
+    return {
         title: options.title,
         filterSets: parsedFilterSets,
-    });
+    };
+}
+function createSegmentRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/segments/', buildCreateSegmentBody(options));
 }
 exports.segments.command('create', {
     description: 'Create a new user segment',

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import { Cli } from 'incur';
+import { Cli } from "incur";
 declare const cli: Cli.Cli<{}, undefined, undefined>;
 export default cli;