@funnelchat-hq/cli 0.2.0 → 0.3.0

package/README.md

@@ -23,6 +23,8 @@ The phone does not need to be a contact yet: the send creates it. Send it to you
 
 **Handing it to an AI agent?** Agents are good at running commands. Two things help them: `funnelchat connect --no-wait` prints the link and ends at once (the agent shows it to you, and `funnelchat numbers list` says when the number is connected), and `--json` on any command gives one JSON document to read.
 
+**Already have a number in Funnelchat?** Look first with `funnelchat numbers list`. If one is connected, use it: `send` takes it. If it is disconnected, `funnelchat connect --device <id>` reconnects that same number, without adding another. With none, connect yours by QR (`funnelchat connect`) or ask for a US number of Funnelchat on the official WhatsApp API (`funnelchat connect --us-number`).
+
 The same key also **follows your WhatsApp groups** (`funnelchat groups`), **exports your conversations and your contacts** to files you can verify, and checks your numbers, templates and MACs:
 
 ```bash
@@ -79,7 +81,7 @@ The CLI uses an API key of your account: `<id>|fc_live_...`, complete, as the **
 
 | Command | Permission |
 |---|---|
-| `connect` | `accounts:operate` (WhatsApp numbers → Create, connect and delete) and `accounts:read` to wait for the number |
+| `connect` | `accounts:operate` (WhatsApp numbers → Create, connect and delete) and `accounts:read` to wait for the number; with `--device`, `accounts:read` always (to know how the number connects) |
 | `send` | `conversations:send`; to a phone that is not a contact yet, `conversations:write` (it creates the contact); `conversations:read` to watch the status; `accounts:read` to pick the number without `--device` |
 | `groups` | `communities:read`; `accounts:read` without `--device` |
 | `groups follow` | `communities:operate` (Groups and campaigns → Manage groups); `accounts:read` without `--device` |
@@ -138,7 +140,7 @@ Every command takes `--json` for use from scripts and `--help` to see all its op
 
 ### `funnelchat connect`
 
-Connects a WhatsApp number to your account by QR code. It creates a connect link (`POST /api/v1/connect-links` with `type: "qr"`), prints it, and waits until the number is connected.
+Connects a WhatsApp number to your account by QR code. It creates a connect link (`POST /api/v1/connect-links` with `type: "qr"`), prints it, and waits until the number is connected. With `--us-number`, the link gives a new US number of Funnelchat instead; with `--device <id>`, it reconnects a number you already have.
 
 ```bash
 funnelchat connect
@@ -161,6 +163,8 @@ Send a first message: funnelchat send <phone> "Hello from Funnelchat"
 |---|---|
 | `--no-wait` | Prints the link and ends, without waiting. For scripts and agents: `funnelchat numbers list` then shows when the number is connected. |
 | `--timeout <seconds>` | How long to wait for the number. By default, 900 (15 minutes). |
+| `--us-number` | A new US number of Funnelchat on the official WhatsApp API, instead of a QR. |
+| `--device <id>` | Reconnects that number of your account, with a link of its own type. It never adds a number. Not with `--us-number`. |
 
 - **The link** is a page on Funnelchat's domain. Opening it does not use it; tapping its button creates the number and shows the QR, which renews itself every 5 seconds. Treat it as a secret: it comes only in this answer, and whoever has it can connect a number to your account.
 - **How it knows:** it lists your numbers before creating the link and then every 5 seconds (`GET /api/v1/devices`), and stops at the first one that was not connected before. Each listing counts toward the daily cap of accounts (about 180 calls in 15 minutes, of 10,000 a day).
@@ -168,6 +172,30 @@ Send a first message: funnelchat send <phone> "Hello from Funnelchat"
 - **No QR in the terminal:** the page shows the QR that WhatsApp scans.
 - If nobody scans the QR within 10 minutes of tapping the button, the link fails and the number it created is deleted: run `funnelchat connect` again. If the CLI stops waiting before (`--timeout`, exit code `8`, or Ctrl+C), the link still works until it expires.
 
+**A US number of Funnelchat** (`--us-number`): the link is `type: "meta"` with `allowed_connection_types: ["dedicated"]` and `provision_us_number: true`.
+
+```bash
+funnelchat connect --us-number
+```
+
+- **On the page,** the person taps the button to use a Funnelchat US number and logs in with Facebook (Meta's signup, the same as the panel's). The number is new and dedicated to the API (it is not in the WhatsApp Business app).
+- **Meta charges its messages** to the payment method of the WhatsApp Business account: it has to be added in Meta.
+- If the Facebook login or Meta fails, the same link can be tried again, up to 5 failed attempts.
+- **It is an official number:** free text only reaches a contact who wrote to it in the last 24 hours (`422 window_closed` otherwise), so write to it first from the phone you send to.
+- Connecting an official number of your own by Facebook is done from the panel.
+
+**Reconnecting a number** (`--device <id>`): the link carries `device_id`, so it reconnects that number and takes no new place.
+
+```bash
+funnelchat numbers list            # the id, and whether it is connected
+funnelchat connect --device 4
+```
+
+- **Of its own type:** a number connected by QR gets a QR link (`type: "qr"`); an official one gets a Facebook link (`type: "meta"`, with its connection, `coexistence` or `dedicated`, as `allowed_connection_types`). The CLI lists your numbers first to know which, even with `--no-wait`.
+- **Already connected:** the CLI says so and creates no link (exit code `0`).
+- **Not one of your numbers:** exit code `4`, and no link is created.
+- The wait ends when that number is connected.
+
 ### `funnelchat send <phone> <text>`
 
 Sends a text message to a phone and shows its status live, until it is `read`, it `failed` or `--timeout` ends.
@@ -388,7 +416,7 @@ MACs in the period: 120 of 1,000 (12 %) · 880 left
 {
   "manifest_version": 1,
   "kind": "conversations",
-  "generator": { "name": "@funnelchat-hq/cli", "version": "0.2.0" },
+  "generator": { "name": "@funnelchat-hq/cli", "version": "0.3.0" },
   "api": { "base_url": "https://api.funnelchat.com", "spec": { "commit": "99928866…", "sha256": "0ffaad2…" }, "routes": [ … ] },
   "started_at": "2026-10-16T12:00:00.000Z",
   "finished_at": "2026-10-16T12:41:10.000Z",
@@ -502,7 +530,7 @@ npm run build
 
 To develop you need Node 20 or later (for the test tools); the CLI it builds runs on Node 18.
 
-**The tests** use simulated answers, with the same shapes as the API (pages by number and by cursor). They cover paging, resuming, `429`s, that the key never shows up in any output or any file, that no file is overwritten, the manifest's SHA-256, and the first use: `connect` waiting for the number, and `send` watching the status until it is read.
+**The tests** use simulated answers, with the same shapes as the API (pages by number and by cursor). They cover paging, resuming, `429`s, that the key never shows up in any output or any file, that no file is overwritten, the manifest's SHA-256, and the first use: `connect` waiting for the number (also a US number and a reconnection), and `send` watching the status until it is read.
 
 **End to end against the sandbox.** With an already built checkout of [funnelchat-sandbox](https://github.com/Funnelchat20/funnelchat-sandbox) (`npm install && npm run build` in its folder), this test starts it in the same process, on a free port, and runs the CLI against it. It does not touch the sandbox's repository:
 

package/dist/cli.js

@@ -151,6 +151,13 @@ var KNOWN_API_ERRORS = {
   number_limit_reached: { message: "Every number of your plan is in use.", hint: "No link was created. Delete a number or change the plan from the panel." },
   connect_not_allowed: { message: "Only the owner of the account can connect numbers, and this key is not the owner's.", hint: "No link was created." },
   too_many_open_links: { message: "The account already has 20 connect links open.", hint: "No link was created. They end when they are used or expire." },
+  // connect --device and --us-number
+  invalid_reference_device: { message: "That number is not one of your account's numbers.", hint: "No link was created. See them with `funnelchat numbers list`." },
+  connection_type_mismatch: {
+    message: "The link is not of the number's type: a number connected by QR reconnects by QR, and an official one through Meta.",
+    hint: "No link was created. The number may have changed since it was listed: check it with `funnelchat numbers list` and try again."
+  },
+  meta_connect_disabled: { message: "Connecting official numbers by link is not enabled right now.", hint: "No link was created. Try again later." },
   // groups
   provider_unsupported: { message: "The number cannot do that: only a number connected by QR can follow groups." },
   group_not_found: {
@@ -253,7 +260,7 @@ function isRecord(value) {
 }
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 var PACKAGE_NAME = "@funnelchat-hq/cli";
 var USER_AGENT_PRODUCT = "funnelchat-cli";
 
@@ -1102,7 +1109,10 @@ var routes = {
     "perPageMax": null,
     "query": [],
     "body": [
-      "type"
+      "type",
+      "allowed_connection_types",
+      "provision_us_number",
+      "device_id"
     ],
     "pending": null
   },
@@ -1476,14 +1486,117 @@ function str(value) {
 // src/commands/connect.ts
 var CONNECT_TIMEOUT_SECONDS = 15 * 60;
 var POLL_MS = 5e3;
+var SECRET = "Whoever has the link can connect a number to your account: do not share it.";
+function expiry(link) {
+  return typeof link.expires_at === "string" ? ` and expires at ${link.expires_at}` : "";
+}
+var QR_PLAN = {
+  body: { type: "qr" },
+  instructions: (link) => [
+    "Open this link, tap the button and scan the QR code with WhatsApp on the phone you are connecting (Linked devices \u2192 Link a device):",
+    "",
+    `  ${link.url}`,
+    "",
+    `It works once${expiry(link)}; after tapping the button there are 10 minutes to scan the QR.`,
+    SECRET
+  ],
+  timeoutHint: "If the QR was not scanned within 10 minutes of tapping the button, the link failed: run `funnelchat connect` again.",
+  target: null,
+  official: false
+};
+var US_NUMBER_PLAN = {
+  body: { type: "meta", allowed_connection_types: ["dedicated"], provision_us_number: true },
+  instructions: (link) => [
+    "Open this link, tap the button to use a Funnelchat US number and log in with Facebook:",
+    "",
+    `  ${link.url}`,
+    "",
+    "It is a new number on the official WhatsApp API. Meta charges its messages, so the WhatsApp Business account needs a payment method in Meta.",
+    `It works once${expiry(link)}.`,
+    SECRET
+  ],
+  timeoutHint: "If the Facebook login or Meta failed, the same link can be tried again (up to 5 failed attempts).",
+  target: null,
+  official: true
+};
+function reconnectPlan(device) {
+  const id = String(device.id);
+  const label = deviceLabel(device);
+  const reconnects = `It reconnects number ${id}: it does not add a new one.`;
+  const secret = "Whoever has the link can connect a phone to that number of your account: do not share it.";
+  if (connectionOf(device) === "qr") {
+    return {
+      body: { type: "qr", device_id: Number(device.id) },
+      instructions: (link) => [
+        `Open this link, tap the button and scan the QR code with WhatsApp on the phone of ${label} (Linked devices \u2192 Link a device):`,
+        "",
+        `  ${link.url}`,
+        "",
+        `It works once${expiry(link)}; after tapping the button there are 10 minutes to scan the QR. ${reconnects}`,
+        secret
+      ],
+      timeoutHint: `If the QR was not scanned within 10 minutes of tapping the button, the link failed: run \`funnelchat connect --device ${id}\` again.`,
+      target: device,
+      official: false
+    };
+  }
+  return {
+    body: { type: "meta", allowed_connection_types: allowedConnectionTypes(device), device_id: Number(device.id) },
+    instructions: (link) => [
+      `Open this link and log in with Facebook to reconnect ${label} to the official WhatsApp API:`,
+      "",
+      `  ${link.url}`,
+      "",
+      `It works once${expiry(link)}. ${reconnects}`,
+      secret
+    ],
+    timeoutHint: "If the Facebook login or Meta failed, the same link can be tried again (up to 5 failed attempts).",
+    target: device,
+    official: true
+  };
+}
+function allowedConnectionTypes(device) {
+  if (device.connection === "coexistence" || device.connection === "dedicated") return [device.connection];
+  if (typeof device.is_coexistence === "boolean") return [device.is_coexistence ? "coexistence" : "dedicated"];
+  return ["coexistence", "dedicated"];
+}
 async function connect(ctx, flags) {
+  if (flags.usNumber && flags.device !== void 0) {
+    throw usageError(
+      "--us-number and --device do not go together: --us-number adds a new number, --device reconnects one you have.",
+      "No link was created. Reconnect with `funnelchat connect --device <id>`, or ask for a US number with `funnelchat connect --us-number`."
+    );
+  }
+  const deviceId = flags.device === void 0 ? null : positiveInt(flags.device, "--device");
   const wait = flags.wait !== false;
   const timeout = flags.timeout === void 0 ? CONNECT_TIMEOUT_SECONDS : seconds(flags.timeout, "--timeout");
   const client = ctx.client();
-  const before = wait ? await listDevices(ctx) : [];
+  const before = wait || deviceId !== null ? await listDevices(ctx) : [];
   const known = new Set(before.map((d) => Number(d.id)));
   const connectedBefore = new Set(before.filter(isConnected).map((d) => Number(d.id)));
-  const body = await client.post(routes.connectLinkCreate, { body: { type: "qr" } });
+  let plan;
+  if (deviceId !== null) {
+    const device = before.find((d) => Number(d.id) === deviceId);
+    if (!device) {
+      throw new CliError(`Number ${deviceId} is not one of your account's numbers.`, {
+        exitCode: ExitCode.NOT_FOUND,
+        code: "device_not_found",
+        hint: "No link was created. See your numbers and their ids with `funnelchat numbers list`.",
+        details: { device_id: deviceId }
+      });
+    }
+    if (isConnected(device)) {
+      ctx.out.result({ link: null, device, already_connected: true }, () => [
+        `${deviceLabel(device)}, id ${deviceId}, is already connected: there is nothing to reconnect and no link was created.`,
+        `Send a message: funnelchat send <phone> "Hello from Funnelchat" --device ${deviceId}`
+      ]);
+      return;
+    }
+    plan = reconnectPlan(device);
+  } else {
+    plan = flags.usNumber ? US_NUMBER_PLAN : QR_PLAN;
+  }
+  const body = await client.post(routes.connectLinkCreate, { body: plan.body });
   const data = isRecord(body) && isRecord(body.data) ? body.data : isRecord(body) ? body : {};
   if (typeof data.url !== "string" || data.url === "") {
     throw new CliError("The API created the connect link but did not return its URL.", {
@@ -1494,16 +1607,10 @@ async function connect(ctx, flags) {
     });
   }
   const link = { id: data.id ?? null, url: data.url, status: data.status ?? null, expires_at: data.expires_at ?? null };
-  const instructions = [
-    "Open this link, tap the button and scan the QR code with WhatsApp on the phone you are connecting (Linked devices \u2192 Link a device):",
-    "",
-    `  ${link.url}`,
-    "",
-    `It works once${typeof link.expires_at === "string" ? ` and expires at ${link.expires_at}` : ""}; after tapping the button there are 10 minutes to scan the QR.`,
-    "Whoever has the link can connect a number to your account: do not share it."
-  ];
+  const instructions = plan.instructions(link);
+  const result = plan.target ? { link, device: plan.target } : { link };
   if (!wait) {
-    ctx.out.result({ link }, () => [...instructions, "", "Once it is connected, `funnelchat numbers list` shows it."]);
+    ctx.out.result(result, () => [...instructions, "", "Once it is connected, `funnelchat numbers list` shows it."]);
     return;
   }
   ctx.out.prompt(instructions);
@@ -1516,18 +1623,25 @@ async function connect(ctx, flags) {
         throw new CliError(`No number connected within ${timeout} s.`, {
           exitCode: ExitCode.TIMEOUT,
           code: "connect_timeout",
-          hint: "If the QR was not scanned within 10 minutes of tapping the button, the link failed: run `funnelchat connect` again."
+          hint: plan.timeoutHint
         });
       }
       await pause(ctx, Math.min(POLL_MS, left));
       const devices = await listDevices(ctx);
-      const connected = devices.filter((d) => isConnected(d) && !connectedBefore.has(Number(d.id)));
-      const device = connected.find((d) => !known.has(Number(d.id))) ?? connected[0];
+      let device;
+      if (plan.target) {
+        device = devices.find((d) => Number(d.id) === Number(plan.target?.id) && isConnected(d));
+      } else {
+        const connected = devices.filter((d) => isConnected(d) && !connectedBefore.has(Number(d.id)));
+        device = connected.find((d) => !known.has(Number(d.id))) ?? connected[0];
+      }
       if (device) {
+        const found = device;
         const several = devices.filter(isConnected).length > 1;
-        ctx.out.result({ link, device }, () => [
-          `Connected: ${deviceLabel(device)}, id ${String(device.id)}.`,
-          `Send a first message: funnelchat send <phone> "Hello from Funnelchat"${several ? ` --device ${String(device.id)}` : ""}`
+        ctx.out.result({ link, device: found }, () => [
+          `${plan.target ? "Reconnected" : "Connected"}: ${deviceLabel(found)}, id ${String(found.id)}.`,
+          `Send a first message: funnelchat send <phone> "Hello from Funnelchat"${several ? ` --device ${String(found.id)}` : ""}`,
+          ...plan.official ? ["It is an official number: free text only reaches a contact who wrote to it in the last 24 hours, so first write to it from the phone you send to."] : []
         ]);
         return;
       }
@@ -2728,7 +2842,12 @@ async function run(argv, io) {
   const profiles = program.command("profiles").description("Saved profiles.");
   profiles.command("list", { isDefault: true }).description("Lists the profiles (never shows the keys).").action(action((ctx) => profilesList(ctx)));
   profiles.command("use").argument("<name>", "Profile to activate.").description("Chooses the profile used by default.").action(action((ctx, _command, name) => profilesUse(ctx, name)));
-  program.command("connect").description("Creates a link to connect a WhatsApp number by QR code, prints it and waits until the number connects.").option("--no-wait", "Prints the link and ends, without waiting (for scripts and agents).").option("--timeout <seconds>", `How long to wait for the number (${CONNECT_TIMEOUT_SECONDS} by default).`).action(action((ctx, command) => connect(ctx, command.opts())));
+  program.command("connect").description(
+    "Creates a link to connect a WhatsApp number by QR code, prints it and waits until the number connects. With --us-number the link gives a new US number of Funnelchat instead; with --device it reconnects a number you already have."
+  ).option("--no-wait", "Prints the link and ends, without waiting (for scripts and agents).").option("--timeout <seconds>", `How long to wait for the number (${CONNECT_TIMEOUT_SECONDS} by default).`).option(
+    "--us-number",
+    "A new US number of Funnelchat on the official WhatsApp API, instead of a QR: the page asks to log in with Facebook, and Meta charges the messages (it needs a payment method in Meta)."
+  ).option("--device <id>", "Reconnects this number of your account with a link of its own type (QR or official); it never adds a number. Not with --us-number.").action(action((ctx, command) => connect(ctx, command.opts())));
   program.command("send").argument("<phone>", "Phone with the country code, for example 5491122334455.").argument("<text...>", "The text of the message (in quotes, or as several words).").description("Sends a text message to a phone, even one that is not a contact yet, and shows its status live: queued, sent, delivered, read.").option("--device <id>", "Number to send from (by default the only connected one).").option("--timeout <seconds>", `How long to watch the status (${SEND_TIMEOUT_SECONDS} by default; 0 does not watch).`).action(action((ctx, command, phone, text2) => send(ctx, phone, text2, command.opts())));
   const groups = program.command("groups").description("WhatsApp groups of a number connected by QR.");
   groups.command("list", { isDefault: true }).description("Lists the groups of the number as WhatsApp has them, and which ones you follow.").option("--device <id>", "Number whose groups to list (by default the only one connected by QR).").action(action((ctx, command) => groupsList(ctx, command.opts())));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnelchat-hq/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Funnelchat CLI: connect a WhatsApp number, send a message and watch it get read, follow groups, and export conversations and contacts through the public API",
   "license": "MIT",
   "author": {