@formo/cli 0.1.0 → 0.2.0

package/dist/commands/profiles.js

@@ -1,8 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.profiles = void 0;
+exports.profilesLabels = exports.profiles = void 0;
 exports.getProfileRun = getProfileRun;
 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', {
@@ -45,10 +51,10 @@ function searchProfilesRun(options) {
     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)
@@ -73,8 +79,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',
@@ -103,15 +109,19 @@ exports.profiles.command('search', {
             .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,
+                size: 20,
             },
             description: 'Search profiles with net worth > 10000',
         },
@@ -119,7 +129,7 @@ exports.profiles.command('search', {
             options: {
                 conditions: '[{"field":"net_worth_usd","op":"gt","value":10000},{"field":"tx_count","op":"gt","value":50}]',
                 logic: 'or',
-                limit: 20,
+                size: 20,
             },
             description: 'Search profiles matching either condition',
         },
@@ -128,3 +138,163 @@ exports.profiles.command('search', {
         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 --tagId (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('--tagId 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,9 +24,7 @@ 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);
@@ -33,10 +32,15 @@ function createSegmentRun(options) {
     catch {
         throw new Error('--filterSets 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;