@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/money.mjs

@@ -1,197 +1,235 @@
-/**
- * Tool family: money - invoices, quotes, proposals, contracts and payments.
- *
- * Nine tools, all of them read-only, and that is the whole point of this family.
- * Money is the one area where a confident machine is most expensive to be wrong
- * in, so this family answers questions and a person still issues the money:
- *
- *   - There is no tool here that creates an invoice or a quote. An invoice row in
- *     KM Hub is born with a public pay link (invoices.public_id has a default,
- *     and the public checkout endpoint charges against it without ever looking at
- *     the invoice status), so a "draft" invoice is not inert the way an outreach
- *     draft is. The same is true of a Quote Builder quote, which is acceptable
- *     from an anonymous page the moment it exists.
- *   - There is no tool here that sends, reminds, voids, refunds or marks anything
- *     paid. Nothing in this family changes a number.
- *
- * The single most useful tool is km_money_now: one call, one readable answer.
- * Everything else exists for the follow-up question.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'money';
-
-export const TOOLS = [
-  'km_money_now',
-  'km_list_invoices',
-  'km_get_invoice',
-  'km_list_quotes',
-  'km_get_quote',
-  'km_list_proposals',
-  'km_get_proposal',
-  'km_list_contracts',
-  'km_list_payments',
-];
-
-// The money profile exists for callers who only want this side of the workspace.
-export const PROFILES = ['money'];
-
-/** Shared tail on every description, so the model never has to guess the limit. */
-const READ_ONLY = 'This tool only reads. It cannot change a number, issue anything, or send anything to a client.';
-
-/** Why there is no create tool, said in the two places a model is most likely to reach for one. */
-const NO_ISSUING =
-  'There is deliberately no way to raise an invoice or a quote from here. In KM Hub a person does that, because an invoice becomes payable by the client the moment it exists. If the user asks you to create one, say plainly that they need to do it in KM Hub, and offer to pull up whatever they need to write it.';
-
-/**
- * @param {{ tool: Function }} server guarded registrar (see ./README.md)
- * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
- * @param {{ out: Function, qs: Function }} helpers shared response helpers from ../tools.mjs
- */
-export function register(server, call, { out, qs }) {
-  server.tool(
-    'km_money_now',
-    'The one money check: where this business stands right now, in a single call. It comes back with a headline sentence you can read straight out loud, plus the detail behind it: how much clients owe, how much of that is already overdue and which clients are late, how many contracts are still waiting on a signature, how many quotes and proposals are out with no answer yet, and how much money has actually landed this month and this year. ' +
-      'Reach for this first when the SUBJECT IS MONEY: how are we doing, what is outstanding, who owes me, what is late on the money side, do I need to chase anyone, how was this month. Only go to the other money tools afterwards, when the user wants the detail behind one line of it. ' +
-      'It is not the tool for the broad question about the day. If the user says "what needs me today", "catch me up", "what should I do first", "anything urgent" or "what did I miss", reach for km_briefing instead: money is one column of somebody\'s day, and km_briefing ranks the late invoices against the new enquiries, the unanswered replies, the overdue tasks and today\'s gig, none of which this tool can see. Answering the whole day from this one would report the money and silently drop the rest. ' +
-      'It tells you honestly when a number is incomplete, for instance when a workspace has more unpaid invoices than one read can cover, or when it bills in more than one currency. Invoices still sitting at draft are reported separately and are never counted as money owed, because they have not gone to anyone. ' +
-      READ_ONLY,
-    {},
-    async () => out(await call('GET', '/money/summary')),
-  );
-
-  server.tool(
-    'km_list_invoices',
-    'List invoices, soonest due first. Each one comes back with the amount still owed, the due date, how many days late it is if it is late, and the client and event it belongs to. ' +
-      'Use paid: false for what is still owed, which is what people usually mean by "my invoices". Use overdue: true for the chase list. Use client_id to see one client. Use from and to for a due-date window, for instance everything due this month. ' +
-      'Reach for it when someone asks who owes money, what is outstanding, what is late, or wants to look through a particular client\'s invoices. If the question is broader than that ("how am I doing"), use km_money_now instead, which answers it in one call. ' +
-      NO_ISSUING +
-      ' ' +
-      READ_ONLY,
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
-      paid: z
-        .boolean()
-        .optional()
-        .describe('false for invoices with money still owed on them. true for ones that are fully settled. Leave it out for both.'),
-      overdue: z.boolean().optional().describe('true for invoices that are past their due date and still owe money.'),
-      status: z
-        .string()
-        .optional()
-        .describe('One KM Hub status, e.g. draft, sent, viewed, partially_paid, paid, voided. Usually paid: false is the better filter.'),
-      client_id: z.string().optional().describe('UUID of a client, from km_find_contact.'),
-      from: z.string().optional().describe('Earliest DUE date, YYYY-MM-DD.'),
-      to: z.string().optional().describe('Latest DUE date, YYYY-MM-DD.'),
-    },
-    async ({ limit, paid, overdue, status, client_id, from, to }) =>
-      out(await call('GET', `/invoices${qs({ limit: limit ?? 25, paid, overdue, status, client_id, from, to })}`)),
-  );
-
-  server.tool(
-    'km_get_invoice',
-    'Open one invoice in full: every line on it, every payment already recorded against it, and its instalment plan if it has one, with how late each instalment is. ' +
-      'Use it after km_list_invoices when someone asks what is actually on an invoice, how much of it has been paid already, or when the next instalment falls due. ' +
-      READ_ONLY,
-    {
-      invoice_id: z.string().describe('UUID of the invoice, from km_list_invoices or km_money_now.'),
-    },
-    async ({ invoice_id }) => out(await call('GET', `/invoices/${encodeURIComponent(String(invoice_id || '').trim())}`)),
-  );
-
-  server.tool(
-    'km_list_quotes',
-    'List the quotes this business has put out. KM Hub keeps quotes in two places, the older CRM quotes and the newer Quote Builder, and this shows BOTH, each row tagged with a source field saying which one it came from. That matters: asking only one of them would tell the user they have no quotes when they have hundreds. ' +
-      'Filter by status to see what is still sitting with a client unanswered. Reach for it when someone asks what quotes are out, what has gone quiet, or what a client was quoted. ' +
-      NO_ISSUING +
-      ' ' +
-      READ_ONLY,
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
-      status: z
-        .string()
-        .optional()
-        .describe('One status, e.g. draft, sent, viewed, accepted. The older quotes use rejected, the Quote Builder uses declined.'),
-      source: z
-        .enum(['crm', 'builder'])
-        .optional()
-        .describe('Narrow to one of the two quote systems. Leave it out to see both, which is almost always what you want.'),
-    },
-    async ({ limit, status, source }) => out(await call('GET', `/quotes${qs({ limit: limit ?? 25, status, source })}`)),
-  );
-
-  server.tool(
-    'km_get_quote',
-    'Open one quote in full, with every priced line on it, so you can say what it actually includes and how it adds up. Works for a quote from either of the two quote systems. Use it after km_list_quotes. ' +
-      READ_ONLY,
-    {
-      quote_id: z.string().describe('UUID of the quote, from km_list_quotes.'),
-    },
-    async ({ quote_id }) => out(await call('GET', `/quotes/${encodeURIComponent(String(quote_id || '').trim())}`)),
-  );
-
-  server.tool(
-    'km_list_proposals',
-    'List proposals and how far each one has got: sent, seen by the client, accepted, completed or declined, with the date of each step and the client and event attached. Archived ones are left out unless you ask for them. ' +
-      'Reach for it when someone asks what is out with clients, which proposals have gone quiet, or what is still waiting on an answer before they can plan the diary. ' +
-      READ_ONLY,
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
-      status: z
-        .string()
-        .optional()
-        .describe('One status, e.g. draft, published, sent, viewed, accepted, completed, declined.'),
-      client_id: z.string().optional().describe('UUID of a client, from km_find_contact.'),
-      include_archived: z.boolean().optional().describe('true to also show archived proposals. Default false.'),
-    },
-    async ({ limit, status, client_id, include_archived }) =>
-      out(await call('GET', `/proposals${qs({ limit: limit ?? 25, status, client_id, include_archived })}`)),
-  );
-
-  server.tool(
-    'km_get_proposal',
-    'Open one proposal: its client, its event, the full trail of when it was sent, first seen, last seen, accepted or declined, and the won or lost figure if anyone recorded one against it. Use it after km_list_proposals when the question is about a specific proposal. ' +
-      READ_ONLY,
-    {
-      proposal_id: z.string().describe('UUID of the proposal, from km_list_proposals.'),
-    },
-    async ({ proposal_id }) => out(await call('GET', `/proposals/${encodeURIComponent(String(proposal_id || '').trim())}`)),
-  );
-
-  server.tool(
-    'km_list_contracts',
-    'List contracts and where each one stands on signing: whether it has gone out, whether the client has opened it, whether it is signed, who signed it and when, and how many days an unsigned one has been sitting with them. ' +
-      'Use signed: false for the chase list, which is the usual question before a gig. Reach for it when someone asks what is unsigned, whether a particular client has signed yet, or what still has to be tied down before an event. ' +
-      READ_ONLY,
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
-      status: z.string().optional().describe('One status, e.g. draft, sent, viewed, signed, voided.'),
-      signed: z.boolean().optional().describe('false for contracts still waiting on a signature. true for ones already signed.'),
-    },
-    async ({ limit, status, signed }) => out(await call('GET', `/contracts${qs({ limit: limit ?? 25, status, signed })}`)),
-  );
-
-  server.tool(
-    'km_list_payments',
-    'List money that has actually come in, most recent first, with the method it arrived by, the reference on it, and the invoice or booking it was against. Refunds are included and marked as such, so the picture is honest rather than flattering. By default it shows only what KM Hub counts as real settled money; set include_pending to true to also see attempts that never settled. ' +
-      'Reach for it when someone asks what has been paid lately, whether a specific payment landed, or wants to tie the workspace up against a bank statement. For a single headline figure for the month, km_money_now is the better call. ' +
-      READ_ONLY,
-    {
-      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
-      kind: z.enum(['payment', 'refund', 'all']).optional().describe('Default all, which shows payments and refunds together.'),
-      include_pending: z
-        .boolean()
-        .optional()
-        .describe('true to also include payments that have not settled. Default false, so only real money is shown.'),
-      method: z
-        .string()
-        .optional()
-        .describe('One method, e.g. cash, check, credit_card, bank_transfer, venmo, paypal, zelle, stripe, other.'),
-      from: z.string().optional().describe('Earliest date the money was received, YYYY-MM-DD.'),
-      to: z.string().optional().describe('Latest date the money was received, YYYY-MM-DD.'),
-    },
-    async ({ limit, kind, include_pending, method, from, to }) =>
-      out(await call('GET', `/payments${qs({ limit: limit ?? 25, kind, include_pending, method, from, to })}`)),
-  );
-}
+/**
+ * Tool family: money - invoices, quotes, proposals, contracts and payments.
+ *
+ * Ten tools, all of them read-only, and that is the whole point of this family.
+ * Money is the one area where a confident machine is most expensive to be wrong
+ * in, so this family answers questions and a person still issues the money:
+ *
+ *   - There is no tool here that creates an invoice or a quote. An invoice row in
+ *     KM Hub is born with a public pay link (invoices.public_id has a default,
+ *     and the public checkout endpoint charges against it without ever looking at
+ *     the invoice status), so a "draft" invoice is not inert the way an outreach
+ *     draft is. The same is true of a Quote Builder quote, which is acceptable
+ *     from an anonymous page the moment it exists.
+ *   - There is no tool here that sends, reminds, voids, refunds or marks anything
+ *     paid. Nothing in this family changes a number.
+ *
+ * The single most useful tool is km_money_now: one call, one readable answer.
+ * Everything else exists for the follow-up question.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'money';
+
+export const TOOLS = [
+  'km_money_now',
+  'km_list_invoices',
+  'km_get_invoice',
+  'km_list_quotes',
+  'km_get_quote',
+  'km_list_proposals',
+  'km_get_proposal',
+  'km_list_contracts',
+  'km_list_payments',
+  'km_price_trend',
+];
+
+// The money profile exists for callers who only want this side of the workspace.
+export const PROFILES = ['money'];
+
+/** Shared tail on every description, so the model never has to guess the limit. */
+const READ_ONLY = 'This tool only reads. It cannot change a number, issue anything, or send anything to a client.';
+
+/** Why there is no create tool, said in the two places a model is most likely to reach for one. */
+const NO_ISSUING =
+  'There is deliberately no way to raise an invoice or a quote from here. In KM Hub a person does that, because an invoice becomes payable by the client the moment it exists. If the user asks you to create one, say plainly that they need to do it in KM Hub, and offer to pull up whatever they need to write it.';
+
+/**
+ * @param {{ tool: Function }} server guarded registrar (see ./README.md)
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ * @param {{ out: Function, qs: Function }} helpers shared response helpers from ../tools.mjs
+ */
+/** A route this KM Hub does not have yet, as opposed to an answer. */
+function routeMissing(r) {
+  if (!(r.status === 404 || r.status === 405 || r.status === 501)) return false;
+  const err = r.data && typeof r.data === 'object' ? r.data.error : undefined;
+  return err !== 'not_found' || /Unknown route/i.test(String(r.data?.message || ''));
+}
+
+const PRICE_NOT_SUPPORTED =
+  'Price history is not available on this KM Hub yet. Nothing is wrong with the workspace and nothing was changed. ' +
+  'The owner can see prices in the web app at https://hub.kivimedia.co under Reports, Business Reporting, Prices, once it is there.';
+
+export function register(server, call, { out, qs, text }) {
+  server.tool(
+    'km_money_now',
+    'The one money check: where this business stands right now, in a single call. It comes back with a headline sentence you can read straight out loud, plus the detail behind it: how much clients owe, how much of that is already overdue and which clients are late, how many contracts are still waiting on a signature, how many quotes and proposals are out with no answer yet, and how much money has actually landed this month and this year. ' +
+      'Reach for this first when the SUBJECT IS MONEY: how are we doing, what is outstanding, who owes me, what is late on the money side, do I need to chase anyone, how was this month. Only go to the other money tools afterwards, when the user wants the detail behind one line of it. ' +
+      'It is not the tool for the broad question about the day. If the user says "what needs me today", "catch me up", "what should I do first", "anything urgent" or "what did I miss", reach for km_briefing instead: money is one column of somebody\'s day, and km_briefing ranks the late invoices against the new enquiries, the unanswered replies, the overdue tasks and today\'s gig, none of which this tool can see. Answering the whole day from this one would report the money and silently drop the rest. ' +
+      'It tells you honestly when a number is incomplete, for instance when a workspace has more unpaid invoices than one read can cover, or when it bills in more than one currency. Invoices still sitting at draft are reported separately and are never counted as money owed, because they have not gone to anyone. ' +
+      READ_ONLY,
+    {},
+    async () => out(await call('GET', '/money/summary')),
+  );
+
+  server.tool(
+    'km_list_invoices',
+    'List invoices, soonest due first. Each one comes back with the amount still owed, the due date, how many days late it is if it is late, and the client and event it belongs to. ' +
+      'Use paid: false for what is still owed, which is what people usually mean by "my invoices". Use overdue: true for the chase list. Use client_id to see one client. Use from and to for a due-date window, for instance everything due this month. ' +
+      'Reach for it when someone asks who owes money, what is outstanding, what is late, or wants to look through a particular client\'s invoices. If the question is broader than that ("how am I doing"), use km_money_now instead, which answers it in one call. ' +
+      NO_ISSUING +
+      ' ' +
+      READ_ONLY,
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
+      paid: z
+        .boolean()
+        .optional()
+        .describe('false for invoices with money still owed on them. true for ones that are fully settled. Leave it out for both.'),
+      overdue: z.boolean().optional().describe('true for invoices that are past their due date and still owe money.'),
+      status: z
+        .string()
+        .optional()
+        .describe('One KM Hub status, e.g. draft, sent, viewed, partially_paid, paid, voided. Usually paid: false is the better filter.'),
+      client_id: z.string().optional().describe('UUID of a client, from km_find_contact.'),
+      from: z.string().optional().describe('Earliest DUE date, YYYY-MM-DD.'),
+      to: z.string().optional().describe('Latest DUE date, YYYY-MM-DD.'),
+    },
+    async ({ limit, paid, overdue, status, client_id, from, to }) =>
+      out(await call('GET', `/invoices${qs({ limit: limit ?? 25, paid, overdue, status, client_id, from, to })}`)),
+  );
+
+  server.tool(
+    'km_get_invoice',
+    'Open one invoice in full: every line on it, every payment already recorded against it, and its instalment plan if it has one, with how late each instalment is. ' +
+      'Use it after km_list_invoices when someone asks what is actually on an invoice, how much of it has been paid already, or when the next instalment falls due. ' +
+      READ_ONLY,
+    {
+      invoice_id: z.string().describe('UUID of the invoice, from km_list_invoices or km_money_now.'),
+    },
+    async ({ invoice_id }) => out(await call('GET', `/invoices/${encodeURIComponent(String(invoice_id || '').trim())}`)),
+  );
+
+  server.tool(
+    'km_list_quotes',
+    'List the quotes this business has put out. KM Hub keeps quotes in two places, the older CRM quotes and the newer Quote Builder, and this shows BOTH, each row tagged with a source field saying which one it came from. That matters: asking only one of them would tell the user they have no quotes when they have hundreds. ' +
+      'Filter by status to see what is still sitting with a client unanswered. Reach for it when someone asks what quotes are out, what has gone quiet, or what a client was quoted. ' +
+      NO_ISSUING +
+      ' ' +
+      READ_ONLY,
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
+      status: z
+        .string()
+        .optional()
+        .describe('One status, e.g. draft, sent, viewed, accepted. The older quotes use rejected, the Quote Builder uses declined.'),
+      source: z
+        .enum(['crm', 'builder'])
+        .optional()
+        .describe('Narrow to one of the two quote systems. Leave it out to see both, which is almost always what you want.'),
+    },
+    async ({ limit, status, source }) => out(await call('GET', `/quotes${qs({ limit: limit ?? 25, status, source })}`)),
+  );
+
+  server.tool(
+    'km_get_quote',
+    'Open one quote in full, with every priced line on it, so you can say what it actually includes and how it adds up. Works for a quote from either of the two quote systems. Use it after km_list_quotes. ' +
+      READ_ONLY,
+    {
+      quote_id: z.string().describe('UUID of the quote, from km_list_quotes.'),
+    },
+    async ({ quote_id }) => out(await call('GET', `/quotes/${encodeURIComponent(String(quote_id || '').trim())}`)),
+  );
+
+  server.tool(
+    'km_list_proposals',
+    'List proposals and how far each one has got: sent, seen by the client, accepted, completed or declined, with the date of each step and the client and event attached. Archived ones are left out unless you ask for them. ' +
+      'Reach for it when someone asks what is out with clients, which proposals have gone quiet, or what is still waiting on an answer before they can plan the diary. ' +
+      READ_ONLY,
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
+      status: z
+        .string()
+        .optional()
+        .describe('One status, e.g. draft, published, sent, viewed, accepted, completed, declined.'),
+      client_id: z.string().optional().describe('UUID of a client, from km_find_contact.'),
+      include_archived: z.boolean().optional().describe('true to also show archived proposals. Default false.'),
+    },
+    async ({ limit, status, client_id, include_archived }) =>
+      out(await call('GET', `/proposals${qs({ limit: limit ?? 25, status, client_id, include_archived })}`)),
+  );
+
+  server.tool(
+    'km_get_proposal',
+    'Open one proposal: its client, its event, the full trail of when it was sent, first seen, last seen, accepted or declined, and the won or lost figure if anyone recorded one against it. Use it after km_list_proposals when the question is about a specific proposal. ' +
+      READ_ONLY,
+    {
+      proposal_id: z.string().describe('UUID of the proposal, from km_list_proposals.'),
+    },
+    async ({ proposal_id }) => out(await call('GET', `/proposals/${encodeURIComponent(String(proposal_id || '').trim())}`)),
+  );
+
+  server.tool(
+    'km_list_contracts',
+    'List contracts and where each one stands on signing: whether it has gone out, whether the client has opened it, whether it is signed, who signed it and when, and how many days an unsigned one has been sitting with them. ' +
+      'Use signed: false for the chase list, which is the usual question before a gig. Reach for it when someone asks what is unsigned, whether a particular client has signed yet, or what still has to be tied down before an event. ' +
+      READ_ONLY,
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
+      status: z.string().optional().describe('One status, e.g. draft, sent, viewed, signed, voided.'),
+      signed: z.boolean().optional().describe('false for contracts still waiting on a signature. true for ones already signed.'),
+    },
+    async ({ limit, status, signed }) => out(await call('GET', `/contracts${qs({ limit: limit ?? 25, status, signed })}`)),
+  );
+
+  server.tool(
+    'km_list_payments',
+    'List money that has actually come in, most recent first, with the method it arrived by, the reference on it, and the invoice or booking it was against. Refunds are included and marked as such, so the picture is honest rather than flattering. By default it shows only what KM Hub counts as real settled money; set include_pending to true to also see attempts that never settled. ' +
+      'Reach for it when someone asks what has been paid lately, whether a specific payment landed, or wants to tie the workspace up against a bank statement. For a single headline figure for the month, km_money_now is the better call. ' +
+      READ_ONLY,
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
+      kind: z.enum(['payment', 'refund', 'all']).optional().describe('Default all, which shows payments and refunds together.'),
+      include_pending: z
+        .boolean()
+        .optional()
+        .describe('true to also include payments that have not settled. Default false, so only real money is shown.'),
+      method: z
+        .string()
+        .optional()
+        .describe('One method, e.g. cash, check, credit_card, bank_transfer, venmo, paypal, zelle, stripe, other.'),
+      from: z.string().optional().describe('Earliest date the money was received, YYYY-MM-DD.'),
+      to: z.string().optional().describe('Latest date the money was received, YYYY-MM-DD.'),
+    },
+    async ({ limit, kind, include_pending, method, from, to }) =>
+      out(await call('GET', `/payments${qs({ limit: limit ?? 25, kind, include_pending, method, from, to })}`)),
+  );
+  server.tool(
+    'km_price_trend',
+    'What this business charges over time: the average and the typical (median) price of its events by month, quarter or year, with how many priced events sit behind every number and the same period a year earlier. ' +
+      'Split it by event type, by where the job came from (return client, referral, search and listing sites), by new versus returning clients, or by tag. With by: source it also says how many leads from each source were won. ' +
+      'Reach for it when someone asks whether their prices are going up, what a typical wedding or birthday sells for now, which clients pay the most, whether new clients are still coming in, or before any conversation about raising prices. ' +
+      'Read the caveats that come back and keep them: a row marked too_few is "too few to read" and carries no conclusion, lead with the typical price because the average moves with the mix of jobs, discounts that read "not recorded" are never 0%, and these numbers show that a price moved, never why, so never credit or blame marketing or brand work for a change. ' +
+      'For a long history use grain year or quarter; months split by event type over many years is a very long list. ' +
+      READ_ONLY,
+    {
+      grain: z
+        .enum(['month', 'quarter', 'year', 'all'])
+        .optional()
+        .describe('How to group the event dates. Default quarter. all gives one row per group for the whole window.'),
+      by: z
+        .enum(['none', 'event_type', 'source', 'client_type', 'tag'])
+        .optional()
+        .describe('How to split each period. Default none. source = where the job came from, client_type = new vs returning client.'),
+      from: z.string().optional().describe('Earliest EVENT date, YYYY-MM-DD. Leave out for the whole history.'),
+      to: z.string().optional().describe('Latest EVENT date, YYYY-MM-DD. Leave out for everything booked, future events included.'),
+    },
+    async ({ grain, by, from, to }) => {
+      const r = await call('GET', `/money/price-trend${qs({ grain: grain ?? 'quarter', by, from, to })}`);
+      if (routeMissing(r)) return text(PRICE_NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}