@kivimedia/kmhub 2.0.0 → 2.9.0

package/tools/balloon-costing.mjs

@@ -0,0 +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);
+    },
+  );
+}

package/tools/booking-equipment.mjs

@@ -0,0 +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()}`));
+    },
+  );
+}

package/tools/bridges.mjs

@@ -0,0 +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);
+    },
+  );
+
+}

package/tools/calendar.mjs

@@ -139,6 +139,15 @@ export function register(server, call, { out, qs }) {
         .enum(['pending', 'confirmed', 'in_progress'])
         .optional()
         .describe('confirmed marks the date taken everywhere; pending releases it; in_progress means the gig is under way. Cancelled and completed are not available here.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
     async ({ booking_id, ...changes }) =>
       out(await call('PATCH', `/bookings/${encodeURIComponent(String(booking_id || '').trim())}`, changes)),

package/tools/capabilities.mjs

@@ -0,0 +1,155 @@
+/**
+ * Tool family: capabilities - what KM Hub can do, and honestly where.
+ *
+ * km_capabilities answers "what is KM Hub" from ./capabilities.json, which is
+ * GENERATED from the web app's own nav registry (scripts/generate-capabilities.mjs).
+ * That generation is the whole point: a hand-written feature list is wrong within a
+ * month, and a connector that confidently describes a product that has moved is
+ * worse than one that says nothing.
+ *
+ * WHY THIS READS A LOCAL FILE AND NOT THE API. The answer is the same for every
+ * workspace on a given build, it is needed at the START of a session when the model
+ * is deciding what is even possible, and it must work when the API is slow. A round
+ * trip would buy nothing. Per-workspace filtering (which pillars this org has switched
+ * on) is a later addition and belongs on the API when it comes.
+ *
+ * 🚨 THE `reach` FIELD IS THE HONEST PART. Every page reports `terminal`,
+ * `terminal_read` or `web_only`. Claude MUST NOT promise to do a web_only thing
+ * from the terminal, and MUST NOT promise to EDIT a terminal_read page: those can
+ * be looked at from here and changed only in the web app. Say KM Hub does it, name
+ * the page, and point at the web app. Telling a client "yes I can" and then
+ * failing is worse than "KM Hub does that, here is where". The read distinction
+ * exists because Mark Fuller's 01-Sep-26 gap report caught two read-only pages
+ * reporting plain `terminal`, which reads as "you can work on this from here".
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+
+export const FAMILY = 'capabilities';
+
+export const TOOLS = ['km_capabilities'];
+
+// Knowing what the product is costs one small file and changes every other answer,
+// so it loads in every profile.
+export const PROFILES = ['*'];
+
+let CACHE = null;
+
+function load() {
+  if (CACHE) return CACHE;
+  try {
+    CACHE = JSON.parse(readFileSync(new URL('../capabilities.json', import.meta.url), 'utf8'));
+  } catch (e) {
+    CACHE = { error: String(e?.message || e) };
+  }
+  return CACHE;
+}
+
+/** Trim a page down to what a model needs to decide, dropping the empty fields. */
+function slim(p, withTools) {
+  const o = { id: p.id, label: p.label, reach: p.reach };
+  // A page can be web-only because nobody built it yet, or because it should never
+  // be driven from a terminal at all. Saying which is the difference between "not
+  // yet" and "not ever", and a model that blurs them will keep offering to try.
+  if (p.web_only_by_design) o.web_only_by_design = true;
+  if (p.benefit) o.what_it_does = p.benefit;
+  if (withTools && p.tools?.length) o.tools = p.tools;
+  if (withTools && p.plays?.length) o.plays = p.plays;
+  return o;
+}
+
+export function register(server, call, { text }) {
+  server.tool(
+    'km_capabilities',
+    'The map of everything KM Hub does, and honestly which parts you can do from here. ' +
+      'CALL THIS EARLY in any session where the user is deciding what to work on, asks what KM Hub can do, ' +
+      'asks whether it can handle some area of their business, wonders if it does something a different tool does, ' +
+      'or asks a question you are about to answer with "I do not think KM Hub does that". You very likely have not ' +
+      'seen the whole product: it is 7 pillars and over 100 feature pages, far more than the tools in front of you, ' +
+      'so an answer based only on your tool list will understate it badly. ' +
+      'What comes back is the same nav the web app renders - Marketing, Sales, Operations, HR, Clients, AI Team, ' +
+      'Settings - each with its groups, its pages, and one plain sentence per page about what that page is FOR. ' +
+      '🚨 Every page carries `reach`. `terminal` means tools or plays here can do it. `terminal_read` means you can ' +
+      'look from here but every change happens in the web app, so say where the editing lives up front. `web_only` ' +
+      'means KM Hub does it but this connector cannot reach it at all. NEVER offer to do a web_only thing or to ' +
+      'edit a terminal_read one. Say KM Hub does it, name the page, and ' +
+      'point them at https://hub.kivimedia.co. Claiming a capability you do not have and then failing costs more ' +
+      'trust than saying where it lives. ' +
+      'Use it to answer the whole question rather than the part you happen to hold: someone asking about follow-up ' +
+      'should hear that KM Hub also runs their newsletter, their SEO and their reviews. It reads a file, costs ' +
+      'nothing, sends nothing and changes nothing.',
+    {
+      pillar: z
+        .enum(['marketing', 'sales', 'operations', 'hr', 'support', 'strategy', 'setup'])
+        .optional()
+        .describe(
+          'Narrow to one pillar when the user asked about one area. marketing = being found and reaching out, ' +
+            'sales = pipeline through to close, operations = diary, money and delivery, hr = team, pay and time, ' +
+            'support = clients, conversations and reputation, strategy = the AI officers, decisions and reporting, ' +
+            'setup = account, billing and connections. Leave it out for the whole product.',
+        ),
+      reach: z
+        .enum(['terminal', 'terminal_read', 'web_only', 'all'])
+        .optional()
+        .describe(
+          "Default 'all'. Use 'terminal' when you want what you can reach from here; it includes 'terminal_read' " +
+            "pages, so check each page's own reach before offering to CHANGE anything on it. Use 'terminal_read' " +
+            "for only the look-but-not-touch pages, and 'web_only' to answer \"what else is in there\" honestly.",
+        ),
+      detail: z
+        .enum(['summary', 'full'])
+        .optional()
+        .describe(
+          "Default 'summary': pillars, groups, pages and what each is for. 'full' adds the exact tool and play " +
+            'names behind each page, which you want when planning a piece of work rather than describing the product.',
+        ),
+    },
+    async ({ pillar, reach = 'all', detail = 'summary' }) => {
+      const doc = load();
+      if (doc.error) {
+        return text(
+          'The capability map did not load on this connector, so I cannot list what KM Hub does. ' +
+            'The workspace itself is fine and every other tool works as normal. Detail: ' + doc.error,
+          true,
+        );
+      }
+
+      const withTools = detail === 'full';
+      const pillars = [];
+      for (const p of doc.pillars) {
+        if (pillar && p.id !== pillar) continue;
+        const groups = [];
+        for (const g of p.groups) {
+          const pages = g.pages
+            // 'terminal' includes 'terminal_read': both are reachable, and a
+            // caller narrowing to what it can reach must not lose the read side.
+            .filter((x) => reach === 'all' || x.reach === reach || (reach === 'terminal' && x.reach === 'terminal_read'))
+            .map((x) => slim(x, withTools));
+          if (pages.length) groups.push({ group: g.header, pages });
+        }
+        if (groups.length) pillars.push({ id: p.id, label: p.label, tagline: p.tagline, groups });
+      }
+
+      const shown = pillars.reduce((n, p) => n + p.groups.reduce((m, g) => m + g.pages.length, 0), 0);
+
+      const body = {
+        product: 'KM Hub',
+        web_app: 'https://hub.kivimedia.co',
+        totals: doc.counts,
+        showing: { pillar: pillar || 'all', reach, pages: shown },
+        how_to_read:
+          "reach 'terminal' means you can do it from here. reach 'terminal_read' means you can LOOK at it from " +
+          'here but every change happens in the web app: say where the editing lives up front, never offer the ' +
+          "edit and fail at it. reach 'web_only' means KM Hub does it but this connector cannot yet, so name the " +
+          'page and point at the web app rather than offering to do it. ' +
+          "A page also carrying web_only_by_design will NEVER be reachable from a terminal: it is a deliberate " +
+          'boundary, not a backlog item, so do not imply it is coming.',
+        pillars,
+      };
+
+      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
+    },
+  );
+}