@palmyr/cli 1.8.5 → 1.9.1

package/dist/cli.js

@@ -17,6 +17,7 @@ import { render as inkRender } from 'ink';
 import { ConfigScreen, Dashboard, DoctorScreen, DomainCheckScreen, DomainPricingScreen, ErrorScreen, HealthScreen, MenuScreen, PricingScreen, RecordsScreen, SetupScreen, StatusScreen, SuccessScreen, WalletCreateScreen, WalletStatusScreen, WalletListScreen } from './app.js';
 import { Palmyr } from './sdk.js';
 import { loadConfig, saveConfig, ensureDirs, log, addPhone, addDomain, addNote } from './config.js';
+import { getState as getTelemetryState, setEnabled as setTelemetryEnabled, queuedCount as telemetryQueuedCount, appendEventSync as telemetryAppendEvent, flushQueue as telemetryFlushQueue } from './telemetry.js';
 import { theme as t, icon, Spinner, warn, table, kv, section, setAgentMode as setUiAgentMode } from './ui.js';
 import { existsSync, readFileSync } from 'fs';
 import { homedir } from 'os';
@@ -776,9 +777,15 @@ const TWITTER_HELP = {
         { flag: '(price)', desc: 'Free — local TOTP generation' },
     ],
     buy: [
-        { flag: '(no args)', desc: 'Purchase the oldest ready X account from the supplier pool' },
-        { flag: '(price)', desc: '$5 USDC — paid via x402. Account auto-imported into the local vault and session primed.' },
-        { flag: '(example)', desc: 'palmyr twitter buy' },
+        { flag: '(no args)', desc: 'Purchase the oldest ready X account from the supplier pool. Default for every filter below is random.' },
+        { flag: '--country <CC>', desc: 'Filter by RESIDENCY (X about_profile.account_based_in). ISO alpha-2 — US, GB, DE, …. Run `pool-prices` to see what is priced.' },
+        { flag: '--registered-country <CC>', desc: 'Filter by REGISTRATION country — where the X account was created from (parsed from X "Connected via" string). May differ from --country.' },
+        { flag: '--platform android|ios|web', desc: 'Filter by registration platform (also parsed from X "Connected via" string).' },
+        { flag: '--max-renames N', desc: 'Cap username-change count. --max-renames 0 = never renamed. Rows with unknown rename count do not match.' },
+        { flag: '--source "raw string"', desc: 'Power-user: exact-match against the lowercased raw "Connected via" string. Used for fine-grained source_multiplier pricing.' },
+        { flag: '--age 1y|2y|...', desc: 'Optional age category filter' },
+        { flag: '(price)', desc: '$5 USDC default; country_price * source_multiplier when filters are passed.' },
+        { flag: '(example)', desc: 'palmyr twitter buy --country GB --registered-country GB --platform android --max-renames 0' },
     ],
     login: [
         { flag: '<username>', desc: 'Force a fresh server-side session (browser runtime)' },
@@ -940,12 +947,62 @@ const TWITTER_HELP = {
     'pool-add': [
         { flag: '--credentials-line "..."', desc: 'Single account creds (login:pw:email:email_pw[:2fa[:ct0:auth_token]])' },
         { flag: '--file path.txt', desc: 'Bulk: one credentials-line per row (# = comment)' },
-        { flag: '--price <USDC>', desc: 'Required — what `twitter buy` will charge per account' },
-        { flag: '--country <CC>', desc: 'Optional metadata' },
+        { flag: '--price <USDC>', desc: 'Required — per-account sale_price_usdc (legacy fallback when no country price row exists)' },
+        { flag: '--country <CC>', desc: 'Optional override; twitterapi.io detects country + source + rename count from about_profile at seed time. Admin wins on country mismatch (flagged in response).' },
         { flag: '--age 1y|2y|3y|...', desc: 'Optional age category metadata' },
         { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
         { flag: '(price)', desc: 'Free — server-side seeding by pool operator' },
     ],
+    'pool-prices': [
+        { flag: '(no args)', desc: 'List per-country prices set by the pool admin (public, free).' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'pool-set-price': [
+        { flag: '--country <CC>', desc: 'ISO 3166-1 alpha-2 country code (US, GB, DE, …)' },
+        { flag: '--price <USDC>', desc: 'USDC amount the `buy --country <CC>` route will charge' },
+        { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'pool-delete-price': [
+        { flag: '--country <CC>', desc: 'Country code to remove pricing for' },
+        { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'pool-set-source-multiplier': [
+        { flag: '--source web|mobile|<id>', desc: 'Source identifier (matches the `source` column populated by twitterapi.io)' },
+        { flag: '--multiplier <number>', desc: 'Positive scaling factor applied on top of country price when --source is passed at buy time. 1.0 = no change.' },
+        { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'pool-delete-source-multiplier': [
+        { flag: '--source <id>', desc: 'Source identifier to remove the multiplier for (buy still works, just reverts to multiplier=1.0)' },
+        { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    dispute: [
+        { flag: '<account_id>', desc: 'Account id returned by `twitter buy` (the 32-char hex)' },
+        { flag: '--reason suspended|other', desc: 'Default "suspended" — triggers auto-verify via twitterapi.io' },
+        { flag: '--evidence "..."', desc: 'Optional note shown to the admin if the dispute ends up in admin_review' },
+        { flag: '(price)', desc: '$0.01 USDC ownership-proof. 7-day window from purchase.' },
+        { flag: '(example)', desc: 'palmyr twitter dispute abcd1234… --reason suspended' },
+    ],
+    disputes: [
+        { flag: '<dispute_id>', desc: 'Look up the status of a previously filed dispute' },
+        { flag: '(price)', desc: '$0.001 USDC' },
+    ],
+    'pool-disputes': [
+        { flag: '(no args)', desc: 'List every dispute in the system (admin)' },
+        { flag: '--status admin_review|pending|replaced|refunded|rejected', desc: 'Filter by status' },
+        { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
+        { flag: '(price)', desc: 'Free' },
+    ],
+    'pool-resolve-dispute': [
+        { flag: '<dispute_id>', desc: 'Id from `pool-disputes`' },
+        { flag: '--action replace|refund|reject', desc: 'replace = grant same-country swap; refund = USDC back to payer; reject = decline' },
+        { flag: '--note "..."', desc: 'Optional admin note appended to the resolution' },
+        { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
+        { flag: '(price)', desc: 'Free' },
+    ],
     'pool-status': [
         { flag: '(no args)', desc: 'Available / sold / reserved counts in the X account pool' },
         { flag: '(auth)', desc: 'Admin-signed call — requires PALMYR_ADMIN_KEY' },
@@ -1133,6 +1190,7 @@ const TOP_LEVEL_COMMANDS = [
     { name: 'doctor', description: 'Verify system health (cred store, vault, API)' },
     { name: 'pricing', description: 'All service prices' },
     { name: 'health', description: 'API status + version check' },
+    { name: 'telemetry', description: 'on · off · status (opt-in anonymous usage stats)' },
 ];
 // ─── Help ───
 function help() {
@@ -1226,6 +1284,22 @@ async function main() {
     const startTime = Date.now();
     // No first-time banner — agent-first CLI should never pollute output.
     const url = process.env.PALMYR_API || config.api;
+    // Opt-in telemetry. If the user has explicitly enabled it, queue this run's
+    // exit-code + duration on shutdown (sync — async work in 'exit' is dropped)
+    // and fire-and-forget any previously-queued events to the API right now.
+    // Both no-ops when telemetry is off. Never blocks the user's command —
+    // the flush races their work and Node exits once both finish.
+    process.on('exit', (code) => {
+        telemetryAppendEvent({
+            cmd: subcommand ? `${command} ${subcommand}` : command,
+            exitCode: code,
+            durationMs: Date.now() - startTime,
+            cliVersion: VERSION,
+            nodeVersion: process.version,
+            platform: process.platform,
+        });
+    });
+    void telemetryFlushQueue(url);
     const token = flags.token || config.apiKey || process.env.PALMYR_TOKEN || process.env.PALMYR_API_KEY;
     const passphrase = flags.passphrase || process.env.PALMYR_WALLET_PASSPHRASE;
     const ao = new Palmyr(url, true, token, passphrase);
@@ -6202,10 +6276,42 @@ async function main() {
                         return print({ success: true, platform, username, op: subcommand, ...(data?.data || {}) });
                     }
                     case 'buy': {
-                        // Agents just say "buy." Server picks the oldest ready account.
+                        // Agents say "buy" with optional filters. Each is independent
+                        // (default: random across that dimension).
+                        //
+                        //   --country GB              account_based_in = United Kingdom (residency)
+                        //   --registered-country GB   X's "Connected via …" country
+                        //   --platform android|ios|web   X's "Connected via" platform
+                        //   --max-renames 0           never-renamed accounts only
+                        //   --source "raw string"     exact-match on the raw "Connected via" string (power user)
+                        //
+                        // Pricing = country_price * source_multiplier (multiplier
+                        // defaults to 1.0 when no source row exists). Without --country,
+                        // falls back to the legacy $5 flat rate.
+                        const country = (flags.country || '').trim().toUpperCase() || undefined;
+                        const ageCategory = flags.age || flags['age-category'] || undefined;
+                        const source = (flags.source || '').trim().toLowerCase() || undefined;
+                        const registeredCountry = (flags['registered-country'] || '').trim().toUpperCase() || undefined;
+                        const platformFlag = (flags.platform || '').trim().toLowerCase() || undefined;
+                        if (platformFlag && !['android', 'ios', 'web'].includes(platformFlag)) {
+                            err('--platform must be one of: android, ios, web');
+                        }
+                        const registeredPlatform = platformFlag;
+                        const maxRenamesRaw = flags['max-renames'];
+                        const maxUsernameChanges = maxRenamesRaw === undefined || maxRenamesRaw === ''
+                            ? undefined
+                            : Number(maxRenamesRaw);
+                        if (maxUsernameChanges !== undefined && (!Number.isFinite(maxUsernameChanges) || maxUsernameChanges < 0)) {
+                            err('--max-renames must be a non-negative integer (e.g. 0 = never renamed)');
+                        }
                         let data;
                         try {
-                            data = await ao.socialTwitterBuy();
+                            data = await ao.socialTwitterBuy(country, ageCategory, {
+                                source,
+                                registeredCountry,
+                                registeredPlatform,
+                                maxUsernameChanges,
+                            });
                         }
                         catch (e) {
                             err(`Buy failed: ${e.message}`, EXIT.GENERAL);
@@ -6217,10 +6323,17 @@ async function main() {
                         // Auto-import into the local vault + prime the session cache so
                         // the buyer can post immediately with the cookies the admin
                         // pre-seasoned at pool-add time.
+                        const filterTags = [
+                            country && `country=${country}`,
+                            registeredCountry && `registered_country=${registeredCountry}`,
+                            registeredPlatform && `platform=${registeredPlatform}`,
+                            source && `source=${source}`,
+                            maxUsernameChanges !== undefined && `max_renames=${maxUsernameChanges}`,
+                        ].filter(Boolean).join(', ');
                         const summary = sv.importAccount(platform, account.username, account.credentials, {
                             source: 'pool',
                             proxy_session_id: account.proxy_session_id,
-                            notes: 'Bought from pool',
+                            notes: filterTags ? `Bought from pool (${filterTags})` : 'Bought from pool',
                         });
                         sv.saveSession(summary.id, platform, account.cookies || []);
                         sv.updateMeta(platform, summary.username, { last_action_at: new Date().toISOString() });
@@ -6228,8 +6341,179 @@ async function main() {
                             success: true,
                             platform,
                             username: summary.username,
-                            hint: `Ready to post — try: palmyr twitter post ${summary.username} --body "gm"`,
+                            country: account.country,
+                            registered_country: account.registered_country,
+                            registered_platform: account.registered_platform,
+                            source: account.source,
+                            username_change_count: account.username_change_count,
+                            account_based_in: account.account_based_in,
+                            account_id: account.id,
+                            hint: `Ready to post — try: palmyr twitter post ${summary.username} --body "gm". ` +
+                                `If the account is suspended within 7 days, run: palmyr twitter dispute ${account.id}`,
+                        });
+                    }
+                    case 'pool-prices': {
+                        // Public: which countries are priced and what they cost. Run
+                        // before `buy --country X` to confirm the country is available.
+                        let data;
+                        try {
+                            data = await ao.socialTwitterPoolPrices();
+                        }
+                        catch (e) {
+                            err(`pool-prices failed: ${e.message}`, EXIT.GENERAL);
+                        }
+                        return print(data);
+                    }
+                    case 'pool-set-price': {
+                        // Admin: set USDC price for a single country code. Idempotent.
+                        const { buildAdminHeaders } = await import('./admin-auth.js');
+                        const country = (flags.country || '').trim().toUpperCase();
+                        const price = flags.price !== undefined ? Number(flags.price) : NaN;
+                        if (!country)
+                            err('--country <CC> required (ISO 3166-1 alpha-2: US, GB, DE, …)');
+                        if (!Number.isFinite(price) || price <= 0)
+                            err('--price <USDC> required (positive number)');
+                        const path = `/social/twitter/pool/prices/${encodeURIComponent(country)}`;
+                        const headers = buildAdminHeaders('PUT', path);
+                        const res = await fetch(ao.api + path, {
+                            method: 'PUT',
+                            headers: { 'Content-Type': 'application/json', ...headers },
+                            body: JSON.stringify({ price_usdc: price }),
                         });
+                        const data = await res.json();
+                        if (!res.ok || !data.success)
+                            err(`pool-set-price failed: ${data.error || `HTTP ${res.status}`}`, EXIT.GENERAL);
+                        return print(data);
+                    }
+                    case 'pool-delete-price': {
+                        // Admin: remove the row for a country. Subsequent `buy --country X`
+                        // will return 400 "Country not priced" until set again.
+                        const { buildAdminHeaders } = await import('./admin-auth.js');
+                        const country = (flags.country || '').trim().toUpperCase();
+                        if (!country)
+                            err('--country <CC> required');
+                        const path = `/social/twitter/pool/prices/${encodeURIComponent(country)}`;
+                        const headers = buildAdminHeaders('DELETE', path);
+                        const res = await fetch(ao.api + path, { method: 'DELETE', headers });
+                        const data = await res.json();
+                        if (!res.ok)
+                            err(`pool-delete-price failed: ${data.error || `HTTP ${res.status}`}`, EXIT.GENERAL);
+                        return print(data);
+                    }
+                    case 'pool-set-source-multiplier': {
+                        // Admin: scale the country price for buys filtered by a given
+                        // source ('web', 'mobile', …). e.g. mult=1.2 → web buys cost
+                        // 20% more than the base country price.
+                        const { buildAdminHeaders } = await import('./admin-auth.js');
+                        const source = (flags.source || '').trim().toLowerCase();
+                        const mult = flags.multiplier !== undefined ? Number(flags.multiplier) : NaN;
+                        if (!source)
+                            err('--source <name> required (e.g. web, mobile)');
+                        if (!Number.isFinite(mult) || mult <= 0)
+                            err('--multiplier <number> required (positive)');
+                        const path = `/social/twitter/pool/source-multipliers/${encodeURIComponent(source)}`;
+                        const headers = buildAdminHeaders('PUT', path);
+                        const res = await fetch(ao.api + path, {
+                            method: 'PUT',
+                            headers: { 'Content-Type': 'application/json', ...headers },
+                            body: JSON.stringify({ multiplier: mult }),
+                        });
+                        const data = await res.json();
+                        if (!res.ok || !data.success)
+                            err(`pool-set-source-multiplier failed: ${data.error || `HTTP ${res.status}`}`, EXIT.GENERAL);
+                        return print(data);
+                    }
+                    case 'pool-delete-source-multiplier': {
+                        // Admin: drop the multiplier for a source. Subsequent `buy
+                        // --source X` reverts to using 1.0 (filter only, no price scaling).
+                        const { buildAdminHeaders } = await import('./admin-auth.js');
+                        const source = (flags.source || '').trim().toLowerCase();
+                        if (!source)
+                            err('--source <name> required');
+                        const path = `/social/twitter/pool/source-multipliers/${encodeURIComponent(source)}`;
+                        const headers = buildAdminHeaders('DELETE', path);
+                        const res = await fetch(ao.api + path, { method: 'DELETE', headers });
+                        const data = await res.json();
+                        if (!res.ok)
+                            err(`pool-delete-source-multiplier failed: ${data.error || `HTTP ${res.status}`}`, EXIT.GENERAL);
+                        return print(data);
+                    }
+                    case 'dispute': {
+                        // Buyer: file a dispute for a pool-bought account that got
+                        // suspended. Server auto-verifies via twitterapi.io and either
+                        // hands over a same-country replacement, refunds USDC, or queues
+                        // for admin review when the signal is ambiguous.
+                        const accountId = positional[0] || flags['account-id'] || flags.id;
+                        const reason = (flags.reason || 'suspended');
+                        const evidence = flags.evidence || flags.note || undefined;
+                        if (!accountId)
+                            err('<account_id> required (the id returned by `palmyr twitter buy`)');
+                        if (reason !== 'suspended' && reason !== 'other')
+                            err('--reason must be "suspended" or "other"');
+                        let data;
+                        try {
+                            data = await ao.socialTwitterDispute(accountId, { reason, evidence });
+                        }
+                        catch (e) {
+                            err(`Dispute failed: ${e.message}`, EXIT.GENERAL);
+                        }
+                        if (!data?.success)
+                            err(`Dispute failed: ${data?.error || 'unknown'}`, EXIT.GENERAL);
+                        return print(data);
+                    }
+                    case 'disputes': {
+                        // Buyer: list ONE specific dispute by id. Listing all your
+                        // disputes isn't supported by the buyer surface today — track
+                        // the id printed by `dispute` and call `disputes <id>`.
+                        const id = positional[0] || flags.id;
+                        if (!id)
+                            err('<dispute_id> required');
+                        let data;
+                        try {
+                            data = await ao.socialTwitterDisputeGet(id);
+                        }
+                        catch (e) {
+                            err(`Get dispute failed: ${e.message}`, EXIT.GENERAL);
+                        }
+                        return print(data);
+                    }
+                    case 'pool-disputes': {
+                        // Admin: list every dispute, optionally filter by status. The
+                        // `admin_review` queue is the human-decision backlog.
+                        const { buildAdminHeaders } = await import('./admin-auth.js');
+                        const status = flags.status || undefined;
+                        const path = '/social/twitter/pool/disputes' + (status ? `?status=${encodeURIComponent(status)}` : '');
+                        const headers = buildAdminHeaders('GET', path);
+                        const res = await fetch(ao.api + path, { headers });
+                        const data = await res.json();
+                        if (!res.ok)
+                            err(`pool-disputes failed: ${data.error || `HTTP ${res.status}`}`, EXIT.GENERAL);
+                        return print(data);
+                    }
+                    case 'pool-resolve-dispute': {
+                        // Admin: resolve an admin_review dispute. action ∈ replace |
+                        // refund | reject. `replace` needs same-country stock; `refund`
+                        // needs payment provenance on the row (auto-saved at buy time).
+                        const { buildAdminHeaders } = await import('./admin-auth.js');
+                        const id = positional[0] || flags.id;
+                        const action = flags.action;
+                        const note = flags.note || undefined;
+                        if (!id)
+                            err('<dispute_id> required');
+                        if (action !== 'replace' && action !== 'refund' && action !== 'reject') {
+                            err('--action must be "replace", "refund", or "reject"');
+                        }
+                        const path = `/social/twitter/pool/disputes/${encodeURIComponent(id)}/resolve`;
+                        const headers = buildAdminHeaders('POST', path);
+                        const res = await fetch(ao.api + path, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json', ...headers },
+                            body: JSON.stringify({ action, ...(note ? { note } : {}) }),
+                        });
+                        const data = await res.json();
+                        if (!res.ok || !data.success)
+                            err(`pool-resolve-dispute failed: ${data.error || `HTTP ${res.status}`}`, EXIT.GENERAL);
+                        return print(data);
                     }
                     case 'pool-add': {
                         const { buildAdminHeaders } = await import('./admin-auth.js');
@@ -7080,6 +7364,55 @@ async function main() {
                     'The Palmyr server fires them at post_at without any client process.', EXIT.BAD_INPUT);
                 break;
             }
+            case 'telemetry': {
+                // Off by default. Opt-in only. We never auto-enable, never prompt at
+                // startup, never write to stdout outside this command. Captured fields
+                // and storage location are documented in cli/telemetry.ts.
+                const action = (subcommand || 'status').toLowerCase();
+                if (action !== 'on' && action !== 'off' && action !== 'status') {
+                    err(`Unknown telemetry action: ${action}. Use: on | off | status`, EXIT.BAD_INPUT);
+                }
+                let state;
+                if (action === 'on')
+                    state = setTelemetryEnabled(true);
+                else if (action === 'off')
+                    state = setTelemetryEnabled(false);
+                else
+                    state = getTelemetryState();
+                const payload = {
+                    enabled: state.enabled,
+                    installId: state.installId || null,
+                    optedInAt: state.optedInAt || null,
+                    queuedEvents: telemetryQueuedCount(),
+                    captures: ['cmd', 'exitCode', 'durationMs', 'cliVersion', 'nodeVersion', 'platform'],
+                    neverCaptures: ['flag values', 'positional args', 'stdout/stderr', 'wallet addresses', 'phone numbers', 'any user input'],
+                };
+                if (AGENT_MODE) {
+                    print(payload);
+                }
+                else {
+                    const status = state.enabled ? `${t.success}on${t.reset}` : `${t.muted}off${t.reset}`;
+                    console.log(`Telemetry:  ${status}`);
+                    if (state.installId)
+                        console.log(`Install ID: ${t.muted}${state.installId}${t.reset}`);
+                    if (state.optedInAt)
+                        console.log(`Opted in:   ${state.optedInAt}`);
+                    if (payload.queuedEvents)
+                        console.log(`Queued:     ${payload.queuedEvents} event(s) waiting to send`);
+                    console.log('');
+                    console.log(`Captures:   ${payload.captures.join(', ')}`);
+                    console.log(`Never:      flag values, positional args, stdout, user input`);
+                    if (!state.enabled) {
+                        console.log('');
+                        console.log(`Opt in:     ${t.accent}palmyr telemetry on${t.reset}`);
+                    }
+                    else {
+                        console.log('');
+                        console.log(`Opt out:    ${t.accent}palmyr telemetry off${t.reset}  (drops any queued events)`);
+                    }
+                }
+                break;
+            }
             case 'config': {
                 const cfg = loadConfig();
                 const { homedir } = await import('os');