@mailmodo/cli 0.0.3 → 0.0.4-beta.pr6.10

package/dist/lib/base-command.d.ts

@@ -0,0 +1,45 @@
+import { Command } from '@oclif/core';
+import { ApiClient } from './api-client.js';
+import { type MailmodoConfig } from './config.js';
+import { type MailmodoYaml } from './yaml-config.js';
+/**
+ * Abstract base command providing shared functionality for all Mailmodo CLI commands.
+ * Subclasses inherit --json and --yes base flags, authentication enforcement,
+ * YAML config loading, and consistent API error handling.
+ */
+export declare abstract class BaseCommand extends Command {
+    static baseFlags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    protected apiClient: ApiClient;
+    /**
+     * Validates that the user is authenticated and initializes the API client.
+     * Checks MAILMODO_API_KEY environment variable first (for AI agent usage),
+     * then falls back to ~/.mailmodo/config.
+     * Exits with an error if no valid API key is found.
+     *
+     * @returns {Promise<MailmodoConfig>} The resolved configuration containing the API key.
+     */
+    protected ensureAuth(): Promise<MailmodoConfig>;
+    /**
+     * Loads and returns the mailmodo.yaml configuration from the current directory.
+     * Exits with an error if the file is not found, directing the user to run init.
+     *
+     * @returns {Promise<MailmodoYaml>} The parsed mailmodo.yaml containing project
+     *   settings and all email sequence definitions.
+     */
+    protected ensureYaml(): Promise<MailmodoYaml>;
+    /**
+     * Handles a failed API response by mapping HTTP status codes to
+     * user-friendly error messages and exiting the process.
+     *
+     * @param {{ status: number; error?: string }} response - The API response object with ok=false.
+     *   Status 401 prompts re-authentication, 429 indicates rate limiting,
+     *   all others display the server's error message or a generic fallback.
+     */
+    protected handleApiError(response: {
+        error?: string;
+        status: number;
+    }): never;
+}

package/dist/lib/base-command.js

@@ -0,0 +1,69 @@
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { ApiClient } from './api-client.js';
+import { loadConfig } from './config.js';
+import { loadYaml } from './yaml-config.js';
+/**
+ * Abstract base command providing shared functionality for all Mailmodo CLI commands.
+ * Subclasses inherit --json and --yes base flags, authentication enforcement,
+ * YAML config loading, and consistent API error handling.
+ */
+export class BaseCommand extends Command {
+    static baseFlags = {
+        json: Flags.boolean({ default: false, description: 'Output as JSON' }),
+        yes: Flags.boolean({ char: 'y', default: false, description: 'Skip confirmation prompts' }),
+    };
+    apiClient;
+    /**
+     * Validates that the user is authenticated and initializes the API client.
+     * Checks MAILMODO_API_KEY environment variable first (for AI agent usage),
+     * then falls back to ~/.mailmodo/config.
+     * Exits with an error if no valid API key is found.
+     *
+     * @returns {Promise<MailmodoConfig>} The resolved configuration containing the API key.
+     */
+    async ensureAuth() {
+        const envKey = process.env.MAILMODO_API_KEY;
+        if (envKey) {
+            this.apiClient = new ApiClient(envKey);
+            return { apiKey: envKey };
+        }
+        const config = await loadConfig();
+        if (!config?.apiKey) {
+            this.error(`Not logged in. Run ${chalk.cyan('mailmodo login')} to authenticate.`);
+        }
+        this.apiClient = new ApiClient(config.apiKey);
+        return config;
+    }
+    /**
+     * Loads and returns the mailmodo.yaml configuration from the current directory.
+     * Exits with an error if the file is not found, directing the user to run init.
+     *
+     * @returns {Promise<MailmodoYaml>} The parsed mailmodo.yaml containing project
+     *   settings and all email sequence definitions.
+     */
+    async ensureYaml() {
+        const config = await loadYaml();
+        if (!config) {
+            this.error(`No mailmodo.yaml found. Run ${chalk.cyan('mailmodo init')} first.`);
+        }
+        return config;
+    }
+    /**
+     * Handles a failed API response by mapping HTTP status codes to
+     * user-friendly error messages and exiting the process.
+     *
+     * @param {{ status: number; error?: string }} response - The API response object with ok=false.
+     *   Status 401 prompts re-authentication, 429 indicates rate limiting,
+     *   all others display the server's error message or a generic fallback.
+     */
+    handleApiError(response) {
+        if (response.status === 401) {
+            this.error(`Invalid API key. Run ${chalk.cyan('mailmodo login')} to re-authenticate.`);
+        }
+        if (response.status === 429) {
+            this.error('Rate limit exceeded. Please try again later.');
+        }
+        this.error(response.error || 'An unexpected API error occurred.');
+    }
+}

package/dist/lib/config.d.ts

@@ -0,0 +1,30 @@
+export interface MailmodoConfig {
+    accountName?: string;
+    apiKey: string;
+    email?: string;
+    freeRemaining?: number;
+}
+/**
+ * Loads the Mailmodo CLI configuration from ~/.mailmodo/config.
+ * The config file stores the API key and account metadata as JSON.
+ *
+ * @returns {Promise<MailmodoConfig | null>} The parsed configuration object
+ *   containing apiKey, email, accountName, and freeRemaining quota,
+ *   or null if the config file does not exist or is corrupted.
+ */
+export declare function loadConfig(): Promise<MailmodoConfig | null>;
+/**
+ * Persists the Mailmodo CLI configuration to ~/.mailmodo/config.
+ * Creates the ~/.mailmodo directory if it does not exist.
+ * Overwrites any existing config file.
+ *
+ * @param {MailmodoConfig} config - The configuration to persist, must include
+ *   at minimum an apiKey. Optional fields: email, accountName, freeRemaining.
+ */
+export declare function saveConfig(config: MailmodoConfig): Promise<void>;
+/**
+ * Returns the absolute path to the Mailmodo config directory (~/.mailmodo).
+ *
+ * @returns {string} The config directory path.
+ */
+export declare function getConfigDir(): string;

package/dist/lib/config.js

@@ -0,0 +1,47 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CONFIG_DIR = join(homedir(), '.mailmodo');
+const CONFIG_FILE = join(CONFIG_DIR, 'config');
+/**
+ * Loads the Mailmodo CLI configuration from ~/.mailmodo/config.
+ * The config file stores the API key and account metadata as JSON.
+ *
+ * @returns {Promise<MailmodoConfig | null>} The parsed configuration object
+ *   containing apiKey, email, accountName, and freeRemaining quota,
+ *   or null if the config file does not exist or is corrupted.
+ */
+export async function loadConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return null;
+    try {
+        const content = await readFile(CONFIG_FILE, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persists the Mailmodo CLI configuration to ~/.mailmodo/config.
+ * Creates the ~/.mailmodo directory if it does not exist.
+ * Overwrites any existing config file.
+ *
+ * @param {MailmodoConfig} config - The configuration to persist, must include
+ *   at minimum an apiKey. Optional fields: email, accountName, freeRemaining.
+ */
+export async function saveConfig(config) {
+    if (!existsSync(CONFIG_DIR)) {
+        await mkdir(CONFIG_DIR, { recursive: true });
+    }
+    await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
+}
+/**
+ * Returns the absolute path to the Mailmodo config directory (~/.mailmodo).
+ *
+ * @returns {string} The config directory path.
+ */
+export function getConfigDir() {
+    return CONFIG_DIR;
+}

package/dist/lib/constants.d.ts

@@ -0,0 +1,27 @@
+export declare const API_BASE_URL: string;
+export declare const API_ENDPOINTS: Readonly<{
+    ANALYTICS: "/analytics";
+    ANALYZE: "/analyze";
+    ASSETS_LOGO: "/assets/logo";
+    AUTH_VALIDATE: "/auth/validate";
+    BILLING_CAP: "/billing/cap";
+    BILLING_STATUS: "/billing/status";
+    CONTACTS: "/contacts";
+    CONTACTS_EXPORT: "/contacts/export";
+    DOMAIN: "/domain";
+    DOMAIN_STATUS: "/domain/status";
+    DOMAIN_VERIFY: "/domain/verify";
+    EDIT: "/edit";
+    EVENTS: "/events";
+    GENERATE: "/generate";
+    LOGS: "/logs";
+    PREVIEW: "/preview";
+    SEQUENCES: "/sequences";
+}>;
+export declare const SIGNUP_URL = "https://mailmodo.com/cli";
+export declare const DOCS_URL = "https://mailmodo.com/docs/cli";
+export declare const DNS_GUIDE_URL = "https://mailmodo.com/docs/dns";
+export declare const PREVIEW_PORT = 3421;
+export declare const DEFAULT_BRAND_COLOR = "#1A56DB";
+export declare const TEMPLATES_DIR = "mailmodo";
+export declare const YAML_FILE = "mailmodo.yaml";

package/dist/lib/constants.js

@@ -0,0 +1,27 @@
+export const API_BASE_URL = process.env.MAILMODO_API_URL || 'https://api.mailmodo.com/cli/v1';
+export const API_ENDPOINTS = Object.freeze({
+    ANALYTICS: '/analytics',
+    ANALYZE: '/analyze',
+    ASSETS_LOGO: '/assets/logo',
+    AUTH_VALIDATE: '/auth/validate',
+    BILLING_CAP: '/billing/cap',
+    BILLING_STATUS: '/billing/status',
+    CONTACTS: '/contacts',
+    CONTACTS_EXPORT: '/contacts/export',
+    DOMAIN: '/domain',
+    DOMAIN_STATUS: '/domain/status',
+    DOMAIN_VERIFY: '/domain/verify',
+    EDIT: '/edit',
+    EVENTS: '/events',
+    GENERATE: '/generate',
+    LOGS: '/logs',
+    PREVIEW: '/preview',
+    SEQUENCES: '/sequences',
+});
+export const SIGNUP_URL = 'https://mailmodo.com/cli';
+export const DOCS_URL = 'https://mailmodo.com/docs/cli';
+export const DNS_GUIDE_URL = 'https://mailmodo.com/docs/dns';
+export const PREVIEW_PORT = 3421;
+export const DEFAULT_BRAND_COLOR = '#1A56DB';
+export const TEMPLATES_DIR = 'mailmodo';
+export const YAML_FILE = 'mailmodo.yaml';

package/dist/lib/yaml-config.d.ts

@@ -0,0 +1,65 @@
+export interface EmailConfig {
+    condition?: string;
+    delay: number | string;
+    goal?: string;
+    id: string;
+    previewText?: string;
+    style?: 'branded' | 'plain';
+    subject: string;
+    template: string;
+    trigger: string;
+}
+export interface ProjectConfig {
+    address?: string;
+    brandColor?: string;
+    domain?: string;
+    emailStyle?: 'branded' | 'plain';
+    fromEmail?: string;
+    fromName?: string;
+    logoFile?: string;
+    logoUrl?: string;
+    monthlyCap?: number;
+    name?: string;
+    replyTo?: string;
+    type?: string;
+    url?: string;
+    webhookUrl?: string;
+}
+export interface MailmodoYaml {
+    emails: EmailConfig[];
+    project: ProjectConfig;
+}
+/**
+ * Loads and parses the mailmodo.yaml configuration file from the specified
+ * directory (or current working directory).
+ *
+ * @param {string} [cwd] - Directory containing mailmodo.yaml. Defaults to process.cwd().
+ * @returns {Promise<MailmodoYaml | null>} The parsed configuration with project
+ *   settings and email array, or null if the file doesn't exist or can't be parsed.
+ */
+export declare function loadYaml(cwd?: string): Promise<MailmodoYaml | null>;
+/**
+ * Serializes and writes the mailmodo.yaml configuration to disk.
+ *
+ * @param {MailmodoYaml} config - The complete configuration to persist.
+ * @param {string} [cwd] - Target directory. Defaults to process.cwd().
+ */
+export declare function saveYaml(config: MailmodoYaml, cwd?: string): Promise<void>;
+/**
+ * Writes an HTML email template file into the /mailmodo templates directory,
+ * creating the directory if it doesn't yet exist.
+ *
+ * @param {string} filename - Template filename relative to the templates dir (e.g., 'welcome.html').
+ * @param {string} html - The complete HTML content for the email template.
+ * @param {string} [cwd] - Base project directory. Defaults to process.cwd().
+ */
+export declare function saveTemplate(filename: string, html: string, cwd?: string): Promise<void>;
+/**
+ * Reads an HTML email template from the /mailmodo templates directory.
+ *
+ * @param {string} filename - Template filename relative to the templates dir (e.g., 'welcome.html').
+ * @param {string} [cwd] - Base project directory. Defaults to process.cwd().
+ * @returns {Promise<string | null>} The raw HTML content of the template,
+ *   or null if the file doesn't exist or can't be read.
+ */
+export declare function loadTemplate(filename: string, cwd?: string): Promise<null | string>;

package/dist/lib/yaml-config.js

@@ -0,0 +1,70 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { dump, load } from 'js-yaml';
+import { TEMPLATES_DIR, YAML_FILE } from './constants.js';
+/**
+ * Loads and parses the mailmodo.yaml configuration file from the specified
+ * directory (or current working directory).
+ *
+ * @param {string} [cwd] - Directory containing mailmodo.yaml. Defaults to process.cwd().
+ * @returns {Promise<MailmodoYaml | null>} The parsed configuration with project
+ *   settings and email array, or null if the file doesn't exist or can't be parsed.
+ */
+export async function loadYaml(cwd) {
+    const filePath = join(cwd || process.cwd(), YAML_FILE);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const content = await readFile(filePath, 'utf8');
+        return load(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Serializes and writes the mailmodo.yaml configuration to disk.
+ *
+ * @param {MailmodoYaml} config - The complete configuration to persist.
+ * @param {string} [cwd] - Target directory. Defaults to process.cwd().
+ */
+export async function saveYaml(config, cwd) {
+    const filePath = join(cwd || process.cwd(), YAML_FILE);
+    const content = dump(config, { lineWidth: -1, noRefs: true, quotingType: '"' });
+    await writeFile(filePath, content);
+}
+/**
+ * Writes an HTML email template file into the /mailmodo templates directory,
+ * creating the directory if it doesn't yet exist.
+ *
+ * @param {string} filename - Template filename relative to the templates dir (e.g., 'welcome.html').
+ * @param {string} html - The complete HTML content for the email template.
+ * @param {string} [cwd] - Base project directory. Defaults to process.cwd().
+ */
+export async function saveTemplate(filename, html, cwd) {
+    const dir = join(cwd || process.cwd(), TEMPLATES_DIR);
+    if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+    }
+    await writeFile(join(dir, filename), html);
+}
+/**
+ * Reads an HTML email template from the /mailmodo templates directory.
+ *
+ * @param {string} filename - Template filename relative to the templates dir (e.g., 'welcome.html').
+ * @param {string} [cwd] - Base project directory. Defaults to process.cwd().
+ * @returns {Promise<string | null>} The raw HTML content of the template,
+ *   or null if the file doesn't exist or can't be read.
+ */
+export async function loadTemplate(filename, cwd) {
+    const filePath = join(cwd || process.cwd(), TEMPLATES_DIR, filename);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return await readFile(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}