@formo/cli 0.2.0 → 1.0.2

package/dist/commands/profiles.js

@@ -1,25 +1,89 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.profilesLabels = exports.profiles = void 0;
+exports.profilesLabels = exports.profilesProperties = exports.profiles = void 0;
 exports.getProfileRun = getProfileRun;
+exports.parseSearchConditions = parseSearchConditions;
 exports.searchProfilesRun = searchProfilesRun;
 exports.buildUpdateProfileBody = buildUpdateProfileBody;
 exports.updateProfileRun = updateProfileRun;
+exports.buildBatchUpdateProfilesBody = buildBatchUpdateProfilesBody;
+exports.batchUpdateProfilesRun = batchUpdateProfilesRun;
 exports.buildCreateLabelBody = buildCreateLabelBody;
 exports.createProfileLabelRun = createProfileLabelRun;
+exports.buildBatchCreateLabelsBody = buildBatchCreateLabelsBody;
+exports.batchCreateProfileLabelsRun = batchCreateProfileLabelsRun;
 exports.buildDeleteLabelBody = buildDeleteLabelBody;
 exports.deleteProfileLabelRun = deleteProfileLabelRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const json_1 = require("../lib/json");
 exports.profiles = incur_1.Cli.create('profiles', {
     description: 'Wallet profile commands',
 });
-function getProfileRun(address, expand) {
+function addLifecycleThresholdParams(params, options) {
+    if (options.newWindowDays !== undefined) {
+        params.new_window_days = options.newWindowDays;
+    }
+    if (options.churnWindowDays !== undefined) {
+        params.churn_window_days = options.churnWindowDays;
+    }
+    if (options.powerUserMinActiveDays !== undefined) {
+        params.power_user_min_active_days = options.powerUserMinActiveDays;
+    }
+    if (options.powerUserWindowDays !== undefined) {
+        params.power_user_window_days = options.powerUserWindowDays;
+    }
+    if (options.resurrectedGapDays !== undefined) {
+        params.resurrected_gap_days = options.resurrectedGapDays;
+    }
+    if (options.atRiskMinDaysInactive !== undefined) {
+        params.at_risk_min_days_inactive = options.atRiskMinDaysInactive;
+    }
+    if (options.atRiskPriorActiveDaysThreshold !== undefined) {
+        params.at_risk_prior_active_days_threshold =
+            options.atRiskPriorActiveDaysThreshold;
+    }
+}
+const lifecycleThresholdOptions = {
+    newWindowDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle new-user window in days'),
+    churnWindowDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle churn window in days'),
+    powerUserMinActiveDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle power-user minimum active days'),
+    powerUserWindowDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle power-user window in days'),
+    resurrectedGapDays: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle resurrected gap in days'),
+    atRiskMinDaysInactive: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle at-risk minimum inactive days'),
+    atRiskPriorActiveDaysThreshold: incur_1.z.coerce
+        .number()
+        .optional()
+        .describe('Override lifecycle at-risk prior active days threshold'),
+};
+function getProfileRun(address, optionsOrExpand = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
+    const options = typeof optionsOrExpand === 'string'
+        ? { expand: optionsOrExpand }
+        : optionsOrExpand;
     const params = {};
-    if (expand)
-        params.expand = expand;
+    if (options.expand)
+        params.expand = options.expand;
+    addLifecycleThresholdParams(params, options);
     return client.get(`/v0/profiles/${encodeURIComponent(address)}`, { params });
 }
 exports.profiles.command('get', {
@@ -32,6 +96,7 @@ exports.profiles.command('get', {
             .string()
             .optional()
             .describe('Comma-separated list of fields to expand: apps,chains,tokens,labels'),
+        ...lifecycleThresholdOptions,
     }),
     examples: [
         { args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' }, description: 'Get a wallet profile' },
@@ -41,16 +106,68 @@ 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);
+        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',
+    '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.search)
+        params.search = options.search;
     if (options.page !== undefined)
         params.page = options.page;
     if (options.size !== undefined)
@@ -61,24 +178,27 @@ function searchProfilesRun(options) {
         params.order_dir = options.orderDir;
     if (options.expand)
         params.expand = options.expand;
+    addLifecycleThresholdParams(params, options);
     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',
+        };
     }
+    // INTENTIONAL: the Formo search API is `GET /v0/profiles` with the
+    // `{ conditions, 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
+    // breaks the API. Filter-less searches still go over query params only.
     return client.request({ method: 'get', url: '/v0/profiles/', params, data: body });
 }
 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'),
+        search: incur_1.z.string().optional().describe('Free-text search across address and identity fields'),
         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
@@ -102,11 +222,20 @@ 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"'),
+        ...lifecycleThresholdOptions,
     }),
     examples: [
         { options: { size: 10 }, description: 'List first 10 profiles' },
@@ -120,34 +249,34 @@ exports.profiles.command('search', {
         },
         {
             options: {
-                conditions: '[{"field":"net_worth_usd","op":"gt","value":10000}]',
+                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',
                 size: 20,
             },
-            description: 'Search profiles matching either condition',
+            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 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');
-    }
+    const body = (0, json_1.parseJsonObject)(options.properties, '--properties');
     if (Object.keys(body).length === 0) {
         throw new Error('--properties must contain at least one key');
     }
@@ -187,6 +316,46 @@ exports.profiles.command('update', {
         return updateProfileRun(args.address, options);
     },
 });
+function buildBatchUpdateProfilesBody(options) {
+    const rows = (0, json_1.parseJsonArrayOfObjects)(options.rows, '--rows');
+    if (rows.length === 0) {
+        throw new Error('--rows must contain at least one item');
+    }
+    for (const row of rows) {
+        if (typeof row.address !== 'string' || row.address.length === 0) {
+            throw new Error('--rows entries must each include a non-empty string address');
+        }
+    }
+    return rows;
+}
+function batchUpdateProfilesRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/profiles/properties', buildBatchUpdateProfilesBody(options));
+}
+exports.profilesProperties = incur_1.Cli.create('properties', {
+    description: 'Manage first-party profile properties in bulk',
+});
+exports.profilesProperties.command('batch', {
+    description: 'Batch update first-party profile properties for up to 100 wallets',
+    options: incur_1.z.object({
+        rows: incur_1.z
+            .string()
+            .describe('JSON array of flat {address,...properties} objects. ENS names are not resolved in batch requests.'),
+    }),
+    examples: [
+        {
+            options: {
+                rows: '[{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","display_name":"alice.eth","email":"alice@example.com"}]',
+            },
+            description: 'Batch set display names and emails',
+        },
+    ],
+    hint: 'Requires profiles:write scope on your API key. Unknown keys are ignored by the API; invalid rows are quarantined.',
+    run({ options }) {
+        return batchUpdateProfilesRun(options);
+    },
+});
 // ── Labels sub-resource ──
 exports.profilesLabels = incur_1.Cli.create('labels', {
     description: 'Manage labels on a wallet profile',
@@ -205,13 +374,18 @@ function buildCreateLabelBody(options) {
     }
     if (options.tagId) {
         const single = { tag_id: options.tagId };
-        if (options.value)
+        if (options.value !== undefined)
             single.value = options.value;
         if (options.chainId)
             single.chain_id = options.chainId;
+        if (options.timestamp)
+            single.timestamp = options.timestamp;
+        if (options.isDeleted !== undefined) {
+            single._is_deleted = options.isDeleted ? 1 : 0;
+        }
         return single;
     }
-    throw new Error('Provide --tagId (single label) or --labels (batch JSON array)');
+    throw new Error('Provide --tag-id (single label) or --labels (batch JSON array)');
 }
 function createProfileLabelRun(address, options) {
     (0, client_1.requireApiKey)();
@@ -230,10 +404,18 @@ exports.profilesLabels.command('create', {
             .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'),
+        timestamp: incur_1.z
+            .string()
+            .optional()
+            .describe('Optional historical ISO-8601 timestamp for the label row'),
+        isDeleted: incur_1.z
+            .boolean()
+            .optional()
+            .describe('Set true with --timestamp to backfill a label removal tombstone'),
         labels: incur_1.z
             .string()
             .optional()
-            .describe('JSON array of UserLabelInput objects for batch upsert'),
+            .describe('JSON array of UserLabelInput objects for this wallet'),
     }),
     examples: [
         {
@@ -246,6 +428,11 @@ exports.profilesLabels.command('create', {
             options: { tagId: 'tier', value: 'gold', chainId: '1' },
             description: 'Apply a tiered label scoped to a chain',
         },
+        {
+            args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
+            options: { tagId: 'tier', timestamp: '2024-03-15T00:00:00.000Z', isDeleted: true },
+            description: 'Backfill a historical label removal',
+        },
         {
             args: { address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' },
             options: { labels: '[{"tag_id":"vip"},{"tag_id":"airdrop_eligible","chain_id":"1"}]' },
@@ -257,9 +444,49 @@ exports.profilesLabels.command('create', {
         return createProfileLabelRun(args.address, options);
     },
 });
+function buildBatchCreateLabelsBody(options) {
+    const labels = (0, json_1.parseJsonArrayOfObjects)(options.labels, '--labels');
+    if (labels.length === 0) {
+        throw new Error('--labels must contain at least one item');
+    }
+    for (const label of labels) {
+        if (typeof label.address !== 'string' || label.address.length === 0) {
+            throw new Error('--labels entries must each include a non-empty string address');
+        }
+        if (typeof label.tag_id !== 'string' || label.tag_id.length === 0) {
+            throw new Error('--labels entries must each include a non-empty string tag_id');
+        }
+    }
+    return labels;
+}
+function batchCreateProfileLabelsRun(options) {
+    (0, client_1.requireApiKey)();
+    const client = (0, client_1.createClient)();
+    return client.post('/v0/profiles/labels', buildBatchCreateLabelsBody(options));
+}
+exports.profilesLabels.command('batch', {
+    description: 'Batch upsert labels across up to 100 wallets',
+    options: incur_1.z.object({
+        labels: incur_1.z
+            .string()
+            .describe('JSON array of {address,tag_id,value?,chain_id?,timestamp?,_is_deleted?} objects'),
+    }),
+    examples: [
+        {
+            options: {
+                labels: '[{"address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","tag_id":"vip","value":"tier-1"}]',
+            },
+            description: 'Batch upsert labels for multiple wallets',
+        },
+    ],
+    hint: 'Requires profiles:write scope on your API key. ENS names are not resolved in batch requests.',
+    run({ options }) {
+        return batchCreateProfileLabelsRun(options);
+    },
+});
 function buildDeleteLabelBody(options) {
     if (!options.tagId) {
-        throw new Error('--tagId is required');
+        throw new Error('--tag-id is required');
     }
     const body = { tag_id: options.tagId };
     if (options.chainId)
@@ -297,4 +524,5 @@ exports.profilesLabels.command('delete', {
         return deleteProfileLabelRun(args.address, options);
     },
 });
+exports.profiles.command(exports.profilesProperties);
 exports.profiles.command(exports.profilesLabels);

package/dist/commands/query.js

@@ -4,13 +4,17 @@ exports.query = void 0;
 exports.queryRunRun = queryRunRun;
 const incur_1 = require("incur");
 const client_1 = require("../lib/client");
+const sql_1 = require("../lib/sql");
 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 });
+    // The API wraps the query in a paginating subquery with its own
+    // `FORMAT JSON`. ClickHouse forbids a `FORMAT` clause inside a subquery, so
+    // strip any trailing `FORMAT`/semicolon before sending to avoid a 400.
+    return client.post('/v0/query/', { query: (0, sql_1.stripTrailingFormatClause)(sql) });
 }
 exports.query.command('run', {
     description: 'Run a SQL query against your Formo analytics data',

package/dist/commands/segments.d.ts

@@ -1,13 +1,17 @@
 import { Cli } from 'incur';
 export declare const segments: Cli.Cli<{}, undefined, undefined>;
-export declare function listSegmentsRun(): Promise<import("axios").AxiosResponse<any, any, {}>>;
+export interface PaginationOptions {
+    page?: number;
+    size?: number;
+}
+export declare function listSegmentsRun(options?: PaginationOptions): Promise<import("axios").AxiosResponse<any, any, {}>>;
 export interface CreateSegmentOptions {
     title: string;
     filterSets: string;
 }
 export declare function buildCreateSegmentBody(options: CreateSegmentOptions): {
     title: string;
-    filterSets: unknown;
+    filterSets: any[];
 };
 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

@@ -10,27 +10,41 @@ const client_1 = require("../lib/client");
 exports.segments = incur_1.Cli.create('segments', {
     description: 'User segment commands — create, list, and delete audience segments',
 });
-// ── List segments ──
-function listSegmentsRun() {
+function buildPaginationParams(options = {}) {
+    const params = {};
+    if (options.page !== undefined)
+        params.page = options.page;
+    if (options.size !== undefined)
+        params.size = options.size;
+    return params;
+}
+function listSegmentsRun(options = {}) {
     (0, client_1.requireApiKey)();
     const client = (0, client_1.createClient)();
-    return client.get('/v0/segments/');
+    return client.get('/v0/segments/', { params: buildPaginationParams(options) });
 }
 exports.segments.command('list', {
     description: 'List all user segments 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 segments' }],
     hint: 'Requires segments:read scope on your API key.',
-    run() {
-        return listSegmentsRun();
+    run({ options }) {
+        return listSegmentsRun(options);
     },
 });
 function buildCreateSegmentBody(options) {
     let parsedFilterSets;
     try {
         parsedFilterSets = JSON.parse(options.filterSets);
+        if (!Array.isArray(parsedFilterSets)) {
+            throw new Error('not an array');
+        }
     }
     catch {
-        throw new Error('--filterSets must be a valid JSON array');
+        throw new Error('--filter-sets must be a valid JSON array');
     }
     return {
         title: options.title,

package/dist/index.js

@@ -3,18 +3,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const incur_1 = require("incur");
 const alerts_1 = require("./commands/alerts");
+const analytics_1 = require("./commands/analytics");
 const boards_1 = require("./commands/boards");
 const charts_1 = require("./commands/charts");
 const contracts_1 = require("./commands/contracts");
+const events_1 = require("./commands/events");
 const import_1 = require("./commands/import");
 const profiles_1 = require("./commands/profiles");
 const query_1 = require("./commands/query");
 const segments_1 = require("./commands/segments");
+const client_1 = require("./lib/client");
 const config_1 = require("./lib/config");
 const ui_1 = require("./lib/ui");
 const DASHBOARD_URL = "https://app.formo.so";
 const DOCS_URL = "https://docs.formo.so";
-const API_BASE_URL = "https://api.formo.so";
 function loginGuide() {
     return [
         "",
@@ -37,7 +39,7 @@ function loginGuide() {
 }
 async function validateAndFetchWorkspace(apiKey) {
     try {
-        const res = await fetch(`${API_BASE_URL}/api/validate-api-key`, {
+        const res = await fetch(`${(0, client_1.getApiBaseUrl)()}/api/validate-api-key`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify({ apiKey }),
@@ -57,21 +59,29 @@ async function validateAndFetchWorkspace(apiKey) {
     }
 }
 const cli = incur_1.Cli.create("formo", {
-    version: "0.2.0",
+    version: "1.0.1",
     description: "Formo API CLI — Web3 analytics from the terminal",
     sync: {
         suggestions: [
             "get the profile for wallet 0xabc",
             "search profiles with net worth > 10000",
             "run a SQL query on my analytics data",
+            "show traffic KPIs for the last 7 days",
+            "get the conversion funnel for the last month",
+            "list the top wallets by activity",
             "search profiles ordered by last_onchain desc",
             "list all project alerts",
             "create an alert for high-value transactions",
             "list charts in a board",
+            "create a line chart in a board",
+            "move or duplicate a dashboard chart",
             "list all tracked contracts",
             "register a new smart contract",
             "list user segments",
             "import wallet addresses",
+            "batch update profile properties with profiles properties batch",
+            "batch upsert labels for wallets",
+            "send raw analytics events",
         ],
     },
 });
@@ -234,10 +244,12 @@ cli.command("status", {
 // ── command groups ──
 cli.command(profiles_1.profiles);
 cli.command(query_1.query);
+cli.command(analytics_1.analytics);
 cli.command(alerts_1.alerts);
 cli.command(boards_1.boards);
 cli.command(charts_1.charts);
 cli.command(contracts_1.contracts);
+cli.command(events_1.events);
 cli.command(segments_1.segments);
 cli.command(import_1.importCmd);
 // Show banner when run with no args (root help)

package/dist/lib/client.d.ts

@@ -1,4 +1,8 @@
 import { AxiosError } from 'axios';
+export declare const DEFAULT_API_BASE_URL = "https://api.formo.so";
+export declare const DEFAULT_EVENTS_BASE_URL = "https://events.formo.so";
+export declare function getApiBaseUrl(): string;
+export declare function getEventsBaseUrl(): string;
 export interface ApiErrorBody {
     error?: {
         code?: string;
@@ -24,6 +28,11 @@ export interface DecoratedApiError extends Error {
  * Exported for unit testing — used by the response interceptor below.
  */
 export declare function parseApiError(error: AxiosError): DecoratedApiError;
-declare function createClient(): import("axios").AxiosInstance;
+export interface ClientOptions {
+    baseURL?: string;
+    apiKey?: string;
+}
+declare function createClient(options?: ClientOptions): import("axios").AxiosInstance;
+export declare function createEventsClient(writeKey: string): import("axios").AxiosInstance;
 export declare function requireApiKey(): void;
 export { createClient };