@kivimedia/kmhub 2.0.0 → 2.9.0

package/tools/profile.mjs

@@ -0,0 +1,118 @@
+/**
+ * Tool family: profile - who this business IS, and correcting it when it is wrong.
+ *
+ *   km_get_profile    -> GET   /profile
+ *   km_update_profile -> PATCH /profile
+ *
+ * WHY THIS EXISTS. A connector could already READ enough to notice that a profile
+ * was wrong and had no way to fix it. The nearest write was km_propose_business_fact,
+ * which lands a PENDING proposal: it does not change the talent category, the
+ * timezone or the sending identity, and nothing downstream reads it until a human
+ * approves it in the web app. A model that answers "I have recorded that you are a
+ * mentalist" on the back of a proposal has told the user something untrue.
+ *
+ * 🚨 The talent category (verticals) is the field that matters. It decides the
+ * flavour every AI writer and every lead scout works in. A magician's workspace
+ * that is really a mentalist's produces subtly wrong copy in every direction, and
+ * the owner usually cannot tell WHY it sounds off.
+ *
+ * 🚨 km_update_profile is a confirmed write. KM Hub answers 409 with the exact
+ * before -> after sentence it wants approved, written server-side from the live
+ * values. Show that sentence and wait for a real answer.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'profile';
+
+export const TOOLS = ['km_get_profile', 'km_update_profile'];
+
+export const PROFILES = ['*'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose the business profile to the terminal yet. That is not a fault: the workspace is fine ' +
+  'and every other tool works as normal. The profile is in the web app at https://hub.kivimedia.co under Settings, ' +
+  'and this connector will read and edit it once your KM Hub is on a build that publishes it.';
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_get_profile',
+    'Who this business actually is, as the software understands it: its name, its talent category, the timezone and ' +
+      'currency it works in, the language the AI writes in, and the public email, phone, website and address clients ' +
+      'see on quotes and invoices. This is the live row the web app Settings page reads, not a cached copy. ' +
+      'Call it before writing anything in the business\'s own voice, before quoting a price, and before saying anything ' +
+      'about what they do. ' +
+      '🚨 The talent category is the one to look at hardest. It decides the flavour every AI writer and every lead scout ' +
+      'works in, so a workspace still set to Magician when the person is a Mentalist produces subtly wrong copy ' +
+      'everywhere, and the owner usually cannot tell why it sounds off. If what you see does not match what the person ' +
+      'has told you, say so plainly and offer to correct it with km_update_profile. Do not quietly work around it, and ' +
+      'do not file it as a business-knowledge fact instead: a proposed fact does not change the profile. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/profile');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_update_profile',
+    'Correct the live business profile: the talent category, the business name, the timezone, the currency, the ' +
+      'language the AI writes in, or the public email, phone, website and address. Send only the fields that are wrong. ' +
+      'This is a real change to the live workspace and it takes effect immediately - the web app Settings page will show ' +
+      'the same values a second later. ' +
+      'Call km_get_profile first so you are changing from a value you have actually seen, and so you use vertical keys ' +
+      'from the vocabulary it returns rather than inventing one. ' +
+      '🚨 This needs an explicit yes from the person, in this turn. KM Hub answers 409 with a plain sentence naming ' +
+      'exactly what would change, from what, to what, written by the server from the live values. Put that sentence to ' +
+      'them in those words, wait for a real answer, and only then call again with the confirm_token and the SAME ' +
+      'arguments. Do not treat something said earlier in the conversation as agreement. ' +
+      '🚨 Changing the currency does NOT convert any money already recorded: every stored amount keeps its number and is ' +
+      'simply re-labelled. Changing the talent category does not rewrite anything already written, only work that comes ' +
+      'after it. ' +
+      'The account type (solo or agency), the logo, the default tax rate and the portal colour are NOT editable from ' +
+      'here and no argument unlocks them - they are money, an upload, or something you cannot see the result of from a ' +
+      'terminal. Those stay in KM Hub.',
+    {
+      name: z.string().optional().describe('The business name, as it should appear to clients.'),
+      verticals: z
+        .array(z.string())
+        .optional()
+        .describe(
+          'What this business does, as a list of KM Hub vertical keys, most important first. The valid keys come back '
+            + 'from km_get_profile under editable.verticals_vocabulary - use those exact strings and never invent one. '
+            + 'It cannot be an empty list.',
+        ),
+      timezone: z.string().optional().describe('An IANA zone name, for example Asia/Jerusalem or America/New_York.'),
+      currency: z.string().optional().describe('A three-letter code KM Hub supports: USD, CAD, GBP, EUR, AUD or ILS.'),
+      language: z.string().optional().describe('The language the AI writes to customers in by default: en, he or es.'),
+      public_email: z.string().nullable().optional().describe('The address clients see. Send null to clear it.'),
+      public_phone: z.string().nullable().optional().describe('The number clients see. Send null to clear it.'),
+      website_url: z.string().nullable().optional().describe('Must start with http:// or https://. Send null to clear it.'),
+      address: z.string().nullable().optional().describe('The business address on one line. Send null to clear it.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. KM Hub will answer 409 with the sentence to put to the person and a token. '
+            + 'Only after they actually say yes, call again with the token and the SAME arguments. A yes for one change '
+            + 'never authorises a different one.',
+        ),
+    },
+    async (args) => {
+      // Only forward what the caller actually set: an undefined key would be sent
+      // as an absent field anyway, but a null one MEANS "clear this", so the two
+      // must not be flattened together.
+      const body = {};
+      for (const [k, v] of Object.entries(args)) if (v !== undefined) body[k] = v;
+      const r = await call('PATCH', '/profile', body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/radar.mjs

@@ -0,0 +1,173 @@
+/**
+ * Tool family: radar - the scanners that go looking for work, plus the tail.
+ *
+ * The last of the parity sweep. KM Hub runs a family of radars: new business
+ * openings, milestones, schools, libraries, property, races, conferences, events
+ * and the gig marketplaces. They looked like nine separate gaps and they are not:
+ * every one is a scout mission with a different kind, so two tools reach all of
+ * them, and a radar added next year is readable the day it ships.
+ *
+ *   km_list_radar_scans     -> GET /radar/missions
+ *   km_property_scan        -> GET /radar/communities
+ *   km_list_marketplace_leads -> GET /radar/finds
+ *   km_list_reviews         -> GET /ops/reviews
+ *   km_list_trips           -> GET /ops/trips
+ *   km_list_catalogs        -> GET /ops/catalogs
+ *
+ * 🚨 READ ONLY. Starting a scan spends the client's money on lead-sourcing
+ * providers. That already exists as km_start_lead_scout, which was built with cost
+ * disclosure around it, and this family deliberately adds no second quieter way
+ * to spend.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'radar';
+
+export const TOOLS = [
+  'km_list_radar_scans',
+  'km_property_scan',
+  'km_list_marketplace_leads',
+  'km_list_reviews',
+  'km_list_trips',
+  'km_list_catalogs',
+];
+
+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_radar_scans',
+    'Every automated scan KM Hub has run looking for work, whatever kind: new business openings, milestones, schools, ' +
+      'libraries, property, races, conferences, events and marketplace sweeps. Each returns its kind, phase, progress, ' +
+      'a summary of what it found and any error. ' +
+      'Use it when the user asks whether the lead finding is working, why no new leads have appeared, or what the ' +
+      'radars are doing. ' +
+      '🚨 `failed` is the number to lead with. A radar that quietly stopped is a lead SOURCE that stopped, and nothing ' +
+      'else in the workspace will ever mention it: the pipeline just gets thinner for reasons nobody connects to a ' +
+      'broken scan weeks earlier. ' +
+      'Full result blobs are summarised rather than returned whole. Starting a scan costs real money and is done with ' +
+      'km_start_lead_scout or in KM Hub, never here. Read only.',
+    {
+      kind: z.string().optional().describe('Narrow to one radar type, for example the job_type a previous call returned.'),
+      status: z.string().optional().describe('Narrow to one state, for example running, failed or completed.'),
+      limit: z.number().int().min(1).max(150).optional().describe('How many scans, newest first. Default 30.'),
+    },
+    async ({ kind, status, limit }) => {
+      const r = await call('GET', `/radar/missions${qs({ kind, status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_property_scan',
+    'The residential communities and owner associations Property Radar has on record for one market: apartment ' +
+      'communities, homeowner and property owner associations (HOA and POA), condo associations and 55+ active adult ' +
+      'communities. Each returns its size, tier, management company, any resident events already evidenced, and how ' +
+      'many reachable STAFF contacts it has. ' +
+      'Two ways in, because the two buyers are filed differently: give a `city` for apartment communities, or a ' +
+      '`county` for associations, which is how the state registries publish them. ' +
+      '🚨 `staff_contacts` is the number that decides whether a row is actionable, not the contact field. An ' +
+      'association is run by paid staff (a lifestyle director, an activities director, a community manager) and by ' +
+      'unpaid volunteers on its board. Only the staff are a lawful outreach target: a board member\'s address is a ' +
+      'personal one, it changes at every annual meeting, and several states forbid the association from releasing it ' +
+      'even to a fellow owner. A row with zero staff contacts needs enrichment before anyone writes to it. ' +
+      '🚨 Timing is the other thing to say out loud. Around nine in ten associations run a calendar fiscal year: the ' +
+      'events budget is drafted from late July, bids close through October and the board votes in November. A pitch ' +
+      'in August is inside the number being written; the same pitch in February is arguing with one already fixed for ' +
+      'twelve months. ' +
+      'Starting a sweep costs real money and is done with km_start_lead_scout or in KM Hub, never here. Read only.',
+    {
+      state: z.string().describe('Two-letter US state code, like TX or VA.'),
+      city: z.string().optional().describe('For apartment communities. Case insensitive.'),
+      county: z.string().optional().describe('For homeowner and property owner associations, which are filed by county. Name only, without the word County.'),
+      assoc_kind: z.string().optional().describe('Narrow to one kind: hoa, poa, condo_assoc, master_assoc, sub_assoc, or any_association for all of them.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many communities. Default 40.'),
+    },
+    async ({ state, city, county, assoc_kind, limit }) => {
+      const r = await call('GET', `/radar/communities${qs({ state, city, county, assoc_kind, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_marketplace_leads',
+    'Leads swept from the gig marketplaces this business sells on, each with its portal, the event, a fit score, a ' +
+      'margin verdict and whether anybody turned it into a deal or skipped it. ' +
+      '🚨 `unactioned` is the important number: leads that are neither a deal nor skipped. On gig portals speed decides ' +
+      'who gets the work, so an unactioned lead is almost always a LOST one rather than a waiting one, and saying that ' +
+      'plainly is more useful than listing them neutrally. ' +
+      '`skip_reason` is worth reading in bulk: the same reason recurring usually means the sweep is aimed slightly wrong. ' +
+      'Replying happens in KM Hub. Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many leads, newest first. Default 40.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/radar/finds${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_reviews',
+    'Reviews this business has received and requested, with platform, rating, the text, and whether each was replied to. ' +
+      'Use it when the user asks about their reputation, what clients are saying, or before any play that leans on ' +
+      'social proof. ' +
+      '🚨 Lead with `unreplied`. An unanswered review, good or bad, is read by every future buyer who finds it, and a ' +
+      'reply is the cheapest reputation work available. `requested_but_not_received` is the other useful number: those ' +
+      'are asks that went nowhere. Requesting and replying happen in KM Hub. Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many reviews, newest first. Default 40.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/ops/reviews${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_trips',
+    'Mileage logged in a window, with distance and what is reimbursable. Defaults to the last 90 days. ' +
+      'Use it when the user asks about travel, vehicle costs or expenses tied to getting to jobs. ' +
+      'Reimbursement is in CENTS. Unclaimed mileage is money the business is entitled to and routinely does not take, ' +
+      'so a large reimbursable total that never appears in the accounts is worth mentioning. 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 trips. Default 100. Check `truncated` before trusting a total.'),
+    },
+    async ({ from, to, limit }) => {
+      const r = await call('GET', `/ops/trips${qs({ from, to, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_catalogs',
+    'The booking catalogues that decide what a buyer is offered on the public booking pages, which is default, and ' +
+      'which customer types each is aimed at. ' +
+      'Use it before describing what this business sells publicly, because the catalogue and the internal price list ' +
+      'are not the same thing and a buyer only ever sees the catalogue. Prices come from km_get_offers_and_pricing, ' +
+      'never from here. Editing happens in KM Hub. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/ops/catalogs');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/recurring-invoices.mjs

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