@myapihq/cli 2.0.1 → 2.1.0

package/dist/commands/billing-auto-recharge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/billing-auto-recharge.test.js

@@ -0,0 +1,103 @@
+// Tests for the auto-recharge client surface: the SDK `withFundsRetry`
+// poll-and-retry helper + the CLI's `autoRechargeSummary` render helper.
+import { describe, it, expect, vi } from 'vitest';
+import { MyApiError, withFundsRetry, isInsufficientFunds, isSpendCapExceeded, autoRechargeState } from '@myapihq/sdk';
+import { autoRechargeSummary } from './billing.js';
+// Build a 402 the way client.ts does — body is the unwrapped `error` object.
+function funds(state, retryAfter) {
+    const body = { code: 'INSUFFICIENT_FUNDS', auto_recharge: state };
+    if (retryAfter != null)
+        body.retry_after_seconds = retryAfter;
+    return new MyApiError('INSUFFICIENT_FUNDS', 402, 'insufficient balance', body);
+}
+const noopSleep = () => Promise.resolve();
+describe('withFundsRetry', () => {
+    it('returns the value when the call succeeds first try (no retry)', async () => {
+        const call = vi.fn().mockResolvedValue('ok');
+        await expect(withFundsRetry(call, { sleep: noopSleep })).resolves.toBe('ok');
+        expect(call).toHaveBeenCalledTimes(1);
+    });
+    it('retries on an in-flight refill, then succeeds', async () => {
+        const call = vi.fn()
+            .mockRejectedValueOnce(funds('in_flight', 0))
+            .mockResolvedValueOnce('ok');
+        const sleep = vi.fn(noopSleep);
+        await expect(withFundsRetry(call, { sleep })).resolves.toBe('ok');
+        expect(call).toHaveBeenCalledTimes(2);
+        expect(sleep).toHaveBeenCalledTimes(1);
+    });
+    it('honors the server retry_after_seconds for the sleep duration', async () => {
+        const call = vi.fn()
+            .mockRejectedValueOnce(funds('in_flight', 7))
+            .mockResolvedValueOnce('ok');
+        const sleep = vi.fn(noopSleep);
+        await withFundsRetry(call, { sleep });
+        expect(sleep).toHaveBeenCalledWith(7000);
+    });
+    it('gives up after maxRetries and rethrows the last error', async () => {
+        const call = vi.fn().mockRejectedValue(funds('in_flight', 0));
+        await expect(withFundsRetry(call, { maxRetries: 2, sleep: noopSleep }))
+            .rejects.toMatchObject({ code: 'INSUFFICIENT_FUNDS' });
+        expect(call).toHaveBeenCalledTimes(3); // initial + 2 retries
+    });
+    it('does NOT retry a capped refill — rethrows immediately (needs a human)', async () => {
+        const call = vi.fn().mockRejectedValue(funds('capped'));
+        await expect(withFundsRetry(call, { sleep: noopSleep })).rejects.toMatchObject({ code: 'INSUFFICIENT_FUNDS' });
+        expect(call).toHaveBeenCalledTimes(1);
+    });
+    it('does NOT retry no_pm / failed / disabled states', async () => {
+        for (const state of ['no_pm', 'failed', 'disabled']) {
+            const call = vi.fn().mockRejectedValue(funds(state));
+            await expect(withFundsRetry(call, { sleep: noopSleep })).rejects.toBeInstanceOf(MyApiError);
+            expect(call).toHaveBeenCalledTimes(1);
+        }
+    });
+    it('does NOT retry a SPEND_CAP_EXCEEDED hard ceiling', async () => {
+        const err = new MyApiError('SPEND_CAP_EXCEEDED', 402, 'cap', { code: 'SPEND_CAP_EXCEEDED', cap_cents: 5000 });
+        const call = vi.fn().mockRejectedValue(err);
+        await expect(withFundsRetry(call, { sleep: noopSleep })).rejects.toBe(err);
+        expect(call).toHaveBeenCalledTimes(1);
+    });
+    it('rethrows non-funds errors untouched', async () => {
+        const err = new Error('network down');
+        const call = vi.fn().mockRejectedValue(err);
+        await expect(withFundsRetry(call, { sleep: noopSleep })).rejects.toBe(err);
+        expect(call).toHaveBeenCalledTimes(1);
+    });
+});
+describe('funds predicates', () => {
+    it('isInsufficientFunds matches both new and legacy codes', () => {
+        expect(isInsufficientFunds(funds('disabled'))).toBe(true);
+        expect(isInsufficientFunds(new MyApiError('INSUFFICIENT_BALANCE', 402, 'x', {}))).toBe(true);
+        expect(isInsufficientFunds(new MyApiError('SPEND_CAP_EXCEEDED', 402, 'x', {}))).toBe(false);
+        expect(isInsufficientFunds(new Error('x'))).toBe(false);
+    });
+    it('isSpendCapExceeded + autoRechargeState read the right fields', () => {
+        expect(isSpendCapExceeded(new MyApiError('SPEND_CAP_EXCEEDED', 402, 'x', {}))).toBe(true);
+        expect(autoRechargeState(funds('in_flight'))).toBe('in_flight');
+        expect(autoRechargeState(new Error('x'))).toBeUndefined();
+    });
+});
+describe('autoRechargeSummary', () => {
+    const base = {
+        enabled: true, threshold_cents: 500, amount_cents: 2000, monthly_cap_cents: 10000,
+        month_to_date_recharged_cents: 4000, has_payment_method: true,
+        last_recharge_status: 'succeeded', last_recharge_attempt_at: null,
+    };
+    it('returns null when disabled', () => {
+        expect(autoRechargeSummary({ ...base, enabled: false })).toBeNull();
+    });
+    it('summarizes an enabled config with dollar amounts', () => {
+        const s = autoRechargeSummary(base);
+        expect(s).toContain('$5.00');
+        expect(s).toContain('$20.00');
+        expect(s).toContain('$40.00'); // month-to-date
+        expect(s).toContain('$100.00'); // cap
+    });
+    it('flags a failed/capped status but not a healthy/pending one', () => {
+        expect(autoRechargeSummary({ ...base, last_recharge_status: 'failed' })).toContain('⚠ failed');
+        expect(autoRechargeSummary({ ...base, last_recharge_status: 'capped' })).toContain('⚠ capped');
+        expect(autoRechargeSummary({ ...base, last_recharge_status: 'pending' })).not.toContain('⚠');
+        expect(autoRechargeSummary(base)).not.toContain('⚠');
+    });
+});

package/dist/commands/billing.d.ts

@@ -1,3 +1,4 @@
+import { hq } from '@myapihq/sdk';
 import type { FlagSchema } from '../flags.js';
 import type { Flags } from '../helpers.js';
 import type { Exposes } from '../exposes.js';
@@ -9,4 +10,6 @@ export declare function history(flags: Flags): Promise<void>;
 export declare function usage(flags: Flags): Promise<void>;
 export declare function topup(amountStr: string, flags: Flags): Promise<void>;
 export declare function setup(_flags: Flags): Promise<void>;
+export declare function autoRechargeSummary(cfg: hq.AutoRechargeConfig): string | null;
+export declare function autoRecharge(action: string | undefined, flags: Flags): Promise<void>;
 export declare function spendCap(arg: string | undefined, flags: Flags): Promise<void>;

package/dist/commands/billing.js

@@ -5,6 +5,9 @@ import { confirm, isNonInteractive } from '../prompt.js';
 import { formatDate } from '../utils.js';
 export const SCHEMA = {
     period: 'string', // spend-cap window: month | day
+    threshold: 'string', // auto-recharge: refill when balance drops below ($)
+    amount: 'string', // auto-recharge: how much to refill each time ($)
+    'monthly-cap': 'string', // auto-recharge: max auto-recharged per month ($)
 };
 export const EXPOSES = [
     'GET /hq/billing/balance',
@@ -14,8 +17,26 @@ export const EXPOSES = [
     'POST /hq/billing/topup',
     'GET /hq/account/me',
     'PATCH /hq/account/spend-cap',
+    'GET /hq/billing/auto-recharge',
+    'PUT /hq/billing/auto-recharge',
+    'DELETE /hq/billing/auto-recharge',
 ];
 const SUBCOMMAND_USAGE = {
+    'auto-recharge': `myapi billing auto-recharge [show | set | disable]
+
+Keep the prepaid wallet funded without a human in the loop: when the balance
+drops below the threshold, MyAPI charges your saved card to refill it, bounded
+by a monthly cap. Off by default; enabling needs a payment method on file.
+
+  myapi billing auto-recharge                 Show current config + status
+  myapi billing auto-recharge set \\
+      --threshold 5 --amount 20 --monthly-cap 100
+                                              Refill to keep ≥$5, $20 at a time,
+                                              up to $100/month
+  myapi billing auto-recharge disable         Turn off (settings are kept)
+
+Amounts are whole dollars. The refill amount must be ≥ $5 and ≥ the threshold;
+the monthly cap must be ≥ the refill amount.`,
     'balance': 'myapi billing balance [--json]',
     'history': 'myapi billing history [--json]',
     'usage': `myapi billing usage [--period month|30d] [--json]
@@ -48,6 +69,7 @@ export async function run(subcommand, args, flags) {
         info(`Usage: myapi billing <subcommand>
 
 Subcommands:
+  auto-recharge  Keep the wallet funded automatically (show/set/disable)
   balance    Check balance, credits, and payment method status
   history    View recent transactions and top-ups
   setup      Open a checkout link to add or update payment method
@@ -71,6 +93,7 @@ Subcommands:
         case 'topup': return topup(args[0], flags);
         case 'setup': return setup(flags);
         case 'spend-cap': return spendCap(args[0], flags);
+        case 'auto-recharge': return autoRecharge(args[0], flags);
         default: error(`Unknown subcommand: ${subcommand}. Run "myapi billing --help" for available subcommands.`);
     }
 }
@@ -165,6 +188,98 @@ export async function setup(_flags) {
     const result = await hq.setupPayment(config.api_key);
     success(`Open this URL in your browser to set up payment:\n${result.url}`);
 }
+function fmtCents(c) {
+    return c == null ? '—' : `$${(c / 100).toFixed(2)}`;
+}
+// One-line summary of auto-recharge state, reused by `billing auto-recharge`
+// and `status`. Returns null when off (callers decide whether to show "off").
+export function autoRechargeSummary(cfg) {
+    if (!cfg.enabled)
+        return null;
+    let s = `on — refill to ≥ ${fmtCents(cfg.threshold_cents)}, ${fmtCents(cfg.amount_cents)} each (${fmtCents(cfg.month_to_date_recharged_cents)}/${fmtCents(cfg.monthly_cap_cents)} this month)`;
+    if (cfg.last_recharge_status && cfg.last_recharge_status !== 'succeeded' && cfg.last_recharge_status !== 'pending') {
+        s += `  ⚠ ${cfg.last_recharge_status}`;
+    }
+    return s;
+}
+const RECHARGE_STATUS_HINT = {
+    failed: 'last refill was declined — check your card: myapi billing setup',
+    capped: 'monthly cap reached — refills paused until next month, or raise --monthly-cap',
+    no_pm: 'no payment method — add one: myapi billing setup',
+    pending: 'a refill is in progress',
+};
+function renderAutoRecharge(cfg) {
+    if (!cfg.enabled) {
+        info('Auto-recharge: off');
+        info(`  Payment method on file: ${cfg.has_payment_method ? 'yes' : 'no'}`);
+        info('  Enable with: myapi billing auto-recharge set --threshold <$> --amount <$> --monthly-cap <$>');
+        if (!cfg.has_payment_method)
+            info('  (add a payment method first: myapi billing setup)');
+        return;
+    }
+    info('Auto-recharge: on');
+    info(`  Refill to keep balance ≥ ${fmtCents(cfg.threshold_cents)}, adding ${fmtCents(cfg.amount_cents)} each time`);
+    info(`  Monthly cap: ${fmtCents(cfg.month_to_date_recharged_cents)} of ${fmtCents(cfg.monthly_cap_cents)} used this month`);
+    info(`  Payment method on file: ${cfg.has_payment_method ? 'yes' : 'no'}`);
+    if (cfg.last_recharge_status && cfg.last_recharge_status !== 'succeeded') {
+        const hint = RECHARGE_STATUS_HINT[cfg.last_recharge_status];
+        info(`  ⚠ Status: ${cfg.last_recharge_status}${hint ? ` — ${hint}` : ''}`);
+    }
+}
+// Keep the wallet funded without a human. No arg / "show" → display config;
+// "set" → enable/update from --threshold/--amount/--monthly-cap (whole
+// dollars); "disable" → turn off (settings preserved for easy re-enable).
+export async function autoRecharge(action, flags) {
+    const config = requireConfig();
+    const act = action ?? 'show';
+    if (act === 'show') {
+        const cfg = await hq.getAutoRecharge(config.api_key);
+        if (flags.json) {
+            printJson(cfg);
+            return;
+        }
+        renderAutoRecharge(cfg);
+        return;
+    }
+    if (act === 'disable') {
+        await hq.disableAutoRecharge(config.api_key);
+        success('Auto-recharge disabled. Your threshold/amount/cap are kept — re-enable with: myapi billing auto-recharge set');
+        return;
+    }
+    if (act === 'set') {
+        const dollarsToCents = (v, name) => {
+            if (v == null)
+                return undefined;
+            const n = Number(v);
+            if (!Number.isFinite(n) || n < 0) {
+                error(`Invalid --${name} "${v}". Use a whole dollar amount (e.g. --${name} 20).`);
+            }
+            return Math.round(n * 100);
+        };
+        const input = { enabled: true };
+        const threshold = dollarsToCents(flags.threshold, 'threshold');
+        const amount = dollarsToCents(flags.amount, 'amount');
+        const cap = dollarsToCents(flags['monthly-cap'], 'monthly-cap');
+        if (threshold != null)
+            input.threshold_cents = threshold;
+        if (amount != null)
+            input.amount_cents = amount;
+        if (cap != null)
+            input.monthly_cap_cents = cap;
+        // The backend enforces the invariants (≥$5 floor, amount ≥ threshold,
+        // cap ≥ amount, payment method present) and returns a 400 the top-level
+        // handler renders — no need to duplicate that validation here.
+        const cfg = await hq.setAutoRecharge(config.api_key, input);
+        if (flags.json) {
+            printJson(cfg);
+            return;
+        }
+        success('Auto-recharge enabled.');
+        renderAutoRecharge(cfg);
+        return;
+    }
+    error(`Unknown action "${act}". Use: myapi billing auto-recharge [show | set | disable]`);
+}
 // The account-level spend ceiling. No arg → show; "clear" → remove; a
 // dollar amount → set. Distinct from per-key caps (myapi keys create
 // --spend-cap): this is the aggregate backstop across the whole account.

package/dist/commands/doctor-setup.test.js

@@ -3,7 +3,7 @@
 // `domains` or `emails` sections come back empty (zero-state), the
 // `setup` augmentation should escalate to actionable warns.
 import { describe, it, expect } from 'vitest';
-import { _setupSection } from './doctor.js';
+import { _setupSection, sanitizeHint, _tallyTotals } from './doctor.js';
 function mkReport(sections) {
     return {
         org_id: 'org-test',
@@ -20,6 +20,12 @@ function populated(name) {
                 id: 'x', severity: 'ok', scope: name, message: 'something',
             }] };
 }
+// A section the backend reports as having resources, but with no issues
+// emitted (all healthy, no per-resource ok rows). The issue-count proxy
+// would mis-read this as zero-state; `resource_count` must win.
+function healthyQuiet(name, count) {
+    return { name, summary: 'all checks passed', issues: [], resource_count: count };
+}
 describe('_setupSection', () => {
     it('returns null when both domains + emails sections are populated', () => {
         expect(_setupSection(mkReport([populated('domains'), populated('emails')]))).toBeNull();
@@ -71,4 +77,83 @@ describe('_setupSection', () => {
         const s = _setupSection(mkReport([populated('domains'), populated('emails')]), { mailingAddress: undefined });
         expect(s).toBeNull();
     });
+    // resource_count is authoritative — it must override the fragile
+    // issues.length proxy in both directions.
+    it('does NOT flag a healthy-but-quiet domains section (resource_count > 0, no issues)', () => {
+        // The bug class this prevents: backend stops emitting per-domain `ok`
+        // rows → issues:[] → proxy would falsely say "No domain registered".
+        const s = _setupSection(mkReport([healthyQuiet('domains', 2), healthyQuiet('emails', 1)]));
+        expect(s).toBeNull();
+    });
+    it('flags zero-state via resource_count even if an issue happens to be present', () => {
+        const domains = {
+            name: 'domains', summary: 'x', resource_count: 0,
+            issues: [{ id: 'y', severity: 'ok', scope: 'domains', message: 'stale ok row' }],
+        };
+        const s = _setupSection(mkReport([domains, populated('emails')]));
+        expect(s).not.toBeNull();
+        expect(s.issues).toHaveLength(1);
+        expect(s.issues[0].scope).toBe('setup/domain');
+    });
+    it('falls back to the issue-count proxy when resource_count is absent', () => {
+        // Older backend: no resource_count → empty section still reads as zero-state.
+        const s = _setupSection(mkReport([empty('domains'), populated('emails')]));
+        expect(s.issues[0].scope).toBe('setup/domain');
+    });
+});
+describe('sanitizeHint', () => {
+    it('drops a hint referencing an internal docs/ artifact', () => {
+        expect(sanitizeHint('see docs/security-debt-pixel-hypersearch-2026-05-27.md item #2 for the fix')).toBeUndefined();
+    });
+    it('drops a hint referencing an internal code path', () => {
+        expect(sanitizeHint('fix in internal/routes/billing/billing.go')).toBeUndefined();
+        expect(sanitizeHint('see packages/cli/src/commands/doctor.ts')).toBeUndefined();
+    });
+    it('keeps actionable command hints unchanged', () => {
+        const cmd = 'Create one with: myapi email mailbox create <username>@<your-domain>';
+        expect(sanitizeHint(cmd)).toBe(cmd);
+        expect(sanitizeHint('attach a workflow if you want a notification on each submission'))
+            .toBe('attach a workflow if you want a notification on each submission');
+    });
+    it('does not false-match a bare word with a dotted suffix (no slash)', () => {
+        // "node.js" / "data.object" have no path slash → not an internal artifact.
+        expect(sanitizeHint('deploy your node.js app')).toBe('deploy your node.js app');
+    });
+    it('passes through undefined', () => {
+        expect(sanitizeHint(undefined)).toBeUndefined();
+    });
+});
+describe('_tallyTotals', () => {
+    function sec(name, issues) {
+        return {
+            name, summary: '', issues: issues.map((i, n) => ({
+                id: `${name}-${n}`, severity: 'warn', scope: name, message: 'm', ...i,
+            })),
+        };
+    }
+    it('counts plain severities', () => {
+        const t = _tallyTotals([sec('a', [{ severity: 'crit' }, { severity: 'warn' }, { severity: 'ok' }])]);
+        expect(t).toEqual({ ok: 1, warn: 1, crit: 1, operator: 0 });
+    });
+    it('pulls an operator_only critical OUT of crit and into operator', () => {
+        // The pixel case: a platform-side critical must not count as a customer
+        // critical (so it won't set exit code 1).
+        const t = _tallyTotals([sec('pixel', [{ severity: 'crit', operator_only: true }])]);
+        expect(t.crit).toBe(0);
+        expect(t.operator).toBe(1);
+    });
+    it('pulls an operator_only warning into operator too', () => {
+        const t = _tallyTotals([sec('x', [{ severity: 'warn', operator_only: true }, { severity: 'warn' }])]);
+        expect(t.warn).toBe(1);
+        expect(t.operator).toBe(1);
+    });
+    it('still counts a real customer critical alongside an operator_only one', () => {
+        const t = _tallyTotals([sec('x', [{ severity: 'crit' }, { severity: 'crit', operator_only: true }])]);
+        expect(t.crit).toBe(1); // exit code WILL be 1 — there's a real one
+        expect(t.operator).toBe(1);
+    });
+    it('treats an operator_only ok row as a passing check, not an operator issue', () => {
+        const t = _tallyTotals([sec('x', [{ severity: 'ok', operator_only: true }])]);
+        expect(t).toEqual({ ok: 1, warn: 0, crit: 0, operator: 0 });
+    });
 });

package/dist/commands/doctor.d.ts

@@ -4,6 +4,14 @@ import { type Flags } from '../helpers.js';
 import type { Exposes } from '../exposes.js';
 export declare const EXPOSES: Exposes;
 export declare const SCHEMA: FlagSchema;
+export interface DoctorTotals {
+    ok: number;
+    warn: number;
+    crit: number;
+    operator: number;
+}
+export declare function _tallyTotals(sections: sdkHq.DoctorSection[]): DoctorTotals;
+export declare function sanitizeHint(hint: string | undefined): string | undefined;
 export interface SetupContext {
     mailingAddress?: string | null;
 }

package/dist/commands/doctor.js

@@ -41,6 +41,33 @@ const MARK = {
     warn: `${C.warn}⚠${C.reset}`,
     crit: `${C.err}✗${C.reset}`,
 };
+// Operator-only issues are platform-side and not the customer's to fix. Render
+// them with a distinct, non-alarming marker so they don't read as a failure the
+// customer must act on — regardless of the backend severity.
+const OPERATOR_MARK = `${C.dim}ℹ${C.reset}`;
+// Tally issues for the exit code + summary. `operator_only` warn/crit issues
+// are pulled into their own `operator` bucket and OUT of crit/warn: a
+// platform-side problem the customer can't fix must not fail their `doctor`
+// run (exit 1) or inflate their critical count. Everything else tallies by
+// severity as before; any ok row (operator or not) counts as ok.
+export function _tallyTotals(sections) {
+    const t = { ok: 0, warn: 0, crit: 0, operator: 0 };
+    for (const s of sections) {
+        for (const i of s.issues) {
+            if (i.severity === 'crit' || i.severity === 'warn') {
+                if (i.operator_only)
+                    t.operator++;
+                else
+                    t[i.severity]++;
+            }
+            else if (i.severity === 'ok') {
+                t.ok++;
+            }
+            // Unknown severities the backend might invent are ignored (no NaN).
+        }
+    }
+    return t;
+}
 function rule(width = 60) {
     return `${C.dim}${'─'.repeat(width)}${C.reset}`;
 }
@@ -51,14 +78,43 @@ function rule(width = 60) {
 function localIssueId(kind, key) {
     return `${kind}/${createHash('sha256').update(key).digest('hex').slice(0, 16)}`;
 }
+// Backend hints are sometimes written for operators, not customers — e.g.
+// "see docs/security-debt-pixel-hypersearch-2026-05-27.md item #2 for the fix".
+// A reference to an internal repo artifact (a file path with a doc/code
+// extension, or anything under `docs/`) is useless to — and leaks internals
+// at — the customer running `myapi doctor`. Drop the hint entirely in that
+// case: the issue's `message` still conveys what's wrong; a hint that points
+// nowhere the user can go is worse than no hint. (Root fix is backend-side
+// hint hygiene — see docs/cross-repo-prompts/backend-doctor-quality-*.md.)
+const INTERNAL_ARTIFACT_RE = /\bdocs\/[\w.\-/]+|\b[\w.\-]+\/[\w.\-/]*\.(?:md|go|tsx?|jsx?|json|ya?ml|sql)\b/i;
+export function sanitizeHint(hint) {
+    if (!hint)
+        return undefined;
+    return INTERNAL_ARTIFACT_RE.test(hint) ? undefined : hint;
+}
 function fmtIssue(i) {
     // Prefix the entity name so sibling issues with identical messages
     // (e.g. four "domain is active" rows) are distinguishable. Skip it when
     // the message already names the entity — the local DNS section does.
     const name = i.entity?.name;
     const label = name && !i.message.includes(name) ? `${C.bold}${name}${C.reset} — ` : '';
-    const head = `  ${MARK[i.severity] ?? '·'} ${label}${i.message}`;
-    return i.hint ? `${head}\n    ${C.dim}→ ${i.hint}${C.reset}` : head;
+    const mark = i.operator_only ? OPERATOR_MARK : (MARK[i.severity] ?? '·');
+    const head = `  ${mark} ${label}${i.message}`;
+    const hint = sanitizeHint(i.hint);
+    return hint ? `${head}\n    ${C.dim}→ ${hint}${C.reset}` : head;
+}
+// "Does this section's org have zero resources of its kind?" Prefer the
+// backend's authoritative `resource_count` when present; fall back to the
+// issue-count proxy only for older backends that omit it. The proxy is
+// fragile — it reads "section emitted no issues" as "no resources", which
+// holds today only because the backend emits an `ok` row per healthy
+// resource. The moment a section returns `issues: []` for an all-healthy
+// org, the proxy would mis-fire (e.g. "No domain registered" for an org
+// that has a live domain). `resource_count` removes that coupling.
+function isZeroState(section) {
+    if (typeof section.resource_count === 'number')
+        return section.resource_count === 0;
+    return section.issues.length === 0;
 }
 export function _setupSection(report, ctx = {}) {
     const byName = new Map();
@@ -66,7 +122,7 @@ export function _setupSection(report, ctx = {}) {
         byName.set(s.name, s);
     const issues = [];
     const dom = byName.get('domains');
-    if (dom && dom.issues.length === 0) {
+    if (dom && isZeroState(dom)) {
         issues.push({
             id: localIssueId('setup_no_domain', report.org_id),
             severity: 'warn',
@@ -77,7 +133,7 @@ export function _setupSection(report, ctx = {}) {
         });
     }
     const em = byName.get('emails');
-    if (em && em.issues.length === 0) {
+    if (em && isZeroState(em)) {
         issues.push({
             id: localIssueId('setup_no_mailbox', report.org_id),
             severity: 'warn',
@@ -283,18 +339,12 @@ export async function run(_subcommand, _args, flags) {
     const reachSection = await httpProbeSection(apiKey, orgId);
     if (reachSection)
         report.sections.push(reachSection);
-    // Re-tally totals after local augmentation.
-    const totals = { ok: 0, warn: 0, crit: 0 };
-    for (const s of report.sections) {
-        for (const i of s.issues) {
-            // Ignore any severity the backend invents that we don't model — better
-            // a missed count than a NaN poisoning the whole tally.
-            if (i.severity in totals)
-                totals[i.severity]++;
-        }
-    }
+    // Re-tally totals after local augmentation. `operator_only` issues land in
+    // their own bucket and out of crit/warn (see _tallyTotals).
+    const totals = _tallyTotals(report.sections);
     // Set the exit code before any output branch — CI relies on it in both
-    // the human and the --json path.
+    // the human and the --json path. Only customer-actionable criticals fail
+    // the run; a platform-side (operator_only) critical does not.
     if (totals.crit)
         process.exitCode = 1;
     if (wantJson) {
@@ -322,6 +372,11 @@ export async function run(_subcommand, _args, flags) {
     else {
         info(`${MARK.ok} ${totals.ok} check${totals.ok === 1 ? '' : 's'} passed`);
     }
+    // Platform-side issues are surfaced for transparency but don't count against
+    // the org or fail the run — make that explicit.
+    if (totals.operator) {
+        info(`${OPERATOR_MARK} ${C.dim}${totals.operator} platform-side issue${totals.operator === 1 ? '' : 's'} the MyAPI team is handling (not counted against your org)${C.reset}`);
+    }
     if (!verbose)
         info(`${C.dim}(--verbose to show passing checks · --json for machine-readable)${C.reset}`);
 }

package/dist/commands/status.js

@@ -3,9 +3,11 @@ import { hq, domain, funnel, webhook, workflow, MyApiError } from '@myapihq/sdk'
 // filter, so there is no global "all mailboxes in this org" call. Use
 // `myapi email mailbox list --domain <d>` for per-domain detail.
 import { loadConfig } from '../config.js';
+import { autoRechargeSummary } from './billing.js';
 import { info, error, printJson } from '../output.js';
 export const EXPOSES = [
     'GET /hq/billing/balance',
+    'GET /hq/billing/auto-recharge',
     'GET /hq/account/free-tier',
     'GET /domain/orgs/{org_id}/list',
     'GET /funnel/orgs/{org_id}/funnels',
@@ -44,8 +46,10 @@ export async function run(_subcommand, _args, flags = {}) {
     const accountResults = await Promise.allSettled([
         hq.getBalance(config.api_key),
         hq.getFreeTier(config.api_key),
+        hq.getAutoRecharge(config.api_key),
     ]);
     const balance = unwrap(accountResults[0]);
+    const autoR = unwrap(accountResults[2]);
     // The backend currently returns an array of { service, used, allowance }
     // per-service entries. The SDK type lies about this (claims scalar) — same
     // bug surfaces in `whoami`. Treat as unknown here and narrow at render time.
@@ -78,6 +82,7 @@ export async function run(_subcommand, _args, flags = {}) {
                 key_rejected: keyRejected,
             },
             balance,
+            auto_recharge: autoR,
             free_tier: freeTier,
             org_resources: orgKnown ? {
                 domains, funnels, webhooks, workflows,
@@ -100,6 +105,13 @@ export async function run(_subcommand, _args, flags = {}) {
     if (config.is_anonymous) {
         info('          → Link an email to unlock $5 free credit + paid actions: myapi account link <email>');
     }
+    // Auto-recharge: only worth a line when it's on (or off but a refill recently
+    // failed/capped and needs attention).
+    if (autoR) {
+        const summary = autoRechargeSummary(autoR);
+        if (summary)
+            info(`Recharge: ${summary}`);
+    }
     if (Array.isArray(freeTier) && freeTier.length > 0) {
         const parts = freeTier
             .filter((e) => e && typeof e.service === 'string')

package/dist/index.js

@@ -296,19 +296,40 @@ async function main() {
             if (err.status === 401)
                 error('Invalid API key. Run: myapi account setup');
             else if (err.status === 402) {
+                const body = (err.body ?? {});
                 if (err.code === 'REGISTRATION_REQUIRED' || err.code === 'UPGRADE_REQUIRED')
                     error('A verified email is required. Run: myapi account link');
                 else if (err.code === 'NO_PAYMENT_METHOD')
                     error('No payment method on file. Run: myapi billing setup');
+                else if (err.code === 'SPEND_CAP_EXCEEDED') {
+                    // A self-imposed ceiling, NOT an empty wallet — topping up won't
+                    // help. Point at the cap, not the balance.
+                    const cap = typeof body.cap_cents === 'number' ? `$${(body.cap_cents / 100).toFixed(2)}` : 'your cap';
+                    const spent = typeof body.spent_cents === 'number' ? `$${(body.spent_cents / 100).toFixed(2)} of ` : '';
+                    const period = typeof body.period === 'string' ? body.period : 'period';
+                    error(`Spend cap reached (${spent}${cap} this ${period}). This is a ceiling you set, not an empty wallet — raise or clear it: myapi billing spend-cap`);
+                }
                 else {
-                    // Anonymous accounts can't top up (no payment surface). The
-                    // natural unblock is to link an email — the upgrade grants the
-                    // free credit and opens the paid surface.
+                    // INSUFFICIENT_FUNDS (or legacy INSUFFICIENT_BALANCE): empty wallet.
+                    // Tailor the unblock to the auto-recharge state the backend reports
+                    // so an agent knows whether to wait, fix a card, or top up.
+                    const state = body.auto_recharge;
                     const cfg = loadConfig();
-                    if (cfg?.is_anonymous) {
-                        error('Insufficient balance. Anonymous accounts have no free credit — link an email to unlock $5: myapi account link <email>');
+                    if (state === 'in_flight') {
+                        const secs = typeof body.retry_after_seconds === 'number' ? body.retry_after_seconds : 5;
+                        error(`Wallet empty — auto-recharge is in flight; retry in ~${secs}s.`);
                     }
-                    error('Insufficient balance. Run: myapi billing topup <amount>');
+                    else if (state === 'capped')
+                        error('Wallet empty and auto-recharge hit your monthly cap. Raise it: myapi billing auto-recharge set --monthly-cap <amount>, or top up: myapi billing topup <amount>');
+                    else if (state === 'failed')
+                        error('Wallet empty and the last auto-recharge was declined. Fix your card: myapi billing setup, or top up: myapi billing topup <amount>');
+                    else if (state === 'no_pm')
+                        error('Wallet empty and auto-recharge has no payment method. Add one: myapi billing setup, or top up: myapi billing topup <amount>');
+                    // Anonymous accounts can't top up (no payment surface) — link to unlock.
+                    else if (cfg?.is_anonymous)
+                        error('Insufficient balance. Anonymous accounts have no free credit — link an email to unlock $5: myapi account link <email>');
+                    else
+                        error('Insufficient balance. Top up: myapi billing topup <amount> — or keep it funded automatically: myapi billing auto-recharge set');
                 }
             }
             else

package/dist/skills/my-api-hq/README.md

@@ -8,6 +8,7 @@ Core identity and billing hub for the MyAPI ecosystem. **Start here** — every
 - API key creation and management
 - Organization management (`org_id` used by all other services)
 - Balance top-up and billing history
+- Org-wide health check (`myapi doctor`)
 
 ## Quickstart
 

package/dist/skills/my-api-hq/SKILL.md

@@ -3,7 +3,7 @@ name: my-api-hq
 version: 1.0.0
 description: >
   Auth, organizations, and billing hub. Start here to get an api_key and org_id — every other service depends on both.
-triggers: [api key, account, organization, org, billing, balance, topup, credits, setup, defaults, brand, sync brand]
+triggers: [api key, account, organization, org, billing, balance, topup, credits, setup, defaults, brand, sync brand, doctor, health check, is my org healthy]
 checksum: sha256-pending
 ---
 
@@ -30,7 +30,11 @@ Two tiers, chosen at setup time:
 - **Anonymous** (`myapi account setup --anonymous`): zero-friction account creation. **Starts with $0 credit.** Good for catalog browsing, reading help, inspecting schemas — nothing that costs upstream money. The agent-onboarding path: provisions an account in one call, no email needed.
 - **Registered** (verified email via `myapi account link <email>`): unlocks $5 free credit and the paid surface (LLM, image, email, domain register, etc.). Required for `myapi billing setup` and anything that hits Stripe.
 
-An anonymous account can upgrade at any time via `myapi account link <email>` — the credit grants on successful verification. Anonymous accounts that need paid actions hit a friendly `INSUFFICIENT_BALANCE` or `REGISTRATION_REQUIRED` error pointing at `myapi account link`.
+An anonymous account can upgrade at any time via `myapi account link <email>` — the credit grants on successful verification. Anonymous accounts that need paid actions hit a friendly `REGISTRATION_REQUIRED` error pointing at `myapi account link`; a registered account with an empty wallet hits `402 INSUFFICIENT_FUNDS` (top up, or enable auto-recharge — below).
+
+### Health check
+
+`myapi doctor` runs an org-wide consistency check across every slot (funnels, webhooks, domains, containers, workflows, emails, payments) and layers on customer-perspective DNS/HTTP probes from your machine. It returns per-section findings (`✓` pass / `⚠` warning / `✗` critical) with remediation hints; add `--json` for machine output. The exit code is non-zero **only** on customer-actionable criticals — platform-side issues the MyAPI team is already handling are surfaced with an `ℹ` marker but don't fail the run. Run it to self-check before building (is the org set up?) and after (did everything wire up?).
 <!-- llm:end -->
 
 ## Commands
@@ -53,9 +57,11 @@ An anonymous account can upgrade at any time via `myapi account link <email>`
 | `myapi billing history` | Recent transactions |
 | `myapi billing usage [--period month|30d]` | Spend rolled up by service (this month, or trailing 30d) |
 | `myapi billing spend-cap [<amount> | clear] [--period month|day]` | Set/show/clear the account-level spend ceiling (IAM Layer 2) |
+| `myapi billing auto-recharge [show \| set \| disable]` | Keep the wallet funded automatically — off-session refill when balance drops below a threshold, bounded by a monthly cap |
 | `myapi account mailing-address ["<address>"]` | Get or set the account's CAN-SPAM mailing address (required for email send) |
 | `myapi config set-org <id>` / `set-funnel <id>` / `set-domain <name>` | Set CLI defaults |
 | `myapi install-skills` | Install agent skill files into ~/.claude/, ~/.gemini/, ~/.cursor/ |
+| `myapi doctor [--verbose] [--json]` | Org-wide health check: per-slot config/integrity findings + DNS/HTTP probes |
 <!-- generated:end -->
 
 ## Examples
@@ -70,6 +76,10 @@ myapi account whoami           # confirm what's active
 myapi billing balance       # before doing anything that costs credits
 myapi billing topup 20      # add $20
 
+# For unattended/autonomous runs: keep the wallet funded so a 402 never
+# stalls the agent. Refill to ≥$5, $20 at a time, up to $100/month.
+myapi billing auto-recharge set --threshold 5 --amount 20 --monthly-cap 100
+
 # Sync brand info from an existing website
 myapi org sync-brand acme.com
 
@@ -77,7 +87,7 @@ myapi org sync-brand acme.com
 myapi account switch 2
 ```
 
-If any service returns `402`, run `myapi billing balance` and top up before retrying.
+If any service returns `402 INSUFFICIENT_FUNDS`, top up (`myapi billing topup`) — or enable `myapi billing auto-recharge` so it refills itself. A `402 SPEND_CAP_EXCEEDED` is different: you hit a spend ceiling you set, so raise it with `myapi billing spend-cap` rather than topping up.
 
 Each org gets a free preview subdomain (`*.makeautonomous.com`) usable before registering a custom domain.
 <!-- llm:end -->

package/dist/skills/my-auth-api/SKILL.md

@@ -109,4 +109,4 @@ myapi auth client list
   be retrieved later — store it immediately. SPA clients have no secret.
 - Redirect URIs are matched exactly: absolute `https://…` (or
   `http://localhost…` for local dev).
-- `402` errors mean insufficient credits — run `myapi billing topup <amount>`.
+- `402 INSUFFICIENT_FUNDS` = empty wallet → `myapi billing topup <amount>` (or keep it funded automatically: `myapi billing auto-recharge set`). `402 SPEND_CAP_EXCEEDED` = you hit your account spend ceiling → raise it with `myapi billing spend-cap`.

package/dist/skills/my-domain-api/SKILL.md

@@ -114,6 +114,6 @@ Set `essentially_off` + `browser-check=off` to allow AI crawlers and training bo
 
 - `register`, `renew`, `assign`, and `unassign` always require an explicit domain argument — they don't fall back to a stored default, to prevent accidental destructive actions.
 - All commands default to `--org` from your saved config (set with `myapi config set-org <id>`).
-- `402` errors mean insufficient credits — run `myapi billing topup <amount>`.
+- `402 INSUFFICIENT_FUNDS` = empty wallet → `myapi billing topup <amount>` (or keep it funded automatically: `myapi billing auto-recharge set`). `402 SPEND_CAP_EXCEEDED` = you hit your account spend ceiling → raise it with `myapi billing spend-cap`.
 
 Run `myapi domain --help` or `myapi domain <subcommand> --help` for full flag reference.

package/dist/skills/my-email-api/README.md

@@ -1,7 +1,7 @@
 ---
 # my-email-api
 
-Send transactional email and run drip campaigns from mailboxes on your own registered domains. Includes AI template generation, warmup, and inbox/outbox reading.
+Send transactional email from mailboxes on your own registered domains. Includes AI template generation, warmup, and inbox/outbox reading.
 
 ## What it does
 
@@ -9,7 +9,6 @@ Send transactional email and run drip campaigns from mailboxes on your own regis
 - Send transactional emails (one-shot or templated)
 - Read inbox, outbox, sent history, and per-message status
 - Generate HTML email templates with AI from a prompt
-- Run paced drip campaigns against uploaded contact lists
 - Manage IP/domain warmup for sender reputation
 
 ## Quickstart
@@ -36,7 +35,7 @@ export MYAPI_KEY=mak_...
 Requires:
 - An `api_key` from **myapihq**
 - A registered domain via **mydomainapi**, assigned to your org
-- Default `org_id` (for templates/campaigns) — set with `myapi account config set-org <id>`
+- Default `org_id` (for templates) — set with `myapi account config set-org <id>`
 
 ## Documentation
 

package/dist/skills/my-funnel-api/SKILL.md

@@ -115,6 +115,6 @@ myapi funnel form <funnel_id> --slug survey \
 - Set defaults with `myapi config set-org <id>` and `myapi config set-funnel <id>` to skip flags on every command — but a stale default is exactly how a push lands on the wrong org/funnel. For demos and one-offs, pass `--org`/`--funnel` explicitly instead of relying on whatever default was set last.
 - `push` (any slug) and `publish --env prod` overwrite live content and are refused without `--force` when something already exists at the target. `--force` means "yes, replace the live page/site" — confirm you're aimed at the right `(org, funnel, slug)` before using it, don't use it to silence the error.
 - Deleting a funnel purges all its edge pages immediately.
-- `402` errors mean insufficient credits — run `myapi billing topup <amount>`.
+- `402 INSUFFICIENT_FUNDS` → top up (`myapi billing topup`) or enable `myapi billing auto-recharge`.
 
 Run `myapi funnel --help` or `myapi funnel <subcommand> --help` for full flag reference.

package/dist/skills/my-llm-api/README.md

@@ -32,7 +32,7 @@ myapi llm draft --kind email --prompt "Friendly welcome, under 60 words"
 export MYAPI_KEY=mak_...
 ```
 
-Requires `api_key` and `org_id` from **myapihq**. Inference cost is debited from your MyAPI balance — top up via `myapi billing topup`.
+Requires `api_key` and `org_id` from **myapihq**. Inference cost is debited from your MyAPI balance — top up via `myapi billing topup`, or keep it funded automatically with `myapi billing auto-recharge`.
 
 ## When to use
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "MyAPI command-line interface",
   "type": "module",
   "files": [
@@ -31,7 +31,7 @@
     "lint:skills:strict": "node scripts/copy-skills.js && node scripts/lint-skills.js --strict"
   },
   "dependencies": {
-    "@myapihq/sdk": "^2.0.1"
+    "@myapihq/sdk": "^2.1.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",