@mailmodo/cli 0.0.55 → 0.0.56-beta.pr58.101

package/dist/lib/base-command.js

@@ -1,15 +1,17 @@
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { input } from '@inquirer/prompts';
+import { input, select } from '@inquirer/prompts';
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import ora from 'ora';
 import { ApiClient } from './api-client.js';
 import { loadConfig } from './config.js';
-import { API_ENDPOINTS, IS_DEV_MODE, YAML_FILE } from './constants.js';
-import { ERRORS, INFO, PROMPTS, quotaExhaustedMessage, recordLabel, VALIDATION, } from './messages.js';
-import { loadYaml, saveYaml } from './yaml-config.js';
+import { API_ENDPOINTS, IS_DEV_MODE, TEMPLATES_DIR, YAML_FILE, } from './constants.js';
+import { syncTemplatesToServer, syncTemplateToServer, fetchTemplatesFromServer, fetchTemplateFromServer, } from './templates/sync.js';
+import { getMissingTemplateIds } from './templates/missing-templates.js';
+import { BLANK_DIR, ERRORS, INFO, PROMPTS, quotaExhaustedMessage, recordLabel, VALIDATION, } from './messages.js';
+import { loadYaml, parseYamlText, saveYaml, } from './yaml-config.js';
 export const FREE_TIER = 'free';
 /**
  * Abstract base command providing shared functionality for all Mailmodo CLI commands.
@@ -90,11 +92,90 @@ export class BaseCommand extends Command {
         const config = await loadYaml();
         if (config)
             return config;
+        if (this.isBlankDirectory())
+            return this.promptBlankDirRestore();
         const restored = await this.restoreYamlFromServer();
         if (restored)
             return restored;
         this.error(ERRORS.NO_YAML);
     }
+    isBlankDirectory() {
+        return (!existsSync(join(process.cwd(), YAML_FILE)) &&
+            !existsSync(join(process.cwd(), TEMPLATES_DIR)));
+    }
+    async fetchYamlText() {
+        try {
+            let client = this.apiClient;
+            if (!client) {
+                const apiKey = process.env.MAILMODO_API_KEY ?? (await loadConfig())?.apiKey;
+                if (!apiKey)
+                    return null;
+                client = new ApiClient(apiKey);
+            }
+            const response = await client.getRawText(API_ENDPOINTS.ASSETS_YAML);
+            return response.ok && response.data ? response.data : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async promptBlankDirRestore() {
+        const yamlText = await this.fetchYamlText();
+        if (!yamlText)
+            this.error(ERRORS.NO_YAML);
+        const autoRestore = this.argv.includes('--yes') || this.argv.includes('--json');
+        if (!autoRestore) {
+            this.log(`\n  ${BLANK_DIR.PROMPT}\n`);
+            const choice = await select({
+                choices: [
+                    { name: BLANK_DIR.CHOICE_RESTORE, value: 'restore' },
+                    { name: BLANK_DIR.CHOICE_SKIP, value: 'skip' },
+                ],
+                message: 'How would you like to proceed?',
+            });
+            if (choice === 'skip') {
+                this.log(`\n  ${BLANK_DIR.SKIP_HINT}\n`);
+                this.exit(0);
+            }
+        }
+        await writeFile(join(process.cwd(), YAML_FILE), yamlText);
+        this.logToStderr(INFO.YAML_RESTORED_FROM_SERVER);
+        const yaml = await loadYaml();
+        if (!yaml)
+            this.error(ERRORS.NO_YAML);
+        const client = this.apiClient;
+        if (client)
+            await this.fetchMissingTemplates(client, yaml);
+        return yaml;
+    }
+    async promptInitServerRestore(flags) {
+        const yamlText = await this.fetchYamlText();
+        if (!yamlText)
+            return { restored: false, serverYaml: null };
+        let shouldRestore = Boolean(flags.yes || flags.json);
+        if (!shouldRestore) {
+            const choice = await select({
+                choices: [
+                    { name: BLANK_DIR.CHOICE_RESTORE_INIT, value: 'restore' },
+                    { name: BLANK_DIR.CHOICE_FRESH, value: 'fresh' },
+                ],
+                message: BLANK_DIR.PROMPT_INIT,
+            });
+            shouldRestore = choice === 'restore';
+        }
+        if (!shouldRestore) {
+            return { restored: false, serverYaml: parseYamlText(yamlText) };
+        }
+        await writeFile(join(process.cwd(), YAML_FILE), yamlText);
+        const yaml = await loadYaml();
+        if (!yaml)
+            return { restored: false, serverYaml: null };
+        const client = this.apiClient;
+        if (client)
+            await this.fetchMissingTemplates(client, yaml);
+        this.log(`\n  ${BLANK_DIR.RESTORED_INIT}\n`);
+        return { restored: true, serverYaml: yaml };
+    }
     async fetchAndWriteYaml(client) {
         try {
             const response = await client.getRawText(API_ENDPOINTS.ASSETS_YAML);
@@ -131,20 +212,6 @@ export class BaseCommand extends Command {
             return null;
         }
     }
-    /**
-     * If `mailmodo.yaml` is absent from the current directory, attempts to restore
-     * it from the server using the given client. Returns `true` if the file was
-     * successfully written, `false` otherwise (file already present, server 404,
-     * or any network error). Silent — never throws.
-     *
-     * Used by `mailmodo login` right after the API key is validated so a returning
-     * user automatically gets their config back without having to run `init` again.
-     */
-    async recoverYamlAfterLogin(client) {
-        if (existsSync(join(process.cwd(), YAML_FILE)))
-            return false;
-        return this.fetchAndWriteYaml(client);
-    }
     /**
      * Uploads the current local mailmodo.yaml to the server as a backup.
      * Best-effort: silently ignores all errors so the originating command
@@ -173,6 +240,92 @@ export class BaseCommand extends Command {
             // Silently ignore — local file remains authoritative
         }
     }
+    /**
+     * Bulk-uploads all template HTML files referenced in the YAML to the server
+     * as a backup. Best-effort: silently ignores all errors so the originating
+     * command always succeeds regardless of sync failures.
+     * Called after init, deploy, and AI regeneration.
+     */
+    async syncTemplatesToServer(yaml) {
+        try {
+            let client = this.apiClient;
+            if (!client) {
+                const envKey = process.env.MAILMODO_API_KEY;
+                const apiKey = envKey ?? (await loadConfig())?.apiKey;
+                if (!apiKey)
+                    return;
+                client = new ApiClient(apiKey);
+            }
+            await syncTemplatesToServer(client, yaml);
+        }
+        catch {
+            // Silently ignore — local files remain authoritative
+        }
+    }
+    /**
+     * Uploads a single template's HTML files to the server for incremental sync.
+     * Best-effort: silently ignores all errors. Called after the edit command
+     * applies changes to a specific template.
+     */
+    async syncTemplateToServer(emailId) {
+        try {
+            let client = this.apiClient;
+            if (!client) {
+                const envKey = process.env.MAILMODO_API_KEY;
+                const apiKey = envKey ?? (await loadConfig())?.apiKey;
+                if (!apiKey)
+                    return;
+                client = new ApiClient(apiKey);
+            }
+            await syncTemplateToServer(client, emailId);
+        }
+        catch {
+            // Silently ignore — local files remain authoritative
+        }
+    }
+    /**
+     * Fetches a single backed-up template from the server and writes it to the
+     * local mailmodo/ folder. Returns true if the template was successfully
+     * restored, false if it is not backed up or on any error.
+     * Used as the `ctx.fetchTemplate` bridge passed to handleMissingTemplates.
+     */
+    async getTemplateFromServer(emailId) {
+        try {
+            let client = this.apiClient;
+            if (!client) {
+                const envKey = process.env.MAILMODO_API_KEY;
+                const apiKey = envKey ?? (await loadConfig())?.apiKey;
+                if (!apiKey)
+                    return false;
+                client = new ApiClient(apiKey);
+            }
+            return fetchTemplateFromServer(client, emailId);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Silently restores any template files missing from disk by fetching them
+     * from the server. Uses the bulk endpoint when all templates are missing
+     * (single round-trip), or individual per-ID requests when only a subset is
+     * missing to avoid overwriting files that are already present. Best-effort —
+     * never throws.
+     */
+    async fetchMissingTemplates(client, yaml) {
+        try {
+            const missingIds = getMissingTemplateIds(yaml);
+            if (missingIds.length === 0)
+                return;
+            // Use bulk endpoint when every template is missing; per-ID otherwise
+            await (missingIds.length === yaml.emails.length
+                ? fetchTemplatesFromServer(client, yaml)
+                : Promise.all(missingIds.map((id) => fetchTemplateFromServer(client, id))));
+        }
+        catch {
+            // best-effort, silently ignore
+        }
+    }
     /**
      * Handles a failed API response by mapping HTTP status codes to
      * user-friendly error messages and exiting the process.

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;
+};

package/dist/lib/commands/contacts/actions.d.ts

@@ -0,0 +1,3 @@
+import type { ContactsCtx } from './types.js';
+export declare function showSummary(ctx: ContactsCtx, json: boolean): Promise<void>;
+export declare function searchContact(ctx: ContactsCtx, email: string, json: boolean): Promise<void>;

package/dist/lib/commands/contacts/actions.js

@@ -0,0 +1,49 @@
+import chalk from 'chalk';
+import { API_ENDPOINTS } from '../../constants.js';
+export async function showSummary(ctx, json) {
+    const response = await ctx.spinner('  Loading contacts...', json, () => ctx.get(API_ENDPOINTS.CONTACTS));
+    if (!response.ok) {
+        ctx.onApiError(response);
+    }
+    const { data } = response;
+    if (json) {
+        ctx.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    ctx.log(`\n  Total: ${chalk.bold(String(data.total ?? 0))}  ` +
+        `Active: ${chalk.green(String(data.active ?? 0))}  ` +
+        `Unsubscribed: ${chalk.yellow(String(data.unsubscribed ?? 0))}  ` +
+        `Bounced: ${chalk.red(String(data.bounced ?? 0))}\n`);
+}
+export async function searchContact(ctx, email, json) {
+    const encodedEmail = encodeURIComponent(email);
+    const response = await ctx.spinner('  Looking up contact...', json, () => ctx.get(`${API_ENDPOINTS.CONTACTS}/${encodedEmail}`));
+    if (!response.ok) {
+        if (response.status === 404) {
+            if (json) {
+                ctx.log(JSON.stringify({ email, error: 'Contact not found' }, null, 2));
+            }
+            else {
+                ctx.log(`\n  Contact '${email}' not found.\n`);
+            }
+            return;
+        }
+        ctx.onApiError(response);
+    }
+    const contact = response.data;
+    if (json) {
+        ctx.log(JSON.stringify(contact, null, 2));
+        return;
+    }
+    ctx.log(`\n  ${chalk.bold('Email:')}       ${contact.email}`);
+    ctx.log(`  ${chalk.bold('Status:')}      ${contact.status}`);
+    ctx.log(`  ${chalk.bold('Added:')}       ${contact.added}`);
+    ctx.log(`  ${chalk.bold('Next email:')}  ${contact.nextEmail || 'None'}`);
+    if (contact.properties && Object.keys(contact.properties).length > 0) {
+        ctx.log(`  ${chalk.bold('Properties:')}`);
+        for (const [key, value] of Object.entries(contact.properties)) {
+            ctx.log(`    ${key}: ${String(value)}`);
+        }
+    }
+    ctx.log('');
+}

package/dist/lib/commands/contacts/export-delete.d.ts

@@ -0,0 +1,9 @@
+import type { ContactsCtx } from './types.js';
+export declare function exportContacts(ctx: ContactsCtx, opts: {
+    json: boolean;
+}): Promise<void>;
+export declare function deleteContact(ctx: ContactsCtx, opts: {
+    email: string;
+    json: boolean;
+    skipConfirm: boolean;
+}): Promise<void>;

package/dist/lib/commands/contacts/export-delete.js

@@ -0,0 +1,51 @@
+import { confirm } from '@inquirer/prompts';
+import chalk from 'chalk';
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { API_ENDPOINTS } from '../../constants.js';
+export async function exportContacts(ctx, opts) {
+    const { json } = opts;
+    const response = await ctx.spinner('  Preparing contact export...', json, () => ctx.get(API_ENDPOINTS.CONTACTS_EXPORT));
+    if (!response.ok) {
+        ctx.onApiError(response);
+    }
+    if (json) {
+        ctx.log(JSON.stringify(response.data, null, 2));
+        return;
+    }
+    ctx.log(`\n  ${chalk.green('✓')} Contact export started.`);
+    const { downloadUrl, status } = response.data;
+    if (!downloadUrl) {
+        ctx.log(`\n  Export status: ${status ?? 'unknown'}. No download URL yet.\n`);
+        return;
+    }
+    const fileResult = await ctx.spinner('  Downloading CSV file...', json, () => ctx.getPublicFile(downloadUrl.trim()));
+    if (!fileResult.ok) {
+        ctx.error(`Download failed: ${fileResult.status} ${fileResult.error ?? ''}\n  URL: ${fileResult.debug.fullUrl}`);
+    }
+    const outputPath = resolve('contacts.csv');
+    await writeFile(outputPath, Buffer.from(fileResult.body));
+    ctx.log(`\n  ${chalk.green('✓')} Contact export saved to ${chalk.cyan(outputPath)}\n`);
+}
+export async function deleteContact(ctx, opts) {
+    const { email, json, skipConfirm } = opts;
+    if (!skipConfirm) {
+        const confirmed = await confirm({
+            default: false,
+            message: `Permanently delete ${email} and all their data? This cannot be undone.`,
+        });
+        if (!confirmed) {
+            ctx.log('\n  Delete cancelled.\n');
+            return;
+        }
+    }
+    const response = await ctx.spinner('  Deleting contact...', json, () => ctx.delete(`${API_ENDPOINTS.CONTACTS}/${encodeURIComponent(email)}`));
+    if (!response.ok) {
+        ctx.onApiError(response);
+    }
+    if (json) {
+        ctx.log(JSON.stringify({ deleted: true, email }, null, 2));
+        return;
+    }
+    ctx.log(`\n  ${chalk.green('✓')} Contact ${email} permanently deleted.\n`);
+}

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

@@ -0,0 +1,35 @@
+import type { ApiResponse } from '../../api-client.js';
+import type { FileFetchResult } from '../../fetch-file.js';
+export interface ContactSummaryResponse {
+    active: number;
+    bounced: number;
+    total: number;
+    unsubscribed: number;
+}
+export interface ContactDetailResponse {
+    added: string;
+    email: string;
+    nextEmail: null | string;
+    properties: Record<string, unknown>;
+    status: string;
+}
+export interface ContactExportResponse {
+    downloadUrl: string;
+    status: string;
+}
+export type ContactsFlags = {
+    json: boolean;
+    yes: boolean;
+};
+export type ContactsCtx = {
+    delete<T = Record<string, unknown>>(path: string): Promise<ApiResponse<T>>;
+    error(msg: string): never;
+    get<T>(path: string, params?: Record<string, string>): Promise<ApiResponse<T>>;
+    getPublicFile(url: string): Promise<FileFetchResult>;
+    log(msg?: string): void;
+    onApiError(resp: {
+        error?: string;
+        status: number;
+    }): never;
+    spinner<T>(text: string, json: boolean, work: () => Promise<T>): Promise<T>;
+};

package/dist/lib/commands/contacts/types.js

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

package/dist/lib/{deploy → commands/deploy}/domain-setup.d.ts

@@ -1,4 +1,4 @@
-import type { MailmodoYaml } from '../yaml-config.js';
+import type { MailmodoYaml } from '../../yaml-config.js';
 import type { DeployCtx, DeployFlags, ValidateResponse } from './types.js';
 export declare function validateDeploySequence(ctx: DeployCtx, payload: object, flags: {
     json: boolean;