@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/clubs.mjs

@@ -1,176 +1,176 @@
-/**
- * Tool family: clubs - the Clubs Radar directory, read from the terminal.
- *
- * Like the military family (and unlike every scan-shaped radar), the clubs market is ENUMERABLE
- * rather than searchable: every chartered American Legion post, VFW post, Elks lodge and Moose
- * lodge is a published row somewhere, and the engine has already pulled them in. So the thing a
- * person wants from the terminal is not "what did the last scan find", it is "show me what is
- * already in there", and that needs its own family rather than another entry in a mission list.
- *
- *   km_clubs_directory -> GET /clubs/directory
- *   km_clubs_posts     -> GET /clubs/posts
- *   km_clubs_post      -> GET /clubs/posts/:ref
- *
- * 🚨 READ ONLY, and there are three separate reasons, all of which the descriptions say out loud:
- *
- *   1. NOTHING HERE SUBMITS, APPROVES OR SENDS. Writing to a post's mailbox or dialing its phone
- *      is a human act in KM Hub, behind the Approval Queue - club_radar drafts are a never-auto
- *      source, because a cold first impression to a veterans hall is exactly the message a human
- *      must read first.
- *   2. NOTHING HERE STARTS A SWEEP. Queueing one is admin-only under RLS in the web app, and the
- *      API runs on the service role, which bypasses RLS: a start tool would quietly hand any
- *      read/write key a power the product refuses to a non-admin member. Whether a sweep is
- *      running is readable through km_list_radar_scans with kind 'club_radar_ingest'.
- *   3. Reading costs NOTHING and sends NOTHING. The directory is shared reference data with
- *      global read, already populated before anybody runs anything, so there is no first click
- *      to make and no bill for looking.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'clubs';
-
-export const TOOLS = [
-  'km_clubs_directory',
-  'km_clubs_posts',
-  'km_clubs_post',
-];
-
-// Finding and reaching buyers is outreach work, so this family joins that profile. It is not in
-// `core`: a session that only wants orientation should not carry three more schemas.
-export const PROFILES = ['outreach'];
-
-/**
- * Has this KM Hub simply never heard of the route, or did the route run and find nothing?
- *
- * 🚨 Same discrimination as the military family, for the same reason: asking for a post that is
- * not in the directory is a real, ordinary 404. Collapsing the two would answer a plain typo with
- * "your KM Hub does not have the clubs directory", which is a false statement about the product
- * rather than a wrong answer about a post. So only the router's own self-describing 404, which
- * carries the whole route list, counts as a missing route.
- */
-function routeMissing(r) {
-  if (r.status === 405 || r.status === 501) return true;
-  if (r.status !== 404) return false;
-  const body = r && r.data && typeof r.data === 'object' ? r.data : null;
-  if (!body) return true;
-  if (Array.isArray(body.routes)) return true;
-  return typeof body.message === 'string' && body.message.startsWith('Unknown route');
-}
-
-const NOT_SUPPORTED =
-  'This KM Hub does not serve the clubs directory to the terminal yet. Nothing is broken: the workspace is fine ' +
-  'and every other tool works as normal. The directory is there in the web app at https://hub.kivimedia.co under ' +
-  'Outbound, named Clubs Radar.';
-
-const NO_SEND =
-  'What it will NOT do: it cannot write to a post, dial a phone, mark an engagement or send anything, and no ' +
-  'other tool here can either. Working a post - the ladder from first contact to a monthly residency - happens in ' +
-  'KM Hub at https://hub.kivimedia.co, on purpose. Never tell somebody a message went out.';
-
-const NO_INVENTION =
-  'Never construct an address. A post that publishes no email keeps no email, and a VFW row with a phone and no ' +
-  'mailbox is the NORMAL published state for that order, not missing data. A row whose email_confidence says ' +
-  '"pattern" is a constructed guess from the order\'s scheme (lodge<NUM>@mooseunits.org) that must verify before ' +
-  'it may reach a draft - say so whenever one is shown.';
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_clubs_directory',
-    'The fraternal and veterans halls KM Hub has already enumerated: every chartered American Legion post, VFW ' +
-      'post, Elks lodge and Moose lodge in the directory, counted by order and by state, with how many rent their ' +
-      'hall, run a club room, and publish a mailbox. ' +
-      'Reach for it whenever somebody asks about clubs, lodges, posts, veterans halls, the Legion, the VFW, the ' +
-      'Elks or the Moose, and reach for it FIRST rather than describing the feature: this directory is shared ' +
-      'reference data that is already full before anybody runs anything, so there is nothing to start and nothing ' +
-      'to wait for. Reading it costs nothing, spends nothing and sends nothing. ' +
-      '🚨 Lead with the `directory` block, which is counted from the rows and not asserted. Say those numbers ' +
-      'before any individual row, because the single thing people get wrong about this surface is assuming it is ' +
-      'empty. ' +
-      'Why these buyers matter: posts run weekly member nights on a PRINTED schedule and most own a rentable hall ' +
-      'with an entertainment budget - one signed residency is a recurring monthly show. ' +
-      NO_INVENTION +
-      ' ' +
-      'Whether a sweep is running is a different question, answered by km_list_radar_scans with kind ' +
-      "'club_radar_ingest'. Starting one is done in KM Hub, never from here. " +
-      NO_SEND,
-    {},
-    async () => {
-      const r = await call('GET', '/clubs/directory');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_clubs_posts',
-    'The posts themselves: one row per hall, with its printed meeting schedule (the free-demo-night slot IS that ' +
-      'line), the hall-rental and club-room flags, the route counts, the best mailbox where one is published, and ' +
-      'this workspace\'s own engagement status per post. ' +
-      'Use it when somebody wants the posts near them, the halls that rent, or a call list. Elks rows are the ' +
-      'warmest written route (published lodge emails); VFW rows are phone-first because that order publishes no ' +
-      'email - a phone-only row there is the office working normally. ' +
-      'Every filter is optional and `filters_applied` says back which ones are doing the narrowing, so an empty ' +
-      'result is explained rather than shrugged at. The radius filter needs lat, lng and radius_miles together, ' +
-      'and `skipped_no_coordinates` counts the rows it could not judge. ' +
-      NO_INVENTION +
-      ' ' +
-      'Read only. Costs nothing, spends nothing. ' +
-      NO_SEND,
-    {
-      org: z
-        .enum(['legion', 'vfw', 'elks', 'moose'])
-        .optional()
-        .describe('One fraternal order. Leave it out to see all four.'),
-      state: z.string().optional().describe('Two-letter US state, for example "NJ".'),
-      city: z.string().optional().describe('City name, matched loosely.'),
-      hall_rental: z.boolean().optional().describe('True for posts whose hall is rentable - the venue-partnership list.'),
-      club_room: z.boolean().optional().describe('True for posts with a bar, canteen or club room on premises.'),
-      q: z.string().optional().describe('Free text against name, place, order and meeting schedule, in any order.'),
-      lat: z.number().optional().describe('Radius center latitude. Use with lng and radius_miles.'),
-      lng: z.number().optional().describe('Radius center longitude. Use with lat and radius_miles.'),
-      radius_miles: z.number().optional().describe('Radius in miles around lat/lng. Nearest posts come back first.'),
-      limit: z.number().int().min(1).max(200).optional().describe('How many posts to return. Default 40. Check `truncated`.'),
-    },
-    async ({ org, state, city, hall_rental, club_room, q, lat, lng, radius_miles, limit }) => {
-      const r = await call('GET', `/clubs/posts${qs({ org, state, city, hall_rental, club_room, q, lat, lng, radius_miles, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_clubs_post',
-    'One post in full: every published contact with the page it was read off and the verbatim fragment it came ' +
-      'from, the meeting schedule, the hall flags, and whatever engagement this workspace has already recorded. ' +
-      'Use it after km_clubs_posts when somebody picks a post, or whenever they name one directly. It takes the ' +
-      'club_key from a previous answer (for example "elks:nj:21") or a 9-digit EIN. ' +
-      '🚨 `email_confidence` decides whether an address may be written to as it stands: "published" was read off ' +
-      'the page named in source_url; "pattern" is a constructed guess that must verify first, and any draft ' +
-      'against it is refused until it does. `serves_posts` above 1 means one mailbox answers for several posts - ' +
-      'send it once, never once per hall. ' +
-      '`your_engagement` is this workspace\'s own ladder (researching, contacted, replied, demo booked, monthly ' +
-      'resident) and its sent marks - the record that keeps the same mailbox from being contacted twice. ' +
-      NO_INVENTION +
-      ' ' +
-      'Read only. Costs nothing, spends nothing. ' +
-      NO_SEND,
-    {
-      post: z
-        .string()
-        .describe('The club_key from a previous answer, for example "elks:nj:21", or the post\'s 9-digit EIN.'),
-    },
-    async ({ post }) => {
-      const ref = String(post || '').trim();
-      if (!ref) {
-        return text(
-          'I need to know which post. km_clubs_posts lists them, and each row carries the club_key this tool takes.',
-        );
-      }
-      const r = await call('GET', `/clubs/posts/${encodeURIComponent(ref)}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: clubs - the Clubs Radar directory, read from the terminal.
+ *
+ * Like the military family (and unlike every scan-shaped radar), the clubs market is ENUMERABLE
+ * rather than searchable: every chartered American Legion post, VFW post, Elks lodge and Moose
+ * lodge is a published row somewhere, and the engine has already pulled them in. So the thing a
+ * person wants from the terminal is not "what did the last scan find", it is "show me what is
+ * already in there", and that needs its own family rather than another entry in a mission list.
+ *
+ *   km_clubs_directory -> GET /clubs/directory
+ *   km_clubs_posts     -> GET /clubs/posts
+ *   km_clubs_post      -> GET /clubs/posts/:ref
+ *
+ * 🚨 READ ONLY, and there are three separate reasons, all of which the descriptions say out loud:
+ *
+ *   1. NOTHING HERE SUBMITS, APPROVES OR SENDS. Writing to a post's mailbox or dialing its phone
+ *      is a human act in KM Hub, behind the Approval Queue - club_radar drafts are a never-auto
+ *      source, because a cold first impression to a veterans hall is exactly the message a human
+ *      must read first.
+ *   2. NOTHING HERE STARTS A SWEEP. Queueing one is admin-only under RLS in the web app, and the
+ *      API runs on the service role, which bypasses RLS: a start tool would quietly hand any
+ *      read/write key a power the product refuses to a non-admin member. Whether a sweep is
+ *      running is readable through km_list_radar_scans with kind 'club_radar_ingest'.
+ *   3. Reading costs NOTHING and sends NOTHING. The directory is shared reference data with
+ *      global read, already populated before anybody runs anything, so there is no first click
+ *      to make and no bill for looking.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'clubs';
+
+export const TOOLS = [
+  'km_clubs_directory',
+  'km_clubs_posts',
+  'km_clubs_post',
+];
+
+// Finding and reaching buyers is outreach work, so this family joins that profile. It is not in
+// `core`: a session that only wants orientation should not carry three more schemas.
+export const PROFILES = ['outreach'];
+
+/**
+ * Has this KM Hub simply never heard of the route, or did the route run and find nothing?
+ *
+ * 🚨 Same discrimination as the military family, for the same reason: asking for a post that is
+ * not in the directory is a real, ordinary 404. Collapsing the two would answer a plain typo with
+ * "your KM Hub does not have the clubs directory", which is a false statement about the product
+ * rather than a wrong answer about a post. So only the router's own self-describing 404, which
+ * carries the whole route list, counts as a missing route.
+ */
+function routeMissing(r) {
+  if (r.status === 405 || r.status === 501) return true;
+  if (r.status !== 404) return false;
+  const body = r && r.data && typeof r.data === 'object' ? r.data : null;
+  if (!body) return true;
+  if (Array.isArray(body.routes)) return true;
+  return typeof body.message === 'string' && body.message.startsWith('Unknown route');
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub does not serve the clubs directory to the terminal yet. Nothing is broken: the workspace is fine ' +
+  'and every other tool works as normal. The directory is there in the web app at https://hub.kivimedia.co under ' +
+  'Outbound, named Clubs Radar.';
+
+const NO_SEND =
+  'What it will NOT do: it cannot write to a post, dial a phone, mark an engagement or send anything, and no ' +
+  'other tool here can either. Working a post - the ladder from first contact to a monthly residency - happens in ' +
+  'KM Hub at https://hub.kivimedia.co, on purpose. Never tell somebody a message went out.';
+
+const NO_INVENTION =
+  'Never construct an address. A post that publishes no email keeps no email, and a VFW row with a phone and no ' +
+  'mailbox is the NORMAL published state for that order, not missing data. A row whose email_confidence says ' +
+  '"pattern" is a constructed guess from the order\'s scheme (lodge<NUM>@mooseunits.org) that must verify before ' +
+  'it may reach a draft - say so whenever one is shown.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_clubs_directory',
+    'The fraternal and veterans halls KM Hub has already enumerated: every chartered American Legion post, VFW ' +
+      'post, Elks lodge and Moose lodge in the directory, counted by order and by state, with how many rent their ' +
+      'hall, run a club room, and publish a mailbox. ' +
+      'Reach for it whenever somebody asks about clubs, lodges, posts, veterans halls, the Legion, the VFW, the ' +
+      'Elks or the Moose, and reach for it FIRST rather than describing the feature: this directory is shared ' +
+      'reference data that is already full before anybody runs anything, so there is nothing to start and nothing ' +
+      'to wait for. Reading it costs nothing, spends nothing and sends nothing. ' +
+      '🚨 Lead with the `directory` block, which is counted from the rows and not asserted. Say those numbers ' +
+      'before any individual row, because the single thing people get wrong about this surface is assuming it is ' +
+      'empty. ' +
+      'Why these buyers matter: posts run weekly member nights on a PRINTED schedule and most own a rentable hall ' +
+      'with an entertainment budget - one signed residency is a recurring monthly show. ' +
+      NO_INVENTION +
+      ' ' +
+      'Whether a sweep is running is a different question, answered by km_list_radar_scans with kind ' +
+      "'club_radar_ingest'. Starting one is done in KM Hub, never from here. " +
+      NO_SEND,
+    {},
+    async () => {
+      const r = await call('GET', '/clubs/directory');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_clubs_posts',
+    'The posts themselves: one row per hall, with its printed meeting schedule (the free-demo-night slot IS that ' +
+      'line), the hall-rental and club-room flags, the route counts, the best mailbox where one is published, and ' +
+      'this workspace\'s own engagement status per post. ' +
+      'Use it when somebody wants the posts near them, the halls that rent, or a call list. Elks rows are the ' +
+      'warmest written route (published lodge emails); VFW rows are phone-first because that order publishes no ' +
+      'email - a phone-only row there is the office working normally. ' +
+      'Every filter is optional and `filters_applied` says back which ones are doing the narrowing, so an empty ' +
+      'result is explained rather than shrugged at. The radius filter needs lat, lng and radius_miles together, ' +
+      'and `skipped_no_coordinates` counts the rows it could not judge. ' +
+      NO_INVENTION +
+      ' ' +
+      'Read only. Costs nothing, spends nothing. ' +
+      NO_SEND,
+    {
+      org: z
+        .enum(['legion', 'vfw', 'elks', 'moose'])
+        .optional()
+        .describe('One fraternal order. Leave it out to see all four.'),
+      state: z.string().optional().describe('Two-letter US state, for example "NJ".'),
+      city: z.string().optional().describe('City name, matched loosely.'),
+      hall_rental: z.boolean().optional().describe('True for posts whose hall is rentable - the venue-partnership list.'),
+      club_room: z.boolean().optional().describe('True for posts with a bar, canteen or club room on premises.'),
+      q: z.string().optional().describe('Free text against name, place, order and meeting schedule, in any order.'),
+      lat: z.number().optional().describe('Radius center latitude. Use with lng and radius_miles.'),
+      lng: z.number().optional().describe('Radius center longitude. Use with lat and radius_miles.'),
+      radius_miles: z.number().optional().describe('Radius in miles around lat/lng. Nearest posts come back first.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many posts to return. Default 40. Check `truncated`.'),
+    },
+    async ({ org, state, city, hall_rental, club_room, q, lat, lng, radius_miles, limit }) => {
+      const r = await call('GET', `/clubs/posts${qs({ org, state, city, hall_rental, club_room, q, lat, lng, radius_miles, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_clubs_post',
+    'One post in full: every published contact with the page it was read off and the verbatim fragment it came ' +
+      'from, the meeting schedule, the hall flags, and whatever engagement this workspace has already recorded. ' +
+      'Use it after km_clubs_posts when somebody picks a post, or whenever they name one directly. It takes the ' +
+      'club_key from a previous answer (for example "elks:nj:21") or a 9-digit EIN. ' +
+      '🚨 `email_confidence` decides whether an address may be written to as it stands: "published" was read off ' +
+      'the page named in source_url; "pattern" is a constructed guess that must verify first, and any draft ' +
+      'against it is refused until it does. `serves_posts` above 1 means one mailbox answers for several posts - ' +
+      'send it once, never once per hall. ' +
+      '`your_engagement` is this workspace\'s own ladder (researching, contacted, replied, demo booked, monthly ' +
+      'resident) and its sent marks - the record that keeps the same mailbox from being contacted twice. ' +
+      NO_INVENTION +
+      ' ' +
+      'Read only. Costs nothing, spends nothing. ' +
+      NO_SEND,
+    {
+      post: z
+        .string()
+        .describe('The club_key from a previous answer, for example "elks:nj:21", or the post\'s 9-digit EIN.'),
+    },
+    async ({ post }) => {
+      const ref = String(post || '').trim();
+      if (!ref) {
+        return text(
+          'I need to know which post. km_clubs_posts lists them, and each row carries the club_key this tool takes.',
+        );
+      }
+      const r = await call('GET', `/clubs/posts/${encodeURIComponent(ref)}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}