smsforwarder 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# smsforwarder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Get SMS verification codes from your own Android phone in shell scripts and AI agents.
+
+Install [SMS Forwarder](https://smsforwarder.app/download/) on the phone that receives the texts, copy the API key from the app, then:
+
+```sh
+npm install -g smsforwarder
+smsforwarder login sk_your_key
+CODE=$(smsforwarder code --timeout 90)
+```
+
+`code` waits for the newest code to arrive and prints only the code. It exits with status 2 if nothing arrives in time. If other codes arrived in the same window it says so on stderr; `smsforwarder messages --codes` lists them so you can pick by the text.
+
+```
+smsforwarder code [--timeout sec] [--since time] [--json]
+smsforwarder messages [--minutes n] [--codes] [--limit n] [--json]
+smsforwarder devices
+smsforwarder webhook set <url> | rm | test
+smsforwarder mcp          # MCP config for Claude, Cursor and other AI tools
+```
+
+The key can also come from `SMSFORWARDER_API_KEY`. Needs Node.js 18 or newer.
+
+Docs: https://smsforwarder.app/docs/ · 中文: https://duanxinzhuanfa.com/

package/package.json

@@ -1,6 +1,12 @@
 {
   "name": "smsforwarder",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Get SMS verification codes from your own phone in scripts and AI agents. CLI for SMS Forwarder (smsforwarder.app).",
+  "type": "module",
+  "bin": { "smsforwarder": "smsforwarder.mjs" },
+  "files": ["smsforwarder.mjs", "README.md"],
+  "engines": { "node": ">=18" },
+  "keywords": ["sms", "otp", "2fa", "verification code", "sms forwarder", "mcp", "ai agent", "sms gateway"],
+  "homepage": "https://smsforwarder.app",
+  "license": "MIT"
+}

package/smsforwarder.mjs

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+// SMS Forwarder CLI — read texts and verification codes forwarded from your phone.
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const API = process.env.SMSFORWARDER_API_URL || "https://api.smsforwarder.app";
+const CONFIG = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "smsforwarder", "config.json");
+
+const HELP = `SMS Forwarder — verification codes from your phone, in your terminal and AI agents.
+
+Usage:
+  smsforwarder login <api-key>          Save your API key (from the phone app)
+  smsforwarder code [options]           Wait for the newest verification code and print it
+      --timeout <sec>    How long to wait, max 120 (default 60)
+      --since <time>     Only messages after this ISO time / unix ms (default: 2 minutes ago)
+      --json             Print the whole result as JSON, including other codes that arrived in the same window
+  smsforwarder messages [--minutes n] [--codes] [--limit n] [--json]
+                                        Messages from the last n minutes (default 10), newest first
+  smsforwarder devices                  List connected phones
+  smsforwarder webhook set <url>        Send every new message to your URL (prints the signing secret)
+  smsforwarder webhook rm               Stop sending to the webhook
+  smsforwarder webhook test             Send a test event
+  smsforwarder mcp                      Print MCP config for Claude, Cursor and other AI tools
+
+The key can also come from SMSFORWARDER_API_KEY. Docs: https://smsforwarder.app/docs`;
+
+function die(msg, code = 1) {
+  process.stderr.write(msg + "\n");
+  process.exit(code);
+}
+
+function parse(argv) {
+  const pos = [];
+  const opt = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const [k, v] = a.slice(2).split("=", 2);
+      if (v !== undefined) opt[k] = v;
+      else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) opt[k] = argv[++i];
+      else opt[k] = true;
+    } else pos.push(a);
+  }
+  return { pos, opt };
+}
+
+function apiKey() {
+  if (process.env.SMSFORWARDER_API_KEY) return process.env.SMSFORWARDER_API_KEY;
+  try {
+    return JSON.parse(readFileSync(CONFIG, "utf8")).apiKey;
+  } catch {
+    die("No API key. Run `smsforwarder login <api-key>` (the key is shown in the phone app) or set SMSFORWARDER_API_KEY.");
+  }
+}
+
+async function call(method, path, body) {
+  const res = await fetch(API + path, {
+    method,
+    headers: { authorization: `Bearer ${apiKey()}`, "content-type": "application/json", "user-agent": "smsforwarder-cli/1.1.0" },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok && res.status !== 404) die(`Error ${res.status}: ${data?.error?.message ?? res.statusText}`);
+  return { status: res.status, data };
+}
+
+function qs(o) {
+  const p = new URLSearchParams();
+  for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== false) p.set(k, String(v));
+  const s = p.toString();
+  return s ? "?" + s : "";
+}
+
+function ago(iso) {
+  const s = Math.round((Date.now() - Date.parse(iso)) / 1000);
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.round(s / 60)}m ago`;
+  if (s < 86400) return `${Math.round(s / 3600)}h ago`;
+  return `${Math.round(s / 86400)}d ago`;
+}
+
+const { pos, opt } = parse(process.argv.slice(2));
+const cmd = pos[0];
+for (const gone of ["from", "contains"]) {
+  if (opt[gone] !== undefined) die(`--${gone} is gone: who sends a code can't be predicted. Take the newest code, or list recent messages and pick by text.`);
+}
+
+switch (cmd) {
+  case "login": {
+    const key = pos[1];
+    if (!key) die("Usage: smsforwarder login <api-key>");
+    process.env.SMSFORWARDER_API_KEY = key;
+    const { data } = await call("GET", "/v1/me");
+    mkdirSync(join(CONFIG, ".."), { recursive: true });
+    writeFileSync(CONFIG, JSON.stringify({ apiKey: key }, null, 2), { mode: 0o600 });
+    console.log(`Saved. Plan: ${data.plan}, ${data.usage.messagesThisMonth}/${data.limits.messagesPerMonth} messages this month.`);
+    break;
+  }
+  case "code":
+  case "wait": {
+    const timeout = Math.min(Number(opt.timeout ?? 60) || 60, 120);
+    const { status, data } = await call("GET", "/v1/codes/wait" + qs({ since: opt.since, timeout }));
+    if (status === 404 || !data.code) die(`No code arrived within ${timeout}s.`, 2);
+    if (opt.json) console.log(JSON.stringify(data, null, 2));
+    else {
+      console.log(data.code);
+      if (data.otherCodes?.length) {
+        process.stderr.write(`${data.otherCodes.length} other code(s) arrived in the same window; run \`smsforwarder messages --codes\` to pick by text.\n`);
+      }
+    }
+    break;
+  }
+  case "messages":
+  case "ls": {
+    const { data } = await call("GET", "/v1/messages" + qs({ minutes: opt.minutes ?? 10, limit: opt.limit ?? 20, codes_only: opt.codes ? "true" : undefined }));
+    if (opt.json) {
+      console.log(JSON.stringify(data.messages, null, 2));
+      break;
+    }
+    if (!data.messages.length) console.log("No messages yet.");
+    for (const m of data.messages) {
+      const who = m.service || m.from || "?";
+      console.log(`${ago(m.receivedAt).padEnd(8)} ${who}${m.code ? `  [${m.code}]` : ""}\n         ${m.body.replace(/\s+/g, " ").slice(0, 160)}`);
+    }
+    break;
+  }
+  case "devices": {
+    const { data } = await call("GET", "/v1/devices");
+    for (const d of data.devices) console.log(`${d.name}  (${d.platform})  last seen ${d.lastSeenAt ? ago(d.lastSeenAt) : "never"}`);
+    break;
+  }
+  case "webhook": {
+    if (pos[1] === "set" && pos[2]) {
+      const { data } = await call("PUT", "/v1/webhook", { url: pos[2] });
+      console.log(`Webhook set. Verify the x-signature header (HMAC-SHA256 of "<t>.<body>") with this secret:\n${data.secret}`);
+    } else if (pos[1] === "rm") {
+      await call("DELETE", "/v1/webhook");
+      console.log("Webhook removed.");
+    } else if (pos[1] === "test") {
+      await call("POST", "/v1/webhook/test");
+      console.log("Test event sent.");
+    } else die("Usage: smsforwarder webhook set <url> | rm | test");
+    break;
+  }
+  case "mcp": {
+    const key = apiKey();
+    console.log(`Claude Code:\n  claude mcp add --transport http sms-forwarder ${API}/mcp --header "Authorization: Bearer ${key}"\n`);
+    console.log("Cursor / Claude Desktop / other MCP clients (mcp.json):");
+    console.log(JSON.stringify({ mcpServers: { "sms-forwarder": { type: "http", url: `${API}/mcp`, headers: { Authorization: `Bearer ${key}` } } } }, null, 2));
+    break;
+  }
+  case undefined:
+  case "help":
+  case "--help":
+  case "-h":
+    console.log(HELP);
+    break;
+  default:
+    die(`Unknown command "${cmd}".\n\n${HELP}`);
+}