@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/flows.mjs

@@ -1,261 +1,261 @@
-/**
- * Tool family: flows - the automation that runs whether anybody is watching.
- *
- * Workstreams B2, B3 and B4. Sequences, workflows, enquiry capture, gambits,
- * forms, questionnaires, SMS, spend and job costing all ran invisibly to the
- * terminal.
- *
- * 🚨 The worst gap here was collision. A connector that cannot see a running
- * sequence will happily propose writing to somebody it is already emailing, and two
- * messages from one business on one day is how a good prospect is lost.
- *
- * 🚨 READ ONLY, except km_send_sms: one text the owner approved word for word, gated
- * server-side by a confirm token. Enrolling, pausing and firing automation act on real
- * people and stay in the web app.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'flows';
-
-export const TOOLS = [
-  'km_list_sequences',
-  'km_list_workflows',
-  'km_inquiry_sources',
-  'km_list_gambits',
-  'km_list_forms',
-  'km_list_questionnaires',
-  'km_list_sms',
-  'km_send_sms',
-  'km_list_expenses',
-  'km_list_job_costs',
-  'km_list_rentals',
-  'km_music_settings',
-];
-
-export const PROFILES = ['outreach', 'money'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'Your KM Hub does not expose this surface to the terminal yet. That is not a fault: the workspace is fine and every ' +
-  'other tool works as normal. It is there in the web app at https://hub.kivimedia.co.';
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_list_sequences',
-    'Who is enrolled in an automated sequence, which step they are on, when the next message goes, and why anybody ' +
-      'stopped. ' +
-      '🚨 CALL THIS BEFORE DRAFTING TO ANYONE. `actively_enrolled` is the number that matters: those contacts are ' +
-      'already being messaged automatically. Writing to somebody a sequence is mid-way through means two messages from ' +
-      'one business on one day, which reads as chaotic and loses good prospects. It is the single most valuable check ' +
-      'in this family and it is invisible everywhere else. ' +
-      '`stop_reason` is worth reading too: the same reason recurring is a sequence problem, not bad luck. Read only.',
-    {
-      status: z.string().optional().describe('Narrow to one state, for example active, stopped or completed.'),
-      limit: z.number().int().min(1).max(200).optional().describe('How many enrolments, newest first. Default 50.'),
-    },
-    async ({ status, limit }) => {
-      const r = await call('GET', `/flows/sequences${qs({ status, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_workflows',
-    'The automations configured on this workspace, what triggers each one, and whether it is switched on. ' +
-      'Use it before telling anybody that nothing will happen automatically, and when something occurred that nobody ' +
-      'remembers doing. An active workflow acts without a human present, so "I did not send that" and "nothing was ' +
-      'sent" are different claims and this tool separates them. ' +
-      'Step definitions are not returned: what matters is what fires and whether it is on. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/flows/workflows');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_inquiry_sources',
-    'Where enquiries actually came from, counted by source and by status. ' +
-      'Use it whenever the user asks where their work comes from, or before recommending they spend more effort ' +
-      'anywhere. 🚨 The answer is very often different from what the owner believes, and that gap is one of the more ' +
-      'valuable things you can show them. Read only.',
-    {
-      limit: z.number().int().min(1).max(200).optional().describe('How many enquiries to count over, newest first. Default 50.'),
-    },
-    async ({ limit }) => {
-      const r = await call('GET', `/flows/inquiries${qs({ limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_gambits',
-    'The lead gambits configured on this workspace. Use it when the user mentions a gambit by name or asks what is set ' +
-      'up. Configuring one happens in KM Hub. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/flows/gambits');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_forms',
-    'The booking and lead forms on this workspace and which are actually live. ' +
-      'A live form is a public front door, so `live_count` of zero is worth saying out loud: it means there is no route ' +
-      'for somebody to enquire through, however good the marketing is. Use it before advising anything about capturing ' +
-      'leads. Field configuration is not returned; editing happens in KM Hub. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/flows/forms');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_questionnaires',
-    'Questionnaires sent to clients, and whether they were viewed and answered. ' +
-      '🚨 `sent_but_unanswered` is the number to lead with. Each one is event detail nobody has, and missing detail ' +
-      'does not stay quiet: it surfaces on the day rather than politely in advance. Answers themselves live in KM Hub. ' +
-      'Read only.',
-    {
-      limit: z.number().int().min(1).max(200).optional().describe('How many, newest first. Default 50.'),
-    },
-    async ({ limit }) => {
-      const r = await call('GET', `/flows/questionnaires${qs({ limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_sms',
-    'Text messages in and out of the business line, grouped into threads, with who each is with, direction and the ' +
-      'words. Texts the owner typed in the Quo app on their phone are included, so a thread is the whole exchange. ' +
-      'Use it when the user asks what came in by text, what a client texted, or whether somebody was actually reached. ' +
-      'Without arguments you get the latest texts plus `threads`, where `awaiting_your_reply: true` means the customer ' +
-      'had the last word. To read one conversation in order, pass `thread_of` with any message id from it, or ' +
-      '`client_id`. ' +
-      '🚨 An inbound text nobody answered is the fastest-decaying message a business gets: people who text expect a ' +
-      'text back, and an hour is already late. Phone numbers are deliberately not returned. To answer, use km_send_sms.',
-    {
-      limit: z.number().int().min(1).max(200).optional().describe('How many messages. Default 50.'),
-      thread_of: z.string().optional().describe('Any message id in a conversation: returns that whole thread, oldest first.'),
-      client_id: z.string().optional().describe('A client id: returns the texts linked to that client, oldest first.'),
-    },
-    async ({ limit, thread_of, client_id }) => {
-      const r = await call('GET', `/flows/sms${qs({ limit, thread_of, client_id })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_send_sms',
-    'Send ONE text message to a customer from the business line. It is a real text on their phone and cannot be ' +
-      'unsent, and it is logged on the client\'s timeline and in km_list_sms automatically. ' +
-      'Pick the recipient ONE way: `reply_to_message_id` (a message id from km_list_sms - answers that thread without ' +
-      'the number ever passing through this chat), `client_id`, or `to` (a phone number the user gave you). ' +
-      '🚨 Write the text, show the user the exact words, and send only the words they approved. The first call returns ' +
-      'a confirmation carrying a sentence written by the server about what will happen, plus a token. Read that ' +
-      'sentence to the user as it is, get a yes to THIS text, then call again with the same arguments and ' +
-      'confirm_token. Any change to the words needs a new confirmation. Keep it short and human: a text, not an email.',
-    {
-      text: z.string().describe('The exact words to send, as the user approved them.'),
-      reply_to_message_id: z.string().optional().describe('Answer this thread: a message id from km_list_sms.'),
-      client_id: z.string().optional().describe('Text this client at the phone number on their record.'),
-      to: z.string().optional().describe('A phone number the user gave you, when there is no thread or client.'),
-      confirm_token: z
-        .string()
-        .optional()
-        .describe('Only on the second call, after the user read the confirmation sentence and said yes. Never invent one.'),
-    },
-    async ({ text: words, reply_to_message_id, client_id, to, confirm_token }) => {
-      const body = { text: words };
-      if (reply_to_message_id) body.reply_to_message_id = String(reply_to_message_id);
-      if (client_id) body.client_id = String(client_id);
-      if (to) body.to = String(to);
-      if (confirm_token) body.confirm_token = String(confirm_token);
-      const r = await call('POST', '/flows/sms/send', body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_expenses',
-    'What has been spent in a window, split into what is billable to a client and what the business absorbs, with ' +
-      'totals by category. Defaults to the last 90 days. ' +
-      '🚨 `absorbed` is the number that decides whether a busy month was a profitable one, and it is the one nobody ' +
-      'looks at. The money tools answer what came IN; without this you can describe a healthy-looking month with no idea ' +
-      'whether any of it was kept. All amounts are in CENTS. Read only.',
-    {
-      from: z.string().optional().describe('Start date, YYYY-MM-DD. Default 90 days ago.'),
-      to: z.string().optional().describe('End date, YYYY-MM-DD. Default tomorrow.'),
-      limit: z.number().int().min(1).max(500).optional().describe('How many entries. Default 100. Check `truncated` before trusting a total.'),
-    },
-    async ({ from, to, limit }) => {
-      const r = await call('GET', `/ops/expenses${qs({ from, to, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_job_costs',
-    'Jobs that have been costed, with the overhead and target profit assumptions behind each. ' +
-      '🚨 Those percentages are ASSUMPTIONS the owner set when costing the job, NOT margin achieved. Describing an ' +
-      'intended margin as a delivered one is the most misleading thing you could do with this data, so say "targeted" ' +
-      'rather than "made". Line-item detail lives in KM Hub. Read only.',
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many costed jobs, newest first. Default 25.'),
-    },
-    async ({ limit }) => {
-      const r = await call('GET', `/ops/job-costing${qs({ limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_rentals',
-    'Stock holds and the rental lines sitting on proposals: what is held, for whom, between which dates, and what is ' +
-      'reserved. ' +
-      '🚨 A HOLD is stock promised to somebody who has NOT committed. An expiring hold that nobody chases ' +
-      'silently releases kit a buyer still believes is theirs, which is worse than never holding it, so ' +
-      '`holds_with_an_expiry` is worth raising. Amounts are in CENTS. Releasing or extending a hold happens in KM Hub. ' +
-      'Read only.',
-    {
-      limit: z.number().int().min(1).max(200).optional().describe('How many holds and rental lines. Default 50.'),
-    },
-    async ({ limit }) => {
-      const r = await call('GET', `/ops/rentals${qs({ limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_music_settings',
-    'What clients may request on the public music page: the per-event request limit, whether off-catalogue requests are ' +
-      'allowed, whether remaining requests are shown, and whether Spotify is connected. ' +
-      'Use it before advising anything about music requests for an event. Off-catalogue requests are the ones that create ' +
-      'work on the day, so whether they are allowed matters more than the limit itself. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/ops/music');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: flows - the automation that runs whether anybody is watching.
+ *
+ * Workstreams B2, B3 and B4. Sequences, workflows, enquiry capture, gambits,
+ * forms, questionnaires, SMS, spend and job costing all ran invisibly to the
+ * terminal.
+ *
+ * 🚨 The worst gap here was collision. A connector that cannot see a running
+ * sequence will happily propose writing to somebody it is already emailing, and two
+ * messages from one business on one day is how a good prospect is lost.
+ *
+ * 🚨 READ ONLY, except km_send_sms: one text the owner approved word for word, gated
+ * server-side by a confirm token. Enrolling, pausing and firing automation act on real
+ * people and stay in the web app.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'flows';
+
+export const TOOLS = [
+  'km_list_sequences',
+  'km_list_workflows',
+  'km_inquiry_sources',
+  'km_list_gambits',
+  'km_list_forms',
+  'km_list_questionnaires',
+  'km_list_sms',
+  'km_send_sms',
+  'km_list_expenses',
+  'km_list_job_costs',
+  'km_list_rentals',
+  'km_music_settings',
+];
+
+export const PROFILES = ['outreach', 'money'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose this surface to the terminal yet. That is not a fault: the workspace is fine and every ' +
+  'other tool works as normal. It is there in the web app at https://hub.kivimedia.co.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_list_sequences',
+    'Who is enrolled in an automated sequence, which step they are on, when the next message goes, and why anybody ' +
+      'stopped. ' +
+      '🚨 CALL THIS BEFORE DRAFTING TO ANYONE. `actively_enrolled` is the number that matters: those contacts are ' +
+      'already being messaged automatically. Writing to somebody a sequence is mid-way through means two messages from ' +
+      'one business on one day, which reads as chaotic and loses good prospects. It is the single most valuable check ' +
+      'in this family and it is invisible everywhere else. ' +
+      '`stop_reason` is worth reading too: the same reason recurring is a sequence problem, not bad luck. Read only.',
+    {
+      status: z.string().optional().describe('Narrow to one state, for example active, stopped or completed.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many enrolments, newest first. Default 50.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/flows/sequences${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_workflows',
+    'The automations configured on this workspace, what triggers each one, and whether it is switched on. ' +
+      'Use it before telling anybody that nothing will happen automatically, and when something occurred that nobody ' +
+      'remembers doing. An active workflow acts without a human present, so "I did not send that" and "nothing was ' +
+      'sent" are different claims and this tool separates them. ' +
+      'Step definitions are not returned: what matters is what fires and whether it is on. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/flows/workflows');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_inquiry_sources',
+    'Where enquiries actually came from, counted by source and by status. ' +
+      'Use it whenever the user asks where their work comes from, or before recommending they spend more effort ' +
+      'anywhere. 🚨 The answer is very often different from what the owner believes, and that gap is one of the more ' +
+      'valuable things you can show them. Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many enquiries to count over, newest first. Default 50.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/flows/inquiries${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_gambits',
+    'The lead gambits configured on this workspace. Use it when the user mentions a gambit by name or asks what is set ' +
+      'up. Configuring one happens in KM Hub. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/flows/gambits');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_forms',
+    'The booking and lead forms on this workspace and which are actually live. ' +
+      'A live form is a public front door, so `live_count` of zero is worth saying out loud: it means there is no route ' +
+      'for somebody to enquire through, however good the marketing is. Use it before advising anything about capturing ' +
+      'leads. Field configuration is not returned; editing happens in KM Hub. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/flows/forms');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_questionnaires',
+    'Questionnaires sent to clients, and whether they were viewed and answered. ' +
+      '🚨 `sent_but_unanswered` is the number to lead with. Each one is event detail nobody has, and missing detail ' +
+      'does not stay quiet: it surfaces on the day rather than politely in advance. Answers themselves live in KM Hub. ' +
+      'Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many, newest first. Default 50.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/flows/questionnaires${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_sms',
+    'Text messages in and out of the business line, grouped into threads, with who each is with, direction and the ' +
+      'words. Texts the owner typed in the Quo app on their phone are included, so a thread is the whole exchange. ' +
+      'Use it when the user asks what came in by text, what a client texted, or whether somebody was actually reached. ' +
+      'Without arguments you get the latest texts plus `threads`, where `awaiting_your_reply: true` means the customer ' +
+      'had the last word. To read one conversation in order, pass `thread_of` with any message id from it, or ' +
+      '`client_id`. ' +
+      '🚨 An inbound text nobody answered is the fastest-decaying message a business gets: people who text expect a ' +
+      'text back, and an hour is already late. Phone numbers are deliberately not returned. To answer, use km_send_sms.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many messages. Default 50.'),
+      thread_of: z.string().optional().describe('Any message id in a conversation: returns that whole thread, oldest first.'),
+      client_id: z.string().optional().describe('A client id: returns the texts linked to that client, oldest first.'),
+    },
+    async ({ limit, thread_of, client_id }) => {
+      const r = await call('GET', `/flows/sms${qs({ limit, thread_of, client_id })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_send_sms',
+    'Send ONE text message to a customer from the business line. It is a real text on their phone and cannot be ' +
+      'unsent, and it is logged on the client\'s timeline and in km_list_sms automatically. ' +
+      'Pick the recipient ONE way: `reply_to_message_id` (a message id from km_list_sms - answers that thread without ' +
+      'the number ever passing through this chat), `client_id`, or `to` (a phone number the user gave you). ' +
+      '🚨 Write the text, show the user the exact words, and send only the words they approved. The first call returns ' +
+      'a confirmation carrying a sentence written by the server about what will happen, plus a token. Read that ' +
+      'sentence to the user as it is, get a yes to THIS text, then call again with the same arguments and ' +
+      'confirm_token. Any change to the words needs a new confirmation. Keep it short and human: a text, not an email.',
+    {
+      text: z.string().describe('The exact words to send, as the user approved them.'),
+      reply_to_message_id: z.string().optional().describe('Answer this thread: a message id from km_list_sms.'),
+      client_id: z.string().optional().describe('Text this client at the phone number on their record.'),
+      to: z.string().optional().describe('A phone number the user gave you, when there is no thread or client.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe('Only on the second call, after the user read the confirmation sentence and said yes. Never invent one.'),
+    },
+    async ({ text: words, reply_to_message_id, client_id, to, confirm_token }) => {
+      const body = { text: words };
+      if (reply_to_message_id) body.reply_to_message_id = String(reply_to_message_id);
+      if (client_id) body.client_id = String(client_id);
+      if (to) body.to = String(to);
+      if (confirm_token) body.confirm_token = String(confirm_token);
+      const r = await call('POST', '/flows/sms/send', body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_expenses',
+    'What has been spent in a window, split into what is billable to a client and what the business absorbs, with ' +
+      'totals by category. Defaults to the last 90 days. ' +
+      '🚨 `absorbed` is the number that decides whether a busy month was a profitable one, and it is the one nobody ' +
+      'looks at. The money tools answer what came IN; without this you can describe a healthy-looking month with no idea ' +
+      'whether any of it was kept. All amounts are in CENTS. Read only.',
+    {
+      from: z.string().optional().describe('Start date, YYYY-MM-DD. Default 90 days ago.'),
+      to: z.string().optional().describe('End date, YYYY-MM-DD. Default tomorrow.'),
+      limit: z.number().int().min(1).max(500).optional().describe('How many entries. Default 100. Check `truncated` before trusting a total.'),
+    },
+    async ({ from, to, limit }) => {
+      const r = await call('GET', `/ops/expenses${qs({ from, to, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_job_costs',
+    'Jobs that have been costed, with the overhead and target profit assumptions behind each. ' +
+      '🚨 Those percentages are ASSUMPTIONS the owner set when costing the job, NOT margin achieved. Describing an ' +
+      'intended margin as a delivered one is the most misleading thing you could do with this data, so say "targeted" ' +
+      'rather than "made". Line-item detail lives in KM Hub. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many costed jobs, newest first. Default 25.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/ops/job-costing${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_rentals',
+    'Stock holds and the rental lines sitting on proposals: what is held, for whom, between which dates, and what is ' +
+      'reserved. ' +
+      '🚨 A HOLD is stock promised to somebody who has NOT committed. An expiring hold that nobody chases ' +
+      'silently releases kit a buyer still believes is theirs, which is worse than never holding it, so ' +
+      '`holds_with_an_expiry` is worth raising. Amounts are in CENTS. Releasing or extending a hold happens in KM Hub. ' +
+      'Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many holds and rental lines. Default 50.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/ops/rentals${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_music_settings',
+    'What clients may request on the public music page: the per-event request limit, whether off-catalogue requests are ' +
+      'allowed, whether remaining requests are shown, and whether Spotify is connected. ' +
+      'Use it before advising anything about music requests for an event. Off-catalogue requests are the ones that create ' +
+      'work on the day, so whether they are allowed matters more than the limit itself. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/ops/music');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}