@funnelchat-hq/cli 0.1.1 → 0.3.0

package/dist/cli.js

@@ -52,10 +52,12 @@ var ExitCode = {
   NOT_FOUND: 4,
   /** A limit the CLI does not wait for: the daily cap or a `Retry-After` too long. Resumable. */
   RATE_LIMITED: 5,
-  /** The API failed (`5xx`, `422`…) or could not be reached, after the retries. */
+  /** The API failed (`5xx`, `422`…) or could not be reached, after the retries; or a sent message failed. */
   API: 6,
   /** The output already exists: the CLI never overwrites a file. */
   EXISTS: 7,
+  /** The CLI waited and it did not happen: no number connected within `connect --timeout`. */
+  TIMEOUT: 8,
   /** Interrupted with Ctrl+C. An export can be resumed. */
   INTERRUPTED: 130
 };
@@ -124,6 +126,58 @@ function withRequestId(hint, requestId) {
   return hint ? `${hint}
 ${cite}` : cite;
 }
+var KNOWN_API_ERRORS = {
+  // send
+  window_closed: {
+    message: "WhatsApp does not let this number send free text to this contact now: on an official number, free text only goes out within 24 hours of the contact's last message, so the first message to a new contact has to be a template.",
+    hint: "Nothing was sent. Ask the contact to write to you first, or send from a number connected by QR."
+  },
+  recipient_mismatch: { message: "The phone is not the one of that contact.", hint: "Nothing was sent." },
+  recipient_unsupported: { message: "That recipient is a group, a broadcast list or a channel: `send` writes to a person.", hint: "Nothing was sent." },
+  antiblock_duplicate_content: {
+    message: "The same text was already sent too many times to a contact that did not answer: Funnelchat stopped it to protect the number.",
+    hint: "Nothing was sent."
+  },
+  antiblock_unanswered_limit: {
+    message: "Too many messages in a row to a contact that did not answer: Funnelchat stopped it to protect the number.",
+    hint: "Nothing was sent. Wait for the contact to answer."
+  },
+  device_unavailable: { message: "The number is not connected or cannot send now.", hint: "Nothing was sent. Check it with `funnelchat numbers list`." },
+  not_sent: { message: "The message could not be registered for sending.", hint: "Nothing was sent." },
+  mac_lockout_24h: { message: "The account used up its monthly active contacts (MACs) and is locked for 24 hours.", hint: "Nothing was sent. Retrying does not help: see `funnelchat mac status`." },
+  mac_limit_reached: { message: "The account used up its monthly active contacts (MACs).", hint: "Nothing was sent. Retrying does not help: see `funnelchat mac status`." },
+  // connect
+  numbers_not_included: { message: "Your plan does not include WhatsApp numbers.", hint: "No link was created. Change the plan from the panel." },
+  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: {
+    message: "That group is not one of the number's groups (or it belongs to another workspace of the account).",
+    hint: "List them with `funnelchat groups` and use the uid it shows."
+  },
+  device_not_found: { message: "That number is not one of the account (or of this key's workspace).", hint: "See them with `funnelchat numbers list`." },
+  device_not_connected: { message: "The number is not connected.", hint: "See it with `funnelchat numbers list`." },
+  device_not_group_admin: { message: "The number is not an admin of that group." },
+  unsupported_group_type: { message: "That uid is a community or a channel, not a group." },
+  import_permission_required: { message: "Following a group needs the Groups and campaigns \u2192 Manage groups permission (`communities:operate`).", hint: "Create a key with that permission." },
+  import_rate_limited: { message: "This number already followed 5 groups in the last minute." },
+  import_in_progress: { message: "That group is being imported right now.", hint: "Try again in a few seconds." }
+};
+function exitCodeOf(status) {
+  if (status === 401 || status === 403) return ExitCode.AUTH;
+  if (status === 404) return ExitCode.NOT_FOUND;
+  if (status === 429) return ExitCode.RATE_LIMITED;
+  return ExitCode.API;
+}
 function describe(init, apiCode, apiMessage, fieldErrors) {
   const where = `${init.method} ${init.route}`;
   const said = apiMessage ? `: ${apiMessage}` : ".";
@@ -135,6 +189,10 @@ function describe(init, apiCode, apiMessage, fieldErrors) {
       hint: "Check that the key is complete (with the `<id>|` at the start) and still active, and run `funnelchat login` again."
     };
   }
+  const known = apiCode !== void 0 && Object.hasOwn(KNOWN_API_ERRORS, apiCode) ? KNOWN_API_ERRORS[apiCode] : void 0;
+  if (known) {
+    return { exitCode: exitCodeOf(status), message: `${known.message} (${status} ${apiCode} on ${where})`, ...known.hint ? { hint: known.hint } : {} };
+  }
   if (status === 403) {
     const permission = init.permission ? ` This route needs \`${init.permission}\`.` : "";
     return {
@@ -202,7 +260,7 @@ function isRecord(value) {
 }
 
 // src/version.ts
-var VERSION = "0.1.1";
+var VERSION = "0.3.0";
 var PACKAGE_NAME = "@funnelchat-hq/cli";
 var USER_AGENT_PRODUCT = "funnelchat-cli";
 
@@ -310,6 +368,7 @@ var DEFAULT_MAX_RETRIES = 4;
 var DEFAULT_MAX_WAIT_SECONDS = 60;
 var INITIAL_BACKOFF_MS = 1e3;
 var MAX_BACKOFF_MS = 3e4;
+var WRITE_MAY_HAVE_ARRIVED = "It was a write: Funnelchat may have received it. Check before repeating it.";
 var ApiClient = class {
   baseUrl;
   /** Requests sent, retries included. */
@@ -329,6 +388,11 @@ var ApiClient = class {
   async get(route, options = {}) {
     return await this.#send(route, options);
   }
+  /** One write (`POST`) of `route` with a JSON `body`, sent once and never retried. Returns the parsed body. */
+  async post(route, options = {}) {
+    if (route.method !== "POST") throw new TypeError(`${route.method} ${route.path} is not a write.`);
+    return await this.#send(route, options);
+  }
   /** One page of a listing route, and the query of the page after it. */
   async page(route, options = {}) {
     const body = await this.#send(route, options);
@@ -359,6 +423,8 @@ var ApiClient = class {
       "User-Agent": `${USER_AGENT_PRODUCT}/${VERSION} node/${process.version}`,
       Authorization: `Bearer ${this.#apiKey}`
     };
+    const payload = options.body === void 0 ? void 0 : JSON.stringify(options.body);
+    if (payload !== void 0) headers["Content-Type"] = "application/json";
     for (let attempt = 0; ; attempt++) {
       const canRetry = retriesAllowed && attempt < maxRetries;
       await opts.pacer.wait(opts.signal);
@@ -366,9 +432,9 @@ var ApiClient = class {
       const started = opts.clock();
       opts.log?.(`\u2192 ${method} ${url}${attempt > 0 ? ` (attempt ${attempt + 1})` : ""}`);
       let response;
-      let text;
+      let text2;
       try {
-        ({ response, text } = await this.#attempt(method, url, headers));
+        ({ response, text: text2 } = await this.#attempt(method, url, headers, payload));
       } catch (error2) {
         if (error2 instanceof InterruptedError) throw error2;
         if (canRetry) {
@@ -377,11 +443,12 @@ var ApiClient = class {
           await this.#sleep(delay2);
           continue;
         }
+        if (!retriesAllowed && error2 instanceof ConnectionError) error2.hint = [error2.hint, WRITE_MAY_HAVE_ARRIVED].filter(Boolean).join("\n");
         throw error2;
       }
       const requestId = response.headers.get("x-request-id") ?? void 0;
       opts.log?.(`\u2190 ${response.status} in ${opts.clock() - started} ms${requestId ? ` \xB7 X-Request-Id ${requestId}` : ""}`);
-      const body = parseBody(response, text);
+      const body = parseBody(response, text2);
       if (response.ok) return body;
       const retryAfter = parseRetryAfter(response.headers.get("retry-after"), opts.clock());
       const error = new ApiError({
@@ -395,9 +462,12 @@ var ApiClient = class {
         requestId
       });
       const retryable = response.status === 429 || response.status >= 500 && error.apiCode !== "edge_misconfigured";
+      if (!retriesAllowed && response.status >= 500 && error.apiCode !== "edge_misconfigured" && error.apiCode !== "gate_unavailable") {
+        error.hint = [WRITE_MAY_HAVE_ARRIVED, error.hint].filter(Boolean).join("\n");
+      }
       if (!retryable) throw error;
       if (retryAfter !== void 0 && retryAfter > maxWait) {
-        throw stopForLongWait(error, retryAfter, opts.clock());
+        throw stopForLongWait(error, retryAfter, opts.clock(), method);
       }
       if (!canRetry) {
         if (response.status === 429) error.hint = [`Wait ${formatSeconds(retryAfter ?? 60)} and try again.`, error.hint].filter(Boolean).join("\n");
@@ -416,7 +486,7 @@ var ApiClient = class {
       throw error;
     }
   }
-  async #attempt(method, url, headers) {
+  async #attempt(method, url, headers, payload) {
     const signal = this.#options.signal;
     if (signal?.aborted) throw new InterruptedError();
     const timeoutMs = this.#options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
@@ -436,7 +506,7 @@ var ApiClient = class {
     try {
       let response;
       try {
-        response = await this.#options.fetch(url, { method, headers, signal: controller2.signal });
+        response = await this.#options.fetch(url, { method, headers, signal: controller2.signal, ...payload !== void 0 ? { body: payload } : {} });
       } catch (error) {
         throw classify(error);
       }
@@ -461,7 +531,7 @@ function backoffMs(attempt, random = Math.random) {
   const base = Math.min(INITIAL_BACKOFF_MS * 2 ** attempt, MAX_BACKOFF_MS);
   return Math.round(base * (1 - 0.25 * random()));
 }
-function stopForLongWait(error, retryAfter, now) {
+function stopForLongWait(error, retryAfter, now, method) {
   const at = new Date(now + retryAfter * 1e3);
   const when = `${formatSeconds(retryAfter)} (at ${at.toISOString().slice(11, 16)} UTC on ${at.toISOString().slice(0, 10)})`;
   let message;
@@ -475,7 +545,7 @@ function stopForLongWait(error, retryAfter, now) {
     status: error.status,
     body: error.apiCode ? { error: error.apiCode } : null,
     retryAfter,
-    method: "GET",
+    method,
     route: error.route,
     domain: error.domain,
     permission: null,
@@ -487,25 +557,25 @@ function stopForLongWait(error, retryAfter, now) {
     }
   });
 }
-function formatSeconds(seconds) {
-  const s = Math.max(0, Math.ceil(seconds));
+function formatSeconds(seconds2) {
+  const s = Math.max(0, Math.ceil(seconds2));
   if (s < 60) return `${s} s`;
   const h = Math.floor(s / 3600);
   const m = Math.floor(s % 3600 / 60);
   if (h === 0) return `${m} min${s % 60 ? ` ${s % 60} s` : ""}`;
   return `${h} h${m ? ` ${m} min` : ""}`;
 }
-function parseBody(response, text) {
-  if (text === "") return null;
+function parseBody(response, text2) {
+  if (text2 === "") return null;
   const type = response.headers.get("content-type") ?? "";
-  if (type.includes("json") || /^\s*[[{]/.test(text)) {
+  if (type.includes("json") || /^\s*[[{]/.test(text2)) {
     try {
-      return JSON.parse(text);
+      return JSON.parse(text2);
     } catch {
-      return text;
+      return text2;
     }
   }
-  return text.length <= 300 ? text : `${text.slice(0, 300)}\u2026`;
+  return text2.length <= 300 ? text2 : `${text2.slice(0, 300)}\u2026`;
 }
 function hostOf(url) {
   try {
@@ -530,8 +600,8 @@ var Redactor = class {
     for (const part of parts) if (part.length >= 6 && !this.#secrets.includes(part)) this.#secrets.push(part);
     this.#secrets.sort((a, b) => b.length - a.length);
   }
-  redact(text) {
-    let out = text;
+  redact(text2) {
+    let out = text2;
     for (const secret of this.#secrets) out = out.split(secret).join(REDACTED);
     return out.replace(KEY_SHAPE, REDACTED);
   }
@@ -693,6 +763,13 @@ var Output = class {
 `);
     else this.#lines(this.stdout, human());
   }
+  /**
+   * What the person has to act on now, before the command ends (the link of `connect`): stdout, or stderr
+   * with `--json` so stdout keeps a single JSON document. Shown even with `--quiet`.
+   */
+  prompt(lines) {
+    this.#lines(this.options.json ? this.stderr : this.stdout, lines);
+  }
   /** Progress of a long command (stderr). Silent with `--quiet` or `--json`. */
   progress(line) {
     if (!this.options.quiet && !this.options.json) this.#lines(this.stderr, line);
@@ -732,12 +809,12 @@ var Output = class {
     return cliError.exitCode;
   }
   #lines(writer, lines) {
-    const text = Array.isArray(lines) ? lines.join("\n") : lines;
-    this.#write(writer, text.endsWith("\n") ? text : `${text}
+    const text2 = Array.isArray(lines) ? lines.join("\n") : lines;
+    this.#write(writer, text2.endsWith("\n") ? text2 : `${text2}
 `);
   }
-  #write(writer, text) {
-    writer.write(this.redactor.redact(text));
+  #write(writer, text2) {
+    writer.write(this.redactor.redact(text2));
   }
 };
 function toCliError(error) {
@@ -827,11 +904,11 @@ var Context = class {
 
 // src/generated/routes.ts
 var SPEC_SOURCE = {
-  "sha256": "8bbbae569b4cab520884db98f28204156c1bd6c629578bee609343c193e0dadb",
+  "sha256": "0ffaad2b25733d28b2cc07dde8152400c3c68974b3515e71e116ce599312b0fa",
   "repository": "git@github.com:Funnelchat20/developers-portal.git",
-  "branch": "feat/openapi-unificada",
-  "commit": "0ef4abb008870ed8c7cae49a08900a81e5e57ed8",
-  "paths": 191
+  "branch": "main",
+  "commit": "99928866cbac41d5b89d31d19773acfabdbbe5dd",
+  "paths": 218
 };
 var routes = {
   "me": {
@@ -845,6 +922,7 @@ var routes = {
     "plainArray": false,
     "perPageMax": null,
     "query": [],
+    "body": [],
     "pending": null
   },
   "devicesList": {
@@ -860,6 +938,7 @@ var routes = {
     "query": [
       "perPage"
     ],
+    "body": [],
     "pending": null
   },
   "deviceHealth": {
@@ -873,6 +952,7 @@ var routes = {
     "plainArray": false,
     "perPageMax": null,
     "query": [],
+    "body": [],
     "pending": null
   },
   "contactsList": {
@@ -895,6 +975,7 @@ var routes = {
       "created_to",
       "only_with_phone"
     ],
+    "body": [],
     "pending": null
   },
   "contactTags": {
@@ -910,6 +991,7 @@ var routes = {
     "query": [
       "perPage"
     ],
+    "body": [],
     "pending": null
   },
   "contactCustomFields": {
@@ -925,6 +1007,7 @@ var routes = {
     "query": [
       "perPage"
     ],
+    "body": [],
     "pending": null
   },
   "customFieldsList": {
@@ -942,6 +1025,7 @@ var routes = {
       "orderBy",
       "orderByMethod"
     ],
+    "body": [],
     "pending": null
   },
   "conversationsList": {
@@ -961,6 +1045,7 @@ var routes = {
       "contactId",
       "updated_since"
     ],
+    "body": [],
     "pending": null
   },
   "contactMessages": {
@@ -977,6 +1062,7 @@ var routes = {
       "perPage",
       "updated_since"
     ],
+    "body": [],
     "pending": null
   },
   "templatesList": {
@@ -994,6 +1080,7 @@ var routes = {
       "deviceId",
       "status"
     ],
+    "body": [],
     "pending": null
   },
   "macStatus": {
@@ -1007,6 +1094,90 @@ var routes = {
     "plainArray": false,
     "perPageMax": null,
     "query": [],
+    "body": [],
+    "pending": null
+  },
+  "connectLinkCreate": {
+    "id": "connectLinkCreate",
+    "method": "POST",
+    "path": "/api/v1/connect-links",
+    "summary": "Crear un link de alta",
+    "domain": "accounts",
+    "permission": "accounts:operate",
+    "pagination": "none",
+    "plainArray": false,
+    "perPageMax": null,
+    "query": [],
+    "body": [
+      "type",
+      "allowed_connection_types",
+      "provision_us_number",
+      "device_id"
+    ],
+    "pending": null
+  },
+  "sendMessage": {
+    "id": "sendMessage",
+    "method": "POST",
+    "path": "/api/v1/message/send-message",
+    "summary": "Enviar un mensaje",
+    "domain": "conversations",
+    "permission": "conversations:send",
+    "pagination": "none",
+    "plainArray": false,
+    "perPageMax": null,
+    "query": [],
+    "body": [
+      "device_id",
+      "phone",
+      "text"
+    ],
+    "pending": null
+  },
+  "messageShow": {
+    "id": "messageShow",
+    "method": "GET",
+    "path": "/api/v1/contacts/{contact}/messages/{message}",
+    "summary": "Ver un mensaje",
+    "domain": "conversations",
+    "permission": "conversations:read",
+    "pagination": "none",
+    "plainArray": false,
+    "perPageMax": null,
+    "query": [],
+    "body": [],
+    "pending": null
+  },
+  "deviceGroups": {
+    "id": "deviceGroups",
+    "method": "GET",
+    "path": "/api/v1/devices/{device}/groups",
+    "summary": "Listar los grupos que administra un n\xFAmero",
+    "domain": "communities",
+    "permission": "communities:read",
+    "pagination": "page",
+    "plainArray": false,
+    "perPageMax": null,
+    "query": [
+      "pageSize"
+    ],
+    "body": [],
+    "pending": null
+  },
+  "groupImport": {
+    "id": "groupImport",
+    "method": "POST",
+    "path": "/api/v1/groups/{group}/import",
+    "summary": "Importar un grupo de un n\xFAmero",
+    "domain": "communities",
+    "permission": "communities:operate",
+    "pagination": "none",
+    "plainArray": false,
+    "perPageMax": null,
+    "query": [],
+    "body": [
+      "device_id"
+    ],
     "pending": null
   }
 };
@@ -1144,6 +1315,19 @@ function readAll(stdin) {
 }
 
 // src/commands/common.ts
+function seconds(value, flag) {
+  if (!/^\d+$/.test(value) || Number(value) > 86400) throw usageError(`${flag} must be a whole number of seconds, from 0 to 86400: ${value}`);
+  return Number(value);
+}
+async function pause(ctx, ms) {
+  if (ctx.io.signal?.aborted) throw new InterruptedError();
+  try {
+    await ctx.io.sleep(Math.max(0, ms), ctx.io.signal);
+  } catch (error) {
+    if (ctx.io.signal?.aborted) throw new InterruptedError();
+    throw error;
+  }
+}
 function positiveInt(value, flag) {
   if (!/^\d+$/.test(value) || Number(value) < 1 || !Number.isSafeInteger(Number(value))) {
     throw usageError(`${flag} must be a positive integer: ${value}`);
@@ -1169,6 +1353,311 @@ function explicitOptions(command, names) {
   return new Set(names.filter((name) => command.getOptionValueSource(name) === "cli"));
 }
 
+// src/commands/numbers.ts
+var OFFICIAL_PROVIDER = 2;
+var CAPABILITY_LABELS = {
+  contacts: "contacts",
+  conversations: "conversations",
+  templates: "templates",
+  health: "health and limit"
+};
+function capabilitiesOf(device) {
+  const official = Number(device.provider) === OFFICIAL_PROVIDER;
+  return ["contacts", "conversations", ...official ? ["templates", "health"] : []];
+}
+function connectionOf(device) {
+  return Number(device.provider) === OFFICIAL_PROVIDER ? "official" : "qr";
+}
+async function listDevices(ctx) {
+  const devices = [];
+  for await (const device of ctx.client().all(routes.devicesList, { query: { perPage: 100 } })) devices.push(device);
+  return devices;
+}
+function isConnected(device) {
+  return device.connected === true || Number(device.connected) === 1;
+}
+function deviceLabel(device) {
+  const alias = typeof device.alias === "string" && device.alias !== "" ? device.alias : null;
+  const number = typeof device.number === "string" && device.number !== "" ? device.number : null;
+  if (alias && number) return `${alias} (${number})`;
+  return alias ?? number ?? `number ${String(device.id)}`;
+}
+async function pickDevice(ctx, flag, options) {
+  if (flag !== void 0) return { id: positiveInt(flag, "--device"), device: null };
+  let devices;
+  try {
+    devices = await listDevices(ctx);
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 403) {
+      error.hint = [error.hint, "Or choose the number with --device <id>: without it the CLI lists your numbers, which needs accounts:read."].filter(Boolean).join("\n");
+    }
+    throw error;
+  }
+  const kind = options.qrOnly ? "connected by QR" : "connected";
+  const candidates = devices.filter((d) => isConnected(d) && (!options.qrOnly || connectionOf(d) === "qr"));
+  const [only] = candidates;
+  if (candidates.length === 1 && only) return { id: Number(only.id), device: only };
+  if (candidates.length === 0) {
+    throw new CliError(`The account has no number ${kind}.`, {
+      exitCode: ExitCode.NOT_FOUND,
+      code: "no_connected_number",
+      hint: `Connect one with \`funnelchat connect\`, or choose one with --device <id> (\`funnelchat numbers list\` shows them).`
+    });
+  }
+  throw usageError(
+    `The account has ${candidates.length} numbers ${kind}: choose one with --device <id>.`,
+    candidates.map((d) => `${String(d.id)}  ${deviceLabel(d)}`).join("\n")
+  );
+}
+async function numbersList(ctx) {
+  const devices = await listDevices(ctx);
+  const rows = devices.map((device) => ({
+    ...device,
+    connection: connectionOf(device),
+    cli_capabilities: capabilitiesOf(device)
+  }));
+  ctx.out.result(
+    { numbers: rows },
+    () => rows.length === 0 ? "The account has no numbers." : table(
+      ["id", "alias", "number", "connection", "connected", "health", "what the CLI reads"],
+      rows.map((d) => [
+        d.id,
+        d.alias,
+        d.number,
+        d.connection === "official" ? "official" : "QR",
+        Number(d.connected) === 1 ? "yes" : "no",
+        isRecord(d.health) ? String(d.health.state ?? "-") : null,
+        d.cli_capabilities.map((c) => CAPABILITY_LABELS[c]).join(", ")
+      ])
+    )
+  );
+}
+async function numbersHealth(ctx, ids) {
+  let targets;
+  const wanted = idList(ids, "number");
+  if (wanted.length) {
+    targets = wanted.map((id) => ({ id, label: String(id) }));
+  } else {
+    const devices = (await listDevices(ctx)).filter((d) => connectionOf(d) === "official");
+    targets = devices.map((d) => ({ id: Number(d.id), label: String(d.alias || d.number || d.id) }));
+    if (targets.length === 0) {
+      ctx.out.result({ numbers: [] }, () => "The account has no official numbers: health and limit exist only for the official WhatsApp API.");
+      return;
+    }
+  }
+  const results = [];
+  for (const target of targets) {
+    try {
+      const health = await ctx.client().get(routes.deviceHealth, { path: { device: target.id } });
+      results.push({ device_id: target.id, ...isRecord(health) ? health : { health } });
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 422 && error.apiCode === "device_not_meta") {
+        results.push({ device_id: target.id, error: "device_not_meta" });
+        continue;
+      }
+      throw error;
+    }
+  }
+  ctx.out.result(
+    { numbers: results },
+    () => table(
+      ["id", "state", "quality", "limit", "per day", "throughput", "updated", "stale"],
+      results.map((r) => {
+        if (r.error === "device_not_meta") return [r.device_id, "not an official number", null, null, null, null, null, null];
+        const h = isRecord(r.health) ? r.health : {};
+        return [
+          r.device_id,
+          str(h.state),
+          str(h.quality_level),
+          str(h.messaging_limit_tier),
+          h.messaging_limit_per_day === null || h.messaging_limit_per_day === void 0 ? "no limit reported" : Number(h.messaging_limit_per_day).toLocaleString("en-US"),
+          str(r.throughput_level),
+          str(h.last_fetched_at),
+          h.stale === true ? "yes" : h.stale === false ? "no" : null
+        ];
+      })
+    )
+  );
+}
+function str(value) {
+  return value === null || value === void 0 || value === "" ? null : String(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 || 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)));
+  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.", {
+      exitCode: ExitCode.API,
+      code: "connect_link_without_url",
+      hint: "Please report it. The link ends on its own when it expires.",
+      details: { connect_link_id: data.id ?? null }
+    });
+  }
+  const link = { id: data.id ?? null, url: data.url, status: data.status ?? null, expires_at: data.expires_at ?? null };
+  const instructions = plan.instructions(link);
+  const result = plan.target ? { link, device: plan.target } : { link };
+  if (!wait) {
+    ctx.out.result(result, () => [...instructions, "", "Once it is connected, `funnelchat numbers list` shows it."]);
+    return;
+  }
+  ctx.out.prompt(instructions);
+  ctx.out.progress("\nWaiting for the number to connect\u2026 (Ctrl+C to stop)");
+  const deadline = ctx.io.clock() + timeout * 1e3;
+  try {
+    for (; ; ) {
+      const left = deadline - ctx.io.clock();
+      if (left <= 0) {
+        throw new CliError(`No number connected within ${timeout} s.`, {
+          exitCode: ExitCode.TIMEOUT,
+          code: "connect_timeout",
+          hint: plan.timeoutHint
+        });
+      }
+      await pause(ctx, Math.min(POLL_MS, left));
+      const devices = await listDevices(ctx);
+      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: 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;
+      }
+    }
+  } catch (error) {
+    throw stillOpen(error, link);
+  }
+}
+function stillOpen(error, link) {
+  const cliError = error instanceof InterruptedError ? new CliError("Stopped waiting for the number (Ctrl+C).", { exitCode: ExitCode.INTERRUPTED, code: "interrupted" }) : toCliError(error);
+  const open = `${typeof link.expires_at === "string" ? `The link stays usable until ${link.expires_at}` : "The link stays usable until it expires"}: once the number connects, \`funnelchat numbers list\` shows it.`;
+  cliError.hint = [cliError.hint, open].filter(Boolean).join("\n");
+  cliError.details.connect_link_id = link.id;
+  return cliError;
+}
+
 // src/dates.ts
 var DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
 var DATE_TIME = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/i;
@@ -1209,9 +1698,9 @@ var FORMULA_START = /^[=+\-@\t\r]/;
 var PLAIN_NUMBER = /^[+-]?\d+(\.\d+)?$/;
 function csvCell(value) {
   if (value === null || value === void 0) return "";
-  let text = typeof value === "string" ? value : typeof value === "object" ? JSON.stringify(value) : String(value);
-  if (FORMULA_START.test(text) && !PLAIN_NUMBER.test(text)) text = `'${text}`;
-  return /[",\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+  let text2 = typeof value === "string" ? value : typeof value === "object" ? JSON.stringify(value) : String(value);
+  if (FORMULA_START.test(text2) && !PLAIN_NUMBER.test(text2)) text2 = `'${text2}`;
+  return /[",\r\n]/.test(text2) ? `"${text2.replace(/"/g, '""')}"` : text2;
 }
 function csvRow(values) {
   return `${values.map(csvCell).join(",")}\r
@@ -1372,8 +1861,8 @@ var PartFile = class _PartFile {
     return this.#rows;
   }
   /** Appends whole rows (each already ending in a newline). */
-  append(text, rows) {
-    const buffer = Buffer.from(text, "utf8");
+  append(text2, rows) {
+    const buffer = Buffer.from(text2, "utf8");
     let written = 0;
     while (written < buffer.length) {
       written += writeSync2(this.fd, buffer, written, buffer.length - written, this.#offset + written);
@@ -1723,7 +2212,7 @@ async function contactsExport(ctx, flags, explicitFlags) {
         const query = mergeNext(baseQuery, state.next ?? { page: 1 });
         const page = await client.page(routes.contactsList, { query });
         if (state.api_total_at_start === null) state.api_total_at_start = totalOf(page.body);
-        let text = "";
+        let text2 = "";
         let rows = 0;
         for (const contact of page.items) {
           const id = typeof contact.id === "number" ? contact.id : Number(contact.id);
@@ -1732,14 +2221,14 @@ async function contactsExport(ctx, flags, explicitFlags) {
           if (enriched === null) {
             state.vanished++;
           } else {
-            text += o.format === "csv" ? csvRow(csvValues(enriched, o, state.columns ?? [])) : `${JSON.stringify(enriched)}
+            text2 += o.format === "csv" ? csvRow(csvValues(enriched, o, state.columns ?? [])) : `${JSON.stringify(enriched)}
 `;
             rows++;
             observe(state, contact.created_at);
           }
           state.last_id = state.last_id === null ? id : Math.max(state.last_id, id);
         }
-        file.append(text, rows);
+        file.append(text2, rows);
         file.sync();
         state.file = file.position;
         state.next = page.next;
@@ -1945,17 +2434,17 @@ async function conversationsExport(ctx, flags, explicitFlags) {
           checkAbort();
           const query = state.list.next ? mergeNext(baseQuery, state.list.next) : baseQuery;
           const page = await client.page(routes.conversationsList, { query });
-          let text = "";
+          let text2 = "";
           let rows = 0;
           for (const conversation of page.items) {
             const id = conversationContactId(conversation);
             if (!Number.isSafeInteger(id) || seen.has(id)) continue;
             seen.add(id);
-            text += `${JSON.stringify(conversation)}
+            text2 += `${JSON.stringify(conversation)}
 `;
             rows++;
           }
-          file.append(text, rows);
+          file.append(text2, rows);
           file.sync();
           state.list.file = file.position;
           state.list.next = page.next;
@@ -2103,6 +2592,43 @@ function observe2(state, time) {
   if (o.last_message_time === null || time > o.last_message_time) o.last_message_time = time;
 }
 
+// src/commands/groups.ts
+var PAGE_SIZE = 100;
+var text = (value) => typeof value === "string" && value !== "" ? value : typeof value === "number" ? String(value) : null;
+async function groupsList(ctx, flags) {
+  const picked = await pickDevice(ctx, flags.device, { qrOnly: true });
+  const groups = [];
+  for await (const group of ctx.client().all(routes.deviceGroups, { path: { device: picked.id }, query: { pageSize: PAGE_SIZE } })) {
+    groups.push(group);
+  }
+  const from = picked.device ? deviceLabel(picked.device) : `number ${picked.id}`;
+  const device = flags.device !== void 0 ? ` --device ${picked.id}` : "";
+  ctx.out.result(
+    { device_id: picked.id, groups },
+    () => groups.length === 0 ? `${from} is in no WhatsApp group (the list is reused for up to a minute: a group just created can take that long to show).` : [
+      ...table(
+        ["uid", "name", "followed"],
+        groups.map((g) => [text(g.uid), text(g.name), text(g.device_id) ? "yes" : "no"])
+      ),
+      "",
+      `Groups of ${from}, as WhatsApp has them (reused for up to a minute). Follow one with: funnelchat groups follow <uid>${device}`
+    ]
+  );
+}
+async function groupsFollow(ctx, group, flags) {
+  const uid = group.trim();
+  if (uid === "") throw usageError("The group needs its uid, as `funnelchat groups` shows it.");
+  const picked = await pickDevice(ctx, flags.device, { qrOnly: true });
+  const body = await ctx.client().post(routes.groupImport, { path: { group: uid }, body: { device_id: picked.id } });
+  const data = isRecord(body) && isRecord(body.data) ? body.data : isRecord(body) ? body : {};
+  const name = text(data.name) ? `"${text(data.name)}" (${text(data.uid) ?? uid})` : text(data.uid) ?? uid;
+  if (data.is_admin === false) ctx.out.warn("the number is not an admin of this group: it cannot send messages to it or manage it.");
+  ctx.out.result({ device_id: picked.id, group: data }, () => [
+    data.imported === false ? `Already following ${name}: it was in your account.` : `Following ${name}.`,
+    "Who joins and who leaves arrives as the group_participant.joined and group_participant.left webhook events."
+  ]);
+}
+
 // src/commands/mac.ts
 async function macStatus(ctx) {
   const body = await ctx.client().get(routes.macStatus);
@@ -2118,98 +2644,127 @@ async function macStatus(ctx) {
   ]);
 }
 
-// src/commands/numbers.ts
-var OFFICIAL_PROVIDER = 2;
-var CAPABILITY_LABELS = {
-  contacts: "contacts",
-  conversations: "conversations",
-  templates: "templates",
-  health: "health and limit"
-};
-function capabilitiesOf(device) {
-  const official = Number(device.provider) === OFFICIAL_PROVIDER;
-  return ["contacts", "conversations", ...official ? ["templates", "health"] : []];
-}
-function connectionOf(device) {
-  return Number(device.provider) === OFFICIAL_PROVIDER ? "official" : "qr";
-}
-async function listDevices(ctx) {
-  const devices = [];
-  for await (const device of ctx.client().all(routes.devicesList, { query: { perPage: 100 } })) devices.push(device);
-  return devices;
-}
-async function numbersList(ctx) {
-  const devices = await listDevices(ctx);
-  const rows = devices.map((device) => ({
-    ...device,
-    connection: connectionOf(device),
-    cli_capabilities: capabilitiesOf(device)
-  }));
-  ctx.out.result(
-    { numbers: rows },
-    () => rows.length === 0 ? "The account has no numbers." : table(
-      ["id", "alias", "number", "connection", "connected", "health", "what the CLI reads"],
-      rows.map((d) => [
-        d.id,
-        d.alias,
-        d.number,
-        d.connection === "official" ? "official" : "QR",
-        Number(d.connected) === 1 ? "yes" : "no",
-        isRecord(d.health) ? String(d.health.state ?? "-") : null,
-        d.cli_capabilities.map((c) => CAPABILITY_LABELS[c]).join(", ")
-      ])
-    )
-  );
-}
-async function numbersHealth(ctx, ids) {
-  let targets;
-  const wanted = idList(ids, "number");
-  if (wanted.length) {
-    targets = wanted.map((id) => ({ id, label: String(id) }));
-  } else {
-    const devices = (await listDevices(ctx)).filter((d) => connectionOf(d) === "official");
-    targets = devices.map((d) => ({ id: Number(d.id), label: String(d.alias || d.number || d.id) }));
-    if (targets.length === 0) {
-      ctx.out.result({ numbers: [] }, () => "The account has no official numbers: health and limit exist only for the official WhatsApp API.");
-      return;
-    }
+// src/commands/send.ts
+var SEND_TIMEOUT_SECONDS = 90;
+var FIRST_POLL_MS = 1e3;
+var MAX_POLL_MS = 1e4;
+function normalizePhone(value) {
+  const digits = value.trim().replace(/^\+/, "").replace(/[\s\-.()]/g, "");
+  if (!/^\d{7,15}$/.test(digits)) {
+    throw usageError(`The phone must have the country code and only digits, for example 5491122334455: ${value}`);
+  }
+  return digits;
+}
+function messageOf(body) {
+  if (!isRecord(body)) return null;
+  if (isRecord(body.message)) return body.message;
+  if (isRecord(body.data)) return body.data;
+  return "status" in body || "id" in body ? body : null;
+}
+var statusOf = (message) => typeof message.status === "string" ? message.status : null;
+var isFinal = (status) => status === null || status === "read" || status === "failed";
+var shown = (status) => status ?? "unknown";
+async function send(ctx, phoneArg, words, flags) {
+  const phone = normalizePhone(phoneArg);
+  const text2 = words.join(" ");
+  if (text2.trim() === "") throw usageError("The message has no text.");
+  const timeout = flags.timeout === void 0 ? SEND_TIMEOUT_SECONDS : seconds(flags.timeout, "--timeout");
+  const picked = await pickDevice(ctx, flags.device, { qrOnly: false });
+  const from = picked.device ? deviceLabel(picked.device) : `number ${picked.id}`;
+  const client = ctx.client();
+  ctx.out.progress(`Sending to ${phone} from ${from}\u2026`);
+  let answer;
+  try {
+    answer = await client.post(routes.sendMessage, { body: { device_id: picked.id, phone, text: text2 } });
+  } catch (error) {
+    throw explainSendError(error);
+  }
+  let message = messageOf(answer);
+  const messageId = message?.id;
+  const contactId = message?.contact_id;
+  if (!message || messageId === void 0 || messageId === null || contactId === void 0 || contactId === null) {
+    ctx.out.result(
+      { device_id: picked.id, phone, message, outcome: "not_watched" },
+      () => `Sent to ${phone}, but the API did not return the message id: its status cannot be watched.`
+    );
+    return;
   }
-  const results = [];
-  for (const target of targets) {
-    try {
-      const health = await ctx.client().get(routes.deviceHealth, { path: { device: target.id } });
-      results.push({ device_id: target.id, ...isRecord(health) ? health : { health } });
-    } catch (error) {
-      if (error instanceof ApiError && error.status === 422 && error.apiCode === "device_not_meta") {
-        results.push({ device_id: target.id, error: "device_not_meta" });
+  const started = ctx.io.clock();
+  const elapsed = () => Math.round((ctx.io.clock() - started) / 1e3);
+  let status = statusOf(message);
+  const statuses = [{ status, seconds: 0 }];
+  ctx.out.progress(`  ${shown(status)}`);
+  const deadline = started + timeout * 1e3;
+  let delay = FIRST_POLL_MS;
+  const ids = { message_id: messageId, contact_id: contactId };
+  try {
+    while (!isFinal(status) && ctx.io.clock() < deadline) {
+      await pause(ctx, Math.min(delay, deadline - ctx.io.clock()));
+      const read = messageOf(await client.get(routes.messageShow, { path: { contact: String(contactId), message: String(messageId) } }));
+      if (!read) continue;
+      message = read;
+      const next = statusOf(read);
+      if (next === status) {
+        delay = Math.min(delay * 2, MAX_POLL_MS);
         continue;
       }
-      throw error;
+      status = next;
+      statuses.push({ status, seconds: elapsed() });
+      ctx.out.progress(`  ${shown(status).padEnd(10)} after ${elapsed()} s`);
+      delay = FIRST_POLL_MS;
     }
+  } catch (error) {
+    throw alreadySent(error, ids, status);
   }
-  ctx.out.result(
-    { numbers: results },
-    () => table(
-      ["id", "state", "quality", "limit", "per day", "throughput", "updated", "stale"],
-      results.map((r) => {
-        if (r.error === "device_not_meta") return [r.device_id, "not an official number", null, null, null, null, null, null];
-        const h = isRecord(r.health) ? r.health : {};
-        return [
-          r.device_id,
-          str(h.state),
-          str(h.quality_level),
-          str(h.messaging_limit_tier),
-          h.messaging_limit_per_day === null || h.messaging_limit_per_day === void 0 ? "no limit reported" : Number(h.messaging_limit_per_day).toLocaleString("en-US"),
-          str(r.throughput_level),
-          str(h.last_fetched_at),
-          h.stale === true ? "yes" : h.stale === false ? "no" : null
-        ];
-      })
-    )
-  );
+  if (status === "failed") {
+    const failure = isRecord(message.error) ? message.error : {};
+    const why = [failure.title, failure.reason ?? failure.code].filter((v) => v !== null && v !== void 0 && v !== "").map(String);
+    throw new CliError(`The message failed${why.length ? `: ${why.join(" \xB7 ")}` : "."}`, {
+      exitCode: ExitCode.API,
+      code: "message_failed",
+      hint: `Message ${String(messageId)} to ${phone} (contact ${String(contactId)}).`,
+      details: { ...ids, status, error: message.error ?? null, statuses }
+    });
+  }
+  const outcome = status === "read" ? "read" : status === null ? "unknown" : timeout === 0 ? "not_watched" : "timeout";
+  const where = `GET /api/v1/contacts/${String(contactId)}/messages/${String(messageId)}`;
+  ctx.out.result({ device_id: picked.id, phone, message, statuses, outcome }, () => {
+    const head = `Message ${String(messageId)} to ${phone}`;
+    if (outcome === "read") return `${head}: read ${elapsed()} s after sending.`;
+    if (outcome === "unknown") {
+      return [`${head}: the provider did not confirm or reject the send. It may have arrived, and its status will not change.`];
+    }
+    if (outcome === "not_watched") return [`${head}: ${shown(status)} (not watched: --timeout 0).`, `Its status: ${where}`];
+    return [
+      `${head}: ${shown(status)} after ${timeout} s; stopped watching (--timeout).`,
+      ...status === "delivered" ? ["If the recipient turned read receipts off, it stays delivered."] : [],
+      `Its status keeps changing in Funnelchat: ${where}, or the message.status_changed webhook.`
+    ];
+  });
 }
-function str(value) {
-  return value === null || value === void 0 || value === "" ? null : String(value);
+function explainSendError(error) {
+  if (!(error instanceof ApiError)) return error;
+  const add = (line) => {
+    error.hint = [line, error.hint].filter(Boolean).join("\n");
+  };
+  if (error.status === 403 && (error.apiCode === void 0 || error.apiCode === "permission_denied")) {
+    add("Sending needs conversations:send; to a phone that is not a contact yet it also needs conversations:write, because the send creates the contact.");
+  } else if (error.status === 404 && error.apiCode !== "route_not_found") {
+    add("Nothing was sent. The phone may be a contact of another workspace of your account, or --device not one of your numbers.");
+  } else if (error.status === 429 && error.apiCode === "rate_limited") {
+    add("Nothing was sent: the number is sending too fast (per second, or per minute to the same contact).");
+  } else if (error.status === 422 && error.fieldErrors) {
+    add("Nothing was sent.");
+  }
+  return error;
+}
+function alreadySent(error, ids, status) {
+  const cliError = error instanceof InterruptedError ? new CliError(`Stopped watching the message (Ctrl+C); its last status was ${shown(status)}.`, { exitCode: ExitCode.INTERRUPTED, code: "interrupted" }) : toCliError(error);
+  if (error instanceof ApiError && error.status === 403) cliError.hint = [cliError.hint, "Watching the status needs conversations:read."].filter(Boolean).join("\n");
+  const sent = `The message was sent (id ${String(ids.message_id)}, contact ${String(ids.contact_id)}): do not send it again. Its status: GET /api/v1/contacts/${String(ids.contact_id)}/messages/${String(ids.message_id)}`;
+  cliError.hint = [cliError.hint, sent].filter(Boolean).join("\n");
+  Object.assign(cliError.details, ids, { last_status: status });
+  return cliError;
 }
 
 // src/commands/templates.ts
@@ -2234,6 +2789,12 @@ async function templatesList(ctx, flags) {
 }
 
 // src/main.ts
+var FIRST_USE_HELP = `
+First use:
+  funnelchat login                                        paste your key; it is not shown
+  funnelchat connect                                      open the link and scan the QR with WhatsApp
+  funnelchat send 5491122334455 "Hello from Funnelchat"   and watch it: queued, sent, delivered, read
+`;
 var EXIT_CODES_HELP = `
 Exit codes:
   0    all good
@@ -2242,8 +2803,9 @@ Exit codes:
   3    no key, a key the API rejects (401) or a missing permission (403)
   4    not found in your account (404)
   5    an API limit the CLI does not wait for (daily cap or a long Retry-After): it can be resumed
-  6    API or network error, after the retries
+  6    API or network error, after the retries; or the message sent failed (send)
   7    the output already exists: the CLI never overwrites a file
+  8    no number connected within the time (connect)
   130  interrupted with Ctrl+C: an export can be resumed
 
 Environment variables:
@@ -2253,13 +2815,16 @@ Environment variables:
   FUNNELCHAT_RATE        requests per second
   FUNNELCHAT_CONFIG_DIR  where to keep the configuration
 
-The CLI only reads: it sends no messages and changes nothing in your account.`;
+Only connect, send and groups follow change something in your account; every other command only reads.
+A write is sent once and never retried on its own.`;
 async function run(argv, io) {
   let exitCode = ExitCode.OK;
   const program = new Command("funnelchat");
-  program.description("Export conversations and contacts from your Funnelchat account through the public API, and check your numbers, templates and MACs.").version(VERSION, "-V, --version", "Shows the version.").helpOption("-h, --help", "Shows the help.").helpCommand("help [command]", "Shows the help of a command.").option("--profile <name>", "Configuration profile to use.").option("--base-url <url>", "Base URL of the API (https://api.funnelchat.com by default).").option("--staging", "Uses the staging API (https://api-staging.funnelchat.com).").option("--json", "JSON output, for scripts.").option("-v, --verbose", "Shows every request to the API (never the key).").option("-q, --quiet", "No progress messages.").option("--rate <requests>", "Requests per second at most (1 by default).").option("--max-wait <seconds>", "How long to wait for a Retry-After on its own before stopping (60 by default).").addHelpText("after", EXIT_CODES_HELP).showSuggestionAfterError(true).exitOverride().configureOutput({
-    writeOut: (text) => io.stdout.write(text),
-    writeErr: (text) => io.stderr.write(text)
+  program.description(
+    "Connect a WhatsApp number, send a message and watch it get read, and follow groups, through the Funnelchat public API. Also exports conversations and contacts, and checks numbers, templates and MACs."
+  ).version(VERSION, "-V, --version", "Shows the version.").helpOption("-h, --help", "Shows the help.").helpCommand("help [command]", "Shows the help of a command.").option("--profile <name>", "Configuration profile to use.").option("--base-url <url>", "Base URL of the API (https://api.funnelchat.com by default).").option("--staging", "Uses the staging API (https://api-staging.funnelchat.com).").option("--json", "JSON output, for scripts.").option("-v, --verbose", "Shows every request to the API (never the key).").option("-q, --quiet", "No progress messages.").option("--rate <requests>", "Requests per second at most (1 by default).").option("--max-wait <seconds>", "How long to wait for a Retry-After on its own before stopping (60 by default).").addHelpText("after", FIRST_USE_HELP + EXIT_CODES_HELP).showSuggestionAfterError(true).exitOverride().configureOutput({
+    writeOut: (text2) => io.stdout.write(text2),
+    writeErr: (text2) => io.stderr.write(text2)
   });
   const action = (fn) => async (...args) => {
     const command = args[args.length - 1];
@@ -2277,6 +2842,16 @@ 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. 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())));
+  groups.command("follow").argument("<group>", "The uid of the group, as `funnelchat groups` shows it.").description("Follows a group: imports it to your account, so who joins and leaves arrives as webhook events.").option("--device <id>", "Number the group is on (by default the only one connected by QR).").action(action((ctx, command, group) => groupsFollow(ctx, group, command.opts())));
   const numbers = program.command("numbers").description("Your WhatsApp numbers.");
   numbers.command("list").description("Lists the numbers, with their connection and what the CLI can export or read for each one.").action(action((ctx) => numbersList(ctx)));
   numbers.command("health").argument("[numbers...]", "Ids of the numbers (all the official ones by default).").description("Health, quality, messaging limit and throughput of the official numbers.").action(action((ctx, _command, ids) => numbersHealth(ctx, ids ?? [])));
@@ -2295,9 +2870,9 @@ async function run(argv, io) {
   const mac = program.command("mac").description("Monthly active contacts (MACs).");
   mac.command("status").description("How many MACs you have used in the period, the limit and how many are left.").action(action((ctx) => macStatus(ctx)));
   for (const command of program.commands) {
-    command.exitOverride().configureOutput({ writeOut: (text) => io.stdout.write(text), writeErr: (text) => io.stderr.write(text) });
+    command.exitOverride().configureOutput({ writeOut: (text2) => io.stdout.write(text2), writeErr: (text2) => io.stderr.write(text2) });
     for (const sub of command.commands) {
-      sub.exitOverride().configureOutput({ writeOut: (text) => io.stdout.write(text), writeErr: (text) => io.stderr.write(text) });
+      sub.exitOverride().configureOutput({ writeOut: (text2) => io.stdout.write(text2), writeErr: (text2) => io.stderr.write(text2) });
     }
   }
   try {