tossinbox 0.1.1 → 0.1.3

package/README.md

@@ -55,7 +55,7 @@ $ tossinbox toss
 | Documented exit codes  | 0–4                     | none                | no                          |
 | MCP server for agents  | yes, built in           | no                  | no                          |
 | Runs headless / in CI  | yes                     | no                  | partial                     |
-| Upstream alive         | mail.tm + GuerrillaMail | varies              | many wrap the dead 1secmail |
+| Upstream alive         | mail.tm + mail.gw + GuerrillaMail | varies              | many wrap the dead 1secmail |
 | Ads, trackers, popups  | none                    | the business model  | none                        |
 
 Checked September 2026. If a cell is wrong, open an issue and win the argument.
@@ -68,11 +68,11 @@ Requires Node.js 18+.
 # Homebrew (macOS, Linux)
 brew install mohamed-khairy-5i/tap/tossinbox
 
-# npm from GitHub (npm registry publish coming soon)
-npm install -g github:mohamed-khairy-5i/tossinbox
+# npm (npmjs.com)
+npm install -g tossinbox
 
 # Or run without installing
-npx github:mohamed-khairy-5i/tossinbox spawn
+npx tossinbox@latest spawn
 ```
 
 From source:
@@ -111,6 +111,7 @@ tossinbox wait --code --json
 | `list` | List messages (`-a address`) |
 | `read <id>` | Read a full message, including any detected code |
 | `wait` | Poll until a message arrives (`-f sender`, `-s subject`, `-c` extract code, `-t timeout` max 600s) |
+| `watch` | Stream new messages until Ctrl-C — only new arrivals; `--json` = one JSON object per line (NDJSON) |
 | `inboxes` | List locally saved inboxes |
 | `toss` | Delete an inbox server-side and remove it from local state (`--all` for every inbox) |
 | `clear` | Remove all inboxes from local state only |
@@ -164,13 +165,14 @@ TossInbox ships with an MCP server exposing four tools:
   "mcpServers": {
     "tossinbox": {
       "command": "npx",
-      "args": ["-y", "github:mohamed-khairy-5i/tossinbox", "mcp"]
+      "args": ["-y", "tossinbox", "mcp"]
     }
   }
 }
 ```
 
-Or after a global install, simply use `tossinbox-mcp` as the command.
+Or after a global install, simply use `tossinbox-mcp` as the command —
+equivalent to `npx -y tossinbox mcp`.
 
 ### Works with any AI agent
 
@@ -214,6 +216,7 @@ machine-readable and kept up to date.
 | Provider | API key | Notes |
 |---|---|---|
 | `mailtm` (default) | not required | mail.tm — reliable, fast |
+| `mailgw` | not required | mail.gw — mail.tm-compatible API on independent infrastructure |
 | `guerrillamail` | not required | GuerrillaMail — classic fallback |
 
 Adding a provider means implementing a small interface (`createInbox`,
@@ -222,14 +225,14 @@ Adding a provider means implementing a small interface (`createInbox`,
 ## FAQ
 
 **Is it really free?**
-Yes. MIT-licensed, and both upstream providers are free with no API keys.
+Yes. MIT-licensed, and all three upstream providers are free with no API keys.
 
 **Can it send email?**
 No — receive-only by design. TossInbox exists for privacy and testing and
 ships no bulk-send or bulk-signup mode.
 
 **Does it work on Windows?**
-Yes, anywhere Node.js 18+ runs. `npx github:mohamed-khairy-5i/tossinbox spawn`
+Yes, anywhere Node.js 18+ runs. `npx tossinbox@latest spawn`
 works in PowerShell exactly the same.
 
 **A site blocked my disposable address. What now?**
@@ -252,7 +255,7 @@ round.
 - [x] GitHub Action: `mohamed-khairy-5i/tossinbox@v1`
 - [x] Homebrew tap: `brew install mohamed-khairy-5i/tap/tossinbox`
 - [x] Project website at [tossinbox.pages.dev](https://tossinbox.pages.dev/)
-- [ ] Publish `tossinbox` + `tossinbox-mcp` to the npm registry
+- [x] Publish `tossinbox` + `tossinbox-mcp` to the [npm registry](https://www.npmjs.com/package/tossinbox)
 - [ ] `mail.gw` provider (mail.tm-compatible API — small lift)
 - [ ] `tempmail.lol` provider (free API)
 - [ ] Provider failover: auto-switch when a provider is down
@@ -264,6 +267,9 @@ round.
 - [CLI reference](https://tossinbox.pages.dev/cli) — every command, flag, and exit code
 - [Agents & MCP](https://tossinbox.pages.dev/agents) — setup for every MCP client
 - [FAQ](https://tossinbox.pages.dev/faq) — privacy, providers, troubleshooting
+- [Examples](https://tossinbox.pages.dev/examples) — copy-paste recipes: shell, CI, Node.js, MCP
+- [Guide](https://tossinbox.pages.dev/guide) — providers, state, flags, exit codes, troubleshooting
+- [Roadmap](https://tossinbox.pages.dev/roadmap) — what shipped and what is next
 - [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) · [Security](./SECURITY.md)
 
 ## License

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from "commander";
-import { DEFAULT_PROVIDER, getProvider, listProviders, listSavedInboxes, removeInbox, clearInboxes, resolveInbox, saveInbox, statePath, waitForMessage, htmlToText, ProviderError, } from "./core/index.js";
+import { DEFAULT_PROVIDER, getProvider, listProviders, listSavedInboxes, removeInbox, clearInboxes, resolveInbox, saveInbox, statePath, waitForMessage, sleep, htmlToText, ProviderError, } from "./core/index.js";
 import { VERSION } from "./version.js";
 /* Documented exit codes:
  * 0  success
@@ -212,6 +212,121 @@ program
         fail(err);
     }
 });
+program
+    .command("watch")
+    .description("Stream new messages as they arrive — prints each message (and its code when found) and keeps polling until Ctrl-C")
+    .option("-a, --address <address>", "inbox address (defaults to the most recent inbox)")
+    .option("-f, --from <sender>", "only report messages from this sender (substring)")
+    .option("-s, --subject <text>", "only report messages whose subject contains this text")
+    .option("-i, --interval <seconds>", "poll interval in seconds", "5")
+    .action(async (opts) => {
+    try {
+        const intervalSeconds = Number(opts.interval);
+        if (!Number.isFinite(intervalSeconds) || intervalSeconds < 1 || intervalSeconds > 60) {
+            fail(new Error(`Invalid --interval "${opts.interval}" (expected seconds between 1 and 60)`), EXIT_USAGE);
+        }
+        const inbox = await resolveInbox(opts.address);
+        if (!inbox)
+            fail(new Error("No saved inbox found. Run: tossinbox spawn"), EXIT_NOT_FOUND);
+        const provider = providerOrExit(inbox.provider);
+        const matches = (m) => {
+            if (opts.from) {
+                const hay = `${m.from} ${m.fromName ?? ""}`.toLowerCase();
+                if (!hay.includes(opts.from.toLowerCase()))
+                    return false;
+            }
+            if (opts.subject && !m.subject.toLowerCase().includes(opts.subject.toLowerCase()))
+                return false;
+            return true;
+        };
+        // Snapshot what is already in the inbox so only NEW arrivals are
+        // reported — re-watching an inbox after a wait must not replay history.
+        const seen = new Set();
+        try {
+            for (const m of await provider.listMessages(inbox))
+                seen.add(m.id);
+        }
+        catch {
+            // A failed first poll should not blind the watcher — start empty.
+        }
+        let stopped = false;
+        const stop = () => {
+            stopped = true;
+        };
+        process.on("SIGINT", stop);
+        process.on("SIGTERM", stop);
+        if (jsonMode()) {
+            // Streaming mode: one compact JSON object per line (NDJSON).
+        }
+        else {
+            console.error(`👀 watching ${inbox.address} — Ctrl-C to stop`);
+        }
+        while (!stopped) {
+            let summaries;
+            try {
+                summaries = await provider.listMessages(inbox);
+            }
+            catch {
+                // Transient provider/network errors: keep polling until stopped.
+            }
+            if (summaries) {
+                for (const summary of summaries) {
+                    if (seen.has(summary.id) || !matches(summary))
+                        continue;
+                    seen.add(summary.id);
+                    // One retry — a transient read error must not swallow a message
+                    // that may have taken minutes to arrive.
+                    let message;
+                    try {
+                        message = await provider.readMessage(inbox, summary.id);
+                    }
+                    catch {
+                        await sleep(1500);
+                        try {
+                            message = await provider.readMessage(inbox, summary.id);
+                        }
+                        catch {
+                            // Report from the summary rather than dropping the event.
+                        }
+                    }
+                    if (jsonMode()) {
+                        const event = {
+                            ok: true,
+                            event: "message",
+                            inbox: inbox.address,
+                            provider: inbox.provider,
+                            id: summary.id,
+                            from: summary.from,
+                            fromName: summary.fromName,
+                            subject: summary.subject,
+                            createdAt: summary.createdAt,
+                            code: message?.code,
+                            text: message?.text ?? (message?.html ? htmlToText(message.html) : undefined),
+                        };
+                        console.log(JSON.stringify(event));
+                    }
+                    else if (message) {
+                        printMessageHuman(message, false);
+                    }
+                    else {
+                        console.log(`✔ new message: ${summary.subject}`);
+                    }
+                }
+            }
+            // Sleep in small slices so Ctrl-C feels instant.
+            const deadline = Date.now() + intervalSeconds * 1000;
+            while (!stopped && Date.now() < deadline) {
+                await sleep(Math.min(200, deadline - Date.now()));
+            }
+        }
+        if (!jsonMode())
+            console.error("✔ watch stopped");
+        exitWith(EXIT_OK);
+    }
+    catch (err) {
+        fail(err);
+    }
+});
 program
     .command("inboxes")
     .description("List locally saved inboxes")

package/dist/core/index.js

@@ -1,11 +1,12 @@
-import { mailTm } from "./providers/mailtm.js";
+import { mailTm, mailGw } from "./providers/mailtm.js";
 import { guerrillaMail } from "./providers/guerrillamail.js";
 export * from "./types.js";
 export { extractCode, htmlToText } from "./otp.js";
 export * from "./state.js";
-export { waitForMessage } from "./wait.js";
+export { waitForMessage, sleep } from "./wait.js";
 export const providers = {
     [mailTm.name]: mailTm,
+    [mailGw.name]: mailGw,
     [guerrillaMail.name]: guerrillaMail,
 };
 export const DEFAULT_PROVIDER = mailTm.name;

package/dist/core/net.js

@@ -0,0 +1,46 @@
+import { ProviderError } from "./types.js";
+/** Translate Node's raw fetch failures into a ProviderError that says what
+ *  actually happened and what to do next. Without this, a DNS blip or a dead
+ *  upstream surfaces as Node's bare "fetch failed" — useless to humans and
+ *  unparsable for agents. Messages stay short, actionable, and stable. */
+export function networkError(err, provider, host, timeoutMs) {
+    const failure = (err ?? {});
+    const cause = failure.cause ?? {};
+    const code = cause.code ?? "";
+    // AbortSignal.timeout rejects with a DOMException named "TimeoutError"
+    // (sometimes wrapped as the fetch cause).
+    if (failure.name === "TimeoutError" ||
+        cause.name === "TimeoutError" ||
+        code === "UND_ERR_HEADERS_TIMEOUT") {
+        return new ProviderError(provider, `no response from ${host} within ${Math.round(timeoutMs / 1000)}s — ` +
+            "provider is down or unreachable; retry, or switch with --provider");
+    }
+    switch (code) {
+        case "ENOTFOUND":
+        case "EAI_AGAIN":
+            return new ProviderError(provider, `DNS lookup failed for ${host} — no internet, bad DNS, or a blocked ` +
+                "network; check connectivity and retry");
+        case "ECONNREFUSED":
+            return new ProviderError(provider, `connection refused by ${host} — provider may be down, or a ` +
+                "firewall/proxy is blocking it; retry later");
+        case "ECONNRESET":
+        case "EPIPE":
+            return new ProviderError(provider, `connection to ${host} dropped mid-request — usually transient; retry`);
+        case "ENETUNREACH":
+        case "ENETDOWN":
+        case "EHOSTUNREACH":
+            return new ProviderError(provider, "network unreachable — you appear to be offline; check your connection and retry");
+        case "ECONNABORTED":
+            return new ProviderError(provider, `connection to ${host} aborted — usually transient; retry`);
+        case "CERT_HAS_EXPIRED":
+        case "DEPTH_ZERO_SELF_SIGNED_CERT":
+        case "SELF_SIGNED_CERT_IN_CHAIN":
+        case "UNABLE_TO_VERIFY_LEAF_SIGNATURE":
+            return new ProviderError(provider, `TLS certificate problem with ${host} — if a corporate proxy ` +
+                "intercepts TLS, point NODE_EXTRA_CA_CERTS at its CA bundle");
+        default: {
+            const detail = cause.message || failure.message || String(err);
+            return new ProviderError(provider, `cannot reach ${host} (${detail}) — check connectivity and retry`);
+        }
+    }
+}

package/dist/core/otp.js

@@ -6,8 +6,34 @@
  *     looks like a code (4-8 digits, or 5-8 uppercase alphanumeric chars
  *     containing both letters and digits).
  *  2. Fall back to the first standalone 4-8 digit number in the text.
+ *
+ * Keywords cover English plus the languages verification mail actually
+ * arrives in: Arabic, French, Spanish, German, Portuguese, Italian, Russian,
+ * Turkish, Chinese, Japanese, and Korean. Latin-script words use \b
+ * boundaries; scripts where \b is meaningless (Arabic, Cyrillic, CJK) match
+ * bare, same as the existing Arabic handling.
  */
-const CODE_KEYWORDS = /\b(?:code|otp|passcode|pin|password.?code|verification|verify|confirm|activation|active.?code|one.?time)\b|رمز|كود|تفعيل|تحقق|الرمز/i;
+const CODE_KEYWORDS = /\b(?:code|otp|passcode|pin|password.?code|verification|verify|confirm|activation|active.?code|one.?time|code.?de.?confirmation)\b/ // en + fr "code de confirmation"
+    .source +
+    "|" +
+    [
+        // Arabic
+        "رمز", "كود", "تفعيل", "تحقق", "الرمز",
+        // French
+        "vérification", "vérifier", "confirmer", "confirmation",
+        // Spanish / Portuguese / Italian (shared words folded)
+        "código", "verificación", "verificar", "confirme", "confirmação", "verificação",
+        "codice", "verifica", "conferma",
+        // German
+        "bestätigung", "verifizierung", "bestätigungscode",
+        // Russian (Cyrillic — no \b)
+        "код", "подтверждение", "верификация",
+        // Turkish
+        "doğrulama", "onay.?kodu",
+        // Chinese / Japanese / Korean (CJK — no \b)
+        "验证码", "校验码", "确认码", "確認コード", "認証コード", "検証コード", "認証番号", "인증코드", "인증 번호",
+    ].join("|");
+const CODE_KEYWORDS_RE = new RegExp(CODE_KEYWORDS, "i");
 export function htmlToText(html) {
     return html
         .replace(/<style[\s\S]*?<\/style>/gi, " ")
@@ -33,7 +59,7 @@ export function extractCode(input) {
     const lines = text.split(/\r?\n/);
     // 1) Keyword line -> prefer a code-shaped token on that line
     for (const line of lines) {
-        if (!CODE_KEYWORDS.test(line))
+        if (!CODE_KEYWORDS_RE.test(line))
             continue;
         // Case-insensitive on purpose: many services send lowercase codes (f4x9k2).
         const tokens = line.match(/(?<![\w-])[A-Za-z0-9]{4,10}(?![\w-])/g);

package/dist/core/providers/guerrillamail.js

@@ -1,5 +1,6 @@
 import { ProviderError } from "../types.js";
 import { extractCode } from "../otp.js";
+import { networkError } from "../net.js";
 import { VERSION } from "../../version.js";
 const BASE = "https://api.guerrillamail.com/ajax.php";
 const REQUEST_TIMEOUT_MS = 20_000;
@@ -13,10 +14,13 @@ async function call(params) {
     const url = new URL(BASE);
     for (const [k, v] of Object.entries(params))
         url.searchParams.set(k, v);
-    // Hard timeout on every request — an agent must never hang forever.
+    // Hard timeout on every request — an agent must never hang forever. Raw
+    // network failures are translated into a readable, actionable ProviderError.
     const res = await fetch(url, {
         headers: { Accept: "application/json", "User-Agent": `tossinbox/${VERSION}` },
         signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).catch((err) => {
+        throw networkError(err, "guerrillamail", "api.guerrillamail.com", REQUEST_TIMEOUT_MS);
     });
     if (!res.ok)
         throw new ProviderError("guerrillamail", `HTTP ${res.status}`, res.status);

package/dist/core/providers/mailtm.js

@@ -1,8 +1,8 @@
 import { randomBytes } from "node:crypto";
 import { ProviderError } from "../types.js";
 import { extractCode } from "../otp.js";
+import { networkError } from "../net.js";
 import { VERSION } from "../../version.js";
-const BASE = "https://api.mail.tm";
 const REQUEST_TIMEOUT_MS = 20_000;
 function randomString(length, alphabet) {
     const bytes = randomBytes(length);
@@ -27,124 +27,148 @@ function headers(token) {
         h.Authorization = `Bearer ${token}`;
     return h;
 }
-/** Hard timeout on every request — an agent must never hang forever. */
-function fetchJson(url, init) {
-    return fetch(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
-}
-/** mail.tm allows ~8 requests per second; retry once on 429. */
-async function request(method, url, options = {}) {
-    const init = {
-        method,
-        headers: { ...headers(options.token), ...(options.body ? { "Content-Type": "application/json" } : {}) },
-        body: options.body ? JSON.stringify(options.body) : undefined,
-    };
-    let res = await fetchJson(url, init);
-    if (res.status === 429) {
-        await new Promise((r) => setTimeout(r, 1200));
-        res = await fetchJson(url, init);
+/** mail.tm and mail.gw expose the identical API (mail.gw is an independent
+ *  infrastructure running the same software), so one factory serves both.
+ *  Every request gets a hard timeout and raw network failures are translated
+ *  into readable, actionable ProviderErrors naming the right provider. */
+function createMailTmLikeProvider(config) {
+    const { name: providerName, base, host } = config;
+    function fetchJson(url, init) {
+        return fetch(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) }).catch((err) => {
+            throw networkError(err, providerName, host, REQUEST_TIMEOUT_MS);
+        });
     }
-    return res;
-}
-async function parseJson(res, provider) {
-    if (!res.ok) {
-        let detail = "";
-        try {
-            const body = (await res.json());
-            const msg = body["hydra:description"] ?? body.message ?? body.detail;
-            if (typeof msg === "string")
-                detail = `: ${msg}`;
+    /** These APIs allow ~8 requests per second; retry once on 429. */
+    async function request(method, url, options = {}) {
+        const init = {
+            method,
+            headers: { ...headers(options.token), ...(options.body ? { "Content-Type": "application/json" } : {}) },
+            body: options.body ? JSON.stringify(options.body) : undefined,
+        };
+        let res = await fetchJson(url, init);
+        if (res.status === 429) {
+            await new Promise((r) => setTimeout(r, 1200));
+            res = await fetchJson(url, init);
         }
-        catch {
-            // ignore body parse errors
+        return res;
+    }
+    async function parseJson(res) {
+        if (!res.ok) {
+            // 5xx = the upstream itself is failing — say so and point at the fix.
+            if (res.status >= 500) {
+                throw new ProviderError(providerName, `HTTP ${res.status} from ${host} — provider is down or having trouble; retry, or switch with --provider`, res.status);
+            }
+            let detail = "";
+            try {
+                const body = (await res.json());
+                const msg = body["hydra:description"] ?? body.message ?? body.detail;
+                if (typeof msg === "string")
+                    detail = `: ${msg}`;
+            }
+            catch {
+                // ignore body parse errors
+            }
+            throw new ProviderError(providerName, `HTTP ${res.status}${detail}`, res.status);
         }
-        throw new ProviderError(provider, `HTTP ${res.status}${detail}`, res.status);
+        return (await res.json());
     }
-    return (await res.json());
-}
-/** mail.tm returns a plain array with Accept: application/json and a hydra
- *  collection with Accept: application/ld+json — normalize both. */
-async function parseCollection(res, provider) {
-    const data = await parseJson(res, provider);
-    if (Array.isArray(data))
-        return data;
-    if (data && typeof data === "object") {
-        const obj = data;
-        const member = obj["hydra:member"] ?? obj.member;
-        if (Array.isArray(member))
-            return member;
+    /** These APIs return a plain array with Accept: application/json and a hydra
+     *  collection with Accept: application/ld+json — normalize both. */
+    async function parseCollection(res) {
+        const data = await parseJson(res);
+        if (Array.isArray(data))
+            return data;
+        if (data && typeof data === "object") {
+            const obj = data;
+            const member = obj["hydra:member"] ?? obj.member;
+            if (Array.isArray(member))
+                return member;
+        }
+        throw new ProviderError(providerName, "Unexpected collection response shape");
     }
-    throw new ProviderError(provider, "Unexpected collection response shape");
+    return {
+        name: providerName,
+        description: config.description,
+        async createInbox(options) {
+            const domainsRes = await request("GET", `${base}/domains?page=1`);
+            const domains = await parseCollection(domainsRes);
+            const domain = domains.find((d) => d.isActive && !d.isPrivate)?.domain;
+            if (!domain) {
+                throw new ProviderError(providerName, `No active public domain available on ${host}`);
+            }
+            const address = `${randomUser()}@${domain}`;
+            const password = randomPassword();
+            const accountRes = await request("POST", `${base}/accounts`, { body: { address, password } });
+            const account = await parseJson(accountRes);
+            const tokenRes = await request("POST", `${base}/token`, { body: { address, password } });
+            const auth = await parseJson(tokenRes);
+            const inbox = {
+                provider: providerName,
+                address: account.address || address,
+                label: options?.label,
+                token: auth.token,
+                password,
+                accountId: account.id || auth.id,
+                createdAt: new Date().toISOString(),
+            };
+            return inbox;
+        },
+        async listMessages(inbox) {
+            if (!inbox.token)
+                throw new ProviderError(providerName, "Inbox is missing its API token");
+            const res = await request("GET", `${base}/messages?page=1`, { token: inbox.token });
+            const data = await parseCollection(res);
+            return data.map((m) => ({
+                id: m.id,
+                from: m.from?.address ?? "unknown",
+                fromName: m.from?.name,
+                subject: m.subject ?? "(no subject)",
+                intro: m.intro,
+                createdAt: m.createdAt,
+            }));
+        },
+        async readMessage(inbox, id) {
+            if (!inbox.token)
+                throw new ProviderError(providerName, "Inbox is missing its API token");
+            const res = await request("GET", `${base}/messages/${encodeURIComponent(id)}`, { token: inbox.token });
+            const m = await parseJson(res);
+            const html = m.html && m.html.length > 0 ? m.html.join("\n") : undefined;
+            const message = {
+                id: m.id,
+                from: m.from?.address ?? "unknown",
+                fromName: m.from?.name,
+                subject: m.subject ?? "(no subject)",
+                intro: m.intro,
+                createdAt: m.createdAt,
+                text: m.text,
+                html,
+            };
+            message.code = extractCode(message.text) ?? extractCode(message.html);
+            return message;
+        },
+        async destroyInbox(inbox) {
+            if (!inbox.token || !inbox.accountId)
+                return;
+            try {
+                await request("DELETE", `${base}/accounts/${encodeURIComponent(inbox.accountId)}`, {
+                    token: inbox.token,
+                });
+            }
+            catch {
+                // best effort: local removal always happens regardless
+            }
+        },
+    };
 }
-export const mailTm = {
+export const mailTm = createMailTmLikeProvider({
     name: "mailtm",
+    base: "https://api.mail.tm",
+    host: "api.mail.tm",
     description: "mail.tm — free disposable email, no API key required",
-    async createInbox(options) {
-        const domainsRes = await request("GET", `${BASE}/domains?page=1`);
-        const domains = await parseCollection(domainsRes, this.name);
-        const domain = domains.find((d) => d.isActive && !d.isPrivate)?.domain;
-        if (!domain) {
-            throw new ProviderError(this.name, "No active public domain available on mail.tm");
-        }
-        const address = `${randomUser()}@${domain}`;
-        const password = randomPassword();
-        const accountRes = await request("POST", `${BASE}/accounts`, { body: { address, password } });
-        const account = await parseJson(accountRes, this.name);
-        const tokenRes = await request("POST", `${BASE}/token`, { body: { address, password } });
-        const auth = await parseJson(tokenRes, this.name);
-        const inbox = {
-            provider: this.name,
-            address: account.address || address,
-            label: options?.label,
-            token: auth.token,
-            password,
-            accountId: account.id || auth.id,
-            createdAt: new Date().toISOString(),
-        };
-        return inbox;
-    },
-    async listMessages(inbox) {
-        if (!inbox.token)
-            throw new ProviderError(this.name, "Inbox is missing its API token");
-        const res = await request("GET", `${BASE}/messages?page=1`, { token: inbox.token });
-        const data = await parseCollection(res, this.name);
-        return data.map((m) => ({
-            id: m.id,
-            from: m.from?.address ?? "unknown",
-            fromName: m.from?.name,
-            subject: m.subject ?? "(no subject)",
-            intro: m.intro,
-            createdAt: m.createdAt,
-        }));
-    },
-    async readMessage(inbox, id) {
-        if (!inbox.token)
-            throw new ProviderError(this.name, "Inbox is missing its API token");
-        const res = await request("GET", `${BASE}/messages/${encodeURIComponent(id)}`, { token: inbox.token });
-        const m = await parseJson(res, this.name);
-        const html = m.html && m.html.length > 0 ? m.html.join("\n") : undefined;
-        const message = {
-            id: m.id,
-            from: m.from?.address ?? "unknown",
-            fromName: m.from?.name,
-            subject: m.subject ?? "(no subject)",
-            intro: m.intro,
-            createdAt: m.createdAt,
-            text: m.text,
-            html,
-        };
-        message.code = extractCode(message.text) ?? extractCode(message.html);
-        return message;
-    },
-    async destroyInbox(inbox) {
-        if (!inbox.token || !inbox.accountId)
-            return;
-        try {
-            await request("DELETE", `${BASE}/accounts/${encodeURIComponent(inbox.accountId)}`, {
-                token: inbox.token,
-            });
-        }
-        catch {
-            // best effort: local removal always happens regardless
-        }
-    },
-};
+});
+export const mailGw = createMailTmLikeProvider({
+    name: "mailgw",
+    base: "https://api.mail.gw",
+    host: "api.mail.gw",
+    description: "mail.gw — mail.tm-compatible API on independent infrastructure",
+});

package/dist/core/state.js

@@ -61,9 +61,28 @@ export async function resolveInbox(address) {
 }
 async function writeState(state) {
     const file = statePath();
+    const dir = path.dirname(file);
     // The state file contains provider tokens — keep it private.
-    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
-    await fs.writeFile(file, JSON.stringify(state, null, 2) + "\n", "utf8");
-    // writeFile's mode option only applies at creation — enforce on every write.
-    await fs.chmod(file, 0o600);
+    await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+    // Atomic save: write a sibling temp file, fsync it, then rename it over the
+    // real one. A crash mid-write can no longer truncate state.json and destroy
+    // saved inboxes — readers always see either the old file or the new one.
+    const tmp = path.join(dir, `.${path.basename(file)}.${process.pid}.${Date.now()}.tmp`);
+    const handle = await fs.open(tmp, "w", 0o600);
+    try {
+        await handle.writeFile(JSON.stringify(state, null, 2) + "\n", "utf8");
+        // open()'s mode is filtered by umask — enforce 0600 before the rename.
+        await handle.chmod(0o600);
+        await handle.sync(); // flush to disk before it becomes the real file
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await fs.rename(tmp, file); // atomic on POSIX; replaces the target on Windows too
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw err;
+    }
 }

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Single source of truth for the runtime version string.
  *  Keep in sync with package.json — bump both on release. */
-export const VERSION = "0.1.1";
+export const VERSION = "0.1.3";

package/llms.txt

@@ -7,6 +7,21 @@ an MCP server, collects verification codes (OTP) from them, and deletes the
 inboxes when done. It is designed agent-first: every CLI command supports
 `--json`, exit codes are documented, and there are no interactive prompts.
 
+## Site
+
+- [Home](https://tossinbox.pages.dev/): overview, install options, comparison table
+- [Quickstart](https://tossinbox.pages.dev/quickstart): first inbox in four commands
+- [CLI reference](https://tossinbox.pages.dev/cli): all commands, flags, exit codes
+- [Agents & MCP](https://tossinbox.pages.dev/agents): MCP server setup for AI agents
+- [Examples](https://tossinbox.pages.dev/examples): copy-paste recipes (shell, CI, Node.js, MCP)
+- [Guide](https://tossinbox.pages.dev/guide): providers, state, flags, exit codes, troubleshooting
+- [FAQ](https://tossinbox.pages.dev/faq): privacy, providers, troubleshooting
+- [Roadmap](https://tossinbox.pages.dev/roadmap): shipped and planned
+- [Changelog](https://tossinbox.pages.dev/changelog): every change by version
+- [Arabic home](https://tossinbox.pages.dev/ar/): الصفحة الرئيسية بالعربية
+- [Arabic quickstart](https://tossinbox.pages.dev/ar/quickstart): البداية السريعة بالعربية
+- [Source repository](https://github.com/mohamed-khairy-5i/tossinbox): code, issues, releases
+
 ## CLI (binary: `tossinbox`)
 
 - `tossinbox spawn` — create a new disposable inbox (flags: `-p provider`, `-l label`)
@@ -37,9 +52,9 @@ Typical agent flow: `create_inbox` -> use the address in a signup form ->
 ## Installation
 
 ```bash
-npm install -g github:mohamed-khairy-5i/tossinbox
+npm install -g tossinbox
 # or run without installing:
-npx github:mohamed-khairy-5i/tossinbox spawn
+npx tossinbox@latest spawn
 ```
 
 ## Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tossinbox",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Disposable email inboxes for humans and AI agents. Spawn an inbox, wait for the OTP, toss it.",
   "type": "module",
   "license": "MIT",