@mailmodo/cli 0.0.56-beta.pr58.100 → 0.0.56-beta.pr58.102

package/dist/commands/init/index.js

@@ -1,7 +1,7 @@
 import { Flags } from '@oclif/core';
 import { BaseCommand } from '../../lib/base-command.js';
 import { API_ENDPOINTS } from '../../lib/constants.js';
-import { loadYaml, saveYaml } from '../../lib/yaml-config.js';
+import { loadYaml, saveYaml, } from '../../lib/yaml-config.js';
 import { analyzeProduct, promptProductUrl, } from '../../lib/commands/init/analysis.js';
 import { confirmOverwrite, logInitSuccess, } from '../../lib/commands/init/output.js';
 import { applyMonthlyCap, buildEmailConfigs, buildYamlConfig, preserveUserFields, saveAllTemplates, } from '../../lib/commands/init/payload.js';
@@ -20,10 +20,12 @@ export default class Init extends BaseCommand {
         await this.ensureAuth();
         const ctx = this.makeCtx();
         const baseFlags = { json: flags.json, yes: flags.yes };
+        let serverYaml = null;
         if (this.isBlankDirectory()) {
-            const restored = await this.promptInitServerRestore(baseFlags);
-            if (restored)
+            const result = await this.promptInitServerRestore(baseFlags);
+            if (result.restored)
                 return;
+            serverYaml = result.serverYaml;
         }
         const existing = await loadYaml();
         if (!(await confirmOverwrite(ctx, baseFlags, existing)))
@@ -38,8 +40,9 @@ export default class Init extends BaseCommand {
         const generatedEmails = generateResponse.data?.emails || [];
         const emailConfigs = buildEmailConfigs(analysisPayload, generatedEmails);
         const yamlConfig = buildYamlConfig(analysisPayload, emailConfigs, productUrl);
-        if (existing)
-            preserveUserFields(yamlConfig, existing);
+        const fieldSource = existing ?? serverYaml;
+        if (fieldSource)
+            preserveUserFields(yamlConfig, fieldSource);
         await saveYaml(yamlConfig);
         await applyMonthlyCap(ctx, yamlConfig);
         await saveAllTemplates(analysisPayload.recommendedEmails, generatedEmails);

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

@@ -0,0 +1,22 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class Report extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        contact: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'email-id': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        event: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        from: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'group-by': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        page: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        preset: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        sequence: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        to: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private makeCtx;
+}

package/dist/commands/report/index.js

@@ -0,0 +1,123 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../lib/base-command.js';
+import { API_ENDPOINTS } from '../../lib/constants.js';
+import { REPORTS } from '../../lib/messages.js';
+import { buildReportPayload } from '../../lib/commands/report/payload.js';
+import { renderReport } from '../../lib/commands/report/output.js';
+import { promptReportFlags } from '../../lib/commands/report/prompt.js';
+export default class Report extends BaseCommand {
+    static description = 'Fetch an email analytics report';
+    static examples = [
+        '<%= config.bin %> report --preset last7d',
+        '<%= config.bin %> report --preset last30d --group-by emailId',
+        '<%= config.bin %> report --from YYYY-MM-DD --to YYYY-MM-DD --output timeseries',
+        '<%= config.bin %> report --preset last7d --output entries --page 1',
+        '<%= config.bin %> report --preset last30d --sequence welcome-flow --event opened',
+        '<%= config.bin %> report --preset last7d --json',
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        contact: Flags.string({
+            description: 'Filter by contact email (repeatable)',
+            multiple: true,
+        }),
+        'email-id': Flags.string({
+            description: 'Filter by email template ID (repeatable)',
+            multiple: true,
+        }),
+        event: Flags.string({
+            description: 'Filter by event type (repeatable)',
+            multiple: true,
+            options: [
+                'bounced',
+                'clicked',
+                'complained',
+                'delivered',
+                'opened',
+                'sent',
+                'skipped',
+                'unsubscribed',
+            ],
+        }),
+        from: Flags.string({
+            description: 'Start of time range, inclusive (YYYY-MM-DD)',
+            exclusive: ['preset'],
+        }),
+        'group-by': Flags.string({
+            default: 'none',
+            description: 'Group results by dimension',
+            options: [
+                'contact',
+                'day',
+                'emailId',
+                'hour',
+                'none',
+                'sequenceId',
+                'status',
+            ],
+        }),
+        limit: Flags.integer({
+            default: 50,
+            description: 'Entries per page, max 200 (entries output only)',
+            max: 200,
+        }),
+        output: Flags.string({
+            default: 'summary',
+            description: 'Output shape: summary | entries | timeseries',
+            options: ['entries', 'summary', 'timeseries'],
+        }),
+        page: Flags.integer({
+            default: 1,
+            description: 'Page number (entries output only)',
+        }),
+        preset: Flags.string({
+            description: 'Relative time range preset',
+            exclusive: ['from', 'to'],
+            options: [
+                'last30d',
+                'last7d',
+                'last90d',
+                'lastMonth',
+                'thisMonth',
+                'today',
+                'yesterday',
+            ],
+        }),
+        sequence: Flags.string({
+            description: 'Filter by sequence ID (repeatable)',
+            multiple: true,
+        }),
+        to: Flags.string({
+            description: 'End of time range, exclusive (YYYY-MM-DD)',
+            exclusive: ['preset'],
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Report);
+        await this.ensureAuth();
+        if ((flags.from && !flags.to) || (!flags.from && flags.to)) {
+            this.error(REPORTS.FROM_TO_REQUIRED);
+        }
+        const resolved = flags.json
+            ? flags
+            : await promptReportFlags(flags);
+        const ctx = this.makeCtx();
+        const payload = buildReportPayload(resolved, (m) => this.error(m));
+        const response = await ctx.spinner(REPORTS.FETCH_SPINNER, flags.json, () => ctx.post(API_ENDPOINTS.REPORTS, payload));
+        if (!response.ok)
+            ctx.onApiError(response);
+        if (flags.json) {
+            this.log(JSON.stringify(response.data, null, 2));
+            return;
+        }
+        renderReport(ctx, response.data, resolved.output);
+    }
+    makeCtx() {
+        return {
+            log: (msg) => this.log(msg),
+            onApiError: (r) => this.handleApiError(r),
+            post: (path, body) => this.apiClient.post(path, body),
+            spinner: (text, json, work) => this.withApiSpinner({ json, text }, work),
+        };
+    }
+}

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

@@ -74,7 +74,10 @@ export declare abstract class BaseCommand extends Command {
     protected promptInitServerRestore(flags: {
         json?: boolean;
         yes?: boolean;
-    }): Promise<boolean>;
+    }): Promise<{
+        restored: boolean;
+        serverYaml: MailmodoYaml | null;
+    }>;
     private fetchAndWriteYaml;
     /**
      * Attempts to fetch mailmodo.yaml from the server and save it locally.

package/dist/lib/base-command.js

@@ -11,7 +11,7 @@ import { API_ENDPOINTS, IS_DEV_MODE, TEMPLATES_DIR, YAML_FILE, } from './constan
 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, saveYaml } from './yaml-config.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.
@@ -151,7 +151,7 @@ export class BaseCommand extends Command {
     async promptInitServerRestore(flags) {
         const yamlText = await this.fetchYamlText();
         if (!yamlText)
-            return false;
+            return { restored: false, serverYaml: null };
         let shouldRestore = Boolean(flags.yes || flags.json);
         if (!shouldRestore) {
             const choice = await select({
@@ -163,17 +163,18 @@ export class BaseCommand extends Command {
             });
             shouldRestore = choice === 'restore';
         }
-        if (!shouldRestore)
-            return false;
+        if (!shouldRestore) {
+            return { restored: false, serverYaml: parseYamlText(yamlText) };
+        }
         await writeFile(join(process.cwd(), YAML_FILE), yamlText);
         const yaml = await loadYaml();
         if (!yaml)
-            return false;
+            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 true;
+        return { restored: true, serverYaml: yaml };
     }
     async fetchAndWriteYaml(client) {
         try {

package/dist/lib/commands/report/output-entries.d.ts

@@ -0,0 +1,2 @@
+import type { EntriesResponse, ReportCtx } from './types.js';
+export declare function renderEntries(ctx: ReportCtx, data: EntriesResponse): void;

package/dist/lib/commands/report/output-entries.js

@@ -0,0 +1,48 @@
+import chalk from 'chalk';
+function statusColor(status) {
+    switch (status) {
+        case 'bounced':
+        case 'complained': {
+            return chalk.red;
+        }
+        case 'clicked':
+        case 'delivered':
+        case 'opened':
+        case 'sent': {
+            return chalk.green;
+        }
+        case 'skipped': {
+            return chalk.yellow;
+        }
+        default: {
+            return chalk.white;
+        }
+    }
+}
+export function renderEntries(ctx, data) {
+    const { entries, limit, page, total } = data;
+    ctx.log(`\n  ${'Time'.padEnd(22)}${'Email'.padEnd(24)}${'Sequence'.padEnd(20)}${'Status'.padEnd(12)}Contact`);
+    ctx.log(`  ${'─'.repeat(90)}`);
+    if (!entries?.length) {
+        ctx.log(`  ${chalk.dim('No entries found.')}`);
+        ctx.log('');
+        return;
+    }
+    for (const entry of entries) {
+        const time = (entry.timestamp || '').padEnd(22);
+        const emailId = (entry.emailId || '').padEnd(24);
+        const seqId = (entry.sequenceId || '').padEnd(20);
+        const colorFn = statusColor(entry.status);
+        const status = colorFn((entry.status || '').padEnd(12));
+        ctx.log(`  ${time}${emailId}${seqId}${status}${entry.contact || ''}`);
+        if (entry.reason) {
+            const label = entry.status === 'skipped' ? 'condition not met' : 'reason';
+            ctx.log(`  ${' '.repeat(78)}${chalk.dim(`(${label}: ${entry.reason})`)}`);
+        }
+    }
+    const totalPages = Math.ceil(total / limit);
+    ctx.log(`\n  Page ${page} of ${totalPages}  ·  ${total} total entries`);
+    if (page < totalPages)
+        ctx.log(`  ${chalk.dim(`Next: --page ${page + 1}`)}`);
+    ctx.log('');
+}

package/dist/lib/commands/report/output-timeseries.d.ts

@@ -0,0 +1,2 @@
+import type { ReportCtx, TimeseriesResponse } from './types.js';
+export declare function renderTimeseries(ctx: ReportCtx, data: TimeseriesResponse): void;

package/dist/lib/commands/report/output-timeseries.js

@@ -0,0 +1,28 @@
+import chalk from 'chalk';
+function fmtRate(n) {
+    return (n * 100).toFixed(1) + '%';
+}
+export function renderTimeseries(ctx, data) {
+    const { bucket, series, timeRange } = data;
+    const from = timeRange.from.slice(0, 10);
+    const to = timeRange.to.slice(0, 10);
+    ctx.log(`\n  ${chalk.dim(`Bucket: ${bucket}  (${from} → ${to})`)}`);
+    ctx.log(`\n  ${'Time'.padEnd(22)}${'Sent'.padEnd(7)}${'Delivered'.padEnd(11)}${'Opened'.padEnd(8)}${'Clicked'.padEnd(9)}${'OpenRate'.padEnd(10)}${'ClickRate'.padEnd(10)}BounceRate`);
+    ctx.log(`  ${'─'.repeat(87)}`);
+    if (!series?.length) {
+        ctx.log(`  ${chalk.dim('No timeseries data.')}`);
+        ctx.log('');
+        return;
+    }
+    for (const point of series) {
+        ctx.log(`  ${(point.ts || '').padEnd(22)}` +
+            `${String(point.sent).padEnd(7)}` +
+            `${String(point.delivered).padEnd(11)}` +
+            `${String(point.opened).padEnd(8)}` +
+            `${String(point.clicked).padEnd(9)}` +
+            `${fmtRate(point.openRate).padEnd(10)}` +
+            `${fmtRate(point.clickRate).padEnd(10)}` +
+            `${fmtRate(point.bounceRate)}`);
+    }
+    ctx.log('');
+}

package/dist/lib/commands/report/output.d.ts

@@ -0,0 +1,3 @@
+import type { ReportCtx, ReportResponse, SummaryResponse } from './types.js';
+export declare function renderSummary(ctx: ReportCtx, data: SummaryResponse): void;
+export declare function renderReport(ctx: ReportCtx, data: ReportResponse, mode: string): void;

package/dist/lib/commands/report/output.js

@@ -0,0 +1,56 @@
+import chalk from 'chalk';
+import { renderEntries } from './output-entries.js';
+import { renderTimeseries } from './output-timeseries.js';
+function fmtRate(n) {
+    return (n * 100).toFixed(1) + '%';
+}
+function statsColumns(s) {
+    return [
+        String(s.sent).padEnd(7),
+        String(s.delivered).padEnd(11),
+        String(s.opened).padEnd(8),
+        String(s.clicked).padEnd(9),
+        String(s.bounced).padEnd(9),
+        fmtRate(s.openRate).padEnd(10),
+        fmtRate(s.clickRate).padEnd(10),
+        fmtRate(s.bounceRate),
+    ].join('');
+}
+function renderGroupedTable(ctx, data) {
+    ctx.log(`\n  ${'Key'.padEnd(20)}${'Sent'.padEnd(7)}${'Delivered'.padEnd(11)}` +
+        `${'Opened'.padEnd(8)}${'Clicked'.padEnd(9)}${'Bounced'.padEnd(9)}` +
+        `${'OpenRate'.padEnd(10)}${'ClickRate'.padEnd(10)}BounceRate`);
+    ctx.log(`  ${'─'.repeat(93)}`);
+    for (const g of data.groups) {
+        const key = g.key.slice(0, 19).padEnd(20);
+        ctx.log(`  ${key}${statsColumns(g)}`);
+    }
+    ctx.log(`  ${'─'.repeat(93)}`);
+    ctx.log(`  ${chalk.bold('TOTAL'.padEnd(20))}${statsColumns(data.totals)}`);
+}
+function renderTotalsOnly(ctx, data) {
+    const t = data.totals;
+    ctx.log(`\n  Sent: ${t.sent}   Delivered: ${t.delivered}   Opened: ${t.opened}` +
+        `   Clicked: ${t.clicked}   Bounced: ${t.bounced}`);
+    ctx.log(`  Open rate: ${fmtRate(t.openRate)}   Click rate: ${fmtRate(t.clickRate)}` +
+        `   Bounce rate: ${fmtRate(t.bounceRate)}`);
+}
+export function renderSummary(ctx, data) {
+    const { from, to } = data.timeRange;
+    ctx.log(`\n  ${chalk.dim(`${from.slice(0, 10)} → ${to.slice(0, 10)}`)}`);
+    if (data.groups.length > 0) {
+        renderGroupedTable(ctx, data);
+    }
+    else {
+        renderTotalsOnly(ctx, data);
+    }
+    ctx.log('');
+}
+export function renderReport(ctx, data, mode) {
+    if (mode === 'entries')
+        renderEntries(ctx, data);
+    else if (mode === 'timeseries')
+        renderTimeseries(ctx, data);
+    else
+        renderSummary(ctx, data);
+}

package/dist/lib/commands/report/payload.d.ts

@@ -0,0 +1,2 @@
+import type { ReportFlags, ReportPayload } from './types.js';
+export declare function buildReportPayload(flags: ReportFlags, onError: (m: string) => never): ReportPayload;

package/dist/lib/commands/report/payload.js

@@ -0,0 +1,49 @@
+import { REPORTS } from '../../messages.js';
+function buildTimeRange(flags) {
+    if (flags.preset)
+        return { preset: flags.preset };
+    if (flags.from && flags.to)
+        return { from: flags.from, to: flags.to };
+    return undefined;
+}
+function buildFilters(flags) {
+    const f = {};
+    if (flags.sequence?.length)
+        f.sequenceIds = flags.sequence;
+    if (flags['email-id']?.length)
+        f.emailIds = flags['email-id'];
+    if (flags.contact?.length)
+        f.contactEmails = flags.contact;
+    if (flags.event?.length)
+        f.events = flags.event;
+    return Object.keys(f).length > 0 ? f : undefined;
+}
+function validateFilterSizes(flags, onError) {
+    const arrays = [
+        flags.sequence,
+        flags['email-id'],
+        flags.contact,
+        flags.event,
+    ];
+    if (arrays.some((a) => a && a.length > 100))
+        onError(REPORTS.TOO_MANY_ITEMS);
+}
+export function buildReportPayload(flags, onError) {
+    validateFilterSizes(flags, onError);
+    const timeRange = buildTimeRange(flags);
+    if (!timeRange)
+        onError(REPORTS.TIME_RANGE_REQUIRED);
+    const payload = {
+        groupBy: flags['group-by'],
+        output: flags.output,
+        timeRange,
+    };
+    const filters = buildFilters(flags);
+    if (filters)
+        payload.filters = filters;
+    if (flags.output === 'entries') {
+        payload.page = flags.page;
+        payload.limit = flags.limit;
+    }
+    return payload;
+}

package/dist/lib/commands/report/prompt.d.ts

@@ -0,0 +1,2 @@
+import type { ReportFlags } from './types.js';
+export declare function promptReportFlags(flags: ReportFlags): Promise<ReportFlags>;

package/dist/lib/commands/report/prompt.js

@@ -0,0 +1,80 @@
+import { input, select } from '@inquirer/prompts';
+const PRESET_CHOICES = [
+    { name: 'Today', value: 'today' },
+    { name: 'Yesterday', value: 'yesterday' },
+    { name: 'Last 7 days', value: 'last7d' },
+    { name: 'Last 30 days', value: 'last30d' },
+    { name: 'Last 90 days', value: 'last90d' },
+    { name: 'This month', value: 'thisMonth' },
+    { name: 'Last month', value: 'lastMonth' },
+];
+const OUTPUT_CHOICES = [
+    { name: 'Summary — grouped aggregates', value: 'summary' },
+    { name: 'Entries — paginated event log', value: 'entries' },
+    { name: 'Timeseries — bucketed over time', value: 'timeseries' },
+];
+const GROUP_BY_CHOICES = [
+    { name: 'None (totals only)', value: 'none' },
+    { name: 'Email ID', value: 'emailId' },
+    { name: 'Sequence ID', value: 'sequenceId' },
+    { name: 'Day', value: 'day' },
+    { name: 'Hour', value: 'hour' },
+    { name: 'Contact', value: 'contact' },
+    { name: 'Status', value: 'status' },
+];
+function isValidIsoDate(value) {
+    if (!value?.trim())
+        return 'Date is required';
+    if (Number.isNaN(new Date(value).getTime()))
+        return 'Enter a valid date in YYYY-MM-DD format';
+    return true;
+}
+async function promptTimeRange() {
+    const usePreset = await select({
+        choices: [
+            { name: 'Use a preset  (today, last7d, last30d…)', value: true },
+            { name: 'Enter a custom date range', value: false },
+        ],
+        message: 'Time range:',
+    });
+    if (usePreset) {
+        const preset = await select({
+            choices: PRESET_CHOICES,
+            message: 'Preset:',
+        });
+        return { preset };
+    }
+    const from = await input({
+        message: 'Start date (YYYY-MM-DD):',
+        validate: isValidIsoDate,
+    });
+    const to = await input({
+        message: 'End date, exclusive (YYYY-MM-DD):',
+        validate(v) {
+            const check = isValidIsoDate(v);
+            if (check !== true)
+                return check;
+            if (new Date(v) <= new Date(from))
+                return 'End date must be after start date';
+            return true;
+        },
+    });
+    return { from, to };
+}
+export async function promptReportFlags(flags) {
+    const hasTimeRange = Boolean(flags.preset || (flags.from && flags.to));
+    if (hasTimeRange)
+        return flags;
+    const timeRange = await promptTimeRange();
+    const output = await select({
+        choices: OUTPUT_CHOICES,
+        default: flags.output,
+        message: 'Output mode:',
+    });
+    const groupBy = await select({
+        choices: GROUP_BY_CHOICES,
+        default: flags['group-by'],
+        message: 'Group by:',
+    });
+    return { ...flags, ...timeRange, 'group-by': groupBy, output };
+}

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

@@ -0,0 +1,97 @@
+import type { ApiResponse } from '../../api-client.js';
+export interface ReportFilters {
+    contactEmails?: string[];
+    emailIds?: string[];
+    events?: string[];
+    sequenceIds?: string[];
+}
+export type ReportTimeRange = {
+    from: string;
+    to: string;
+} | {
+    preset: string;
+};
+export interface ReportPayload {
+    filters?: ReportFilters;
+    groupBy: string;
+    limit?: number;
+    output: string;
+    page?: number;
+    timeRange?: ReportTimeRange;
+}
+export interface ReportGroup {
+    bounceRate: number;
+    bounced: number;
+    clickRate: number;
+    clicked: number;
+    complained: number;
+    delivered: number;
+    key: string;
+    openRate: number;
+    opened: number;
+    sent: number;
+    skipped: number;
+    unsubscribed: number;
+}
+export type ReportTotals = Omit<ReportGroup, 'key'>;
+export interface SummaryResponse {
+    groupBy: string;
+    groups: ReportGroup[];
+    timeRange: {
+        from: string;
+        to: string;
+    };
+    totals: ReportTotals;
+}
+export interface EntryRecord {
+    contact: string;
+    emailId: string;
+    reason?: null | string;
+    sequenceId: string;
+    status: string;
+    timestamp: string;
+}
+export interface EntriesResponse {
+    entries: EntryRecord[];
+    limit: number;
+    page: number;
+    timeRange: {
+        from: string;
+        to: string;
+    };
+    total: number;
+}
+export type TimeseriesPoint = ReportTotals & {
+    ts: string;
+};
+export interface TimeseriesResponse {
+    bucket: string;
+    series: TimeseriesPoint[];
+    timeRange: {
+        from: string;
+        to: string;
+    };
+}
+export type ReportResponse = EntriesResponse | SummaryResponse | TimeseriesResponse;
+export type ReportFlags = {
+    contact?: string[];
+    'email-id'?: string[];
+    event?: string[];
+    from?: string;
+    'group-by': string;
+    limit: number;
+    output: string;
+    page: number;
+    preset?: string;
+    sequence?: string[];
+    to?: string;
+};
+export type ReportCtx = {
+    log(msg?: string): void;
+    onApiError(resp: {
+        error?: string;
+        status: number;
+    }): never;
+    post<T = Record<string, unknown>>(path: string, body?: unknown): Promise<ApiResponse<T>>;
+    spinner<T>(text: string, json: boolean, work: () => Promise<T>): Promise<T>;
+};

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

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

package/dist/lib/constants.d.ts

@@ -26,6 +26,7 @@ export declare const API_ENDPOINTS: Readonly<{
     GENERATE: "/email/generate";
     LOGS: "/logs";
     PREVIEW: "/preview";
+    REPORTS: "/reports";
     SEQUENCES: "/sequences";
     SEQUENCES_DEPLOY: "/sequences/deploy";
     SEQUENCES_SDK: "/sequences/sdk";

package/dist/lib/constants.js

@@ -31,6 +31,7 @@ export const API_ENDPOINTS = Object.freeze({
     GENERATE: '/email/generate',
     LOGS: '/logs',
     PREVIEW: '/preview',
+    REPORTS: '/reports',
     SEQUENCES: '/sequences',
     SEQUENCES_DEPLOY: '/sequences/deploy',
     SEQUENCES_SDK: '/sequences/sdk',

package/dist/lib/messages.d.ts

@@ -14,7 +14,7 @@ export declare const PROMPTS: {
     readonly SENDER_EMAIL: "Sender email address:";
 };
 export declare const BLANK_DIR: {
-    readonly CHOICE_FRESH: "Start fresh — create a new project here";
+    readonly CHOICE_FRESH: "Start fresh — new emails will be generated (your domain, sender, and address settings will be kept)";
     readonly CHOICE_RESTORE: "Restore project files from server";
     readonly CHOICE_RESTORE_INIT: "Restore existing project files from server";
     readonly CHOICE_SKIP: "Skip — I'll navigate to my project directory manually";
@@ -64,6 +64,13 @@ export declare const INFO: {
     readonly YAML_RESTORED_FROM_SERVER: string;
     readonly YAML_RESTORED_ON_LOGIN: `  mailmodo.yaml restored from server. Run ${string} to re-deploy your sequences.`;
 };
+export declare const REPORTS: {
+    readonly FETCH_SPINNER: "  Fetching report...";
+    readonly FROM_TO_REQUIRED: "--from and --to must both be provided together.";
+    readonly NO_DATA: "No data found for the given filters and time range.";
+    readonly TIME_RANGE_REQUIRED: "A time range is required. Use --preset or --from/--to.";
+    readonly TOO_MANY_ITEMS: "Filter arrays cannot exceed 100 items each.";
+};
 export declare const DEPLOY: {
     readonly CHANGES_HEADER: "Changes vs. last deployment:";
     readonly DEPLOYING_HEADER: "Deploying:";

package/dist/lib/messages.js

@@ -15,7 +15,7 @@ export const PROMPTS = {
     SENDER_EMAIL: 'Sender email address:',
 };
 export const BLANK_DIR = {
-    CHOICE_FRESH: 'Start fresh — create a new project here',
+    CHOICE_FRESH: 'Start fresh — new emails will be generated (your domain, sender, and address settings will be kept)',
     CHOICE_RESTORE: 'Restore project files from server',
     CHOICE_RESTORE_INIT: 'Restore existing project files from server',
     CHOICE_SKIP: "Skip — I'll navigate to my project directory manually",
@@ -64,6 +64,13 @@ export const INFO = {
     YAML_RESTORED_FROM_SERVER: chalk.dim('  mailmodo.yaml not found locally — restored from server.'),
     YAML_RESTORED_ON_LOGIN: `  mailmodo.yaml restored from server. Run ${chalk.cyan("'mailmodo deploy'")} to re-deploy your sequences.`,
 };
+export const REPORTS = {
+    FETCH_SPINNER: '  Fetching report...',
+    FROM_TO_REQUIRED: '--from and --to must both be provided together.',
+    NO_DATA: 'No data found for the given filters and time range.',
+    TIME_RANGE_REQUIRED: 'A time range is required. Use --preset or --from/--to.',
+    TOO_MANY_ITEMS: 'Filter arrays cannot exceed 100 items each.',
+};
 export const DEPLOY = {
     CHANGES_HEADER: 'Changes vs. last deployment:',
     DEPLOYING_HEADER: 'Deploying:',

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

@@ -44,6 +44,7 @@ export interface MailmodoYaml {
  *   formatted Error with the line number if the file contains invalid YAML syntax.
  */
 export declare function loadYaml(cwd?: string): Promise<MailmodoYaml | null>;
+export declare function parseYamlText(text: string): MailmodoYaml | null;
 /**
  * Serializes and writes the mailmodo.yaml configuration to disk.
  *

package/dist/lib/yaml-config.js

@@ -25,6 +25,14 @@ export async function loadYaml(cwd) {
         throw new Error(yamlParseError(error.message));
     }
 }
+export function parseYamlText(text) {
+    try {
+        return load(text);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Serializes and writes the mailmodo.yaml configuration to disk.
  *

package/oclif.manifest.json

@@ -426,13 +426,12 @@
         "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": {
@@ -451,7 +450,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "login",
+      "id": "logout",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -461,16 +460,17 @@
       "relativePath": [
         "dist",
         "commands",
-        "login",
+        "logout",
         "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": {
@@ -489,7 +489,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "logout",
+      "id": "login",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -499,7 +499,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "logout",
+        "login",
         "index.js"
       ]
     },
@@ -631,14 +631,17 @@
         "index.js"
       ]
     },
-    "sdk": {
+    "report": {
       "aliases": [],
       "args": {},
-      "description": "Show the SDK track() / identify() reference for deployed sequences",
+      "description": "Fetch an email analytics report",
       "examples": [
-        "<%= config.bin %> sdk",
-        "<%= config.bin %> sdk --sequence-id a1b2c3d4",
-        "<%= config.bin %> sdk --json"
+        "<%= config.bin %> report --preset last7d",
+        "<%= config.bin %> report --preset last30d --group-by emailId",
+        "<%= config.bin %> report --from YYYY-MM-DD --to YYYY-MM-DD --output timeseries",
+        "<%= config.bin %> report --preset last7d --output entries --page 1",
+        "<%= config.bin %> report --preset last30d --sequence welcome-flow --event opened",
+        "<%= config.bin %> report --preset last7d --json"
       ],
       "flags": {
         "json": {
@@ -654,9 +657,126 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "sequence-id": {
-          "description": "Limit output to a single active sequence by ID (default: all active sequences)",
-          "name": "sequence-id",
+        "contact": {
+          "description": "Filter by contact email (repeatable)",
+          "name": "contact",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "email-id": {
+          "description": "Filter by email template ID (repeatable)",
+          "name": "email-id",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "event": {
+          "description": "Filter by event type (repeatable)",
+          "name": "event",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "options": [
+            "bounced",
+            "clicked",
+            "complained",
+            "delivered",
+            "opened",
+            "sent",
+            "skipped",
+            "unsubscribed"
+          ],
+          "type": "option"
+        },
+        "from": {
+          "description": "Start of time range, inclusive (YYYY-MM-DD)",
+          "exclusive": [
+            "preset"
+          ],
+          "name": "from",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "group-by": {
+          "description": "Group results by dimension",
+          "name": "group-by",
+          "default": "none",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "contact",
+            "day",
+            "emailId",
+            "hour",
+            "none",
+            "sequenceId",
+            "status"
+          ],
+          "type": "option"
+        },
+        "limit": {
+          "description": "Entries per page, max 200 (entries output only)",
+          "name": "limit",
+          "default": 50,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "output": {
+          "description": "Output shape: summary | entries | timeseries",
+          "name": "output",
+          "default": "summary",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "entries",
+            "summary",
+            "timeseries"
+          ],
+          "type": "option"
+        },
+        "page": {
+          "description": "Page number (entries output only)",
+          "name": "page",
+          "default": 1,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "preset": {
+          "description": "Relative time range preset",
+          "exclusive": [
+            "from",
+            "to"
+          ],
+          "name": "preset",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "last30d",
+            "last7d",
+            "last90d",
+            "lastMonth",
+            "thisMonth",
+            "today",
+            "yesterday"
+          ],
+          "type": "option"
+        },
+        "sequence": {
+          "description": "Filter by sequence ID (repeatable)",
+          "name": "sequence",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        },
+        "to": {
+          "description": "End of time range, exclusive (YYYY-MM-DD)",
+          "exclusive": [
+            "preset"
+          ],
+          "name": "to",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -664,7 +784,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "sdk",
+      "id": "report",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -674,18 +794,18 @@
       "relativePath": [
         "dist",
         "commands",
-        "sdk",
+        "report",
         "index.js"
       ]
     },
-    "settings": {
+    "sdk": {
       "aliases": [],
       "args": {},
-      "description": "View and update project settings",
+      "description": "Show the SDK track() / identify() reference for deployed sequences",
       "examples": [
-        "<%= config.bin %> settings",
-        "<%= config.bin %> settings --set brand_color=#0F3460",
-        "<%= config.bin %> settings --json"
+        "<%= config.bin %> sdk",
+        "<%= config.bin %> sdk --sequence-id a1b2c3d4",
+        "<%= config.bin %> sdk --json"
       ],
       "flags": {
         "json": {
@@ -701,9 +821,9 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "set": {
-          "description": "Set a setting (format: key=value)",
-          "name": "set",
+        "sequence-id": {
+          "description": "Limit output to a single active sequence by ID (default: all active sequences)",
+          "name": "sequence-id",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -711,7 +831,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "settings",
+      "id": "sdk",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -721,7 +841,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "settings",
+        "sdk",
         "index.js"
       ]
     },
@@ -763,7 +883,54 @@
         "status",
         "index.js"
       ]
+    },
+    "settings": {
+      "aliases": [],
+      "args": {},
+      "description": "View and update project settings",
+      "examples": [
+        "<%= config.bin %> settings",
+        "<%= config.bin %> settings --set brand_color=#0F3460",
+        "<%= config.bin %> settings --json"
+      ],
+      "flags": {
+        "json": {
+          "description": "Output as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompts",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "set": {
+          "description": "Set a setting (format: key=value)",
+          "name": "set",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "settings",
+      "pluginAlias": "@mailmodo/cli",
+      "pluginName": "@mailmodo/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "settings",
+        "index.js"
+      ]
     }
   },
-  "version": "0.0.56-beta.pr58.100"
+  "version": "0.0.56-beta.pr58.102"
 }

package/package.json

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