npm - mailfully - Versions diffs - 0.1.0 - Mend

mailfully 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (36) hide show

package/README.md +126 -0
package/dist/bin.d.ts +2 -0
package/dist/bin.js +37 -0
package/dist/commands/analytics.d.ts +3 -0
package/dist/commands/analytics.js +97 -0
package/dist/commands/auth.d.ts +3 -0
package/dist/commands/auth.js +82 -0
package/dist/commands/domains.d.ts +3 -0
package/dist/commands/domains.js +135 -0
package/dist/commands/emails.d.ts +3 -0
package/dist/commands/emails.js +273 -0
package/dist/commands/suppressions.d.ts +9 -0
package/dist/commands/suppressions.js +44 -0
package/dist/commands/templates.d.ts +3 -0
package/dist/commands/templates.js +123 -0
package/dist/config.d.ts +30 -0
package/dist/config.js +82 -0
package/dist/context.d.ts +45 -0
package/dist/context.js +54 -0
package/dist/failure.d.ts +22 -0
package/dist/failure.js +34 -0
package/dist/flags.d.ts +3 -0
package/dist/flags.js +7 -0
package/dist/output.d.ts +15 -0
package/dist/output.js +84 -0
package/dist/pages.d.ts +42 -0
package/dist/pages.js +76 -0
package/dist/parse.d.ts +37 -0
package/dist/parse.js +92 -0
package/dist/program.d.ts +35 -0
package/dist/program.js +83 -0
package/dist/prompt.d.ts +12 -0
package/dist/prompt.js +37 -0
package/dist/version.d.ts +6 -0
package/dist/version.js +11 -0
package/package.json +63 -0

package/dist/commands/emails.js ADDED Viewed

@@ -0,0 +1,273 @@
+import { resolveContext } from "../context.js";
+import { CommandFailure, EXIT_NOTHING_SENT, unwrap } from "../failure.js";
+import { formatTable, toJson } from "../output.js";
+import { collectPair, collectString, pairsToTags, parseMessageType, readBody, readJsonFile, wireToSendInput, } from "../parse.js";
+import { withGlobalOptions } from "../flags.js";
+import { defaultSleep, renderPagedList } from "../pages.js";
+/** Attach the shared send flag set to a command (used by both registrations). */
+function configureSendCommand(cmd) {
+    return withGlobalOptions(cmd
+        .description("Send one email.")
+        .requiredOption("--from <address>", "Sender address (verified domain).")
+        .requiredOption("--to <address>", "Recipient address (repeatable).", collectString)
+        .option("--cc <address>", "Cc address (repeatable).", collectString)
+        .option("--bcc <address>", "Bcc address (repeatable).", collectString)
+        .option("--reply-to <address>", "Reply-to address (repeatable).", collectString)
+        .option("--subject <subject>", "Subject line.")
+        .option("--html <html>", "Inline HTML body.")
+        .option("--html-file <path>", "Read the HTML body from a file.")
+        .option("--text <text>", "Inline plain-text body.")
+        .option("--text-file <path>", "Read the plain-text body from a file.")
+        .option("--type <transactional|marketing>", "Message type (default: transactional, applied by the API).", parseMessageType)
+        .option("--template <id>", "Render a stored template.")
+        .option("--var <name=value>", "Template variable (repeatable).", collectPair)
+        .option("--tag <name=value>", "Message tag (repeatable).", collectPair)
+        .option("--header <name=value>", "Custom message header (repeatable).", collectPair)
+        .option("--scheduled-at <iso8601>", "Schedule delivery for a future time (up to 90 days out).")
+        .option("--idempotency-key <key>", "Idempotency key — a retry with the same key never double-sends."));
+}
+async function sendAction(opts, deps) {
+    const ctx = await resolveContext(opts, deps);
+    const html = await readBody(opts.html, opts.htmlFile, "--html");
+    const text = await readBody(opts.text, opts.textFile, "--text");
+    if (html === undefined && text === undefined && opts.template === undefined) {
+        throw new CommandFailure("Provide a body: --html/--html-file, --text/--text-file, or --template.", 2);
+    }
+    if (opts.var !== undefined && opts.template === undefined) {
+        throw new CommandFailure("--var requires --template.", 2);
+    }
+    const input = {
+        from: opts.from,
+        to: opts.to,
+        ...(opts.cc !== undefined ? { cc: opts.cc } : {}),
+        ...(opts.bcc !== undefined ? { bcc: opts.bcc } : {}),
+        ...(opts.replyTo !== undefined ? { replyTo: opts.replyTo } : {}),
+        ...(opts.subject !== undefined ? { subject: opts.subject } : {}),
+        ...(html !== undefined ? { html } : {}),
+        ...(text !== undefined ? { text } : {}),
+        ...(opts.type !== undefined ? { type: opts.type } : {}),
+        ...(opts.header !== undefined ? { headers: opts.header } : {}),
+        ...(opts.tag !== undefined ? { tags: pairsToTags(opts.tag) } : {}),
+        ...(opts.scheduledAt !== undefined
+            ? { scheduledAt: opts.scheduledAt }
+            : {}),
+        ...(opts.template !== undefined
+            ? {
+                template: {
+                    id: opts.template,
+                    ...(opts.var !== undefined ? { variables: opts.var } : {}),
+                },
+            }
+            : {}),
+    };
+    const data = unwrap(await ctx.client.emails.send(input, opts.idempotencyKey !== undefined
+        ? { idempotencyKey: opts.idempotencyKey }
+        : undefined));
+    if (ctx.json) {
+        deps.stdout.write(toJson(data));
+        // Same exit contract as the human arm — a JSON consumer in a `&&` chain
+        // deserves it just as much — but silent, so the pipe stays pure JSON.
+        if (data.status === "canceled") {
+            throw new CommandFailure("", EXIT_NOTHING_SENT);
+        }
+        return;
+    }
+    // A send drained by suppression still returns 202, carrying
+    // `status: "canceled"` — nothing will go out. Reporting that as "Accepted"
+    // tells the operator the opposite of what happened. The parenthetical is not
+    // padding: `toDrainedBySuppression` (acceptSend.ts) cancels even when a
+    // cc/bcc SURVIVES, because a suppressed `to` is never replaced by promoting
+    // one — so "all of them were suppressed" would be the wrong explanation.
+    if (data.status === "canceled") {
+        deps.stdout.write(`Canceled: ${data.id} (${ctx.environment})\n`);
+        deps.stderr.write("Canceled by suppression — no mail will be sent (a fully suppressed To cancels the send even when a Cc or Bcc survives).\n");
+        throw new CommandFailure("", EXIT_NOTHING_SENT);
+    }
+    // `status` is narrowed to the literal "queued" here. The annotation is the
+    // point: if `AcceptedEmail["status"]` ever grows a third member, this stops
+    // compiling instead of silently printing "Accepted" for it — which is the
+    // exact bug this branch was added to fix.
+    const _queuedOnly = data.status;
+    void _queuedOnly;
+    // The environment is printed on every accept line so a live key is never
+    // mistaken for a test one at the moment it matters most.
+    deps.stdout.write(`Accepted: ${data.id} (${ctx.environment})\n`);
+}
+export function registerEmailsCommands(program, deps) {
+    // Root-level alias: `mailfully send …` is the advertised quickstart form.
+    configureSendCommand(program.command("send")).action((opts) => sendAction(opts, deps));
+    const emails = program
+        .command("emails")
+        .description("Send email and work with the message log.");
+    configureSendCommand(emails.command("send")).action((opts) => sendAction(opts, deps));
+    withGlobalOptions(emails
+        .command("batch")
+        .description("Send up to 100 emails from a JSON file (a wire-shape array).")
+        .argument("<file>", "Path to a JSON array of email objects.")
+        .option("--idempotency-key <key>", "Idempotency key — a retry with the same key never double-sends.")).action(async (file, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const parsed = await readJsonFile(file);
+        if (!Array.isArray(parsed)) {
+            throw new CommandFailure(`${file} must contain a JSON array of email objects.`, 2);
+        }
+        const inputs = parsed.map((item) => {
+            if (typeof item !== "object" || item === null || Array.isArray(item)) {
+                throw new CommandFailure(`${file} must contain only email objects.`, 2);
+            }
+            return wireToSendInput(item);
+        });
+        const data = unwrap(await ctx.client.emails.batch(inputs, opts.idempotencyKey !== undefined
+            ? { idempotencyKey: opts.idempotencyKey }
+            : undefined));
+        const canceled = data.data.filter((row) => row.status === "canceled");
+        const total = data.data.length;
+        const allCanceled = total > 0 && canceled.length === total;
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            // Same exit contract as the human arm — a JSON consumer in a `&&`
+            // chain deserves it too — but silent, so the pipe stays pure JSON.
+            if (allCanceled) {
+                throw new CommandFailure("", EXIT_NOTHING_SENT);
+            }
+            return;
+        }
+        // Three summaries, not two. A batch drained END TO END must not lead
+        // with "Accepted" — that is the claim the single-send arm refuses to
+        // make, and the reader most likely to be misled (a script piping the id
+        // list) is exactly the one who discarded stderr. "N of them" in the
+        // partial case is deliberate too: "2 emails, 1 canceled" reads as three.
+        const summary = canceled.length === 0
+            ? `Accepted ${total} emails`
+            : canceled.length === total
+                ? `Canceled all ${total} emails by suppression`
+                : `Accepted ${total} emails, ${canceled.length} of them canceled by suppression`;
+        deps.stdout.write(`${summary} (${ctx.environment}):\n`);
+        for (const row of data.data) {
+            deps.stdout.write(`${row.id}\n`);
+        }
+        // WHICH rows were dropped is a hint, not data — the id list above stays
+        // one bare id per line for pipes, so the names go to stderr.
+        if (canceled.length > 0) {
+            deps.stderr.write(`No mail will be sent for: ${canceled.map((row) => row.id).join(", ")}\n`);
+        }
+        // A PARTIAL cancellation stays 0: some mail really did go out, and the
+        // stdout count already says how much. Only a batch that delivered
+        // NOTHING gets the nonzero code.
+        if (allCanceled) {
+            throw new CommandFailure("", EXIT_NOTHING_SENT);
+        }
+    });
+    withGlobalOptions(emails
+        .command("get")
+        .description("Fetch one email's detail.")
+        .argument("<id>", "The email id (em_…).")).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.emails.get(id));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write([
+            `ID:         ${data.id}`,
+            `Status:     ${data.last_event}`,
+            `From:       ${data.from}`,
+            `To:         ${data.to.join(", ")}`,
+            `Subject:    ${data.subject ?? ""}`,
+            `Created:    ${data.created_at}`,
+            `Scheduled:  ${data.scheduled_at ?? ""}`,
+            // Array.isArray guard: a malformed tags payload (seen from bad seed
+            // data) must degrade to an empty cell, not crash the renderer.
+            `Tags:       ${(Array.isArray(data.tags) ? data.tags : [])
+                .map((t) => `${t.name}=${t.value}`)
+                .join(", ")}`,
+        ].join("\n") + "\n");
+    });
+    withGlobalOptions(emails
+        .command("events")
+        .description("Show one email's event timeline.")
+        .argument("<id>", "The email id (em_…).")).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.emails.events(id));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(formatTable(["Type", "At", "Detail"], data.data.map((event) => [
+            event.type,
+            event.event_at,
+            event.detail === null ? "" : JSON.stringify(event.detail),
+        ])));
+    });
+    withGlobalOptions(emails
+        .command("list")
+        .description("List sent emails (newest first).")
+        .option("--status <status>", "Filter by status (e.g. delivered, bounced).")
+        .option("--tag <value>", "Filter by tag value (the value half of a send-time name=value tag).")
+        .option("--domain <domain>", "Filter by recipient domain.")
+        .option("--recipient <address>", "Filter by exact recipient address.")
+        .option("--search <term>", "Free-text search (subject, from address, id, or recipient).")
+        // Deliberately NOT --from/--to: those mean addresses on `send`, and the
+        // wire params from/to stay an internal mapping detail.
+        .option("--since <date>", "Window start (ISO date, e.g. 2026-07-01).")
+        .option("--until <date>", "Window end (ISO date).")
+        .option("--limit <n>", "Page size (max 100).")
+        .option("--cursor <cursor>", "Resume from a previous next-cursor value.")
+        .option("--all", "Fetch every page (ignores --limit; starts from --cursor when given).")).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const baseQuery = {
+            ...(opts.status !== undefined ? { status: opts.status } : {}),
+            ...(opts.tag !== undefined ? { tag: opts.tag } : {}),
+            ...(opts.domain !== undefined ? { domain: opts.domain } : {}),
+            ...(opts.recipient !== undefined ? { recipient: opts.recipient } : {}),
+            ...(opts.search !== undefined ? { q: opts.search } : {}),
+            ...(opts.since !== undefined ? { from: opts.since } : {}),
+            ...(opts.until !== undefined ? { to: opts.until } : {}),
+        };
+        await renderPagedList({
+            all: opts.all,
+            cursor: opts.cursor,
+            limit: opts.limit,
+            json: ctx.json,
+            header: ["ID", "Status", "From", "To", "Subject", "Created"],
+            toCells: (r) => [
+                r.id,
+                r.last_event,
+                r.from,
+                r.to.join(","),
+                r.subject ?? "",
+                r.created_at,
+            ],
+            fetchPage: (paging) => ctx.client.emails.list({ ...baseQuery, ...paging }),
+            stdout: deps.stdout,
+            stderr: deps.stderr,
+            sleep: deps.sleep ?? defaultSleep,
+        });
+    });
+    withGlobalOptions(emails
+        .command("cancel")
+        .description("Cancel a scheduled email that has not been sent yet.")
+        .argument("<id>", "The email id (em_…).")).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.emails.cancel(id));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(`${data.id} is now ${data.last_event}.\n`);
+    });
+    withGlobalOptions(emails
+        .command("reschedule")
+        .description("Move a scheduled email to a new delivery time.")
+        .argument("<id>", "The email id (em_…).")
+        .requiredOption("--scheduled-at <iso8601>", "The new delivery time (up to 90 days out).")).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.emails.reschedule(id, {
+            scheduledAt: opts.scheduledAt,
+        }));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(`${data.id} rescheduled for ${data.scheduled_at ?? "(unset)"}.\n`);
+    });
+}

package/dist/commands/suppressions.d.ts ADDED Viewed

@@ -0,0 +1,9 @@
+import type { Command } from "commander";
+import type { ProgramDeps } from "../program.js";
+/**
+ * Read-only by design: `read:suppressions` is mintable on an API key, but
+ * adding/removing a suppression is a `manage:suppressions` (dashboard-session)
+ * operation, so the CLI ships `list` only and the help text says where the
+ * write side lives.
+ */
+export declare function registerSuppressionsCommands(program: Command, deps: ProgramDeps): void;

package/dist/commands/suppressions.js ADDED Viewed

@@ -0,0 +1,44 @@
+import { resolveContext } from "../context.js";
+import { defaultSleep, renderPagedList } from "../pages.js";
+import { withGlobalOptions } from "../flags.js";
+function suppressionCells(s) {
+    return [s.id, s.email, s.reason, s.source, s.created_at];
+}
+const SUPPRESSION_HEADER = ["ID", "Email", "Reason", "Source", "Created"];
+/**
+ * Read-only by design: `read:suppressions` is mintable on an API key, but
+ * adding/removing a suppression is a `manage:suppressions` (dashboard-session)
+ * operation, so the CLI ships `list` only and the help text says where the
+ * write side lives.
+ */
+export function registerSuppressionsCommands(program, deps) {
+    const suppressions = program
+        .command("suppressions")
+        .description("Inspect suppressed recipients (adding/removing lives in the dashboard).");
+    withGlobalOptions(suppressions
+        .command("list")
+        .description("List suppressed recipients.")
+        .option("--email <address>", "Filter by exact address.")
+        .option("--reason <reason>", "Filter by reason (e.g. hard_bounce, complaint).")
+        .option("--limit <n>", "Page size (max 100).")
+        .option("--cursor <cursor>", "Resume from a previous next-cursor value.")
+        .option("--all", "Fetch every page (ignores --limit; starts from --cursor when given).")).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const baseQuery = {
+            ...(opts.email !== undefined ? { email: opts.email } : {}),
+            ...(opts.reason !== undefined ? { reason: opts.reason } : {}),
+        };
+        await renderPagedList({
+            all: opts.all,
+            cursor: opts.cursor,
+            limit: opts.limit,
+            json: ctx.json,
+            header: SUPPRESSION_HEADER,
+            toCells: suppressionCells,
+            fetchPage: (paging) => ctx.client.suppressions.list({ ...baseQuery, ...paging }),
+            stdout: deps.stdout,
+            stderr: deps.stderr,
+            sleep: deps.sleep ?? defaultSleep,
+        });
+    });
+}

package/dist/commands/templates.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { ProgramDeps } from "../program.js";
+export declare function registerTemplatesCommands(program: Command, deps: ProgramDeps): void;

package/dist/commands/templates.js ADDED Viewed

@@ -0,0 +1,123 @@
+import { resolveContext } from "../context.js";
+import { CommandFailure, unwrap } from "../failure.js";
+import { formatTable, toJson } from "../output.js";
+import { readBody, readJsonFile } from "../parse.js";
+import { withGlobalOptions } from "../flags.js";
+/** Attach the shared body flag set to a command (create and update). */
+function withBodyOptions(cmd) {
+    return cmd
+        .option("--html <html>", "Inline HTML body.")
+        .option("--html-file <path>", "Read the HTML body from a file.")
+        .option("--text <text>", "Inline plain-text body.")
+        .option("--text-file <path>", "Read the plain-text body from a file.")
+        .option("--variables-schema-file <path>", "Read the variables schema (JSON) from a file.");
+}
+/** Read and parse the variables schema file (shared contract: see readJsonFile). */
+async function readVariablesSchema(path) {
+    if (path === undefined)
+        return undefined;
+    return readJsonFile(path);
+}
+/** The one-template-per-row summary used by `templates list`. */
+function templateCells(t) {
+    return [
+        t.id,
+        t.name,
+        t.html !== null ? "yes" : "",
+        t.text !== null ? "yes" : "",
+        t.updated_at,
+    ];
+}
+const TEMPLATE_HEADER = ["ID", "Name", "HTML", "Text", "Updated"];
+export function registerTemplatesCommands(program, deps) {
+    const templates = program
+        .command("templates")
+        .description("Manage stored email templates.");
+    withGlobalOptions(withBodyOptions(templates
+        .command("create")
+        .description("Create a template.")
+        .requiredOption("--name <name>", "Template name."))).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const html = await readBody(opts.html, opts.htmlFile, "--html");
+        const text = await readBody(opts.text, opts.textFile, "--text");
+        if (html === undefined && text === undefined) {
+            throw new CommandFailure("Provide a body: --html/--html-file or --text/--text-file.", 2);
+        }
+        const variablesSchema = await readVariablesSchema(opts.variablesSchemaFile);
+        const data = unwrap(await ctx.client.templates.create({
+            name: opts.name,
+            ...(html !== undefined ? { html } : {}),
+            ...(text !== undefined ? { text } : {}),
+            ...(variablesSchema !== undefined ? { variablesSchema } : {}),
+        }));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(`Created ${data.id} (${data.name}).\n`);
+    });
+    withGlobalOptions(templates.command("list").description("List this org's templates.")).action(async (opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.templates.list());
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(formatTable(TEMPLATE_HEADER, data.data.map(templateCells)));
+    });
+    withGlobalOptions(templates
+        .command("get")
+        .description("Show one template.")
+        .argument("<id>", "The template id (tmpl_…).")).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.templates.get(id));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write([
+            `ID:       ${data.id}`,
+            `Name:     ${data.name}`,
+            `Updated:  ${data.updated_at}`,
+            "",
+            data.html ?? data.text ?? "(no body)",
+        ].join("\n") + "\n");
+    });
+    withGlobalOptions(withBodyOptions(templates
+        .command("update")
+        .description("Update the provided fields of a template.")
+        .argument("<id>", "The template id (tmpl_…).")
+        .option("--name <name>", "New template name."))).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const html = await readBody(opts.html, opts.htmlFile, "--html");
+        const text = await readBody(opts.text, opts.textFile, "--text");
+        const variablesSchema = await readVariablesSchema(opts.variablesSchemaFile);
+        const patch = {
+            ...(opts.name !== undefined ? { name: opts.name } : {}),
+            ...(html !== undefined ? { html } : {}),
+            ...(text !== undefined ? { text } : {}),
+            ...(variablesSchema !== undefined ? { variablesSchema } : {}),
+        };
+        if (Object.keys(patch).length === 0) {
+            throw new CommandFailure("Provide at least one field to update (--name, --html/--html-file, --text/--text-file, --variables-schema-file).", 2);
+        }
+        const data = unwrap(await ctx.client.templates.update(id, patch));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(`Updated ${data.id} (${data.name}).\n`);
+    });
+    withGlobalOptions(templates
+        .command("delete")
+        .description("Delete a template.")
+        .argument("<id>", "The template id (tmpl_…).")).action(async (id, opts) => {
+        const ctx = await resolveContext(opts, deps);
+        const data = unwrap(await ctx.client.templates.delete(id));
+        if (ctx.json) {
+            deps.stdout.write(toJson(data));
+            return;
+        }
+        deps.stdout.write(`Deleted ${data.id}.\n`);
+    });
+}

package/dist/config.d.ts ADDED Viewed

@@ -0,0 +1,30 @@
+/** The on-disk config shape (snake_case, mirroring the wire convention). */
+export interface CliConfig {
+    api_key?: string;
+    base_url?: string;
+}
+/**
+ * Resolve the config path: `MAILFULLY_CONFIG_PATH` env override, else
+ * `$XDG_CONFIG_HOME/mailfully/config.json`, else `~/.config/mailfully/config.json`.
+ *
+ * NOTE: only those two keys are read from `env` — the home-directory fallback
+ * calls `os.homedir()`, which reads the REAL process environment. `env.HOME`
+ * is NOT part of the injectable seam; tests that must redirect the config file
+ * set `MAILFULLY_CONFIG_PATH` or `XDG_CONFIG_HOME` instead.
+ */
+export declare function defaultConfigPath(env: Record<string, string | undefined>): string;
+/**
+ * Read the config file. Missing, unreadable, or malformed files all yield `{}`
+ * — the CLI treats a broken config as "not logged in", never as a crash.
+ */
+export declare function loadConfig(path: string): Promise<CliConfig>;
+/** Write the config, creating the directory (0700) and file (0600) tightly. */
+export declare function saveConfig(path: string, config: CliConfig): Promise<void>;
+/**
+ * Delete the config file; `true` if it existed. A missing file (ENOENT)
+ * yields `false` — the ordinary "not logged in" case. Any other error (e.g.
+ * EACCES) is rethrown rather than swallowed: `logout` must report a real
+ * failure to remove the file instead of claiming success while the key is
+ * still on disk.
+ */
+export declare function deleteConfig(path: string): Promise<boolean>;

package/dist/config.js ADDED Viewed

@@ -0,0 +1,82 @@
+import { chmod, mkdir, rm, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Resolve the config path: `MAILFULLY_CONFIG_PATH` env override, else
+ * `$XDG_CONFIG_HOME/mailfully/config.json`, else `~/.config/mailfully/config.json`.
+ *
+ * NOTE: only those two keys are read from `env` — the home-directory fallback
+ * calls `os.homedir()`, which reads the REAL process environment. `env.HOME`
+ * is NOT part of the injectable seam; tests that must redirect the config file
+ * set `MAILFULLY_CONFIG_PATH` or `XDG_CONFIG_HOME` instead.
+ */
+export function defaultConfigPath(env) {
+    if (env.MAILFULLY_CONFIG_PATH !== undefined &&
+        env.MAILFULLY_CONFIG_PATH !== "") {
+        return env.MAILFULLY_CONFIG_PATH;
+    }
+    const base = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(base, "mailfully", "config.json");
+}
+/**
+ * Read the config file. Missing, unreadable, or malformed files all yield `{}`
+ * — the CLI treats a broken config as "not logged in", never as a crash.
+ */
+export async function loadConfig(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return {};
+        }
+        const record = parsed;
+        const config = {};
+        if (typeof record.api_key === "string")
+            config.api_key = record.api_key;
+        if (typeof record.base_url === "string")
+            config.base_url = record.base_url;
+        return config;
+    }
+    catch {
+        return {};
+    }
+}
+/** Write the config, creating the directory (0700) and file (0600) tightly. */
+export async function saveConfig(path, config) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    // `mode` on writeFile only applies when the file is created — an existing,
+    // looser-permission file (e.g. left behind by an older CLI version) keeps
+    // its old mode otherwise. Tighten it explicitly on every save.
+    if (process.platform !== "win32") {
+        await chmod(path, 0o600);
+    }
+}
+/**
+ * Delete the config file; `true` if it existed. A missing file (ENOENT)
+ * yields `false` — the ordinary "not logged in" case. Any other error (e.g.
+ * EACCES) is rethrown rather than swallowed: `logout` must report a real
+ * failure to remove the file instead of claiming success while the key is
+ * still on disk.
+ */
+export async function deleteConfig(path) {
+    try {
+        await rm(path);
+        return true;
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return false;
+        }
+        throw err;
+    }
+}

package/dist/context.d.ts ADDED Viewed

@@ -0,0 +1,45 @@
+import { Mailfully } from "@mailfully/node";
+/** The three per-command global flags (added by withGlobalOptions, Task 7). */
+export interface GlobalFlags {
+    apiKey?: string;
+    apiUrl?: string;
+    json?: boolean;
+}
+/** What resolveContext needs from the program (a slice of ProgramDeps). */
+export interface ContextDeps {
+    env: Record<string, string | undefined>;
+    configPath: string;
+    fetchImpl?: typeof fetch;
+}
+/** The resolved per-invocation context every command action works from. */
+export interface CliContext {
+    client: Mailfully;
+    apiKey: string;
+    baseUrl: string;
+    environment: "live" | "test" | "unknown";
+    json: boolean;
+}
+/** Classify a key by its `mf_live_` / `mf_test_` prefix. */
+export declare function keyEnvironment(apiKey: string): "live" | "test" | "unknown";
+/**
+ * `mf_live_abcd…wxyz` — the stored-key display form. Never print a full key.
+ * Real Mailfully keys are ~51 chars; anything ≤24 gets prefix-only truncation
+ * so a short foreign token is never substantially revealed.
+ */
+export declare function redactKey(apiKey: string): string;
+/**
+ * The documented base-URL precedence (flag > env > config file), shared by
+ * {@link resolveContext} and login's key-verification probe so the two can
+ * never drift. Returns undefined when nothing overrides the default.
+ */
+export declare function resolveBaseUrl(apiUrlFlag: string | undefined, env: {
+    MAILFULLY_API_URL?: string;
+}, config: {
+    base_url?: string;
+}): string | undefined;
+/**
+ * Resolve key + base URL with the documented precedence (flag > env > config
+ * file > default) and construct the SDK client. Throws {@link MissingApiKeyError}
+ * when no key is found anywhere.
+ */
+export declare function resolveContext(flags: GlobalFlags, deps: ContextDeps): Promise<CliContext>;

package/dist/context.js ADDED Viewed

@@ -0,0 +1,54 @@
+import { DEFAULT_BASE_URL, Mailfully } from "@mailfully/node";
+import { loadConfig } from "./config.js";
+import { MissingApiKeyError } from "./failure.js";
+/** Classify a key by its `mf_live_` / `mf_test_` prefix. */
+export function keyEnvironment(apiKey) {
+    if (apiKey.startsWith("mf_live_"))
+        return "live";
+    if (apiKey.startsWith("mf_test_"))
+        return "test";
+    return "unknown";
+}
+/**
+ * `mf_live_abcd…wxyz` — the stored-key display form. Never print a full key.
+ * Real Mailfully keys are ~51 chars; anything ≤24 gets prefix-only truncation
+ * so a short foreign token is never substantially revealed.
+ */
+export function redactKey(apiKey) {
+    if (apiKey.length <= 24)
+        return `${apiKey.slice(0, 4)}…`;
+    return `${apiKey.slice(0, 12)}…${apiKey.slice(-4)}`;
+}
+/**
+ * The documented base-URL precedence (flag > env > config file), shared by
+ * {@link resolveContext} and login's key-verification probe so the two can
+ * never drift. Returns undefined when nothing overrides the default.
+ */
+export function resolveBaseUrl(apiUrlFlag, env, config) {
+    return apiUrlFlag ?? env.MAILFULLY_API_URL ?? config.base_url;
+}
+/**
+ * Resolve key + base URL with the documented precedence (flag > env > config
+ * file > default) and construct the SDK client. Throws {@link MissingApiKeyError}
+ * when no key is found anywhere.
+ */
+export async function resolveContext(flags, deps) {
+    const config = await loadConfig(deps.configPath);
+    const apiKey = flags.apiKey ?? deps.env.MAILFULLY_API_KEY ?? config.api_key;
+    if (apiKey === undefined || apiKey === "") {
+        throw new MissingApiKeyError();
+    }
+    const baseUrl = resolveBaseUrl(flags.apiUrl, deps.env, config) ?? DEFAULT_BASE_URL;
+    const client = new Mailfully({
+        apiKey,
+        baseUrl,
+        ...(deps.fetchImpl !== undefined ? { fetch: deps.fetchImpl } : {}),
+    });
+    return {
+        client,
+        apiKey,
+        baseUrl,
+        environment: keyEnvironment(apiKey),
+        json: flags.json ?? false,
+    };
+}