rootr-cli 0.17.3 → 0.19.0

package/lib/mcp-tools/booking.js

@@ -0,0 +1,403 @@
+import { z } from 'zod';
+
+import { jsonResult, errorResult, makeClient, resolveNodeId, NODE_TARGET_HINT } from './shared.js';
+
+/**
+ * BOOKING — 공개한 표를 **예약 페이지**로 쓰는 도구들(창업자 지시 2026-09-23).
+ *
+ * 화면에서 하던 것을 에이전트도 그대로 할 수 있어야 한다는 요구다. 그래서 여기에는
+ * 켜기·규칙·확정 방식·물어볼 칸·구글 캘린더 고르기, 그리고 **방문자가 보는 빈 시간**까지
+ * 다 있다 — 마지막 것이 없으면 에이전트는 자기가 건 규칙이 실제로 어떻게 보이는지 모른 채
+ * "설정했습니다"라고만 말하게 된다.
+ *
+ * 구글 연결(동의)은 여기에 없다. 구글이 **브라우저에서 사람 손으로 한 번** 허용받기를
+ * 요구하기 때문이다. 대신 `rootr_connect_google_calendar` 가 그 주소를 만들어 주고,
+ * 허용한 뒤로는 목록 보기·고르기가 전부 도구로 된다.
+ */
+
+const WEEKDAY_HINT =
+  '0=Sunday … 6=Saturday. Weekdays only is [1,2,3,4,5].';
+
+const ASK_FIELD = z.object({
+  propId: z
+    .string()
+    .describe('Column id, or the column NAME as shown in the table (names are resolved for you).'),
+  required: z.boolean().optional().describe('Must the visitor fill this in? Default false.'),
+});
+
+/**
+ * 열어 둔 시간 중 **못 잡게 막는 구간**. 하루를 통째로 쉬는 것은 blockedDates 로 두고,
+ * 여기는 "매일 점심", "매주 월요일 오전", "10월 5일 오후만" 같은 시간 구간을 다룬다.
+ */
+const BLOCK = z.object({
+  kind: z
+    .enum(['date', 'daily', 'weekly'])
+    .describe('date = that one day · daily = every day · weekly = every week on that weekday.'),
+  date: z.string().optional().describe('kind="date": the day, "YYYY-MM-DD".'),
+  weekday: z.number().optional().describe(`kind="weekly": which day. ${WEEKDAY_HINT}`),
+  start: z.string().optional().describe('"HH:mm". Leave out to block from the start of the day.'),
+  end: z.string().optional().describe('"HH:mm". Leave out to block until the end of the day.'),
+  label: z
+    .string()
+    .optional()
+    .describe('Your own note (e.g. "lunch"). Only the owner sees it — visitors never do.'),
+});
+
+const GOOGLE_SCHEMA = z.object({
+  connectionId: z
+    .string()
+    .describe('Connection id from rootr_list_google_calendars. The connection belongs to ONE person.'),
+  busyCalendarIds: z
+    .array(z.string())
+    .optional()
+    .describe('Calendars whose busy times block bookings. Only free/busy is read — never event titles.'),
+  writeCalendarId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe('Calendar that receives confirmed bookings. null = do not write anything to Google.'),
+  meet: z
+    .boolean()
+    .optional()
+    .describe(
+      'Also create a Google Meet room on each booking. Needs writeCalendarId. No extra permission is needed. ' +
+        'Rootr puts the link in a "회의 링크" column (created for you) and in both confirmation emails.',
+    ),
+});
+
+export function registerBookingTools(server) {
+  server.registerTool(
+    'rootr_get_booking',
+    {
+      title: 'Read a table\'s visitor-booking settings',
+      description:
+        'Read the visitor booking (scheduling) setup of a Rootr (루터) DATABASE: whether it is on, the rules ' +
+        '(days, hours, slot length, gap, notice, how far ahead, per-day cap, days off, blocked times, timezone), whether bookings ' +
+        'are confirmed instantly or after approval, who gets notified by email, whether a Google Meet room is created, ' +
+        'which columns visitors are asked for, and which Google Calendar ' +
+        'account/calendars are wired up. Also reports whether the table is published (booking only works on a ' +
+        'published table) and whether any booking failed to reach Google. Use this before changing anything.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe(`DATABASE node id${NODE_TARGET_HINT}`),
+      },
+    },
+    async ({ target }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, target);
+        return jsonResult(await client.getBooking(id));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_set_booking',
+    {
+      title: 'Turn on / configure visitor booking on a table',
+      description:
+        'Turn a published Rootr (루터) DATABASE into a booking page and set its rules. Visitors open the public ' +
+        'link, pick a date, pick an open time, and their booking lands as ONE ROW in the table. ' +
+        'ONLY the fields you pass change; everything else is left alone. ' +
+        'The table must be published first (rootr_publish_node) — otherwise this returns an error saying so. ' +
+        'Columns you do not have are CREATED for you: a date column, an email column, and (for approval mode) a ' +
+        'status column with 승인 대기/확정/거절. ' +
+        'Visitors never see other people\'s bookings: rows are stripped from the public payload and cloning is ' +
+        'blocked while booking is on. Two people clicking the same slot: only one gets it. ' +
+        'Google Calendar is OPTIONAL — pass `google` only after rootr_list_google_calendars shows a connection ' +
+        '(picking a connection requires a human account, not a bare API key).',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe(`DATABASE node id${NODE_TARGET_HINT}`),
+        enabled: z.boolean().optional().describe('Turn visitor booking on or off.'),
+        weekdays: z.array(z.number()).optional().describe(`Days that accept bookings. ${WEEKDAY_HINT}`),
+        startTime: z.string().optional().describe('First bookable time, "HH:mm" (e.g. "10:00"). Owner timezone.'),
+        endTime: z.string().optional().describe('Last bookable time ends by this, "HH:mm" (e.g. "18:00").'),
+        durationMin: z
+          .number()
+          .optional()
+          .describe('Length of one booking in minutes: 15, 20, 30, 45, 60, 90, 120, 180 or 240.'),
+        bufferMin: z.number().optional().describe('Gap kept before AND after each booking, in minutes.'),
+        minNoticeHours: z.number().optional().describe('No bookings closer than this many hours from now.'),
+        maxDaysAhead: z.number().optional().describe('How far ahead visitors may book, in days.'),
+        maxPerDay: z.number().optional().describe('Max bookings per day. 0 = unlimited.'),
+        blockedDates: z
+          .array(z.string())
+          .optional()
+          .describe('Days off, "YYYY-MM-DD". A date-only entry already in the table also blocks that day.'),
+        blockedTimes: z
+          .array(BLOCK)
+          .optional()
+          .describe(
+            'Times that stay closed inside the open hours. Replaces the whole list — send every rule you want kept. ' +
+              'Leave out both times to block the whole day: {"kind":"weekly","weekday":5} closes every Friday. ' +
+              'Examples: one afternoon {"kind":"date","date":"2026-10-05","start":"13:00","end":"15:00"}; ' +
+              'lunch every day {"kind":"daily","start":"12:00","end":"13:00"}; ' +
+              'Monday mornings {"kind":"weekly","weekday":1,"start":"09:00","end":"11:00"}.',
+          ),
+        timezone: z.string().optional().describe('IANA timezone the rules and the visitor page use (e.g. "Asia/Seoul").'),
+        approval: z
+          .enum(['instant', 'manual'])
+          .optional()
+          .describe(
+            'instant = confirmed the moment the visitor books (and written to Google right away). ' +
+              'manual = arrives as "승인 대기"; it still HOLDS the slot, and you confirm or decline in the table.',
+          ),
+        notice: z.string().optional().describe('Short note shown at the top of the visitor page.'),
+        askFields: z
+          .array(ASK_FIELD)
+          .optional()
+          .describe(
+            'Extra columns to ask the visitor for. Name and email are ALWAYS asked, so do not list them. ' +
+              'Only text/number/select/multi_select/checkbox/url/email/phone columns can be asked.',
+          ),
+        google: GOOGLE_SCHEMA.optional().describe('Google Calendar wiring. Omit to leave it untouched.'),
+        notifyVisitor: z
+          .boolean()
+          .optional()
+          .describe('Email the visitor when their booking is confirmed, still pending, or declined. On by default.'),
+        allowVisitorCancel: z
+          .boolean()
+          .optional()
+          .describe(
+            'Put a cancel link in the visitor\'s email so they can cancel without an account. ' +
+              'The link is a secret only that one booking\'s email carries. On by default; turning it off also ' +
+              'refuses links already sent.',
+          ),
+        types: z
+          .array(
+            z.object({
+              id: z.string().optional().describe('Short label used in the ?type= link. Derived from the name when omitted.'),
+              name: z.string(),
+              durationMin: z.number().int(),
+              description: z.string().optional(),
+            }),
+          )
+          .optional()
+          .describe(
+            'Several kinds of appointment at ONE address, e.g. a 15-minute call and a 60-minute demo. ' +
+              'Replaces the whole list; send [] for a single kind using durationMin. The visitor picks one before ' +
+              'the calendar appears, and ?type=<id> links straight to one. All kinds share the same busy time, ' +
+              'which is why this beats making one table per kind. A column records which kind was booked.',
+          ),
+        hosts: z
+          .array(
+            z.object({
+              id: z.string().optional(),
+              name: z.string(),
+              email: z.string(),
+              google: GOOGLE_SCHEMA.optional().nullable().describe("That host's own Google Calendar wiring, so their busy time blocks their slots."),
+            }),
+          )
+          .optional()
+          .describe(
+            'The people who take these appointments. Replaces the whole list; send [] to drop the idea of hosts. ' +
+              'A column records who got each booking, and each host is emailed their own bookings.',
+          ),
+        assign: z
+          .enum(['none', 'roundRobin', 'collective'])
+          .optional()
+          .describe(
+            'How the hosts are used. roundRobin: ONE host takes it — a slot is open when ANY host is free, and the ' +
+              'booking goes to whoever has taken the fewest so far. collective: EVERYONE joins — a slot is open only ' +
+              'when ALL hosts are free. none (default): no hosts. Ignored unless `hosts` is non-empty.',
+          ),
+        allowGuests: z
+          .boolean()
+          .optional()
+          .describe('Let the visitor add other email addresses. Guests get the same emails and the same calendar invite.'),
+        maxGuests: z.number().int().optional().describe('How many guests a visitor may add (default 5). 0 turns it off.'),
+        redirectUrl: z
+          .string()
+          .optional()
+          .describe(
+            'Where to send the visitor after they book — your own thank-you page. http/https only; anything else is ' +
+              'dropped. Empty keeps them on the Rootr confirmation screen.',
+          ),
+        allowVisitorReschedule: z
+          .boolean()
+          .optional()
+          .describe(
+            'Let the visitor move their booking to another time from the same emailed link, without an account. ' +
+              'One locked check picks the new slot, so there is no gap where someone else can take it. On by default.',
+          ),
+        reminders: z
+          .array(z.number().int())
+          .optional()
+          .describe(
+            'Minutes before the meeting to email both sides a reminder, e.g. [1440, 60] for a day and an hour before. ' +
+              'Up to 4 values; [] stops reminders. Defaults to [1440]. Only confirmed bookings are reminded, and a ' +
+              'reminder whose moment already passed when the booking was made is skipped instead of firing at once.',
+          ),
+        notifyEmails: z
+          .array(z.string())
+          .optional()
+          .describe(
+            'Who on the owner side gets an email for each new booking. Replaces the whole list; send [] to stop. ' +
+              'Defaults to the account that first set booking up.',
+          ),
+      },
+    },
+    async ({ target, askFields, ...rest }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, target);
+        const body = { ...rest };
+        if (askFields) {
+          // 칸 이름으로 골라도 받는다 — 사람도 에이전트도 칸 id 를 외우고 있지 않다.
+          const db = await client.getDatabase(id);
+          const props = db.properties || [];
+          const ids = new Set(props.map((p) => p.id));
+          const byName = new Map(props.map((p) => [p.name, p.id]));
+          body.askFields = askFields.map((a) => {
+            if (ids.has(a.propId)) return a;
+            const found = byName.get(a.propId);
+            if (!found) {
+              throw new Error(
+                `No column "${a.propId}" in this table. Columns: ${props.map((p) => p.name).join(', ')}`,
+              );
+            }
+            return { ...a, propId: found };
+          });
+        }
+        return jsonResult(await client.setBooking(id, body));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_booking_slots',
+    {
+      title: 'See the open times visitors see',
+      description:
+        'List the times a visitor could actually book on a Rootr (루터) booking page, day by day. This is the ' +
+        'SAME calculation the public page and the server use, so it is the way to check that the rules you set ' +
+        'do what you meant — including which days are closed and which times the owner\'s Google Calendar blocks. ' +
+        'Days with nothing open are omitted entirely. If Google Calendar is wired up but unreachable, this errors ' +
+        'rather than showing times that might already be taken.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        target: z.string().describe(`DATABASE node id${NODE_TARGET_HINT}`),
+        from: z.string().optional().describe('First day to look at, "YYYY-MM-DD". Defaults to today.'),
+        to: z.string().optional().describe('Last day, "YYYY-MM-DD". At most 62 days after `from`.'),
+        type: z
+          .string()
+          .optional()
+          .describe(
+            'Which kind of appointment to look at, when the page takes several (the `id` from `types`). Each kind ' +
+              'has its own length, so the open times differ. Omitted or unknown falls back to the first kind.',
+          ),
+      },
+    },
+    async ({ target, from, to, type }) => {
+      try {
+        const client = makeClient();
+        const id = await resolveNodeId(client, target);
+        const status = await client.nodePublicStatus(id);
+        if (!status.slug) {
+          throw new Error('This table is not published yet — publish it first (rootr_publish_node).');
+        }
+        const today = new Date(Date.now() + 9 * 3600e3).toISOString().slice(0, 10);
+        const start = from || today;
+        const end = to || new Date(Date.parse(`${start}T00:00:00Z`) + 30 * 864e5).toISOString().slice(0, 10);
+        return jsonResult(await client.bookingSlots(status.slug, { from: start, to: end, type }));
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_list_google_calendars',
+    {
+      title: 'List connected Google accounts and their calendars',
+      description:
+        'List the Google accounts this PERSON has connected to Rootr (루터) for booking, and — when you pass a ' +
+        'connectionId — the calendars on that account with whether each one can be written to. ' +
+        'Use the ids from here in rootr_set_booking `google`. ' +
+        'A Google connection belongs to one person, so this needs a human account: a bare API key (legacy or the ' +
+        'hosted MCP connector) gets a clear error instead of an empty list. If `available` is false, the server ' +
+        'itself has no Google setup yet and booking simply runs without Google.',
+      annotations: { readOnlyHint: true, destructiveHint: false },
+      inputSchema: {
+        connectionId: z
+          .string()
+          .optional()
+          .describe('Also list the calendars on this connection. Omit to just list the connected accounts.'),
+      },
+    },
+    async ({ connectionId }) => {
+      try {
+        const client = makeClient();
+        const connections = await client.googleCalendarConnections();
+        if (!connectionId) return jsonResult(connections);
+        const calendars = await client.googleCalendars(connectionId);
+        return jsonResult({ ...connections, ...calendars });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_connect_google_calendar',
+    {
+      title: 'Start connecting a Google Calendar account',
+      description:
+        'Get the Google consent URL to connect a Google Calendar account for booking. ' +
+        'You cannot finish this for the user: Google requires a PERSON to open that URL in a browser and approve ' +
+        'the calendar permissions once. Hand them the URL and say so. After they approve, everything else ' +
+        '(listing calendars, wiring them to a table) works through the tools. ' +
+        'Rootr asks only for: the list of their calendars, free/busy times, and permission to manage the events it ' +
+        'creates — never the contents of their existing events. Needs a human account, not a bare API key.',
+      annotations: { readOnlyHint: false, destructiveHint: false },
+      inputSchema: {
+        returnTo: z
+          .string()
+          .optional()
+          .describe('In-app path to come back to after approving, e.g. "/ko". Must start with "/".'),
+      },
+    },
+    async ({ returnTo }) => {
+      try {
+        const client = makeClient();
+        const res = await client.googleCalendarAuthorizeUrl(returnTo || '/');
+        return jsonResult({
+          ...res,
+          next: 'Ask the person to open `url` in a browser and approve. Then call rootr_list_google_calendars.',
+        });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    'rootr_disconnect_google_calendar',
+    {
+      title: 'Disconnect a Google Calendar account',
+      description:
+        'Disconnect a Google Calendar account from Rootr (루터) and revoke Rootr\'s access on Google\'s side. ' +
+        'Tables using that connection stop blocking busy times and stop writing new bookings to Google; bookings ' +
+        'already written stay in the calendar. Ask the person before doing this — it affects every table wired to ' +
+        'that account.',
+      annotations: { readOnlyHint: false, destructiveHint: true },
+      inputSchema: {
+        connectionId: z.string().describe('Connection id from rootr_list_google_calendars.'),
+      },
+    },
+    async ({ connectionId }) => {
+      try {
+        const client = makeClient();
+        await client.disconnectGoogleCalendar(connectionId);
+        return jsonResult({ ok: true, connectionId });
+      } catch (err) {
+        return errorResult(err);
+      }
+    },
+  );
+}