@ordinatio/scheduling-api 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,2541 +0,0 @@
1
- "use strict";
2
- var __defProp = Object.defineProperty;
3
- var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
4
- var __getOwnPropNames = Object.getOwnPropertyNames;
5
- var __hasOwnProp = Object.prototype.hasOwnProperty;
6
- var __export = (target, all) => {
7
- for (var name in all)
8
- __defProp(target, name, { get: all[name], enumerable: true });
9
- };
10
- var __copyProps = (to, from, except, desc) => {
11
- if (from && typeof from === "object" || typeof from === "function") {
12
- for (let key of __getOwnPropNames(from))
13
- if (!__hasOwnProp.call(to, key) && key !== except)
14
- __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
15
- }
16
- return to;
17
- };
18
- var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
19
-
20
- // src/agent/index.ts
21
- var agent_exports = {};
22
- __export(agent_exports, {
23
- SCHEDULING_AGENT_EXCLUDED: () => SCHEDULING_AGENT_EXCLUDED,
24
- SCHEDULING_AGENT_PENDING: () => SCHEDULING_AGENT_PENDING,
25
- SCHEDULING_AGENT_TOOLS: () => SCHEDULING_AGENT_TOOLS,
26
- createSchedulingAgentTools: () => createSchedulingAgentTools
27
- });
28
- module.exports = __toCommonJS(agent_exports);
29
-
30
- // src/agent/appointment-tools.ts
31
- var APPOINTMENT_FIELDS = "id, calendarId, calendarName, staffName, typeId, typeName, startTime, endTime, duration, timezone, status, clientName, clientEmail, clientPhone, intakeResponses, staffNotes, location, paymentId, paymentStatus, paymentAmount, depositAmount, paymentProvider, couponCode, discountAmount, isGroup, manageToken, createdAt";
32
- var STAFF_APPOINTMENT_FIELDS = "id, calendarId, calendarName, staffName, typeId, typeName, startTime, endTime, duration, timezone, status, clientName, clientEmail, clientPhone, intakeResponses, staffNotes, location, paymentId, paymentStatus, paymentAmount, depositAmount, paymentProvider, couponCode, discountAmount, isGroup, createdAt";
33
- var ID = { name: "id", type: "string", required: true, description: "Appointment id" };
34
- var APPOINTMENT_TOOLS = [
35
- {
36
- name: "scheduling_list_appointments",
37
- module: "scheduling",
38
- method: "GET",
39
- route: "/appointments",
40
- auth: "session_cookie",
41
- description: "List appointments, oldest first by start time, with optional filters. Only calendars the signed-in person may see are returned.",
42
- params: [
43
- { name: "calendarId", type: "string", required: false, description: "Only this calendar" },
44
- { name: "clientId", type: "string", required: false, description: "Only this client" },
45
- {
46
- name: "status",
47
- type: "string",
48
- required: false,
49
- description: "Only this status",
50
- allowedValues: ["PENDING", "CONFIRMED", "COMPLETED", "CANCELLED", "NO_SHOW"]
51
- },
52
- { name: "startDate", type: "string", required: false, description: "Earliest start, in UTC ending in Z" },
53
- { name: "endDate", type: "string", required: false, description: "Latest start, in UTC ending in Z" },
54
- { name: "limit", type: "number", required: false, description: "How many to return (default and maximum are set by the server)" }
55
- ],
56
- example: { status: "CONFIRMED", startDate: "2026-11-02T00:00:00Z", endDate: "2026-11-03T00:00:00Z" },
57
- responseShape: "{ appointments: [{ id, clientName, clientEmail, clientId, startTime, endTime, status, calendarId, calendarName, staffName, type: { id, name, color }, notes, staffNotes, location, meetingUrl, recurringId, recurringIndex }], total }",
58
- whenToUse: 'To answer "what is on today", "who is coming tomorrow" or "what did this client book".',
59
- pitfalls: ["Oldest first and capped by limit: to find the latest, narrow with startDate or raise limit.", "Without a clientId, only an admin may list; other roles get a 403."],
60
- dataSensitivity: "sensitive",
61
- risk: "observe"
62
- },
63
- {
64
- name: "scheduling_check_availability",
65
- module: "scheduling",
66
- method: "GET",
67
- route: "/availability",
68
- auth: "none",
69
- description: "List the start times on one calendar for one day. Use the slots whose available is true.",
70
- params: [
71
- { name: "calendarId", type: "string", required: true, description: "Calendar to check" },
72
- { name: "date", type: "string", required: true, description: "Day to check, YYYY-MM-DD" },
73
- { name: "typeId", type: "string", required: true, description: "Appointment type; its length decides which times fit" },
74
- { name: "timezone", type: "string", required: false, description: "IANA timezone that decides which calendar day `date` means; the times come back as UTC instants" },
75
- { name: "orgSlug", type: "string", required: false, description: "Organization slug, for hosts that serve several" }
76
- ],
77
- example: { calendarId: "cal_1", date: "2026-11-03", typeId: "type_1", timezone: "America/New_York" },
78
- responseShape: "{ date, calendarId, slots: [{ start, end, available }], timezone }",
79
- whenToUse: "Before booking or moving an appointment, to see which times are really free.",
80
- dataSensitivity: "internal",
81
- risk: "observe"
82
- },
83
- {
84
- name: "scheduling_check_team_availability",
85
- module: "scheduling",
86
- method: "GET",
87
- route: "/availability/team",
88
- auth: "none",
89
- description: "List the free start times for a team appointment type: a time is free if any calendar in the team has it open.",
90
- params: [
91
- { name: "typeId", type: "string", required: true, description: "A team appointment type" },
92
- { name: "date", type: "string", required: true, description: "Day to check, YYYY-MM-DD" },
93
- { name: "timezone", type: "string", required: false, description: "IANA timezone that decides which calendar day `date` means; the times come back as UTC instants" },
94
- { name: "orgSlug", type: "string", required: false, description: "Organization slug, for hosts that serve several" }
95
- ],
96
- example: { typeId: "type_team", date: "2026-11-03" },
97
- responseShape: "{ date, slots: [{ start, end, available, seatsTotal?, seatsBooked?, seatsAvailable? }], timezone }",
98
- whenToUse: "For appointment types that rotate between several staff members.",
99
- pitfalls: ["A calendar that fails to load is left out rather than failing the whole answer.", "A type that is not a team type is refused with 400; use the single-calendar availability tool."],
100
- dataSensitivity: "internal",
101
- risk: "observe"
102
- },
103
- {
104
- name: "scheduling_list_appointment_types",
105
- module: "scheduling",
106
- method: "GET",
107
- route: "/appointment-types",
108
- auth: "none",
109
- description: "List the appointment types a calendar offers, with length, price, deposit and intake questions.",
110
- params: [
111
- { name: "calendarSlug", type: "string", required: true, description: "Slug of the calendar" },
112
- { name: "orgSlug", type: "string", required: false, description: "Organization slug, for hosts that serve several" }
113
- ],
114
- example: { calendarSlug: "front-desk" },
115
- responseShape: "[{ id, name, slug, duration, price, deposit, requiresPayment, assignmentStrategy, isGroup, maxSeats, intakeForm, calendars? }]",
116
- whenToUse: "To find the typeId needed for booking or checking availability.",
117
- dataSensitivity: "none",
118
- risk: "observe"
119
- },
120
- {
121
- name: "scheduling_check_capacity",
122
- module: "scheduling",
123
- method: "GET",
124
- route: "/appointments/capacity",
125
- auth: "none",
126
- description: "For a group appointment type, say how many seats are left at one start time.",
127
- params: [
128
- { name: "typeId", type: "string", required: true, description: "A group appointment type" },
129
- { name: "calendarId", type: "string", required: true, description: "Calendar the session is on" },
130
- { name: "startTime", type: "string", required: true, description: "Session start, in UTC ending in Z" }
131
- ],
132
- example: { typeId: "type_group", calendarId: "cal_1", startTime: "2026-11-03T15:00:00Z" },
133
- responseShape: "{ seatsTotal, seatsBooked, seatsAvailable, isFull }; seatsTotal and seatsAvailable are null when the type has no seat limit",
134
- pitfalls: ["A type that is not a group type, or a calendar not offering it, gets a 404."],
135
- whenToUse: "Before booking someone into a group session.",
136
- dataSensitivity: "none",
137
- risk: "observe"
138
- },
139
- {
140
- name: "scheduling_list_appointment_notifications",
141
- module: "scheduling",
142
- method: "GET",
143
- route: "/appointments/[id]/notifications",
144
- auth: "session_cookie",
145
- description: "List the confirmation and reminder messages queued or sent for one appointment.",
146
- params: [ID],
147
- example: { id: "appt_1" },
148
- responseShape: "{ notifications: [...] }",
149
- whenToUse: "To check whether a client was told about their appointment.",
150
- dataSensitivity: "sensitive",
151
- risk: "observe"
152
- },
153
- {
154
- name: "scheduling_book_appointment",
155
- module: "scheduling",
156
- method: "POST",
157
- route: "/appointments",
158
- auth: "none",
159
- description: "Book an appointment for a client. Checks the slot is free and applies any coupon or package. The client gets a confirmation, or a request-received notice when the type needs staff approval and the booking starts as PENDING.",
160
- params: [
161
- { name: "typeId", type: "string", required: true, description: "Appointment type" },
162
- { name: "startTime", type: "string", required: true, description: "Start in UTC, ISO 8601 ending in Z (an offset such as -05:00 is refused)" },
163
- { name: "clientName", type: "string", required: true, description: "Client full name" },
164
- { name: "clientEmail", type: "string", required: true, description: "Client email address" },
165
- { name: "calendarId", type: "string", required: false, description: "Calendar to book; leave out for a team type so the rotation picks" },
166
- { name: "preferredCalendarId", type: "string", required: false, description: "For a team type, the calendar to try first" },
167
- { name: "timezone", type: "string", required: false, description: "IANA timezone of the client" },
168
- { name: "clientPhone", type: "string", required: false, description: "Client phone number" },
169
- { name: "clientId", type: "string", required: false, description: "Existing client record; only a hint, the host decides whether to honour it" },
170
- { name: "notes", type: "string", required: false, description: "Notes, up to 1000 characters" },
171
- { name: "intakeResponses", type: "json-object", required: false, description: `A JSON object of answers to the type's intake questions, keyed by field name, for example {"allergies":"none"}; values are text, numbers or true/false` },
172
- { name: "paymentId", type: "string", required: false, description: "A payment already taken for this booking" },
173
- { name: "couponCode", type: "string", required: false, description: "Coupon code" },
174
- { name: "packagePurchaseId", type: "string", required: false, description: "Prepaid package to draw a session from" },
175
- { name: "orgSlug", type: "string", required: false, description: "Organization slug, for hosts that serve several; leave out unless told" }
176
- ],
177
- example: {
178
- typeId: "type_1",
179
- startTime: "2026-11-03T20:00:00Z",
180
- clientName: "Jane Smith",
181
- clientEmail: "jane@example.com",
182
- calendarId: "cal_1"
183
- },
184
- responseShape: `{ ${APPOINTMENT_FIELDS}, meetingUrl, icalUrl }`,
185
- whenToUse: "When a person asks to book a client in. Check availability first.",
186
- pitfalls: [
187
- "A slot taken a moment ago returns 409 with code SLOT_UNAVAILABLE; check availability again and offer another time.",
188
- "This is the public booking route: by default it allows only five booking requests an hour from one address (more get 429), takes no staff sign-in and does not apply the signed-in person's calendar visibility.",
189
- "A type that requires payment is refused unless a payment already verified with the payment provider is passed as paymentId; an agent cannot create one, so it cannot book paid types.",
190
- "Coupon codes, packages and payment ids are checked by the server, not trusted as given; a coupon has no effect on a free type.",
191
- "The answer holds the client's private manage and calendar links; never repeat them in a message.",
192
- "A type with no team needs calendarId; leave it out only for a team type."
193
- ],
194
- dataSensitivity: "sensitive",
195
- risk: "act",
196
- requiresApproval: {
197
- action: "Book an appointment",
198
- reason: "A booking commits a staff member's time and sends the client a confirmation.",
199
- prompt: "Book {clientName} at {startTime} (UTC)?"
200
- }
201
- },
202
- {
203
- name: "scheduling_cancel_appointment",
204
- module: "scheduling",
205
- method: "POST",
206
- route: "/appointments/[id]/cancel",
207
- auth: "session_cookie",
208
- description: "Cancel an appointment as staff. The calendar entry is removed, the staff member is notified and a paid booking is flagged for refund review. This route does not message the client itself; the host may send a notice when it hears the appointment.cancelled event.",
209
- params: [ID, { name: "reason", type: "string", required: false, description: "Why, up to 500 characters; stored as the cancellation reason" }],
210
- example: { id: "appt_1", reason: "Staff member is unwell" },
211
- responseShape: `{ ${STAFF_APPOINTMENT_FIELDS} } with status "CANCELLED"`,
212
- pitfalls: ["Staff can cancel even after the type's client cancellation deadline; those limits apply only to the client's own link. Refused with 409 only when the appointment is no longer pending or confirmed."],
213
- whenToUse: "When staff, not the client, ends the booking.",
214
- dataSensitivity: "sensitive",
215
- risk: "act",
216
- requiresApproval: {
217
- action: "Cancel an appointment",
218
- reason: "Cancelling frees the staff member's time and may leave a paid booking waiting for a refund decision.",
219
- prompt: "Cancel appointment {id}?"
220
- }
221
- },
222
- {
223
- name: "scheduling_reschedule_appointment",
224
- module: "scheduling",
225
- method: "POST",
226
- route: "/appointments/[id]/reschedule",
227
- auth: "session_cookie",
228
- description: "Move an appointment to a new start time on the same calendar. The client is sent a reschedule notice and their reminders are redone for the new time.",
229
- params: [ID, { name: "newStartTime", type: "string", required: true, description: "New start in UTC, ending in Z; a time with no zone is read in the server's own zone and lands in the wrong place" }],
230
- example: { id: "appt_1", newStartTime: "2026-11-04T16:00:00Z" },
231
- responseShape: `{ ${STAFF_APPOINTMENT_FIELDS} }`,
232
- whenToUse: "When a time change was asked for. Check availability for the new time first.",
233
- pitfalls: ["A time that is taken, a time in the past, an appointment that has already started, a type that does not allow moving, or a change made at the same moment by someone else, is refused."],
234
- dataSensitivity: "sensitive",
235
- risk: "act",
236
- requiresApproval: {
237
- action: "Reschedule an appointment",
238
- reason: "Moving an appointment changes what the client and staff member have planned.",
239
- prompt: "Move appointment {id} to {newStartTime}?"
240
- }
241
- },
242
- {
243
- name: "scheduling_decide_pending_appointment",
244
- module: "scheduling",
245
- method: "POST",
246
- route: "/appointments/[id]/approve",
247
- auth: "session_cookie",
248
- description: "Approve or reject an appointment that is waiting for staff approval. Approving confirms it and sets up its reminders. Rejecting cancels it and flags a paid one for refund review; the route does not message the client about a rejection itself.",
249
- params: [
250
- ID,
251
- { name: "approved", type: "boolean", required: true, description: "true to approve, false to reject" },
252
- { name: "reason", type: "string", required: false, description: "Why; recorded with the decision" }
253
- ],
254
- example: { id: "appt_1", approved: true },
255
- responseShape: '{ success: true, status: "CONFIRMED" | "CANCELLED", appointment }',
256
- whenToUse: "For appointments with status PENDING.",
257
- pitfalls: ["Only PENDING appointments can be decided."],
258
- dataSensitivity: "sensitive",
259
- risk: "act",
260
- requiresApproval: {
261
- action: "Approve or reject an appointment request",
262
- reason: "A decision changes the booking's status and a rejection cannot be taken back.",
263
- prompt: "Record the decision on appointment {id}: approved = {approved}. A rejection cancels the booking and cannot be undone. Continue?"
264
- }
265
- },
266
- {
267
- name: "scheduling_reassign_appointment",
268
- module: "scheduling",
269
- method: "PATCH",
270
- route: "/appointments/[id]/reassign",
271
- auth: "session_cookie",
272
- description: "Hand an appointment to a different calendar, which means a different staff member, at the same time.",
273
- params: [ID, { name: "calendarId", type: "string", required: true, description: "Calendar to move it to" }],
274
- example: { id: "appt_1", calendarId: "cal_2" },
275
- responseShape: "{ id, calendarId, typeId, startTime, endTime, duration, timezone, clientName, clientEmail, clientPhone, status, staffNotes, location, paymentStatus, createdAt, updatedAt } (the stored record without the client's private manage token)",
276
- whenToUse: "When a different person should take the appointment.",
277
- pitfalls: ["Admin roles only. Only pending or confirmed appointments, and not group sessions. The new calendar must be in the appointment type's team and free at that time; otherwise it is refused."],
278
- dataSensitivity: "sensitive",
279
- risk: "act",
280
- requiresApproval: {
281
- action: "Reassign an appointment",
282
- reason: "The appointment moves to another staff member's calendar.",
283
- prompt: "Move appointment {id} to calendar {calendarId}?"
284
- }
285
- },
286
- {
287
- name: "scheduling_mark_no_show",
288
- module: "scheduling",
289
- method: "POST",
290
- route: "/appointments/[id]/no-show",
291
- auth: "session_cookie",
292
- description: "Record that the client did not come.",
293
- params: [ID],
294
- example: { id: "appt_1" },
295
- responseShape: `{ ${STAFF_APPOINTMENT_FIELDS} } with status "NO_SHOW"`,
296
- whenToUse: "After the start time has passed and the client did not arrive.",
297
- pitfalls: ["Refused with 409 unless the appointment is pending or confirmed and its start time has passed."],
298
- dataSensitivity: "sensitive",
299
- risk: "act",
300
- requiresApproval: {
301
- action: "Mark an appointment as a no-show",
302
- reason: "The status changes to a no-show and appears in the client's history.",
303
- prompt: "Mark appointment {id} as a no-show?"
304
- }
305
- },
306
- {
307
- name: "scheduling_send_followup",
308
- module: "scheduling",
309
- method: "POST",
310
- route: "/appointments/[id]/followup",
311
- auth: "session_cookie",
312
- description: "Queue a thank-you message to the client after their appointment: always by email, and by text too when a phone number is on file.",
313
- params: [ID],
314
- example: { id: "appt_1" },
315
- responseShape: "{ success: true }",
316
- whenToUse: "After an appointment has ended.",
317
- pitfalls: ["Refused before the appointment ends, and for cancelled or no-show appointments.", "The message is queued for sending, not sent in the same instant.", "A repeat call replaces a manual message that is still waiting to go out."],
318
- dataSensitivity: "sensitive",
319
- risk: "act",
320
- requiresApproval: {
321
- action: "Send a follow-up message",
322
- reason: "The message goes to the client in the business's name.",
323
- prompt: "Send a follow-up to the client of appointment {id}?"
324
- }
325
- },
326
- {
327
- name: "scheduling_send_reminder",
328
- module: "scheduling",
329
- method: "POST",
330
- route: "/appointments/[id]/remind",
331
- auth: "session_cookie",
332
- description: "Queue a reminder to the client about an appointment for immediate sending: always by email, and by text too when a phone number is on file.",
333
- params: [ID],
334
- example: { id: "appt_1" },
335
- responseShape: "{ success: true }",
336
- whenToUse: "When a client needs an extra nudge before the regular reminder.",
337
- pitfalls: ["Does not check the status: do not send it for a cancelled appointment.", "A repeat call replaces a manual message that is still waiting to go out."],
338
- dataSensitivity: "sensitive",
339
- risk: "act",
340
- requiresApproval: {
341
- action: "Send a reminder message",
342
- reason: "The message goes to the client in the business's name.",
343
- prompt: "Send a reminder to the client of appointment {id}?"
344
- }
345
- },
346
- {
347
- name: "scheduling_update_appointment_notes",
348
- module: "scheduling",
349
- method: "PATCH",
350
- route: "/appointments/[id]/notes",
351
- auth: "session_cookie",
352
- description: "Replace the private staff notes on an appointment. An empty string clears them.",
353
- params: [ID, { name: "notes", type: "string", required: true, description: "New notes, up to 5000 characters; send an empty string to clear them" }],
354
- example: { id: "appt_1", notes: "Prefers mornings. Bring the signed form." },
355
- responseShape: "{ success: true }",
356
- whenToUse: "To record what staff should remember. The client never sees these.",
357
- pitfalls: ["This replaces the existing notes; read them first and include what should stay."],
358
- dataSensitivity: "sensitive",
359
- risk: "act",
360
- requiresApproval: {
361
- action: "Change appointment notes",
362
- reason: "The old notes are replaced.",
363
- prompt: "Replace the notes on appointment {id}?"
364
- }
365
- },
366
- {
367
- name: "scheduling_update_appointment_location",
368
- module: "scheduling",
369
- method: "PATCH",
370
- route: "/appointments/[id]/location",
371
- auth: "session_cookie",
372
- description: "Change where an appointment takes place (an address or a video link). An empty string clears it. When the appointment is linked to a client record, the new place is also remembered as that client's preferred location.",
373
- params: [ID, { name: "location", type: "string", required: true, description: "New location, up to 500 characters; send an empty string to clear it" }],
374
- example: { id: "appt_1", location: "100 Main Street, Springfield" },
375
- responseShape: "{ success: true }",
376
- whenToUse: "When the meeting place changes.",
377
- pitfalls: ["For a temporary one-off address this still updates the client's saved preferred location."],
378
- dataSensitivity: "sensitive",
379
- risk: "act",
380
- requiresApproval: {
381
- action: "Change appointment location",
382
- reason: "The place changes on this appointment and, for a linked client, is saved as their preferred location for future bookings.",
383
- prompt: "Change the location of appointment {id}?"
384
- }
385
- },
386
- {
387
- name: "scheduling_collect_balance",
388
- module: "scheduling",
389
- method: "POST",
390
- route: "/appointments/[id]/collect-balance",
391
- auth: "session_cookie",
392
- description: "Start a payment for the unpaid part of an appointment after a deposit was taken.",
393
- params: [ID],
394
- example: { id: "appt_1" },
395
- responseShape: "{ clientSecret, paymentIntentId, amount (in cents), currency, depositPaid (in dollars), totalPrice (in dollars) }",
396
- whenToUse: "When a deposit was paid and the rest is due.",
397
- pitfalls: [
398
- "Only works when a deposit was paid and a balance remains.",
399
- "The answer holds a payment secret meant for the client's own browser; never repeat it in a message.",
400
- "It only starts the payment; the client still has to complete it.",
401
- "The approval request shows only the appointment id: say whose appointment and what amount in your own message first."
402
- ],
403
- dataSensitivity: "critical",
404
- risk: "govern",
405
- requiresApproval: {
406
- action: "Collect the balance for an appointment",
407
- reason: "This opens a payment for the client to complete.",
408
- prompt: "Start a payment for the remaining balance on appointment {id}?"
409
- }
410
- },
411
- {
412
- name: "scheduling_resolve_refund",
413
- module: "scheduling",
414
- method: "POST",
415
- route: "/appointments/[id]/resolve-refund",
416
- auth: "session_cookie",
417
- description: 'Settle a cancelled, paid appointment. "refund" sends the money back through the payment provider. "credit" only records that a credit was handled outside this system (a gift card, say); no credit is created or tracked here.',
418
- params: [
419
- ID,
420
- { name: "action", type: "string", required: true, description: "How to settle it", allowedValues: ["refund", "credit"] }
421
- ],
422
- example: { id: "appt_1", action: "refund" },
423
- responseShape: "{ refundStatus, action }, where refundStatus is REFUNDED or CREDIT_ISSUED (done), or REFUND_FAILED or PARTIAL_REFUND (not finished; can be tried again)",
424
- whenToUse: 'For a cancelled appointment flagged "refund pending".',
425
- pitfalls: ["Owners, admins and managers only.", "The approval request shows only the appointment id: say whose appointment and what amount in your own message first.", 'A 200 answer is not proof it worked: only REFUNDED or CREDIT_ISSUED mean done. REFUND_FAILED and PARTIAL_REFUND mean unfinished; tell the person, and finish with another "refund" call ("credit" is refused once a partial refund exists).', "Money may already have moved if a call fails part-way; check the appointment before trying again."],
426
- dataSensitivity: "critical",
427
- risk: "govern",
428
- requiresApproval: {
429
- action: "Resolve a refund",
430
- reason: "A refund moves money back to the client and cannot be undone; a credit is only recorded, not created.",
431
- prompt: "Resolve the refund on appointment {id} as {action}?"
432
- }
433
- }
434
- ];
435
-
436
- // src/agent/analytics-tools.ts
437
- var ANALYTICS_TOOLS = [
438
- {
439
- name: "scheduling_get_booking_analytics",
440
- module: "scheduling",
441
- method: "GET",
442
- route: "/analytics",
443
- auth: "session_cookie",
444
- description: "Booking figures for the last few days: how many were booked, completed, cancelled, no-shows and pending, the rates, what was paid, the busiest hours and days, and a trend per day.",
445
- params: [
446
- { name: "days", type: "number", required: false, description: "How many days back to look, a whole number from 1 to 365; 30 if left out" },
447
- { name: "calendarId", type: "string", required: false, description: "Only this calendar" }
448
- ],
449
- example: { days: 30 },
450
- responseShape: "{ period: { start, end, days }, totals: { booked, completed, cancelled, noShows, pending }, rates: { completionRate, cancellationRate, noShowRate }, revenue: { total, avg, currency }, peakHours: [{ hour, count }], peakDays: [{ dayOfWeek, count }], heatmap: [{ dayOfWeek, hour, count }], byType: [{ typeId, typeName, count, color, totalRevenue, avgRevenue }], dailyTrend: [{ date, count }], funnel: [{ stage, count }] }",
451
- whenToUse: "To answer how busy the business is, how many people cancel or do not turn up, and which services book most.",
452
- pitfalls: [
453
- "It counts bookings whose start time falls between the start of the first day and now, so bookings still to come are not included.",
454
- "Rates are whole percentages of the booked total. confirmed in the funnel is booked minus cancelled and pending.",
455
- "Hours and days are counted in UTC, not the calendar's own time zone.",
456
- "revenue adds up the payment amount of every booking in the period that has one, whatever its status, so a cancelled booking that was paid is counted. The amounts are in the same units the payments were recorded in, and currency always says usd whatever was charged; avg is rounded to a whole number.",
457
- "Only for admin roles: others are refused with 403. A calendar of another organization, or one the person may not see, is a plain 404. days outside 1 to 365, or not a number, is refused with 400.",
458
- "A server that has switched analytics off answers 503."
459
- ],
460
- dataSensitivity: "internal",
461
- risk: "observe"
462
- }
463
- ];
464
-
465
- // src/agent/availability-tools.ts
466
- var CALENDAR_ID = { name: "calendarId", type: "string", required: true, description: "Calendar id" };
467
- var RULE_FIELDS = "id, calendarId, dayOfWeek, startTime, endTime, specificDate, isBlocked, blockReason, maxPerDay, bufferBefore, bufferAfter, minNotice, maxAdvanceBooking, createdAt";
468
- var WEEKLY_RULE = "A list with one object per open day. Each object has dayOfWeek (a whole number from 0 (Sunday) to 6 (Saturday); each day at most once), startTime and endTime (HH:MM on a 24-hour clock, startTime before endTime), and optionally bufferBefore and bufferAfter (minutes kept free around a booking, 0 to 120; 0 and 15 if left out), minNotice (minutes of warning needed before a booking, 0 to 10080; 60 if left out), maxAdvanceBooking (how many days ahead clients may book, 1 to 365; 60 if left out) and maxPerDay (most bookings in the day, a whole number of 1 or more, or null for no limit; no limit if left out).";
469
- var AVAILABILITY_TOOLS = [
470
- {
471
- name: "scheduling_list_availability_rules",
472
- module: "scheduling",
473
- method: "GET",
474
- route: "/admin/availability/[calendarId]",
475
- auth: "session_cookie",
476
- description: "List the opening hours of one calendar: the weekly rules (they have a dayOfWeek) and the exceptions for single dates (they have a specificDate).",
477
- params: [
478
- CALENDAR_ID,
479
- { name: "limit", type: "number", required: false, description: "How many rules to return (default 200, at most 500)" },
480
- { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
481
- ],
482
- example: { calendarId: "cal_1" },
483
- responseShape: `{ rules: [{ ${RULE_FIELDS} }], total, hasMore }`,
484
- whenToUse: "Before changing the hours, to see what is set now, and to find the ruleId of an exception to remove.",
485
- pitfalls: [
486
- "A blocked whole day is an exception with isBlocked true and startTime and endTime both 00:00; a blocked part of a day has real times.",
487
- "A calendar of another organization, or one the person may not see, is a plain 404."
488
- ],
489
- dataSensitivity: "internal",
490
- risk: "observe"
491
- },
492
- {
493
- name: "scheduling_set_weekly_availability",
494
- module: "scheduling",
495
- method: "PUT",
496
- route: "/admin/availability/[calendarId]",
497
- auth: "session_cookie",
498
- description: "Set the weekly opening hours of a calendar. This replaces every weekly rule the calendar has now with the list you send.",
499
- params: [
500
- CALENDAR_ID,
501
- { name: "rules", type: "json-array", required: true, description: WEEKLY_RULE }
502
- ],
503
- example: {
504
- calendarId: "cal_1",
505
- rules: [
506
- { dayOfWeek: 1, startTime: "09:00", endTime: "17:00" },
507
- { dayOfWeek: 2, startTime: "09:00", endTime: "17:00", bufferAfter: 10, maxPerDay: 8 }
508
- ]
509
- },
510
- responseShape: `[{ ${RULE_FIELDS} }]`,
511
- whenToUse: "To give a new calendar its opening hours, or to change them. Send the whole week every time.",
512
- pitfalls: [
513
- "Days not listed become closed. To keep a day as it is, send it again.",
514
- "An empty list does not close the calendar: a calendar with no weekly hours and no custom-hours exception is open around the clock. To stop bookings, block dates or switch the appointment types off.",
515
- "Date exceptions are kept; only the weekly rules are replaced.",
516
- "Times are in the time zone of the calendar.",
517
- "The buffers, notice, advance limit and daily limit are part of each day, so a day sent without them goes back to the defaults.",
518
- "A runner that cannot offer a list of objects to the model cannot use this tool."
519
- ],
520
- dataSensitivity: "internal",
521
- risk: "act",
522
- requiresApproval: {
523
- action: "Set weekly opening hours",
524
- reason: "The hours decide which times clients can book; days left out stop taking bookings, and an empty list opens the calendar around the clock.",
525
- prompt: "Replace the weekly opening hours of calendar {calendarId}?"
526
- }
527
- },
528
- {
529
- name: "scheduling_add_availability_exception",
530
- module: "scheduling",
531
- method: "POST",
532
- route: "/admin/availability/[calendarId]",
533
- auth: "session_cookie",
534
- description: "Add an exception for one date: close the whole day, block part of a day, or open custom hours that day.",
535
- params: [
536
- CALENDAR_ID,
537
- { name: "date", type: "string", required: true, description: "The date, YYYY-MM-DD" },
538
- { name: "isBlocked", type: "boolean", required: false, description: "true blocks time (true if left out); false opens custom hours that day, 09:00 to 17:00 unless startTime and endTime say otherwise" },
539
- { name: "startTime", type: "string", required: false, description: "HH:MM on a 24-hour clock. With isBlocked true, together with endTime, it blocks only that part of the day; with isBlocked false it is when the custom hours begin" },
540
- { name: "endTime", type: "string", required: false, description: "HH:MM on a 24-hour clock, after startTime" },
541
- { name: "blockReason", type: "string", required: false, description: "A short note for staff, up to 500 characters" }
542
- ],
543
- example: { calendarId: "cal_1", date: "2026-12-24", isBlocked: true, blockReason: "Holiday" },
544
- responseShape: `{ ${RULE_FIELDS}, warning? }`,
545
- whenToUse: "For a holiday, a meeting, a short day or a special opening. Use scheduling_set_weekly_availability for the regular week.",
546
- pitfalls: [
547
- "Leave startTime and endTime out to close the whole day.",
548
- "Closing the whole day or opening custom hours replaces every exception already set for that date, part-day blocks included. A part-day block is added next to the others.",
549
- "Times are in the time zone of the calendar.",
550
- "Blocking part of a day does not cancel bookings already in it; a warning says how many overlap, if any.",
551
- "On a calendar that has no weekly hours at all, a part-day block closes that whole day instead of leaving the rest of it open.",
552
- "On a calendar that has no weekly hours at all, the first custom-hours exception (isBlocked false) closes every other day, which until then were open around the clock. Set the weekly hours first.",
553
- "A part-day block in the past, one that overlaps another block that day, or a 21st block on the same day is refused with 400.",
554
- "Send both startTime and endTime or neither: with isBlocked true and only one of them, the whole day is closed and the time is ignored."
555
- ],
556
- dataSensitivity: "internal",
557
- risk: "act",
558
- requiresApproval: {
559
- action: "Add an availability exception",
560
- reason: "Closing or opening time on a date changes which times clients can book.",
561
- prompt: "Add an exception for {date} on calendar {calendarId}?"
562
- }
563
- },
564
- {
565
- name: "scheduling_remove_availability_exception",
566
- module: "scheduling",
567
- method: "DELETE",
568
- route: "/admin/availability/[calendarId]",
569
- auth: "session_cookie",
570
- description: "Remove one date exception, which gives that day or time back to the normal weekly hours.",
571
- params: [
572
- CALENDAR_ID,
573
- { name: "ruleId", type: "string", required: true, description: "Id of the exception, from scheduling_list_availability_rules" }
574
- ],
575
- example: { calendarId: "cal_1", ruleId: "rule_1" },
576
- responseShape: "{ success: true }",
577
- whenToUse: "When a holiday or block was added by mistake or no longer applies. Find the id with scheduling_list_availability_rules.",
578
- pitfalls: [
579
- "Use only an id whose rule has a specificDate. The route does not check, so the id of a weekly rule is deleted too, and that weekday is closed.",
580
- "An id that is not on this calendar is a 404.",
581
- "Removing the last weekly rule leaves the calendar with no weekly hours. With no custom-hours exception either, it is then open around the clock, not closed; with one, only the dates of its custom hours are open and every other day is closed."
582
- ],
583
- dataSensitivity: "internal",
584
- risk: "act",
585
- requiresApproval: {
586
- action: "Remove an availability exception",
587
- reason: "The date goes back to the weekly hours, which can open times that were closed.",
588
- prompt: "Remove exception {ruleId} from calendar {calendarId}?"
589
- }
590
- }
591
- ];
592
-
593
- // src/agent/billing-tools.ts
594
- var COUPON_FIELDS = "id, code, discountType, discountValue, maxUses, usedCount, expiresAt, organizationId, isActive, createdAt, updatedAt";
595
- var PACKAGE_FIELDS = "id, name, description, price, sessions, validDays, typeId, organizationId, isActive, createdAt, updatedAt, type: { id, name }";
596
- var PURCHASE_FIELDS = "id, packageId, organizationId, clientEmail, clientName, sessionsTotal, sessionsUsed, expiresAt, purchasedAt, status, paymentId, notes, pricePaidCents, createdAt, updatedAt, package: { id, name, sessions }";
597
- var COUPON_ID = { name: "id", type: "string", required: true, description: "Coupon id" };
598
- var PACKAGE_ID = { name: "id", type: "string", required: true, description: "Package id" };
599
- var MONEY_NOTE = `Amounts are decimal numbers in the organization's currency; the answer returns them as text without trailing zeros, such as "12.5" or "20".`;
600
- var BILLING_TOOLS = [
601
- {
602
- name: "scheduling_list_coupons",
603
- module: "scheduling",
604
- method: "GET",
605
- route: "/admin/coupons",
606
- auth: "session_cookie",
607
- description: "List the organization's coupon codes, newest first, with how many times each has been used.",
608
- params: [
609
- { name: "limit", type: "number", required: false, description: "How many coupons to return (default 50, at most 200)" },
610
- { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
611
- ],
612
- example: {},
613
- responseShape: `{ coupons: [{ ${COUPON_FIELDS} }], total, hasMore }`,
614
- whenToUse: "To find a coupon id, check whether a code exists, or see how much a code has been used.",
615
- pitfalls: [MONEY_NOTE, "Needs the scheduling switch to be on for the organization."],
616
- dataSensitivity: "internal",
617
- risk: "observe"
618
- },
619
- {
620
- name: "scheduling_create_coupon",
621
- module: "scheduling",
622
- method: "POST",
623
- route: "/admin/coupons",
624
- auth: "session_cookie",
625
- description: "Create a coupon code that takes a percentage or a flat amount off the online payment of a booking.",
626
- params: [
627
- { name: "code", type: "string", required: true, description: "The code clients type, 3 to 50 characters of letters, digits, hyphens and underscores. It is stored in capital letters." },
628
- { name: "discountType", type: "string", required: true, description: "PERCENTAGE takes a share off; FLAT takes a fixed amount off", allowedValues: ["PERCENTAGE", "FLAT"] },
629
- { name: "discountValue", type: "number", required: true, description: "The percentage (at most 100) or the amount, from 0.01 up to 100000" },
630
- { name: "maxUses", type: "number", required: false, description: "How many paid bookings may use it, a whole number of 1 or more; no limit if left out or null" },
631
- { name: "expiresAt", type: "string", required: false, description: "When it stops working, as an ISO 8601 UTC date-time such as 2026-12-31T23:59:59Z; never if left out or null" }
632
- ],
633
- example: { code: "WELCOME20", discountType: "PERCENTAGE", discountValue: 20, maxUses: 100, expiresAt: "2026-12-31T23:59:59Z" },
634
- responseShape: `{ coupon: { ${COUPON_FIELDS} } }`,
635
- whenToUse: "To start a promotion. It is active straight away and its used count starts at 0. Leave at least 0.50 to pay, or the coupon will be refused at checkout.",
636
- pitfalls: [
637
- "A code that already exists is refused with 409. Codes are unique across the whole database, so a code used by another organization is refused too.",
638
- "A percentage over 100 is refused with 400.",
639
- "A coupon only matters for a booking that is paid online (scheduling_book_appointment with couponCode). The discount comes off the deposit when the appointment type has one, otherwise off the price, and the charge cannot go below zero. Online payment is refused with 400 when the discounted charge would be under 50 cents (the card provider's minimum), so a coupon cannot make a booking free: a 100% coupon, or a flat coupon as large as the charge, fails at checkout. A booking for a type that takes no payment ignores the code and does not use it up.",
640
- MONEY_NOTE,
641
- "Needs the scheduling switch to be on for the organization."
642
- ],
643
- dataSensitivity: "internal",
644
- risk: "govern",
645
- requiresApproval: {
646
- action: "Create a coupon",
647
- reason: "Anyone with the code gets the discount on their online payment straight away.",
648
- prompt: "Create coupon {code} for {discountValue} ({discountType}) off?"
649
- }
650
- },
651
- {
652
- name: "scheduling_update_coupon",
653
- module: "scheduling",
654
- method: "PUT",
655
- route: "/admin/coupons/[id]",
656
- auth: "session_cookie",
657
- description: "Change a coupon, or switch it off. Only the fields you send change.",
658
- params: [
659
- COUPON_ID,
660
- { name: "code", type: "string", required: false, description: "New code, 3 to 50 characters of letters, digits, hyphens and underscores; stored in capital letters" },
661
- { name: "discountType", type: "string", required: false, description: "PERCENTAGE or FLAT", allowedValues: ["PERCENTAGE", "FLAT"] },
662
- { name: "discountValue", type: "number", required: false, description: "The percentage (at most 100) or the amount, from 0.01 up to 100000" },
663
- { name: "maxUses", type: "number", required: false, description: "How many paid bookings may use it, a whole number of 1 or more, or null for no limit" },
664
- { name: "expiresAt", type: "string", required: false, description: "When it stops working, as an ISO 8601 UTC date-time, or null for never" },
665
- { name: "isActive", type: "boolean", required: false, description: "false switches it off so it no longer works; true switches it back on" }
666
- ],
667
- example: { id: "coupon_1", isActive: false },
668
- responseShape: `{ coupon: { ${COUPON_FIELDS} } }`,
669
- whenToUse: "To end a promotion (isActive false), extend it, or change its discount. To stop one that has been used, switch it off instead of deleting it.",
670
- pitfalls: [
671
- "The percentage cap is checked on the coupon as it would be after the change, so switching a flat coupon of 500 to PERCENTAGE without a new value is refused with 400.",
672
- "The used count cannot be changed.",
673
- "A coupon of another organization is a plain 404. A new code that is already taken is refused with 409.",
674
- "Needs no scheduling switch."
675
- ],
676
- dataSensitivity: "internal",
677
- risk: "govern",
678
- requiresApproval: {
679
- action: "Change a coupon",
680
- reason: "The change takes effect for the next booking that uses the code.",
681
- prompt: "Change coupon {id}?"
682
- }
683
- },
684
- {
685
- name: "scheduling_delete_coupon",
686
- module: "scheduling",
687
- method: "DELETE",
688
- route: "/admin/coupons/[id]",
689
- auth: "session_cookie",
690
- description: "Delete a coupon that has never been used.",
691
- params: [COUPON_ID],
692
- example: { id: "coupon_1" },
693
- responseShape: "{ success: true }",
694
- whenToUse: "Only to remove a coupon made by mistake. To stop one that has been used, use scheduling_update_coupon with isActive false.",
695
- pitfalls: [
696
- "Refused with 409 once the coupon has been used, even once.",
697
- "A deleted coupon cannot be brought back.",
698
- "Needs no scheduling switch."
699
- ],
700
- dataSensitivity: "internal",
701
- risk: "act",
702
- requiresApproval: {
703
- action: "Delete a coupon",
704
- reason: "The coupon is removed for good.",
705
- prompt: "Delete coupon {id}? This cannot be undone."
706
- }
707
- },
708
- {
709
- name: "scheduling_list_packages",
710
- module: "scheduling",
711
- method: "GET",
712
- route: "/admin/packages",
713
- auth: "session_cookie",
714
- description: "List the prepaid service packages (a number of sessions sold as one), newest first, with the appointment type each is for.",
715
- params: [],
716
- example: {},
717
- responseShape: `{ packages: [{ ${PACKAGE_FIELDS} }] }`,
718
- whenToUse: "To find a package id, or see what packages are on offer and whether they are switched on.",
719
- pitfalls: [MONEY_NOTE, "The answer is a plain list with no paging, including switched-off packages.", "Needs the scheduling switch to be on for the organization."],
720
- dataSensitivity: "internal",
721
- risk: "observe"
722
- },
723
- {
724
- name: "scheduling_create_package",
725
- module: "scheduling",
726
- method: "POST",
727
- route: "/admin/packages",
728
- auth: "session_cookie",
729
- description: "Create a prepaid package: a number of sessions with a price and a time in which to use them. It starts active.",
730
- params: [
731
- { name: "name", type: "string", required: true, description: "Package name, 1 to 100 characters" },
732
- { name: "description", type: "string", required: false, description: "Description, up to 500 characters" },
733
- { name: "price", type: "number", required: true, description: "Price of the whole package, from 0.01 up to 99999" },
734
- { name: "sessions", type: "number", required: true, description: "How many sessions it includes, a whole number from 1 to 1000" },
735
- { name: "validDays", type: "number", required: false, description: "Days from purchase in which the sessions can be used, a whole number from 1 to 3650; 365 if left out" },
736
- { name: "typeId", type: "string", required: false, description: "Appointment type the package is for. A package with a type can only be used to book that type; with none it covers any type." }
737
- ],
738
- example: { name: "Ten fittings", price: 500, sessions: 10, validDays: 365, typeId: "type_1" },
739
- responseShape: `{ package: { ${PACKAGE_FIELDS} } }`,
740
- whenToUse: "To offer sessions at a bundle price. Then give it to a client with scheduling_create_package_purchase.",
741
- pitfalls: [
742
- "A typeId that is not an appointment type of this organization is refused with 404.",
743
- "Creating a package sells nothing and takes no payment; a client only gets sessions when a purchase is created for them.",
744
- MONEY_NOTE,
745
- "Needs the scheduling switch to be on for the organization."
746
- ],
747
- dataSensitivity: "internal",
748
- risk: "govern",
749
- requiresApproval: {
750
- action: "Create a package",
751
- reason: "A package sets a price and a number of sessions that staff can then hand to clients.",
752
- prompt: 'Create the package "{name}" with {sessions} sessions for {price}?'
753
- }
754
- },
755
- {
756
- name: "scheduling_update_package",
757
- module: "scheduling",
758
- method: "PUT",
759
- route: "/admin/packages/[id]",
760
- auth: "session_cookie",
761
- description: "Change a package, or switch it off. Only the fields you send change.",
762
- params: [
763
- PACKAGE_ID,
764
- { name: "name", type: "string", required: false, description: "Package name, 1 to 100 characters" },
765
- { name: "description", type: "string", required: false, description: "Description, up to 500 characters, or null to clear it" },
766
- { name: "price", type: "number", required: false, description: "Price, from 0.01 up to 99999" },
767
- { name: "sessions", type: "number", required: false, description: "Sessions included, a whole number from 1 to 1000" },
768
- { name: "validDays", type: "number", required: false, description: "Days to use the sessions, from 1 to 3650" },
769
- { name: "typeId", type: "string", required: false, description: "Appointment type it is for, or null for any type" },
770
- { name: "isActive", type: "boolean", required: false, description: "false stops new purchases of it; true switches it back on" }
771
- ],
772
- example: { id: "pkg_1", isActive: false },
773
- responseShape: `{ package: { ${PACKAGE_FIELDS} } }`,
774
- whenToUse: "To change the offer for future purchases, or take it off sale with isActive false.",
775
- pitfalls: [
776
- "Purchases already made keep the session count and price they were made with. Changing the package's typeId does change what existing purchases of it can book.",
777
- "A typeId of another organization is refused with 404.",
778
- "A switched-off package cannot be given to a client, but purchases already made stay usable.",
779
- "Needs no scheduling switch."
780
- ],
781
- dataSensitivity: "internal",
782
- risk: "govern",
783
- requiresApproval: {
784
- action: "Change a package",
785
- reason: "The change sets what new purchases cost and include, and what existing purchases can book.",
786
- prompt: "Change package {id}?"
787
- }
788
- },
789
- {
790
- name: "scheduling_delete_package",
791
- module: "scheduling",
792
- method: "DELETE",
793
- route: "/admin/packages/[id]",
794
- auth: "session_cookie",
795
- description: "Delete a package that no purchase refers to.",
796
- params: [PACKAGE_ID],
797
- example: { id: "pkg_1" },
798
- responseShape: "{ success: true }",
799
- whenToUse: "Only to remove a package made by mistake. To take one off sale, use scheduling_update_package with isActive false.",
800
- pitfalls: [
801
- "Refused with 409 once any purchase refers to the package.",
802
- "A deleted package cannot be brought back.",
803
- "Needs no scheduling switch."
804
- ],
805
- dataSensitivity: "internal",
806
- risk: "act",
807
- requiresApproval: {
808
- action: "Delete a package",
809
- reason: "The package is removed for good.",
810
- prompt: "Delete package {id}? This cannot be undone."
811
- }
812
- },
813
- {
814
- name: "scheduling_list_package_purchases",
815
- module: "scheduling",
816
- method: "GET",
817
- route: "/admin/package-purchases",
818
- auth: "session_cookie",
819
- description: "List the packages given to clients, newest first, with how many sessions each has used.",
820
- params: [
821
- { name: "limit", type: "number", required: false, description: "How many purchases to return (default 50, at most 200)" },
822
- { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
823
- ],
824
- example: {},
825
- responseShape: `{ purchases: [{ ${PURCHASE_FIELDS} }], total, hasMore }`,
826
- whenToUse: "To find a client's package, see how many sessions are left (sessionsTotal minus sessionsUsed), or get the id to book with.",
827
- pitfalls: [
828
- "status is ACTIVE, EXHAUSTED (all sessions used) or CANCELLED. A purchase stays ACTIVE after its expiry date passes, so check expiresAt as well as status before telling a client they can still book.",
829
- "The answer carries client names and email addresses.",
830
- "Needs the scheduling switch to be on for the organization."
831
- ],
832
- dataSensitivity: "sensitive",
833
- risk: "observe"
834
- },
835
- {
836
- name: "scheduling_create_package_purchase",
837
- module: "scheduling",
838
- method: "POST",
839
- route: "/admin/package-purchases",
840
- auth: "session_cookie",
841
- description: "Give a client a package: they receive its sessions to use for bookings. This records the purchase; it does not take a payment.",
842
- params: [
843
- { name: "packageId", type: "string", required: true, description: "Package id; it must be switched on" },
844
- { name: "clientEmail", type: "string", required: true, description: "Client email address. Only a booking made with this same address can use the package." },
845
- { name: "clientName", type: "string", required: false, description: "Client name, up to 200 characters" },
846
- { name: "notes", type: "string", required: false, description: "Note, up to 1000 characters" },
847
- { name: "expiresAt", type: "string", required: false, description: "When the sessions stop being usable, as an ISO 8601 UTC date-time in the future. If left out it is the purchase date plus the package's validDays." }
848
- ],
849
- example: { packageId: "pkg_1", clientEmail: "sam@example.com", clientName: "Sam Rivera" },
850
- responseShape: `{ purchase: { ${PURCHASE_FIELDS} } }`,
851
- whenToUse: "When a client has paid for a package outside this system, or is being given sessions. The client then books with packagePurchaseId in scheduling_book_appointment.",
852
- pitfalls: [
853
- "No payment is taken or checked. The package's current price is only written down as pricePaidCents, so only create a purchase when the money has been handled.",
854
- "The client's sessions and expiry are fixed now: later changes to the package do not change this purchase.",
855
- "A package that does not exist, belongs to another organization or is switched off is refused with 404. An expiresAt in the past is refused with 400.",
856
- "Needs the scheduling switch to be on for the organization."
857
- ],
858
- dataSensitivity: "sensitive",
859
- risk: "govern",
860
- requiresApproval: {
861
- action: "Give a client a package",
862
- reason: "The client can book that many sessions without paying again, and nothing here checks that they paid.",
863
- prompt: "Give {clientEmail} the package {packageId}?"
864
- }
865
- },
866
- {
867
- name: "scheduling_update_package_purchase",
868
- module: "scheduling",
869
- method: "PATCH",
870
- route: "/admin/package-purchases/[id]",
871
- auth: "session_cookie",
872
- description: "Cancel a purchase, bring a cancelled one back, or correct the client's name, email or the notes.",
873
- params: [
874
- { name: "id", type: "string", required: true, description: "Purchase id" },
875
- { name: "status", type: "string", required: false, description: "CANCELLED stops the client using the remaining sessions; ACTIVE brings a cancelled purchase back", allowedValues: ["ACTIVE", "CANCELLED"] },
876
- { name: "clientName", type: "string", required: false, description: "Client name, up to 200 characters" },
877
- { name: "clientEmail", type: "string", required: false, description: "Client email. Bookings must use this address to draw on the package." },
878
- { name: "notes", type: "string", required: false, description: "Note, up to 1000 characters" }
879
- ],
880
- example: { id: "purchase_1", status: "CANCELLED" },
881
- responseShape: `{ purchase: { ${PURCHASE_FIELDS} } }`,
882
- whenToUse: "To withdraw a package that was given by mistake or refunded elsewhere, or to fix a mistyped email so the client can use it.",
883
- pitfalls: [
884
- "Send at least one field, or it is refused with 400.",
885
- "Cancelling works only on an ACTIVE purchase; reactivating only on a CANCELLED one that still has sessions left and has not expired. Anything else is refused with 409.",
886
- "Cancelling takes back only the unused sessions: bookings already made with the package are left as they are, and no money is refunded.",
887
- "The expiry and the number of sessions cannot be changed. To give more time, create a new purchase.",
888
- "Needs no scheduling switch."
889
- ],
890
- dataSensitivity: "sensitive",
891
- risk: "govern",
892
- requiresApproval: {
893
- action: "Change a package purchase",
894
- reason: "It can take sessions away from a client or give them back, and a changed email decides who may use the package.",
895
- prompt: "Change package purchase {id}?"
896
- }
897
- }
898
- ];
899
-
900
- // src/agent/calendar-tools.ts
901
- var ID2 = { name: "id", type: "string", required: true, description: "Calendar id" };
902
- var CALENDAR_FIELDS = "id, name, slug, type, timezone, isActive, staffName, staffEmail, staffAvatar, userId, location, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, slotGranularityMinutes";
903
- var THEME_KEYS = "primaryColor, accentColor, backgroundColor, textColor, mutedTextColor, borderColor, borderRadius, fontFamily";
904
- var CONFIG_KEYS = "title, description, logoUrl, confirmationMessage, redirectUrl, redirectDelay, showContactInfo";
905
- var SLOT_SIZES = "one of 5, 10, 15, 30 or 60 (minutes between the start times offered)";
906
- var CALENDAR_TOOLS = [
907
- {
908
- name: "scheduling_list_staff_options",
909
- module: "scheduling",
910
- method: "GET",
911
- route: "/admin/calendars/staff-options",
912
- auth: "session_cookie",
913
- description: "List the active people in the organization that a calendar can be linked to, with id, name and email.",
914
- params: [],
915
- example: {},
916
- responseShape: "{ staff: [{ id, name, email }] }",
917
- whenToUse: "Before linking a calendar to a person: the id returned here is the userId to use, provided it is in the cuid format the calendar tools accept (other ids are refused with 400).",
918
- pitfalls: ["Admin roles only, because it lists every staff member's name and email.", "A host that has no staff directory returns an empty list."],
919
- dataSensitivity: "sensitive",
920
- risk: "observe"
921
- },
922
- {
923
- name: "scheduling_list_calendars",
924
- module: "scheduling",
925
- method: "GET",
926
- route: "/admin/calendars",
927
- auth: "session_cookie",
928
- description: "List the organization's calendars, active and archived, with how many appointments each has. A person limited by group visibility sees only their groups' calendars.",
929
- params: [
930
- { name: "limit", type: "number", required: false, description: "How many to return (default 500, at most 1000)" },
931
- { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
932
- ],
933
- example: { limit: 100 },
934
- responseShape: `{ calendars: [{ ${CALENDAR_FIELDS}, _count }], total, hasMore }`,
935
- whenToUse: "To find a calendar id, or to see which calendars exist and which are archived (isActive false).",
936
- pitfalls: ["Only counts: appointments are listed with the appointments tool."],
937
- dataSensitivity: "internal",
938
- risk: "observe"
939
- },
940
- {
941
- name: "scheduling_get_calendar",
942
- module: "scheduling",
943
- method: "GET",
944
- route: "/admin/calendars/[id]",
945
- auth: "session_cookie",
946
- description: "Read one calendar: its name, type, time zone, staff details, outside-calendar connections and slot size.",
947
- params: [ID2],
948
- example: { id: "cal_1" },
949
- responseShape: `{ calendar: { ${CALENDAR_FIELDS}, organizationId, _count } }`,
950
- whenToUse: "To check one calendar before changing it.",
951
- pitfalls: ["A calendar of another organization, or one the person may not see, is a plain 404."],
952
- dataSensitivity: "internal",
953
- risk: "observe"
954
- },
955
- {
956
- name: "scheduling_create_calendar",
957
- module: "scheduling",
958
- method: "POST",
959
- route: "/admin/calendars",
960
- auth: "session_cookie",
961
- description: "Create a calendar. Its web address name (slug) is made from the name, and it starts active.",
962
- params: [
963
- { name: "name", type: "string", required: true, description: "Calendar name, 1 to 100 characters" },
964
- { name: "type", type: "string", required: false, description: "What the calendar stands for; STAFF if left out", allowedValues: ["STAFF", "LOCATION", "RESOURCE"] },
965
- { name: "timezone", type: "string", required: false, description: "IANA timezone of the calendar, such as America/New_York (the default)" },
966
- { name: "staffName", type: "string", required: false, description: "Name shown on the booking page, up to 100 characters" },
967
- { name: "staffEmail", type: "string", required: false, description: "Email of the person, where notices go" },
968
- { name: "staffAvatar", type: "string", required: false, description: "Address (URL) of a picture, up to 500 characters" },
969
- { name: "userId", type: "string", required: false, description: "The person this calendar belongs to, from the staff options tool: an id in cuid format who is a member of the organization (any other id is refused with 400)" },
970
- { name: "location", type: "string", required: false, description: "Where appointments happen by default, up to 200 characters" },
971
- { name: "slotGranularityMinutes", type: "number", required: false, description: `Slot size: ${SLOT_SIZES}; 15 if left out` }
972
- ],
973
- example: { name: "Front desk", type: "STAFF", timezone: "America/New_York", slotGranularityMinutes: 15 },
974
- responseShape: "{ calendar, directoryClaimed } where calendar holds id, organizationId, name, slug, type, timezone, isActive, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, staffName, staffEmail, staffAvatar, userId, theme, bookingPageConfig, location, slotGranularityMinutes, createdAt, updatedAt; sync settings and tokens are never returned",
975
- whenToUse: "When a new person, room or resource needs its own bookable calendar. Give it opening hours with scheduling_set_weekly_availability.",
976
- pitfalls: [
977
- 'A calendar with the same name, or a name that gives the same web address ("Front Desk" and "front-desk!" do), already exists: refused with 409.',
978
- "A new calendar has no opening hours, which means it is open around the clock (up to the booking limits) until weekly hours are set with scheduling_set_weekly_availability. Set them straight away.",
979
- "directoryClaimed false means the short booking address could not be registered; only the organization-qualified address works then."
980
- ],
981
- dataSensitivity: "internal",
982
- risk: "act",
983
- requiresApproval: {
984
- action: "Create a calendar",
985
- reason: "A new calendar becomes a bookable resource with its own public booking address.",
986
- prompt: 'Create the calendar "{name}"?'
987
- }
988
- },
989
- {
990
- name: "scheduling_update_calendar",
991
- module: "scheduling",
992
- method: "PUT",
993
- route: "/admin/calendars/[id]",
994
- auth: "session_cookie",
995
- description: "Change a calendar. Only the fields you send change; a field left out stays as it is. Setting isActive to false archives it.",
996
- params: [
997
- ID2,
998
- { name: "name", type: "string", required: false, description: "New name, 1 to 100 characters" },
999
- { name: "type", type: "string", required: false, description: "New type", allowedValues: ["STAFF", "LOCATION", "RESOURCE"] },
1000
- { name: "timezone", type: "string", required: false, description: "New IANA timezone" },
1001
- { name: "staffName", type: "string", required: false, description: "New staff name, up to 100 characters, or null to clear it" },
1002
- { name: "staffEmail", type: "string", required: false, description: "New staff email, or null to clear it" },
1003
- { name: "staffAvatar", type: "string", required: false, description: "New picture address (URL), or null to clear it" },
1004
- { name: "userId", type: "string", required: false, description: "The person this calendar belongs to: an id in cuid format who is a member of the organization (any other id is refused with 400); null unlinks it" },
1005
- { name: "location", type: "string", required: false, description: "New default location, up to 200 characters, or null to clear it" },
1006
- { name: "slotGranularityMinutes", type: "number", required: false, description: `New slot size: ${SLOT_SIZES}` },
1007
- { name: "isActive", type: "boolean", required: false, description: "false archives the calendar, true brings it back" },
1008
- { name: "syncDirection", type: "string", required: false, description: "How an outside calendar is synced", allowedValues: ["one-way", "two-way"] }
1009
- ],
1010
- example: { id: "cal_1", timezone: "America/Chicago", slotGranularityMinutes: 30 },
1011
- responseShape: "{ calendar } where calendar holds id, organizationId, name, slug, type, timezone, isActive, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, staffName, staffEmail, staffAvatar, userId, theme, bookingPageConfig, location, slotGranularityMinutes, createdAt, updatedAt; sync settings and tokens are never returned",
1012
- whenToUse: "To rename a calendar, change its time zone or slot size, link it to a person, or switch it off or on.",
1013
- pitfalls: [
1014
- "Changing the time zone changes what the opening hours mean in real time.",
1015
- "Renaming a calendar to the name of another active calendar, ignoring capital letters, is refused with 409. A name that only gives the same web address is not checked on rename, because renaming never changes the web address.",
1016
- "Switching off the last active calendar is refused with 409, as archiving is. If the other changes in the same request then fail to save, the calendar is switched back on.",
1017
- "Linking a calendar to a person (userId) changes who can see it when staff are limited to their groups.",
1018
- "Switching a calendar back on (isActive true) does not give back its short booking address; only the organization-qualified address works until it is registered again."
1019
- ],
1020
- dataSensitivity: "internal",
1021
- risk: "act",
1022
- requiresApproval: {
1023
- action: "Change a calendar",
1024
- reason: "Changes can stop a calendar taking bookings, move its opening hours in real time, and link it to a person, which decides who can see it.",
1025
- prompt: "Change calendar {id}?"
1026
- }
1027
- },
1028
- {
1029
- name: "scheduling_archive_calendar",
1030
- module: "scheduling",
1031
- method: "DELETE",
1032
- route: "/admin/calendars/[id]",
1033
- auth: "session_cookie",
1034
- description: "Archive a calendar: it stops taking bookings and its short address is released. Its appointments are kept, and the update tool can bring it back.",
1035
- params: [ID2],
1036
- example: { id: "cal_1" },
1037
- responseShape: "{ success: true }",
1038
- whenToUse: "When a person, room or resource is no longer bookable.",
1039
- pitfalls: [
1040
- "The last active calendar can never be archived: refused with 409. Create another calendar first.",
1041
- "Appointments already booked on the calendar are not cancelled by this.",
1042
- "Restoring it later with the update tool does not give back its short booking address; only the organization-qualified address works until it is registered again."
1043
- ],
1044
- dataSensitivity: "internal",
1045
- risk: "act",
1046
- requiresApproval: {
1047
- action: "Archive a calendar",
1048
- reason: "The calendar stops taking bookings and its public address stops working.",
1049
- prompt: "Archive calendar {id}? It stops taking bookings."
1050
- }
1051
- },
1052
- {
1053
- name: "scheduling_get_booking_page",
1054
- module: "scheduling",
1055
- method: "GET",
1056
- route: "/admin/calendars/[id]/booking-page",
1057
- auth: "session_cookie",
1058
- description: "Read how a calendar's public booking page looks and what it says: the theme colours and fonts, and the page wording and settings.",
1059
- params: [ID2],
1060
- example: { id: "cal_1" },
1061
- responseShape: "{ theme, config, name, slug, staffName }",
1062
- whenToUse: "Before changing the booking page, to see what is set now.",
1063
- pitfalls: ["theme and config are null when nothing was ever saved."],
1064
- dataSensitivity: "internal",
1065
- risk: "observe"
1066
- },
1067
- {
1068
- name: "scheduling_update_booking_page",
1069
- module: "scheduling",
1070
- method: "PUT",
1071
- route: "/admin/calendars/[id]/booking-page",
1072
- auth: "session_cookie",
1073
- description: "Save the look and wording of a calendar's public booking page. Send theme, config or both; a part left out is untouched, and null clears that part.",
1074
- params: [
1075
- ID2,
1076
- { name: "theme", type: "json-object", required: false, description: `A JSON object of look settings, each optional: ${THEME_KEYS}. Colours and sizes are written as CSS values (such as #1a4d3a or 8px); a value that could load a web address or break out of the style is refused. null clears the theme.` },
1077
- { name: "config", type: "json-object", required: false, description: `A JSON object of page wording and settings, each optional: ${CONFIG_KEYS}. title is up to 100 characters; description and confirmationMessage up to 500; logoUrl and redirectUrl must start with https://; redirectDelay is whole seconds from 0 to 30 (5 if left out); showContactInfo is true or false (true if left out). null clears the config.` }
1078
- ],
1079
- example: { id: "cal_1", theme: { primaryColor: "#1a4d3a", borderRadius: "8px" }, config: { title: "Book a visit", redirectDelay: 5 } },
1080
- responseShape: "{ success: true }",
1081
- whenToUse: "To brand a booking page or change what the client reads on it.",
1082
- pitfalls: [
1083
- "The theme or config you send replaces the saved one as a whole: read it first and send back what should stay.",
1084
- "A runner that cannot offer an object to the model cannot use this tool."
1085
- ],
1086
- dataSensitivity: "internal",
1087
- risk: "act",
1088
- requiresApproval: {
1089
- action: "Change a booking page",
1090
- reason: "The booking page is what clients see when they book.",
1091
- prompt: "Change the booking page of calendar {id}?"
1092
- }
1093
- },
1094
- {
1095
- name: "scheduling_disconnect_google_calendar",
1096
- module: "scheduling",
1097
- method: "POST",
1098
- route: "/admin/calendars/[id]/disconnect-google",
1099
- auth: "session_cookie",
1100
- description: "Disconnect a calendar from Google Calendar. This stops syncing both ways and clears the connection and its sync state. Google may keep sending notices for a while; whether they are accepted is up to the host application that receives them. Appointments already created stay.",
1101
- params: [ID2],
1102
- example: { id: "cal_1" },
1103
- responseShape: "{ success: true }",
1104
- whenToUse: "When a person no longer wants their Google Calendar tied to this calendar.",
1105
- pitfalls: [
1106
- "A calendar that is not connected to Google is refused with 400.",
1107
- "Connecting needs a person to sign in to Google in a browser; no tool can do that."
1108
- ],
1109
- dataSensitivity: "internal",
1110
- risk: "act",
1111
- requiresApproval: {
1112
- action: "Disconnect Google Calendar",
1113
- reason: "Syncing stops, and the connection can only be restored by a person signing in to Google again.",
1114
- prompt: "Disconnect Google Calendar from calendar {id}?"
1115
- }
1116
- },
1117
- {
1118
- name: "scheduling_disconnect_outlook_calendar",
1119
- module: "scheduling",
1120
- method: "POST",
1121
- route: "/admin/calendars/[id]/disconnect-outlook",
1122
- auth: "session_cookie",
1123
- description: "Disconnect a calendar from Outlook Calendar. This stops syncing and removes the stored Outlook sign-in. Appointments already created stay.",
1124
- params: [ID2],
1125
- example: { id: "cal_1" },
1126
- responseShape: "{ success: true }",
1127
- whenToUse: "When a person no longer wants their Outlook calendar tied to this calendar.",
1128
- pitfalls: [
1129
- "A calendar that is not connected to Outlook is refused with 400.",
1130
- "Connecting needs a person to sign in to Microsoft in a browser; no tool can do that."
1131
- ],
1132
- dataSensitivity: "internal",
1133
- risk: "act",
1134
- requiresApproval: {
1135
- action: "Disconnect Outlook Calendar",
1136
- reason: "Syncing stops, and the connection can only be restored by a person signing in to Microsoft again.",
1137
- prompt: "Disconnect Outlook Calendar from calendar {id}?"
1138
- }
1139
- },
1140
- {
1141
- name: "scheduling_list_location_recents",
1142
- module: "scheduling",
1143
- method: "GET",
1144
- route: "/admin/calendars/[id]/location-recents",
1145
- auth: "session_cookie",
1146
- description: "List up to five places that recent appointments on this calendar happened at, most recent first, with a client's preferred place first when a client is named.",
1147
- params: [
1148
- ID2,
1149
- { name: "clientId", type: "string", required: false, description: "A client whose preferred place should come first" }
1150
- ],
1151
- example: { id: "cal_1" },
1152
- responseShape: "{ locations }",
1153
- whenToUse: "When filling in a location for a booking: suggests places already used.",
1154
- pitfalls: ["Open to any signed-in member, not only admin roles.", "A client the person may not see counts as absent, so the answer is the same as for a missing client."],
1155
- dataSensitivity: "internal",
1156
- risk: "observe"
1157
- }
1158
- ];
1159
-
1160
- // src/agent/gift-certificate-tools.ts
1161
- var CERTIFICATE_FIELDS = "id, code, status, currency, initialCents, balanceCents, expiresAt, recipientName, recipientEmail, purchaserName, purchaserEmail, message, notes, paymentId, createdByUserId, createdAt";
1162
- var LINE_FIELDS = "id, seq, type, amountCents, balanceAfterCents, appointmentId, note, createdByUserId, createdAt";
1163
- var NOT_ENABLED = "A server without gift certificates answers 501.";
1164
- var ID3 = { name: "id", type: "string", required: true, description: "Gift certificate id" };
1165
- var CODE_CARE = "The code in the answer spends like cash: give it only to the person it is for, and do not repeat it anywhere else. A read-only API key sees only the last four characters of each code.";
1166
- var GIFT_CERTIFICATE_TOOLS = [
1167
- {
1168
- name: "scheduling_list_gift_certificates",
1169
- module: "scheduling",
1170
- method: "GET",
1171
- route: "/admin/gift-certificates",
1172
- auth: "session_cookie",
1173
- description: "List the organization's gift certificates, newest first, with their balances.",
1174
- params: [
1175
- { name: "status", type: "string", required: false, description: "Only this status", allowedValues: ["ACTIVE", "VOID"] },
1176
- { name: "limit", type: "number", required: false, description: "How many to return (default 100, at most 500)" }
1177
- ],
1178
- example: { status: "ACTIVE" },
1179
- responseShape: `{ certificates: [{ ${CERTIFICATE_FIELDS} }] }`,
1180
- whenToUse: "To find a certificate id, see how much value is outstanding, or look up who a certificate was sold to.",
1181
- pitfalls: [CODE_CARE, "status is ACTIVE or VOID only: a certificate that has expired or been used up is still ACTIVE here; read its expiresAt and balanceCents.", "There is no total and no paging: the newest 100 come back unless limit says more.", NOT_ENABLED, "Needs the scheduling switch to be on for the organization."],
1182
- dataSensitivity: "critical",
1183
- risk: "observe"
1184
- },
1185
- {
1186
- name: "scheduling_get_gift_certificate",
1187
- module: "scheduling",
1188
- method: "GET",
1189
- route: "/admin/gift-certificates/[id]",
1190
- auth: "session_cookie",
1191
- description: "Read one gift certificate with its history: the issue, every spend, every give-back and any void, in order.",
1192
- params: [ID3],
1193
- example: { id: "gc_1" },
1194
- responseShape: `{ certificate: { ${CERTIFICATE_FIELDS} }, transactions: [{ ${LINE_FIELDS} }], truncated }`,
1195
- whenToUse: 'To answer "what is left on this certificate" or "what was it spent on". Amounts are whole cents: 1250 is 12.50.',
1196
- pitfalls: [CODE_CARE, "Spends have a negative amountCents and give-backs a positive one. truncated is true when the history has more than 1000 lines and only the first are shown.", NOT_ENABLED, "Needs the scheduling switch to be on for the organization."],
1197
- dataSensitivity: "critical",
1198
- risk: "observe"
1199
- },
1200
- {
1201
- name: "scheduling_issue_gift_certificate",
1202
- module: "scheduling",
1203
- method: "POST",
1204
- route: "/admin/gift-certificates",
1205
- auth: "session_cookie",
1206
- description: "Issue a gift certificate worth an amount, with a random code the holder types at booking.",
1207
- params: [
1208
- { name: "amountCents", type: "number", required: true, description: "Value in whole cents, from 100 to 1000000: 5000 is 50.00" },
1209
- { name: "currency", type: "string", required: false, description: "Three-letter currency code, default usd. A certificate only pays a bill in its own currency." },
1210
- { name: "expiresAt", type: "string", required: false, description: "When it stops working, an ISO date or time in the future. Leave out for no expiry." },
1211
- { name: "recipientName", type: "string", required: false, description: "Who it is for" },
1212
- { name: "recipientEmail", type: "string", required: false, description: "Where to send it" },
1213
- { name: "purchaserName", type: "string", required: false, description: "Who bought it" },
1214
- { name: "purchaserEmail", type: "string", required: false, description: "The buyer's email" },
1215
- { name: "message", type: "string", required: false, description: "A note for the recipient, up to 500 characters" },
1216
- { name: "paymentId", type: "string", required: false, description: "The payment that bought it. A payment makes one certificate: asking again with the same id returns the first one." },
1217
- { name: "notes", type: "string", required: false, description: "A note for staff, up to 1000 characters" }
1218
- ],
1219
- example: { amountCents: 5e3, recipientName: "Jane Smith", recipientEmail: "jane@example.com", message: "Happy birthday" },
1220
- responseShape: `{ certificate: { ${CERTIFICATE_FIELDS} } }`,
1221
- whenToUse: "When a certificate is sold at the counter, given as a gift or issued to make up for a problem. It works at once.",
1222
- pitfalls: [
1223
- CODE_CARE,
1224
- "This creates value the business owes the holder: nothing is charged here. Take payment separately and pass its id as paymentId so a repeat cannot issue a second certificate.",
1225
- "A paymentId already used for a different amount or currency is refused with 409. An amount outside 100 to 1000000 cents, a past expiry or an email that is not an address is refused with 400, with every problem listed.",
1226
- NOT_ENABLED,
1227
- "Needs the scheduling switch to be on for the organization."
1228
- ],
1229
- dataSensitivity: "critical",
1230
- risk: "govern",
1231
- requiresApproval: {
1232
- action: "Issue a gift certificate",
1233
- reason: "It creates spendable value that the business owes the holder, and the code in the answer can be spent by anyone who has it.",
1234
- prompt: "Issue a gift certificate worth {amountCents} cents?"
1235
- }
1236
- },
1237
- {
1238
- name: "scheduling_void_gift_certificate",
1239
- module: "scheduling",
1240
- method: "POST",
1241
- route: "/admin/gift-certificates/[id]/void",
1242
- auth: "session_cookie",
1243
- description: "Stop a gift certificate from being spent. Its balance and history stay on record.",
1244
- params: [ID3],
1245
- example: { id: "gc_1" },
1246
- responseShape: "{ voided: true }",
1247
- whenToUse: "When a certificate was issued by mistake, was lost or stolen, or the sale was refunded.",
1248
- pitfalls: ["A void certificate cannot be spent or topped up, and cannot be made active again: issue a new one if the holder is owed value.", "Answers 404 for a certificate that does not exist, belongs to another business, or is already void.", NOT_ENABLED, "Needs the scheduling switch to be on for the organization."],
1249
- dataSensitivity: "sensitive",
1250
- risk: "govern",
1251
- requiresApproval: {
1252
- action: "Void a gift certificate",
1253
- reason: "The holder can no longer spend it, and a voided certificate cannot be brought back.",
1254
- prompt: "Void gift certificate {id}?"
1255
- }
1256
- },
1257
- {
1258
- name: "scheduling_restore_gift_certificate",
1259
- module: "scheduling",
1260
- method: "POST",
1261
- route: "/admin/gift-certificates/[id]/restore",
1262
- auth: "session_cookie",
1263
- description: "Give value back to a gift certificate, for a cancelled or refunded booking or to correct a mistake.",
1264
- params: [
1265
- ID3,
1266
- { name: "amountCents", type: "number", required: true, description: "Value to give back in whole cents: 1250 is 12.50" },
1267
- { name: "appointmentId", type: "string", required: false, description: "The appointment the value was spent on. With it, no more than was spent on that appointment and not yet returned can come back." },
1268
- { name: "note", type: "string", required: false, description: "Why, up to 1000 characters" }
1269
- ],
1270
- example: { id: "gc_1", amountCents: 2500, appointmentId: "appt_1", note: "Booking cancelled" },
1271
- responseShape: "{ restored: { certificateId, transactionId, restoredCents, balanceCents } }",
1272
- whenToUse: "After a booking paid with a certificate is cancelled or refunded, or to put right a wrong spend. Give the appointment whenever there is one.",
1273
- pitfalls: [
1274
- "Without appointmentId the only limit is the amount the certificate was issued for, so a correction cannot go above it.",
1275
- "A repeated give-back for the same appointment returns nothing more and is refused with 409. A void certificate is refused with 409. An expired certificate takes the value back but its expiry is not extended.",
1276
- NOT_ENABLED,
1277
- "Needs the scheduling switch to be on for the organization."
1278
- ],
1279
- dataSensitivity: "sensitive",
1280
- risk: "govern",
1281
- requiresApproval: {
1282
- action: "Give value back to a gift certificate",
1283
- reason: "It adds spendable value to the certificate.",
1284
- prompt: "Give {amountCents} cents back to gift certificate {id}?"
1285
- }
1286
- }
1287
- ];
1288
-
1289
- // src/agent/policy-tools.ts
1290
- var FEE = "An object with enabled (true or false), amount (0 to 10000, required when enabled is true; for a PERCENTAGE it is at most 100) and feeType (FLAT or PERCENTAGE; FLAT if left out).";
1291
- var PREVENTION = "An object with enabled (true or false; false if left out), threshold (how many no-shows trigger it, a whole number 1 to 20; 2 if left out) and action (REQUIRE_APPROVAL, so the booking waits for a person, or BLOCK_BOOKING, so online booking is refused; REQUIRE_APPROVAL if left out).";
1292
- var POLICY_TOOLS = [
1293
- {
1294
- name: "scheduling_get_cancellation_policy",
1295
- module: "scheduling",
1296
- method: "GET",
1297
- route: "/admin/policy",
1298
- auth: "session_cookie",
1299
- description: "Read the organization's cancellation policy, with what each active appointment type enforces for itself, and when the policy was last saved.",
1300
- params: [],
1301
- example: {},
1302
- responseShape: "{ policy: { defaultAllowCancel, defaultCancelDeadlineHrs, noShowFee: { enabled, amount, feeType }, lateCancelFee: { enabled, amount, feeType }, requireCardOnFile, noShowPrevention: { enabled, threshold, action } }, types: [{ id, name, allowCancel, cancelDeadlineHrs }], updatedAt }",
1303
- whenToUse: "Before changing the policy, to see what is set now, and to see each type's own cancel rules.",
1304
- pitfalls: [
1305
- "Until a policy is saved, the answer is the built-in default: cancelling allowed, 24 hours notice, no fees, no card on file, no-show prevention off.",
1306
- "Saving the policy stores the fees, the card-on-file switch and the default cancel rules, but nothing in the scheduling API charges a fee, asks for a card or applies those two defaults; each appointment type's own allowCancel and cancelDeadlineHrs (in types) are what clients meet. The no-show rule is applied only when the host server supplies a booking policy that reads it.",
1307
- "Needs the scheduling switch to be on for the organization."
1308
- ],
1309
- dataSensitivity: "internal",
1310
- risk: "observe"
1311
- },
1312
- {
1313
- name: "scheduling_save_cancellation_policy",
1314
- module: "scheduling",
1315
- method: "PUT",
1316
- route: "/admin/policy",
1317
- auth: "session_cookie",
1318
- description: "Save the organization's cancellation policy. This replaces the whole policy: a field you leave out goes back to its default, not to what it was.",
1319
- params: [
1320
- { name: "defaultAllowCancel", type: "boolean", required: false, description: "Whether clients may cancel by default; true if left out" },
1321
- { name: "defaultCancelDeadlineHrs", type: "number", required: false, description: "Default hours before the start after which a client may no longer cancel, a whole number 0 to 720; 0 means no deadline; 24 if left out" },
1322
- { name: "noShowFee", type: "json-object", required: true, description: `Fee for a no-show. ${FEE}` },
1323
- { name: "lateCancelFee", type: "json-object", required: true, description: `Fee for a late cancellation. ${FEE}` },
1324
- { name: "requireCardOnFile", type: "boolean", required: false, description: "Whether a card must be kept on file; false if left out" },
1325
- { name: "noShowPrevention", type: "json-object", required: false, description: `What happens to a client with repeated no-shows. ${PREVENTION} Left out means off.` },
1326
- { name: "clientUpdatedAt", type: "string", required: false, description: "The updatedAt from the read you based this on, as an ISO 8601 date-time. When sent, a save is refused with 409 if anyone saved the policy since." }
1327
- ],
1328
- example: {
1329
- defaultAllowCancel: true,
1330
- defaultCancelDeadlineHrs: 48,
1331
- noShowFee: { enabled: true, amount: 25, feeType: "FLAT" },
1332
- lateCancelFee: { enabled: false },
1333
- requireCardOnFile: false,
1334
- noShowPrevention: { enabled: true, threshold: 3, action: "REQUIRE_APPROVAL" }
1335
- },
1336
- responseShape: "{ success: true }",
1337
- whenToUse: "To change the policy. Read it first with scheduling_get_cancellation_policy and send back every field that should stay, with its updatedAt as clientUpdatedAt.",
1338
- pitfalls: [
1339
- "It replaces everything. A field left out is reset to its default, so a change to one field must resend all the others.",
1340
- "A fee that is enabled needs an amount, and a PERCENTAGE fee cannot be over 100: both refused with 400, and nothing is saved.",
1341
- "Only the saved policy changes. Fees are not charged and a card is not asked for by this API; see the note on scheduling_get_cancellation_policy.",
1342
- "The organization's other settings are kept.",
1343
- "Needs the scheduling switch to be on for the organization."
1344
- ],
1345
- dataSensitivity: "internal",
1346
- risk: "govern",
1347
- requiresApproval: {
1348
- action: "Save the cancellation policy",
1349
- reason: "The policy is what the business tells clients about cancelling, fees and no-shows, and a no-show rule can refuse online booking to clients with repeated no-shows.",
1350
- prompt: "Save the cancellation policy? This replaces the current policy."
1351
- }
1352
- }
1353
- ];
1354
-
1355
- // src/agent/privacy-tools.ts
1356
- var COUNTS = "{ appointments, notifications, waitlistEntries, packagePurchases, recurringSeries, webhookDeliveries }";
1357
- var NOT_ENABLED2 = "A server without data export and erasure answers 501.";
1358
- var WHO = "Name the person with email, clientId or both. A client id also stands for every address that client has booked with.";
1359
- var SUBJECT_PARAMS = [
1360
- { name: "email", type: "string", required: false, description: "The person's email address: one valid address, up to 254 characters, in any letter case" },
1361
- { name: "clientId", type: "string", required: false, description: "The client id in the host system, 1 to 200 characters" }
1362
- ];
1363
- var PRIVACY_TOOLS = [
1364
- {
1365
- name: "scheduling_export_person_data",
1366
- module: "scheduling",
1367
- method: "POST",
1368
- route: "/admin/privacy/export",
1369
- auth: "session_cookie",
1370
- description: "Export everything held about one person as a single document: their bookings, messages, waitlist entries, package purchases, repeating series and webhook events.",
1371
- params: [...SUBJECT_PARAMS],
1372
- example: { email: "sam@example.com" },
1373
- responseShape: `{ format, version, exportedAt, organizationId, subject: { emails, clientId }, counts: ${COUNTS}, appointments, notifications, waitlistEntries, packagePurchases, recurringSeries, webhookDeliveries }`,
1374
- whenToUse: "When a person asks what is held about them. It reads only; to remove the data use scheduling_erase_person_data.",
1375
- pitfalls: [
1376
- `${WHO} Sending neither, an address that is not one valid address, or any other field is refused with 400.`,
1377
- "The answer is everything about the person, including notes, staff notes, intake answers, payment amounts and message text. Treat it as highly sensitive and give it only to the person's own request.",
1378
- "Self-service links and waitlist links are left out or removed from the messages, so the document cannot be used to change a booking.",
1379
- "Someone with no data gets empty lists and zero counts, not an error. The request is recorded either way, and if it cannot be recorded nothing is returned.",
1380
- "The request is recorded with only a digest of the address, never the address itself.",
1381
- NOT_ENABLED2,
1382
- "Needs the scheduling switch to be on for the organization."
1383
- ],
1384
- dataSensitivity: "critical",
1385
- risk: "act",
1386
- requiresApproval: {
1387
- action: "Export a person's data",
1388
- reason: "Everything held about one person, including notes and payment details, is read out in one document.",
1389
- prompt: "Export all the data held about this person?"
1390
- }
1391
- },
1392
- {
1393
- name: "scheduling_erase_person_data",
1394
- module: "scheduling",
1395
- method: "POST",
1396
- route: "/admin/privacy/erase",
1397
- auth: "session_cookie",
1398
- description: "Erase the personal data held about one person. Without confirm true it only shows what would be erased and what is in the way.",
1399
- params: [
1400
- ...SUBJECT_PARAMS,
1401
- { name: "confirm", type: "boolean", required: false, description: "true really erases. Left out or false only previews and changes nothing." }
1402
- ],
1403
- example: { email: "sam@example.com" },
1404
- responseShape: `{ erased, preview?: { counts: ${COUNTS}, blockers: { upcomingAppointments, liveWaitlistEntries }, canErase, warnings }, counts?: ${COUNTS} }`,
1405
- whenToUse: "When a person asks to be forgotten. Always preview first, show the person what will happen, and only then send confirm true.",
1406
- pitfalls: [
1407
- `${WHO}`,
1408
- "Without confirm the answer is { erased: false, preview }; with confirm true it is { erased: true, counts }.",
1409
- 'It cannot be undone. Bookings, package purchases and repeating series stay as anonymous records ("Erased client", erased@erased.invalid, phone, notes and intake answers cleared, self-service links changed); messages, waitlist entries and queued webhook events about the person are deleted.',
1410
- "It is refused with 409 while the person has an upcoming pending or confirmed booking or a waitlist offer they hold (blockers says how many). Cancel those first.",
1411
- "warnings notes sessions left on an active package: after erasure it can no longer be matched to the person.",
1412
- "Copies already sent elsewhere, such as emails, webhook receivers or backups outside this system, are not recalled.",
1413
- NOT_ENABLED2,
1414
- "Needs the scheduling switch to be on for the organization."
1415
- ],
1416
- dataSensitivity: "critical",
1417
- risk: "govern",
1418
- requiresApproval: {
1419
- action: "Erase a person's data",
1420
- reason: "With confirm true the personal data is permanently erased and cannot be recovered. Without it, it only previews.",
1421
- prompt: "Erase the data held about this person (confirm true erases for good; otherwise it only previews)?"
1422
- }
1423
- },
1424
- {
1425
- name: "scheduling_list_privacy_requests",
1426
- module: "scheduling",
1427
- method: "GET",
1428
- route: "/admin/privacy/requests",
1429
- auth: "session_cookie",
1430
- description: "List the data exports and erasures that have been carried out, newest first, with who asked and how much each covered.",
1431
- params: [
1432
- { name: "limit", type: "number", required: false, description: "How many requests to return (default 50, at most 200)" },
1433
- { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
1434
- ],
1435
- example: {},
1436
- responseShape: `{ requests: [{ id, kind, requestedBy, counts: ${COUNTS}, createdAt }], total, hasMore }`,
1437
- whenToUse: "To show that a request was handled, or to see who has been exporting or erasing data.",
1438
- pitfalls: [
1439
- "kind is EXPORT or ERASE. The log holds counts and who asked, never the person's name or address.",
1440
- NOT_ENABLED2,
1441
- "Needs the scheduling switch to be on for the organization."
1442
- ],
1443
- dataSensitivity: "internal",
1444
- risk: "observe"
1445
- }
1446
- ];
1447
-
1448
- // src/agent/routing-tools.ts
1449
- var SUMMARY_FIELDS = "id, name, slug, description, isActive, updatedAt";
1450
- var FORM_FIELDS = "id, name, slug, description, isActive, questions, rules, fallback, createdAt, updatedAt";
1451
- var FORM_ID = { name: "id", type: "string", required: true, description: "Routing form id" };
1452
- var NOT_ENABLED3 = "A server without routing forms answers 501.";
1453
- var DETAILS = "A form with any problem is refused with 400 and nothing is saved; for a problem in the form itself, details lists every one with its path (such as rules[1].conditions[0].value) and the reason. A body of the wrong shape (a missing fallback, a list that is too long) is refused earlier with 400 and details that name the field instead.";
1454
- var QUESTIONS = "A list of 1 to 20 questions, each an object with id (starts with a letter; letters, digits, - and _; at most 40 characters; different for each question), label (1 to 200 characters), type (select, radio, checkbox, text or number), required (true or false; false if left out) and, for select, radio and checkbox only, options (2 to 50 different choices of 1 to 100 characters).";
1455
- var RULES = `A list of 1 to 50 rules, tried in order; the first whose conditions hold decides where the client goes. Each rule is an object with match ("all" conditions must hold, or "any"; "all" if left out), conditions (1 to 10, each an object with questionId, operator and value) and destination (an object with typeId, calendarId or both), and optionally id (made up if left out) and label (up to 200 characters). Operators by question type: select and radio take equals, not_equals, in, is_answered, is_empty; checkbox takes contains, not_contains, is_answered, is_empty; text takes equals, not_equals, contains, not_contains, is_answered, is_empty; number takes equals, not_equals, gt, gte, lt, lte, is_answered, is_empty. For in the value is a list of the question's options. Otherwise the value is one of the question's options, or a text of 1 to 200 characters for a text question, or a number; is_answered and is_empty take no value.`;
1456
- var FALLBACK = 'What happens when no rule matches. Either { "kind": "DESTINATION", "destination": { typeId and/or calendarId } } to send the client somewhere anyway, or { "kind": "MESSAGE", "message": "1 to 500 characters" } to show a message.';
1457
- var ROUTING_TOOLS = [
1458
- {
1459
- name: "scheduling_list_routing_forms",
1460
- module: "scheduling",
1461
- method: "GET",
1462
- route: "/admin/routing-forms",
1463
- auth: "session_cookie",
1464
- description: "List the routing forms of the organization, by name, with whether each is switched on.",
1465
- params: [],
1466
- example: {},
1467
- responseShape: `{ forms: [{ ${SUMMARY_FIELDS} }] }`,
1468
- whenToUse: "To find a form id or slug. Read one form in full with scheduling_get_routing_form.",
1469
- pitfalls: ["The list has no questions or rules; it is a summary.", "The answer is a plain list with no paging, ordered by name.", NOT_ENABLED3, "Needs the scheduling switch to be on for the organization."],
1470
- dataSensitivity: "internal",
1471
- risk: "observe"
1472
- },
1473
- {
1474
- name: "scheduling_get_routing_form",
1475
- module: "scheduling",
1476
- method: "GET",
1477
- route: "/admin/routing-forms/[id]",
1478
- auth: "session_cookie",
1479
- description: "Read one routing form in full: its questions, its rules and what happens when no rule matches.",
1480
- params: [FORM_ID],
1481
- example: { id: "form_1" },
1482
- responseShape: `{ form: { ${FORM_FIELDS} } }`,
1483
- whenToUse: "Before changing a form, to see what it is now and send back what should stay.",
1484
- pitfalls: ["A form of another organization is a plain 404.", NOT_ENABLED3, "Needs the scheduling switch to be on for the organization."],
1485
- dataSensitivity: "internal",
1486
- risk: "observe"
1487
- },
1488
- {
1489
- name: "scheduling_create_routing_form",
1490
- module: "scheduling",
1491
- method: "POST",
1492
- route: "/admin/routing-forms",
1493
- auth: "session_cookie",
1494
- description: "Create a routing form that asks a client a few questions and sends them to the right appointment type or calendar.",
1495
- params: [
1496
- { name: "name", type: "string", required: true, description: "Name for staff, 1 to 100 characters" },
1497
- { name: "slug", type: "string", required: true, description: "Short name used in the form's public address: lower-case words joined by dashes, at most 60 characters. No other organization on the server may use the same one." },
1498
- { name: "description", type: "string", required: false, description: "A line shown above the questions, up to 500 characters" },
1499
- { name: "isActive", type: "boolean", required: false, description: "Whether clients can use it; true if left out" },
1500
- { name: "questions", type: "json-array", required: true, description: QUESTIONS },
1501
- { name: "rules", type: "json-array", required: true, description: RULES },
1502
- { name: "fallback", type: "json-object", required: true, description: FALLBACK }
1503
- ],
1504
- example: {
1505
- name: "Which service?",
1506
- slug: "which-service",
1507
- questions: [{ id: "goal", label: "What do you need?", type: "radio", required: true, options: ["A new suit", "An alteration"] }],
1508
- rules: [{ conditions: [{ questionId: "goal", operator: "equals", value: "An alteration" }], destination: { typeId: "type_1" } }],
1509
- fallback: { kind: "MESSAGE", message: "Please call us to book." }
1510
- },
1511
- responseShape: `{ form: { ${FORM_FIELDS} } }`,
1512
- whenToUse: "When clients need help choosing the right service. Try it with scheduling_test_routing_form before sharing the link.",
1513
- pitfalls: [
1514
- DETAILS,
1515
- "Every type and calendar a rule or the fallback names must exist, be switched on and, when both are named, the type must be offered on that calendar; otherwise it is refused with 400.",
1516
- "A slug that another organization uses is refused with 400 (details names slug); the same slug on two of your own forms, or a 51st form, is refused with 409.",
1517
- "At least one rule is required.",
1518
- NOT_ENABLED3,
1519
- "Needs the scheduling switch to be on for the organization."
1520
- ],
1521
- dataSensitivity: "internal",
1522
- risk: "act",
1523
- requiresApproval: {
1524
- action: "Create a routing form",
1525
- reason: "Clients who use the form are sent wherever its rules say.",
1526
- prompt: 'Create the routing form "{name}"?'
1527
- }
1528
- },
1529
- {
1530
- name: "scheduling_update_routing_form",
1531
- module: "scheduling",
1532
- method: "PUT",
1533
- route: "/admin/routing-forms/[id]",
1534
- auth: "session_cookie",
1535
- description: "Change a routing form, or switch it off. Only the fields you send change; the whole form is checked again afterwards.",
1536
- params: [
1537
- FORM_ID,
1538
- { name: "name", type: "string", required: false, description: "Name for staff, 1 to 100 characters" },
1539
- { name: "slug", type: "string", required: false, description: "Public short name; changing it breaks links that use the old one" },
1540
- { name: "description", type: "string", required: false, description: "A line shown above the questions, up to 500 characters, or null to clear it" },
1541
- { name: "isActive", type: "boolean", required: false, description: "false stops clients using it; true switches it back on" },
1542
- { name: "questions", type: "json-array", required: false, description: `${QUESTIONS} Replaces the whole list.` },
1543
- { name: "rules", type: "json-array", required: false, description: `${RULES} Replaces the whole list.` },
1544
- { name: "fallback", type: "json-object", required: false, description: `${FALLBACK} Replaces the current fallback.` }
1545
- ],
1546
- example: { id: "form_1", isActive: false },
1547
- responseShape: `{ form: { ${FORM_FIELDS} } }`,
1548
- whenToUse: "To reword a question, add a rule, or switch a form off. Read the form first, because questions, rules and fallback replace what is there.",
1549
- pitfalls: [
1550
- "Send at least one field, or it is refused with 400.",
1551
- DETAILS,
1552
- "Changing a question can break a rule that uses it, so the whole result is checked; the destinations are checked again only when questions, rules or the fallback are sent, so renaming or switching off a form always works.",
1553
- "A slug that another organization uses is refused with 400, and one that another of your own forms uses with 409. A form of another organization is a plain 404.",
1554
- NOT_ENABLED3,
1555
- "Needs the scheduling switch to be on for the organization."
1556
- ],
1557
- dataSensitivity: "internal",
1558
- risk: "act",
1559
- requiresApproval: {
1560
- action: "Change a routing form",
1561
- reason: "Clients are sent wherever the changed rules say, and a changed slug breaks links already shared.",
1562
- prompt: "Change routing form {id}?"
1563
- }
1564
- },
1565
- {
1566
- name: "scheduling_delete_routing_form",
1567
- module: "scheduling",
1568
- method: "DELETE",
1569
- route: "/admin/routing-forms/[id]",
1570
- auth: "session_cookie",
1571
- description: "Delete a routing form for good.",
1572
- params: [FORM_ID],
1573
- example: { id: "form_1" },
1574
- responseShape: "{ success: true }",
1575
- whenToUse: "Only to remove a form that is no longer wanted. To stop clients using one for now, switch it off with scheduling_update_routing_form.",
1576
- pitfalls: ["A link to the form stops working at once.", "A deleted form cannot be brought back.", "A form of another organization is a plain 404.", NOT_ENABLED3, "Needs the scheduling switch to be on for the organization."],
1577
- dataSensitivity: "internal",
1578
- risk: "act",
1579
- requiresApproval: {
1580
- action: "Delete a routing form",
1581
- reason: "The form is removed for good and any link to it stops working.",
1582
- prompt: "Delete routing form {id}? This cannot be undone."
1583
- }
1584
- },
1585
- {
1586
- name: "scheduling_test_routing_form",
1587
- module: "scheduling",
1588
- method: "POST",
1589
- route: "/admin/routing-forms/[id]/test",
1590
- auth: "session_cookie",
1591
- description: "Try sample answers on a routing form and see where a client would be sent. Nothing is saved or booked.",
1592
- params: [
1593
- FORM_ID,
1594
- { name: "answers", type: "json-object", required: true, description: "The sample answers, an object keyed by question id: a text for select, radio and text questions, a list of options for checkbox, a number for number. Every required question needs an answer, nothing the form does not ask is allowed, and a text answer is at most 1000 characters." }
1595
- ],
1596
- example: { id: "form_1", answers: { goal: "An alteration" } },
1597
- responseShape: "{ destination, message, matchedRuleId, usedFallback, allMatchedRuleIds }",
1598
- whenToUse: "After creating or changing a form, to check each path before clients use it.",
1599
- pitfalls: [
1600
- "It works even when the form is switched off.",
1601
- "allMatchedRuleIds lists every rule the answers satisfy, in order, even those not live; only the first live one decides, and its id is matchedRuleId. destination is null, and message is set, when the form says to show a message or when the fallback destination is gone. It carries typeId, typeSlug, typeName, calendarId, calendarSlug and calendarName.",
1602
- "A rule whose destination has since been switched off is skipped and the next matching rule is tried; if the fallback destination is also gone, message tells the client to get in touch.",
1603
- "Answers that do not fit the form are refused with 400 and details.",
1604
- "It changes nothing, but it is a POST, so it asks first.",
1605
- NOT_ENABLED3
1606
- ],
1607
- dataSensitivity: "none",
1608
- risk: "act",
1609
- requiresApproval: {
1610
- action: "Test a routing form",
1611
- reason: "It runs the form against sample answers; nothing is changed.",
1612
- prompt: "Test routing form {id} with these answers?"
1613
- }
1614
- }
1615
- ];
1616
-
1617
- // src/agent/series-tools.ts
1618
- var SERIES_FIELDS = "id, organizationId, calendarId, typeId, frequency, occurrences, startTimeLocal, durationMins, timezone, endsAt, clientEmail, clientName, clientPhone, clientId, notes, status, createdAt, updatedAt";
1619
- var FREQUENCIES = ["DAILY", "WEEKLY", "BIWEEKLY", "MONTHLY"];
1620
- var SCOPES = ["ONE", "THIS_AND_FOLLOWING", "ALL"];
1621
- var SERIES_TOOLS = [
1622
- {
1623
- name: "scheduling_list_recurring_series",
1624
- module: "scheduling",
1625
- method: "GET",
1626
- route: "/admin/recurring",
1627
- auth: "session_cookie",
1628
- description: "List repeating series of appointments, newest first, each with its calendar, its appointment type and the status of every occurrence.",
1629
- params: [
1630
- { name: "limit", type: "number", required: false, description: "How many series to return (default 50, at most 200)" },
1631
- { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
1632
- ],
1633
- example: {},
1634
- responseShape: `{ series: [{ ${SERIES_FIELDS}, calendar: { id, name }, type: { id, name }, appointments: [{ id, status }] }], total, hasMore }`,
1635
- whenToUse: "To find a series id, or to see which series a client has.",
1636
- pitfalls: [
1637
- "Only series on calendars the person may see are listed.",
1638
- "The appointments inside each series carry only id and status. Read one series with scheduling_get_recurring_series for the times.",
1639
- "Needs the scheduling switch to be on for the organization."
1640
- ],
1641
- dataSensitivity: "sensitive",
1642
- risk: "observe"
1643
- },
1644
- {
1645
- name: "scheduling_get_recurring_series",
1646
- module: "scheduling",
1647
- method: "GET",
1648
- route: "/admin/recurring/[id]",
1649
- auth: "session_cookie",
1650
- description: "Read one repeating series with every occurrence in order, with its start and end time, status and notes.",
1651
- params: [{ name: "id", type: "string", required: true, description: "Series id" }],
1652
- example: { id: "series_1" },
1653
- responseShape: `{ series: { ${SERIES_FIELDS}, calendar: { id, name, userId }, type: { id, name, duration }, appointments: [{ id, status, startTime, endTime, recurringIndex, notes, clientName }] } }`,
1654
- whenToUse: "Before cancelling part of a series, to find the id of the occurrence to cancel from.",
1655
- pitfalls: [
1656
- "A series of another organization, or on a calendar the person may not see, is a plain 404.",
1657
- "Times are UTC. The series timezone says which clock the visits were set on."
1658
- ],
1659
- dataSensitivity: "sensitive",
1660
- risk: "observe"
1661
- },
1662
- {
1663
- name: "scheduling_create_recurring_series",
1664
- module: "scheduling",
1665
- method: "POST",
1666
- route: "/admin/recurring",
1667
- auth: "session_cookie",
1668
- description: "Book a client into a repeating series: the same time on a repeating day, for a number of visits, all confirmed at once.",
1669
- params: [
1670
- { name: "calendarId", type: "string", required: true, description: "Calendar the visits go on" },
1671
- { name: "typeId", type: "string", required: true, description: "Appointment type; it sets how long each visit is. It must be active." },
1672
- { name: "frequency", type: "string", required: true, description: "How often the visits repeat", allowedValues: FREQUENCIES },
1673
- { name: "occurrences", type: "number", required: true, description: "How many visits to book, 1 to 104" },
1674
- { name: "startTimeLocal", type: "string", required: true, description: "Clock time of every visit as HH:MM on a 24-hour clock, read in the timezone parameter, for example 14:30" },
1675
- { name: "firstDate", type: "string", required: true, description: "Date of the first visit as YYYY-MM-DD, read in the timezone parameter" },
1676
- { name: "timezone", type: "string", required: false, description: "IANA zone name such as America/Chicago that startTimeLocal is read in; America/New_York if left out. Send the calendar's own zone." },
1677
- { name: "endsAt", type: "string", required: false, description: "Last date to book a visit on, as an ISO 8601 UTC date-time such as 2026-12-31T00:00:00Z. Only the date is compared: a visit on that UTC date is still booked, whatever its clock time, and none on a later date is. The series may end up with fewer visits than occurrences." },
1678
- { name: "clientEmail", type: "string", required: true, description: "Client email address" },
1679
- { name: "clientName", type: "string", required: true, description: "Client name, 1 to 200 characters" },
1680
- { name: "clientPhone", type: "string", required: false, description: "Client phone number, up to 30 characters" },
1681
- { name: "clientId", type: "string", required: false, description: "Id of the client record in the host system, when known. The host may ignore it and match by email." },
1682
- { name: "notes", type: "string", required: false, description: "Note copied onto every visit, up to 1000 characters" }
1683
- ],
1684
- example: { calendarId: "cal_1", typeId: "type_1", frequency: "WEEKLY", occurrences: 6, startTimeLocal: "14:30", firstDate: "2026-12-01", timezone: "America/New_York", clientEmail: "sam@example.com", clientName: "Sam Rivera" },
1685
- responseShape: `{ series: { ${SERIES_FIELDS} }, occurrences, warnings? }`,
1686
- whenToUse: "When one client needs the same slot repeatedly, such as a weekly session or a fitting course. For a single visit use scheduling_book_appointment.",
1687
- pitfalls: [
1688
- "It does not check opening hours or free times: a visit is saved at the time asked for, even on a closed day or overlapping another booking. Only a visit that starts at exactly the same moment as a booking already on the calendar is refused, with 409, and then nothing is saved. Check the dates with scheduling_check_availability first.",
1689
- "startTimeLocal and firstDate are read in the timezone you send, not in the calendar's own zone. An unknown zone name is refused with 422.",
1690
- "A monthly series from the 31st uses the last day of shorter months and goes back to the 31st when the month has one.",
1691
- "Every visit is confirmed straight away: the type's approval and payment settings do not apply to a series.",
1692
- "The visits are saved together or not at all. warnings, when present, lists follow-up steps that failed after saving (reminders, calendar entries, the staff alert); the series is saved regardless.",
1693
- "The calendar, or the type, not being found (or inactive) is refused with 404; so is a calendar the person may not see.",
1694
- "Needs the scheduling switch to be on for the organization."
1695
- ],
1696
- dataSensitivity: "sensitive",
1697
- risk: "act",
1698
- requiresApproval: {
1699
- action: "Create a recurring series",
1700
- reason: "Many appointments are confirmed at once, with reminders scheduled for the client, and none is checked against opening hours or overlapping bookings.",
1701
- prompt: "Book {occurrences} {frequency} visits for {clientName} from {firstDate}?"
1702
- }
1703
- },
1704
- {
1705
- name: "scheduling_cancel_recurring_series",
1706
- module: "scheduling",
1707
- method: "PATCH",
1708
- route: "/admin/recurring/[id]",
1709
- auth: "session_cookie",
1710
- description: "Cancel one visit of a series, one visit and every later one, or the whole series. Visits already cancelled, completed or marked no-show are left alone.",
1711
- params: [
1712
- { name: "id", type: "string", required: true, description: "Series id" },
1713
- { name: "scope", type: "string", required: true, description: "ONE cancels only the visit in fromAppointmentId; THIS_AND_FOLLOWING cancels that visit and every later one; ALL cancels every open visit", allowedValues: SCOPES },
1714
- { name: "fromAppointmentId", type: "string", required: false, description: "Id of the visit to start from. Required for ONE and THIS_AND_FOLLOWING, and it must belong to this series." }
1715
- ],
1716
- example: { id: "series_1", scope: "THIS_AND_FOLLOWING", fromAppointmentId: "appt_3" },
1717
- responseShape: "{ cancelledCount, newSeriesStatus, warnings? }",
1718
- whenToUse: "When a client stops coming or a staff member is away for a while. To move one visit, use scheduling_reschedule_appointment; to cancel a single booking outside a series, use scheduling_cancel_appointment.",
1719
- pitfalls: [
1720
- "The series becomes ACTIVE after ONE, ENDED after THIS_AND_FOLLOWING and CANCELLED after ALL.",
1721
- "Each cancelled visit gets follow-up steps: its reminders are dropped, its calendar entry is removed, a visit that was paid is flagged for a refund decision and staff are alerted once. warnings lists any step that failed; the visits are cancelled regardless. The client is not sent a cancellation message by this tool.",
1722
- "If any open visit is on a calendar the person may not see, nothing is cancelled and the answer is a plain 404.",
1723
- "This cannot be undone. A cancelled visit cannot be reopened; book a new one instead.",
1724
- "Needs no scheduling switch, and is open to any signed-in staff member."
1725
- ],
1726
- dataSensitivity: "sensitive",
1727
- risk: "act",
1728
- requiresApproval: {
1729
- action: "Cancel a recurring series",
1730
- reason: "Several client appointments are cancelled at once, which cannot be undone, and paid visits are flagged for refund.",
1731
- prompt: "Cancel ({scope}) in series {id}?"
1732
- }
1733
- },
1734
- {
1735
- name: "scheduling_list_group_sessions",
1736
- module: "scheduling",
1737
- method: "GET",
1738
- route: "/admin/group-sessions",
1739
- auth: "session_cookie",
1740
- description: "List the group sessions held in a date range, each with how many seats are taken and who is booked.",
1741
- params: [
1742
- { name: "startDate", type: "string", required: true, description: "Start of the range as an ISO 8601 UTC date-time such as 2026-12-01T00:00:00Z; sessions from this moment on" },
1743
- { name: "endDate", type: "string", required: true, description: "End of the range as an ISO 8601 UTC date-time, later than startDate and at most 366 days after it; sessions before this moment" },
1744
- { name: "calendarId", type: "string", required: false, description: "Only sessions on this calendar" }
1745
- ],
1746
- example: { startDate: "2026-12-01T00:00:00Z", endDate: "2026-12-08T00:00:00Z" },
1747
- responseShape: "{ sessions: [{ typeId, typeName, typeColor, maxSeats, calendarId, calendarName, staffName, startTime, endTime, seatsBooked, seatsAvailable, isFull, attendees }], total, hasMore }",
1748
- whenToUse: "To see how full a class is, or who is coming. A person books a seat with scheduling_book_appointment on a type that has isGroup true.",
1749
- pitfalls: [
1750
- "seatsBooked counts pending and confirmed bookings only; cancelled, completed and no-show attendees are listed but take no seat.",
1751
- "maxSeats and seatsAvailable are null when the type has no seat limit, and isFull is then false.",
1752
- "hasMore true means the range holds more than 1000 bookings and some sessions are missing. Ask for a shorter range.",
1753
- "Both dates are required. A range longer than 366 days, or one that ends before it starts, is refused with 400.",
1754
- "Attendees carry names, emails and phone numbers."
1755
- ],
1756
- dataSensitivity: "sensitive",
1757
- risk: "observe"
1758
- }
1759
- ];
1760
-
1761
- // src/agent/settings-tools.ts
1762
- var CATEGORY_FIELDS = "id, organizationId, name, sortOrder, createdAt";
1763
- var TEMPLATE_FIELDS = "id, organizationId, name, channel, trigger, recipientType, subject, body, isActive";
1764
- var BRAND_FIELDS = "displayName, logoUrl, primaryColor, accentColor, backgroundColor, textColor, fontFamily, footerText, replyToEmail, fromName, fromEmail, updatedAt";
1765
- var TRIGGERS = ["CONFIRMATION", "REMINDER_24H", "REMINDER_1H", "FOLLOWUP", "CANCELLATION", "RESCHEDULE"];
1766
- var TEMPLATE_VARIABLES = "Write {{name}} where a value should go. Available: clientName, clientEmail, clientPhone, serviceName, dateTime, duration, calendarName, staffName, location, manageUrl, icalUrl, meetingUrl, time, appointmentStatus, intake_<id of an intake question>, and brandName, brandLogoUrl, brandColor, brandFooter when the server has branding. A value the appointment does not have (for example staffName with no staff name) is left in the message as the literal {{staffName}}.";
1767
- var BODY_LIMITS = "An email body keeps only b, i, em, strong, a (href), br, p, ul, ol and li tags; an SMS body has every tag removed.";
1768
- var SETTINGS_TOOLS = [
1769
- {
1770
- name: "scheduling_list_categories",
1771
- module: "scheduling",
1772
- method: "GET",
1773
- route: "/admin/categories",
1774
- auth: "session_cookie",
1775
- description: "List the appointment categories, in the order they are shown.",
1776
- params: [],
1777
- example: {},
1778
- responseShape: `[{ ${CATEGORY_FIELDS} }]`,
1779
- whenToUse: "To find a category id, for example to file an appointment type under it.",
1780
- pitfalls: ["The answer is a plain list with no paging, lowest sortOrder first.", "Needs the scheduling switch to be on for the organization."],
1781
- dataSensitivity: "none",
1782
- risk: "observe"
1783
- },
1784
- {
1785
- name: "scheduling_create_category",
1786
- module: "scheduling",
1787
- method: "POST",
1788
- route: "/admin/categories",
1789
- auth: "session_cookie",
1790
- description: "Create an appointment category for grouping appointment types on the booking page.",
1791
- params: [{ name: "name", type: "string", required: true, description: "Category name, 1 to 50 characters" }],
1792
- example: { name: "Fittings" },
1793
- responseShape: `{ ${CATEGORY_FIELDS} }`,
1794
- whenToUse: "When appointment types need a new group. File a type under it with categoryId in scheduling_update_appointment_type.",
1795
- pitfalls: [
1796
- "A new category starts at sortOrder 0. Set the order afterwards with scheduling_update_category.",
1797
- "A category with the same name already existing is refused with 409. Names are unique across the whole database, so a name used by another organization is refused too.",
1798
- "Needs the scheduling switch to be on for the organization."
1799
- ],
1800
- dataSensitivity: "none",
1801
- risk: "act",
1802
- requiresApproval: {
1803
- action: "Create a category",
1804
- reason: "A new category becomes visible to clients on the booking page once a type is filed under it.",
1805
- prompt: 'Create the appointment category "{name}"?'
1806
- }
1807
- },
1808
- {
1809
- name: "scheduling_update_category",
1810
- module: "scheduling",
1811
- method: "PATCH",
1812
- route: "/admin/categories",
1813
- auth: "session_cookie",
1814
- description: "Rename a category or change its position in the list.",
1815
- params: [
1816
- { name: "id", type: "string", required: true, description: "Category id" },
1817
- { name: "name", type: "string", required: false, description: "New name, 1 to 50 characters" },
1818
- { name: "sortOrder", type: "number", required: false, description: "Position in lists as a whole number of 0 or more, lowest first" }
1819
- ],
1820
- example: { id: "cat_1", name: "Suit fittings", sortOrder: 2 },
1821
- responseShape: `{ ${CATEGORY_FIELDS} }`,
1822
- whenToUse: "To rename a category or reorder the list. Send name, sortOrder or both.",
1823
- pitfalls: [
1824
- "Sending neither name nor sortOrder is refused with 400.",
1825
- "Another category already having that name is refused with 409. A category of another organization is a plain 404.",
1826
- "Needs the scheduling switch to be on for the organization."
1827
- ],
1828
- dataSensitivity: "none",
1829
- risk: "act",
1830
- requiresApproval: {
1831
- action: "Change a category",
1832
- reason: "The name and order are what clients see on the booking page.",
1833
- prompt: "Change category {id}?"
1834
- }
1835
- },
1836
- {
1837
- name: "scheduling_delete_category",
1838
- module: "scheduling",
1839
- method: "DELETE",
1840
- route: "/admin/categories",
1841
- auth: "session_cookie",
1842
- description: "Delete a category that no appointment type uses.",
1843
- params: [{ name: "id", type: "string", required: true, description: "Category id" }],
1844
- example: { id: "cat_1" },
1845
- responseShape: "{ success: true }",
1846
- whenToUse: "To remove a category that is no longer wanted, after moving its types elsewhere.",
1847
- pitfalls: [
1848
- "Refused with 409 while any appointment type uses it. Move or clear those types first with categoryId in scheduling_update_appointment_type.",
1849
- "A deleted category cannot be brought back.",
1850
- "Needs the scheduling switch to be on for the organization."
1851
- ],
1852
- dataSensitivity: "none",
1853
- risk: "act",
1854
- requiresApproval: {
1855
- action: "Delete a category",
1856
- reason: "The category is removed for good.",
1857
- prompt: "Delete category {id}? This cannot be undone."
1858
- }
1859
- },
1860
- {
1861
- name: "scheduling_list_message_templates",
1862
- module: "scheduling",
1863
- method: "GET",
1864
- route: "/admin/templates",
1865
- auth: "session_cookie",
1866
- description: "List the message templates: the email and text messages sent to clients and staff when a booking is confirmed, reminded, followed up, cancelled or moved.",
1867
- params: [],
1868
- example: {},
1869
- responseShape: `[{ ${TEMPLATE_FIELDS} }]`,
1870
- whenToUse: "To see what messages are set up and which are switched on, and to find a template id.",
1871
- pitfalls: [
1872
- "The answer is a plain list with no paging, ordered by channel, then trigger, then name.",
1873
- "An organization with no templates sends no messages at all.",
1874
- "Needs the scheduling switch to be on for the organization."
1875
- ],
1876
- dataSensitivity: "internal",
1877
- risk: "observe"
1878
- },
1879
- {
1880
- name: "scheduling_create_message_template",
1881
- module: "scheduling",
1882
- method: "POST",
1883
- route: "/admin/templates",
1884
- auth: "session_cookie",
1885
- description: "Create the message sent for one trigger on one channel to one kind of recipient.",
1886
- params: [
1887
- { name: "name", type: "string", required: true, description: "Name for staff to recognise it by, 1 to 100 characters" },
1888
- { name: "channel", type: "string", required: true, description: "How it is sent", allowedValues: ["EMAIL", "SMS"] },
1889
- { name: "trigger", type: "string", required: true, description: "When it is sent: CONFIRMATION when booked, REMINDER_24H and REMINDER_1H before the visit (the actual lead times are set on each appointment type), FOLLOWUP after it, CANCELLATION and RESCHEDULE when it is cancelled or moved", allowedValues: TRIGGERS },
1890
- { name: "recipientType", type: "string", required: false, description: "Who receives it: CLIENT (the booking's client) or STAFF; CLIENT if left out. A STAFF template is sent at once to the calendar's staff email address, only for the CONFIRMATION, CANCELLATION and RESCHEDULE triggers, and only when the calendar has a staff email. Use the EMAIL channel for it: a STAFF template on the SMS channel is queued as a text addressed to an email address and is not delivered as an email. A STAFF template for any other trigger is saved but never sent.", allowedValues: ["CLIENT", "STAFF"] },
1891
- { name: "subject", type: "string", required: false, description: "Email subject, up to 200 characters. Required for EMAIL (not blank), refused for SMS. HTML tags are removed. You may use the {{name}} values listed in the body description." },
1892
- { name: "body", type: "string", required: true, description: `Message text, 1 to 5000 characters. ${BODY_LIMITS} ${TEMPLATE_VARIABLES}` },
1893
- { name: "isActive", type: "boolean", required: false, description: "Whether it is sent; true if left out" }
1894
- ],
1895
- example: { name: "Day-before reminder", channel: "EMAIL", trigger: "REMINDER_24H", subject: "See you tomorrow, {{clientName}}", body: "<p>Hello {{clientName}}, this is a reminder of your {{serviceName}} on {{dateTime}}.</p>" },
1896
- responseShape: `{ ${TEMPLATE_FIELDS} }`,
1897
- whenToUse: "When a kind of message is missing. There is one template for each combination of channel, trigger and recipientType.",
1898
- pitfalls: [
1899
- "A template for the same channel, trigger and recipientType already existing is refused with 409. Change the existing one with scheduling_update_message_template.",
1900
- "An EMAIL template needs a subject and an SMS template must not have one: both refused with 400.",
1901
- "A CLIENT SMS goes only to bookings that have a client phone number. A STAFF template is sent only for CONFIRMATION, CANCELLATION and RESCHEDULE, at once, to the calendar's staff email, and only on the EMAIL channel; there are no staff reminders or follow-ups.",
1902
- "A reminder whose time has already passed when the booking is made is skipped, and a lead time of 0 on the appointment type switches that reminder or follow-up off. Bookings waiting for approval get no reminders or follow-ups until they are approved.",
1903
- "Reminders and follow-ups are scheduled when a booking is made, so a new template does not reach bookings that already exist.",
1904
- "Needs the scheduling switch to be on for the organization."
1905
- ],
1906
- dataSensitivity: "internal",
1907
- risk: "act",
1908
- requiresApproval: {
1909
- action: "Create a message template",
1910
- reason: "From then on, real clients or staff receive this message automatically for every matching booking.",
1911
- prompt: 'Create the {channel} message "{name}" for {trigger}?'
1912
- }
1913
- },
1914
- {
1915
- name: "scheduling_update_message_template",
1916
- module: "scheduling",
1917
- method: "PUT",
1918
- route: "/admin/templates/[id]",
1919
- auth: "session_cookie",
1920
- description: "Change the name, subject, text or on/off switch of a message template. Only the fields you send change.",
1921
- params: [
1922
- { name: "id", type: "string", required: true, description: "Template id" },
1923
- { name: "name", type: "string", required: false, description: "Name for staff, 1 to 100 characters" },
1924
- { name: "subject", type: "string", required: false, description: "Email subject, up to 200 characters. An EMAIL template cannot be left without one; an SMS template must have none (send null to clear it)." },
1925
- { name: "body", type: "string", required: false, description: `Message text, 1 to 5000 characters. ${BODY_LIMITS} ${TEMPLATE_VARIABLES}` },
1926
- { name: "isActive", type: "boolean", required: false, description: "true sends the message; false stops it for bookings and events from then on without deleting the template. Reminders and follow-ups already queued for existing bookings are still sent." }
1927
- ],
1928
- example: { id: "tpl_1", body: "<p>Hello {{clientName}}, see you on {{dateTime}}.</p>", isActive: true },
1929
- responseShape: `{ ${TEMPLATE_FIELDS} }`,
1930
- whenToUse: "To reword a message or pause it for future bookings. To pause temporarily, set isActive false rather than deleting.",
1931
- pitfalls: [
1932
- "Channel, trigger and recipientType cannot be changed: sending any of them is refused with 400. Create a new template instead.",
1933
- "Reminders and follow-ups already scheduled for existing bookings keep their text and are still sent, whether the template is changed, paused or deleted afterwards; only cancelling the appointment drops them. Cancellation, reschedule and staff messages are written from the current template at the moment they are sent, and a booking that is later moved or approved gets its reminders made from the current template.",
1934
- "A template of another organization is a plain 404.",
1935
- "Needs the scheduling switch to be on for the organization."
1936
- ],
1937
- dataSensitivity: "internal",
1938
- risk: "act",
1939
- requiresApproval: {
1940
- action: "Change a message template",
1941
- reason: "Clients or staff receive the changed wording, or stop receiving the message, for future bookings and for cancellation, reschedule and staff messages sent from then on; reminders already queued are not affected.",
1942
- prompt: "Change message template {id}?"
1943
- }
1944
- },
1945
- {
1946
- name: "scheduling_delete_message_template",
1947
- module: "scheduling",
1948
- method: "DELETE",
1949
- route: "/admin/templates/[id]",
1950
- auth: "session_cookie",
1951
- description: "Delete a message template for good.",
1952
- params: [{ name: "id", type: "string", required: true, description: "Template id" }],
1953
- example: { id: "tpl_1" },
1954
- responseShape: "{ success: true }",
1955
- whenToUse: "Only to remove a template that is no longer wanted. To pause one, use scheduling_update_message_template with isActive false.",
1956
- pitfalls: [
1957
- "With the template gone, that kind of message is no longer made for new bookings or events. Reminders and follow-ups already queued for existing bookings are still sent.",
1958
- "A deleted template cannot be brought back.",
1959
- "Needs the scheduling switch to be on for the organization."
1960
- ],
1961
- dataSensitivity: "internal",
1962
- risk: "act",
1963
- requiresApproval: {
1964
- action: "Delete a message template",
1965
- reason: "The template is removed for good and that kind of message is no longer made for new bookings or events.",
1966
- prompt: "Delete message template {id}? This cannot be undone."
1967
- }
1968
- },
1969
- {
1970
- name: "scheduling_get_brand",
1971
- module: "scheduling",
1972
- method: "GET",
1973
- route: "/admin/brand",
1974
- auth: "session_cookie",
1975
- description: "Read the organization's brand: its name, logo, colours, font, footer text and the sending identity of its emails.",
1976
- params: [],
1977
- example: {},
1978
- responseShape: `{ brand: { ${BRAND_FIELDS} } }`,
1979
- whenToUse: "Before changing the brand, to see what is set now.",
1980
- pitfalls: [
1981
- "brand is null when none has been saved.",
1982
- "Unlike the public booking page, this answer includes the reply-to and from addresses.",
1983
- "A server without branding answers 501.",
1984
- "Needs the scheduling switch to be on for the organization."
1985
- ],
1986
- dataSensitivity: "internal",
1987
- risk: "observe"
1988
- },
1989
- {
1990
- name: "scheduling_save_brand",
1991
- module: "scheduling",
1992
- method: "PUT",
1993
- route: "/admin/brand",
1994
- auth: "session_cookie",
1995
- description: "Save the organization's brand. This replaces the whole brand: a field you leave out is cleared, not kept.",
1996
- params: [
1997
- { name: "displayName", type: "string", required: true, description: "Business name shown to clients, 1 to 100 characters" },
1998
- { name: "logoUrl", type: "string", required: false, description: "Logo address: https only, no user name or password, up to 500 characters" },
1999
- { name: "primaryColor", type: "string", required: false, description: "Main colour as hex such as #1a2b3c" },
2000
- { name: "accentColor", type: "string", required: false, description: "Accent colour as hex such as #1a2b3c" },
2001
- { name: "backgroundColor", type: "string", required: false, description: "Background colour as hex such as #ffffff" },
2002
- { name: "textColor", type: "string", required: false, description: "Text colour as hex such as #111111" },
2003
- { name: "fontFamily", type: "string", required: false, description: "Font name, up to 100 characters of letters, digits, spaces, commas and dashes" },
2004
- { name: "footerText", type: "string", required: false, description: "Footer text, up to 300 characters. It appears in a message only where a template contains {{brandFooter}}, and it is returned to the booking page." },
2005
- { name: "replyToEmail", type: "string", required: false, description: "Address that client replies go to: one plain email address, up to 254 characters" },
2006
- { name: "fromName", type: "string", required: false, description: "Sender name on emails, up to 100 characters, without quotes, angle brackets, commas, semicolons, @ or backslashes" },
2007
- { name: "fromEmail", type: "string", required: false, description: "Address emails are sent from. Its domain must be one the server has confirmed; otherwise the whole save is refused." }
2008
- ],
2009
- example: { displayName: "Rivera Fittings", primaryColor: "#1a2b3c", accentColor: "#c9a227", footerText: "Thank you for booking with us." },
2010
- responseShape: `{ brand: { ${BRAND_FIELDS} } }`,
2011
- whenToUse: "To set or change how the business looks to clients. Read the brand first and send back every field that should stay.",
2012
- pitfalls: [
2013
- "It replaces everything. A field left out becomes empty, so a change to one colour must resend all the others.",
2014
- "A save that breaks a rule is refused with 400 and every problem is listed at once in details, each with its path and reason; nothing is saved. A body of the wrong shape (a text over its size limit, a field that does not exist) is refused earlier with 400 and details that name the field.",
2015
- "Colours are stored in lower case. Email addresses are stored in lower case.",
2016
- "fromEmail is accepted only for a domain the server has confirmed it may send from; a check that fails counts as not confirmed.",
2017
- "A server without branding answers 501.",
2018
- "Needs the scheduling switch to be on for the organization."
2019
- ],
2020
- dataSensitivity: "internal",
2021
- risk: "act",
2022
- requiresApproval: {
2023
- action: "Save the brand",
2024
- reason: "Clients see the new name and colours on the booking page straight away, the sender name, from address and reply-to apply to the emails sent from then on, and a new sending address changes who emails appear to come from.",
2025
- prompt: 'Save the brand "{displayName}"? This replaces the current brand.'
2026
- }
2027
- },
2028
- {
2029
- name: "scheduling_remove_brand",
2030
- module: "scheduling",
2031
- method: "DELETE",
2032
- route: "/admin/brand",
2033
- auth: "session_cookie",
2034
- description: "Remove the organization's brand, so clients see the server's default look and name.",
2035
- params: [],
2036
- example: {},
2037
- responseShape: "{ removed }",
2038
- whenToUse: "Only to go back to no custom brand. To change it, use scheduling_save_brand.",
2039
- pitfalls: [
2040
- "removed is false when there was no brand to remove; that is not an error.",
2041
- "A removed brand cannot be brought back; save it again.",
2042
- "A server without branding answers 501.",
2043
- "Needs the scheduling switch to be on for the organization."
2044
- ],
2045
- dataSensitivity: "internal",
2046
- risk: "act",
2047
- requiresApproval: {
2048
- action: "Remove the brand",
2049
- reason: "Clients lose the custom name, colours and sender at once.",
2050
- prompt: "Remove the brand? Clients will see the default look."
2051
- }
2052
- },
2053
- {
2054
- name: "scheduling_get_text_settings",
2055
- module: "scheduling",
2056
- method: "GET",
2057
- route: "/admin/text-settings",
2058
- auth: "session_cookie",
2059
- description: "Read which text-message provider and sending number the organization uses, and which providers the server offers.",
2060
- params: [],
2061
- example: {},
2062
- responseShape: "{ settings: { provider, fromNumber, enabled, updatedAt } | null, providers: string[] }",
2063
- whenToUse: "Before changing the text-message settings, or when the owner asks which number their texts come from.",
2064
- pitfalls: [
2065
- "settings is null when none has been saved; the organization then sends no texts of its own.",
2066
- "The provider accounts belong to the server; this holds only the choice and the number.",
2067
- "A server without text-message settings answers 501.",
2068
- "Needs the scheduling switch to be on for the organization."
2069
- ],
2070
- dataSensitivity: "internal",
2071
- risk: "observe"
2072
- },
2073
- {
2074
- name: "scheduling_save_text_settings",
2075
- module: "scheduling",
2076
- method: "PUT",
2077
- route: "/admin/text-settings",
2078
- auth: "session_cookie",
2079
- description: "Save the organization's text-message provider and sending number. This replaces the whole setting: enabled you leave out becomes true.",
2080
- params: [
2081
- { name: "provider", type: "string", required: true, description: "The text provider: one of the providers the server offers (TELNYX or TWILIO)" },
2082
- { name: "fromNumber", type: "string", required: true, description: "The number texts are sent from, such as +13135550100; ten US digits are read as a US number" },
2083
- { name: "enabled", type: "boolean", required: false, description: "False pauses texting without losing the number. Default true." }
2084
- ],
2085
- example: { provider: "TELNYX", fromNumber: "+13135550100" },
2086
- responseShape: "{ settings: { provider, fromNumber, enabled, updatedAt } }",
2087
- whenToUse: "To set up or change the number clients are texted from. Read the settings first.",
2088
- pitfalls: [
2089
- "It replaces everything; send enabled again to keep texting paused.",
2090
- "The number must be one the owner has with that provider; this does not buy or register a number.",
2091
- "A save that breaks a rule is refused with 400 and every problem is listed at once in details; nothing is saved.",
2092
- "A server without text-message settings answers 501.",
2093
- "Needs the scheduling switch to be on for the organization."
2094
- ],
2095
- dataSensitivity: "internal",
2096
- risk: "act",
2097
- requiresApproval: {
2098
- action: "Save the text-message settings",
2099
- reason: "Clients are texted from this number from now on, and a number that is not set up with the provider means their reminders are not delivered.",
2100
- prompt: "Save the text-message settings: send from {fromNumber} with {provider}?"
2101
- }
2102
- },
2103
- {
2104
- name: "scheduling_remove_text_settings",
2105
- module: "scheduling",
2106
- method: "DELETE",
2107
- route: "/admin/text-settings",
2108
- auth: "session_cookie",
2109
- description: "Remove the organization's text-message settings, so it sends no texts of its own.",
2110
- params: [],
2111
- example: {},
2112
- responseShape: "{ removed }",
2113
- whenToUse: "Only to stop texting from the organization's own number. To pause or change it, use scheduling_save_text_settings.",
2114
- pitfalls: [
2115
- "removed is false when there were no settings; that is not an error.",
2116
- "Text reminders stop being sent until settings are saved again.",
2117
- "A server without text-message settings answers 501.",
2118
- "Needs the scheduling switch to be on for the organization."
2119
- ],
2120
- dataSensitivity: "internal",
2121
- risk: "act",
2122
- requiresApproval: {
2123
- action: "Remove the text-message settings",
2124
- reason: "Clients stop receiving text reminders and confirmations at once.",
2125
- prompt: "Remove the text-message settings? Clients will no longer be texted."
2126
- }
2127
- }
2128
- ];
2129
-
2130
- // src/agent/type-tools.ts
2131
- var ID4 = { name: "id", type: "string", required: true, description: "Appointment type id" };
2132
- var TYPE_FIELDS = "id, name, slug, description, location, locationType, duration, color, price, deposit, currency, isGroup, maxSeats, assignmentStrategy, intakeForm, requiresPayment, requiresApproval, allowReschedule, allowCancel, cancelDeadlineHrs, reminder1MinsBefore, reminder2MinsBefore, followupMinsAfter, organizationId, categoryId, isActive, sortOrder, createdAt, updatedAt";
2133
- var LOCATION_TYPES = ["IN_PERSON", "TRAVEL_TO_CLIENT", "VIRTUAL", "PHONE"];
2134
- var STRATEGIES = ["NONE", "ROUND_ROBIN", "LOAD_BALANCED"];
2135
- var INTAKE_FORM = "A list of questions the client answers when booking. Each question is an object with id (1 to 100 characters, a different one for each question), type (one of text, email, phone, textarea, select, checkbox, radio, date, number), label (1 to 255 characters), required (true or false), and optionally placeholder (up to 255 characters), options (a list of up to 50 choices of 1 to 100 characters each; select, checkbox and radio questions must have at least one) and showIf (an object with fieldId, operator of equals, not_equals, contains, is_empty or is_not_empty, and value: show this question only when another answer matches).";
2136
- function typeFields(forUpdate) {
2137
- const when = (create, update) => forUpdate ? update : create;
2138
- return [
2139
- { name: "name", type: "string", required: !forUpdate, description: when("Name clients see, 1 to 100 characters. The booking address is made from it.", "Name clients see, 1 to 100 characters. The booking address does not change when a type is renamed.") },
2140
- { name: "description", type: "string", required: false, description: when("Short text shown on the booking page, up to 500 characters", "Short text shown on the booking page, up to 500 characters. Left out keeps the current text.") },
2141
- { name: "location", type: "string", required: false, description: when("Where it takes place, up to 500 characters", "Where it takes place, up to 500 characters, or null to clear it") },
2142
- { name: "locationType", type: "string", required: false, description: when("How the appointment is held; IN_PERSON if left out", "How the appointment is held"), allowedValues: LOCATION_TYPES },
2143
- { name: "duration", type: "number", required: !forUpdate, description: "Length in whole minutes, 5 to 480" },
2144
- { name: "color", type: "string", required: false, description: when("Calendar colour as #RRGGBB hex; #3B82F6 if left out", "Calendar colour as #RRGGBB hex") },
2145
- { name: "categoryId", type: "string", required: false, description: when("Id of an appointment category to file it under", "Id of an appointment category to file it under, or null to remove it from its category") },
2146
- { name: "price", type: "number", required: false, description: when("Price, 0 or more; none if left out", "Price, 0 or more, or null to clear it") },
2147
- { name: "deposit", type: "number", required: false, description: when("Deposit taken at booking, 0 or more; none if left out", "Deposit taken at booking, 0 or more, or null to clear it") },
2148
- { name: "requiresPayment", type: "boolean", required: false, description: when("Whether booking needs a payment; false if left out", "Whether booking needs a payment") },
2149
- { name: "requiresApproval", type: "boolean", required: false, description: when("Whether a person must approve each booking before it is confirmed; false if left out", "Whether a person must approve each booking before it is confirmed") },
2150
- { name: "allowReschedule", type: "boolean", required: false, description: when("Whether the client may move a booking; true if left out", "Whether the client may move a booking") },
2151
- { name: "allowCancel", type: "boolean", required: false, description: when("Whether the client may cancel a booking; true if left out", "Whether the client may cancel a booking") },
2152
- { name: "cancelDeadlineHrs", type: "number", required: false, description: when("Hours before the start after which the client can no longer cancel or move it, 0 to 720; 24 if left out", "Hours before the start after which the client can no longer cancel or move it, 0 to 720") },
2153
- { name: "reminder1MinsBefore", type: "number", required: false, description: when("Minutes before the start to send the first reminder, 0 to 10080; 1440 (one day) if left out", "Minutes before the start to send the first reminder, 0 to 10080") },
2154
- { name: "reminder2MinsBefore", type: "number", required: false, description: when("Minutes before the start to send the second reminder, 0 to 10080; 60 if left out", "Minutes before the start to send the second reminder, 0 to 10080") },
2155
- { name: "followupMinsAfter", type: "number", required: false, description: when("Minutes after the end to send the follow-up, 0 to 10080; 120 if left out", "Minutes after the end to send the follow-up, 0 to 10080") },
2156
- { name: "isGroup", type: "boolean", required: false, description: when("Whether several clients share one session; false if left out", "Whether several clients share one session") },
2157
- { name: "maxSeats", type: "number", required: false, description: when("Seats in a group session, at least 2; required when isGroup is true", "Seats in a group session, at least 2, or null to clear it; null is refused when isGroup is true") },
2158
- { name: "intakeForm", type: "json-array", required: false, description: when(INTAKE_FORM, `${INTAKE_FORM} Replaces the whole list; null removes the questions.`) },
2159
- { name: "calendarIds", type: "string[]", required: false, description: when("Ids of the calendars that offer this type", "Ids of the calendars that offer this type; replaces the current list") },
2160
- { name: "assignmentStrategy", type: "string", required: false, description: when("Who gets the booking on a type several calendars offer: NONE, ROUND_ROBIN (take turns) or LOAD_BALANCED (fewest bookings first); NONE if left out", "Who gets the booking on a type several calendars offer: NONE, ROUND_ROBIN (take turns) or LOAD_BALANCED (fewest bookings first)"), allowedValues: STRATEGIES },
2161
- { name: "sortOrder", type: "number", required: false, description: when("Accepted but ignored when creating: every new type starts at 0. Set it afterwards with scheduling_update_appointment_type", "Position in lists, lowest first") }
2162
- ];
2163
- }
2164
- var TYPE_TOOLS = [
2165
- {
2166
- name: "scheduling_list_all_appointment_types",
2167
- module: "scheduling",
2168
- method: "GET",
2169
- route: "/admin/types",
2170
- auth: "session_cookie",
2171
- description: "List every appointment type of the organization, inactive ones too, with the calendars that offer each, its category and which calendar took the last turn.",
2172
- params: [],
2173
- example: {},
2174
- responseShape: `[{ ${TYPE_FIELDS}, calendars: [{ calendar: { id, name } }], categoryRef, roundRobinState }]`,
2175
- whenToUse: "To find a type id or see how types are set up, including switched-off ones. For what a visitor sees on one calendar, use scheduling_list_appointment_types instead.",
2176
- pitfalls: ["The answer is a plain list with no paging.", "Needs the scheduling switch to be on for the organization."],
2177
- dataSensitivity: "internal",
2178
- risk: "observe"
2179
- },
2180
- {
2181
- name: "scheduling_create_appointment_type",
2182
- module: "scheduling",
2183
- method: "POST",
2184
- route: "/admin/types",
2185
- auth: "session_cookie",
2186
- description: "Create an appointment type. Its web address name (slug) is made from the name, and it starts active.",
2187
- params: [...typeFields(false)],
2188
- example: { name: "Consultation", duration: 45, price: 60, deposit: 20, requiresPayment: true, calendarIds: ["cal_1"] },
2189
- responseShape: `{ ${TYPE_FIELDS}, directoryClaimed }`,
2190
- whenToUse: "When something new needs to be bookable. Put it on a calendar with calendarIds, and make sure that calendar has opening hours.",
2191
- pitfalls: [
2192
- "A type with the same name, or a name that gives the same web address, already exists: refused with 409.",
2193
- "isGroup true needs maxSeats of at least 2.",
2194
- "ROUND_ROBIN and LOAD_BALANCED need at least one calendar in calendarIds: refused with 409 otherwise. Every calendar in calendarIds must belong to the organization, or it is refused with 409.",
2195
- "The first and second reminder must not be the same number of minutes (unless one is 0).",
2196
- "directoryClaimed false means the short booking address could not be registered; only the organization-qualified address works then.",
2197
- "Needs the scheduling switch to be on for the organization."
2198
- ],
2199
- dataSensitivity: "internal",
2200
- risk: "act",
2201
- requiresApproval: {
2202
- action: "Create an appointment type",
2203
- reason: "A new type becomes something clients can book, with its own price and booking address.",
2204
- prompt: 'Create the appointment type "{name}"?'
2205
- }
2206
- },
2207
- {
2208
- name: "scheduling_update_appointment_type",
2209
- module: "scheduling",
2210
- method: "PUT",
2211
- route: "/admin/types/[id]",
2212
- auth: "session_cookie",
2213
- description: "Change an appointment type. Only the fields you send change; a field left out stays as it is. Setting isActive to false switches it off.",
2214
- params: [
2215
- ID4,
2216
- ...typeFields(true),
2217
- { name: "isActive", type: "boolean", required: false, description: "false switches the type off so it can no longer be booked, true switches it back on" }
2218
- ],
2219
- example: { id: "type_1", duration: 60, price: 80 },
2220
- responseShape: `{ ${TYPE_FIELDS} }`,
2221
- whenToUse: "To change length, price, reminders or intake questions, move a type to other calendars, or switch it off or on.",
2222
- pitfalls: [
2223
- "Switching a type off releases its short booking address. Switching it back on does not give it back; only the organization-qualified address works until it is registered again.",
2224
- "Bookings that already exist keep their time; a changed length applies to new bookings.",
2225
- "calendarIds and intakeForm replace the whole list, so read the type first and send back what should stay.",
2226
- "Turning isGroup on needs maxSeats of at least 2, sent in the same call unless one is already stored; clearing maxSeats of a group type is refused with 400.",
2227
- "A ROUND_ROBIN or LOAD_BALANCED type must keep at least one calendar, and a calendar of another organization is refused: both with 409. Going back to NONE is refused with 409 while the type has future pending or confirmed bookings.",
2228
- "Neither the update nor the delete needs the scheduling switch to be on."
2229
- ],
2230
- dataSensitivity: "internal",
2231
- risk: "act",
2232
- requiresApproval: {
2233
- action: "Change an appointment type",
2234
- reason: "Changes can alter what clients pay, how long they are booked for, and whether the type can be booked at all.",
2235
- prompt: "Change appointment type {id}?"
2236
- }
2237
- },
2238
- {
2239
- name: "scheduling_delete_appointment_type",
2240
- module: "scheduling",
2241
- method: "DELETE",
2242
- route: "/admin/types/[id]",
2243
- auth: "session_cookie",
2244
- description: "Delete an appointment type that no appointment has ever used, and release its short booking address.",
2245
- params: [ID4],
2246
- example: { id: "type_1" },
2247
- responseShape: "{ success: true }",
2248
- whenToUse: "Only to remove a type that was created by mistake and never booked.",
2249
- pitfalls: [
2250
- "Refused with 409 while any appointment, past or future, uses the type. Switch it off with isActive false in the update tool instead.",
2251
- "A deleted type cannot be brought back."
2252
- ],
2253
- dataSensitivity: "internal",
2254
- risk: "act",
2255
- requiresApproval: {
2256
- action: "Delete an appointment type",
2257
- reason: "The type is removed for good and its booking address stops working.",
2258
- prompt: "Delete appointment type {id}? This cannot be undone."
2259
- }
2260
- },
2261
- {
2262
- name: "scheduling_reset_round_robin",
2263
- module: "scheduling",
2264
- method: "DELETE",
2265
- route: "/admin/types/[id]/round-robin-state",
2266
- auth: "session_cookie",
2267
- description: "Restart the turn-taking of a team appointment type, so the next booking goes to whoever the rotation starts with.",
2268
- params: [ID4],
2269
- example: { id: "type_1" },
2270
- responseShape: "{ success: true }",
2271
- whenToUse: "After a staff member joins or leaves a team type and the rotation should begin again.",
2272
- pitfalls: [
2273
- "This does not change the strategy or the calendars; it only forgets whose turn was last.",
2274
- "Bookings already made are untouched."
2275
- ],
2276
- dataSensitivity: "internal",
2277
- risk: "act",
2278
- requiresApproval: {
2279
- action: "Reset a rotation",
2280
- reason: "The next bookings are shared out as if the rotation were new, which can shift work between staff.",
2281
- prompt: "Restart the rotation of appointment type {id}?"
2282
- }
2283
- }
2284
- ];
2285
-
2286
- // src/agent/waitlist-tools.ts
2287
- var ENTRY_FIELDS = "id, typeId, calendarId, day, slotStart, clientName, clientEmail, clientPhone, status, offerSlotStart, offerExpiresAt, createdAt";
2288
- var NOT_ENABLED4 = "A server without the waitlist answers 501.";
2289
- var WAITLIST_TOOLS = [
2290
- {
2291
- name: "scheduling_list_waitlist",
2292
- module: "scheduling",
2293
- method: "GET",
2294
- route: "/admin/waitlist",
2295
- auth: "session_cookie",
2296
- description: "List the people on the waitlist, oldest first, with the day they want, and any slot they have been offered.",
2297
- params: [
2298
- { name: "status", type: "string", required: false, description: "Only entries in this state: WAITING (waiting for a slot), OFFERED (holding an offer that has not expired), ACCEPTING (taking the offer right now), BOOKED (took an offer), or EXPIRED (did not take it in time)", allowedValues: ["WAITING", "OFFERED", "ACCEPTING", "BOOKED", "EXPIRED"] },
2299
- { name: "limit", type: "number", required: false, description: "How many entries to return (default 50, at most 200)" },
2300
- { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
2301
- ],
2302
- example: { status: "WAITING" },
2303
- responseShape: `{ entries: [{ ${ENTRY_FIELDS} }], total, hasMore }`,
2304
- whenToUse: "To see who is waiting for which day, who holds an offer, and to find an entry id.",
2305
- pitfalls: [
2306
- "slotStart is the time the person asked for; null means any time that day. calendarId null means any calendar that offers the type. day is YYYY-MM-DD in the calendar's time zone.",
2307
- "offerSlotStart and offerExpiresAt are set only while the entry holds an offer.",
2308
- "The client's private link token is never part of the answer.",
2309
- "The answer carries names, email addresses and phone numbers.",
2310
- "Any other status value is refused with 400.",
2311
- NOT_ENABLED4,
2312
- "Needs the scheduling switch to be on for the organization."
2313
- ],
2314
- dataSensitivity: "sensitive",
2315
- risk: "observe"
2316
- },
2317
- {
2318
- name: "scheduling_remove_waitlist_entry",
2319
- module: "scheduling",
2320
- method: "DELETE",
2321
- route: "/admin/waitlist/[id]",
2322
- auth: "session_cookie",
2323
- description: "Take one person off the waitlist. If they were holding an offer, the slot goes to the next person who fits.",
2324
- params: [{ name: "id", type: "string", required: true, description: "Waitlist entry id" }],
2325
- example: { id: "wait_1" },
2326
- responseShape: "{ success: true }",
2327
- whenToUse: "When someone asked to be taken off, or an entry should be cleared away (including old BOOKED and EXPIRED ones).",
2328
- pitfalls: [
2329
- "Works on an entry that is WAITING, OFFERED, EXPIRED or BOOKED. One that is ACCEPTING (taking the offer at this moment) is refused with 404; try again in a moment.",
2330
- "Removing someone who holds an offer frees that slot, and it is offered to the next person who fits, who is told by the host's own notice.",
2331
- "The person removed is not sent a message by this tool, and a removed entry cannot be brought back; the client has to join again.",
2332
- "An entry of another organization is a plain 404.",
2333
- NOT_ENABLED4,
2334
- "Needs the scheduling switch to be on for the organization."
2335
- ],
2336
- dataSensitivity: "sensitive",
2337
- risk: "act",
2338
- requiresApproval: {
2339
- action: "Remove someone from the waitlist",
2340
- reason: "The person loses their place, and any offer they hold passes to the next person.",
2341
- prompt: "Remove waitlist entry {id}?"
2342
- }
2343
- }
2344
- ];
2345
-
2346
- // src/agent/webhook-tools.ts
2347
- var ENDPOINT_FIELDS = "id, url, description, eventTypes, isActive, createdAt";
2348
- var DELIVERY_FIELDS = "id, endpointId, eventId, eventType, status, attempts, nextAttemptAt, lastStatusCode, lastError, deliveredAt, createdAt, attemptLog: [{ attemptNumber, statusCode, error, durationMs, createdAt }]";
2349
- var ENDPOINT_ID = { name: "id", type: "string", required: true, description: "Webhook endpoint id" };
2350
- var NOT_ENABLED5 = "A server without webhooks answers 501.";
2351
- var WEBHOOK_TOOLS = [
2352
- {
2353
- name: "scheduling_list_webhooks",
2354
- module: "scheduling",
2355
- method: "GET",
2356
- route: "/admin/webhooks",
2357
- auth: "session_cookie",
2358
- description: "List the webhook endpoints of the organization, with the events each one receives, and the names of all the events that exist.",
2359
- params: [],
2360
- example: {},
2361
- responseShape: `{ endpoints: [{ ${ENDPOINT_FIELDS} }], eventTypes }`,
2362
- whenToUse: "To see what outside systems are told about bookings, to find an endpoint id, or to learn the event names.",
2363
- pitfalls: ["The signing secret is never part of this answer; it was shown once when the endpoint was added.", "The answer is a plain list with no paging, newest first.", NOT_ENABLED5, "Needs the scheduling switch to be on for the organization."],
2364
- dataSensitivity: "internal",
2365
- risk: "observe"
2366
- },
2367
- {
2368
- name: "scheduling_create_webhook",
2369
- module: "scheduling",
2370
- method: "POST",
2371
- route: "/admin/webhooks",
2372
- auth: "session_cookie",
2373
- description: "Add a web address that will be sent a signed message each time one of the chosen events happens.",
2374
- params: [
2375
- { name: "url", type: "string", required: true, description: "Where to send the events: an https address with a public domain name, no user name or password, up to 2000 characters. A server set up for local development may also accept http and local addresses; a production server refuses them." },
2376
- { name: "eventTypes", type: "string[]", required: true, description: "The events to send: appointment.booked, appointment.rescheduled, appointment.cancelled, appointment.no_show, reminder.sent, waitlist.offered. Or the single entry * for every event." },
2377
- { name: "description", type: "string", required: false, description: "A note for staff about what it is for, up to 200 characters" }
2378
- ],
2379
- example: { url: "https://hooks.example.com/scheduling", eventTypes: ["appointment.booked", "appointment.cancelled"], description: "Send bookings to the CRM" },
2380
- responseShape: `{ endpoint: { ${ENDPOINT_FIELDS} }, secret }`,
2381
- whenToUse: "When an outside system must hear about bookings. Then use scheduling_send_test_webhook to check it receives them.",
2382
- pitfalls: [
2383
- "The answer carries the signing secret, and it is shown only this once; it is never returned again. Give it to the person who is setting up the receiver and do not repeat it anywhere else.",
2384
- "An address that is not https, points at a private or local network, has no domain, or contains a user name or password is refused with 400. An organization can have at most 20 endpoints; the 21st is refused with 400. A list that names an unknown event, or mixes * with other events, is refused with 400; an event named twice is counted once.",
2385
- "Events are sent from the server and a receiver that keeps failing is retried, then its deliveries are parked as DEAD_LETTER (see scheduling_list_webhook_deliveries).",
2386
- NOT_ENABLED5,
2387
- "Needs the scheduling switch to be on for the organization."
2388
- ],
2389
- dataSensitivity: "critical",
2390
- risk: "govern",
2391
- requiresApproval: {
2392
- action: "Add a webhook",
2393
- reason: "From then on, booking details (client names and emails among them) are sent to that outside address.",
2394
- prompt: "Send booking events to {url}?"
2395
- }
2396
- },
2397
- {
2398
- name: "scheduling_delete_webhook",
2399
- module: "scheduling",
2400
- method: "DELETE",
2401
- route: "/admin/webhooks/[id]",
2402
- auth: "session_cookie",
2403
- description: "Remove a webhook endpoint together with its delivery log.",
2404
- params: [ENDPOINT_ID],
2405
- example: { id: "hook_1" },
2406
- responseShape: "{ success: true }",
2407
- whenToUse: "When an outside system should stop being told about bookings. There is no way to switch one off without deleting it.",
2408
- pitfalls: ["Its deliveries and their log are deleted too, including any that were still waiting to be sent.", "It cannot be brought back; add the address again for a new endpoint with a new secret.", "An endpoint of another organization is a plain 404.", NOT_ENABLED5, "Needs the scheduling switch to be on for the organization."],
2409
- dataSensitivity: "internal",
2410
- risk: "act",
2411
- requiresApproval: {
2412
- action: "Remove a webhook",
2413
- reason: "The endpoint and its delivery history are deleted for good.",
2414
- prompt: "Remove webhook {id}? This cannot be undone."
2415
- }
2416
- },
2417
- {
2418
- name: "scheduling_send_test_webhook",
2419
- module: "scheduling",
2420
- method: "POST",
2421
- route: "/admin/webhooks/[id]/test",
2422
- auth: "session_cookie",
2423
- description: "Send one signed test event to an endpoint right now, with no retries, and report whether the receiver accepted it.",
2424
- params: [ENDPOINT_ID],
2425
- example: { id: "hook_1" },
2426
- responseShape: "{ deliveryId, ok, statusCode, error }",
2427
- whenToUse: "After adding an endpoint, or when a receiver seems to be missing events.",
2428
- pitfalls: [
2429
- "The answer is 200 whether or not the receiver accepted it: read ok. ok false comes with the receiver's statusCode, or an error when it could not be reached.",
2430
- "It makes a real outgoing request from the server to the address, and the test shows in the delivery log as the event webhook.test. A test that fails (the receiver answers with an error or cannot be reached) is logged as DEAD_LETTER after its single try, so it appears in that list and could be retried like any other.",
2431
- "An endpoint of another organization is a plain 404.",
2432
- NOT_ENABLED5,
2433
- "Needs the scheduling switch to be on for the organization."
2434
- ],
2435
- dataSensitivity: "internal",
2436
- risk: "act",
2437
- requiresApproval: {
2438
- action: "Send a test webhook",
2439
- reason: "The server sends a real request to an outside address.",
2440
- prompt: "Send a test event to webhook {id}?"
2441
- }
2442
- },
2443
- {
2444
- name: "scheduling_list_webhook_deliveries",
2445
- module: "scheduling",
2446
- method: "GET",
2447
- route: "/admin/webhooks/[id]/deliveries",
2448
- auth: "session_cookie",
2449
- description: "Read the delivery log of one endpoint, newest first: each event, whether it got through, and the last attempts.",
2450
- params: [
2451
- ENDPOINT_ID,
2452
- { name: "status", type: "string", required: false, description: "Only deliveries in this state: PENDING (waiting to be sent), PROCESSING (being sent), SUCCEEDED, or DEAD_LETTER (ran out of tries)", allowedValues: ["PENDING", "PROCESSING", "SUCCEEDED", "DEAD_LETTER"] },
2453
- { name: "limit", type: "number", required: false, description: "How many deliveries to return (default 50, at most 200)" },
2454
- { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
2455
- ],
2456
- example: { id: "hook_1", status: "DEAD_LETTER" },
2457
- responseShape: `{ deliveries: [{ ${DELIVERY_FIELDS} }], total, hasMore }`,
2458
- whenToUse: "To find out why an outside system missed events, and to find the id of a DEAD_LETTER delivery to retry.",
2459
- pitfalls: ["Each delivery shows only its last 10 attempts.", "Any other status value is refused with 400.", "An endpoint of another organization is a plain 404.", NOT_ENABLED5, "Needs the scheduling switch to be on for the organization."],
2460
- dataSensitivity: "internal",
2461
- risk: "observe"
2462
- },
2463
- {
2464
- name: "scheduling_retry_webhook_delivery",
2465
- module: "scheduling",
2466
- method: "POST",
2467
- route: "/admin/webhook-deliveries/[id]/retry",
2468
- auth: "session_cookie",
2469
- description: "Put a delivery that ran out of tries back in the queue with a fresh set of tries.",
2470
- params: [{ name: "id", type: "string", required: true, description: "Delivery id (not the endpoint id), from scheduling_list_webhook_deliveries" }],
2471
- example: { id: "delivery_1" },
2472
- responseShape: "{ success: true }",
2473
- whenToUse: "After fixing a receiver, to send again an event it missed.",
2474
- pitfalls: [
2475
- "Only a DEAD_LETTER delivery can be retried (this includes a failed test send); any other delivery, or one of another organization, is a plain 404.",
2476
- "This only queues it. The server's background delivery sends it, so success true does not mean the receiver has it yet; read the delivery log again later.",
2477
- "The event is sent again as it was first made, so the receiver may see an event it partly processed before.",
2478
- NOT_ENABLED5,
2479
- "Needs the scheduling switch to be on for the organization."
2480
- ],
2481
- dataSensitivity: "internal",
2482
- risk: "act",
2483
- requiresApproval: {
2484
- action: "Retry a webhook delivery",
2485
- reason: "The event is sent to the outside address again.",
2486
- prompt: "Send delivery {id} again?"
2487
- }
2488
- }
2489
- ];
2490
-
2491
- // src/agent/coverage.ts
2492
- var SCHEDULING_AGENT_EXCLUDED = {
2493
- "GET /admin/api-keys": "Lists credentials. Agents do not handle API keys; the owner manages them in the dashboard.",
2494
- "POST /admin/api-keys": "Makes a credential whose secret would be shown in the agent's own transcript. The owner makes keys in the dashboard.",
2495
- "DELETE /admin/api-keys/[id]": "Credential management is left to the owner in the dashboard, not to an agent.",
2496
- "POST /coupons/validate": "Advisory price check for a visitor's booking page. It changes nothing but is a POST, and only GET tools run without approval; staff read a coupon's terms with the coupon list tool.",
2497
- "POST /gift-certificates/check": "A visitor checking the balance of a code they hold, from the public booking page. It changes nothing but is a POST, and only GET tools run without approval; staff read a certificate with the get tool.",
2498
- "POST /waitlist": "A client joining the waitlist for themselves; the answer holds their own private link token, which an agent should never be handed.",
2499
- "DELETE /waitlist": "A client leaving the waitlist from their own private link; staff remove an entry with the remove-waitlist-entry tool.",
2500
- "GET /waitlist/offer": "A client reading their own offer from a private link token.",
2501
- "POST /waitlist/offer/accept": "A client taking their own offer from a private link token; it books the slot.",
2502
- "GET /widget-init": "Boots the public booking widget in a visitor's browser; an agent reads the same facts from the type and calendar tools.",
2503
- "GET /type": "Public page data for one booking link; the staff tools list the same types.",
2504
- "GET /calendars": "Public booking-page data for visitors; the admin calendar tools cover this for staff.",
2505
- "GET /calendars/active": "A short calendar list for the pickers in a staff dashboard; the admin calendar list tool, for admin roles, returns every calendar with more detail, inactive ones too.",
2506
- "POST /payments/intent": "Creates a card payment in the visitor's own browser session; staff take payment with the collect-balance tool.",
2507
- "GET /admin/brand/sending-domain": "Makes the server look up DNS names under a domain the caller chooses, with no approval step for a GET tool; an agent steered by injected text could use it to send data to a name server it controls. Admins use the dashboard setup screen.",
2508
- "GET /brand": "Public copy of the brand settings; the brand tool for staff returns the same data.",
2509
- "GET /routing-forms": "Public form shown to a visitor; staff read the whole form, rules and fallback included, with scheduling_get_routing_form.",
2510
- "POST /routing-forms/route": "Runs a visitor's own answers through a form; staff try sample answers with scheduling_test_routing_form.",
2511
- "GET /appointments/ical": "Calendar feed opened with a private link token, not a staff sign-in.",
2512
- "GET /appointments/manage": "Client self-service opened with a private link token, not a staff sign-in.",
2513
- "DELETE /appointments/manage": "Client self-service opened with a private link token; staff cancel with the cancel tool.",
2514
- "PATCH /appointments/manage": "Client self-service opened with a private link token; staff move bookings with the reschedule tool.",
2515
- "POST /appointments/[id]/cancel-sync": "Called by the background worker when a calendar provider reports a deletion, with a shared secret.",
2516
- "POST /internal/webhooks/deliver": "Background worker entry point that sends queued webhooks, with a shared secret.",
2517
- "POST /internal/waitlist/sweep": "Background worker entry point that offers freed slots, with a shared secret.",
2518
- "GET /calendars/connect-google": "Starts a Google sign-in that a person must finish in a browser.",
2519
- "POST /calendars/connect-google": "Final step of a Google sign-in that a person must finish in a browser.",
2520
- "GET /calendars/connect-google/callback": "The address Google sends the person's browser back to.",
2521
- "GET /calendars/connect-outlook": "Starts a Microsoft sign-in that a person must finish in a browser.",
2522
- "GET /calendars/connect-outlook/callback": "The address Microsoft sends the person's browser back to."
2523
- };
2524
- var SCHEDULING_AGENT_PENDING = [];
2525
-
2526
- // src/agent/index.ts
2527
- var SCHEDULING_AGENT_TOOLS = [...APPOINTMENT_TOOLS, ...CALENDAR_TOOLS, ...TYPE_TOOLS, ...AVAILABILITY_TOOLS, ...SERIES_TOOLS, ...SETTINGS_TOOLS, ...POLICY_TOOLS, ...BILLING_TOOLS, ...GIFT_CERTIFICATE_TOOLS, ...WEBHOOK_TOOLS, ...ROUTING_TOOLS, ...WAITLIST_TOOLS, ...PRIVACY_TOOLS, ...ANALYTICS_TOOLS];
2528
- function createSchedulingAgentTools(options = {}) {
2529
- const base = (options.basePath ?? "/api/scheduling").replace(/\/+$/, "");
2530
- return SCHEDULING_AGENT_TOOLS.filter((tool) => !options.readOnly || tool.method === "GET").map(({ route, ...tool }) => ({
2531
- ...structuredClone(tool),
2532
- endpoint: base + route.replace(/\[(\w+)\]/g, "{$1}")
2533
- }));
2534
- }
2535
- // Annotate the CommonJS export names for ESM import in node:
2536
- 0 && (module.exports = {
2537
- SCHEDULING_AGENT_EXCLUDED,
2538
- SCHEDULING_AGENT_PENDING,
2539
- SCHEDULING_AGENT_TOOLS,
2540
- createSchedulingAgentTools
2541
- });