@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/recurring-invoices.mjs

@@ -1,149 +1,149 @@
-/**
- * Tool family: recurring-invoices - subscription billing from the terminal.
- *
- * WHY THIS FAMILY EXISTS. On 22-Sep-2026 Jackie (Dazzling Balloons) set out to
- * launch a monthly decor subscription - billed monthly in advance on the 1st,
- * three tiers, a three-month minimum. Her terminal could read every invoice she
- * had ever raised and could not set up a single repeating one: the
- * recurring_invoices table was writable only from the "Make recurring" panel on
- * an existing invoice in the web app. A recurring plan is one bill with a
- * schedule inside it, and the schedule was mouse-only.
- *
- * 🚨 auto_send DEFAULTS FALSE, on purpose. Off, each month's invoice is created
- * as a DRAFT and nobody is emailed - the owner looks at it and sends it. On, the
- * cron marks it sent and emails the client the pay link unattended, every month,
- * forever. That second one is a standing instruction to charge somebody, so a
- * terminal never picks it by omission: the person has to ask, and the
- * confirmation sentence says in plain words which one they are getting.
- *
- * Every write here moves money, so every write is confirm-gated.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'recurring-invoices';
-
-export const TOOLS = [
-  'km_list_recurring_invoices', 'km_create_recurring_invoice', 'km_update_recurring_invoice',
-];
-
-// 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 = [];
-
-/** Route-level 404 (carries a routes list) vs a handler's not_found. See forms.mjs. */
-function routeMissing(r) {
-  if (r.status === 405 || r.status === 501) return true;
-  return r.status === 404 && Array.isArray(r.data?.routes);
-}
-
-const NOT_SUPPORTED =
-  'This KM Hub is running a version that cannot set up repeating invoices from the terminal yet. The workspace is ' +
-  'fine and every other tool works as normal. Recurring invoices are set up in the web app at ' +
-  'https://hub.kivimedia.co: open an invoice, then "Make recurring".';
-
-const CONFIRM_DESC =
-  'Leave this out on the first call. This action commits to billing somebody money on a schedule, so it needs an '
-  + 'explicit yes from the person you are working with: KM Hub answers 409 with a plain sentence saying who gets '
-  + 'billed how much and how often, plus a token. Show them that sentence in those words, wait for a real answer, '
-  + 'and only then call again with the token and the SAME arguments. A yes for one plan never authorises a different '
-  + 'one.';
-
-const LINE_ITEM = z.object({
-  description: z.string().min(1).max(500).describe('What the line says on the invoice, e.g. "Dazzling Decor Club - Gold tier, monthly".'),
-  unit_price_cents: z.number().int().min(0).describe('Price per unit in CENTS. 45000 is $450.00.'),
-  quantity: z.number().gt(0).max(9999).optional().describe('How many. Leave it out for 1; decimals like 1.5 are fine.'),
-});
-
-export function register(server, call, { out, text }) {
-  server.tool(
-    'km_list_recurring_invoices',
-    'The repeating invoices this workspace bills: what each one charges, to whom, when it next runs, whether it ' +
-      'is paused, and whether it emails itself or waits as a draft for approval. Each row carries the computed ' +
-      'monthly total in real money, plus a plain_english line, and the response totals up the active monthly ' +
-      'recurring revenue. ' +
-      'THE MODEL, so you never have to guess: a recurring invoice is a TEMPLATE, not an invoice. A daily cron ' +
-      'creates the next real invoice when next_run_date arrives and moves the date on a month. So nothing here ' +
-      'appears in km_list_invoices until it has actually run at least once, and pausing one (active false) never ' +
-      'touches invoices it has already raised - those are still owed. Read only.',
-    {
-      active: z.boolean().optional().describe('True for only the live plans, false for only the paused ones. Leave it out for all of them.'),
-    },
-    async ({ active }) => {
-      const q = active === undefined ? '' : `?active=${active ? 'true' : 'false'}`;
-      const r = await call('GET', `/recurring-invoices${q}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_create_recurring_invoice',
-    'Set up a repeating invoice: a subscription, a retainer, a payment plan - anything billed on the same day ' +
-      'every month. This is how a monthly membership actually gets charged; the booking catalog only sells it. ' +
-      'Prices are CENTS: unit_price_cents 45000 is $450. cadence is monthly and only monthly (the table refuses ' +
-      'anything else, so weekly and annual plans cannot be stored yet). next_run_date is the day the FIRST ' +
-      'invoice is raised AND the day of the month every later one repeats on, so 2026-10-01 means the 1st. ' +
-      'due_in_days 0 means due the day it is raised, which is what "billed in advance" looks like. ' +
-      '🚨 auto_send defaults to FALSE and you should usually leave it alone: each month the invoice appears as a ' +
-      'DRAFT and the owner approves and sends it. Pass auto_send true ONLY if the owner has explicitly said they ' +
-      'want the client emailed and charged automatically with nobody looking first - and say out loud that it ' +
-      'repeats unattended every month until paused. It also needs a client with an email address on file. ' +
-      'This is a confirmed write; expect a 409 spelling out who is billed how much and how often.',
-    {
-      title: z.string().min(1).max(200).describe('Name the plan, e.g. "Dazzling Decor Club - Gold". The owner reads this in the list, and the generated invoices quote it in their notes.'),
-      line_items: z.array(LINE_ITEM).min(1).max(50).describe('What is billed each month. At least one line: a template with none generates nothing at all.'),
-      client_id: z.string().optional().describe('UUID from km_list_clients: who gets billed. Leave it out only for a plan not yet tied to a client (and then auto_send cannot be used).'),
-      cadence: z.enum(['monthly']).optional().describe("Leave it out. 'monthly' is the only value the table accepts today."),
-      next_run_date: z.string().describe('yyyy-mm-dd, e.g. 2026-10-01. The first billing date, and the day of the month it repeats on. The 31st clamps to the 28th in February.'),
-      due_in_days: z.number().int().min(0).max(365).optional().describe('Days from issue to due date. Leave it out for 14; use 0 for billed-in-advance, due immediately.'),
-      discount_cents: z.number().int().min(0).optional().describe('A flat discount off each month, in cents. Cannot exceed what the line items add up to.'),
-      tax_rate: z.number().min(0).max(100).optional().describe('Tax as a PERCENTAGE: 7.5 means 7.5%, not 0.075.'),
-      currency: z.string().length(3).optional().describe('3-letter code like USD. Leave it out to use the workspace currency.'),
-      auto_send: z.boolean().optional().describe('Leave it out for false: the invoice is a draft each month and the owner sends it. True emails the client the pay link automatically, unattended, every month, with nobody checking it first.'),
-      booking_id: z.string().optional().describe('UUID of a booking every generated invoice should hang off, if there is one.'),
-      source_invoice_id: z.string().optional().describe('UUID of the invoice this plan was modelled on, for provenance. Optional.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async (body) => {
-      const r = await call('POST', '/recurring-invoices', body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_update_recurring_invoice',
-    'Change a repeating invoice: PAUSE it (active false - no invoice is generated at all until resumed), resume ' +
-      'it, change what it bills each month (line_items, discount_cents, tax_rate), move the next billing date, ' +
-      'change the payment terms, or switch auto-send on or off. ' +
-      'Run km_list_recurring_invoices first and work from real ids. Send only the fields you are changing - but ' +
-      'line_items REPLACES the whole list, so send every line, not just the changed one. ' +
-      'Everything here affects FUTURE invoices only: invoices already raised keep their amounts and are still ' +
-      'owed, so ending a subscription means pausing the plan, not undoing the bills. ' +
-      '🚨 Moving next_run_date EARLIER can bill a month again - the generator bills on whatever date it finds, ' +
-      'and it has no memory of which months it already covered. The confirmation sentence and the response both ' +
-      'say so when that is what you are doing. There is no way to change who a plan bills: create a new plan and ' +
-      'pause this one, so a template that has billed somebody cannot quietly start billing somebody else. ' +
-      'This is a confirmed write; expect a 409 naming the plan and the change first.',
-    {
-      recurring_invoice_id: z.string().describe('UUID of the plan, from km_list_recurring_invoices.'),
-      active: z.boolean().optional().describe('false pauses it: nothing is generated until it is true again. true resumes it.'),
-      title: z.string().min(1).max(200).optional(),
-      line_items: z.array(LINE_ITEM).min(1).max(50).optional().describe('The COMPLETE list of what is billed each month. It replaces what is there.'),
-      discount_cents: z.number().int().min(0).optional().describe('Flat discount off each month, in cents.'),
-      tax_rate: z.number().min(0).max(100).optional().describe('Tax as a PERCENTAGE: 7.5 means 7.5%.'),
-      currency: z.string().length(3).nullable().optional().describe('3-letter code, or null to fall back to the workspace currency.'),
-      next_run_date: z.string().optional().describe('yyyy-mm-dd. The next billing date, and from then on the day of the month it repeats on. Moving it LATER skips ahead; moving it EARLIER can re-bill a month.'),
-      due_in_days: z.number().int().min(0).max(365).optional().describe('Days from issue to due date on each generated invoice.'),
-      auto_send: z.boolean().optional().describe('True starts emailing the client the pay link automatically each month with nobody checking first; false goes back to a draft the owner approves. Only ask for true if the owner explicitly wants it.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async ({ recurring_invoice_id, ...changes }) => {
-      const r = await call('PATCH', `/recurring-invoices/${encodeURIComponent(String(recurring_invoice_id || '').trim())}`, changes);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: recurring-invoices - subscription billing from the terminal.
+ *
+ * WHY THIS FAMILY EXISTS. On 22-Sep-2026 Jackie (Dazzling Balloons) set out to
+ * launch a monthly decor subscription - billed monthly in advance on the 1st,
+ * three tiers, a three-month minimum. Her terminal could read every invoice she
+ * had ever raised and could not set up a single repeating one: the
+ * recurring_invoices table was writable only from the "Make recurring" panel on
+ * an existing invoice in the web app. A recurring plan is one bill with a
+ * schedule inside it, and the schedule was mouse-only.
+ *
+ * 🚨 auto_send DEFAULTS FALSE, on purpose. Off, each month's invoice is created
+ * as a DRAFT and nobody is emailed - the owner looks at it and sends it. On, the
+ * cron marks it sent and emails the client the pay link unattended, every month,
+ * forever. That second one is a standing instruction to charge somebody, so a
+ * terminal never picks it by omission: the person has to ask, and the
+ * confirmation sentence says in plain words which one they are getting.
+ *
+ * Every write here moves money, so every write is confirm-gated.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'recurring-invoices';
+
+export const TOOLS = [
+  'km_list_recurring_invoices', 'km_create_recurring_invoice', 'km_update_recurring_invoice',
+];
+
+// 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 = [];
+
+/** Route-level 404 (carries a routes list) vs a handler's not_found. See forms.mjs. */
+function routeMissing(r) {
+  if (r.status === 405 || r.status === 501) return true;
+  return r.status === 404 && Array.isArray(r.data?.routes);
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub is running a version that cannot set up repeating invoices from the terminal yet. The workspace is ' +
+  'fine and every other tool works as normal. Recurring invoices are set up in the web app at ' +
+  'https://hub.kivimedia.co: open an invoice, then "Make recurring".';
+
+const CONFIRM_DESC =
+  'Leave this out on the first call. This action commits to billing somebody money on a schedule, so it needs an '
+  + 'explicit yes from the person you are working with: KM Hub answers 409 with a plain sentence saying who gets '
+  + 'billed how much and how often, plus a token. Show them that sentence in those words, wait for a real answer, '
+  + 'and only then call again with the token and the SAME arguments. A yes for one plan never authorises a different '
+  + 'one.';
+
+const LINE_ITEM = z.object({
+  description: z.string().min(1).max(500).describe('What the line says on the invoice, e.g. "Dazzling Decor Club - Gold tier, monthly".'),
+  unit_price_cents: z.number().int().min(0).describe('Price per unit in CENTS. 45000 is $450.00.'),
+  quantity: z.number().gt(0).max(9999).optional().describe('How many. Leave it out for 1; decimals like 1.5 are fine.'),
+});
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_list_recurring_invoices',
+    'The repeating invoices this workspace bills: what each one charges, to whom, when it next runs, whether it ' +
+      'is paused, and whether it emails itself or waits as a draft for approval. Each row carries the computed ' +
+      'monthly total in real money, plus a plain_english line, and the response totals up the active monthly ' +
+      'recurring revenue. ' +
+      'THE MODEL, so you never have to guess: a recurring invoice is a TEMPLATE, not an invoice. A daily cron ' +
+      'creates the next real invoice when next_run_date arrives and moves the date on a month. So nothing here ' +
+      'appears in km_list_invoices until it has actually run at least once, and pausing one (active false) never ' +
+      'touches invoices it has already raised - those are still owed. Read only.',
+    {
+      active: z.boolean().optional().describe('True for only the live plans, false for only the paused ones. Leave it out for all of them.'),
+    },
+    async ({ active }) => {
+      const q = active === undefined ? '' : `?active=${active ? 'true' : 'false'}`;
+      const r = await call('GET', `/recurring-invoices${q}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_create_recurring_invoice',
+    'Set up a repeating invoice: a subscription, a retainer, a payment plan - anything billed on the same day ' +
+      'every month. This is how a monthly membership actually gets charged; the booking catalog only sells it. ' +
+      'Prices are CENTS: unit_price_cents 45000 is $450. cadence is monthly and only monthly (the table refuses ' +
+      'anything else, so weekly and annual plans cannot be stored yet). next_run_date is the day the FIRST ' +
+      'invoice is raised AND the day of the month every later one repeats on, so 2026-10-01 means the 1st. ' +
+      'due_in_days 0 means due the day it is raised, which is what "billed in advance" looks like. ' +
+      '🚨 auto_send defaults to FALSE and you should usually leave it alone: each month the invoice appears as a ' +
+      'DRAFT and the owner approves and sends it. Pass auto_send true ONLY if the owner has explicitly said they ' +
+      'want the client emailed and charged automatically with nobody looking first - and say out loud that it ' +
+      'repeats unattended every month until paused. It also needs a client with an email address on file. ' +
+      'This is a confirmed write; expect a 409 spelling out who is billed how much and how often.',
+    {
+      title: z.string().min(1).max(200).describe('Name the plan, e.g. "Dazzling Decor Club - Gold". The owner reads this in the list, and the generated invoices quote it in their notes.'),
+      line_items: z.array(LINE_ITEM).min(1).max(50).describe('What is billed each month. At least one line: a template with none generates nothing at all.'),
+      client_id: z.string().optional().describe('UUID from km_list_clients: who gets billed. Leave it out only for a plan not yet tied to a client (and then auto_send cannot be used).'),
+      cadence: z.enum(['monthly']).optional().describe("Leave it out. 'monthly' is the only value the table accepts today."),
+      next_run_date: z.string().describe('yyyy-mm-dd, e.g. 2026-10-01. The first billing date, and the day of the month it repeats on. The 31st clamps to the 28th in February.'),
+      due_in_days: z.number().int().min(0).max(365).optional().describe('Days from issue to due date. Leave it out for 14; use 0 for billed-in-advance, due immediately.'),
+      discount_cents: z.number().int().min(0).optional().describe('A flat discount off each month, in cents. Cannot exceed what the line items add up to.'),
+      tax_rate: z.number().min(0).max(100).optional().describe('Tax as a PERCENTAGE: 7.5 means 7.5%, not 0.075.'),
+      currency: z.string().length(3).optional().describe('3-letter code like USD. Leave it out to use the workspace currency.'),
+      auto_send: z.boolean().optional().describe('Leave it out for false: the invoice is a draft each month and the owner sends it. True emails the client the pay link automatically, unattended, every month, with nobody checking it first.'),
+      booking_id: z.string().optional().describe('UUID of a booking every generated invoice should hang off, if there is one.'),
+      source_invoice_id: z.string().optional().describe('UUID of the invoice this plan was modelled on, for provenance. Optional.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async (body) => {
+      const r = await call('POST', '/recurring-invoices', body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_update_recurring_invoice',
+    'Change a repeating invoice: PAUSE it (active false - no invoice is generated at all until resumed), resume ' +
+      'it, change what it bills each month (line_items, discount_cents, tax_rate), move the next billing date, ' +
+      'change the payment terms, or switch auto-send on or off. ' +
+      'Run km_list_recurring_invoices first and work from real ids. Send only the fields you are changing - but ' +
+      'line_items REPLACES the whole list, so send every line, not just the changed one. ' +
+      'Everything here affects FUTURE invoices only: invoices already raised keep their amounts and are still ' +
+      'owed, so ending a subscription means pausing the plan, not undoing the bills. ' +
+      '🚨 Moving next_run_date EARLIER can bill a month again - the generator bills on whatever date it finds, ' +
+      'and it has no memory of which months it already covered. The confirmation sentence and the response both ' +
+      'say so when that is what you are doing. There is no way to change who a plan bills: create a new plan and ' +
+      'pause this one, so a template that has billed somebody cannot quietly start billing somebody else. ' +
+      'This is a confirmed write; expect a 409 naming the plan and the change first.',
+    {
+      recurring_invoice_id: z.string().describe('UUID of the plan, from km_list_recurring_invoices.'),
+      active: z.boolean().optional().describe('false pauses it: nothing is generated until it is true again. true resumes it.'),
+      title: z.string().min(1).max(200).optional(),
+      line_items: z.array(LINE_ITEM).min(1).max(50).optional().describe('The COMPLETE list of what is billed each month. It replaces what is there.'),
+      discount_cents: z.number().int().min(0).optional().describe('Flat discount off each month, in cents.'),
+      tax_rate: z.number().min(0).max(100).optional().describe('Tax as a PERCENTAGE: 7.5 means 7.5%.'),
+      currency: z.string().length(3).nullable().optional().describe('3-letter code, or null to fall back to the workspace currency.'),
+      next_run_date: z.string().optional().describe('yyyy-mm-dd. The next billing date, and from then on the day of the month it repeats on. Moving it LATER skips ahead; moving it EARLIER can re-bill a month.'),
+      due_in_days: z.number().int().min(0).max(365).optional().describe('Days from issue to due date on each generated invoice.'),
+      auto_send: z.boolean().optional().describe('True starts emailing the client the pay link automatically each month with nobody checking first; false goes back to a draft the owner approves. Only ask for true if the owner explicitly wants it.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async ({ recurring_invoice_id, ...changes }) => {
+      const r = await call('PATCH', `/recurring-invoices/${encodeURIComponent(String(recurring_invoice_id || '').trim())}`, changes);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}