@kivimedia/kmhub 2.9.1 → 2.10.0

package/tools/balloon-costing.mjs

@@ -1,80 +1,80 @@
-/**
- * Tool family: balloon-costing - what a balloon build actually costs, and the way
- * back to the window that holds it.
- *
- * Freshdesk #271. Jackie went looking for the price of her balloon COLUMNS to check
- * her margin, closed the window by accident, and could not find her way back: "I
- * always have this problem of not getting back to the correct window using Claude and
- * KM Hub once it is closed."
- *
- * Two things were wrong, and this family fixes the first while the shared `out()`
- * helper fixes the second.
- *
- *   1. km_list_job_costs reads `cost_jobs`, the GENERAL costing table. The balloon
- *      calculator writes balloon_jobs and balloon_inventory (mig 393), which no route
- *      had ever read. So the one tool that sounded like the answer was reading a
- *      different set of books.
- *   2. Every row this returns carries `open_url`, and the body carries
- *      `open_in_km_hub`, which `out()` appends as a plain "Open in KM Hub" line.
- *
- * 🚨 READ ONLY. Costing a job, importing a price list and editing a line item act on
- * the owner's own pricing and stay in the web app.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'balloon-costing';
-
-export const TOOLS = ['km_list_balloon_costs'];
-
-export const PROFILES = ['money'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'Your KM Hub does not expose balloon job costing to the terminal yet. That is not a fault: the workspace is fine and ' +
-  'every other tool works as normal. The calculator is there in the web app at ' +
-  'https://hub.kivimedia.co/?page=job-cost.';
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_list_balloon_costs',
-    'What a balloon build costs and what it was quoted at: the priced balloon catalog (pack price, pack count and the ' +
-      'per-each price derived from them) and the costed balloon jobs with their material, labor and expense lines, the ' +
-      'overhead and profit percentages behind each, and the margin those percentages imply. ' +
-      'Reach for this for any question about balloon pricing or balloon margin, for example "what do my columns cost ' +
-      'me" or "what margin did I build into the Saturday job". ' +
-      '🚨 This is a DIFFERENT set of books from km_list_job_costs, which reads the general costing table and knows ' +
-      'nothing about balloons. Use this one for a balloon question. ' +
-      '🚨 indirect_expense_percentage and profit_percentage are ASSUMPTIONS the owner typed when costing the job, not ' +
-      'margin achieved, so `targeted_margin_percentage` is targeted and never "made". `actual_margin_percentage` is ' +
-      'null until somebody has filled in the actual columns. ' +
-      'Every row carries `open_url` and the answer carries a link back to the page it came from: show it, because ' +
-      'losing the window is the reason this tool exists. Read only: pricing is edited in the web app.',
-    {
-      search: z
-        .string()
-        .optional()
-        .describe(
-          'Narrow to one thing by name, for example "column", "garland" or a client name. Matches catalog item names, ' +
-            'part numbers and descriptions, and matches jobs on client name, job number, description and the names of ' +
-            'the material lines inside them.',
-        ),
-      limit: z
-        .number()
-        .int()
-        .min(1)
-        .max(100)
-        .optional()
-        .describe('How many catalog items and how many jobs, newest job first. Default 25.'),
-    },
-    async ({ search, limit }) => {
-      const r = await call('GET', `/balloon-costing${qs({ search, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: balloon-costing - what a balloon build actually costs, and the way
+ * back to the window that holds it.
+ *
+ * Freshdesk #271. Jackie went looking for the price of her balloon COLUMNS to check
+ * her margin, closed the window by accident, and could not find her way back: "I
+ * always have this problem of not getting back to the correct window using Claude and
+ * KM Hub once it is closed."
+ *
+ * Two things were wrong, and this family fixes the first while the shared `out()`
+ * helper fixes the second.
+ *
+ *   1. km_list_job_costs reads `cost_jobs`, the GENERAL costing table. The balloon
+ *      calculator writes balloon_jobs and balloon_inventory (mig 393), which no route
+ *      had ever read. So the one tool that sounded like the answer was reading a
+ *      different set of books.
+ *   2. Every row this returns carries `open_url`, and the body carries
+ *      `open_in_km_hub`, which `out()` appends as a plain "Open in KM Hub" line.
+ *
+ * 🚨 READ ONLY. Costing a job, importing a price list and editing a line item act on
+ * the owner's own pricing and stay in the web app.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'balloon-costing';
+
+export const TOOLS = ['km_list_balloon_costs'];
+
+export const PROFILES = ['money'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose balloon job costing to the terminal yet. That is not a fault: the workspace is fine and ' +
+  'every other tool works as normal. The calculator is there in the web app at ' +
+  'https://hub.kivimedia.co/?page=job-cost.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_list_balloon_costs',
+    'What a balloon build costs and what it was quoted at: the priced balloon catalog (pack price, pack count and the ' +
+      'per-each price derived from them) and the costed balloon jobs with their material, labor and expense lines, the ' +
+      'overhead and profit percentages behind each, and the margin those percentages imply. ' +
+      'Reach for this for any question about balloon pricing or balloon margin, for example "what do my columns cost ' +
+      'me" or "what margin did I build into the Saturday job". ' +
+      '🚨 This is a DIFFERENT set of books from km_list_job_costs, which reads the general costing table and knows ' +
+      'nothing about balloons. Use this one for a balloon question. ' +
+      '🚨 indirect_expense_percentage and profit_percentage are ASSUMPTIONS the owner typed when costing the job, not ' +
+      'margin achieved, so `targeted_margin_percentage` is targeted and never "made". `actual_margin_percentage` is ' +
+      'null until somebody has filled in the actual columns. ' +
+      'Every row carries `open_url` and the answer carries a link back to the page it came from: show it, because ' +
+      'losing the window is the reason this tool exists. Read only: pricing is edited in the web app.',
+    {
+      search: z
+        .string()
+        .optional()
+        .describe(
+          'Narrow to one thing by name, for example "column", "garland" or a client name. Matches catalog item names, ' +
+            'part numbers and descriptions, and matches jobs on client name, job number, description and the names of ' +
+            'the material lines inside them.',
+        ),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe('How many catalog items and how many jobs, newest job first. Default 25.'),
+    },
+    async ({ search, limit }) => {
+      const r = await call('GET', `/balloon-costing${qs({ search, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/booking-equipment.mjs

@@ -1,110 +1,110 @@
-/**
- * Tool family: booking-equipment - what gear is going out on a job.
- *
- * WHY THIS EXISTS
- * This is the row that makes an equipment SOP reach a human being. A procedure
- * attached to the Roland V160 is a document nobody opens until something says
- * the V160 is on Tuesday's job; then it arrives in the brief on its own.
- *
- * Before migration 677 the only way to say that ran through a performer's shift,
- * which is the right model for a DJ and the wrong one for production AV, where
- * the pull sheet exists before anybody is rostered and a projector belongs to a
- * ballroom rather than to a person.
- *
- * SAFETY. Nothing here contacts anybody or moves money. It does decide what a
- * crew member is told to bring, which is why every line records where it came
- * from: a demonstration row can never be mistaken for a real pull sheet.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'booking-equipment';
-
-export const TOOLS = ['km_list_equipment', 'km_booking_gear', 'km_add_booking_gear', 'km_remove_booking_gear'];
-
-// Lands in `full` only. An EMPTY list means exactly that - ['*'] would opt into
-// every profile, which is the mistake tools.mjs documents six families making.
-export const PROFILES = [];
-
-export function register(server, call, { out }) {
-  server.tool(
-    'km_list_equipment',
-    'The gear this workspace owns: name, category, how many, condition and day rate. ' +
-      'REACH FOR THIS FIRST whenever gear is involved, because every other tool here needs an item id and this is the only ' +
-      'way to find one. Search by name to find the item an SOP is about, or filter by category to see what the business ' +
-      'actually has. ' +
-      'An empty catalogue is worth saying out loud: it means no equipment procedure can ever surface on a job, however ' +
-      'many are written, because nothing can say which job the gear is on. Read only.',
-    {
-      q: z.string().optional().describe('Free text against the item name, e.g. Roland or projector.'),
-      category: z.string().optional().describe('Only this category, e.g. Video, Audio, Lighting, Staging.'),
-      limit: z.number().int().positive().max(500).optional().describe('Page size, default 200.'),
-      offset: z.number().int().min(0).optional().describe('Skip this many. Use it when a page comes back full.'),
-    },
-    async (args) => {
-      const p = new URLSearchParams();
-      for (const [k, v] of Object.entries(args)) if (v !== undefined && v !== '') p.set(k, String(v));
-      const qs = p.toString();
-      return out(await call('GET', `/equipment${qs ? `?${qs}` : ''}`));
-    },
-  );
-
-  server.tool(
-    'km_booking_gear',
-    'The gear going out on a job, room by room, with each item named and counted. ' +
-      'Reach for it when preparing a job, when somebody asks what is on the truck, or before briefing crew - and reach ' +
-      'for it whenever km_sop_brief comes back with no equipment procedures, because an empty gear list is almost always ' +
-      'the reason. A booking with nothing recorded here cannot surface a single equipment SOP, however many are written. ' +
-      'Lines marked source "seed" are demonstrations rather than a real pull sheet; say so rather than reading them out ' +
-      'as fact. Read only.',
-    { booking_id: z.string().describe('The booking id from km_list_bookings or km_get_booking.') },
-    async ({ booking_id }) => out(await call('GET', `/bookings/${encodeURIComponent(booking_id)}/equipment`)),
-  );
-
-  server.tool(
-    'km_add_booking_gear',
-    'Put gear on a job, as a list. This is what makes equipment procedures surface: attach an SOP to a projector with ' +
-      'km_attach_sop, record that the projector is on this job here, and it appears in that job\'s brief from then on. ' +
-      'Reach for it when a pull sheet is being built, when somebody says what is going out, or when a proposal has been ' +
-      'won and the gear on it is now real. ' +
-      'Send the whole list in one call rather than one item at a time - a half-built pull sheet is worse than none. ' +
-      'Put the room on every line where the job has rooms: "the V160, Valencia Ballroom" tells somebody where to walk, ' +
-      'and the same item in two rooms is two lines because two people set it up. ' +
-      'Re-sending the same list updates quantities instead of duplicating, so it is safe to run again. ' +
-      'Set source honestly: "seed" for anything you are adding to demonstrate the system, never for gear you were told ' +
-      'is actually going out.',
-    {
-      booking_id: z.string(),
-      items: z.array(z.object({
-        equipment_item_id: z.string().describe('The gear id. Look it up first; an id that points at nothing is refused rather than stored.'),
-        quantity: z.number().int().positive().optional().describe('How many. Defaults to 1.'),
-        room: z.string().optional().describe('Which room this one is for, named the way the client says it, e.g. "Valencia Ballroom".'),
-        notes: z.string().optional().describe('Anything the crew needs about this line specifically.'),
-      })).describe('The whole pull sheet, or the part of it being added.'),
-      source: z.enum(['manual', 'proposal', 'djep', 'import', 'seed']).optional()
-        .describe('Where this came from. "proposal" or "djep" when it was copied from one, with the number in source_ref. "seed" for a demonstration.'),
-      source_ref: z.string().optional().describe('The proposal number or DJEP job this was taken from, so the line can be traced back.'),
-    },
-    async ({ booking_id, ...body }) =>
-      out(await call('POST', `/bookings/${encodeURIComponent(booking_id)}/equipment`, body)),
-  );
-
-  server.tool(
-    'km_remove_booking_gear',
-    'Take one piece of gear off a job. The equipment itself and any SOPs attached to it are untouched; this only says it ' +
-      'is no longer going out on this booking. ' +
-      'If the job has rooms, name the room - a line with no room is a different line from the one in the Valencia ' +
-      'Ballroom, and leaving it out removes every room\'s copy.',
-    {
-      booking_id: z.string(),
-      equipment_item_id: z.string(),
-      room: z.string().optional().describe('The room to remove it from. Leave it out to remove every copy across all rooms.'),
-    },
-    async ({ booking_id, equipment_item_id, room }) => {
-      const p = new URLSearchParams({ equipment_item_id });
-      if (room !== undefined) p.set('room', room);
-      return out(await call('DELETE', `/bookings/${encodeURIComponent(booking_id)}/equipment?${p.toString()}`));
-    },
-  );
-}
+/**
+ * Tool family: booking-equipment - what gear is going out on a job.
+ *
+ * WHY THIS EXISTS
+ * This is the row that makes an equipment SOP reach a human being. A procedure
+ * attached to the Roland V160 is a document nobody opens until something says
+ * the V160 is on Tuesday's job; then it arrives in the brief on its own.
+ *
+ * Before migration 677 the only way to say that ran through a performer's shift,
+ * which is the right model for a DJ and the wrong one for production AV, where
+ * the pull sheet exists before anybody is rostered and a projector belongs to a
+ * ballroom rather than to a person.
+ *
+ * SAFETY. Nothing here contacts anybody or moves money. It does decide what a
+ * crew member is told to bring, which is why every line records where it came
+ * from: a demonstration row can never be mistaken for a real pull sheet.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'booking-equipment';
+
+export const TOOLS = ['km_list_equipment', 'km_booking_gear', 'km_add_booking_gear', 'km_remove_booking_gear'];
+
+// Lands in `full` only. An EMPTY list means exactly that - ['*'] would opt into
+// every profile, which is the mistake tools.mjs documents six families making.
+export const PROFILES = [];
+
+export function register(server, call, { out }) {
+  server.tool(
+    'km_list_equipment',
+    'The gear this workspace owns: name, category, how many, condition and day rate. ' +
+      'REACH FOR THIS FIRST whenever gear is involved, because every other tool here needs an item id and this is the only ' +
+      'way to find one. Search by name to find the item an SOP is about, or filter by category to see what the business ' +
+      'actually has. ' +
+      'An empty catalogue is worth saying out loud: it means no equipment procedure can ever surface on a job, however ' +
+      'many are written, because nothing can say which job the gear is on. Read only.',
+    {
+      q: z.string().optional().describe('Free text against the item name, e.g. Roland or projector.'),
+      category: z.string().optional().describe('Only this category, e.g. Video, Audio, Lighting, Staging.'),
+      limit: z.number().int().positive().max(500).optional().describe('Page size, default 200.'),
+      offset: z.number().int().min(0).optional().describe('Skip this many. Use it when a page comes back full.'),
+    },
+    async (args) => {
+      const p = new URLSearchParams();
+      for (const [k, v] of Object.entries(args)) if (v !== undefined && v !== '') p.set(k, String(v));
+      const qs = p.toString();
+      return out(await call('GET', `/equipment${qs ? `?${qs}` : ''}`));
+    },
+  );
+
+  server.tool(
+    'km_booking_gear',
+    'The gear going out on a job, room by room, with each item named and counted. ' +
+      'Reach for it when preparing a job, when somebody asks what is on the truck, or before briefing crew - and reach ' +
+      'for it whenever km_sop_brief comes back with no equipment procedures, because an empty gear list is almost always ' +
+      'the reason. A booking with nothing recorded here cannot surface a single equipment SOP, however many are written. ' +
+      'Lines marked source "seed" are demonstrations rather than a real pull sheet; say so rather than reading them out ' +
+      'as fact. Read only.',
+    { booking_id: z.string().describe('The booking id from km_list_bookings or km_get_booking.') },
+    async ({ booking_id }) => out(await call('GET', `/bookings/${encodeURIComponent(booking_id)}/equipment`)),
+  );
+
+  server.tool(
+    'km_add_booking_gear',
+    'Put gear on a job, as a list. This is what makes equipment procedures surface: attach an SOP to a projector with ' +
+      'km_attach_sop, record that the projector is on this job here, and it appears in that job\'s brief from then on. ' +
+      'Reach for it when a pull sheet is being built, when somebody says what is going out, or when a proposal has been ' +
+      'won and the gear on it is now real. ' +
+      'Send the whole list in one call rather than one item at a time - a half-built pull sheet is worse than none. ' +
+      'Put the room on every line where the job has rooms: "the V160, Valencia Ballroom" tells somebody where to walk, ' +
+      'and the same item in two rooms is two lines because two people set it up. ' +
+      'Re-sending the same list updates quantities instead of duplicating, so it is safe to run again. ' +
+      'Set source honestly: "seed" for anything you are adding to demonstrate the system, never for gear you were told ' +
+      'is actually going out.',
+    {
+      booking_id: z.string(),
+      items: z.array(z.object({
+        equipment_item_id: z.string().describe('The gear id. Look it up first; an id that points at nothing is refused rather than stored.'),
+        quantity: z.number().int().positive().optional().describe('How many. Defaults to 1.'),
+        room: z.string().optional().describe('Which room this one is for, named the way the client says it, e.g. "Valencia Ballroom".'),
+        notes: z.string().optional().describe('Anything the crew needs about this line specifically.'),
+      })).describe('The whole pull sheet, or the part of it being added.'),
+      source: z.enum(['manual', 'proposal', 'djep', 'import', 'seed']).optional()
+        .describe('Where this came from. "proposal" or "djep" when it was copied from one, with the number in source_ref. "seed" for a demonstration.'),
+      source_ref: z.string().optional().describe('The proposal number or DJEP job this was taken from, so the line can be traced back.'),
+    },
+    async ({ booking_id, ...body }) =>
+      out(await call('POST', `/bookings/${encodeURIComponent(booking_id)}/equipment`, body)),
+  );
+
+  server.tool(
+    'km_remove_booking_gear',
+    'Take one piece of gear off a job. The equipment itself and any SOPs attached to it are untouched; this only says it ' +
+      'is no longer going out on this booking. ' +
+      'If the job has rooms, name the room - a line with no room is a different line from the one in the Valencia ' +
+      'Ballroom, and leaving it out removes every room\'s copy.',
+    {
+      booking_id: z.string(),
+      equipment_item_id: z.string(),
+      room: z.string().optional().describe('The room to remove it from. Leave it out to remove every copy across all rooms.'),
+    },
+    async ({ booking_id, equipment_item_id, room }) => {
+      const p = new URLSearchParams({ equipment_item_id });
+      if (room !== undefined) p.set('room', room);
+      return out(await call('DELETE', `/bookings/${encodeURIComponent(booking_id)}/equipment?${p.toString()}`));
+    },
+  );
+}

package/tools/bridges.mjs

@@ -1,54 +1,54 @@
-/**
- * Tool family: bridges - which CRM this workspace sends its lead replies through, and
- * whether that connection is alive right now.
- *
- * Some businesses run their inquiries out of a CRM with no usable API (Dubsado, SMPL).
- * Kivi Media keeps a live session to it on a server, and KM Hub sends replies to those
- * leads THROUGH the CRM, so the answer lands in the client's own record, from the
- * business's own address, instead of arriving as a stray email from somewhere else.
- *
- * This family answers "is that connected and working". Reading and answering the leads
- * themselves is the `dubsado` family. Same table behind both, and behind the card in
- * Settings > Email Senders, so the terminal and the app never disagree.
- *
- * READ ONLY, on purpose. A `km_bridge_set_sending` shipped on 02-Sep and was removed the
- * next morning: turning the routing off is a Kivi Media action now, and a KM Hub API key
- * is welded to one workspace and carries no user, so nothing in a call from here can tell
- * Kivi apart from the client. If somebody asks to switch it off, say that Kivi Media does
- * it and usually the same day - do not go looking for another route.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-export const FAMILY = 'bridges';
-
-export const TOOLS = ['km_bridges'];
-
-export const PROFILES = ['*'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'This KM Hub server does not report CRM connections yet. Nothing is wrong: it just means the ' +
-  'workspace sends email the ordinary way.';
-
-export function register(server, call, { out, text }) {
-  server.tool(
-    'km_bridges',
-    'Whether this workspace sends its lead replies through a CRM (Dubsado, SMPL) rather than by ' +
-      'ordinary email, and whether that connection is alive RIGHT NOW. Call it before promising that ' +
-      'a reply will reach a lead, whenever somebody says a client never heard back, and any time you ' +
-      'are about to explain where their email comes from. A bridge shown as down is not something ' +
-      'the person can fix: say plainly that new inquiries are not arriving and replies to them cannot ' +
-      'send until the Kivi Media team revives it, and do not attempt a send that depends on it. Most ' +
-      'workspaces have no bridge at all, which is normal and worth saying just as plainly.',
-    {},
-    async () => {
-      const r = await call('GET', '/bridges');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-}
+/**
+ * Tool family: bridges - which CRM this workspace sends its lead replies through, and
+ * whether that connection is alive right now.
+ *
+ * Some businesses run their inquiries out of a CRM with no usable API (Dubsado, SMPL).
+ * Kivi Media keeps a live session to it on a server, and KM Hub sends replies to those
+ * leads THROUGH the CRM, so the answer lands in the client's own record, from the
+ * business's own address, instead of arriving as a stray email from somewhere else.
+ *
+ * This family answers "is that connected and working". Reading and answering the leads
+ * themselves is the `dubsado` family. Same table behind both, and behind the card in
+ * Settings > Email Senders, so the terminal and the app never disagree.
+ *
+ * READ ONLY, on purpose. A `km_bridge_set_sending` shipped on 02-Sep and was removed the
+ * next morning: turning the routing off is a Kivi Media action now, and a KM Hub API key
+ * is welded to one workspace and carries no user, so nothing in a call from here can tell
+ * Kivi apart from the client. If somebody asks to switch it off, say that Kivi Media does
+ * it and usually the same day - do not go looking for another route.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+export const FAMILY = 'bridges';
+
+export const TOOLS = ['km_bridges'];
+
+export const PROFILES = ['*'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub server does not report CRM connections yet. Nothing is wrong: it just means the ' +
+  'workspace sends email the ordinary way.';
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_bridges',
+    'Whether this workspace sends its lead replies through a CRM (Dubsado, SMPL) rather than by ' +
+      'ordinary email, and whether that connection is alive RIGHT NOW. Call it before promising that ' +
+      'a reply will reach a lead, whenever somebody says a client never heard back, and any time you ' +
+      'are about to explain where their email comes from. A bridge shown as down is not something ' +
+      'the person can fix: say plainly that new inquiries are not arriving and replies to them cannot ' +
+      'send until the Kivi Media team revives it, and do not attempt a send that depends on it. Most ' +
+      'workspaces have no bridge at all, which is normal and worth saying just as plainly.',
+    {},
+    async () => {
+      const r = await call('GET', '/bridges');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+}