@mailmodo/cli 0.0.49 → 0.0.50

package/dist/commands/edit/index.js

@@ -49,6 +49,7 @@ export default class Edit extends BaseCommand {
     async runEditStep(ctx, changeDescription, flags) {
         const response = await this.withApiSpinner({ json: flags.json, text: '  Applying AI edits...' }, () => this.callEditApi(changeDescription, ctx.email, ctx.templateHtml));
         if (!response.ok) {
+            this.handleAiQuotaError(response, 'edit');
             this.handleApiError(response);
         }
         const updated = response.data;

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

@@ -8,5 +8,6 @@ export default class Init extends BaseCommand {
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    private persistMonthlyCap;
     private confirmOverwriteIfNeeded;
 }

package/dist/commands/init/index.js

@@ -64,6 +64,7 @@ export default class Init extends BaseCommand {
             url: productUrl,
         }));
         if (!analysisResponse.ok) {
+            this.handleAiQuotaError(analysisResponse, 'init');
             this.handleApiError(analysisResponse);
         }
         const analysis = analysisResponse.data;
@@ -154,12 +155,7 @@ export default class Init extends BaseCommand {
             },
         };
         await saveYaml(yamlConfig);
-        const billingStatus = await this.fetchBillingStatus();
-        const monthlyCap = billingStatus?.cap?.inBlocks;
-        if (monthlyCap !== null && monthlyCap !== undefined) {
-            yamlConfig.project.monthlyCap = monthlyCap;
-            await saveYaml(yamlConfig);
-        }
+        await this.persistMonthlyCap(yamlConfig);
         const templateSaves = analysisPayload.recommendedEmails.flatMap((rec, index) => {
             const generated = generatedEmails[index];
             const saves = [];
@@ -184,6 +180,14 @@ export default class Init extends BaseCommand {
         this.log(`  Created ${chalk.green('mailmodo.yaml')} + ${chalk.green(String(emailConfigs.length))} email templates in ${chalk.green('/mailmodo')}\n`);
         this.log(`  Run ${chalk.cyan("'mailmodo emails'")} to review.\n`);
     }
+    async persistMonthlyCap(yamlConfig) {
+        const billingStatus = await this.fetchBillingStatus();
+        const monthlyCap = billingStatus?.cap?.inBlocks;
+        if (monthlyCap !== null && monthlyCap !== undefined) {
+            yamlConfig.project.monthlyCap = monthlyCap;
+            await saveYaml(yamlConfig);
+        }
+    }
     async confirmOverwriteIfNeeded(flags) {
         const existing = await loadYaml();
         if (!existing)

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

@@ -2,6 +2,11 @@ import { Command } from '@oclif/core';
 import { ApiClient, type ApiRequestDebugInfo } from './api-client.js';
 import { type MailmodoConfig } from './config.js';
 import { type MailmodoYaml } from './yaml-config.js';
+/**
+ * Kind of AI quota that was exhausted. Drives both the headline default
+ * message and the follow-up tip pointing the user at the next-best action.
+ */
+export type AiQuotaFeature = 'edit' | 'init';
 export interface BillingCapUpdateResult {
     autoChargeBlockCount?: number;
     capBlocks: number;
@@ -76,6 +81,25 @@ export declare abstract class BaseCommand extends Command {
         error?: string;
         status: number;
     }): never;
+    /**
+     * Intercepts a 429 "Monthly quota exhausted" response from an AI rate-limited
+     * endpoint (analyze for `init`, email edit for `edit`) and exits with a
+     * feature-specific message that includes the server's error text, the reset
+     * date, optional retry hint, and the next-best action. Returns without
+     * exiting when the response is not a 429 so callers can fall through to
+     * `handleApiError` for non-quota failures.
+     *
+     * @param {{ status: number; error?: string; data?: unknown; debug?: ApiRequestDebugInfo }} response - The failed API response.
+     *   Must carry the parsed JSON body (`data`) so reset/retry fields can be surfaced.
+     * @param {AiQuotaFeature} feature - Which AI quota was hit. Drives the default headline + tip
+     *   shown when the server omits an explicit `error` string.
+     */
+    protected handleAiQuotaError(response: {
+        data?: unknown;
+        debug?: ApiRequestDebugInfo;
+        error?: string;
+        status: number;
+    }, feature: AiQuotaFeature): void;
     protected collectDomainSetupInputs(yamlConfig: MailmodoYaml, skipPrompts: boolean): Promise<{
         address: string;
         domain: string;
@@ -144,12 +168,15 @@ export declare abstract class BaseCommand extends Command {
         value: string;
     }>, guideUrl: string | undefined, json: boolean): void;
     /**
-     * Builds the terminal error string for a failed API call, appending request
-     * metadata when {@link ApiRequestDebugInfo} is available.
+     * Builds the terminal error string for a failed API call. In production only
+     * the user-facing message is returned; verbose request diagnostics (URL,
+     * status, response body, error code) are appended only when [[IS_DEV_MODE]]
+     * is true so end users never see internal request metadata.
      *
      * @param {string} message - Primary error text (HTTP message or generic).
      * @param {{ status: number; debug?: ApiRequestDebugInfo }} response - Failed API response.
-     * @returns {string} Message plus indented Request details for troubleshooting.
+     * @returns {string} Message alone in production, or message plus indented
+     *   Request details when running in dev/debug mode.
      */
     private formatApiFailure;
 }

package/dist/lib/base-command.js

@@ -4,8 +4,8 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { ApiClient } from './api-client.js';
 import { loadConfig } from './config.js';
-import { API_ENDPOINTS } from './constants.js';
-import { ERRORS, INFO, PROMPTS, recordLabel, VALIDATION } from './messages.js';
+import { API_ENDPOINTS, IS_DEV_MODE } from './constants.js';
+import { ERRORS, INFO, PROMPTS, quotaExhaustedMessage, recordLabel, VALIDATION, } from './messages.js';
 import { loadYaml, saveYaml } from './yaml-config.js';
 export const FREE_TIER = 'free';
 /**
@@ -107,6 +107,35 @@ export class BaseCommand extends Command {
         }
         this.error(this.formatApiFailure(response.error || ERRORS.UNEXPECTED_API, response));
     }
+    /**
+     * Intercepts a 429 "Monthly quota exhausted" response from an AI rate-limited
+     * endpoint (analyze for `init`, email edit for `edit`) and exits with a
+     * feature-specific message that includes the server's error text, the reset
+     * date, optional retry hint, and the next-best action. Returns without
+     * exiting when the response is not a 429 so callers can fall through to
+     * `handleApiError` for non-quota failures.
+     *
+     * @param {{ status: number; error?: string; data?: unknown; debug?: ApiRequestDebugInfo }} response - The failed API response.
+     *   Must carry the parsed JSON body (`data`) so reset/retry fields can be surfaced.
+     * @param {AiQuotaFeature} feature - Which AI quota was hit. Drives the default headline + tip
+     *   shown when the server omits an explicit `error` string.
+     */
+    handleAiQuotaError(response, feature) {
+        if (response.status !== 429)
+            return;
+        const body = (response.data ?? {});
+        const isInit = feature === 'init';
+        const message = quotaExhaustedMessage({
+            defaultMessage: isInit
+                ? ERRORS.QUOTA_INIT_DEFAULT
+                : ERRORS.QUOTA_EDIT_DEFAULT,
+            limitReset: body.limitReset,
+            retryAfter: body.retryAfter,
+            serverError: typeof body.error === 'string' ? body.error : undefined,
+            tip: isInit ? ERRORS.QUOTA_INIT_TIP : ERRORS.QUOTA_EDIT_TIP,
+        });
+        this.error(this.formatApiFailure(message, response));
+    }
     async collectDomainSetupInputs(yamlConfig, skipPrompts) {
         if (skipPrompts) {
             const domain = yamlConfig.project?.domain || '';
@@ -267,16 +296,19 @@ export class BaseCommand extends Command {
             this.log(`  Full guide: ${chalk.cyan(guideUrl)}\n`);
     }
     /**
-     * Builds the terminal error string for a failed API call, appending request
-     * metadata when {@link ApiRequestDebugInfo} is available.
+     * Builds the terminal error string for a failed API call. In production only
+     * the user-facing message is returned; verbose request diagnostics (URL,
+     * status, response body, error code) are appended only when [[IS_DEV_MODE]]
+     * is true so end users never see internal request metadata.
      *
      * @param {string} message - Primary error text (HTTP message or generic).
      * @param {{ status: number; debug?: ApiRequestDebugInfo }} response - Failed API response.
-     * @returns {string} Message plus indented Request details for troubleshooting.
+     * @returns {string} Message alone in production, or message plus indented
+     *   Request details when running in dev/debug mode.
      */
     formatApiFailure(message, response) {
         const { debug, status } = response;
-        if (!debug) {
+        if (!IS_DEV_MODE || !debug) {
             return message;
         }
         return [

package/dist/lib/constants.d.ts

@@ -1,3 +1,9 @@
+/**
+ * True when the CLI is running in a dev/debug context. Verbose request
+ * diagnostics (URL, status, response body, error code) are only surfaced
+ * when this is true so end users never see internal request metadata.
+ */
+export declare const IS_DEV_MODE: boolean;
 export declare const API_BASE_URL = "https://app-vertex-debug.azurewebsites.net";
 export declare const API_ENDPOINTS: Readonly<{
     ANALYTICS: "/analytics";

package/dist/lib/constants.js

@@ -1,5 +1,11 @@
 /** Set by `bin/dev.js` when running the CLI locally (tsx bootstrap). */
 const DEV_API_BASE_URL = 'https://app-vertex-debug.azurewebsites.net';
+/**
+ * True when the CLI is running in a dev/debug context. Verbose request
+ * diagnostics (URL, status, response body, error code) are only surfaced
+ * when this is true so end users never see internal request metadata.
+ */
+export const IS_DEV_MODE = Boolean(process.env.MAILMODO_DEV_TSX || process.env.MAILMODO_DEBUG);
 // const PRODUCTION_API_BASE_URL = 'https://api.mailmodo.com';
 const PRODUCTION_API_BASE_URL = 'https://app-vertex-debug.azurewebsites.net';
 export const API_BASE_URL = process.env.MAILMODO_DEV_TSX

package/dist/lib/messages.d.ts

@@ -19,6 +19,10 @@ export declare const ERRORS: {
     readonly INVALID_API_KEY: `Invalid API key. Run ${string} to re-authenticate.`;
     readonly NOT_LOGGED_IN: `Not logged in. Run ${string} to authenticate.`;
     readonly NO_YAML: `No mailmodo.yaml found. Run ${string} first.`;
+    readonly QUOTA_EDIT_DEFAULT: "Edit limit reached for this month.";
+    readonly QUOTA_EDIT_TIP: "AI edits are limited to 50 per account per month. Manually edit the template file under ./mailmodo to make further changes.";
+    readonly QUOTA_INIT_DEFAULT: "Regeneration limit reached.";
+    readonly QUOTA_INIT_TIP: `Regenerations are limited to 5 per account per month. Run ${string} to modify individual emails instead.`;
     readonly RATE_LIMIT: "Rate limit exceeded. Please try again later.";
     readonly UNEXPECTED_API: "An unexpected API error occurred.";
 };
@@ -37,3 +41,26 @@ export declare const INFO: {
 };
 export declare function yamlParseError(detail: string): string;
 export declare function recordLabel(index: number): string;
+/**
+ * Parses an ISO-8601 timestamp into a `YYYY-MM-DD` date string.
+ * Returns the raw input if parsing fails so the original value is preserved.
+ */
+export declare function formatQuotaResetDate(value?: string): string | undefined;
+/**
+ * Formats a `retry-after` value (seconds) into a short, human-readable hint
+ * suitable for appending to a 429 error message.
+ */
+export declare function formatRetryAfter(seconds?: number): string | undefined;
+/**
+ * Builds the multi-line message printed when an AI quota (init regeneration or
+ * edit) is exhausted. `serverError` is the message returned by the API; the
+ * default text is used when the server omits it. The tip lists the next action
+ * the user can take (e.g. switch from init to edit).
+ */
+export declare function quotaExhaustedMessage(input: {
+    defaultMessage: string;
+    limitReset?: string;
+    retryAfter?: number;
+    serverError?: string;
+    tip: string;
+}): string;

package/dist/lib/messages.js

@@ -20,6 +20,10 @@ export const ERRORS = {
     INVALID_API_KEY: `Invalid API key. Run ${chalk.cyan('mailmodo login')} to re-authenticate.`,
     NOT_LOGGED_IN: `Not logged in. Run ${chalk.cyan('mailmodo login')} to authenticate.`,
     NO_YAML: `No mailmodo.yaml found. Run ${chalk.cyan('mailmodo init')} first.`,
+    QUOTA_EDIT_DEFAULT: 'Edit limit reached for this month.',
+    QUOTA_EDIT_TIP: 'AI edits are limited to 50 per account per month. Manually edit the template file under ./mailmodo to make further changes.',
+    QUOTA_INIT_DEFAULT: 'Regeneration limit reached.',
+    QUOTA_INIT_TIP: `Regenerations are limited to 5 per account per month. Run ${chalk.cyan('mailmodo edit <id>')} to modify individual emails instead.`,
     RATE_LIMIT: 'Rate limit exceeded. Please try again later.',
     UNEXPECTED_API: 'An unexpected API error occurred.',
 };
@@ -42,3 +46,56 @@ export function recordLabel(index) {
     const labels = ['DKIM', 'DMARC', 'Return Path'];
     return labels[index] || `Record ${index + 1}`;
 }
+/**
+ * Parses an ISO-8601 timestamp into a `YYYY-MM-DD` date string.
+ * Returns the raw input if parsing fails so the original value is preserved.
+ */
+export function formatQuotaResetDate(value) {
+    if (!value)
+        return undefined;
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime()))
+        return value;
+    const year = parsed.getUTCFullYear();
+    const month = String(parsed.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(parsed.getUTCDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+}
+/**
+ * Formats a `retry-after` value (seconds) into a short, human-readable hint
+ * suitable for appending to a 429 error message.
+ */
+export function formatRetryAfter(seconds) {
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0)
+        return undefined;
+    if (seconds < 60)
+        return `${Math.round(seconds)} seconds`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} minutes`;
+    const hours = Math.round(seconds / 3600);
+    if (hours < 24)
+        return `${hours} hours`;
+    const days = Math.round(seconds / 86_400);
+    return `${days} days`;
+}
+/**
+ * Builds the multi-line message printed when an AI quota (init regeneration or
+ * edit) is exhausted. `serverError` is the message returned by the API; the
+ * default text is used when the server omits it. The tip lists the next action
+ * the user can take (e.g. switch from init to edit).
+ */
+export function quotaExhaustedMessage(input) {
+    const headline = input.serverError || input.defaultMessage;
+    const lines = [headline];
+    const resetDate = formatQuotaResetDate(input.limitReset);
+    if (resetDate && !headline.includes(resetDate)) {
+        lines.push(`Resets on ${resetDate}.`);
+    }
+    const retryHint = formatRetryAfter(input.retryAfter);
+    if (retryHint) {
+        lines.push(`Try again in ${retryHint}.`);
+    }
+    lines.push('', input.tip);
+    return lines.join('\n');
+}

package/oclif.manifest.json

@@ -365,12 +365,13 @@
         "index.js"
       ]
     },
-    "logout": {
+    "login": {
       "aliases": [],
       "args": {},
-      "description": "Sign out by removing saved credentials from this machine",
+      "description": "Authenticate with Mailmodo using your API key",
       "examples": [
-        "<%= config.bin %> logout"
+        "<%= config.bin %> login",
+        "MAILMODO_API_KEY=YOUR_API_KEY <%= config.bin %> login"
       ],
       "flags": {
         "json": {
@@ -389,7 +390,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "logout",
+      "id": "login",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -399,17 +400,16 @@
       "relativePath": [
         "dist",
         "commands",
-        "logout",
+        "login",
         "index.js"
       ]
     },
-    "login": {
+    "logout": {
       "aliases": [],
       "args": {},
-      "description": "Authenticate with Mailmodo using your API key",
+      "description": "Sign out by removing saved credentials from this machine",
       "examples": [
-        "<%= config.bin %> login",
-        "MAILMODO_API_KEY=YOUR_API_KEY <%= config.bin %> login"
+        "<%= config.bin %> logout"
       ],
       "flags": {
         "json": {
@@ -428,7 +428,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "login",
+      "id": "logout",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -438,23 +438,19 @@
       "relativePath": [
         "dist",
         "commands",
-        "login",
+        "logout",
         "index.js"
       ]
     },
-    "preview": {
+    "logs": {
       "aliases": [],
-      "args": {
-        "id": {
-          "description": "Email template ID to preview",
-          "name": "id"
-        }
-      },
-      "description": "Preview an email in browser, as text, or send a test",
+      "args": {},
+      "description": "View email send logs and delivery events",
       "examples": [
-        "<%= config.bin %> preview welcome",
-        "<%= config.bin %> preview welcome --text",
-        "<%= config.bin %> preview welcome --send me@example.com"
+        "<%= config.bin %> logs",
+        "<%= config.bin %> logs --email sarah@example.com",
+        "<%= config.bin %> logs --failed",
+        "<%= config.bin %> logs --json"
       ],
       "flags": {
         "json": {
@@ -470,23 +466,39 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "send": {
-          "description": "Send test email to this address",
-          "name": "send",
+        "email": {
+          "description": "Filter logs by contact email",
+          "name": "email",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "text": {
-          "description": "Output plain text version (for AI agents)",
-          "name": "text",
+        "failed": {
+          "description": "Show only failed/bounced events",
+          "name": "failed",
           "allowNo": false,
           "type": "boolean"
+        },
+        "limit": {
+          "description": "Entries per page (max 200)",
+          "name": "limit",
+          "default": 50,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "page": {
+          "description": "Page number",
+          "name": "page",
+          "default": 1,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "preview",
+      "id": "logs",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -496,19 +508,23 @@
       "relativePath": [
         "dist",
         "commands",
-        "preview",
+        "logs",
         "index.js"
       ]
     },
-    "logs": {
+    "preview": {
       "aliases": [],
-      "args": {},
-      "description": "View email send logs and delivery events",
+      "args": {
+        "id": {
+          "description": "Email template ID to preview",
+          "name": "id"
+        }
+      },
+      "description": "Preview an email in browser, as text, or send a test",
       "examples": [
-        "<%= config.bin %> logs",
-        "<%= config.bin %> logs --email sarah@example.com",
-        "<%= config.bin %> logs --failed",
-        "<%= config.bin %> logs --json"
+        "<%= config.bin %> preview welcome",
+        "<%= config.bin %> preview welcome --text",
+        "<%= config.bin %> preview welcome --send me@example.com"
       ],
       "flags": {
         "json": {
@@ -524,39 +540,23 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "email": {
-          "description": "Filter logs by contact email",
-          "name": "email",
+        "send": {
+          "description": "Send test email to this address",
+          "name": "send",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
-        "failed": {
-          "description": "Show only failed/bounced events",
-          "name": "failed",
+        "text": {
+          "description": "Output plain text version (for AI agents)",
+          "name": "text",
           "allowNo": false,
           "type": "boolean"
-        },
-        "limit": {
-          "description": "Entries per page (max 200)",
-          "name": "limit",
-          "default": 50,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
-        },
-        "page": {
-          "description": "Page number",
-          "name": "page",
-          "default": 1,
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "logs",
+      "id": "preview",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -566,7 +566,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "logs",
+        "preview",
         "index.js"
       ]
     },
@@ -657,5 +657,5 @@
       ]
     }
   },
-  "version": "0.0.49"
+  "version": "0.0.50"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mailmodo/cli",
   "description": "Email lifecycle automation for the AI-native builder generation.",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "author": "provishalk",
   "bin": {
     "mailmodo": "bin/run.js"