callkaro-cli-unofficial 0.5.0 → 0.6.0

package/dist/index.js

@@ -36,6 +36,8 @@ const batches_1 = require("./commands/batches");
 const simulations_1 = require("./commands/simulations");
 const simVariables_1 = require("./commands/simVariables");
 const dashboardApiCmd_1 = require("./commands/dashboardApiCmd");
+const adminAuth_1 = require("./lib/adminAuth");
+const admin_1 = require("./commands/admin");
 const auditStrategies_1 = require("./commands/auditStrategies");
 const chatAgents_1 = require("./commands/chatAgents");
 // The command this fork installs as. Deliberately NOT `ck` or `callkaro`:
@@ -71,6 +73,7 @@ program
     .description('sign in through your browser (no password in the terminal)')
     .option('--password', 'use the classic email + password prompt instead')
     .option('--email <email>', 'email address (with --password)')
+    .option('--no-save-password', "don't keep the password (the token then cannot be renewed)")
     .action(accounts_1.loginCommand);
 program
     .command('logout')
@@ -114,6 +117,150 @@ dashboard
     .option('--query <k=v...>', 'query parameter, repeatable', (v, prev = []) => [...prev, v])
     .addHelpText('after', '\n  Example: cku dashboard api GET /v1/test-simulations --query agentId=<id>\n  Errors print the status and full body to stderr and exit 1.')
     .action(dashboardApiCmd_1.dashboardApiCommand);
+// The internal admin console (intadmin.callkaro.ai). A third credential: the
+// /monitor/* routes answer to the access_token_monitor cookie and to nothing
+// else. It is the only place the console's write routes live — recharge,
+// concurrency, pause/resume, phone numbers — and the only way to act on a
+// client account when no login of yours is assigned to it.
+const admin = program
+    .command('admin')
+    .description('the internal admin console: client accounts, analytics, and the console writes');
+admin
+    .command('login')
+    .description('sign in to the internal admin console')
+    .option('--email <email>', 'skip the email prompt')
+    .option('--no-save-password', "don't keep the password (the session then lapses after 24h)")
+    .action(adminAuth_1.adminLoginCommand);
+admin
+    .command('whoami')
+    .description('prove the stored admin console session still works')
+    .option('--json', 'output raw JSON')
+    .action(adminAuth_1.adminWhoamiCommand);
+admin
+    .command('logout')
+    .description('forget the admin console session (the ck_ token is kept)')
+    .option('--yes', 'skip the confirmation')
+    .action(adminAuth_1.adminLogoutCommand);
+admin
+    .command('clients', { isDefault: true })
+    .description('list the client accounts assigned to this admin user')
+    .option('--json', 'output raw JSON')
+    .action(admin_1.adminClientsCommand);
+admin
+    .command('client <clientId>')
+    .description('show one client account: plan, credits, concurrency, phone numbers')
+    .option('--json', 'output raw JSON')
+    .action(admin_1.adminClientCommand);
+admin
+    .command('coworkers <clientId>')
+    .description('list the coworkers assigned to a client account')
+    .option('--json', 'output raw JSON')
+    .action(admin_1.adminCoworkersCommand);
+admin
+    .command('impersonate <clientId>')
+    .description("mint a real ck_ token for a client account and store it, scoped to that client")
+    .option('--yes', 'skip the confirmation when the account already has a login')
+    .addHelpText('after', '\n  This is the console\'s "Login as this user", in the terminal. The token is stored\n' +
+    '  under the client\'s own email, so `cku accounts use <email>` picks it up, and it\n' +
+    '  renews itself by impersonating again.\n')
+    .action(admin_1.adminImpersonateCommand);
+admin
+    .command('analytics')
+    .description('call, minute and cost totals per client')
+    .option('--client <id>', 'scope to one client account id')
+    .option('--start <YYYY-MM-DD>', 'window start (default: one month ago)')
+    .option('--end <YYYY-MM-DD>', 'window end (default: today)')
+    .option('--json', 'output raw JSON')
+    .action(admin_1.adminAnalyticsCommand);
+admin
+    .command('costs')
+    .description('total and daily cost, broken down by subscription and category')
+    .option('--client <id>', 'scope to one client account id')
+    .option('--start <YYYY-MM-DD>', 'window start (default: one month ago)')
+    .option('--end <YYYY-MM-DD>', 'window end (default: today)')
+    .option('--json', 'output raw JSON')
+    .action(admin_1.adminCostsCommand);
+admin
+    .command('recharges <clientId>')
+    .description('a client account\'s recharge history')
+    .option('--start <YYYY-MM-DD>', 'window start (default: one month ago)')
+    .option('--end <YYYY-MM-DD>', 'window end (default: today)')
+    .option('--json', 'output raw JSON')
+    .action(admin_1.adminRechargesCommand);
+admin
+    .command('calls')
+    .description('look up calls by phone number, lead id, buylead, call sid or call id')
+    .option('--phone <number>', 'the number that was called')
+    .option('--lead-id <id>', 'lead id')
+    .option('--buylead <id>', 'buylead id')
+    .option('--call-sid <sid>', 'call sid')
+    .option('--call-id <id>', 'call id')
+    .option('--json', 'output raw JSON')
+    .addHelpText('after', '\n  The search needs exactly one of those. Filling more than one narrows it.')
+    .action(admin_1.adminCallsCommand);
+admin
+    .command('bots')
+    .description('the bots (agent + client pairs) seen over a window')
+    .option('--start <YYYY-MM-DD>', 'window start (default: one month ago)')
+    .option('--end <YYYY-MM-DD>', 'window end (default: today)')
+    .option('--json', 'output raw JSON')
+    .action(admin_1.adminBotsCommand);
+admin
+    .command('sentry')
+    .description('Sentry transactions over the last 24h')
+    .option('--json', 'output raw JSON')
+    .action(admin_1.adminSentryCommand);
+admin
+    .command('recharge <clientId>')
+    .description('add credits to a client account (real money — the console has no undo)')
+    .requiredOption('--amount <n>', 'credits to add')
+    .option('--yes', 'skip the confirmation')
+    .action(admin_1.adminRechargeCommand);
+admin
+    .command('set <clientId>')
+    .description("change a client account's settings")
+    .option('--concurrency <n>', 'set the concurrency limit')
+    .option('--yes', 'skip the confirmation')
+    .action(admin_1.adminClientSetCommand);
+admin
+    .command('pause <clientId>')
+    .description('pause a client account — no more calls dial out for it')
+    .option('--yes', 'skip the confirmation')
+    .action((clientId, opts) => (0, admin_1.adminClientActionCommand)('pause', clientId, opts));
+admin
+    .command('resume <clientId>')
+    .description('resume a paused client account')
+    .option('--yes', 'skip the confirmation')
+    .action((clientId, opts) => (0, admin_1.adminClientActionCommand)('resume', clientId, opts));
+admin
+    .command('clear <clientId>')
+    .description("clear a client account's whole call queue")
+    .option('--yes', 'skip the confirmation')
+    .action((clientId, opts) => (0, admin_1.adminClientActionCommand)('clear', clientId, opts));
+admin
+    .command('agent <action> <clientId> <agentId>')
+    .description('pause, resume or clear one agent of a client account (action: pause, resume, clear)')
+    .option('--yes', 'skip the confirmation')
+    .action(admin_1.adminAgentActionCommand);
+admin
+    .command('numbers <clientIds...>')
+    .description('add or replace the phone numbers on several client accounts at once')
+    .requiredOption('--phone <n,n>', 'phone numbers, comma separated')
+    .option('--mode <mode>', 'add (keep existing) or replace (default)', 'replace')
+    .option('--yes', 'skip the confirmation')
+    .action(admin_1.adminNumbersCommand);
+admin
+    .command('voice-cache')
+    .description('clear the console-wide voice cache')
+    .option('--yes', 'skip the confirmation')
+    .action(admin_1.adminVoiceCacheCommand);
+admin
+    .command('api <method> <path>')
+    .description('call any admin route with the stored session (the token never leaves the CLI)')
+    .option('--body <json|@file>', 'JSON request body')
+    .option('--query <k=v...>', 'query parameter, repeatable', (v, prev = []) => [...prev, v])
+    .addHelpText('after', '\n  Example: cku admin api GET /monitor/bots --query startDate=2026-01-01\n  Errors print the status and full body to stderr and exit 1.')
+    .action(admin_1.adminApiCommand);
 // Which models the server accepts. Same source the validator uses, so it cannot drift.
 program
     .command('models')

package/dist/lib/adminApi.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminApi = exports.AdminError = void 0;
+exports.isNotFound = isNotFound;
+exports.adminApi = adminApi;
+exports.normalisePhone = normalisePhone;
+const config_1 = require("./config");
+const adminAuth_1 = require("./adminAuth");
+/**
+ * Client for the internal admin console's API — `https://intadmin.callkaro.ai`
+ * and the `/monitor/*` routes on the backend.
+ *
+ * ## A third credential, interchangeable with neither of the other two
+ *
+ *   | credential   | how it travels | reaches                        |
+ *   |--------------|----------------|--------------------------------|
+ *   | `ck_…`       | bearer         | `/cli/*`                       |
+ *   | dashboard JWT| bearer + cookie| `/auth/*`, `/v1/*`, `/v2/agents/`|
+ *   | `access_token_monitor` | cookie | `/monitor/*`                |
+ *
+ * Each is rejected by the other two's routes. Sending the wrong one produces an
+ * unexplained 401 rather than anything diagnostic, which is why this client
+ * exists as a separate file rather than a flag on `DashboardApi`.
+ *
+ * ## The surface is undocumented
+ *
+ * Every route, query-parameter name and request body below was read out of the
+ * console's own JS bundle and confirmed by probing the live server. Two of them
+ * are misspelled upstream and must be sent exactly as they are:
+ *
+ *   - the recharge body field is `rechargeAmmount` (not `rechargeAmount`)
+ *   - the clients list is `GET /monitor/users/:adminId` — there is no
+ *     `GET /monitor/clients`
+ *
+ * See docs/admin-api.md for the full map, including which routes 403 for which
+ * role.
+ */
+/**
+ * A non-2xx response from the admin API.
+ *
+ * Shaped like `DashboardError` on the dashboard side, so a caller reads
+ * `err.status` the same way on every surface. Extends Error so existing
+ * `handleError` paths and message-based assertions keep working.
+ */
+class AdminError extends Error {
+    status;
+    data;
+    /** `data` is the parsed error body, kept whole for callers (`admin api`) that print it. */
+    constructor(status, message, data) {
+        super(message);
+        this.status = status;
+        this.data = data;
+        this.name = 'AdminError';
+    }
+}
+exports.AdminError = AdminError;
+/** True when the failure was "no such record", as opposed to a real error. */
+function isNotFound(err) {
+    return err instanceof AdminError && err.status === 404;
+}
+class AdminApi {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    /**
+     * One place that adds auth, so no caller can forget it. `requireAdmin()` runs
+     * per request rather than once at construction: it is what proves the stored
+     * 24h session is still valid, and a long-lived client must not outlive it.
+     */
+    async request(method, path, body) {
+        // baseUrl + path is the whole URL, so a path that does not start with "/"
+        // can rewrite the host ("https://backend.callkaro.ai" + "@evil.com/x") and
+        // carry the session cookie with it.
+        if (!path.startsWith('/'))
+            throw new Error(`Admin path must start with "/" (got "${path}").`);
+        const { token } = await (0, adminAuth_1.requireAdmin)();
+        const headers = {
+            'Content-Type': 'application/json',
+            Cookie: `access_token_monitor=${token}`,
+        };
+        let res;
+        try {
+            res = await fetch(`${this.baseUrl}${path}`, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                // A redirect would re-send the cookie to wherever it points.
+                redirect: 'error',
+                signal: AbortSignal.timeout(30_000),
+            });
+        }
+        catch (err) {
+            throw new Error(`Cannot reach ${this.baseUrl} (${err.message})`);
+        }
+        const text = await res.text();
+        let data;
+        try {
+            data = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            data = { msg: text.slice(0, 200) };
+        }
+        if (!res.ok) {
+            // Carry the status, not just the message: a caller that cannot tell 404
+            // from 500 has to treat every failure the same.
+            throw new AdminError(res.status, explain(data?.msg || data?.message || `Request failed (${res.status})`, res.status), data);
+        }
+        return data;
+    }
+    // --- identity -------------------------------------------------------------
+    /** The signed-in admin's own record: name, email, role, isSuperAdmin. */
+    getAdmin() { return this.request('GET', '/monitor/auth/get-admin'); }
+    /**
+     * The client accounts this admin is assigned to.
+     *
+     * There is no `GET /monitor/clients` — the console lists clients through the
+     * *admin's* own user record, whose `users[]` array holds them. The id in
+     * `admin.user._id` is what this route is keyed by.
+     *
+     * Note that `GET /monitor/users/:clientId` is a *different* route and 403s
+     * for a non-superadmin: a client id is not an admin you may read. The client
+     * records come from here, not from there.
+     */
+    myClients(adminId) { return this.request('GET', `/monitor/users/${encodeURIComponent(adminId)}`); }
+    /** The colleagues assigned to a client account. */
+    coworkers(clientId) {
+        return this.request('GET', `/monitor/clients/${encodeURIComponent(clientId)}/coworkers`);
+    }
+    /**
+     * "Login as this user" — the console's impersonation.
+     *
+     * Returns a dashboard JWT with an `actAs` claim. It is **not** a `ck_` token
+     * and reaches no `/cli/*` route; `impersonateClient` in adminAuth.ts turns it
+     * into one.
+     */
+    impersonate(clientId) {
+        return this.request('GET', `/monitor/clients/${encodeURIComponent(clientId)}/impersonate`);
+    }
+    // --- analytics ------------------------------------------------------------
+    //
+    // The user filter is `user_ids` (a csv), not `userIds`. `userIds` is
+    // accepted and answered with "At least one user must be selected", which
+    // reads like a permissions problem rather than a wrong parameter name.
+    /** Call, minute and cost totals per client. */
+    analytics(query = {}) {
+        return this.request('GET', `/monitor/analytics${qs(query)}`);
+    }
+    /** Just the call counts per client. */
+    analyticsCounts(query = {}) {
+        return this.request('GET', `/monitor/analytics/counts${qs(query)}`);
+    }
+    /** Daily / weekly / monthly active users. */
+    analyticsUsage(query = {}) {
+        return this.request('GET', `/monitor/analytics/usage${qs(query)}`);
+    }
+    /** The usage trend over the window. */
+    analyticsTrend(query = {}) {
+        return this.request('GET', `/monitor/analytics/trend${qs(query)}`);
+    }
+    // --- costs ----------------------------------------------------------------
+    // All four need startDate and endDate as YYYY-MM-DD.
+    /** Total and daily cost, broken down by subscription and category. */
+    costs(query = {}) { return this.request('GET', `/monitor/costs${qs(query)}`); }
+    /** Cost per meter. */
+    costsMeters(query = {}) {
+        return this.request('GET', `/monitor/costs/meters${qs(query)}`);
+    }
+    /** Cost per resource group. */
+    costsResourceGroups(query = {}) {
+        return this.request('GET', `/monitor/costs/resource-groups${qs(query)}`);
+    }
+    /** Subscription costs. */
+    costsSubscriptions(query = {}) {
+        return this.request('GET', `/monitor/costs/subscriptions${qs(query)}`);
+    }
+    // --- recharges ------------------------------------------------------------
+    /** Credits and amount added per client, over a window. */
+    rechargeSummary(query = {}) {
+        return this.request('GET', `/monitor/recharges/summary${qs(query)}`);
+    }
+    /** One client's recharge history. */
+    recharges(clientId, query = {}) {
+        return this.request('GET', `/monitor/recharges/${encodeURIComponent(clientId)}${qs(query)}`);
+    }
+    // --- calls ----------------------------------------------------------------
+    //
+    // The search needs exactly one of: to (phone), lead_id, buylead, call_sid,
+    // call_id. Filling more than one narrows the search.
+    /** Look up calls by phone number, lead id, buylead, call sid or call id. */
+    calls(query = {}) { return this.request('GET', `/monitor/calls${qs(query)}`); }
+    // --- bots -----------------------------------------------------------------
+    /** The bots (agent+client pairs) seen over a window. */
+    bots(query = {}) { return this.request('GET', `/monitor/bots${qs(query)}`); }
+    /** Function call statistics per agent. */
+    botFunctions(query = {}) {
+        return this.request('GET', `/monitor/bots/functions${qs(query)}`);
+    }
+    // --- observability --------------------------------------------------------
+    /** Sentry transactions over the last 24h. */
+    sentryTransactions(query = {}) {
+        return this.request('GET', `/monitor/sentry/transactions${qs(query)}`);
+    }
+    /** Sentry queries over the last 24h. */
+    sentryQueries(query = {}) {
+        return this.request('GET', `/monitor/sentry/queries${qs(query)}`);
+    }
+    /** Latency series for one transaction. */
+    sentryLatencySeries(query = {}) {
+        return this.request('GET', `/monitor/sentry/latency-series${qs(query)}`);
+    }
+    /** Clickhouse queries over a range. */
+    metricsQueries(query = {}) {
+        return this.request('GET', `/monitor/metrics/clickhouse-queries${qs(query)}`);
+    }
+    // --- writes ---------------------------------------------------------------
+    //
+    // These act on live client accounts. The console sends an empty object as the
+    // body on every one of them, and the server rejects a missing body, so they
+    // are all sent as `{}`.
+    /** Pause a client account: no more calls dial out for it. */
+    pauseClient(clientId) {
+        return this.request('POST', `/monitor/clients/${encodeURIComponent(clientId)}/pause`, {});
+    }
+    /** Resume a paused client account. */
+    resumeClient(clientId) {
+        return this.request('POST', `/monitor/clients/${encodeURIComponent(clientId)}/resume`, {});
+    }
+    /** Clear a client account's whole call queue. */
+    clearClientQueue(clientId) {
+        return this.request('POST', `/monitor/clients/${encodeURIComponent(clientId)}/clear`, {});
+    }
+    /** Pause one agent of a client account. */
+    pauseAgent(clientId, agentId) {
+        return this.request('POST', `/monitor/clients/${encodeURIComponent(clientId)}/agents/${encodeURIComponent(agentId)}/pause`, {});
+    }
+    /** Resume one agent of a client account. */
+    resumeAgent(clientId, agentId) {
+        return this.request('POST', `/monitor/clients/${encodeURIComponent(clientId)}/agents/${encodeURIComponent(agentId)}/resume`, {});
+    }
+    /** Clear one agent's call queue. */
+    clearAgentQueue(clientId, agentId) {
+        return this.request('POST', `/monitor/clients/${encodeURIComponent(clientId)}/agents/${encodeURIComponent(agentId)}/clear`, {});
+    }
+    /** Clear the console-wide voice cache. */
+    clearVoiceCache() { return this.request('POST', '/monitor/voice-cache/clear', {}); }
+    /**
+     * Add credits to a client account.
+     *
+     * `rechargeAmmount` is the server's own spelling — the typo is upstream, and
+     * sending `rechargeAmount` is a silent no-op at best. The response carries
+     * the updated client as `user`.
+     */
+    recharge(clientId, amount) {
+        return this.request('POST', `/monitor/clients/${encodeURIComponent(clientId)}/recharge`, {
+            rechargeAmmount: amount,
+        });
+    }
+    /**
+     * Update a client account's settings. The console sends only the fields the
+     * form changed, so this is a partial update rather than a replace.
+     */
+    updateClient(clientId, body) {
+        return this.request('PUT', `/monitor/clients/${encodeURIComponent(clientId)}`, body);
+    }
+    /**
+     * Replace or extend the phone numbers on several client accounts at once.
+     *
+     * `mode` is `add` (keep the existing ones) or `replace`. The console
+     * normalises every number to `+` followed by 12 digits and rejects anything
+     * else before it sends, so this method does the same.
+     */
+    bulkUpdatePhoneNumbers(userIds, phoneNumbers, mode = 'replace') {
+        return this.request('PUT', '/monitor/clients/bulk-update-phone-numbers', {
+            userIds,
+            phoneNumbers: phoneNumbers.map(normalisePhone),
+            mode,
+        });
+    }
+}
+exports.AdminApi = AdminApi;
+/** Build a client bound to the configured backend. */
+function adminApi() {
+    return new AdminApi((0, config_1.backendUrl)());
+}
+/**
+ * `+` then 12 digits, the format the console enforces before it sends.
+ * Anything else is a phone number the server will reject.
+ */
+function normalisePhone(raw) {
+    const digits = raw.replace(/[^0-9]/g, '');
+    return `+${digits}`;
+}
+/** `?a=1&b=2`, skipping undefined and empty. Mirrors the one in api.ts. */
+function qs(params) {
+    const parts = Object.entries(params)
+        .filter(([, v]) => v !== undefined && v !== '')
+        .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    return parts.length ? `?${parts.join('&')}` : '';
+}
+/**
+ * Say what a bare "Not Authorized!" actually means.
+ *
+ * The console's 403 is two different things depending on the route. On a
+ * client you do not own it is "This client is not assigned to you" — a
+ * question of which account, and one the CLI can answer. On the write routes
+ * it is a role limit: an FDE may read a client but not change it. The server
+ * says the same two words for both, so the CLI has to name the difference.
+ */
+function explain(message, status) {
+    if (status !== 403)
+        return message;
+    if (/not assigned to you/i.test(message)) {
+        return `${message}\n  The client account must be assigned to your admin user. Run \`cku admin clients\`.`;
+    }
+    if (/not authorized/i.test(message)) {
+        return (`${message}\n` +
+            '  The console role on this account cannot make that change. Reading a client is\n' +
+            '  allowed; changing one (recharge, concurrency, pause, phone numbers) needs a\n' +
+            '  higher role. The account that did the write is a super admin.');
+    }
+    return message;
+}