@mailmodo/cli 0.0.54-beta.pr56.91 → 0.0.55-beta.pr57.92

package/dist/commands/settings/index.js

@@ -1,26 +1,10 @@
 import { Flags } from '@oclif/core';
-import { input, select } from '@inquirer/prompts';
 import chalk from 'chalk';
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
 import { BaseCommand, FREE_TIER } from '../../lib/base-command.js';
-import { API_ENDPOINTS } from '../../lib/constants.js';
-import { INFO } from '../../lib/messages.js';
-import { settingKeyToProp } from '../../lib/utils.js';
 import { saveYaml } from '../../lib/yaml-config.js';
-const SETTINGS_GROUPS = Object.freeze({
-    billing: ['monthly_cap'],
-    brand: ['email_style', 'brand_color', 'logo_url', 'logo_file'],
-    domain: ['domain', 'address'],
-    identity: ['from_name', 'from_email', 'reply_to'],
-    integrations: ['webhook_url'],
-});
-const SETUP_HINTS = {
-    address: "'mailmodo domain'",
-    domain: "'mailmodo domain'",
-    monthlyCap: "'mailmodo billing --cap <n>'",
-};
+import { applySetFlag } from '../../lib/commands/settings/actions.js';
+import { displaySettingsGroup, fetchDomainVerified, SETTINGS_GROUPS, } from '../../lib/commands/settings/display.js';
+import { promptEditSetting } from '../../lib/commands/settings/prompt.js';
 export default class Settings extends BaseCommand {
     static description = 'View and update project settings';
     static examples = [
@@ -35,14 +19,18 @@ export default class Settings extends BaseCommand {
     async run() {
         const { flags } = await this.parse(Settings);
         const yamlConfig = await this.ensureYaml();
+        const ctx = this.makeCtx();
         if (flags.set) {
-            await this.applySetFlag(flags.set, yamlConfig, flags.json ?? false);
+            await applySetFlag(ctx, yamlConfig, {
+                isJson: flags.json ?? false,
+                setFlag: flags.set,
+            });
             return;
         }
         const [domainVerified, billingStatus] = await Promise.all([
             flags.json
                 ? Promise.resolve(null)
-                : this.fetchDomainVerified(yamlConfig.project.domain),
+                : fetchDomainVerified(ctx, yamlConfig.project.domain),
             this.fetchBillingStatus(),
         ]);
         const tier = billingStatus?.tier ?? null;
@@ -60,235 +48,35 @@ export default class Settings extends BaseCommand {
         for (const [group, keys] of Object.entries(SETTINGS_GROUPS)) {
             if (group === 'billing' && tier === FREE_TIER)
                 continue;
-            this.displaySettingsGroup(group, keys, yamlConfig.project, domainVerified);
-        }
-        if (!flags.yes) {
-            await this.promptEditSetting(yamlConfig, tier);
-        }
-    }
-    async applySetFlag(setFlag, yamlConfig, isJson) {
-        const { project } = yamlConfig;
-        const eqIndex = setFlag.indexOf('=');
-        if (eqIndex === -1) {
-            this.error('Invalid format. Use --set key=value (e.g., --set brand_color=#0F3460)');
-        }
-        const key = setFlag.slice(0, eqIndex).trim();
-        const propKey = settingKeyToProp(key);
-        const value = setFlag.slice(eqIndex + 1).trim();
-        if (!(propKey in project) && key !== 'logo_file') {
-            this.error(`Unknown setting: ${key}`);
-        }
-        if (propKey === 'monthlyCap') {
-            await this.applyMonthlyCapChange(yamlConfig, value, isJson, null);
-            return;
-        }
-        project[propKey] = value;
-        await saveYaml(yamlConfig);
-        await this.syncYamlToServer();
-        if (isJson) {
-            this.log(JSON.stringify({ [propKey]: value, status: 'updated' }, null, 2));
-            return;
-        }
-        this.log(`\n  ${chalk.green('✓')} ${key} updated to ${chalk.cyan(value)}`);
-        this.log(`  ${INFO.DEPLOY_TO_APPLY}\n`);
-    }
-    async applyMonthlyCapChange(yamlConfig, rawValue, isJson, knownTier) {
-        const parsed = Number(rawValue);
-        if (!Number.isInteger(parsed) || parsed < 1) {
-            this.error('monthly_cap must be a positive integer (blocks).');
-        }
-        await this.ensureAuth();
-        const tier = knownTier ?? (await this.fetchBillingTier());
-        if (tier === FREE_TIER) {
-            this.warnFreeTierCapBlocked(isJson);
-            return;
-        }
-        const data = await this.applyBillingCap({ cap: parsed, json: isJson });
-        yamlConfig.project.monthlyCap = data.capBlocks;
-        await saveYaml(yamlConfig);
-        await this.syncYamlToServer();
-        if (isJson) {
-            this.log(JSON.stringify({ monthlyCap: data.capBlocks, status: 'updated' }, null, 2));
-            return;
-        }
-        this.log(`\n  ${chalk.green('✓')} monthly_cap updated to ${chalk.cyan(String(data.capBlocks))} (${data.capEmails.toLocaleString()} emails)\n`);
-    }
-    displaySettingsGroup(group, keys, project, domainVerified) {
-        const availableKeys = keys.filter((key) => {
-            if (group === 'brand' && key === 'logo_file')
-                return true;
-            return settingKeyToProp(key) in project;
-        });
-        const groupTitle = `  ${chalk.bold(group.charAt(0).toUpperCase() + group.slice(1))}`;
-        if (availableKeys.length === 0) {
-            const hint = SETUP_HINTS[settingKeyToProp(keys[0])];
-            if (hint) {
-                this.log(groupTitle);
-                this.log(`  ${'─'.repeat(49)}`);
-                this.log(`  ${chalk.dim(`Run ${hint} to configure.`)}`);
-                this.log('');
-            }
-            return;
-        }
-        this.log(groupTitle);
-        this.log(`  ${'─'.repeat(49)}`);
-        for (const key of availableKeys) {
-            const propKey = settingKeyToProp(key);
-            const value = project[propKey];
-            let displayValue = value ? String(value) : chalk.dim('(not set)');
-            if (key === 'domain' && value && domainVerified === true) {
-                displayValue += `  ${chalk.green('✓ verified')}`;
-            }
-            else if (key === 'domain' && value && domainVerified === false) {
-                displayValue += `  ${chalk.red('✗ not verified')}`;
-            }
-            this.log(`  ${key.padEnd(16)} ${displayValue}`);
-        }
-        const missingKeys = keys.filter((key) => !(settingKeyToProp(key) in project) &&
-            !(group === 'brand' && key === 'logo_file'));
-        for (const key of missingKeys) {
-            const hint = SETUP_HINTS[settingKeyToProp(key)];
-            if (hint) {
-                this.log(`  ${key.padEnd(16)} ${chalk.dim(`(run ${hint} to set up)`)}`);
-            }
-        }
-        this.log('');
-    }
-    /**
-     * Prompts the user to pick a setting key to edit and dispatches
-     * to the appropriate handler for that key.
-     */
-    async promptEditSetting(yamlConfig, tier) {
-        const { project } = yamlConfig;
-        const editKey = await input({
-            default: 'n',
-            message: "Edit a setting? (key or 'n'):",
-        });
-        if (editKey === 'n')
-            return;
-        if (editKey === 'monthly_cap' && tier === FREE_TIER) {
-            this.warnFreeTierCapBlocked(false);
-            return;
-        }
-        const editPropKey = settingKeyToProp(editKey);
-        if (!(editPropKey in project)) {
-            if (editKey === 'logo_file') {
-                await this.handleLogoUpload(yamlConfig);
-                return;
-            }
-            const hint = SETUP_HINTS[editPropKey];
-            if (hint) {
-                this.log(`\n  ${editKey} is not configured yet. Run ${chalk.cyan(hint)} to set it up.\n`);
-            }
-            else {
-                this.log(`\n  Unknown setting: ${editKey}\n`);
-            }
-            return;
-        }
-        if (editKey === 'logo_file') {
-            await this.handleLogoUpload(yamlConfig);
-            return;
-        }
-        if (editKey === 'domain') {
-            await this.handleDomainChange(yamlConfig);
-            return;
-        }
-        if (editKey === 'monthly_cap') {
-            const newValue = await input({
-                message: 'New monthly cap (blocks):',
-            });
-            await this.applyMonthlyCapChange(yamlConfig, newValue, false, tier);
-            return;
-        }
-        if (editKey === 'email_style') {
-            const style = await select({
-                choices: [
-                    { name: 'plain', value: 'plain' },
-                    { name: 'branded', value: 'branded' },
-                ],
-                message: 'Email style:',
+            displaySettingsGroup(ctx, group, {
+                domainVerified,
+                keys,
+                project: yamlConfig.project,
             });
-            project.emailStyle = style;
-            await saveYaml(yamlConfig);
-            await this.syncYamlToServer();
-            this.log(`\n  ${chalk.green('✓')} email_style updated to ${chalk.cyan(style)}`);
-            this.log(`  ${INFO.DEPLOY_TO_APPLY}\n`);
-            return;
-        }
-        const newValue = await input({
-            message: `New value for ${editKey}:`,
-        });
-        project[editPropKey] = newValue;
-        await saveYaml(yamlConfig);
-        await this.syncYamlToServer();
-        this.log(`\n  ${chalk.green('✓')} Updated. ${INFO.DEPLOY_TO_APPLY}\n`);
-    }
-    /**
-     * Fetches the domain verification status from the API.
-     * Returns true/false for verified/unverified, or null if unavailable.
-     */
-    async fetchDomainVerified(domain) {
-        if (!domain)
-            return null;
-        try {
-            await this.ensureAuth();
-            const response = await this.apiClient.get(API_ENDPOINTS.DOMAIN_STATUS, { domain });
-            if (!response.ok) {
-                this.log(`  ${chalk.dim('Could not fetch domain status. Run')} ${chalk.cyan("'mailmodo domain --status'")} ${chalk.dim('to check manually.')}`);
-                return null;
-            }
-            return response.data?.verified === true;
         }
-        catch {
-            this.log(`  ${chalk.dim('Could not reach API for domain status. Skipping verification check.')}`);
-            return null;
+        if (!flags.yes) {
+            await promptEditSetting(ctx, yamlConfig, tier);
         }
     }
-    async handleDomainChange(yamlConfig) {
-        await this.ensureAuth();
-        const inputs = await this.collectDomainSetupInputs(yamlConfig, false);
-        const { dnsRecords, dnsGuideUrl } = await this.registerDomain(yamlConfig, inputs, false);
-        this.log(`\n  Domain and sender details updated. You will need to re-verify.`);
-        this.logDnsRecords(dnsRecords, dnsGuideUrl, false);
-        this.log(`  Run ${chalk.cyan("'mailmodo domain --verify'")} once records are added.`);
-        this.log(`  Emails will not send until the new domain is verified.`);
-    }
-    /**
-     * Handles the logo file upload flow: validates the local file exists,
-     * reads it, uploads to Mailmodo CDN via API, and updates both logoFile
-     * and logoUrl in the project config.
-     *
-     * @param {import('../../lib/yaml-config.js').MailmodoYaml} yamlConfig - The full YAML config to update and save.
-     */
-    async handleLogoUpload(yamlConfig) {
-        const logoPath = await input({ message: 'Path to logo file:' });
-        const resolvedPath = resolve(logoPath);
-        if (!existsSync(resolvedPath)) {
-            this.log(`\n  File not found: ${resolvedPath}\n`);
-            return;
-        }
-        await this.ensureAuth();
-        const fileBuffer = await readFile(resolvedPath);
-        const ext = resolvedPath.split('.').pop()?.toLowerCase();
-        const mimeTypes = {
-            png: 'image/png',
-            jpg: 'image/jpeg',
-            jpeg: 'image/jpeg',
-            svg: 'image/svg+xml',
+    makeCtx() {
+        return {
+            applyBillingCap: (opts) => this.applyBillingCap(opts),
+            collectDomainInputs: (yaml, skip) => this.collectDomainSetupInputs(yaml, skip),
+            ensureAuth: async () => {
+                await this.ensureAuth();
+            },
+            error: (msg) => this.error(msg),
+            fetchBillingStatus: () => this.fetchBillingStatus(),
+            fetchBillingTier: () => this.fetchBillingTier(),
+            get: (path, params) => this.apiClient.get(path, params),
+            log: (msg) => this.log(msg),
+            onApiError: (r) => this.handleApiError(r),
+            postFormData: (path, formData) => this.apiClient.postFormData(path, formData),
+            registerDomainAndSave: (yaml, inputs, json) => this.registerDomain(yaml, inputs, json),
+            showDnsRecords: (records, url, json) => this.logDnsRecords(records, url, json),
+            spinner: (text, json, work) => this.withApiSpinner({ json, text }, work),
+            syncYaml: () => this.syncYamlToServer(),
+            warnFreeTierCapBlocked: (json) => this.warnFreeTierCapBlocked(json),
         };
-        const mimeType = mimeTypes[ext ?? ''] ?? 'application/octet-stream';
-        const formData = new FormData();
-        formData.append('logo', new Blob([new Uint8Array(fileBuffer)], { type: mimeType }), logoPath.split(/[/\\]/).pop() || 'logo.png');
-        const response = await this.withApiSpinner({ json: false, text: '  Uploading logo file...' }, () => this.apiClient.postFormData(API_ENDPOINTS.ASSETS_LOGO, formData));
-        if (!response.ok) {
-            this.handleApiError(response);
-        }
-        yamlConfig.project.logoUrl = response.data?.url || '';
-        yamlConfig.project.logoFile = logoPath;
-        await saveYaml(yamlConfig);
-        await this.syncYamlToServer();
-        this.log(`\n  Logo uploaded and hosted at:`);
-        this.log(`  ${chalk.cyan(String(response.data?.url))}`);
-        this.log(`  Run ${chalk.cyan("'mailmodo deploy'")} to apply to all branded emails.\n`);
     }
 }

package/dist/commands/status/index.d.ts

@@ -7,4 +7,5 @@ export default class Status extends BaseCommand {
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    private makeCtx;
 }

package/dist/commands/status/index.js

@@ -1,6 +1,6 @@
-import chalk from 'chalk';
 import { BaseCommand } from '../../lib/base-command.js';
 import { API_ENDPOINTS } from '../../lib/constants.js';
+import { logStatusOutput } from '../../lib/commands/status/output.js';
 export default class Status extends BaseCommand {
     static description = 'View email performance metrics and quota usage';
     static examples = [
@@ -13,49 +13,23 @@ export default class Status extends BaseCommand {
     async run() {
         const { flags } = await this.parse(Status);
         await this.ensureAuth();
-        const response = await this.withApiSpinner({ json: flags.json, text: '  Loading analytics...' }, () => this.apiClient.get(API_ENDPOINTS.ANALYTICS));
+        const ctx = this.makeCtx();
+        const response = await ctx.spinner('  Loading analytics...', flags.json, () => ctx.get(API_ENDPOINTS.ANALYTICS));
         if (!response.ok) {
-            this.handleApiError(response);
+            ctx.onApiError(response);
         }
-        const { emails, monthlySent, quota } = response.data;
         if (flags.json) {
             this.log(JSON.stringify(response.data, null, 2));
             return;
         }
-        this.log(`\n  ${chalk.bold('Last 7 days')}${''.padEnd(20)}Sent   Open   Click   Conv`);
-        this.log(`  ${'─'.repeat(62)}`);
-        if (emails?.length) {
-            for (const metric of emails) {
-                const id = (metric.emailId || '').padEnd(30);
-                const sent = String(metric.sent ?? 0).padEnd(7);
-                const openRate = (metric.open || '0%').padEnd(7);
-                const clickRate = (metric.click || '0%').padEnd(8);
-                const convRate = metric.conv || '0%';
-                this.log(`  ${id}${sent}${openRate}${clickRate}${convRate}`);
-            }
-        }
-        else {
-            this.log(`  ${chalk.dim('No data yet. Deploy emails first.')}`);
-        }
-        this.log('');
-        if (monthlySent !== null && monthlySent !== undefined) {
-            this.log(`  Emails sent this month:  ${chalk.bold(String(monthlySent))}`);
-        }
-        if (quota) {
-            if (quota.plan === 'free') {
-                this.log(`  Free tier remaining:     ${chalk.cyan(String(quota.freeRemaining))} emails`);
-            }
-            else if (quota.plan === 'paid') {
-                if (quota.currentBlockEmailsRemaining !== null &&
-                    quota.currentBlockEmailsRemaining !== undefined) {
-                    const { blockSize } = quota;
-                    const sent = blockSize - quota.currentBlockEmailsRemaining;
-                    const remaining = quota.currentBlockEmailsRemaining;
-                    this.log(`  Current paid block (${blockSize} emails) : ${chalk.cyan(`${sent} emails sent, ${remaining} emails remaining`)}`);
-                }
-                this.log(`  Blocks used:             ${quota.blocksUsed}`);
-            }
-        }
-        this.log('');
+        logStatusOutput(ctx, response.data);
+    }
+    makeCtx() {
+        return {
+            get: (path, params) => this.apiClient.get(path, params),
+            log: (msg) => this.log(msg),
+            onApiError: (r) => this.handleApiError(r),
+            spinner: (text, json, work) => this.withApiSpinner({ json, text }, work),
+        };
     }
 }

package/dist/lib/commands/billing/checkout-status.d.ts

@@ -0,0 +1,3 @@
+import type { BillingCtx } from './types.js';
+export declare function startCheckout(ctx: BillingCtx, jsonOutput: boolean): Promise<void>;
+export declare function showStatus(ctx: BillingCtx, jsonOutput: boolean, statusOnly: boolean): Promise<void>;

package/dist/lib/commands/billing/checkout-status.js

@@ -0,0 +1,63 @@
+import chalk from 'chalk';
+import open from 'open';
+import { FREE_TIER } from '../../base-command.js';
+import { API_ENDPOINTS } from '../../constants.js';
+import { INFO } from '../../messages.js';
+import { formatAutoCharge, formatCap, formatCurrency, formatPaymentMethod, formatUsageBlock, } from './format.js';
+export async function startCheckout(ctx, jsonOutput) {
+    const response = await ctx.spinner('  Creating checkout session...', jsonOutput, () => ctx.post(API_ENDPOINTS.BILLING_CHECKOUT));
+    if (!response.ok) {
+        ctx.onApiError(response);
+    }
+    const { checkoutUrl } = response.data;
+    if (jsonOutput) {
+        ctx.log(JSON.stringify({ checkoutUrl }, null, 2));
+        return;
+    }
+    ctx.log(`\n  ${chalk.bold('Stripe Checkout')} — add or update your payment method.`);
+    ctx.log(`  ${chalk.dim(checkoutUrl)}\n`);
+    if (!process.env.CI) {
+        try {
+            await open(checkoutUrl);
+            ctx.log(`  ${INFO.BROWSER_OPENING}\n`);
+        }
+        catch {
+            ctx.log(`  ${INFO.BROWSER_OPEN_FAILED}\n`);
+        }
+    }
+}
+function logStatusFields(ctx, data) {
+    ctx.log('');
+    ctx.log(`  Tier:          ${data.tier}`);
+    ctx.log(`  Payment:       ${formatPaymentMethod(data)}`);
+    ctx.log(`  Auto-charge:   ${formatAutoCharge(data)}`);
+    if (data.tier !== FREE_TIER) {
+        ctx.log(`  Monthly cap:   ${formatCap(data.cap)}`);
+    }
+    ctx.log(`  Total spent:   ${formatCurrency(data.totalSpent, data.spentCurrency)}`);
+    if (data.activeBlocks.length === 0) {
+        ctx.log('  Active blocks: none');
+    }
+    else {
+        ctx.log('  Active blocks:');
+        for (const block of data.activeBlocks) {
+            ctx.log(`    - ${formatUsageBlock(block)}`);
+        }
+    }
+    ctx.log('');
+}
+export async function showStatus(ctx, jsonOutput, statusOnly) {
+    const response = await ctx.spinner('  Loading billing status...', jsonOutput, () => ctx.get(API_ENDPOINTS.BILLING_STATUS));
+    if (!response.ok) {
+        ctx.onApiError(response);
+    }
+    const { data } = response;
+    if (jsonOutput) {
+        ctx.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    logStatusFields(ctx, data);
+    if (!data.hasPaymentMethod && !statusOnly) {
+        await startCheckout(ctx, jsonOutput);
+    }
+}

package/dist/lib/commands/billing/format.d.ts

@@ -0,0 +1,7 @@
+import type { BillingCap, BillingStatusResponse, BillingUsageBlock } from './types.js';
+export declare function pluralize(word: string, count: number): string;
+export declare function formatAutoCharge(data: BillingStatusResponse): string;
+export declare function formatCap(cap: BillingCap): string;
+export declare function formatCurrency(amount: number | string, currency: string): string;
+export declare function formatPaymentMethod(data: BillingStatusResponse): string;
+export declare function formatUsageBlock(block: BillingUsageBlock): string;

package/dist/lib/commands/billing/format.js

@@ -0,0 +1,63 @@
+export function pluralize(word, count) {
+    return count === 1 ? word : `${word}s`;
+}
+export function formatAutoCharge(data) {
+    if (!data.autoChargeEnabled) {
+        return 'disabled';
+    }
+    if (typeof data.autoChargeBlockCount !== 'number') {
+        return 'enabled';
+    }
+    return `enabled (${data.autoChargeBlockCount} ${pluralize('block', data.autoChargeBlockCount)})`;
+}
+export function formatCap(cap) {
+    const hasBlocks = typeof cap.inBlocks === 'number';
+    const hasEmails = typeof cap.inEmails === 'number';
+    if (hasBlocks && hasEmails) {
+        return `${cap.inBlocks} ${pluralize('block', cap.inBlocks)} (${cap.inEmails.toLocaleString()} ${pluralize('email', cap.inEmails)})`;
+    }
+    if (hasBlocks) {
+        return `${cap.inBlocks} ${pluralize('block', cap.inBlocks)}`;
+    }
+    if (hasEmails) {
+        return `${cap.inEmails.toLocaleString()} ${pluralize('email', cap.inEmails)}`;
+    }
+    return 'not set';
+}
+export function formatCurrency(amount, currency) {
+    const numericAmount = typeof amount === 'number' ? amount : Number.parseFloat(amount);
+    const normalizedCurrency = currency.toUpperCase();
+    if (Number.isFinite(numericAmount)) {
+        try {
+            return new Intl.NumberFormat('en-US', {
+                currency: normalizedCurrency,
+                style: 'currency',
+            }).format(numericAmount);
+        }
+        catch {
+            return `${numericAmount.toFixed(2)} ${normalizedCurrency}`;
+        }
+    }
+    return `${String(amount)} ${normalizedCurrency}`;
+}
+export function formatPaymentMethod(data) {
+    if (!data.hasPaymentMethod) {
+        return 'No payment method on file';
+    }
+    const primaryMethod = data.paymentMethod[0];
+    if (!primaryMethod) {
+        return 'Payment method on file';
+    }
+    const brand = primaryMethod.brand || 'Card';
+    return primaryMethod.last4
+        ? `${brand} ending ${primaryMethod.last4}`
+        : `${brand} on file`;
+}
+export function formatUsageBlock(block) {
+    const allowance = block.blockAllowance ?? Math.max(block.blocksCount * block.blockSize, 0);
+    const used = Math.max(block.emailsSent ?? 0, 0);
+    const activationSuffix = block.activatedAt
+        ? `, activated at ${new Date(block.activatedAt).toLocaleDateString('en-US')}`
+        : '';
+    return `${block.type} block (${used + allowance}): ${used} ${pluralize('email', used)} sent, ${allowance} ${pluralize('email', allowance)} remaining${activationSuffix}`;
+}

package/dist/lib/commands/billing/purchase-cap.d.ts

@@ -0,0 +1,7 @@
+import type { BillingCtx } from './types.js';
+export declare function purchaseBlocks(ctx: BillingCtx, blocksCount: number, jsonOutput: boolean): Promise<void>;
+export declare function setCap(ctx: BillingCtx, opts: {
+    autoChargeBlockCount?: number;
+    cap: number;
+    json: boolean;
+}): Promise<void>;

package/dist/lib/commands/billing/purchase-cap.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { FREE_TIER } from '../../base-command.js';
+import { API_ENDPOINTS } from '../../constants.js';
+import { loadYaml, saveYaml } from '../../yaml-config.js';
+import { pluralize } from './format.js';
+async function persistMonthlyCap(ctx, capBlocks) {
+    const yamlConfig = await loadYaml();
+    if (!yamlConfig)
+        return;
+    if (yamlConfig.project.monthlyCap === capBlocks)
+        return;
+    yamlConfig.project.monthlyCap = capBlocks;
+    await saveYaml(yamlConfig);
+    await ctx.syncYaml();
+}
+export async function purchaseBlocks(ctx, blocksCount, jsonOutput) {
+    if (blocksCount < 1) {
+        ctx.error('Purchase block count must be at least 1 block.');
+    }
+    const response = await ctx.spinner('  Initiating block purchase...', jsonOutput, () => ctx.post(API_ENDPOINTS.BILLING_PURCHASE, {
+        blocksCount,
+    }));
+    if (!response.ok) {
+        ctx.onApiError(response);
+    }
+    if (jsonOutput) {
+        ctx.log(JSON.stringify(response.data, null, 2));
+        return;
+    }
+    ctx.log(`\n  ${chalk.green('✓')} ${response.data.message}`);
+    ctx.log(`  Blocks:        ${blocksCount} ${pluralize('block', blocksCount)}`);
+    ctx.log(`  Payment intent:${` ${chalk.dim(response.data.paymentIntentId)}`}`);
+    ctx.log('');
+}
+export async function setCap(ctx, opts) {
+    ctx.validateBillingCapInputs({
+        autoChargeBlockCount: opts.autoChargeBlockCount,
+        cap: opts.cap,
+    });
+    const tier = await ctx.fetchBillingTier();
+    if (tier === FREE_TIER) {
+        ctx.warnFreeTierCapBlocked(opts.json);
+        return;
+    }
+    const data = await ctx.applyBillingCap(opts);
+    await persistMonthlyCap(ctx, data.capBlocks);
+    if (opts.json) {
+        ctx.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    ctx.log(`\n  ${chalk.green('✓')} ${data.message}`);
+    ctx.log(`  Monthly cap:   ${chalk.bold(String(data.capBlocks))} ${pluralize('block', data.capBlocks)} (${data.capEmails.toLocaleString()} emails)`);
+    if (data.autoChargeBlockCount !== undefined) {
+        ctx.log(`  Auto-charge:   ${data.autoChargeBlockCount} ${pluralize('block', data.autoChargeBlockCount)}`);
+    }
+    ctx.log('');
+}

package/dist/lib/commands/billing/types.d.ts

@@ -0,0 +1,72 @@
+import type { ApiResponse } from '../../api-client.js';
+import type { BillingCapUpdateResult } from '../../base-command.js';
+export type { BillingCapUpdateResult } from '../../base-command.js';
+export interface BillingCap {
+    capUpdatedAt: null | string;
+    inBlocks: null | number;
+    inEmails: null | number;
+}
+export interface BillingPaymentMethod {
+    brand?: string;
+    last4?: string;
+    type?: string;
+}
+export interface BillingUsageBlock {
+    activatedAt?: string;
+    blockAllowance?: number;
+    blockSize: number;
+    blocksCount: number;
+    emailsSent: number;
+    id: string;
+    status: string;
+    type: string;
+}
+export interface BillingStatusResponse {
+    activeBlocks: BillingUsageBlock[];
+    autoChargeBlockCount: null | number;
+    autoChargeEnabled: boolean;
+    cap: BillingCap;
+    hasPaymentMethod: boolean;
+    paymentMethod: BillingPaymentMethod[];
+    spentCurrency: string;
+    tier: string;
+    totalSpent: number | string;
+}
+export interface CheckoutResponse {
+    checkoutUrl: string;
+}
+export interface BillingPurchaseResponse {
+    message: string;
+    paymentIntentId: string;
+}
+export type BillingFlags = {
+    'auto-charge-block-count'?: number;
+    cap?: number;
+    checkout: boolean;
+    json: boolean;
+    purchase?: number;
+    status: boolean;
+};
+export type BillingCtx = {
+    applyBillingCap(opts: {
+        autoChargeBlockCount?: number;
+        cap: number;
+        json: boolean;
+    }): Promise<BillingCapUpdateResult>;
+    error(msg: string): never;
+    fetchBillingTier(): Promise<null | string>;
+    get<T>(path: string, params?: Record<string, string>): Promise<ApiResponse<T>>;
+    log(msg?: string): void;
+    onApiError(resp: {
+        error?: string;
+        status: number;
+    }): never;
+    post<T>(path: string, body?: unknown): Promise<ApiResponse<T>>;
+    spinner<T>(text: string, json: boolean, work: () => Promise<T>): Promise<T>;
+    syncYaml(): Promise<void>;
+    validateBillingCapInputs(opts: {
+        autoChargeBlockCount?: number;
+        cap: number;
+    }): void;
+    warnFreeTierCapBlocked(json: boolean): void;
+};