@vatio-ai/cli 0.116.0 → 0.117.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -36,11 +36,48 @@ export class ApiClient extends HttpClient {
36
36
  return this.get("/whatsapp");
37
37
  }
38
38
 
39
+ setWhatsappLive(active) {
40
+ return this.patch("/whatsapp/live", { active });
41
+ }
42
+
43
+ checkWhatsapp() {
44
+ return this.post("/whatsapp/health_check", {});
45
+ }
46
+
47
+ disconnectWhatsapp() {
48
+ return this.delete("/whatsapp");
49
+ }
50
+
51
+ inviteWhatsappConnector(body) {
52
+ return this.post("/whatsapp/invite", body);
53
+ }
54
+
55
+ whatsappTeam() {
56
+ return this.get("/whatsapp/team");
57
+ }
58
+
59
+ moveTestPhone(phoneNumber) {
60
+ return this.post(`/test_phones/${encode(phoneNumber)}/move`, {});
61
+ }
62
+
63
+ syncTemplates() {
64
+ return this.post("/templates/sync", {});
65
+ }
66
+
39
67
  // The phones verified in Try the agent.
40
68
  testPhones() {
41
69
  return this.get("/test_phones");
42
70
  }
43
71
 
72
+ // The code a phone sends to Vatio's shared number to join; it adds nothing by itself.
73
+ testPhoneCode() {
74
+ return this.post("/test_phones", {});
75
+ }
76
+
77
+ removeTestPhone(phoneNumber) {
78
+ return this.delete(`/test_phones/${encode(phoneNumber)}`);
79
+ }
80
+
44
81
  deployedManifest({ environment = "live" } = {}) {
45
82
  return this.get("/manifest", { environment });
46
83
  }
@@ -256,6 +293,10 @@ export class ApiClient extends HttpClient {
256
293
  return this.post("/templates", payload);
257
294
  }
258
295
 
296
+ deleteTemplate({ name, language = null }) {
297
+ return this.delete(`/templates/${encode(name)}${query({ language })}`);
298
+ }
299
+
259
300
  listWebhookEndpoints() {
260
301
  return this.get("/webhook_endpoints");
261
302
  }
@@ -1,45 +1,76 @@
1
- // whatsapp / instagram -- both are set up in the inbox: connecting your own
2
- // number or account needs Meta's consent screen, and test phones and accounts
3
- // are a form with a code. The CLI only says where, and that depends on whether
4
- // the workspace has published: before, "Try the agent", where test phones and
5
- // accounts are verified; after, the channel's own page (WhatsApp, Instagram).
1
+ // whatsapp / instagram -- connecting your own number or account needs Meta's
2
+ // consent screen, so `connect` prints where in the inbox, and that depends on
3
+ // whether the workspace has published: before, "Try the agent"; after, the
4
+ // channel's own page. Everything else on the WhatsApp page is here too.
6
5
  // vatio.ai/workspaces is only for a server too old to send the link, and
7
6
  // redirects to the inbox.
8
7
 
9
8
  import { deployClient } from "./deploy.mjs";
10
- import { fail, paint, takeFlag } from "../support.mjs";
9
+ import { messages } from "./messages.mjs";
10
+ import { withSecondFactor } from "./team.mjs";
11
+ import { templates } from "./webhooks.mjs";
12
+ import { ask, fail, paint, takeFlag, takeValue } from "../support.mjs";
11
13
 
12
- const WHATSAPP_USAGE =
13
- "Usage: vatio whatsapp [test-phones [--json]]";
14
+ const WHATSAPP_USAGE = [
15
+ "Usage: vatio whatsapp [status] [--json]",
16
+ " vatio whatsapp connect | live on|off | check | disconnect [--yes] | team",
17
+ " vatio whatsapp invite EMAIL [--code CODE | --recovery-code CODE]",
18
+ " vatio whatsapp phones [list] | add | rm PHONE | move PHONE [--json]",
19
+ " vatio whatsapp templates [list] | create NAME ... | rm NAME | sync",
20
+ " vatio whatsapp failed [--since DATE] [--until DATE] [--error-code CODE] ...",
21
+ ].join("\n");
14
22
  // The list of who the agent answered on your own number is gone: it answers
15
- // everyone, and Live off in the inbox is how it answers nobody.
23
+ // everyone, and `vatio whatsapp live off` is how it answers nobody.
16
24
  const AGENT_NUMBERS_REMOVED =
17
25
  "`vatio whatsapp only` and `everyone` were removed: the agent answers everyone who writes to your number. " +
18
- "To have it answer nobody, turn Live off in the inbox, on the WhatsApp page.";
26
+ "To have it answer nobody: vatio whatsapp live off.";
19
27
  // "Your numbers" were a list typed by hand; the team's numbers took its place.
20
28
  const MINE_REMOVED =
21
29
  "`vatio whatsapp mine` was removed: the team's numbers are the ones each member verified on their account " +
22
- "(Account in the inbox), so there is no list to set. A tool declares which role may use it with " +
30
+ "(Account in the inbox): vatio whatsapp team. A tool declares which role may use it with " +
23
31
  "`access: supervisor`, `developer` or `owner`.";
24
32
 
33
+ // One noun per thing on the inbox's WhatsApp page, each with the same verbs:
34
+ // the number itself, its test phones, its templates and its failed messages.
35
+ // `test-phones`, `vatio templates` and `vatio messages failed` still work.
25
36
  export async function whatsapp(config, args = []) {
37
+ const json = takeFlag(args, "--json");
26
38
  const sub = args.shift();
27
- if (sub === undefined) {
28
- await inInbox(config, { name: "WhatsApp", key: "whatsapp", own: "number", test: "phone" });
29
- // A server that predates the route answers 404; the link above is enough.
30
- await printTestPhones(config).catch((error) => {
31
- if (error?.status !== 404 && error?.body?.error?.code !== "not_found") throw error;
32
- });
33
- return printNumber(config);
39
+ const client = () => deployClient(config, config.resolveWorkspaceRequired());
40
+ switch (sub) {
41
+ case undefined:
42
+ case "status":
43
+ return status(config, client(), { json });
44
+ case "connect":
45
+ return inInbox(config, { name: "WhatsApp", key: "whatsapp", own: "number", test: "phone" });
46
+ case "live": {
47
+ const value = args.shift();
48
+ if (!["on", "off"].includes(value) || args.length) fail(WHATSAPP_USAGE);
49
+ return printNumber(await client().setWhatsappLive(value === "on"), { json });
50
+ }
51
+ case "check":
52
+ return printNumber(await client().checkWhatsapp(), { json });
53
+ case "disconnect":
54
+ return disconnect(client(), args, { json });
55
+ case "invite":
56
+ return invite(client(), args, { json });
57
+ case "team":
58
+ return printTeam(await client().whatsappTeam(), { json });
59
+ case "phones":
60
+ case "test-phones":
61
+ return phones(config, client(), args, { json });
62
+ case "templates":
63
+ return templates(config, json ? [...args, "--json"] : args);
64
+ case "failed":
65
+ return messages(config, ["failed", ...args, ...(json ? ["--json"] : [])]);
66
+ case "only":
67
+ case "everyone":
68
+ return fail(AGENT_NUMBERS_REMOVED);
69
+ case "mine":
70
+ return fail(MINE_REMOVED);
71
+ default:
72
+ return fail(WHATSAPP_USAGE);
34
73
  }
35
- if (sub === "test-phones") {
36
- const json = takeFlag(args, "--json");
37
- if (args.length > 0) fail(WHATSAPP_USAGE);
38
- return printTestPhones(config, { json });
39
- }
40
- if (sub === "only" || sub === "everyone") fail(AGENT_NUMBERS_REMOVED);
41
- if (sub === "mine") fail(MINE_REMOVED);
42
- fail(WHATSAPP_USAGE);
43
74
  }
44
75
 
45
76
  export const instagram = (config) =>
@@ -59,34 +90,106 @@ async function inInbox(config, channel) {
59
90
  console.log(` ${published ? url : (status.try_url ?? url)}`);
60
91
  }
61
92
 
93
+ async function status(config, client, { json }) {
94
+ let number = null;
95
+ try {
96
+ number = await client.getWhatsapp();
97
+ } catch (error) {
98
+ if (error?.body?.error?.code !== "whatsapp_not_connected") throw error;
99
+ }
100
+ if (json) return console.log(JSON.stringify(number ?? { connected: false }, null, 2));
101
+ await inInbox(config, { name: "WhatsApp", key: "whatsapp", own: "number", test: "phone" });
102
+ // A server that predates the route answers 404; the link above is enough.
103
+ await printPhones(await client.testPhones()).catch((error) => {
104
+ if (error?.status !== 404 && error?.body?.error?.code !== "not_found") throw error;
105
+ });
106
+ if (number) printNumber(number);
107
+ }
108
+
109
+ async function phones(config, client, args, { json }) {
110
+ const action = args.shift() ?? "list";
111
+ const phone = args.shift();
112
+ if (args.length) fail(WHATSAPP_USAGE);
113
+ if (action === "list" && !phone) {
114
+ const list = await client.testPhones();
115
+ return json ? console.log(JSON.stringify(list, null, 2)) : printPhones(list);
116
+ }
117
+ if (action === "add" && !phone) return printJoin(await client.testPhoneCode(), { json });
118
+ if (action === "rm" && phone) {
119
+ await client.removeTestPhone(phone);
120
+ return json ? console.log(JSON.stringify({ removed: phone })) : console.log(`Removed ${phone} from the test phones.`);
121
+ }
122
+ if (action === "move" && phone) {
123
+ const { data } = await client.moveTestPhone(phone);
124
+ return json ? console.log(JSON.stringify(data)) : console.log(`${data.phone_number} now tests this workspace.`);
125
+ }
126
+ fail(WHATSAPP_USAGE);
127
+ }
128
+
62
129
  // The phones that joined by sending Try the agent's code: the ones a preview
63
- // message can go to. Adding one is only in the inbox.
64
- async function printTestPhones(config, { json = false } = {}) {
65
- const { data = [], max } = await deployClient(config, config.resolveWorkspaceRequired()).testPhones();
66
- if (json) return console.log(JSON.stringify({ data, max }, null, 2));
130
+ // message can go to.
131
+ function printPhones({ data = [], max, elsewhere = [] }) {
67
132
  if (data.length === 0) {
68
- console.log("\nNo test phones yet. Add yours with Try the agent in the inbox: send it the code it shows.");
69
- return;
133
+ console.log("\nNo test phones yet. Add yours: vatio whatsapp phones add");
134
+ } else {
135
+ console.log(`\nTest phones (${data.length} of ${max}):`);
136
+ for (const phone of data) console.log(` ${phone.phone_number}`);
137
+ }
138
+ if (elsewhere.length) {
139
+ console.log("Verified on your other workspaces (vatio whatsapp phones move PHONE brings one here):");
140
+ for (const phone of elsewhere) console.log(` ${phone.phone_number} ${phone.workspace}`);
70
141
  }
71
- console.log(`\nTest phones (${data.length} of ${max}), verified in Try the agent:`);
72
- for (const phone of data) console.log(` ${phone.phone_number}`);
73
142
  }
74
143
 
75
- // After the inbox link: a workspace with no number of its own has nothing
76
- // more to show, and the link already says what to do.
77
- async function printNumber(config) {
78
- const client = deployClient(config, config.resolveWorkspaceRequired());
79
- try {
80
- printLive(await client.getWhatsapp());
81
- } catch (error) {
82
- if (error?.body?.error?.code === "whatsapp_not_connected") return;
83
- throw error;
144
+ // The same code Try the agent shows: the phone joins when it sends it, so the
145
+ // message is the proof that whoever added it holds the phone.
146
+ function printJoin(join, { json }) {
147
+ if (json) return console.log(JSON.stringify(join, null, 2));
148
+ console.log(`From the phone to add, send this to ${join.send_to ?? "Vatio's test number"} on WhatsApp:`);
149
+ console.log(` ${join.message}`);
150
+ if (join.link_url) console.log(`Or open this on the phone, it writes the message:\n ${join.link_url}`);
151
+ console.log(`The code works for ${Math.round((join.expires_in ?? 900) / 60)} minutes. Check with: vatio whatsapp phones`);
152
+ }
153
+
154
+ async function disconnect(client, args, { json }) {
155
+ const yes = takeFlag(args, "--yes");
156
+ if (args.length) fail(WHATSAPP_USAGE);
157
+ if (!yes) {
158
+ if (!process.stdin.isTTY) fail("Disconnecting stops the agent answering on your number, so without a terminal it needs --yes.");
159
+ const answer = await ask(`${paint("green", "?")} Disconnect your WhatsApp number? Type yes: `);
160
+ if (answer.trim().toLowerCase() !== "yes") fail("Nothing changed.");
84
161
  }
162
+ const after = await client.disconnectWhatsapp();
163
+ if (json) return console.log(JSON.stringify(after, null, 2));
164
+ console.log("Disconnected. Connect a number again with: vatio whatsapp connect");
165
+ }
166
+
167
+ // The owner's: whoever holds the number (often a client) gets the link that
168
+ // connects it, and joins as a supervisor. Confirmed with a second factor, as
169
+ // `vatio team invite` is.
170
+ async function invite(client, args, { json }) {
171
+ const code = takeValue(args, "--code");
172
+ const recoveryCode = takeValue(args, "--recovery-code");
173
+ const email = args.shift();
174
+ if (!email || args.length) fail(WHATSAPP_USAGE);
175
+ const answer = await withSecondFactor((body) => client.inviteWhatsappConnector(body),
176
+ { email, code, recovery_code: recoveryCode });
177
+ if (json) return console.log(JSON.stringify(answer, null, 2));
178
+ console.log(`Emailed ${answer.invited} the link that connects your number (${answer.role} on the team).`);
179
+ }
180
+
181
+ function printTeam({ members = [] }, { json }) {
182
+ if (json) return console.log(JSON.stringify(members, null, 2));
183
+ if (members.length === 0) return console.log("No one on the team has verified their WhatsApp yet (Account, in the inbox).");
184
+ for (const member of members) console.log(` ${member.role.padEnd(11)} ${member.number} ${member.name}`);
85
185
  }
86
186
 
87
- function printLive(number) {
187
+ function printNumber(number, { json = false } = {}) {
188
+ if (json) return console.log(JSON.stringify(number, null, 2));
88
189
  const live = number.live
89
190
  ? paint("green", "live: the agent answers everyone who writes")
90
- : paint("cyan", "paused: Live is off in the inbox, on the WhatsApp page");
91
- console.log(`\n${number.display_phone_number ?? "Your number"}: ${live}`);
191
+ : paint("cyan", "paused: vatio whatsapp live on to answer");
192
+ console.log(`\n${number.number ?? number.display_phone_number ?? "Your number"}: ${live}`);
193
+ if (number.last_health_error) console.log(` ${paint("red", "problem:")} ${number.last_health_error} (vatio whatsapp check)`);
194
+ if (number.failed_deliveries) console.log(` ${number.failed_deliveries} failed deliveries: vatio whatsapp failed`);
92
195
  }
@@ -67,16 +67,19 @@ function print(answer, workspace, json) {
67
67
  // An owner with a second factor confirms it is them, as the inbox asks. From a
68
68
  // terminal the code is asked for; a coding agent has none, so it fails with what
69
69
  // to ask the person for.
70
- async function invite(client, body) {
70
+ // `vatio whatsapp invite` asks the same way.
71
+ const invite = (client, body) => withSecondFactor((confirmed) => client.inviteMember(confirmed), body);
72
+
73
+ export async function withSecondFactor(send, body) {
71
74
  const confirmed = Object.fromEntries(Object.entries(body).filter(([, value]) => value));
72
75
  try {
73
- return await client.inviteMember(confirmed);
76
+ return await send(confirmed);
74
77
  } catch (error) {
75
78
  const needsCode = error?.status === 403 && error?.body?.error?.code === "reauthentication_required";
76
79
  if (!needsCode || confirmed.code || confirmed.recovery_code) throw error;
77
80
  if (!process.stdin.isTTY || !/--code/.test(error.message)) throw error;
78
81
  const code = await askSecret(`${paint("green", "?")} Code from your authenticator app: `);
79
- return await client.inviteMember({ ...confirmed, code });
82
+ return await send({ ...confirmed, code });
80
83
  }
81
84
  }
82
85
 
@@ -19,6 +19,8 @@ function takeAll(args, name) {
19
19
  const LIST_USAGE = "vatio templates list [--env live] [--json]";
20
20
  const CREATE_USAGE = "vatio templates create NAME --language CODE --body TEXT [--example VALUE]... " +
21
21
  "[--category utility|marketing] [--footer TEXT] [--json]";
22
+ const RM_USAGE = "vatio templates rm NAME [--language CODE] [--json]";
23
+ const SYNC_USAGE = "vatio templates sync [--json]";
22
24
 
23
25
  export async function templates(config, args) {
24
26
  const json = takeFlag(args, "--json");
@@ -26,11 +28,20 @@ export async function templates(config, args) {
26
28
  args.shift();
27
29
  return createTemplate(config, args, json);
28
30
  }
31
+ if (args[0] === "sync") {
32
+ const payload = await deployClient(config, config.resolveWorkspaceRequired()).syncTemplates();
33
+ if (json) return console.log(JSON.stringify(payload.templates ?? [], null, 2));
34
+ return console.log(`Synced ${(payload.templates ?? []).length} templates from Meta. See them: vatio whatsapp templates`);
35
+ }
36
+ if (args[0] === "rm") {
37
+ args.shift();
38
+ return deleteTemplate(config, args, json);
39
+ }
29
40
  const environment = takeEnv(args, { fallback: "live" });
30
41
  const workspace = config.resolveWorkspaceRequired();
31
42
  const client = deployClient(config, workspace);
32
43
  const sub = args.shift() ?? "list";
33
- if (sub !== "list") fail(`Usage: ${LIST_USAGE}\n ${CREATE_USAGE}`);
44
+ if (sub !== "list") fail(`Usage: ${LIST_USAGE}\n ${CREATE_USAGE}\n ${RM_USAGE}\n ${SYNC_USAGE}`);
34
45
 
35
46
  const payload = await client.listTemplates({ environment });
36
47
  const list = Array.isArray(payload.templates) ? payload.templates : [];
@@ -101,6 +112,19 @@ async function createTemplate(config, args, json) {
101
112
  }
102
113
  }
103
114
 
115
+ // Where create put it: the workspace's own number, or Vatio's test number
116
+ // before it has one. Every language under the name unless one is given.
117
+ async function deleteTemplate(config, args, json) {
118
+ const language = takeValue(args, "--language");
119
+ const name = args.shift();
120
+ if (!name || args.length > 0) fail(`Usage: ${RM_USAGE}`);
121
+
122
+ const client = deployClient(config, config.resolveWorkspaceRequired());
123
+ const { deleted = [] } = await client.deleteTemplate({ name, language });
124
+ if (json) return console.log(JSON.stringify(deleted, null, 2));
125
+ for (const template of deleted) console.log(`Deleted ${template.name} (${template.language}).`);
126
+ }
127
+
104
128
  export async function webhooks(config, args) {
105
129
  const environment = takeEnv(args, { fallback: "live" });
106
130
  const label = takeValue(args, "--label");
package/lib/help.mjs CHANGED
@@ -182,22 +182,7 @@ the two you are in. Commands default as listed.
182
182
  keys revoke PREFIX
183
183
  auth --new-key Keypair that signs the JWT saying who a visitor is
184
184
 
185
- Recover outbound WhatsApp messages (with your developer login):
186
- Vatio retries confirmed failures automatically. Inspect terminal failures:
187
- messages failed [--since DATE] [--until DATE] [--error-code CODE]
188
- [--error-contains TEXT] [--before ID] [--json]
189
- List failed outgoing messages, including Meta's
190
- delivery failures (default: live)
191
-
192
- Sending from your backend (WhatsApp, with a server key):
193
- templates list [--env live] [--json]
194
- The number's templates, parameter counts, and the
195
- "template" object to send
196
- templates create NAME --language CODE --body TEXT [--example VALUE]...
197
- [--category utility|marketing] [--footer TEXT] [--json]
198
- Submit a template for Meta's review: on your number,
199
- or on Vatio's test number until you connect one;
200
- one --example per {{n}} in the body
185
+ Sending from your backend (with a server key):
201
186
  webhooks list|create URL [--event NAME]...|test ID|deliveries ID|enable ID|rm ID
202
187
  Where Vatio tells your backend what happened
203
188
 
@@ -208,12 +193,37 @@ the two you are in. Commands default as listed.
208
193
  contacts delete ID [--yes] Delete them and everything about them, for good. Asks you
209
194
  to type the ID; without a terminal, needs --yes
210
195
 
196
+ WhatsApp (everything on the inbox's WhatsApp page; --json on each):
197
+ whatsapp [status] Your number, whether it is live, its problems,
198
+ and the test phones
199
+ whatsapp connect Where to connect your number (Meta's consent
200
+ screen only opens in the inbox)
201
+ whatsapp live on|off Answer everyone who writes, or nobody
202
+ whatsapp check Check the number with Meta and re-subscribe it
203
+ whatsapp disconnect [--yes]
204
+ whatsapp invite EMAIL [--code CODE]
205
+ Email whoever holds the number the link that
206
+ connects it (owner only)
207
+ whatsapp team Who on the team verified their own WhatsApp
208
+ whatsapp phones [list] Test phones on Vatio's shared preview number
209
+ whatsapp phones add The code a phone sends to join, and its link
210
+ whatsapp phones rm PHONE | move PHONE
211
+ Remove one, or bring one you verified elsewhere
212
+ whatsapp templates [list] [--env live]
213
+ The number's templates and the "template" to send
214
+ whatsapp templates create NAME --language CODE --body TEXT [--example VALUE]...
215
+ [--category utility|marketing] [--footer TEXT]
216
+ Submit one for Meta's review: on your number, or
217
+ on Vatio's test number until you connect one
218
+ whatsapp templates rm NAME [--language CODE] | sync
219
+ Delete one at Meta; pull back ones made elsewhere
220
+ whatsapp failed [--since DATE] [--until DATE] [--error-code CODE]
221
+ [--error-contains TEXT] [--before ID]
222
+ Messages Vatio gave up retrying (default: live)
223
+ templates ... Older spelling of whatsapp templates; still works
224
+ messages failed ... Older spelling of whatsapp failed; still works
225
+
211
226
  Channels:
212
- whatsapp Set up in the inbox; prints the link (Try the agent
213
- until you publish, then Channels)
214
- whatsapp test-phones [--json]
215
- The phones verified in Try the agent, to send a
216
- preview message to
217
227
  instagram The same, for Instagram
218
228
 
219
229
  Everything else:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vatio-ai/cli",
3
- "version": "0.116.0",
3
+ "version": "0.117.0",
4
4
  "description": "Vatio CLI — deploy and manage Vatio agent workspaces",
5
5
  "keywords": [
6
6
  "vatio",