@vatio-ai/cli 0.37.2

package/lib/commands/channels.mjs

@@ -0,0 +1,322 @@
+// whatsapp / instagram — the two channels a workspace can answer on for real.
+//
+// Each has the same two halves, deliberately mirrored: the workspace's *own*
+// account, which serves live, and a shared preview you can use immediately with
+// no Meta account of your own. `numbers` and `accounts` are the preview halves,
+// and they hang off the channel they belong to because "accounts" on its own
+// would say nothing about which one.
+
+import { deployClient } from "./deploy.mjs";
+import { fail, openBrowser } from "../support.mjs";
+
+export async function whatsapp(config, args) {
+  const workspace = config.resolveWorkspaceRequired();
+  const client = deployClient(config, workspace);
+  const sub = args.shift() ?? "status";
+
+  switch (sub) {
+    case "status": return printWhatsapp(await client.whatsappAccount(), workspace);
+    case "connect": return await connectWhatsapp(client, workspace);
+    case "check": return printWhatsapp(await client.checkWhatsappAccount(), workspace);
+    case "activate": {
+      await client.activateWhatsappAccount();
+      console.log(`Activated WhatsApp on workspace ${workspace} — it answers customers now.`);
+      return;
+    }
+    case "deactivate": {
+      await client.deactivateWhatsappAccount();
+      console.log(`Paused WhatsApp on workspace ${workspace}. The credentials are kept.`);
+      return;
+    }
+    case "disconnect": case "remove": case "rm": {
+      await client.disconnectWhatsappAccount();
+      console.log(`Disconnected WhatsApp from workspace ${workspace}. Vatio stops receiving its messages.`);
+      return;
+    }
+    case "numbers": return await numbers(client, workspace, args);
+    default: fail(whatsappUsage());
+  }
+}
+
+function whatsappUsage() {
+  return `Usage: vatio whatsapp status|connect|check|activate|deactivate|disconnect
+       vatio whatsapp numbers list|add PHONE|verify PHONE CODE|resend PHONE|remove PHONE
+
+  The bare commands drive your own WhatsApp number, which serves live.
+  \`numbers\` registers test phones on the shared WhatsApp preview, which always
+  reach preview — the counterpart of \`vatio instagram accounts\`.
+
+  connect
+    Prints a link to finish in a browser. Connecting a number is Meta's
+    Embedded Signup, a consent screen a person has to read, so there is
+    nothing for a command to do but hand the link over.`;
+}
+
+function printWhatsapp(account, workspace) {
+  if (!account.connected) {
+    console.log(`No WhatsApp number connected to workspace ${workspace}.`);
+    console.log("  Connect yours: vatio whatsapp connect");
+    console.log("  Or test on the shared preview number with no Meta account: vatio whatsapp numbers add +56912345678");
+    return;
+  }
+
+  const label = account.phone_number ?? "your WhatsApp number";
+  console.log(`${label} on workspace ${workspace}:`);
+  console.log(`  status:     ${account.status}`);
+  console.log(`  receiving:  ${account.receiving_messages ? "yes" : "no"}`);
+  console.log(`  active:     ${account.active ? "yes" : "no (paused)"}`);
+  if (account.last_health_error) console.log(`  error:      ${account.last_health_error}`);
+  console.log("");
+
+  // Three things that fail separately, so the advice names which one did.
+  if (account.live_ready) {
+    console.log(`Messages to ${label} reach your live deployment.`);
+    console.log("Change what it answers with: vatio push && vatio publish");
+  } else if (!account.receiving_messages) {
+    console.log("Meta is not delivering this number's messages to Vatio, so the agent");
+    console.log("never sees them. Repair the subscription: vatio whatsapp check");
+  } else if (!account.active) {
+    console.log("Connected and receiving, but paused — nobody gets an answer yet.");
+    console.log("Start answering: vatio whatsapp activate");
+  } else {
+    console.log("Not ready to answer yet. Re-check with: vatio whatsapp check");
+  }
+}
+
+// Prints the link and stops. Meta's Embedded Signup needs a logged-in browser
+// and a person reading a consent screen; there is no headless form of it, and
+// the ids a credentials flag would take do not exist until it has run. Keeping
+// a number in the WhatsApp Business phone app is only possible through it too.
+async function connectWhatsapp(client, workspace) {
+  const payload = await client.whatsappConnectLink();
+  const url = payload.connect_url;
+  if (!url) fail("The platform did not return a connect URL");
+
+  if (payload.connected_number) {
+    console.log(`Workspace ${workspace} is already connected to ${payload.connected_number}.`);
+    console.log("Connecting the same number again renews its access token. To connect a");
+    console.log("different one, run `vatio whatsapp disconnect` first.");
+    console.log("");
+  }
+
+  console.log("Open this to connect your WhatsApp number:");
+  console.log("");
+  console.log(`  ${url}`);
+  console.log("");
+  console.log("Choose your number in Meta's popup. A number already in the WhatsApp");
+  console.log("Business app on your phone stays there — you keep answering from the");
+  console.log("phone and the agent answers on the same number.");
+  console.log("");
+  console.log("Then run `vatio whatsapp`.");
+  // The link is printed first and stays printed: openBrowser is a convenience
+  // that silently does nothing over SSH, in a container, or wherever there is
+  // no browser to open, and the developer still has the URL to paste.
+  openBrowser(url);
+}
+
+async function numbers(client, workspace, args) {
+  const sub = args.shift() ?? "list";
+  const usage = "Usage: vatio whatsapp numbers list|add PHONE|verify PHONE CODE|resend PHONE|remove PHONE";
+
+  if (sub === "list") {
+    const list = asArray((await client.listTestPhoneNumbers()).test_phone_numbers);
+    if (list.length === 0) {
+      console.log(`No test phone numbers on workspace ${workspace}`);
+      console.log("  Register one: vatio whatsapp numbers add +56912345678");
+      return;
+    }
+    console.log(`Test phone numbers on workspace ${workspace} (${list.length}):`);
+    for (const number of list) {
+      const suffix = number.status === "verified" ? `verified ${number.verified_at}` : "pending verification";
+      console.log(`  ${number.phone_number}  ${suffix}`);
+    }
+    console.log("");
+    console.log("They reach the preview deployment on the shared WhatsApp preview number, never live.");
+    return;
+  }
+  if (sub === "add") {
+    const phoneNumber = requireArg(args, "vatio whatsapp numbers add +56912345678");
+    const number = await client.addTestPhoneNumber({ phoneNumber });
+    if (number.already_verified) {
+      console.log(`${number.phone_number} is already verified on workspace ${workspace} — nothing to do.`);
+    } else if (number.moved_from) {
+      console.log(`Moved ${number.phone_number} from workspace ${number.moved_from} to ${workspace}.`);
+      console.log("It was already verified, so no new code was sent.");
+    } else {
+      console.log(`Sent a 6-digit code over WhatsApp to ${number.phone_number}.`);
+      console.log("It is valid for 10 minutes. When it arrives:");
+      console.log("");
+      console.log(`  vatio whatsapp numbers verify ${number.phone_number} 123456`);
+    }
+    return;
+  }
+  if (sub === "verify") {
+    const phoneNumber = requireArg(args, "vatio whatsapp numbers verify +56912345678 123456");
+    const code = requireArg(args, "vatio whatsapp numbers verify +56912345678 123456");
+    const number = await client.verifyTestPhoneNumber({ phoneNumber, code });
+    console.log(
+      number.already_verified
+        ? `${number.phone_number} was already verified on workspace ${workspace}.`
+        : `Verified ${number.phone_number} on workspace ${workspace}.`
+    );
+    console.log("Anything you send from that phone now reaches the preview deployment.");
+    return;
+  }
+  if (sub === "resend") {
+    const phoneNumber = requireArg(args, "vatio whatsapp numbers resend +56912345678");
+    const number = await client.resendTestPhoneNumberCode({ phoneNumber });
+    console.log(
+      number.already_verified
+        ? `${number.phone_number} is already verified on workspace ${workspace} — no code needed.`
+        : `Sent a new 6-digit code to ${number.phone_number}.`
+    );
+    return;
+  }
+  if (sub === "remove" || sub === "delete" || sub === "rm") {
+    const phoneNumber = requireArg(args, "vatio whatsapp numbers remove +56912345678");
+    await client.removeTestPhoneNumber({ phoneNumber });
+    console.log(`Removed ${phoneNumber} from workspace ${workspace}.`);
+    return;
+  }
+
+  fail(usage);
+}
+
+export async function instagram(config, args) {
+  const workspace = config.resolveWorkspaceRequired();
+  const client = deployClient(config, workspace);
+  const sub = args.shift() ?? "status";
+
+  switch (sub) {
+    case "status": return printInstagram(await client.instagramAccount(), workspace);
+    case "connect": return await connectInstagram(client);
+    case "check": return printInstagram(await client.checkInstagramAccount(), workspace);
+    case "disconnect": case "remove": case "rm": {
+      await client.disconnectInstagramAccount();
+      console.log(`Disconnected Instagram from workspace ${workspace}. Vatio stops receiving its DMs.`);
+      return;
+    }
+    case "accounts": return await instagramAccounts(client, workspace, args);
+    default: fail(instagramUsage());
+  }
+}
+
+function instagramUsage() {
+  return `Usage: vatio instagram status|connect|check|disconnect
+       vatio instagram accounts list|add @HANDLE|verify CODE|resend ID|remove ID
+
+  The bare commands drive your own Instagram account, which serves live.
+  \`accounts\` registers test accounts on the shared Instagram preview, which
+  always reach preview — the counterpart of \`vatio whatsapp numbers\`.`;
+}
+
+function printInstagram(account, workspace) {
+  if (!account.connected) {
+    console.log(`No Instagram account connected to workspace ${workspace}.`);
+    console.log("  Connect yours: vatio instagram connect");
+    console.log("  Or test on the shared preview account: vatio instagram accounts add @yourhandle");
+    return;
+  }
+
+  const handle = account.username ? `@${account.username}` : "your Instagram account";
+  console.log(`${handle} on workspace ${workspace}:`);
+  console.log(`  status:     ${account.status}`);
+  console.log(`  receiving:  ${account.receiving_messages ? "yes" : "no"}`);
+  if (account.last_health_error) console.log(`  error:      ${account.last_health_error}`);
+  console.log("");
+
+  if (account.live_ready) {
+    console.log(`DMs to ${handle} reach your live deployment.`);
+    console.log("Change what it answers with: vatio push && vatio publish");
+  } else if (account.token_expired) {
+    console.log("The access token expired. Re-grant it: vatio instagram connect");
+  } else if (!account.receiving_messages) {
+    console.log("Instagram is not delivering this account's messages to Vatio, so the");
+    console.log("agent never sees them. Repair the subscription: vatio instagram check");
+  } else {
+    console.log("Not ready to answer DMs yet. Re-check with: vatio instagram check");
+  }
+}
+
+// Connecting mints a URL for Meta's consent screen rather than taking
+// credentials: granting an app access to an Instagram account is a decision
+// Meta insists a human makes in a browser.
+async function connectInstagram(client) {
+  const payload = await client.instagramConnectLink();
+  const url = payload.url ?? payload.consent_url;
+  if (!url) fail("The platform did not return a consent URL");
+
+  console.log("Open this to grant Vatio access to an Instagram professional account:");
+  console.log("");
+  console.log(`  ${url}`);
+  console.log("");
+  console.log("Then run `vatio instagram check`.");
+  openBrowser(url);
+}
+
+async function instagramAccounts(client, workspace, args) {
+  const sub = args.shift() ?? "list";
+  const usage = "Usage: vatio instagram accounts list|add @HANDLE|verify CODE|resend ID|remove ID";
+
+  if (sub === "list") {
+    const list = asArray((await client.listTestInstagramAccounts()).test_instagram_accounts);
+    if (list.length === 0) {
+      console.log(`No test Instagram accounts on workspace ${workspace}`);
+      console.log("  Register one: vatio instagram accounts add @yourhandle");
+      return;
+    }
+    console.log(`Test Instagram accounts on workspace ${workspace} (${list.length}):`);
+    for (const account of list) {
+      const suffix =
+        account.status === "verified" ? `verified ${account.verified_at}`
+        : account.status === "awaiting_code" ? "code sent — confirm it: vatio instagram accounts verify CODE"
+        : `declared — DM @${account.dm_to} from that account to get a code`;
+      console.log(`  [${account.id}] @${account.username}  ${suffix}`);
+    }
+    return;
+  }
+  if (sub === "add") {
+    const username = requireArg(args, "vatio instagram accounts add @yourhandle").replace(/^@/, "");
+    const account = await client.addTestInstagramAccount({ username });
+    console.log(`Declared @${account.username} on workspace ${workspace}.`);
+    console.log("");
+    // Meta will not let an app DM an account that has not written first, which
+    // is why the code travels in that direction and nothing happens until the
+    // developer sends that first message.
+    console.log(`Now DM @${account.dm_to} from that account. Vatio replies with a 6-digit code:`);
+    console.log("");
+    console.log("  vatio instagram accounts verify 123456");
+    return;
+  }
+  if (sub === "verify") {
+    const code = requireArg(args, "vatio instagram accounts verify 123456");
+    const account = await client.verifyTestInstagramAccount({ code });
+    console.log(`Verified @${account.username} on workspace ${workspace}.`);
+    console.log("DMs from that account now reach the preview deployment.");
+    return;
+  }
+  if (sub === "resend") {
+    const id = requireArg(args, "vatio instagram accounts resend ID");
+    const account = await client.resendTestInstagramAccountCode(id);
+    console.log(`Sent a new code to @${account.username}.`);
+    return;
+  }
+  if (sub === "remove" || sub === "delete" || sub === "rm") {
+    const id = requireArg(args, "vatio instagram accounts remove ID");
+    await client.removeTestInstagramAccount(id);
+    console.log(`Removed test Instagram account ${id} from workspace ${workspace}.`);
+    return;
+  }
+
+  fail(usage);
+}
+
+function requireArg(args, usage) {
+  const value = String(args.shift() ?? "").trim();
+  if (value === "") fail(`Usage: ${usage}`);
+  return value;
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}

package/lib/commands/chat.mjs

@@ -0,0 +1,242 @@
+// `vatio chat …` — a conversation with one of your own deployments.
+//
+// You are always yourself here: the chat belongs to the token you are holding,
+// on the `cli` channel. There is no flag that pretends to be a WhatsApp or
+// Instagram visitor; the shared WhatsApp preview number and the Instagram test
+// accounts do that for real, and a simulated channel was only ever a second
+// answer to keep in step with the true one.
+
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { ApiClient } from "../api-client.mjs";
+import { fail, sleep, takeEnv, takeValue } from "../support.mjs";
+
+export const STATE_FILE = ".vatio-chat.json";
+
+const SUBCOMMANDS = new Set(["transcript", "debug", "reset", "destroy", "delete", "help"]);
+const REMOVED_FLAGS = ["--channel", "--from", "--as", "--sandbox-url"];
+
+export async function chat(config, args) {
+  for (const arg of args) {
+    if (REMOVED_FLAGS.some((flag) => arg === flag || arg.startsWith(`${flag}=`))) {
+      fail(
+        `\`${arg}\` was removed. A CLI chat is you, the developer holding the token. ` +
+          "To test a real channel use `vatio whatsapp numbers` or an Instagram test account; " +
+          "to pick a deployment use --env."
+      );
+    }
+  }
+
+  const environment = takeEnv(args, { fallback: "preview" });
+  const timeout = Number(takeValue(args, "--timeout") ?? 120);
+  const last = Number(takeValue(args, "--last") ?? 10);
+  const apiUrl = takeValue(args, "--api-url");
+  const token = takeValue(args, "--token");
+
+  const options = { environment, timeout, last, apiUrl, token };
+  const sub = SUBCOMMANDS.has(args[0]) ? args.shift() : null;
+
+  if (sub === "help") return console.log(chatHelp());
+  if (sub === "transcript") return await transcript(config, options);
+  if (sub === "debug") return await debugChat(config, options);
+  if (sub === "reset") return await resetChat(config, options);
+  if (sub === "destroy" || sub === "delete") return await destroyChat(config, options, args);
+
+  const message = args.join(" ").trim();
+  if (message === "") return console.log(chatHelp());
+
+  return await converse(config, options, message);
+}
+
+function chatHelp() {
+  return `Usage:
+  vatio chat "message" [--env NAME] [--timeout N]
+  vatio chat transcript [--last N]
+  vatio chat debug [--last N]
+  vatio chat reset
+  vatio chat destroy CHAT_ID
+
+--env picks the deployment that answers: preview (default), live, or a preview
+name like pr-42. A chat against live is a real conversation and shows up in
+your inbox.
+
+The open chat per deployment is remembered in ${STATE_FILE}, so a second
+\`vatio chat\` continues the first. \`reset\` starts over as a visitor the
+workspace has never met.`;
+}
+
+function client(config, options) {
+  const apiUrl = config.resolveApiUrl({ explicit: options.apiUrl });
+  const token = options.token ?? config.resolveToken();
+  if (!apiUrl) fail("A workspace API url is required (--api-url, or base_url + a vatio.yml with `workspace:`)");
+  if (!token) fail("VATIO_TOKEN is required (env or `vatio login`)");
+  return new ApiClient({ baseUrl: apiUrl, token });
+}
+
+function statePath(config) {
+  return join(config.workspaceRootRequired(), STATE_FILE);
+}
+
+function loadState(config) {
+  const path = statePath(config);
+  if (!existsSync(path)) return {};
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    return data && typeof data === "object" && !Array.isArray(data) ? data : {};
+  } catch {
+    return {};
+  }
+}
+
+// One chat per deployment, keyed by environment: switching to `--env live` and
+// back must not throw away the preview conversation you were in the middle of.
+// Chats are dropped wholesale when the api url changes, since a chat id only
+// means anything on the server that issued it.
+function chatsFor(config, apiUrl) {
+  const state = loadState(config);
+  if (state.api_url !== apiUrl) return {};
+  return state.chats && typeof state.chats === "object" ? state.chats : {};
+}
+
+function rememberChat(config, { apiUrl, environment, chatId }) {
+  const chats = { ...chatsFor(config, apiUrl), [environment]: chatId };
+  writeFileSync(statePath(config), `${JSON.stringify({ api_url: apiUrl, chats }, null, 2)}\n`);
+}
+
+async function ensureChat(config, options) {
+  const apiUrl = config.resolveApiUrl({ explicit: options.apiUrl });
+  const existing = chatsFor(config, apiUrl)[options.environment];
+  if (existing) return Number(existing);
+
+  const payload = await openChat(config, options, { apiUrl });
+  return Number(payload.chat_id);
+}
+
+async function openChat(config, options, { apiUrl, chatId = null }) {
+  const api = client(config, options);
+  const payload = chatId
+    ? await api.resetChat({ chatId, environment: options.environment })
+    : await api.createChat({ environment: options.environment });
+
+  rememberChat(config, { apiUrl, environment: options.environment, chatId: payload.chat_id });
+  announce(options.environment);
+  return payload;
+}
+
+// Live is not refused -- you asked for it -- but it is said out loud, once,
+// when the chat opens. A conversation against live is a real one: it lands in
+// the inbox next to the ones visitors started, and nothing downstream knows it
+// came from a terminal.
+function announce(environment) {
+  if (environment === "live") {
+    console.log("Talking to live — this is a real conversation and appears in your inbox.");
+  } else {
+    console.log(`Talking to ${environment}`);
+  }
+}
+
+async function converse(config, options, message) {
+  const api = client(config, options);
+  const chatId = await ensureChat(config, options);
+  const sent = await api.sendChatMessage({ chatId, content: message });
+  const assistant = await waitForAssistant(api, {
+    chatId,
+    after: sent.user_message_id,
+    timeout: options.timeout
+  });
+  console.log(formatVisitor(assistant));
+}
+
+// Conversations are asynchronous: post a message, then poll for the reply.
+async function waitForAssistant(api, { chatId, after, timeout, interval = 2 }) {
+  const deadline = Date.now() + timeout * 1000;
+  for (;;) {
+    const payload = await api.chatMessages({ chatId, view: "visitor", after });
+    const messages = Array.isArray(payload.data) ? payload.data : [];
+    const assistant = [...messages].reverse().find(
+      (entry) => entry.role === "assistant" && String(entry.content ?? "").trim() !== ""
+    );
+    if (assistant) return assistant;
+    if (Date.now() >= deadline) fail(`Timed out waiting for assistant reply after ${timeout}s`);
+    await sleep(interval * 1000);
+  }
+}
+
+async function transcript(config, options) {
+  const api = client(config, options);
+  const chatId = await ensureChat(config, options);
+  const payload = await api.chatMessages({
+    chatId,
+    view: "visitor",
+    limit: Math.min(options.last * 6, 200)
+  });
+  const messages = (Array.isArray(payload.data) ? payload.data : [])
+    .filter((entry) => ["user", "assistant"].includes(entry.role) && !entry.discarded)
+    .slice(-options.last);
+  for (const message of messages) console.log(formatVisitor(message));
+}
+
+async function debugChat(config, options) {
+  const api = client(config, options);
+  const chatId = await ensureChat(config, options);
+
+  console.log("## Chat status (developer)");
+  console.log(JSON.stringify(await api.showChat({ chatId, view: "developer" }), null, 2));
+  console.log("");
+  console.log(`## Transcript (developer/debug, last ${options.last})`);
+  const payload = await api.chatMessages({ chatId, view: "developer", limit: options.last });
+  for (const message of Array.isArray(payload.data) ? payload.data : []) {
+    console.log(`[${message.role}] ${String(message.content ?? "").trim()}`);
+  }
+}
+
+async function resetChat(config, options) {
+  const apiUrl = config.resolveApiUrl({ explicit: options.apiUrl });
+  const payload = await openChat(config, options, {
+    apiUrl,
+    chatId: chatsFor(config, apiUrl)[options.environment] ?? null
+  });
+  console.log(`Reset ${options.environment} chat ${payload.chat_id}`);
+}
+
+// Destroying a chat on the platform must not leave the local state pointing at
+// it: the next `vatio chat` would send a message to an id that is gone. Only
+// that deployment's entry is dropped -- destroying the live chat should not
+// close the preview one.
+async function destroyChat(config, options, args) {
+  const chatId = args.shift();
+  if (!chatId) fail("Usage: vatio chat destroy CHAT_ID");
+
+  const workspace = config.resolveWorkspaceRequired();
+  await client(config, options).destroyChat({ chatId });
+
+  const state = loadState(config);
+  if (state.chats && typeof state.chats === "object") {
+    const kept = Object.fromEntries(
+      Object.entries(state.chats).filter(([, id]) => Number(id) !== Number(chatId))
+    );
+    const path = statePath(config);
+    if (Object.keys(kept).length === 0 && Object.keys(state.chats).length > 0) {
+      writeFileSync(path, `${JSON.stringify({ ...state, chats: {} }, null, 2)}\n`);
+    } else if (existsSync(path)) {
+      writeFileSync(path, `${JSON.stringify({ ...state, chats: kept }, null, 2)}\n`);
+    }
+  }
+
+  console.log(`Destroyed chat ${chatId} in ${workspace}`);
+}
+
+function formatVisitor(message) {
+  if (!message) return "";
+  const role = message.role === "assistant" ? "agent" : "you";
+  return `[${role}] ${String(message.content ?? "").trim()}`;
+}
+
+export function removeLegacyChatState(root) {
+  // `.vatio-sandbox.json` held a chat id *and* the simulated identity it was
+  // opened with. The identity half no longer means anything, so it is removed
+  // rather than migrated.
+  const legacy = join(root, ".vatio-sandbox.json");
+  if (existsSync(legacy)) rmSync(legacy);
+}