@ordinatio/scheduling-api 0.3.1 → 0.4.1
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.
- package/CHANGELOG.md +52 -0
- package/README.md +19 -0
- package/dist/agent/index.d.mts +55 -0
- package/dist/agent/index.d.ts +55 -0
- package/dist/agent/index.js +1070 -0
- package/dist/agent/index.mjs +1040 -0
- package/dist/{chunk-P6OR2DKC.mjs → chunk-WZ5KO7IW.mjs} +2 -2
- package/dist/index.d.mts +4 -385
- package/dist/index.d.ts +4 -385
- package/dist/index.js +83 -16
- package/dist/index.mjs +84 -17
- package/dist/routes-CM-ezlv2.d.mts +386 -0
- package/dist/routes-CM-ezlv2.d.ts +386 -0
- package/dist/schemas/index.js +2 -2
- package/dist/schemas/index.mjs +1 -1
- package/package.json +12 -2
|
@@ -0,0 +1,1070 @@
|
|
|
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 ID = { name: "id", type: "string", required: true, description: "Appointment id" };
|
|
33
|
+
var APPOINTMENT_TOOLS = [
|
|
34
|
+
{
|
|
35
|
+
name: "scheduling_list_appointments",
|
|
36
|
+
module: "scheduling",
|
|
37
|
+
method: "GET",
|
|
38
|
+
route: "/appointments",
|
|
39
|
+
auth: "session_cookie",
|
|
40
|
+
description: "List appointments, oldest first by start time, with optional filters. Only calendars the signed-in person may see are returned.",
|
|
41
|
+
params: [
|
|
42
|
+
{ name: "calendarId", type: "string", required: false, description: "Only this calendar" },
|
|
43
|
+
{ name: "clientId", type: "string", required: false, description: "Only this client" },
|
|
44
|
+
{
|
|
45
|
+
name: "status",
|
|
46
|
+
type: "string",
|
|
47
|
+
required: false,
|
|
48
|
+
description: "Only this status",
|
|
49
|
+
allowedValues: ["PENDING", "CONFIRMED", "COMPLETED", "CANCELLED", "NO_SHOW"]
|
|
50
|
+
},
|
|
51
|
+
{ name: "startDate", type: "string", required: false, description: "Earliest start, in UTC ending in Z" },
|
|
52
|
+
{ name: "endDate", type: "string", required: false, description: "Latest start, in UTC ending in Z" },
|
|
53
|
+
{ name: "limit", type: "number", required: false, description: "How many to return (default and maximum are set by the server)" }
|
|
54
|
+
],
|
|
55
|
+
example: { status: "CONFIRMED", startDate: "2026-11-02T00:00:00Z", endDate: "2026-11-03T00:00:00Z" },
|
|
56
|
+
responseShape: "{ appointments: [{ id, clientName, clientEmail, clientId, startTime, endTime, status, calendarId, calendarName, staffName, type: { id, name, color }, notes, staffNotes, location, meetingUrl, recurringId, recurringIndex }], total }",
|
|
57
|
+
whenToUse: 'To answer "what is on today", "who is coming tomorrow" or "what did this client book".',
|
|
58
|
+
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."],
|
|
59
|
+
dataSensitivity: "sensitive",
|
|
60
|
+
risk: "observe"
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
name: "scheduling_check_availability",
|
|
64
|
+
module: "scheduling",
|
|
65
|
+
method: "GET",
|
|
66
|
+
route: "/availability",
|
|
67
|
+
auth: "none",
|
|
68
|
+
description: "List the start times on one calendar for one day. Use the slots whose available is true.",
|
|
69
|
+
params: [
|
|
70
|
+
{ name: "calendarId", type: "string", required: true, description: "Calendar to check" },
|
|
71
|
+
{ name: "date", type: "string", required: true, description: "Day to check, YYYY-MM-DD" },
|
|
72
|
+
{ name: "typeId", type: "string", required: true, description: "Appointment type; its length decides which times fit" },
|
|
73
|
+
{ name: "timezone", type: "string", required: false, description: "IANA timezone that decides which calendar day `date` means; the times come back as UTC instants" },
|
|
74
|
+
{ name: "orgSlug", type: "string", required: false, description: "Organization slug, for hosts that serve several" }
|
|
75
|
+
],
|
|
76
|
+
example: { calendarId: "cal_1", date: "2026-11-03", typeId: "type_1", timezone: "America/New_York" },
|
|
77
|
+
responseShape: "{ date, calendarId, slots: [{ start, end, available }], timezone }",
|
|
78
|
+
whenToUse: "Before booking or moving an appointment, to see which times are really free.",
|
|
79
|
+
dataSensitivity: "internal",
|
|
80
|
+
risk: "observe"
|
|
81
|
+
},
|
|
82
|
+
{
|
|
83
|
+
name: "scheduling_check_team_availability",
|
|
84
|
+
module: "scheduling",
|
|
85
|
+
method: "GET",
|
|
86
|
+
route: "/availability/team",
|
|
87
|
+
auth: "none",
|
|
88
|
+
description: "List the free start times for a team appointment type: a time is free if any calendar in the team has it open.",
|
|
89
|
+
params: [
|
|
90
|
+
{ name: "typeId", type: "string", required: true, description: "A team appointment type" },
|
|
91
|
+
{ name: "date", type: "string", required: true, description: "Day to check, YYYY-MM-DD" },
|
|
92
|
+
{ name: "timezone", type: "string", required: false, description: "IANA timezone that decides which calendar day `date` means; the times come back as UTC instants" },
|
|
93
|
+
{ name: "orgSlug", type: "string", required: false, description: "Organization slug, for hosts that serve several" }
|
|
94
|
+
],
|
|
95
|
+
example: { typeId: "type_team", date: "2026-11-03" },
|
|
96
|
+
responseShape: "{ date, slots: [{ start, end, available, seatsTotal?, seatsBooked?, seatsAvailable? }], timezone }",
|
|
97
|
+
whenToUse: "For appointment types that rotate between several staff members.",
|
|
98
|
+
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."],
|
|
99
|
+
dataSensitivity: "internal",
|
|
100
|
+
risk: "observe"
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
name: "scheduling_list_appointment_types",
|
|
104
|
+
module: "scheduling",
|
|
105
|
+
method: "GET",
|
|
106
|
+
route: "/appointment-types",
|
|
107
|
+
auth: "none",
|
|
108
|
+
description: "List the appointment types a calendar offers, with length, price, deposit and intake questions.",
|
|
109
|
+
params: [
|
|
110
|
+
{ name: "calendarSlug", type: "string", required: true, description: "Slug of the calendar" },
|
|
111
|
+
{ name: "orgSlug", type: "string", required: false, description: "Organization slug, for hosts that serve several" }
|
|
112
|
+
],
|
|
113
|
+
example: { calendarSlug: "front-desk" },
|
|
114
|
+
responseShape: "[{ id, name, slug, duration, price, deposit, requiresPayment, assignmentStrategy, isGroup, maxSeats, intakeForm, calendars? }]",
|
|
115
|
+
whenToUse: "To find the typeId needed for booking or checking availability.",
|
|
116
|
+
dataSensitivity: "none",
|
|
117
|
+
risk: "observe"
|
|
118
|
+
},
|
|
119
|
+
{
|
|
120
|
+
name: "scheduling_check_capacity",
|
|
121
|
+
module: "scheduling",
|
|
122
|
+
method: "GET",
|
|
123
|
+
route: "/appointments/capacity",
|
|
124
|
+
auth: "none",
|
|
125
|
+
description: "For a group appointment type, say how many seats are left at one start time.",
|
|
126
|
+
params: [
|
|
127
|
+
{ name: "typeId", type: "string", required: true, description: "A group appointment type" },
|
|
128
|
+
{ name: "calendarId", type: "string", required: true, description: "Calendar the session is on" },
|
|
129
|
+
{ name: "startTime", type: "string", required: true, description: "Session start, in UTC ending in Z" }
|
|
130
|
+
],
|
|
131
|
+
example: { typeId: "type_group", calendarId: "cal_1", startTime: "2026-11-03T15:00:00Z" },
|
|
132
|
+
responseShape: "{ seatsTotal, seatsBooked, seatsAvailable, isFull }; seatsTotal and seatsAvailable are null when the type has no seat limit",
|
|
133
|
+
pitfalls: ["A type that is not a group type, or a calendar not offering it, gets a 404."],
|
|
134
|
+
whenToUse: "Before booking someone into a group session.",
|
|
135
|
+
dataSensitivity: "none",
|
|
136
|
+
risk: "observe"
|
|
137
|
+
},
|
|
138
|
+
{
|
|
139
|
+
name: "scheduling_list_appointment_notifications",
|
|
140
|
+
module: "scheduling",
|
|
141
|
+
method: "GET",
|
|
142
|
+
route: "/appointments/[id]/notifications",
|
|
143
|
+
auth: "session_cookie",
|
|
144
|
+
description: "List the confirmation and reminder messages queued or sent for one appointment.",
|
|
145
|
+
params: [ID],
|
|
146
|
+
example: { id: "appt_1" },
|
|
147
|
+
responseShape: "{ notifications: [...] }",
|
|
148
|
+
whenToUse: "To check whether a client was told about their appointment.",
|
|
149
|
+
dataSensitivity: "sensitive",
|
|
150
|
+
risk: "observe"
|
|
151
|
+
},
|
|
152
|
+
{
|
|
153
|
+
name: "scheduling_book_appointment",
|
|
154
|
+
module: "scheduling",
|
|
155
|
+
method: "POST",
|
|
156
|
+
route: "/appointments",
|
|
157
|
+
auth: "none",
|
|
158
|
+
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.",
|
|
159
|
+
params: [
|
|
160
|
+
{ name: "typeId", type: "string", required: true, description: "Appointment type" },
|
|
161
|
+
{ name: "startTime", type: "string", required: true, description: "Start in UTC, ISO 8601 ending in Z (an offset such as -05:00 is refused)" },
|
|
162
|
+
{ name: "clientName", type: "string", required: true, description: "Client full name" },
|
|
163
|
+
{ name: "clientEmail", type: "string", required: true, description: "Client email address" },
|
|
164
|
+
{ name: "calendarId", type: "string", required: false, description: "Calendar to book; leave out for a team type so the rotation picks" },
|
|
165
|
+
{ name: "preferredCalendarId", type: "string", required: false, description: "For a team type, the calendar to try first" },
|
|
166
|
+
{ name: "timezone", type: "string", required: false, description: "IANA timezone of the client" },
|
|
167
|
+
{ name: "clientPhone", type: "string", required: false, description: "Client phone number" },
|
|
168
|
+
{ name: "clientId", type: "string", required: false, description: "Existing client record; only a hint, the host decides whether to honour it" },
|
|
169
|
+
{ name: "notes", type: "string", required: false, description: "Notes, up to 1000 characters" },
|
|
170
|
+
{ 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` },
|
|
171
|
+
{ name: "paymentId", type: "string", required: false, description: "A payment already taken for this booking" },
|
|
172
|
+
{ name: "couponCode", type: "string", required: false, description: "Coupon code" },
|
|
173
|
+
{ name: "packagePurchaseId", type: "string", required: false, description: "Prepaid package to draw a session from" },
|
|
174
|
+
{ name: "orgSlug", type: "string", required: false, description: "Organization slug, for hosts that serve several; leave out unless told" }
|
|
175
|
+
],
|
|
176
|
+
example: {
|
|
177
|
+
typeId: "type_1",
|
|
178
|
+
startTime: "2026-11-03T20:00:00Z",
|
|
179
|
+
clientName: "Jane Smith",
|
|
180
|
+
clientEmail: "jane@example.com",
|
|
181
|
+
calendarId: "cal_1"
|
|
182
|
+
},
|
|
183
|
+
responseShape: `{ ${APPOINTMENT_FIELDS}, meetingUrl, icalUrl }`,
|
|
184
|
+
whenToUse: "When a person asks to book a client in. Check availability first.",
|
|
185
|
+
pitfalls: [
|
|
186
|
+
"A slot taken a moment ago returns 409 with code SLOT_UNAVAILABLE; check availability again and offer another time.",
|
|
187
|
+
"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.",
|
|
188
|
+
"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.",
|
|
189
|
+
"Coupon codes, packages and payment ids are checked by the server, not trusted as given; a coupon has no effect on a free type.",
|
|
190
|
+
"The answer holds the client's private manage and calendar links; never repeat them in a message.",
|
|
191
|
+
"A type with no team needs calendarId; leave it out only for a team type."
|
|
192
|
+
],
|
|
193
|
+
dataSensitivity: "sensitive",
|
|
194
|
+
risk: "act",
|
|
195
|
+
requiresApproval: {
|
|
196
|
+
action: "Book an appointment",
|
|
197
|
+
reason: "A booking commits a staff member's time and sends the client a confirmation.",
|
|
198
|
+
prompt: "Book {clientName} at {startTime} (UTC)?"
|
|
199
|
+
}
|
|
200
|
+
},
|
|
201
|
+
{
|
|
202
|
+
name: "scheduling_cancel_appointment",
|
|
203
|
+
module: "scheduling",
|
|
204
|
+
method: "POST",
|
|
205
|
+
route: "/appointments/[id]/cancel",
|
|
206
|
+
auth: "session_cookie",
|
|
207
|
+
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.",
|
|
208
|
+
params: [ID, { name: "reason", type: "string", required: false, description: "Why, up to 500 characters; stored as the cancellation reason" }],
|
|
209
|
+
example: { id: "appt_1", reason: "Staff member is unwell" },
|
|
210
|
+
responseShape: `{ ${APPOINTMENT_FIELDS} } with status "CANCELLED"`,
|
|
211
|
+
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."],
|
|
212
|
+
whenToUse: "When staff, not the client, ends the booking.",
|
|
213
|
+
dataSensitivity: "sensitive",
|
|
214
|
+
risk: "act",
|
|
215
|
+
requiresApproval: {
|
|
216
|
+
action: "Cancel an appointment",
|
|
217
|
+
reason: "Cancelling frees the staff member's time and may leave a paid booking waiting for a refund decision.",
|
|
218
|
+
prompt: "Cancel appointment {id}?"
|
|
219
|
+
}
|
|
220
|
+
},
|
|
221
|
+
{
|
|
222
|
+
name: "scheduling_reschedule_appointment",
|
|
223
|
+
module: "scheduling",
|
|
224
|
+
method: "POST",
|
|
225
|
+
route: "/appointments/[id]/reschedule",
|
|
226
|
+
auth: "session_cookie",
|
|
227
|
+
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.",
|
|
228
|
+
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" }],
|
|
229
|
+
example: { id: "appt_1", newStartTime: "2026-11-04T16:00:00Z" },
|
|
230
|
+
responseShape: `{ ${APPOINTMENT_FIELDS} }`,
|
|
231
|
+
whenToUse: "When a time change was asked for. Check availability for the new time first.",
|
|
232
|
+
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."],
|
|
233
|
+
dataSensitivity: "sensitive",
|
|
234
|
+
risk: "act",
|
|
235
|
+
requiresApproval: {
|
|
236
|
+
action: "Reschedule an appointment",
|
|
237
|
+
reason: "Moving an appointment changes what the client and staff member have planned.",
|
|
238
|
+
prompt: "Move appointment {id} to {newStartTime}?"
|
|
239
|
+
}
|
|
240
|
+
},
|
|
241
|
+
{
|
|
242
|
+
name: "scheduling_decide_pending_appointment",
|
|
243
|
+
module: "scheduling",
|
|
244
|
+
method: "POST",
|
|
245
|
+
route: "/appointments/[id]/approve",
|
|
246
|
+
auth: "session_cookie",
|
|
247
|
+
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.",
|
|
248
|
+
params: [
|
|
249
|
+
ID,
|
|
250
|
+
{ name: "approved", type: "boolean", required: true, description: "true to approve, false to reject" },
|
|
251
|
+
{ name: "reason", type: "string", required: false, description: "Why; recorded with the decision" }
|
|
252
|
+
],
|
|
253
|
+
example: { id: "appt_1", approved: true },
|
|
254
|
+
responseShape: '{ success: true, status: "CONFIRMED" | "CANCELLED", appointment }',
|
|
255
|
+
whenToUse: "For appointments with status PENDING.",
|
|
256
|
+
pitfalls: ["Only PENDING appointments can be decided."],
|
|
257
|
+
dataSensitivity: "sensitive",
|
|
258
|
+
risk: "act",
|
|
259
|
+
requiresApproval: {
|
|
260
|
+
action: "Approve or reject an appointment request",
|
|
261
|
+
reason: "A decision changes the booking's status and a rejection cannot be taken back.",
|
|
262
|
+
prompt: "Record the decision on appointment {id}: approved = {approved}. A rejection cancels the booking and cannot be undone. Continue?"
|
|
263
|
+
}
|
|
264
|
+
},
|
|
265
|
+
{
|
|
266
|
+
name: "scheduling_reassign_appointment",
|
|
267
|
+
module: "scheduling",
|
|
268
|
+
method: "PATCH",
|
|
269
|
+
route: "/appointments/[id]/reassign",
|
|
270
|
+
auth: "session_cookie",
|
|
271
|
+
description: "Hand an appointment to a different calendar, which means a different staff member, at the same time.",
|
|
272
|
+
params: [ID, { name: "calendarId", type: "string", required: true, description: "Calendar to move it to" }],
|
|
273
|
+
example: { id: "appt_1", calendarId: "cal_2" },
|
|
274
|
+
responseShape: "{ id, calendarId, typeId, startTime, endTime, duration, timezone, clientName, clientEmail, clientPhone, status, staffNotes, location, paymentStatus, manageToken, createdAt, updatedAt } (the stored record, which has more fields than the other appointment answers)",
|
|
275
|
+
whenToUse: "When a different person should take the appointment.",
|
|
276
|
+
pitfalls: ["The answer is the stored record and holds the client's private manage token; never repeat it in a message.", "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."],
|
|
277
|
+
dataSensitivity: "sensitive",
|
|
278
|
+
risk: "act",
|
|
279
|
+
requiresApproval: {
|
|
280
|
+
action: "Reassign an appointment",
|
|
281
|
+
reason: "The appointment moves to another staff member's calendar.",
|
|
282
|
+
prompt: "Move appointment {id} to calendar {calendarId}?"
|
|
283
|
+
}
|
|
284
|
+
},
|
|
285
|
+
{
|
|
286
|
+
name: "scheduling_mark_no_show",
|
|
287
|
+
module: "scheduling",
|
|
288
|
+
method: "POST",
|
|
289
|
+
route: "/appointments/[id]/no-show",
|
|
290
|
+
auth: "session_cookie",
|
|
291
|
+
description: "Record that the client did not come.",
|
|
292
|
+
params: [ID],
|
|
293
|
+
example: { id: "appt_1" },
|
|
294
|
+
responseShape: `{ ${APPOINTMENT_FIELDS} } with status "NO_SHOW"`,
|
|
295
|
+
whenToUse: "After the start time has passed and the client did not arrive.",
|
|
296
|
+
pitfalls: ["Refused with 409 unless the appointment is pending or confirmed and its start time has passed."],
|
|
297
|
+
dataSensitivity: "sensitive",
|
|
298
|
+
risk: "act",
|
|
299
|
+
requiresApproval: {
|
|
300
|
+
action: "Mark an appointment as a no-show",
|
|
301
|
+
reason: "The status changes to a no-show and appears in the client's history.",
|
|
302
|
+
prompt: "Mark appointment {id} as a no-show?"
|
|
303
|
+
}
|
|
304
|
+
},
|
|
305
|
+
{
|
|
306
|
+
name: "scheduling_send_followup",
|
|
307
|
+
module: "scheduling",
|
|
308
|
+
method: "POST",
|
|
309
|
+
route: "/appointments/[id]/followup",
|
|
310
|
+
auth: "session_cookie",
|
|
311
|
+
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.",
|
|
312
|
+
params: [ID],
|
|
313
|
+
example: { id: "appt_1" },
|
|
314
|
+
responseShape: "{ success: true }",
|
|
315
|
+
whenToUse: "After an appointment has ended.",
|
|
316
|
+
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."],
|
|
317
|
+
dataSensitivity: "sensitive",
|
|
318
|
+
risk: "act",
|
|
319
|
+
requiresApproval: {
|
|
320
|
+
action: "Send a follow-up message",
|
|
321
|
+
reason: "The message goes to the client in the business's name.",
|
|
322
|
+
prompt: "Send a follow-up to the client of appointment {id}?"
|
|
323
|
+
}
|
|
324
|
+
},
|
|
325
|
+
{
|
|
326
|
+
name: "scheduling_send_reminder",
|
|
327
|
+
module: "scheduling",
|
|
328
|
+
method: "POST",
|
|
329
|
+
route: "/appointments/[id]/remind",
|
|
330
|
+
auth: "session_cookie",
|
|
331
|
+
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.",
|
|
332
|
+
params: [ID],
|
|
333
|
+
example: { id: "appt_1" },
|
|
334
|
+
responseShape: "{ success: true }",
|
|
335
|
+
whenToUse: "When a client needs an extra nudge before the regular reminder.",
|
|
336
|
+
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."],
|
|
337
|
+
dataSensitivity: "sensitive",
|
|
338
|
+
risk: "act",
|
|
339
|
+
requiresApproval: {
|
|
340
|
+
action: "Send a reminder message",
|
|
341
|
+
reason: "The message goes to the client in the business's name.",
|
|
342
|
+
prompt: "Send a reminder to the client of appointment {id}?"
|
|
343
|
+
}
|
|
344
|
+
},
|
|
345
|
+
{
|
|
346
|
+
name: "scheduling_update_appointment_notes",
|
|
347
|
+
module: "scheduling",
|
|
348
|
+
method: "PATCH",
|
|
349
|
+
route: "/appointments/[id]/notes",
|
|
350
|
+
auth: "session_cookie",
|
|
351
|
+
description: "Replace the private staff notes on an appointment. An empty string clears them.",
|
|
352
|
+
params: [ID, { name: "notes", type: "string", required: true, description: "New notes, up to 5000 characters; send an empty string to clear them" }],
|
|
353
|
+
example: { id: "appt_1", notes: "Prefers mornings. Bring the signed form." },
|
|
354
|
+
responseShape: "{ success: true }",
|
|
355
|
+
whenToUse: "To record what staff should remember. The client never sees these.",
|
|
356
|
+
pitfalls: ["This replaces the existing notes; read them first and include what should stay."],
|
|
357
|
+
dataSensitivity: "sensitive",
|
|
358
|
+
risk: "act",
|
|
359
|
+
requiresApproval: {
|
|
360
|
+
action: "Change appointment notes",
|
|
361
|
+
reason: "The old notes are replaced.",
|
|
362
|
+
prompt: "Replace the notes on appointment {id}?"
|
|
363
|
+
}
|
|
364
|
+
},
|
|
365
|
+
{
|
|
366
|
+
name: "scheduling_update_appointment_location",
|
|
367
|
+
module: "scheduling",
|
|
368
|
+
method: "PATCH",
|
|
369
|
+
route: "/appointments/[id]/location",
|
|
370
|
+
auth: "session_cookie",
|
|
371
|
+
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.",
|
|
372
|
+
params: [ID, { name: "location", type: "string", required: true, description: "New location, up to 500 characters; send an empty string to clear it" }],
|
|
373
|
+
example: { id: "appt_1", location: "100 Main Street, Springfield" },
|
|
374
|
+
responseShape: "{ success: true }",
|
|
375
|
+
whenToUse: "When the meeting place changes.",
|
|
376
|
+
pitfalls: ["For a temporary one-off address this still updates the client's saved preferred location."],
|
|
377
|
+
dataSensitivity: "sensitive",
|
|
378
|
+
risk: "act",
|
|
379
|
+
requiresApproval: {
|
|
380
|
+
action: "Change appointment location",
|
|
381
|
+
reason: "The place changes on this appointment and, for a linked client, is saved as their preferred location for future bookings.",
|
|
382
|
+
prompt: "Change the location of appointment {id}?"
|
|
383
|
+
}
|
|
384
|
+
},
|
|
385
|
+
{
|
|
386
|
+
name: "scheduling_collect_balance",
|
|
387
|
+
module: "scheduling",
|
|
388
|
+
method: "POST",
|
|
389
|
+
route: "/appointments/[id]/collect-balance",
|
|
390
|
+
auth: "session_cookie",
|
|
391
|
+
description: "Start a payment for the unpaid part of an appointment after a deposit was taken.",
|
|
392
|
+
params: [ID],
|
|
393
|
+
example: { id: "appt_1" },
|
|
394
|
+
responseShape: "{ clientSecret, paymentIntentId, amount (in cents), currency, depositPaid (in dollars), totalPrice (in dollars) }",
|
|
395
|
+
whenToUse: "When a deposit was paid and the rest is due.",
|
|
396
|
+
pitfalls: [
|
|
397
|
+
"Only works when a deposit was paid and a balance remains.",
|
|
398
|
+
"The answer holds a payment secret meant for the client's own browser; never repeat it in a message.",
|
|
399
|
+
"It only starts the payment; the client still has to complete it.",
|
|
400
|
+
"The approval request shows only the appointment id: say whose appointment and what amount in your own message first."
|
|
401
|
+
],
|
|
402
|
+
dataSensitivity: "critical",
|
|
403
|
+
risk: "govern",
|
|
404
|
+
requiresApproval: {
|
|
405
|
+
action: "Collect the balance for an appointment",
|
|
406
|
+
reason: "This opens a payment for the client to complete.",
|
|
407
|
+
prompt: "Start a payment for the remaining balance on appointment {id}?"
|
|
408
|
+
}
|
|
409
|
+
},
|
|
410
|
+
{
|
|
411
|
+
name: "scheduling_resolve_refund",
|
|
412
|
+
module: "scheduling",
|
|
413
|
+
method: "POST",
|
|
414
|
+
route: "/appointments/[id]/resolve-refund",
|
|
415
|
+
auth: "session_cookie",
|
|
416
|
+
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.',
|
|
417
|
+
params: [
|
|
418
|
+
ID,
|
|
419
|
+
{ name: "action", type: "string", required: true, description: "How to settle it", allowedValues: ["refund", "credit"] }
|
|
420
|
+
],
|
|
421
|
+
example: { id: "appt_1", action: "refund" },
|
|
422
|
+
responseShape: "{ refundStatus, action }, where refundStatus is REFUNDED or CREDIT_ISSUED (done), or REFUND_FAILED or PARTIAL_REFUND (not finished; can be tried again)",
|
|
423
|
+
whenToUse: 'For a cancelled appointment flagged "refund pending".',
|
|
424
|
+
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."],
|
|
425
|
+
dataSensitivity: "critical",
|
|
426
|
+
risk: "govern",
|
|
427
|
+
requiresApproval: {
|
|
428
|
+
action: "Resolve a refund",
|
|
429
|
+
reason: "A refund moves money back to the client and cannot be undone; a credit is only recorded, not created.",
|
|
430
|
+
prompt: "Resolve the refund on appointment {id} as {action}?"
|
|
431
|
+
}
|
|
432
|
+
}
|
|
433
|
+
];
|
|
434
|
+
|
|
435
|
+
// src/agent/availability-tools.ts
|
|
436
|
+
var CALENDAR_ID = { name: "calendarId", type: "string", required: true, description: "Calendar id" };
|
|
437
|
+
var RULE_FIELDS = "id, calendarId, dayOfWeek, startTime, endTime, specificDate, isBlocked, blockReason, maxPerDay, bufferBefore, bufferAfter, minNotice, maxAdvanceBooking, createdAt";
|
|
438
|
+
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).";
|
|
439
|
+
var AVAILABILITY_TOOLS = [
|
|
440
|
+
{
|
|
441
|
+
name: "scheduling_list_availability_rules",
|
|
442
|
+
module: "scheduling",
|
|
443
|
+
method: "GET",
|
|
444
|
+
route: "/admin/availability/[calendarId]",
|
|
445
|
+
auth: "session_cookie",
|
|
446
|
+
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).",
|
|
447
|
+
params: [
|
|
448
|
+
CALENDAR_ID,
|
|
449
|
+
{ name: "limit", type: "number", required: false, description: "How many rules to return (default 200, at most 500)" },
|
|
450
|
+
{ name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
|
|
451
|
+
],
|
|
452
|
+
example: { calendarId: "cal_1" },
|
|
453
|
+
responseShape: `{ rules: [{ ${RULE_FIELDS} }], total, hasMore }`,
|
|
454
|
+
whenToUse: "Before changing the hours, to see what is set now, and to find the ruleId of an exception to remove.",
|
|
455
|
+
pitfalls: [
|
|
456
|
+
"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.",
|
|
457
|
+
"A calendar of another organization, or one the person may not see, is a plain 404."
|
|
458
|
+
],
|
|
459
|
+
dataSensitivity: "internal",
|
|
460
|
+
risk: "observe"
|
|
461
|
+
},
|
|
462
|
+
{
|
|
463
|
+
name: "scheduling_set_weekly_availability",
|
|
464
|
+
module: "scheduling",
|
|
465
|
+
method: "PUT",
|
|
466
|
+
route: "/admin/availability/[calendarId]",
|
|
467
|
+
auth: "session_cookie",
|
|
468
|
+
description: "Set the weekly opening hours of a calendar. This replaces every weekly rule the calendar has now with the list you send.",
|
|
469
|
+
params: [
|
|
470
|
+
CALENDAR_ID,
|
|
471
|
+
{ name: "rules", type: "json-array", required: true, description: WEEKLY_RULE }
|
|
472
|
+
],
|
|
473
|
+
example: {
|
|
474
|
+
calendarId: "cal_1",
|
|
475
|
+
rules: [
|
|
476
|
+
{ dayOfWeek: 1, startTime: "09:00", endTime: "17:00" },
|
|
477
|
+
{ dayOfWeek: 2, startTime: "09:00", endTime: "17:00", bufferAfter: 10, maxPerDay: 8 }
|
|
478
|
+
]
|
|
479
|
+
},
|
|
480
|
+
responseShape: `[{ ${RULE_FIELDS} }]`,
|
|
481
|
+
whenToUse: "To give a new calendar its opening hours, or to change them. Send the whole week every time.",
|
|
482
|
+
pitfalls: [
|
|
483
|
+
"Days not listed become closed. To keep a day as it is, send it again.",
|
|
484
|
+
"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.",
|
|
485
|
+
"Date exceptions are kept; only the weekly rules are replaced.",
|
|
486
|
+
"Times are in the time zone of the calendar.",
|
|
487
|
+
"The buffers, notice, advance limit and daily limit are part of each day, so a day sent without them goes back to the defaults.",
|
|
488
|
+
"A runner that cannot offer a list of objects to the model cannot use this tool."
|
|
489
|
+
],
|
|
490
|
+
dataSensitivity: "internal",
|
|
491
|
+
risk: "act",
|
|
492
|
+
requiresApproval: {
|
|
493
|
+
action: "Set weekly opening hours",
|
|
494
|
+
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.",
|
|
495
|
+
prompt: "Replace the weekly opening hours of calendar {calendarId}?"
|
|
496
|
+
}
|
|
497
|
+
},
|
|
498
|
+
{
|
|
499
|
+
name: "scheduling_add_availability_exception",
|
|
500
|
+
module: "scheduling",
|
|
501
|
+
method: "POST",
|
|
502
|
+
route: "/admin/availability/[calendarId]",
|
|
503
|
+
auth: "session_cookie",
|
|
504
|
+
description: "Add an exception for one date: close the whole day, block part of a day, or open custom hours that day.",
|
|
505
|
+
params: [
|
|
506
|
+
CALENDAR_ID,
|
|
507
|
+
{ name: "date", type: "string", required: true, description: "The date, YYYY-MM-DD" },
|
|
508
|
+
{ 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" },
|
|
509
|
+
{ 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" },
|
|
510
|
+
{ name: "endTime", type: "string", required: false, description: "HH:MM on a 24-hour clock, after startTime" },
|
|
511
|
+
{ name: "blockReason", type: "string", required: false, description: "A short note for staff, up to 500 characters" }
|
|
512
|
+
],
|
|
513
|
+
example: { calendarId: "cal_1", date: "2026-12-24", isBlocked: true, blockReason: "Holiday" },
|
|
514
|
+
responseShape: `{ ${RULE_FIELDS}, warning? }`,
|
|
515
|
+
whenToUse: "For a holiday, a meeting, a short day or a special opening. Use scheduling_set_weekly_availability for the regular week.",
|
|
516
|
+
pitfalls: [
|
|
517
|
+
"Leave startTime and endTime out to close the whole day.",
|
|
518
|
+
"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.",
|
|
519
|
+
"Times are in the time zone of the calendar.",
|
|
520
|
+
"Blocking part of a day does not cancel bookings already in it; a warning says how many overlap, if any.",
|
|
521
|
+
"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.",
|
|
522
|
+
"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.",
|
|
523
|
+
"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.",
|
|
524
|
+
"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."
|
|
525
|
+
],
|
|
526
|
+
dataSensitivity: "internal",
|
|
527
|
+
risk: "act",
|
|
528
|
+
requiresApproval: {
|
|
529
|
+
action: "Add an availability exception",
|
|
530
|
+
reason: "Closing or opening time on a date changes which times clients can book.",
|
|
531
|
+
prompt: "Add an exception for {date} on calendar {calendarId}?"
|
|
532
|
+
}
|
|
533
|
+
},
|
|
534
|
+
{
|
|
535
|
+
name: "scheduling_remove_availability_exception",
|
|
536
|
+
module: "scheduling",
|
|
537
|
+
method: "DELETE",
|
|
538
|
+
route: "/admin/availability/[calendarId]",
|
|
539
|
+
auth: "session_cookie",
|
|
540
|
+
description: "Remove one date exception, which gives that day or time back to the normal weekly hours.",
|
|
541
|
+
params: [
|
|
542
|
+
CALENDAR_ID,
|
|
543
|
+
{ name: "ruleId", type: "string", required: true, description: "Id of the exception, from scheduling_list_availability_rules" }
|
|
544
|
+
],
|
|
545
|
+
example: { calendarId: "cal_1", ruleId: "rule_1" },
|
|
546
|
+
responseShape: "{ success: true }",
|
|
547
|
+
whenToUse: "When a holiday or block was added by mistake or no longer applies. Find the id with scheduling_list_availability_rules.",
|
|
548
|
+
pitfalls: [
|
|
549
|
+
"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.",
|
|
550
|
+
"An id that is not on this calendar is a 404.",
|
|
551
|
+
"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."
|
|
552
|
+
],
|
|
553
|
+
dataSensitivity: "internal",
|
|
554
|
+
risk: "act",
|
|
555
|
+
requiresApproval: {
|
|
556
|
+
action: "Remove an availability exception",
|
|
557
|
+
reason: "The date goes back to the weekly hours, which can open times that were closed.",
|
|
558
|
+
prompt: "Remove exception {ruleId} from calendar {calendarId}?"
|
|
559
|
+
}
|
|
560
|
+
}
|
|
561
|
+
];
|
|
562
|
+
|
|
563
|
+
// src/agent/calendar-tools.ts
|
|
564
|
+
var ID2 = { name: "id", type: "string", required: true, description: "Calendar id" };
|
|
565
|
+
var CALENDAR_FIELDS = "id, name, slug, type, timezone, isActive, staffName, staffEmail, staffAvatar, userId, location, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, slotGranularityMinutes";
|
|
566
|
+
var THEME_KEYS = "primaryColor, accentColor, backgroundColor, textColor, mutedTextColor, borderColor, borderRadius, fontFamily";
|
|
567
|
+
var CONFIG_KEYS = "title, description, logoUrl, confirmationMessage, redirectUrl, redirectDelay, showContactInfo";
|
|
568
|
+
var SLOT_SIZES = "one of 5, 10, 15, 30 or 60 (minutes between the start times offered)";
|
|
569
|
+
var CALENDAR_TOOLS = [
|
|
570
|
+
{
|
|
571
|
+
name: "scheduling_list_staff_options",
|
|
572
|
+
module: "scheduling",
|
|
573
|
+
method: "GET",
|
|
574
|
+
route: "/admin/calendars/staff-options",
|
|
575
|
+
auth: "session_cookie",
|
|
576
|
+
description: "List the active people in the organization that a calendar can be linked to, with id, name and email.",
|
|
577
|
+
params: [],
|
|
578
|
+
example: {},
|
|
579
|
+
responseShape: "{ staff: [{ id, name, email }] }",
|
|
580
|
+
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).",
|
|
581
|
+
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."],
|
|
582
|
+
dataSensitivity: "sensitive",
|
|
583
|
+
risk: "observe"
|
|
584
|
+
},
|
|
585
|
+
{
|
|
586
|
+
name: "scheduling_list_calendars",
|
|
587
|
+
module: "scheduling",
|
|
588
|
+
method: "GET",
|
|
589
|
+
route: "/admin/calendars",
|
|
590
|
+
auth: "session_cookie",
|
|
591
|
+
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.",
|
|
592
|
+
params: [
|
|
593
|
+
{ name: "limit", type: "number", required: false, description: "How many to return (default 500, at most 1000)" },
|
|
594
|
+
{ name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
|
|
595
|
+
],
|
|
596
|
+
example: { limit: 100 },
|
|
597
|
+
responseShape: `{ calendars: [{ ${CALENDAR_FIELDS}, _count }], total, hasMore }`,
|
|
598
|
+
whenToUse: "To find a calendar id, or to see which calendars exist and which are archived (isActive false).",
|
|
599
|
+
pitfalls: ["Only counts: appointments are listed with the appointments tool."],
|
|
600
|
+
dataSensitivity: "internal",
|
|
601
|
+
risk: "observe"
|
|
602
|
+
},
|
|
603
|
+
{
|
|
604
|
+
name: "scheduling_get_calendar",
|
|
605
|
+
module: "scheduling",
|
|
606
|
+
method: "GET",
|
|
607
|
+
route: "/admin/calendars/[id]",
|
|
608
|
+
auth: "session_cookie",
|
|
609
|
+
description: "Read one calendar: its name, type, time zone, staff details, outside-calendar connections and slot size.",
|
|
610
|
+
params: [ID2],
|
|
611
|
+
example: { id: "cal_1" },
|
|
612
|
+
responseShape: `{ calendar: { ${CALENDAR_FIELDS}, organizationId, _count } }`,
|
|
613
|
+
whenToUse: "To check one calendar before changing it.",
|
|
614
|
+
pitfalls: ["A calendar of another organization, or one the person may not see, is a plain 404."],
|
|
615
|
+
dataSensitivity: "internal",
|
|
616
|
+
risk: "observe"
|
|
617
|
+
},
|
|
618
|
+
{
|
|
619
|
+
name: "scheduling_create_calendar",
|
|
620
|
+
module: "scheduling",
|
|
621
|
+
method: "POST",
|
|
622
|
+
route: "/admin/calendars",
|
|
623
|
+
auth: "session_cookie",
|
|
624
|
+
description: "Create a calendar. Its web address name (slug) is made from the name, and it starts active.",
|
|
625
|
+
params: [
|
|
626
|
+
{ name: "name", type: "string", required: true, description: "Calendar name, 1 to 100 characters" },
|
|
627
|
+
{ name: "type", type: "string", required: false, description: "What the calendar stands for; STAFF if left out", allowedValues: ["STAFF", "LOCATION", "RESOURCE"] },
|
|
628
|
+
{ name: "timezone", type: "string", required: false, description: "IANA timezone of the calendar, such as America/New_York (the default)" },
|
|
629
|
+
{ name: "staffName", type: "string", required: false, description: "Name shown on the booking page, up to 100 characters" },
|
|
630
|
+
{ name: "staffEmail", type: "string", required: false, description: "Email of the person, where notices go" },
|
|
631
|
+
{ name: "staffAvatar", type: "string", required: false, description: "Address (URL) of a picture, up to 500 characters" },
|
|
632
|
+
{ 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)" },
|
|
633
|
+
{ name: "location", type: "string", required: false, description: "Where appointments happen by default, up to 200 characters" },
|
|
634
|
+
{ name: "slotGranularityMinutes", type: "number", required: false, description: `Slot size: ${SLOT_SIZES}; 15 if left out` }
|
|
635
|
+
],
|
|
636
|
+
example: { name: "Front desk", type: "STAFF", timezone: "America/New_York", slotGranularityMinutes: 15 },
|
|
637
|
+
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",
|
|
638
|
+
whenToUse: "When a new person, room or resource needs its own bookable calendar. Give it opening hours with scheduling_set_weekly_availability.",
|
|
639
|
+
pitfalls: [
|
|
640
|
+
'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.',
|
|
641
|
+
"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.",
|
|
642
|
+
"directoryClaimed false means the short booking address could not be registered; only the organization-qualified address works then."
|
|
643
|
+
],
|
|
644
|
+
dataSensitivity: "internal",
|
|
645
|
+
risk: "act",
|
|
646
|
+
requiresApproval: {
|
|
647
|
+
action: "Create a calendar",
|
|
648
|
+
reason: "A new calendar becomes a bookable resource with its own public booking address.",
|
|
649
|
+
prompt: 'Create the calendar "{name}"?'
|
|
650
|
+
}
|
|
651
|
+
},
|
|
652
|
+
{
|
|
653
|
+
name: "scheduling_update_calendar",
|
|
654
|
+
module: "scheduling",
|
|
655
|
+
method: "PUT",
|
|
656
|
+
route: "/admin/calendars/[id]",
|
|
657
|
+
auth: "session_cookie",
|
|
658
|
+
description: "Change a calendar. Only the fields you send change; a field left out stays as it is. Setting isActive to false archives it.",
|
|
659
|
+
params: [
|
|
660
|
+
ID2,
|
|
661
|
+
{ name: "name", type: "string", required: false, description: "New name, 1 to 100 characters" },
|
|
662
|
+
{ name: "type", type: "string", required: false, description: "New type", allowedValues: ["STAFF", "LOCATION", "RESOURCE"] },
|
|
663
|
+
{ name: "timezone", type: "string", required: false, description: "New IANA timezone" },
|
|
664
|
+
{ name: "staffName", type: "string", required: false, description: "New staff name, up to 100 characters, or null to clear it" },
|
|
665
|
+
{ name: "staffEmail", type: "string", required: false, description: "New staff email, or null to clear it" },
|
|
666
|
+
{ name: "staffAvatar", type: "string", required: false, description: "New picture address (URL), or null to clear it" },
|
|
667
|
+
{ 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" },
|
|
668
|
+
{ name: "location", type: "string", required: false, description: "New default location, up to 200 characters, or null to clear it" },
|
|
669
|
+
{ name: "slotGranularityMinutes", type: "number", required: false, description: `New slot size: ${SLOT_SIZES}` },
|
|
670
|
+
{ name: "isActive", type: "boolean", required: false, description: "false archives the calendar, true brings it back" },
|
|
671
|
+
{ name: "syncDirection", type: "string", required: false, description: "How an outside calendar is synced", allowedValues: ["one-way", "two-way"] }
|
|
672
|
+
],
|
|
673
|
+
example: { id: "cal_1", timezone: "America/Chicago", slotGranularityMinutes: 30 },
|
|
674
|
+
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",
|
|
675
|
+
whenToUse: "To rename a calendar, change its time zone or slot size, link it to a person, or switch it off or on.",
|
|
676
|
+
pitfalls: [
|
|
677
|
+
"Changing the time zone changes what the opening hours mean in real time.",
|
|
678
|
+
"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.",
|
|
679
|
+
"Linking a calendar to a person (userId) changes who can see it when staff are limited to their groups.",
|
|
680
|
+
"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."
|
|
681
|
+
],
|
|
682
|
+
dataSensitivity: "internal",
|
|
683
|
+
risk: "act",
|
|
684
|
+
requiresApproval: {
|
|
685
|
+
action: "Change a calendar",
|
|
686
|
+
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.",
|
|
687
|
+
prompt: "Change calendar {id}?"
|
|
688
|
+
}
|
|
689
|
+
},
|
|
690
|
+
{
|
|
691
|
+
name: "scheduling_archive_calendar",
|
|
692
|
+
module: "scheduling",
|
|
693
|
+
method: "DELETE",
|
|
694
|
+
route: "/admin/calendars/[id]",
|
|
695
|
+
auth: "session_cookie",
|
|
696
|
+
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.",
|
|
697
|
+
params: [ID2],
|
|
698
|
+
example: { id: "cal_1" },
|
|
699
|
+
responseShape: "{ success: true }",
|
|
700
|
+
whenToUse: "When a person, room or resource is no longer bookable.",
|
|
701
|
+
pitfalls: [
|
|
702
|
+
"The last active calendar can never be archived: refused with 409. Create another calendar first.",
|
|
703
|
+
"Appointments already booked on the calendar are not cancelled by this.",
|
|
704
|
+
"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."
|
|
705
|
+
],
|
|
706
|
+
dataSensitivity: "internal",
|
|
707
|
+
risk: "act",
|
|
708
|
+
requiresApproval: {
|
|
709
|
+
action: "Archive a calendar",
|
|
710
|
+
reason: "The calendar stops taking bookings and its public address stops working.",
|
|
711
|
+
prompt: "Archive calendar {id}? It stops taking bookings."
|
|
712
|
+
}
|
|
713
|
+
},
|
|
714
|
+
{
|
|
715
|
+
name: "scheduling_get_booking_page",
|
|
716
|
+
module: "scheduling",
|
|
717
|
+
method: "GET",
|
|
718
|
+
route: "/admin/calendars/[id]/booking-page",
|
|
719
|
+
auth: "session_cookie",
|
|
720
|
+
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.",
|
|
721
|
+
params: [ID2],
|
|
722
|
+
example: { id: "cal_1" },
|
|
723
|
+
responseShape: "{ theme, config, name, slug, staffName }",
|
|
724
|
+
whenToUse: "Before changing the booking page, to see what is set now.",
|
|
725
|
+
pitfalls: ["theme and config are null when nothing was ever saved."],
|
|
726
|
+
dataSensitivity: "internal",
|
|
727
|
+
risk: "observe"
|
|
728
|
+
},
|
|
729
|
+
{
|
|
730
|
+
name: "scheduling_update_booking_page",
|
|
731
|
+
module: "scheduling",
|
|
732
|
+
method: "PUT",
|
|
733
|
+
route: "/admin/calendars/[id]/booking-page",
|
|
734
|
+
auth: "session_cookie",
|
|
735
|
+
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.",
|
|
736
|
+
params: [
|
|
737
|
+
ID2,
|
|
738
|
+
{ 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.` },
|
|
739
|
+
{ 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.` }
|
|
740
|
+
],
|
|
741
|
+
example: { id: "cal_1", theme: { primaryColor: "#1a4d3a", borderRadius: "8px" }, config: { title: "Book a visit", redirectDelay: 5 } },
|
|
742
|
+
responseShape: "{ success: true }",
|
|
743
|
+
whenToUse: "To brand a booking page or change what the client reads on it.",
|
|
744
|
+
pitfalls: [
|
|
745
|
+
"The theme or config you send replaces the saved one as a whole: read it first and send back what should stay.",
|
|
746
|
+
"A runner that cannot offer an object to the model cannot use this tool."
|
|
747
|
+
],
|
|
748
|
+
dataSensitivity: "internal",
|
|
749
|
+
risk: "act",
|
|
750
|
+
requiresApproval: {
|
|
751
|
+
action: "Change a booking page",
|
|
752
|
+
reason: "The booking page is what clients see when they book.",
|
|
753
|
+
prompt: "Change the booking page of calendar {id}?"
|
|
754
|
+
}
|
|
755
|
+
},
|
|
756
|
+
{
|
|
757
|
+
name: "scheduling_disconnect_google_calendar",
|
|
758
|
+
module: "scheduling",
|
|
759
|
+
method: "POST",
|
|
760
|
+
route: "/admin/calendars/[id]/disconnect-google",
|
|
761
|
+
auth: "session_cookie",
|
|
762
|
+
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.",
|
|
763
|
+
params: [ID2],
|
|
764
|
+
example: { id: "cal_1" },
|
|
765
|
+
responseShape: "{ success: true }",
|
|
766
|
+
whenToUse: "When a person no longer wants their Google Calendar tied to this calendar.",
|
|
767
|
+
pitfalls: [
|
|
768
|
+
"A calendar that is not connected to Google is refused with 400.",
|
|
769
|
+
"Connecting needs a person to sign in to Google in a browser; no tool can do that."
|
|
770
|
+
],
|
|
771
|
+
dataSensitivity: "internal",
|
|
772
|
+
risk: "act",
|
|
773
|
+
requiresApproval: {
|
|
774
|
+
action: "Disconnect Google Calendar",
|
|
775
|
+
reason: "Syncing stops, and the connection can only be restored by a person signing in to Google again.",
|
|
776
|
+
prompt: "Disconnect Google Calendar from calendar {id}?"
|
|
777
|
+
}
|
|
778
|
+
},
|
|
779
|
+
{
|
|
780
|
+
name: "scheduling_disconnect_outlook_calendar",
|
|
781
|
+
module: "scheduling",
|
|
782
|
+
method: "POST",
|
|
783
|
+
route: "/admin/calendars/[id]/disconnect-outlook",
|
|
784
|
+
auth: "session_cookie",
|
|
785
|
+
description: "Disconnect a calendar from Outlook Calendar. This stops syncing and removes the stored Outlook sign-in. Appointments already created stay.",
|
|
786
|
+
params: [ID2],
|
|
787
|
+
example: { id: "cal_1" },
|
|
788
|
+
responseShape: "{ success: true }",
|
|
789
|
+
whenToUse: "When a person no longer wants their Outlook calendar tied to this calendar.",
|
|
790
|
+
pitfalls: [
|
|
791
|
+
"A calendar that is not connected to Outlook is refused with 400.",
|
|
792
|
+
"Connecting needs a person to sign in to Microsoft in a browser; no tool can do that."
|
|
793
|
+
],
|
|
794
|
+
dataSensitivity: "internal",
|
|
795
|
+
risk: "act",
|
|
796
|
+
requiresApproval: {
|
|
797
|
+
action: "Disconnect Outlook Calendar",
|
|
798
|
+
reason: "Syncing stops, and the connection can only be restored by a person signing in to Microsoft again.",
|
|
799
|
+
prompt: "Disconnect Outlook Calendar from calendar {id}?"
|
|
800
|
+
}
|
|
801
|
+
},
|
|
802
|
+
{
|
|
803
|
+
name: "scheduling_list_location_recents",
|
|
804
|
+
module: "scheduling",
|
|
805
|
+
method: "GET",
|
|
806
|
+
route: "/admin/calendars/[id]/location-recents",
|
|
807
|
+
auth: "session_cookie",
|
|
808
|
+
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.",
|
|
809
|
+
params: [
|
|
810
|
+
ID2,
|
|
811
|
+
{ name: "clientId", type: "string", required: false, description: "A client whose preferred place should come first" }
|
|
812
|
+
],
|
|
813
|
+
example: { id: "cal_1" },
|
|
814
|
+
responseShape: "{ locations }",
|
|
815
|
+
whenToUse: "When filling in a location for a booking: suggests places already used.",
|
|
816
|
+
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."],
|
|
817
|
+
dataSensitivity: "internal",
|
|
818
|
+
risk: "observe"
|
|
819
|
+
}
|
|
820
|
+
];
|
|
821
|
+
|
|
822
|
+
// src/agent/type-tools.ts
|
|
823
|
+
var ID3 = { name: "id", type: "string", required: true, description: "Appointment type id" };
|
|
824
|
+
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";
|
|
825
|
+
var LOCATION_TYPES = ["IN_PERSON", "TRAVEL_TO_CLIENT", "VIRTUAL", "PHONE"];
|
|
826
|
+
var STRATEGIES = ["NONE", "ROUND_ROBIN", "LOAD_BALANCED"];
|
|
827
|
+
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).";
|
|
828
|
+
function typeFields(forUpdate) {
|
|
829
|
+
const when = (create, update) => forUpdate ? update : create;
|
|
830
|
+
return [
|
|
831
|
+
{ 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.") },
|
|
832
|
+
{ 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.") },
|
|
833
|
+
{ 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") },
|
|
834
|
+
{ 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 },
|
|
835
|
+
{ name: "duration", type: "number", required: !forUpdate, description: "Length in whole minutes, 5 to 480" },
|
|
836
|
+
{ name: "color", type: "string", required: false, description: when("Calendar colour as #RRGGBB hex; #3B82F6 if left out", "Calendar colour as #RRGGBB hex") },
|
|
837
|
+
{ 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") },
|
|
838
|
+
{ 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") },
|
|
839
|
+
{ 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") },
|
|
840
|
+
{ name: "requiresPayment", type: "boolean", required: false, description: when("Whether booking needs a payment; false if left out", "Whether booking needs a payment") },
|
|
841
|
+
{ 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") },
|
|
842
|
+
{ 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") },
|
|
843
|
+
{ 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") },
|
|
844
|
+
{ 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") },
|
|
845
|
+
{ 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") },
|
|
846
|
+
{ 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") },
|
|
847
|
+
{ 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") },
|
|
848
|
+
{ name: "isGroup", type: "boolean", required: false, description: when("Whether several clients share one session; false if left out", "Whether several clients share one session") },
|
|
849
|
+
{ 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") },
|
|
850
|
+
{ name: "intakeForm", type: "json-array", required: false, description: when(INTAKE_FORM, `${INTAKE_FORM} Replaces the whole list; null removes the questions.`) },
|
|
851
|
+
{ 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") },
|
|
852
|
+
{ 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 },
|
|
853
|
+
{ 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") }
|
|
854
|
+
];
|
|
855
|
+
}
|
|
856
|
+
var TYPE_TOOLS = [
|
|
857
|
+
{
|
|
858
|
+
name: "scheduling_list_all_appointment_types",
|
|
859
|
+
module: "scheduling",
|
|
860
|
+
method: "GET",
|
|
861
|
+
route: "/admin/types",
|
|
862
|
+
auth: "session_cookie",
|
|
863
|
+
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.",
|
|
864
|
+
params: [],
|
|
865
|
+
example: {},
|
|
866
|
+
responseShape: `[{ ${TYPE_FIELDS}, calendars: [{ calendar: { id, name } }], categoryRef, roundRobinState }]`,
|
|
867
|
+
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.",
|
|
868
|
+
pitfalls: ["The answer is a plain list with no paging.", "Needs the scheduling switch to be on for the organization."],
|
|
869
|
+
dataSensitivity: "internal",
|
|
870
|
+
risk: "observe"
|
|
871
|
+
},
|
|
872
|
+
{
|
|
873
|
+
name: "scheduling_create_appointment_type",
|
|
874
|
+
module: "scheduling",
|
|
875
|
+
method: "POST",
|
|
876
|
+
route: "/admin/types",
|
|
877
|
+
auth: "session_cookie",
|
|
878
|
+
description: "Create an appointment type. Its web address name (slug) is made from the name, and it starts active.",
|
|
879
|
+
params: [...typeFields(false)],
|
|
880
|
+
example: { name: "Consultation", duration: 45, price: 60, deposit: 20, requiresPayment: true, calendarIds: ["cal_1"] },
|
|
881
|
+
responseShape: `{ ${TYPE_FIELDS}, directoryClaimed }`,
|
|
882
|
+
whenToUse: "When something new needs to be bookable. Put it on a calendar with calendarIds, and make sure that calendar has opening hours.",
|
|
883
|
+
pitfalls: [
|
|
884
|
+
"A type with the same name, or a name that gives the same web address, already exists: refused with 409.",
|
|
885
|
+
"isGroup true needs maxSeats of at least 2.",
|
|
886
|
+
"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.",
|
|
887
|
+
"The first and second reminder must not be the same number of minutes (unless one is 0).",
|
|
888
|
+
"directoryClaimed false means the short booking address could not be registered; only the organization-qualified address works then.",
|
|
889
|
+
"Needs the scheduling switch to be on for the organization."
|
|
890
|
+
],
|
|
891
|
+
dataSensitivity: "internal",
|
|
892
|
+
risk: "act",
|
|
893
|
+
requiresApproval: {
|
|
894
|
+
action: "Create an appointment type",
|
|
895
|
+
reason: "A new type becomes something clients can book, with its own price and booking address.",
|
|
896
|
+
prompt: 'Create the appointment type "{name}"?'
|
|
897
|
+
}
|
|
898
|
+
},
|
|
899
|
+
{
|
|
900
|
+
name: "scheduling_update_appointment_type",
|
|
901
|
+
module: "scheduling",
|
|
902
|
+
method: "PUT",
|
|
903
|
+
route: "/admin/types/[id]",
|
|
904
|
+
auth: "session_cookie",
|
|
905
|
+
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.",
|
|
906
|
+
params: [
|
|
907
|
+
ID3,
|
|
908
|
+
...typeFields(true),
|
|
909
|
+
{ name: "isActive", type: "boolean", required: false, description: "false switches the type off so it can no longer be booked, true switches it back on" }
|
|
910
|
+
],
|
|
911
|
+
example: { id: "type_1", duration: 60, price: 80 },
|
|
912
|
+
responseShape: `{ ${TYPE_FIELDS} }`,
|
|
913
|
+
whenToUse: "To change length, price, reminders or intake questions, move a type to other calendars, or switch it off or on.",
|
|
914
|
+
pitfalls: [
|
|
915
|
+
"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.",
|
|
916
|
+
"Bookings that already exist keep their time; a changed length applies to new bookings.",
|
|
917
|
+
"calendarIds and intakeForm replace the whole list, so read the type first and send back what should stay.",
|
|
918
|
+
"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.",
|
|
919
|
+
"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.",
|
|
920
|
+
"Neither the update nor the delete needs the scheduling switch to be on."
|
|
921
|
+
],
|
|
922
|
+
dataSensitivity: "internal",
|
|
923
|
+
risk: "act",
|
|
924
|
+
requiresApproval: {
|
|
925
|
+
action: "Change an appointment type",
|
|
926
|
+
reason: "Changes can alter what clients pay, how long they are booked for, and whether the type can be booked at all.",
|
|
927
|
+
prompt: "Change appointment type {id}?"
|
|
928
|
+
}
|
|
929
|
+
},
|
|
930
|
+
{
|
|
931
|
+
name: "scheduling_delete_appointment_type",
|
|
932
|
+
module: "scheduling",
|
|
933
|
+
method: "DELETE",
|
|
934
|
+
route: "/admin/types/[id]",
|
|
935
|
+
auth: "session_cookie",
|
|
936
|
+
description: "Delete an appointment type that no appointment has ever used, and release its short booking address.",
|
|
937
|
+
params: [ID3],
|
|
938
|
+
example: { id: "type_1" },
|
|
939
|
+
responseShape: "{ success: true }",
|
|
940
|
+
whenToUse: "Only to remove a type that was created by mistake and never booked.",
|
|
941
|
+
pitfalls: [
|
|
942
|
+
"Refused with 409 while any appointment, past or future, uses the type. Switch it off with isActive false in the update tool instead.",
|
|
943
|
+
"A deleted type cannot be brought back."
|
|
944
|
+
],
|
|
945
|
+
dataSensitivity: "internal",
|
|
946
|
+
risk: "act",
|
|
947
|
+
requiresApproval: {
|
|
948
|
+
action: "Delete an appointment type",
|
|
949
|
+
reason: "The type is removed for good and its booking address stops working.",
|
|
950
|
+
prompt: "Delete appointment type {id}? This cannot be undone."
|
|
951
|
+
}
|
|
952
|
+
},
|
|
953
|
+
{
|
|
954
|
+
name: "scheduling_reset_round_robin",
|
|
955
|
+
module: "scheduling",
|
|
956
|
+
method: "DELETE",
|
|
957
|
+
route: "/admin/types/[id]/round-robin-state",
|
|
958
|
+
auth: "session_cookie",
|
|
959
|
+
description: "Restart the turn-taking of a team appointment type, so the next booking goes to whoever the rotation starts with.",
|
|
960
|
+
params: [ID3],
|
|
961
|
+
example: { id: "type_1" },
|
|
962
|
+
responseShape: "{ success: true }",
|
|
963
|
+
whenToUse: "After a staff member joins or leaves a team type and the rotation should begin again.",
|
|
964
|
+
pitfalls: [
|
|
965
|
+
"This does not change the strategy or the calendars; it only forgets whose turn was last.",
|
|
966
|
+
"Bookings already made are untouched."
|
|
967
|
+
],
|
|
968
|
+
dataSensitivity: "internal",
|
|
969
|
+
risk: "act",
|
|
970
|
+
requiresApproval: {
|
|
971
|
+
action: "Reset a rotation",
|
|
972
|
+
reason: "The next bookings are shared out as if the rotation were new, which can shift work between staff.",
|
|
973
|
+
prompt: "Restart the rotation of appointment type {id}?"
|
|
974
|
+
}
|
|
975
|
+
}
|
|
976
|
+
];
|
|
977
|
+
|
|
978
|
+
// src/agent/coverage.ts
|
|
979
|
+
var SCHEDULING_AGENT_EXCLUDED = {
|
|
980
|
+
"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.",
|
|
981
|
+
"GET /type": "Public page data for one booking link; the staff tools list the same types.",
|
|
982
|
+
"GET /calendars": "Public booking-page data for visitors; the admin calendar tools cover this for staff.",
|
|
983
|
+
"POST /payments/intent": "Creates a card payment in the visitor's own browser session; staff take payment with the collect-balance tool.",
|
|
984
|
+
"GET /brand": "Public copy of the brand settings; the admin brand tools (still to come) return the same data.",
|
|
985
|
+
"GET /routing-forms": "Public form shown to a visitor; the admin routing-form tools (still to come) cover it.",
|
|
986
|
+
"POST /routing-forms/route": "Runs a visitor's own answers through a form; staff will be able to test a form with the admin test tool, still to come.",
|
|
987
|
+
"GET /appointments/ical": "Calendar feed opened with a private link token, not a staff sign-in.",
|
|
988
|
+
"GET /appointments/manage": "Client self-service opened with a private link token, not a staff sign-in.",
|
|
989
|
+
"DELETE /appointments/manage": "Client self-service opened with a private link token; staff cancel with the cancel tool.",
|
|
990
|
+
"PATCH /appointments/manage": "Client self-service opened with a private link token; staff move bookings with the reschedule tool.",
|
|
991
|
+
"POST /appointments/[id]/cancel-sync": "Called by the background worker when a calendar provider reports a deletion, with a shared secret.",
|
|
992
|
+
"POST /internal/webhooks/deliver": "Background worker entry point that sends queued webhooks, with a shared secret.",
|
|
993
|
+
"POST /internal/waitlist/sweep": "Background worker entry point that offers freed slots, with a shared secret.",
|
|
994
|
+
"GET /calendars/connect-google": "Starts a Google sign-in that a person must finish in a browser.",
|
|
995
|
+
"POST /calendars/connect-google": "Final step of a Google sign-in that a person must finish in a browser.",
|
|
996
|
+
"GET /calendars/connect-google/callback": "The address Google sends the person's browser back to.",
|
|
997
|
+
"GET /calendars/connect-outlook": "Starts a Microsoft sign-in that a person must finish in a browser.",
|
|
998
|
+
"GET /calendars/connect-outlook/callback": "The address Microsoft sends the person's browser back to."
|
|
999
|
+
};
|
|
1000
|
+
var SCHEDULING_AGENT_PENDING = [
|
|
1001
|
+
"POST /coupons/validate",
|
|
1002
|
+
"POST /waitlist",
|
|
1003
|
+
"DELETE /waitlist",
|
|
1004
|
+
"GET /waitlist/offer",
|
|
1005
|
+
"POST /waitlist/offer/accept",
|
|
1006
|
+
"GET /admin/recurring",
|
|
1007
|
+
"POST /admin/recurring",
|
|
1008
|
+
"GET /admin/recurring/[id]",
|
|
1009
|
+
"PATCH /admin/recurring/[id]",
|
|
1010
|
+
"GET /admin/group-sessions",
|
|
1011
|
+
"GET /admin/policy",
|
|
1012
|
+
"PUT /admin/policy",
|
|
1013
|
+
"GET /admin/categories",
|
|
1014
|
+
"POST /admin/categories",
|
|
1015
|
+
"PATCH /admin/categories",
|
|
1016
|
+
"DELETE /admin/categories",
|
|
1017
|
+
"GET /admin/templates",
|
|
1018
|
+
"POST /admin/templates",
|
|
1019
|
+
"PUT /admin/templates/[id]",
|
|
1020
|
+
"DELETE /admin/templates/[id]",
|
|
1021
|
+
"GET /admin/coupons",
|
|
1022
|
+
"POST /admin/coupons",
|
|
1023
|
+
"PUT /admin/coupons/[id]",
|
|
1024
|
+
"DELETE /admin/coupons/[id]",
|
|
1025
|
+
"GET /admin/packages",
|
|
1026
|
+
"POST /admin/packages",
|
|
1027
|
+
"PUT /admin/packages/[id]",
|
|
1028
|
+
"DELETE /admin/packages/[id]",
|
|
1029
|
+
"GET /admin/package-purchases",
|
|
1030
|
+
"POST /admin/package-purchases",
|
|
1031
|
+
"PATCH /admin/package-purchases/[id]",
|
|
1032
|
+
"GET /admin/brand",
|
|
1033
|
+
"PUT /admin/brand",
|
|
1034
|
+
"DELETE /admin/brand",
|
|
1035
|
+
"GET /admin/webhooks",
|
|
1036
|
+
"POST /admin/webhooks",
|
|
1037
|
+
"DELETE /admin/webhooks/[id]",
|
|
1038
|
+
"POST /admin/webhooks/[id]/test",
|
|
1039
|
+
"GET /admin/webhooks/[id]/deliveries",
|
|
1040
|
+
"POST /admin/webhook-deliveries/[id]/retry",
|
|
1041
|
+
"GET /admin/routing-forms",
|
|
1042
|
+
"POST /admin/routing-forms",
|
|
1043
|
+
"GET /admin/routing-forms/[id]",
|
|
1044
|
+
"PUT /admin/routing-forms/[id]",
|
|
1045
|
+
"DELETE /admin/routing-forms/[id]",
|
|
1046
|
+
"POST /admin/routing-forms/[id]/test",
|
|
1047
|
+
"GET /admin/waitlist",
|
|
1048
|
+
"DELETE /admin/waitlist/[id]",
|
|
1049
|
+
"POST /admin/privacy/export",
|
|
1050
|
+
"POST /admin/privacy/erase",
|
|
1051
|
+
"GET /admin/privacy/requests",
|
|
1052
|
+
"GET /analytics"
|
|
1053
|
+
];
|
|
1054
|
+
|
|
1055
|
+
// src/agent/index.ts
|
|
1056
|
+
var SCHEDULING_AGENT_TOOLS = [...APPOINTMENT_TOOLS, ...CALENDAR_TOOLS, ...TYPE_TOOLS, ...AVAILABILITY_TOOLS];
|
|
1057
|
+
function createSchedulingAgentTools(options = {}) {
|
|
1058
|
+
const base = (options.basePath ?? "/api/scheduling").replace(/\/+$/, "");
|
|
1059
|
+
return SCHEDULING_AGENT_TOOLS.filter((tool) => !options.readOnly || tool.method === "GET").map(({ route, ...tool }) => ({
|
|
1060
|
+
...structuredClone(tool),
|
|
1061
|
+
endpoint: base + route.replace(/\[(\w+)\]/g, "{$1}")
|
|
1062
|
+
}));
|
|
1063
|
+
}
|
|
1064
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
1065
|
+
0 && (module.exports = {
|
|
1066
|
+
SCHEDULING_AGENT_EXCLUDED,
|
|
1067
|
+
SCHEDULING_AGENT_PENDING,
|
|
1068
|
+
SCHEDULING_AGENT_TOOLS,
|
|
1069
|
+
createSchedulingAgentTools
|
|
1070
|
+
});
|