@ordinatio/scheduling-api 0.3.0 → 0.4.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.
- package/CHANGELOG.md +34 -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 +547 -0
- package/dist/agent/index.mjs +517 -0
- package/dist/{chunk-MQO3VRMU.mjs → chunk-WZ5KO7IW.mjs} +12 -10
- package/dist/index.d.mts +4 -385
- package/dist/index.d.ts +4 -385
- package/dist/index.js +81 -24
- package/dist/index.mjs +72 -17
- package/dist/routes-CM-ezlv2.d.mts +386 -0
- package/dist/routes-CM-ezlv2.d.ts +386 -0
- package/dist/schemas/index.js +12 -10
- package/dist/schemas/index.mjs +1 -1
- package/package.json +13 -3
|
@@ -0,0 +1,547 @@
|
|
|
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/coverage.ts
|
|
436
|
+
var SCHEDULING_AGENT_EXCLUDED = {
|
|
437
|
+
"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.",
|
|
438
|
+
"GET /type": "Public page data for one booking link; the staff tools list the same types.",
|
|
439
|
+
"GET /calendars": "Public booking-page data for visitors; the admin calendar tools (still to come) cover this for staff.",
|
|
440
|
+
"POST /payments/intent": "Creates a card payment in the visitor's own browser session; staff take payment with the collect-balance tool.",
|
|
441
|
+
"GET /brand": "Public copy of the brand settings; the admin brand tools (still to come) return the same data.",
|
|
442
|
+
"GET /routing-forms": "Public form shown to a visitor; the admin routing-form tools (still to come) cover it.",
|
|
443
|
+
"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.",
|
|
444
|
+
"GET /appointments/ical": "Calendar feed opened with a private link token, not a staff sign-in.",
|
|
445
|
+
"GET /appointments/manage": "Client self-service opened with a private link token, not a staff sign-in.",
|
|
446
|
+
"DELETE /appointments/manage": "Client self-service opened with a private link token; staff cancel with the cancel tool.",
|
|
447
|
+
"PATCH /appointments/manage": "Client self-service opened with a private link token; staff move bookings with the reschedule tool.",
|
|
448
|
+
"POST /appointments/[id]/cancel-sync": "Called by the background worker when a calendar provider reports a deletion, with a shared secret.",
|
|
449
|
+
"POST /internal/webhooks/deliver": "Background worker entry point that sends queued webhooks, with a shared secret.",
|
|
450
|
+
"POST /internal/waitlist/sweep": "Background worker entry point that offers freed slots, with a shared secret.",
|
|
451
|
+
"GET /calendars/connect-google": "Starts a Google sign-in that a person must finish in a browser.",
|
|
452
|
+
"POST /calendars/connect-google": "Final step of a Google sign-in that a person must finish in a browser.",
|
|
453
|
+
"GET /calendars/connect-google/callback": "The address Google sends the person's browser back to.",
|
|
454
|
+
"GET /calendars/connect-outlook": "Starts a Microsoft sign-in that a person must finish in a browser.",
|
|
455
|
+
"GET /calendars/connect-outlook/callback": "The address Microsoft sends the person's browser back to."
|
|
456
|
+
};
|
|
457
|
+
var SCHEDULING_AGENT_PENDING = [
|
|
458
|
+
"POST /coupons/validate",
|
|
459
|
+
"POST /waitlist",
|
|
460
|
+
"DELETE /waitlist",
|
|
461
|
+
"GET /waitlist/offer",
|
|
462
|
+
"POST /waitlist/offer/accept",
|
|
463
|
+
"GET /admin/calendars/staff-options",
|
|
464
|
+
"GET /admin/calendars",
|
|
465
|
+
"POST /admin/calendars",
|
|
466
|
+
"GET /admin/calendars/[id]",
|
|
467
|
+
"PUT /admin/calendars/[id]",
|
|
468
|
+
"DELETE /admin/calendars/[id]",
|
|
469
|
+
"GET /admin/calendars/[id]/booking-page",
|
|
470
|
+
"PUT /admin/calendars/[id]/booking-page",
|
|
471
|
+
"POST /admin/calendars/[id]/disconnect-google",
|
|
472
|
+
"POST /admin/calendars/[id]/disconnect-outlook",
|
|
473
|
+
"GET /admin/calendars/[id]/location-recents",
|
|
474
|
+
"GET /admin/types",
|
|
475
|
+
"POST /admin/types",
|
|
476
|
+
"PUT /admin/types/[id]",
|
|
477
|
+
"DELETE /admin/types/[id]",
|
|
478
|
+
"DELETE /admin/types/[id]/round-robin-state",
|
|
479
|
+
"GET /admin/availability/[calendarId]",
|
|
480
|
+
"PUT /admin/availability/[calendarId]",
|
|
481
|
+
"POST /admin/availability/[calendarId]",
|
|
482
|
+
"DELETE /admin/availability/[calendarId]",
|
|
483
|
+
"GET /admin/recurring",
|
|
484
|
+
"POST /admin/recurring",
|
|
485
|
+
"GET /admin/recurring/[id]",
|
|
486
|
+
"PATCH /admin/recurring/[id]",
|
|
487
|
+
"GET /admin/group-sessions",
|
|
488
|
+
"GET /admin/policy",
|
|
489
|
+
"PUT /admin/policy",
|
|
490
|
+
"GET /admin/categories",
|
|
491
|
+
"POST /admin/categories",
|
|
492
|
+
"PATCH /admin/categories",
|
|
493
|
+
"DELETE /admin/categories",
|
|
494
|
+
"GET /admin/templates",
|
|
495
|
+
"POST /admin/templates",
|
|
496
|
+
"PUT /admin/templates/[id]",
|
|
497
|
+
"DELETE /admin/templates/[id]",
|
|
498
|
+
"GET /admin/coupons",
|
|
499
|
+
"POST /admin/coupons",
|
|
500
|
+
"PUT /admin/coupons/[id]",
|
|
501
|
+
"DELETE /admin/coupons/[id]",
|
|
502
|
+
"GET /admin/packages",
|
|
503
|
+
"POST /admin/packages",
|
|
504
|
+
"PUT /admin/packages/[id]",
|
|
505
|
+
"DELETE /admin/packages/[id]",
|
|
506
|
+
"GET /admin/package-purchases",
|
|
507
|
+
"POST /admin/package-purchases",
|
|
508
|
+
"PATCH /admin/package-purchases/[id]",
|
|
509
|
+
"GET /admin/brand",
|
|
510
|
+
"PUT /admin/brand",
|
|
511
|
+
"DELETE /admin/brand",
|
|
512
|
+
"GET /admin/webhooks",
|
|
513
|
+
"POST /admin/webhooks",
|
|
514
|
+
"DELETE /admin/webhooks/[id]",
|
|
515
|
+
"POST /admin/webhooks/[id]/test",
|
|
516
|
+
"GET /admin/webhooks/[id]/deliveries",
|
|
517
|
+
"POST /admin/webhook-deliveries/[id]/retry",
|
|
518
|
+
"GET /admin/routing-forms",
|
|
519
|
+
"POST /admin/routing-forms",
|
|
520
|
+
"GET /admin/routing-forms/[id]",
|
|
521
|
+
"PUT /admin/routing-forms/[id]",
|
|
522
|
+
"DELETE /admin/routing-forms/[id]",
|
|
523
|
+
"POST /admin/routing-forms/[id]/test",
|
|
524
|
+
"GET /admin/waitlist",
|
|
525
|
+
"DELETE /admin/waitlist/[id]",
|
|
526
|
+
"POST /admin/privacy/export",
|
|
527
|
+
"POST /admin/privacy/erase",
|
|
528
|
+
"GET /admin/privacy/requests",
|
|
529
|
+
"GET /analytics"
|
|
530
|
+
];
|
|
531
|
+
|
|
532
|
+
// src/agent/index.ts
|
|
533
|
+
var SCHEDULING_AGENT_TOOLS = [...APPOINTMENT_TOOLS];
|
|
534
|
+
function createSchedulingAgentTools(options = {}) {
|
|
535
|
+
const base = (options.basePath ?? "/api/scheduling").replace(/\/+$/, "");
|
|
536
|
+
return SCHEDULING_AGENT_TOOLS.filter((tool) => !options.readOnly || tool.method === "GET").map(({ route, ...tool }) => ({
|
|
537
|
+
...structuredClone(tool),
|
|
538
|
+
endpoint: base + route.replace(/\[(\w+)\]/g, "{$1}")
|
|
539
|
+
}));
|
|
540
|
+
}
|
|
541
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
542
|
+
0 && (module.exports = {
|
|
543
|
+
SCHEDULING_AGENT_EXCLUDED,
|
|
544
|
+
SCHEDULING_AGENT_PENDING,
|
|
545
|
+
SCHEDULING_AGENT_TOOLS,
|
|
546
|
+
createSchedulingAgentTools
|
|
547
|
+
});
|