tossinbox 0.1.1 → 0.1.2

package/README.md

@@ -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:
@@ -164,13 +164,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
 
@@ -229,7 +230,7 @@ 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 +253,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 +265,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/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/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,6 +1,7 @@
 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;
@@ -27,9 +28,13 @@ function headers(token) {
         h.Authorization = `Bearer ${token}`;
     return h;
 }
-/** 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 (DNS, refused, timeout) are translated into a readable,
+ *  actionable ProviderError instead of Node's bare "fetch failed". */
 function fetchJson(url, init) {
-    return fetch(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+    return fetch(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) }).catch((err) => {
+        throw networkError(err, "mailtm", "api.mail.tm", REQUEST_TIMEOUT_MS);
+    });
 }
 /** mail.tm allows ~8 requests per second; retry once on 429. */
 async function request(method, url, options = {}) {

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.2";

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.2",
   "description": "Disposable email inboxes for humans and AI agents. Spawn an inbox, wait for the OTP, toss it.",
   "type": "module",
   "license": "MIT",