@ordinatio/scheduling-api 0.4.1 → 0.5.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 +61 -0
- package/README.md +9 -5
- package/dist/agent/index.js +1408 -147
- package/dist/agent/index.mjs +1408 -147
- package/dist/index.js +91 -49
- package/dist/index.mjs +91 -49
- package/package.json +3 -3
package/dist/agent/index.js
CHANGED
|
@@ -29,6 +29,7 @@ module.exports = __toCommonJS(agent_exports);
|
|
|
29
29
|
|
|
30
30
|
// src/agent/appointment-tools.ts
|
|
31
31
|
var APPOINTMENT_FIELDS = "id, calendarId, calendarName, staffName, typeId, typeName, startTime, endTime, duration, timezone, status, clientName, clientEmail, clientPhone, intakeResponses, staffNotes, location, paymentId, paymentStatus, paymentAmount, depositAmount, paymentProvider, couponCode, discountAmount, isGroup, manageToken, createdAt";
|
|
32
|
+
var STAFF_APPOINTMENT_FIELDS = "id, calendarId, calendarName, staffName, typeId, typeName, startTime, endTime, duration, timezone, status, clientName, clientEmail, clientPhone, intakeResponses, staffNotes, location, paymentId, paymentStatus, paymentAmount, depositAmount, paymentProvider, couponCode, discountAmount, isGroup, createdAt";
|
|
32
33
|
var ID = { name: "id", type: "string", required: true, description: "Appointment id" };
|
|
33
34
|
var APPOINTMENT_TOOLS = [
|
|
34
35
|
{
|
|
@@ -207,7 +208,7 @@ var APPOINTMENT_TOOLS = [
|
|
|
207
208
|
description: "Cancel an appointment as staff. The calendar entry is removed, the staff member is notified and a paid booking is flagged for refund review. This route does not message the client itself; the host may send a notice when it hears the appointment.cancelled event.",
|
|
208
209
|
params: [ID, { name: "reason", type: "string", required: false, description: "Why, up to 500 characters; stored as the cancellation reason" }],
|
|
209
210
|
example: { id: "appt_1", reason: "Staff member is unwell" },
|
|
210
|
-
responseShape: `{ ${
|
|
211
|
+
responseShape: `{ ${STAFF_APPOINTMENT_FIELDS} } with status "CANCELLED"`,
|
|
211
212
|
pitfalls: ["Staff can cancel even after the type's client cancellation deadline; those limits apply only to the client's own link. Refused with 409 only when the appointment is no longer pending or confirmed."],
|
|
212
213
|
whenToUse: "When staff, not the client, ends the booking.",
|
|
213
214
|
dataSensitivity: "sensitive",
|
|
@@ -227,7 +228,7 @@ var APPOINTMENT_TOOLS = [
|
|
|
227
228
|
description: "Move an appointment to a new start time on the same calendar. The client is sent a reschedule notice and their reminders are redone for the new time.",
|
|
228
229
|
params: [ID, { name: "newStartTime", type: "string", required: true, description: "New start in UTC, ending in Z; a time with no zone is read in the server's own zone and lands in the wrong place" }],
|
|
229
230
|
example: { id: "appt_1", newStartTime: "2026-11-04T16:00:00Z" },
|
|
230
|
-
responseShape: `{ ${
|
|
231
|
+
responseShape: `{ ${STAFF_APPOINTMENT_FIELDS} }`,
|
|
231
232
|
whenToUse: "When a time change was asked for. Check availability for the new time first.",
|
|
232
233
|
pitfalls: ["A time that is taken, a time in the past, an appointment that has already started, a type that does not allow moving, or a change made at the same moment by someone else, is refused."],
|
|
233
234
|
dataSensitivity: "sensitive",
|
|
@@ -271,9 +272,9 @@ var APPOINTMENT_TOOLS = [
|
|
|
271
272
|
description: "Hand an appointment to a different calendar, which means a different staff member, at the same time.",
|
|
272
273
|
params: [ID, { name: "calendarId", type: "string", required: true, description: "Calendar to move it to" }],
|
|
273
274
|
example: { id: "appt_1", calendarId: "cal_2" },
|
|
274
|
-
responseShape: "{ id, calendarId, typeId, startTime, endTime, duration, timezone, clientName, clientEmail, clientPhone, status, staffNotes, location, paymentStatus,
|
|
275
|
+
responseShape: "{ id, calendarId, typeId, startTime, endTime, duration, timezone, clientName, clientEmail, clientPhone, status, staffNotes, location, paymentStatus, createdAt, updatedAt } (the stored record without the client's private manage token)",
|
|
275
276
|
whenToUse: "When a different person should take the appointment.",
|
|
276
|
-
pitfalls: ["
|
|
277
|
+
pitfalls: ["Admin roles only. Only pending or confirmed appointments, and not group sessions. The new calendar must be in the appointment type's team and free at that time; otherwise it is refused."],
|
|
277
278
|
dataSensitivity: "sensitive",
|
|
278
279
|
risk: "act",
|
|
279
280
|
requiresApproval: {
|
|
@@ -291,7 +292,7 @@ var APPOINTMENT_TOOLS = [
|
|
|
291
292
|
description: "Record that the client did not come.",
|
|
292
293
|
params: [ID],
|
|
293
294
|
example: { id: "appt_1" },
|
|
294
|
-
responseShape: `{ ${
|
|
295
|
+
responseShape: `{ ${STAFF_APPOINTMENT_FIELDS} } with status "NO_SHOW"`,
|
|
295
296
|
whenToUse: "After the start time has passed and the client did not arrive.",
|
|
296
297
|
pitfalls: ["Refused with 409 unless the appointment is pending or confirmed and its start time has passed."],
|
|
297
298
|
dataSensitivity: "sensitive",
|
|
@@ -432,6 +433,35 @@ var APPOINTMENT_TOOLS = [
|
|
|
432
433
|
}
|
|
433
434
|
];
|
|
434
435
|
|
|
436
|
+
// src/agent/analytics-tools.ts
|
|
437
|
+
var ANALYTICS_TOOLS = [
|
|
438
|
+
{
|
|
439
|
+
name: "scheduling_get_booking_analytics",
|
|
440
|
+
module: "scheduling",
|
|
441
|
+
method: "GET",
|
|
442
|
+
route: "/analytics",
|
|
443
|
+
auth: "session_cookie",
|
|
444
|
+
description: "Booking figures for the last few days: how many were booked, completed, cancelled, no-shows and pending, the rates, what was paid, the busiest hours and days, and a trend per day.",
|
|
445
|
+
params: [
|
|
446
|
+
{ name: "days", type: "number", required: false, description: "How many days back to look, a whole number from 1 to 365; 30 if left out" },
|
|
447
|
+
{ name: "calendarId", type: "string", required: false, description: "Only this calendar" }
|
|
448
|
+
],
|
|
449
|
+
example: { days: 30 },
|
|
450
|
+
responseShape: "{ period: { start, end, days }, totals: { booked, completed, cancelled, noShows, pending }, rates: { completionRate, cancellationRate, noShowRate }, revenue: { total, avg, currency }, peakHours: [{ hour, count }], peakDays: [{ dayOfWeek, count }], heatmap: [{ dayOfWeek, hour, count }], byType: [{ typeId, typeName, count, color, totalRevenue, avgRevenue }], dailyTrend: [{ date, count }], funnel: [{ stage, count }] }",
|
|
451
|
+
whenToUse: "To answer how busy the business is, how many people cancel or do not turn up, and which services book most.",
|
|
452
|
+
pitfalls: [
|
|
453
|
+
"It counts bookings whose start time falls between the start of the first day and now, so bookings still to come are not included.",
|
|
454
|
+
"Rates are whole percentages of the booked total. confirmed in the funnel is booked minus cancelled and pending.",
|
|
455
|
+
"Hours and days are counted in UTC, not the calendar's own time zone.",
|
|
456
|
+
"revenue adds up the payment amount of every booking in the period that has one, whatever its status, so a cancelled booking that was paid is counted. The amounts are in the same units the payments were recorded in, and currency always says usd whatever was charged; avg is rounded to a whole number.",
|
|
457
|
+
"Only for admin roles: others are refused with 403. A calendar of another organization, or one the person may not see, is a plain 404. days outside 1 to 365, or not a number, is refused with 400.",
|
|
458
|
+
"A server that has switched analytics off answers 503."
|
|
459
|
+
],
|
|
460
|
+
dataSensitivity: "internal",
|
|
461
|
+
risk: "observe"
|
|
462
|
+
}
|
|
463
|
+
];
|
|
464
|
+
|
|
435
465
|
// src/agent/availability-tools.ts
|
|
436
466
|
var CALENDAR_ID = { name: "calendarId", type: "string", required: true, description: "Calendar id" };
|
|
437
467
|
var RULE_FIELDS = "id, calendarId, dayOfWeek, startTime, endTime, specificDate, isBlocked, blockReason, maxPerDay, bufferBefore, bufferAfter, minNotice, maxAdvanceBooking, createdAt";
|
|
@@ -560,6 +590,313 @@ var AVAILABILITY_TOOLS = [
|
|
|
560
590
|
}
|
|
561
591
|
];
|
|
562
592
|
|
|
593
|
+
// src/agent/billing-tools.ts
|
|
594
|
+
var COUPON_FIELDS = "id, code, discountType, discountValue, maxUses, usedCount, expiresAt, organizationId, isActive, createdAt, updatedAt";
|
|
595
|
+
var PACKAGE_FIELDS = "id, name, description, price, sessions, validDays, typeId, organizationId, isActive, createdAt, updatedAt, type: { id, name }";
|
|
596
|
+
var PURCHASE_FIELDS = "id, packageId, organizationId, clientEmail, clientName, sessionsTotal, sessionsUsed, expiresAt, purchasedAt, status, paymentId, notes, pricePaidCents, createdAt, updatedAt, package: { id, name, sessions }";
|
|
597
|
+
var COUPON_ID = { name: "id", type: "string", required: true, description: "Coupon id" };
|
|
598
|
+
var PACKAGE_ID = { name: "id", type: "string", required: true, description: "Package id" };
|
|
599
|
+
var MONEY_NOTE = `Amounts are decimal numbers in the organization's currency; the answer returns them as text without trailing zeros, such as "12.5" or "20".`;
|
|
600
|
+
var BILLING_TOOLS = [
|
|
601
|
+
{
|
|
602
|
+
name: "scheduling_list_coupons",
|
|
603
|
+
module: "scheduling",
|
|
604
|
+
method: "GET",
|
|
605
|
+
route: "/admin/coupons",
|
|
606
|
+
auth: "session_cookie",
|
|
607
|
+
description: "List the organization's coupon codes, newest first, with how many times each has been used.",
|
|
608
|
+
params: [
|
|
609
|
+
{ name: "limit", type: "number", required: false, description: "How many coupons to return (default 50, at most 200)" },
|
|
610
|
+
{ name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
|
|
611
|
+
],
|
|
612
|
+
example: {},
|
|
613
|
+
responseShape: `{ coupons: [{ ${COUPON_FIELDS} }], total, hasMore }`,
|
|
614
|
+
whenToUse: "To find a coupon id, check whether a code exists, or see how much a code has been used.",
|
|
615
|
+
pitfalls: [MONEY_NOTE, "Needs the scheduling switch to be on for the organization."],
|
|
616
|
+
dataSensitivity: "internal",
|
|
617
|
+
risk: "observe"
|
|
618
|
+
},
|
|
619
|
+
{
|
|
620
|
+
name: "scheduling_create_coupon",
|
|
621
|
+
module: "scheduling",
|
|
622
|
+
method: "POST",
|
|
623
|
+
route: "/admin/coupons",
|
|
624
|
+
auth: "session_cookie",
|
|
625
|
+
description: "Create a coupon code that takes a percentage or a flat amount off the online payment of a booking.",
|
|
626
|
+
params: [
|
|
627
|
+
{ name: "code", type: "string", required: true, description: "The code clients type, 3 to 50 characters of letters, digits, hyphens and underscores. It is stored in capital letters." },
|
|
628
|
+
{ name: "discountType", type: "string", required: true, description: "PERCENTAGE takes a share off; FLAT takes a fixed amount off", allowedValues: ["PERCENTAGE", "FLAT"] },
|
|
629
|
+
{ name: "discountValue", type: "number", required: true, description: "The percentage (at most 100) or the amount, from 0.01 up to 100000" },
|
|
630
|
+
{ name: "maxUses", type: "number", required: false, description: "How many paid bookings may use it, a whole number of 1 or more; no limit if left out or null" },
|
|
631
|
+
{ name: "expiresAt", type: "string", required: false, description: "When it stops working, as an ISO 8601 UTC date-time such as 2026-12-31T23:59:59Z; never if left out or null" }
|
|
632
|
+
],
|
|
633
|
+
example: { code: "WELCOME20", discountType: "PERCENTAGE", discountValue: 20, maxUses: 100, expiresAt: "2026-12-31T23:59:59Z" },
|
|
634
|
+
responseShape: `{ coupon: { ${COUPON_FIELDS} } }`,
|
|
635
|
+
whenToUse: "To start a promotion. It is active straight away and its used count starts at 0. Leave at least 0.50 to pay, or the coupon will be refused at checkout.",
|
|
636
|
+
pitfalls: [
|
|
637
|
+
"A code that already exists is refused with 409. Codes are unique across the whole database, so a code used by another organization is refused too.",
|
|
638
|
+
"A percentage over 100 is refused with 400.",
|
|
639
|
+
"A coupon only matters for a booking that is paid online (scheduling_book_appointment with couponCode). The discount comes off the deposit when the appointment type has one, otherwise off the price, and the charge cannot go below zero. Online payment is refused with 400 when the discounted charge would be under 50 cents (the card provider's minimum), so a coupon cannot make a booking free: a 100% coupon, or a flat coupon as large as the charge, fails at checkout. A booking for a type that takes no payment ignores the code and does not use it up.",
|
|
640
|
+
MONEY_NOTE,
|
|
641
|
+
"Needs the scheduling switch to be on for the organization."
|
|
642
|
+
],
|
|
643
|
+
dataSensitivity: "internal",
|
|
644
|
+
risk: "govern",
|
|
645
|
+
requiresApproval: {
|
|
646
|
+
action: "Create a coupon",
|
|
647
|
+
reason: "Anyone with the code gets the discount on their online payment straight away.",
|
|
648
|
+
prompt: "Create coupon {code} for {discountValue} ({discountType}) off?"
|
|
649
|
+
}
|
|
650
|
+
},
|
|
651
|
+
{
|
|
652
|
+
name: "scheduling_update_coupon",
|
|
653
|
+
module: "scheduling",
|
|
654
|
+
method: "PUT",
|
|
655
|
+
route: "/admin/coupons/[id]",
|
|
656
|
+
auth: "session_cookie",
|
|
657
|
+
description: "Change a coupon, or switch it off. Only the fields you send change.",
|
|
658
|
+
params: [
|
|
659
|
+
COUPON_ID,
|
|
660
|
+
{ name: "code", type: "string", required: false, description: "New code, 3 to 50 characters of letters, digits, hyphens and underscores; stored in capital letters" },
|
|
661
|
+
{ name: "discountType", type: "string", required: false, description: "PERCENTAGE or FLAT", allowedValues: ["PERCENTAGE", "FLAT"] },
|
|
662
|
+
{ name: "discountValue", type: "number", required: false, description: "The percentage (at most 100) or the amount, from 0.01 up to 100000" },
|
|
663
|
+
{ name: "maxUses", type: "number", required: false, description: "How many paid bookings may use it, a whole number of 1 or more, or null for no limit" },
|
|
664
|
+
{ name: "expiresAt", type: "string", required: false, description: "When it stops working, as an ISO 8601 UTC date-time, or null for never" },
|
|
665
|
+
{ name: "isActive", type: "boolean", required: false, description: "false switches it off so it no longer works; true switches it back on" }
|
|
666
|
+
],
|
|
667
|
+
example: { id: "coupon_1", isActive: false },
|
|
668
|
+
responseShape: `{ coupon: { ${COUPON_FIELDS} } }`,
|
|
669
|
+
whenToUse: "To end a promotion (isActive false), extend it, or change its discount. To stop one that has been used, switch it off instead of deleting it.",
|
|
670
|
+
pitfalls: [
|
|
671
|
+
"The percentage cap is checked on the coupon as it would be after the change, so switching a flat coupon of 500 to PERCENTAGE without a new value is refused with 400.",
|
|
672
|
+
"The used count cannot be changed.",
|
|
673
|
+
"A coupon of another organization is a plain 404. A new code that is already taken is refused with 409.",
|
|
674
|
+
"Needs no scheduling switch."
|
|
675
|
+
],
|
|
676
|
+
dataSensitivity: "internal",
|
|
677
|
+
risk: "govern",
|
|
678
|
+
requiresApproval: {
|
|
679
|
+
action: "Change a coupon",
|
|
680
|
+
reason: "The change takes effect for the next booking that uses the code.",
|
|
681
|
+
prompt: "Change coupon {id}?"
|
|
682
|
+
}
|
|
683
|
+
},
|
|
684
|
+
{
|
|
685
|
+
name: "scheduling_delete_coupon",
|
|
686
|
+
module: "scheduling",
|
|
687
|
+
method: "DELETE",
|
|
688
|
+
route: "/admin/coupons/[id]",
|
|
689
|
+
auth: "session_cookie",
|
|
690
|
+
description: "Delete a coupon that has never been used.",
|
|
691
|
+
params: [COUPON_ID],
|
|
692
|
+
example: { id: "coupon_1" },
|
|
693
|
+
responseShape: "{ success: true }",
|
|
694
|
+
whenToUse: "Only to remove a coupon made by mistake. To stop one that has been used, use scheduling_update_coupon with isActive false.",
|
|
695
|
+
pitfalls: [
|
|
696
|
+
"Refused with 409 once the coupon has been used, even once.",
|
|
697
|
+
"A deleted coupon cannot be brought back.",
|
|
698
|
+
"Needs no scheduling switch."
|
|
699
|
+
],
|
|
700
|
+
dataSensitivity: "internal",
|
|
701
|
+
risk: "act",
|
|
702
|
+
requiresApproval: {
|
|
703
|
+
action: "Delete a coupon",
|
|
704
|
+
reason: "The coupon is removed for good.",
|
|
705
|
+
prompt: "Delete coupon {id}? This cannot be undone."
|
|
706
|
+
}
|
|
707
|
+
},
|
|
708
|
+
{
|
|
709
|
+
name: "scheduling_list_packages",
|
|
710
|
+
module: "scheduling",
|
|
711
|
+
method: "GET",
|
|
712
|
+
route: "/admin/packages",
|
|
713
|
+
auth: "session_cookie",
|
|
714
|
+
description: "List the prepaid service packages (a number of sessions sold as one), newest first, with the appointment type each is for.",
|
|
715
|
+
params: [],
|
|
716
|
+
example: {},
|
|
717
|
+
responseShape: `{ packages: [{ ${PACKAGE_FIELDS} }] }`,
|
|
718
|
+
whenToUse: "To find a package id, or see what packages are on offer and whether they are switched on.",
|
|
719
|
+
pitfalls: [MONEY_NOTE, "The answer is a plain list with no paging, including switched-off packages.", "Needs the scheduling switch to be on for the organization."],
|
|
720
|
+
dataSensitivity: "internal",
|
|
721
|
+
risk: "observe"
|
|
722
|
+
},
|
|
723
|
+
{
|
|
724
|
+
name: "scheduling_create_package",
|
|
725
|
+
module: "scheduling",
|
|
726
|
+
method: "POST",
|
|
727
|
+
route: "/admin/packages",
|
|
728
|
+
auth: "session_cookie",
|
|
729
|
+
description: "Create a prepaid package: a number of sessions with a price and a time in which to use them. It starts active.",
|
|
730
|
+
params: [
|
|
731
|
+
{ name: "name", type: "string", required: true, description: "Package name, 1 to 100 characters" },
|
|
732
|
+
{ name: "description", type: "string", required: false, description: "Description, up to 500 characters" },
|
|
733
|
+
{ name: "price", type: "number", required: true, description: "Price of the whole package, from 0.01 up to 99999" },
|
|
734
|
+
{ name: "sessions", type: "number", required: true, description: "How many sessions it includes, a whole number from 1 to 1000" },
|
|
735
|
+
{ name: "validDays", type: "number", required: false, description: "Days from purchase in which the sessions can be used, a whole number from 1 to 3650; 365 if left out" },
|
|
736
|
+
{ name: "typeId", type: "string", required: false, description: "Appointment type the package is for. A package with a type can only be used to book that type; with none it covers any type." }
|
|
737
|
+
],
|
|
738
|
+
example: { name: "Ten fittings", price: 500, sessions: 10, validDays: 365, typeId: "type_1" },
|
|
739
|
+
responseShape: `{ package: { ${PACKAGE_FIELDS} } }`,
|
|
740
|
+
whenToUse: "To offer sessions at a bundle price. Then give it to a client with scheduling_create_package_purchase.",
|
|
741
|
+
pitfalls: [
|
|
742
|
+
"A typeId that is not an appointment type of this organization is refused with 404.",
|
|
743
|
+
"Creating a package sells nothing and takes no payment; a client only gets sessions when a purchase is created for them.",
|
|
744
|
+
MONEY_NOTE,
|
|
745
|
+
"Needs the scheduling switch to be on for the organization."
|
|
746
|
+
],
|
|
747
|
+
dataSensitivity: "internal",
|
|
748
|
+
risk: "govern",
|
|
749
|
+
requiresApproval: {
|
|
750
|
+
action: "Create a package",
|
|
751
|
+
reason: "A package sets a price and a number of sessions that staff can then hand to clients.",
|
|
752
|
+
prompt: 'Create the package "{name}" with {sessions} sessions for {price}?'
|
|
753
|
+
}
|
|
754
|
+
},
|
|
755
|
+
{
|
|
756
|
+
name: "scheduling_update_package",
|
|
757
|
+
module: "scheduling",
|
|
758
|
+
method: "PUT",
|
|
759
|
+
route: "/admin/packages/[id]",
|
|
760
|
+
auth: "session_cookie",
|
|
761
|
+
description: "Change a package, or switch it off. Only the fields you send change.",
|
|
762
|
+
params: [
|
|
763
|
+
PACKAGE_ID,
|
|
764
|
+
{ name: "name", type: "string", required: false, description: "Package name, 1 to 100 characters" },
|
|
765
|
+
{ name: "description", type: "string", required: false, description: "Description, up to 500 characters, or null to clear it" },
|
|
766
|
+
{ name: "price", type: "number", required: false, description: "Price, from 0.01 up to 99999" },
|
|
767
|
+
{ name: "sessions", type: "number", required: false, description: "Sessions included, a whole number from 1 to 1000" },
|
|
768
|
+
{ name: "validDays", type: "number", required: false, description: "Days to use the sessions, from 1 to 3650" },
|
|
769
|
+
{ name: "typeId", type: "string", required: false, description: "Appointment type it is for, or null for any type" },
|
|
770
|
+
{ name: "isActive", type: "boolean", required: false, description: "false stops new purchases of it; true switches it back on" }
|
|
771
|
+
],
|
|
772
|
+
example: { id: "pkg_1", isActive: false },
|
|
773
|
+
responseShape: `{ package: { ${PACKAGE_FIELDS} } }`,
|
|
774
|
+
whenToUse: "To change the offer for future purchases, or take it off sale with isActive false.",
|
|
775
|
+
pitfalls: [
|
|
776
|
+
"Purchases already made keep the session count and price they were made with. Changing the package's typeId does change what existing purchases of it can book.",
|
|
777
|
+
"A typeId of another organization is refused with 404.",
|
|
778
|
+
"A switched-off package cannot be given to a client, but purchases already made stay usable.",
|
|
779
|
+
"Needs no scheduling switch."
|
|
780
|
+
],
|
|
781
|
+
dataSensitivity: "internal",
|
|
782
|
+
risk: "govern",
|
|
783
|
+
requiresApproval: {
|
|
784
|
+
action: "Change a package",
|
|
785
|
+
reason: "The change sets what new purchases cost and include, and what existing purchases can book.",
|
|
786
|
+
prompt: "Change package {id}?"
|
|
787
|
+
}
|
|
788
|
+
},
|
|
789
|
+
{
|
|
790
|
+
name: "scheduling_delete_package",
|
|
791
|
+
module: "scheduling",
|
|
792
|
+
method: "DELETE",
|
|
793
|
+
route: "/admin/packages/[id]",
|
|
794
|
+
auth: "session_cookie",
|
|
795
|
+
description: "Delete a package that no purchase refers to.",
|
|
796
|
+
params: [PACKAGE_ID],
|
|
797
|
+
example: { id: "pkg_1" },
|
|
798
|
+
responseShape: "{ success: true }",
|
|
799
|
+
whenToUse: "Only to remove a package made by mistake. To take one off sale, use scheduling_update_package with isActive false.",
|
|
800
|
+
pitfalls: [
|
|
801
|
+
"Refused with 409 once any purchase refers to the package.",
|
|
802
|
+
"A deleted package cannot be brought back.",
|
|
803
|
+
"Needs no scheduling switch."
|
|
804
|
+
],
|
|
805
|
+
dataSensitivity: "internal",
|
|
806
|
+
risk: "act",
|
|
807
|
+
requiresApproval: {
|
|
808
|
+
action: "Delete a package",
|
|
809
|
+
reason: "The package is removed for good.",
|
|
810
|
+
prompt: "Delete package {id}? This cannot be undone."
|
|
811
|
+
}
|
|
812
|
+
},
|
|
813
|
+
{
|
|
814
|
+
name: "scheduling_list_package_purchases",
|
|
815
|
+
module: "scheduling",
|
|
816
|
+
method: "GET",
|
|
817
|
+
route: "/admin/package-purchases",
|
|
818
|
+
auth: "session_cookie",
|
|
819
|
+
description: "List the packages given to clients, newest first, with how many sessions each has used.",
|
|
820
|
+
params: [
|
|
821
|
+
{ name: "limit", type: "number", required: false, description: "How many purchases to return (default 50, at most 200)" },
|
|
822
|
+
{ name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
|
|
823
|
+
],
|
|
824
|
+
example: {},
|
|
825
|
+
responseShape: `{ purchases: [{ ${PURCHASE_FIELDS} }], total, hasMore }`,
|
|
826
|
+
whenToUse: "To find a client's package, see how many sessions are left (sessionsTotal minus sessionsUsed), or get the id to book with.",
|
|
827
|
+
pitfalls: [
|
|
828
|
+
"status is ACTIVE, EXHAUSTED (all sessions used) or CANCELLED. A purchase stays ACTIVE after its expiry date passes, so check expiresAt as well as status before telling a client they can still book.",
|
|
829
|
+
"The answer carries client names and email addresses.",
|
|
830
|
+
"Needs the scheduling switch to be on for the organization."
|
|
831
|
+
],
|
|
832
|
+
dataSensitivity: "sensitive",
|
|
833
|
+
risk: "observe"
|
|
834
|
+
},
|
|
835
|
+
{
|
|
836
|
+
name: "scheduling_create_package_purchase",
|
|
837
|
+
module: "scheduling",
|
|
838
|
+
method: "POST",
|
|
839
|
+
route: "/admin/package-purchases",
|
|
840
|
+
auth: "session_cookie",
|
|
841
|
+
description: "Give a client a package: they receive its sessions to use for bookings. This records the purchase; it does not take a payment.",
|
|
842
|
+
params: [
|
|
843
|
+
{ name: "packageId", type: "string", required: true, description: "Package id; it must be switched on" },
|
|
844
|
+
{ name: "clientEmail", type: "string", required: true, description: "Client email address. Only a booking made with this same address can use the package." },
|
|
845
|
+
{ name: "clientName", type: "string", required: false, description: "Client name, up to 200 characters" },
|
|
846
|
+
{ name: "notes", type: "string", required: false, description: "Note, up to 1000 characters" },
|
|
847
|
+
{ name: "expiresAt", type: "string", required: false, description: "When the sessions stop being usable, as an ISO 8601 UTC date-time in the future. If left out it is the purchase date plus the package's validDays." }
|
|
848
|
+
],
|
|
849
|
+
example: { packageId: "pkg_1", clientEmail: "sam@example.com", clientName: "Sam Rivera" },
|
|
850
|
+
responseShape: `{ purchase: { ${PURCHASE_FIELDS} } }`,
|
|
851
|
+
whenToUse: "When a client has paid for a package outside this system, or is being given sessions. The client then books with packagePurchaseId in scheduling_book_appointment.",
|
|
852
|
+
pitfalls: [
|
|
853
|
+
"No payment is taken or checked. The package's current price is only written down as pricePaidCents, so only create a purchase when the money has been handled.",
|
|
854
|
+
"The client's sessions and expiry are fixed now: later changes to the package do not change this purchase.",
|
|
855
|
+
"A package that does not exist, belongs to another organization or is switched off is refused with 404. An expiresAt in the past is refused with 400.",
|
|
856
|
+
"Needs the scheduling switch to be on for the organization."
|
|
857
|
+
],
|
|
858
|
+
dataSensitivity: "sensitive",
|
|
859
|
+
risk: "govern",
|
|
860
|
+
requiresApproval: {
|
|
861
|
+
action: "Give a client a package",
|
|
862
|
+
reason: "The client can book that many sessions without paying again, and nothing here checks that they paid.",
|
|
863
|
+
prompt: "Give {clientEmail} the package {packageId}?"
|
|
864
|
+
}
|
|
865
|
+
},
|
|
866
|
+
{
|
|
867
|
+
name: "scheduling_update_package_purchase",
|
|
868
|
+
module: "scheduling",
|
|
869
|
+
method: "PATCH",
|
|
870
|
+
route: "/admin/package-purchases/[id]",
|
|
871
|
+
auth: "session_cookie",
|
|
872
|
+
description: "Cancel a purchase, bring a cancelled one back, or correct the client's name, email or the notes.",
|
|
873
|
+
params: [
|
|
874
|
+
{ name: "id", type: "string", required: true, description: "Purchase id" },
|
|
875
|
+
{ name: "status", type: "string", required: false, description: "CANCELLED stops the client using the remaining sessions; ACTIVE brings a cancelled purchase back", allowedValues: ["ACTIVE", "CANCELLED"] },
|
|
876
|
+
{ name: "clientName", type: "string", required: false, description: "Client name, up to 200 characters" },
|
|
877
|
+
{ name: "clientEmail", type: "string", required: false, description: "Client email. Bookings must use this address to draw on the package." },
|
|
878
|
+
{ name: "notes", type: "string", required: false, description: "Note, up to 1000 characters" }
|
|
879
|
+
],
|
|
880
|
+
example: { id: "purchase_1", status: "CANCELLED" },
|
|
881
|
+
responseShape: `{ purchase: { ${PURCHASE_FIELDS} } }`,
|
|
882
|
+
whenToUse: "To withdraw a package that was given by mistake or refunded elsewhere, or to fix a mistyped email so the client can use it.",
|
|
883
|
+
pitfalls: [
|
|
884
|
+
"Send at least one field, or it is refused with 400.",
|
|
885
|
+
"Cancelling works only on an ACTIVE purchase; reactivating only on a CANCELLED one that still has sessions left and has not expired. Anything else is refused with 409.",
|
|
886
|
+
"Cancelling takes back only the unused sessions: bookings already made with the package are left as they are, and no money is refunded.",
|
|
887
|
+
"The expiry and the number of sessions cannot be changed. To give more time, create a new purchase.",
|
|
888
|
+
"Needs no scheduling switch."
|
|
889
|
+
],
|
|
890
|
+
dataSensitivity: "sensitive",
|
|
891
|
+
risk: "govern",
|
|
892
|
+
requiresApproval: {
|
|
893
|
+
action: "Change a package purchase",
|
|
894
|
+
reason: "It can take sessions away from a client or give them back, and a changed email decides who may use the package.",
|
|
895
|
+
prompt: "Change package purchase {id}?"
|
|
896
|
+
}
|
|
897
|
+
}
|
|
898
|
+
];
|
|
899
|
+
|
|
563
900
|
// src/agent/calendar-tools.ts
|
|
564
901
|
var ID2 = { name: "id", type: "string", required: true, description: "Calendar id" };
|
|
565
902
|
var CALENDAR_FIELDS = "id, name, slug, type, timezone, isActive, staffName, staffEmail, staffAvatar, userId, location, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, slotGranularityMinutes";
|
|
@@ -675,6 +1012,7 @@ var CALENDAR_TOOLS = [
|
|
|
675
1012
|
whenToUse: "To rename a calendar, change its time zone or slot size, link it to a person, or switch it off or on.",
|
|
676
1013
|
pitfalls: [
|
|
677
1014
|
"Changing the time zone changes what the opening hours mean in real time.",
|
|
1015
|
+
"Renaming a calendar to the name of another active calendar, ignoring capital letters, is refused with 409. A name that only gives the same web address is not checked on rename, because renaming never changes the web address.",
|
|
678
1016
|
"Switching off the last active calendar is refused with 409, as archiving is. If the other changes in the same request then fail to save, the calendar is switched back on.",
|
|
679
1017
|
"Linking a calendar to a person (userId) changes who can see it when staff are limited to their groups.",
|
|
680
1018
|
"Switching a calendar back on (isActive true) does not give back its short booking address; only the organization-qualified address works until it is registered again."
|
|
@@ -819,119 +1157,885 @@ var CALENDAR_TOOLS = [
|
|
|
819
1157
|
}
|
|
820
1158
|
];
|
|
821
1159
|
|
|
822
|
-
// src/agent/
|
|
823
|
-
var
|
|
824
|
-
var
|
|
825
|
-
var
|
|
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 = [
|
|
1160
|
+
// src/agent/policy-tools.ts
|
|
1161
|
+
var FEE = "An object with enabled (true or false), amount (0 to 10000, required when enabled is true; for a PERCENTAGE it is at most 100) and feeType (FLAT or PERCENTAGE; FLAT if left out).";
|
|
1162
|
+
var PREVENTION = "An object with enabled (true or false; false if left out), threshold (how many no-shows trigger it, a whole number 1 to 20; 2 if left out) and action (REQUIRE_APPROVAL, so the booking waits for a person, or BLOCK_BOOKING, so online booking is refused; REQUIRE_APPROVAL if left out).";
|
|
1163
|
+
var POLICY_TOOLS = [
|
|
857
1164
|
{
|
|
858
|
-
name: "
|
|
1165
|
+
name: "scheduling_get_cancellation_policy",
|
|
859
1166
|
module: "scheduling",
|
|
860
1167
|
method: "GET",
|
|
861
|
-
route: "/admin/
|
|
1168
|
+
route: "/admin/policy",
|
|
862
1169
|
auth: "session_cookie",
|
|
863
|
-
description: "
|
|
1170
|
+
description: "Read the organization's cancellation policy, with what each active appointment type enforces for itself, and when the policy was last saved.",
|
|
864
1171
|
params: [],
|
|
865
1172
|
example: {},
|
|
866
|
-
responseShape:
|
|
867
|
-
whenToUse: "
|
|
868
|
-
pitfalls: [
|
|
1173
|
+
responseShape: "{ policy: { defaultAllowCancel, defaultCancelDeadlineHrs, noShowFee: { enabled, amount, feeType }, lateCancelFee: { enabled, amount, feeType }, requireCardOnFile, noShowPrevention: { enabled, threshold, action } }, types: [{ id, name, allowCancel, cancelDeadlineHrs }], updatedAt }",
|
|
1174
|
+
whenToUse: "Before changing the policy, to see what is set now, and to see each type's own cancel rules.",
|
|
1175
|
+
pitfalls: [
|
|
1176
|
+
"Until a policy is saved, the answer is the built-in default: cancelling allowed, 24 hours notice, no fees, no card on file, no-show prevention off.",
|
|
1177
|
+
"Saving the policy stores the fees, the card-on-file switch and the default cancel rules, but nothing in the scheduling API charges a fee, asks for a card or applies those two defaults; each appointment type's own allowCancel and cancelDeadlineHrs (in types) are what clients meet. The no-show rule is applied only when the host server supplies a booking policy that reads it.",
|
|
1178
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1179
|
+
],
|
|
869
1180
|
dataSensitivity: "internal",
|
|
870
1181
|
risk: "observe"
|
|
871
1182
|
},
|
|
872
1183
|
{
|
|
873
|
-
name: "
|
|
1184
|
+
name: "scheduling_save_cancellation_policy",
|
|
874
1185
|
module: "scheduling",
|
|
875
|
-
method: "
|
|
876
|
-
route: "/admin/
|
|
1186
|
+
method: "PUT",
|
|
1187
|
+
route: "/admin/policy",
|
|
877
1188
|
auth: "session_cookie",
|
|
878
|
-
description: "
|
|
879
|
-
params: [
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
1189
|
+
description: "Save the organization's cancellation policy. This replaces the whole policy: a field you leave out goes back to its default, not to what it was.",
|
|
1190
|
+
params: [
|
|
1191
|
+
{ name: "defaultAllowCancel", type: "boolean", required: false, description: "Whether clients may cancel by default; true if left out" },
|
|
1192
|
+
{ name: "defaultCancelDeadlineHrs", type: "number", required: false, description: "Default hours before the start after which a client may no longer cancel, a whole number 0 to 720; 0 means no deadline; 24 if left out" },
|
|
1193
|
+
{ name: "noShowFee", type: "json-object", required: true, description: `Fee for a no-show. ${FEE}` },
|
|
1194
|
+
{ name: "lateCancelFee", type: "json-object", required: true, description: `Fee for a late cancellation. ${FEE}` },
|
|
1195
|
+
{ name: "requireCardOnFile", type: "boolean", required: false, description: "Whether a card must be kept on file; false if left out" },
|
|
1196
|
+
{ name: "noShowPrevention", type: "json-object", required: false, description: `What happens to a client with repeated no-shows. ${PREVENTION} Left out means off.` },
|
|
1197
|
+
{ name: "clientUpdatedAt", type: "string", required: false, description: "The updatedAt from the read you based this on, as an ISO 8601 date-time. When sent, a save is refused with 409 if anyone saved the policy since." }
|
|
1198
|
+
],
|
|
1199
|
+
example: {
|
|
1200
|
+
defaultAllowCancel: true,
|
|
1201
|
+
defaultCancelDeadlineHrs: 48,
|
|
1202
|
+
noShowFee: { enabled: true, amount: 25, feeType: "FLAT" },
|
|
1203
|
+
lateCancelFee: { enabled: false },
|
|
1204
|
+
requireCardOnFile: false,
|
|
1205
|
+
noShowPrevention: { enabled: true, threshold: 3, action: "REQUIRE_APPROVAL" }
|
|
1206
|
+
},
|
|
1207
|
+
responseShape: "{ success: true }",
|
|
1208
|
+
whenToUse: "To change the policy. Read it first with scheduling_get_cancellation_policy and send back every field that should stay, with its updatedAt as clientUpdatedAt.",
|
|
883
1209
|
pitfalls: [
|
|
884
|
-
"A
|
|
885
|
-
"
|
|
886
|
-
"
|
|
887
|
-
"The
|
|
888
|
-
"directoryClaimed false means the short booking address could not be registered; only the organization-qualified address works then.",
|
|
1210
|
+
"It replaces everything. A field left out is reset to its default, so a change to one field must resend all the others.",
|
|
1211
|
+
"A fee that is enabled needs an amount, and a PERCENTAGE fee cannot be over 100: both refused with 400, and nothing is saved.",
|
|
1212
|
+
"Only the saved policy changes. Fees are not charged and a card is not asked for by this API; see the note on scheduling_get_cancellation_policy.",
|
|
1213
|
+
"The organization's other settings are kept.",
|
|
889
1214
|
"Needs the scheduling switch to be on for the organization."
|
|
890
1215
|
],
|
|
891
1216
|
dataSensitivity: "internal",
|
|
892
|
-
risk: "
|
|
1217
|
+
risk: "govern",
|
|
893
1218
|
requiresApproval: {
|
|
894
|
-
action: "
|
|
895
|
-
reason: "
|
|
896
|
-
prompt:
|
|
1219
|
+
action: "Save the cancellation policy",
|
|
1220
|
+
reason: "The policy is what the business tells clients about cancelling, fees and no-shows, and a no-show rule can refuse online booking to clients with repeated no-shows.",
|
|
1221
|
+
prompt: "Save the cancellation policy? This replaces the current policy."
|
|
897
1222
|
}
|
|
898
|
-
}
|
|
1223
|
+
}
|
|
1224
|
+
];
|
|
1225
|
+
|
|
1226
|
+
// src/agent/privacy-tools.ts
|
|
1227
|
+
var COUNTS = "{ appointments, notifications, waitlistEntries, packagePurchases, recurringSeries, webhookDeliveries }";
|
|
1228
|
+
var NOT_ENABLED = "A server without data export and erasure answers 501.";
|
|
1229
|
+
var WHO = "Name the person with email, clientId or both. A client id also stands for every address that client has booked with.";
|
|
1230
|
+
var SUBJECT_PARAMS = [
|
|
1231
|
+
{ name: "email", type: "string", required: false, description: "The person's email address: one valid address, up to 254 characters, in any letter case" },
|
|
1232
|
+
{ name: "clientId", type: "string", required: false, description: "The client id in the host system, 1 to 200 characters" }
|
|
1233
|
+
];
|
|
1234
|
+
var PRIVACY_TOOLS = [
|
|
899
1235
|
{
|
|
900
|
-
name: "
|
|
1236
|
+
name: "scheduling_export_person_data",
|
|
901
1237
|
module: "scheduling",
|
|
902
|
-
method: "
|
|
903
|
-
route: "/admin/
|
|
1238
|
+
method: "POST",
|
|
1239
|
+
route: "/admin/privacy/export",
|
|
904
1240
|
auth: "session_cookie",
|
|
905
|
-
description: "
|
|
906
|
-
params: [
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
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.",
|
|
1241
|
+
description: "Export everything held about one person as a single document: their bookings, messages, waitlist entries, package purchases, repeating series and webhook events.",
|
|
1242
|
+
params: [...SUBJECT_PARAMS],
|
|
1243
|
+
example: { email: "sam@example.com" },
|
|
1244
|
+
responseShape: `{ format, version, exportedAt, organizationId, subject: { emails, clientId }, counts: ${COUNTS}, appointments, notifications, waitlistEntries, packagePurchases, recurringSeries, webhookDeliveries }`,
|
|
1245
|
+
whenToUse: "When a person asks what is held about them. It reads only; to remove the data use scheduling_erase_person_data.",
|
|
914
1246
|
pitfalls: [
|
|
915
|
-
|
|
916
|
-
"
|
|
917
|
-
"
|
|
918
|
-
"
|
|
919
|
-
"
|
|
920
|
-
|
|
1247
|
+
`${WHO} Sending neither, an address that is not one valid address, or any other field is refused with 400.`,
|
|
1248
|
+
"The answer is everything about the person, including notes, staff notes, intake answers, payment amounts and message text. Treat it as highly sensitive and give it only to the person's own request.",
|
|
1249
|
+
"Self-service links and waitlist links are left out or removed from the messages, so the document cannot be used to change a booking.",
|
|
1250
|
+
"Someone with no data gets empty lists and zero counts, not an error. The request is recorded either way, and if it cannot be recorded nothing is returned.",
|
|
1251
|
+
"The request is recorded with only a digest of the address, never the address itself.",
|
|
1252
|
+
NOT_ENABLED,
|
|
1253
|
+
"Needs the scheduling switch to be on for the organization."
|
|
921
1254
|
],
|
|
922
|
-
dataSensitivity: "
|
|
1255
|
+
dataSensitivity: "critical",
|
|
923
1256
|
risk: "act",
|
|
924
1257
|
requiresApproval: {
|
|
925
|
-
action: "
|
|
926
|
-
reason: "
|
|
927
|
-
prompt: "
|
|
1258
|
+
action: "Export a person's data",
|
|
1259
|
+
reason: "Everything held about one person, including notes and payment details, is read out in one document.",
|
|
1260
|
+
prompt: "Export all the data held about this person?"
|
|
928
1261
|
}
|
|
929
1262
|
},
|
|
930
1263
|
{
|
|
931
|
-
name: "
|
|
1264
|
+
name: "scheduling_erase_person_data",
|
|
932
1265
|
module: "scheduling",
|
|
933
|
-
method: "
|
|
934
|
-
route: "/admin/
|
|
1266
|
+
method: "POST",
|
|
1267
|
+
route: "/admin/privacy/erase",
|
|
1268
|
+
auth: "session_cookie",
|
|
1269
|
+
description: "Erase the personal data held about one person. Without confirm true it only shows what would be erased and what is in the way.",
|
|
1270
|
+
params: [
|
|
1271
|
+
...SUBJECT_PARAMS,
|
|
1272
|
+
{ name: "confirm", type: "boolean", required: false, description: "true really erases. Left out or false only previews and changes nothing." }
|
|
1273
|
+
],
|
|
1274
|
+
example: { email: "sam@example.com" },
|
|
1275
|
+
responseShape: `{ erased, preview?: { counts: ${COUNTS}, blockers: { upcomingAppointments, liveWaitlistEntries }, canErase, warnings }, counts?: ${COUNTS} }`,
|
|
1276
|
+
whenToUse: "When a person asks to be forgotten. Always preview first, show the person what will happen, and only then send confirm true.",
|
|
1277
|
+
pitfalls: [
|
|
1278
|
+
`${WHO}`,
|
|
1279
|
+
"Without confirm the answer is { erased: false, preview }; with confirm true it is { erased: true, counts }.",
|
|
1280
|
+
'It cannot be undone. Bookings, package purchases and repeating series stay as anonymous records ("Erased client", erased@erased.invalid, phone, notes and intake answers cleared, self-service links changed); messages, waitlist entries and queued webhook events about the person are deleted.',
|
|
1281
|
+
"It is refused with 409 while the person has an upcoming pending or confirmed booking or a waitlist offer they hold (blockers says how many). Cancel those first.",
|
|
1282
|
+
"warnings notes sessions left on an active package: after erasure it can no longer be matched to the person.",
|
|
1283
|
+
"Copies already sent elsewhere, such as emails, webhook receivers or backups outside this system, are not recalled.",
|
|
1284
|
+
NOT_ENABLED,
|
|
1285
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1286
|
+
],
|
|
1287
|
+
dataSensitivity: "critical",
|
|
1288
|
+
risk: "govern",
|
|
1289
|
+
requiresApproval: {
|
|
1290
|
+
action: "Erase a person's data",
|
|
1291
|
+
reason: "With confirm true the personal data is permanently erased and cannot be recovered. Without it, it only previews.",
|
|
1292
|
+
prompt: "Erase the data held about this person (confirm true erases for good; otherwise it only previews)?"
|
|
1293
|
+
}
|
|
1294
|
+
},
|
|
1295
|
+
{
|
|
1296
|
+
name: "scheduling_list_privacy_requests",
|
|
1297
|
+
module: "scheduling",
|
|
1298
|
+
method: "GET",
|
|
1299
|
+
route: "/admin/privacy/requests",
|
|
1300
|
+
auth: "session_cookie",
|
|
1301
|
+
description: "List the data exports and erasures that have been carried out, newest first, with who asked and how much each covered.",
|
|
1302
|
+
params: [
|
|
1303
|
+
{ name: "limit", type: "number", required: false, description: "How many requests to return (default 50, at most 200)" },
|
|
1304
|
+
{ name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
|
|
1305
|
+
],
|
|
1306
|
+
example: {},
|
|
1307
|
+
responseShape: `{ requests: [{ id, kind, requestedBy, counts: ${COUNTS}, createdAt }], total, hasMore }`,
|
|
1308
|
+
whenToUse: "To show that a request was handled, or to see who has been exporting or erasing data.",
|
|
1309
|
+
pitfalls: [
|
|
1310
|
+
"kind is EXPORT or ERASE. The log holds counts and who asked, never the person's name or address.",
|
|
1311
|
+
NOT_ENABLED,
|
|
1312
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1313
|
+
],
|
|
1314
|
+
dataSensitivity: "internal",
|
|
1315
|
+
risk: "observe"
|
|
1316
|
+
}
|
|
1317
|
+
];
|
|
1318
|
+
|
|
1319
|
+
// src/agent/routing-tools.ts
|
|
1320
|
+
var SUMMARY_FIELDS = "id, name, slug, description, isActive, updatedAt";
|
|
1321
|
+
var FORM_FIELDS = "id, name, slug, description, isActive, questions, rules, fallback, createdAt, updatedAt";
|
|
1322
|
+
var FORM_ID = { name: "id", type: "string", required: true, description: "Routing form id" };
|
|
1323
|
+
var NOT_ENABLED2 = "A server without routing forms answers 501.";
|
|
1324
|
+
var DETAILS = "A form with any problem is refused with 400 and nothing is saved; for a problem in the form itself, details lists every one with its path (such as rules[1].conditions[0].value) and the reason. A body of the wrong shape (a missing fallback, a list that is too long) is refused earlier with 400 and details that name the field instead.";
|
|
1325
|
+
var QUESTIONS = "A list of 1 to 20 questions, each an object with id (starts with a letter; letters, digits, - and _; at most 40 characters; different for each question), label (1 to 200 characters), type (select, radio, checkbox, text or number), required (true or false; false if left out) and, for select, radio and checkbox only, options (2 to 50 different choices of 1 to 100 characters).";
|
|
1326
|
+
var RULES = `A list of 1 to 50 rules, tried in order; the first whose conditions hold decides where the client goes. Each rule is an object with match ("all" conditions must hold, or "any"; "all" if left out), conditions (1 to 10, each an object with questionId, operator and value) and destination (an object with typeId, calendarId or both), and optionally id (made up if left out) and label (up to 200 characters). Operators by question type: select and radio take equals, not_equals, in, is_answered, is_empty; checkbox takes contains, not_contains, is_answered, is_empty; text takes equals, not_equals, contains, not_contains, is_answered, is_empty; number takes equals, not_equals, gt, gte, lt, lte, is_answered, is_empty. For in the value is a list of the question's options. Otherwise the value is one of the question's options, or a text of 1 to 200 characters for a text question, or a number; is_answered and is_empty take no value.`;
|
|
1327
|
+
var FALLBACK = 'What happens when no rule matches. Either { "kind": "DESTINATION", "destination": { typeId and/or calendarId } } to send the client somewhere anyway, or { "kind": "MESSAGE", "message": "1 to 500 characters" } to show a message.';
|
|
1328
|
+
var ROUTING_TOOLS = [
|
|
1329
|
+
{
|
|
1330
|
+
name: "scheduling_list_routing_forms",
|
|
1331
|
+
module: "scheduling",
|
|
1332
|
+
method: "GET",
|
|
1333
|
+
route: "/admin/routing-forms",
|
|
1334
|
+
auth: "session_cookie",
|
|
1335
|
+
description: "List the routing forms of the organization, by name, with whether each is switched on.",
|
|
1336
|
+
params: [],
|
|
1337
|
+
example: {},
|
|
1338
|
+
responseShape: `{ forms: [{ ${SUMMARY_FIELDS} }] }`,
|
|
1339
|
+
whenToUse: "To find a form id or slug. Read one form in full with scheduling_get_routing_form.",
|
|
1340
|
+
pitfalls: ["The list has no questions or rules; it is a summary.", "The answer is a plain list with no paging, ordered by name.", NOT_ENABLED2, "Needs the scheduling switch to be on for the organization."],
|
|
1341
|
+
dataSensitivity: "internal",
|
|
1342
|
+
risk: "observe"
|
|
1343
|
+
},
|
|
1344
|
+
{
|
|
1345
|
+
name: "scheduling_get_routing_form",
|
|
1346
|
+
module: "scheduling",
|
|
1347
|
+
method: "GET",
|
|
1348
|
+
route: "/admin/routing-forms/[id]",
|
|
1349
|
+
auth: "session_cookie",
|
|
1350
|
+
description: "Read one routing form in full: its questions, its rules and what happens when no rule matches.",
|
|
1351
|
+
params: [FORM_ID],
|
|
1352
|
+
example: { id: "form_1" },
|
|
1353
|
+
responseShape: `{ form: { ${FORM_FIELDS} } }`,
|
|
1354
|
+
whenToUse: "Before changing a form, to see what it is now and send back what should stay.",
|
|
1355
|
+
pitfalls: ["A form of another organization is a plain 404.", NOT_ENABLED2, "Needs the scheduling switch to be on for the organization."],
|
|
1356
|
+
dataSensitivity: "internal",
|
|
1357
|
+
risk: "observe"
|
|
1358
|
+
},
|
|
1359
|
+
{
|
|
1360
|
+
name: "scheduling_create_routing_form",
|
|
1361
|
+
module: "scheduling",
|
|
1362
|
+
method: "POST",
|
|
1363
|
+
route: "/admin/routing-forms",
|
|
1364
|
+
auth: "session_cookie",
|
|
1365
|
+
description: "Create a routing form that asks a client a few questions and sends them to the right appointment type or calendar.",
|
|
1366
|
+
params: [
|
|
1367
|
+
{ name: "name", type: "string", required: true, description: "Name for staff, 1 to 100 characters" },
|
|
1368
|
+
{ name: "slug", type: "string", required: true, description: "Short name used in the form's public address: lower-case words joined by dashes, at most 60 characters. No other organization on the server may use the same one." },
|
|
1369
|
+
{ name: "description", type: "string", required: false, description: "A line shown above the questions, up to 500 characters" },
|
|
1370
|
+
{ name: "isActive", type: "boolean", required: false, description: "Whether clients can use it; true if left out" },
|
|
1371
|
+
{ name: "questions", type: "json-array", required: true, description: QUESTIONS },
|
|
1372
|
+
{ name: "rules", type: "json-array", required: true, description: RULES },
|
|
1373
|
+
{ name: "fallback", type: "json-object", required: true, description: FALLBACK }
|
|
1374
|
+
],
|
|
1375
|
+
example: {
|
|
1376
|
+
name: "Which service?",
|
|
1377
|
+
slug: "which-service",
|
|
1378
|
+
questions: [{ id: "goal", label: "What do you need?", type: "radio", required: true, options: ["A new suit", "An alteration"] }],
|
|
1379
|
+
rules: [{ conditions: [{ questionId: "goal", operator: "equals", value: "An alteration" }], destination: { typeId: "type_1" } }],
|
|
1380
|
+
fallback: { kind: "MESSAGE", message: "Please call us to book." }
|
|
1381
|
+
},
|
|
1382
|
+
responseShape: `{ form: { ${FORM_FIELDS} } }`,
|
|
1383
|
+
whenToUse: "When clients need help choosing the right service. Try it with scheduling_test_routing_form before sharing the link.",
|
|
1384
|
+
pitfalls: [
|
|
1385
|
+
DETAILS,
|
|
1386
|
+
"Every type and calendar a rule or the fallback names must exist, be switched on and, when both are named, the type must be offered on that calendar; otherwise it is refused with 400.",
|
|
1387
|
+
"A slug that another organization uses is refused with 400 (details names slug); the same slug on two of your own forms, or a 51st form, is refused with 409.",
|
|
1388
|
+
"At least one rule is required.",
|
|
1389
|
+
NOT_ENABLED2,
|
|
1390
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1391
|
+
],
|
|
1392
|
+
dataSensitivity: "internal",
|
|
1393
|
+
risk: "act",
|
|
1394
|
+
requiresApproval: {
|
|
1395
|
+
action: "Create a routing form",
|
|
1396
|
+
reason: "Clients who use the form are sent wherever its rules say.",
|
|
1397
|
+
prompt: 'Create the routing form "{name}"?'
|
|
1398
|
+
}
|
|
1399
|
+
},
|
|
1400
|
+
{
|
|
1401
|
+
name: "scheduling_update_routing_form",
|
|
1402
|
+
module: "scheduling",
|
|
1403
|
+
method: "PUT",
|
|
1404
|
+
route: "/admin/routing-forms/[id]",
|
|
1405
|
+
auth: "session_cookie",
|
|
1406
|
+
description: "Change a routing form, or switch it off. Only the fields you send change; the whole form is checked again afterwards.",
|
|
1407
|
+
params: [
|
|
1408
|
+
FORM_ID,
|
|
1409
|
+
{ name: "name", type: "string", required: false, description: "Name for staff, 1 to 100 characters" },
|
|
1410
|
+
{ name: "slug", type: "string", required: false, description: "Public short name; changing it breaks links that use the old one" },
|
|
1411
|
+
{ name: "description", type: "string", required: false, description: "A line shown above the questions, up to 500 characters, or null to clear it" },
|
|
1412
|
+
{ name: "isActive", type: "boolean", required: false, description: "false stops clients using it; true switches it back on" },
|
|
1413
|
+
{ name: "questions", type: "json-array", required: false, description: `${QUESTIONS} Replaces the whole list.` },
|
|
1414
|
+
{ name: "rules", type: "json-array", required: false, description: `${RULES} Replaces the whole list.` },
|
|
1415
|
+
{ name: "fallback", type: "json-object", required: false, description: `${FALLBACK} Replaces the current fallback.` }
|
|
1416
|
+
],
|
|
1417
|
+
example: { id: "form_1", isActive: false },
|
|
1418
|
+
responseShape: `{ form: { ${FORM_FIELDS} } }`,
|
|
1419
|
+
whenToUse: "To reword a question, add a rule, or switch a form off. Read the form first, because questions, rules and fallback replace what is there.",
|
|
1420
|
+
pitfalls: [
|
|
1421
|
+
"Send at least one field, or it is refused with 400.",
|
|
1422
|
+
DETAILS,
|
|
1423
|
+
"Changing a question can break a rule that uses it, so the whole result is checked; the destinations are checked again only when questions, rules or the fallback are sent, so renaming or switching off a form always works.",
|
|
1424
|
+
"A slug that another organization uses is refused with 400, and one that another of your own forms uses with 409. A form of another organization is a plain 404.",
|
|
1425
|
+
NOT_ENABLED2,
|
|
1426
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1427
|
+
],
|
|
1428
|
+
dataSensitivity: "internal",
|
|
1429
|
+
risk: "act",
|
|
1430
|
+
requiresApproval: {
|
|
1431
|
+
action: "Change a routing form",
|
|
1432
|
+
reason: "Clients are sent wherever the changed rules say, and a changed slug breaks links already shared.",
|
|
1433
|
+
prompt: "Change routing form {id}?"
|
|
1434
|
+
}
|
|
1435
|
+
},
|
|
1436
|
+
{
|
|
1437
|
+
name: "scheduling_delete_routing_form",
|
|
1438
|
+
module: "scheduling",
|
|
1439
|
+
method: "DELETE",
|
|
1440
|
+
route: "/admin/routing-forms/[id]",
|
|
1441
|
+
auth: "session_cookie",
|
|
1442
|
+
description: "Delete a routing form for good.",
|
|
1443
|
+
params: [FORM_ID],
|
|
1444
|
+
example: { id: "form_1" },
|
|
1445
|
+
responseShape: "{ success: true }",
|
|
1446
|
+
whenToUse: "Only to remove a form that is no longer wanted. To stop clients using one for now, switch it off with scheduling_update_routing_form.",
|
|
1447
|
+
pitfalls: ["A link to the form stops working at once.", "A deleted form cannot be brought back.", "A form of another organization is a plain 404.", NOT_ENABLED2, "Needs the scheduling switch to be on for the organization."],
|
|
1448
|
+
dataSensitivity: "internal",
|
|
1449
|
+
risk: "act",
|
|
1450
|
+
requiresApproval: {
|
|
1451
|
+
action: "Delete a routing form",
|
|
1452
|
+
reason: "The form is removed for good and any link to it stops working.",
|
|
1453
|
+
prompt: "Delete routing form {id}? This cannot be undone."
|
|
1454
|
+
}
|
|
1455
|
+
},
|
|
1456
|
+
{
|
|
1457
|
+
name: "scheduling_test_routing_form",
|
|
1458
|
+
module: "scheduling",
|
|
1459
|
+
method: "POST",
|
|
1460
|
+
route: "/admin/routing-forms/[id]/test",
|
|
1461
|
+
auth: "session_cookie",
|
|
1462
|
+
description: "Try sample answers on a routing form and see where a client would be sent. Nothing is saved or booked.",
|
|
1463
|
+
params: [
|
|
1464
|
+
FORM_ID,
|
|
1465
|
+
{ name: "answers", type: "json-object", required: true, description: "The sample answers, an object keyed by question id: a text for select, radio and text questions, a list of options for checkbox, a number for number. Every required question needs an answer, nothing the form does not ask is allowed, and a text answer is at most 1000 characters." }
|
|
1466
|
+
],
|
|
1467
|
+
example: { id: "form_1", answers: { goal: "An alteration" } },
|
|
1468
|
+
responseShape: "{ destination, message, matchedRuleId, usedFallback, allMatchedRuleIds }",
|
|
1469
|
+
whenToUse: "After creating or changing a form, to check each path before clients use it.",
|
|
1470
|
+
pitfalls: [
|
|
1471
|
+
"It works even when the form is switched off.",
|
|
1472
|
+
"allMatchedRuleIds lists every rule the answers satisfy, in order, even those not live; only the first live one decides, and its id is matchedRuleId. destination is null, and message is set, when the form says to show a message or when the fallback destination is gone. It carries typeId, typeSlug, typeName, calendarId, calendarSlug and calendarName.",
|
|
1473
|
+
"A rule whose destination has since been switched off is skipped and the next matching rule is tried; if the fallback destination is also gone, message tells the client to get in touch.",
|
|
1474
|
+
"Answers that do not fit the form are refused with 400 and details.",
|
|
1475
|
+
"It changes nothing, but it is a POST, so it asks first.",
|
|
1476
|
+
NOT_ENABLED2
|
|
1477
|
+
],
|
|
1478
|
+
dataSensitivity: "none",
|
|
1479
|
+
risk: "act",
|
|
1480
|
+
requiresApproval: {
|
|
1481
|
+
action: "Test a routing form",
|
|
1482
|
+
reason: "It runs the form against sample answers; nothing is changed.",
|
|
1483
|
+
prompt: "Test routing form {id} with these answers?"
|
|
1484
|
+
}
|
|
1485
|
+
}
|
|
1486
|
+
];
|
|
1487
|
+
|
|
1488
|
+
// src/agent/series-tools.ts
|
|
1489
|
+
var SERIES_FIELDS = "id, organizationId, calendarId, typeId, frequency, occurrences, startTimeLocal, durationMins, timezone, endsAt, clientEmail, clientName, clientPhone, clientId, notes, status, createdAt, updatedAt";
|
|
1490
|
+
var FREQUENCIES = ["DAILY", "WEEKLY", "BIWEEKLY", "MONTHLY"];
|
|
1491
|
+
var SCOPES = ["ONE", "THIS_AND_FOLLOWING", "ALL"];
|
|
1492
|
+
var SERIES_TOOLS = [
|
|
1493
|
+
{
|
|
1494
|
+
name: "scheduling_list_recurring_series",
|
|
1495
|
+
module: "scheduling",
|
|
1496
|
+
method: "GET",
|
|
1497
|
+
route: "/admin/recurring",
|
|
1498
|
+
auth: "session_cookie",
|
|
1499
|
+
description: "List repeating series of appointments, newest first, each with its calendar, its appointment type and the status of every occurrence.",
|
|
1500
|
+
params: [
|
|
1501
|
+
{ name: "limit", type: "number", required: false, description: "How many series to return (default 50, at most 200)" },
|
|
1502
|
+
{ name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
|
|
1503
|
+
],
|
|
1504
|
+
example: {},
|
|
1505
|
+
responseShape: `{ series: [{ ${SERIES_FIELDS}, calendar: { id, name }, type: { id, name }, appointments: [{ id, status }] }], total, hasMore }`,
|
|
1506
|
+
whenToUse: "To find a series id, or to see which series a client has.",
|
|
1507
|
+
pitfalls: [
|
|
1508
|
+
"Only series on calendars the person may see are listed.",
|
|
1509
|
+
"The appointments inside each series carry only id and status. Read one series with scheduling_get_recurring_series for the times.",
|
|
1510
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1511
|
+
],
|
|
1512
|
+
dataSensitivity: "sensitive",
|
|
1513
|
+
risk: "observe"
|
|
1514
|
+
},
|
|
1515
|
+
{
|
|
1516
|
+
name: "scheduling_get_recurring_series",
|
|
1517
|
+
module: "scheduling",
|
|
1518
|
+
method: "GET",
|
|
1519
|
+
route: "/admin/recurring/[id]",
|
|
1520
|
+
auth: "session_cookie",
|
|
1521
|
+
description: "Read one repeating series with every occurrence in order, with its start and end time, status and notes.",
|
|
1522
|
+
params: [{ name: "id", type: "string", required: true, description: "Series id" }],
|
|
1523
|
+
example: { id: "series_1" },
|
|
1524
|
+
responseShape: `{ series: { ${SERIES_FIELDS}, calendar: { id, name, userId }, type: { id, name, duration }, appointments: [{ id, status, startTime, endTime, recurringIndex, notes, clientName }] } }`,
|
|
1525
|
+
whenToUse: "Before cancelling part of a series, to find the id of the occurrence to cancel from.",
|
|
1526
|
+
pitfalls: [
|
|
1527
|
+
"A series of another organization, or on a calendar the person may not see, is a plain 404.",
|
|
1528
|
+
"Times are UTC. The series timezone says which clock the visits were set on."
|
|
1529
|
+
],
|
|
1530
|
+
dataSensitivity: "sensitive",
|
|
1531
|
+
risk: "observe"
|
|
1532
|
+
},
|
|
1533
|
+
{
|
|
1534
|
+
name: "scheduling_create_recurring_series",
|
|
1535
|
+
module: "scheduling",
|
|
1536
|
+
method: "POST",
|
|
1537
|
+
route: "/admin/recurring",
|
|
1538
|
+
auth: "session_cookie",
|
|
1539
|
+
description: "Book a client into a repeating series: the same time on a repeating day, for a number of visits, all confirmed at once.",
|
|
1540
|
+
params: [
|
|
1541
|
+
{ name: "calendarId", type: "string", required: true, description: "Calendar the visits go on" },
|
|
1542
|
+
{ name: "typeId", type: "string", required: true, description: "Appointment type; it sets how long each visit is. It must be active." },
|
|
1543
|
+
{ name: "frequency", type: "string", required: true, description: "How often the visits repeat", allowedValues: FREQUENCIES },
|
|
1544
|
+
{ name: "occurrences", type: "number", required: true, description: "How many visits to book, 1 to 104" },
|
|
1545
|
+
{ name: "startTimeLocal", type: "string", required: true, description: "Clock time of every visit as HH:MM on a 24-hour clock, read in the timezone parameter, for example 14:30" },
|
|
1546
|
+
{ name: "firstDate", type: "string", required: true, description: "Date of the first visit as YYYY-MM-DD, read in the timezone parameter" },
|
|
1547
|
+
{ name: "timezone", type: "string", required: false, description: "IANA zone name such as America/Chicago that startTimeLocal is read in; America/New_York if left out. Send the calendar's own zone." },
|
|
1548
|
+
{ name: "endsAt", type: "string", required: false, description: "Last date to book a visit on, as an ISO 8601 UTC date-time such as 2026-12-31T00:00:00Z. Only the date is compared: a visit on that UTC date is still booked, whatever its clock time, and none on a later date is. The series may end up with fewer visits than occurrences." },
|
|
1549
|
+
{ name: "clientEmail", type: "string", required: true, description: "Client email address" },
|
|
1550
|
+
{ name: "clientName", type: "string", required: true, description: "Client name, 1 to 200 characters" },
|
|
1551
|
+
{ name: "clientPhone", type: "string", required: false, description: "Client phone number, up to 30 characters" },
|
|
1552
|
+
{ name: "clientId", type: "string", required: false, description: "Id of the client record in the host system, when known. The host may ignore it and match by email." },
|
|
1553
|
+
{ name: "notes", type: "string", required: false, description: "Note copied onto every visit, up to 1000 characters" }
|
|
1554
|
+
],
|
|
1555
|
+
example: { calendarId: "cal_1", typeId: "type_1", frequency: "WEEKLY", occurrences: 6, startTimeLocal: "14:30", firstDate: "2026-12-01", timezone: "America/New_York", clientEmail: "sam@example.com", clientName: "Sam Rivera" },
|
|
1556
|
+
responseShape: `{ series: { ${SERIES_FIELDS} }, occurrences, warnings? }`,
|
|
1557
|
+
whenToUse: "When one client needs the same slot repeatedly, such as a weekly session or a fitting course. For a single visit use scheduling_book_appointment.",
|
|
1558
|
+
pitfalls: [
|
|
1559
|
+
"It does not check opening hours or free times: a visit is saved at the time asked for, even on a closed day or overlapping another booking. Only a visit that starts at exactly the same moment as a booking already on the calendar is refused, with 409, and then nothing is saved. Check the dates with scheduling_check_availability first.",
|
|
1560
|
+
"startTimeLocal and firstDate are read in the timezone you send, not in the calendar's own zone. An unknown zone name is refused with 422.",
|
|
1561
|
+
"A monthly series from the 31st uses the last day of shorter months and goes back to the 31st when the month has one.",
|
|
1562
|
+
"Every visit is confirmed straight away: the type's approval and payment settings do not apply to a series.",
|
|
1563
|
+
"The visits are saved together or not at all. warnings, when present, lists follow-up steps that failed after saving (reminders, calendar entries, the staff alert); the series is saved regardless.",
|
|
1564
|
+
"The calendar, or the type, not being found (or inactive) is refused with 404; so is a calendar the person may not see.",
|
|
1565
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1566
|
+
],
|
|
1567
|
+
dataSensitivity: "sensitive",
|
|
1568
|
+
risk: "act",
|
|
1569
|
+
requiresApproval: {
|
|
1570
|
+
action: "Create a recurring series",
|
|
1571
|
+
reason: "Many appointments are confirmed at once, with reminders scheduled for the client, and none is checked against opening hours or overlapping bookings.",
|
|
1572
|
+
prompt: "Book {occurrences} {frequency} visits for {clientName} from {firstDate}?"
|
|
1573
|
+
}
|
|
1574
|
+
},
|
|
1575
|
+
{
|
|
1576
|
+
name: "scheduling_cancel_recurring_series",
|
|
1577
|
+
module: "scheduling",
|
|
1578
|
+
method: "PATCH",
|
|
1579
|
+
route: "/admin/recurring/[id]",
|
|
1580
|
+
auth: "session_cookie",
|
|
1581
|
+
description: "Cancel one visit of a series, one visit and every later one, or the whole series. Visits already cancelled, completed or marked no-show are left alone.",
|
|
1582
|
+
params: [
|
|
1583
|
+
{ name: "id", type: "string", required: true, description: "Series id" },
|
|
1584
|
+
{ name: "scope", type: "string", required: true, description: "ONE cancels only the visit in fromAppointmentId; THIS_AND_FOLLOWING cancels that visit and every later one; ALL cancels every open visit", allowedValues: SCOPES },
|
|
1585
|
+
{ name: "fromAppointmentId", type: "string", required: false, description: "Id of the visit to start from. Required for ONE and THIS_AND_FOLLOWING, and it must belong to this series." }
|
|
1586
|
+
],
|
|
1587
|
+
example: { id: "series_1", scope: "THIS_AND_FOLLOWING", fromAppointmentId: "appt_3" },
|
|
1588
|
+
responseShape: "{ cancelledCount, newSeriesStatus, warnings? }",
|
|
1589
|
+
whenToUse: "When a client stops coming or a staff member is away for a while. To move one visit, use scheduling_reschedule_appointment; to cancel a single booking outside a series, use scheduling_cancel_appointment.",
|
|
1590
|
+
pitfalls: [
|
|
1591
|
+
"The series becomes ACTIVE after ONE, ENDED after THIS_AND_FOLLOWING and CANCELLED after ALL.",
|
|
1592
|
+
"Each cancelled visit gets follow-up steps: its reminders are dropped, its calendar entry is removed, a visit that was paid is flagged for a refund decision and staff are alerted once. warnings lists any step that failed; the visits are cancelled regardless. The client is not sent a cancellation message by this tool.",
|
|
1593
|
+
"If any open visit is on a calendar the person may not see, nothing is cancelled and the answer is a plain 404.",
|
|
1594
|
+
"This cannot be undone. A cancelled visit cannot be reopened; book a new one instead.",
|
|
1595
|
+
"Needs no scheduling switch, and is open to any signed-in staff member."
|
|
1596
|
+
],
|
|
1597
|
+
dataSensitivity: "sensitive",
|
|
1598
|
+
risk: "act",
|
|
1599
|
+
requiresApproval: {
|
|
1600
|
+
action: "Cancel a recurring series",
|
|
1601
|
+
reason: "Several client appointments are cancelled at once, which cannot be undone, and paid visits are flagged for refund.",
|
|
1602
|
+
prompt: "Cancel ({scope}) in series {id}?"
|
|
1603
|
+
}
|
|
1604
|
+
},
|
|
1605
|
+
{
|
|
1606
|
+
name: "scheduling_list_group_sessions",
|
|
1607
|
+
module: "scheduling",
|
|
1608
|
+
method: "GET",
|
|
1609
|
+
route: "/admin/group-sessions",
|
|
1610
|
+
auth: "session_cookie",
|
|
1611
|
+
description: "List the group sessions held in a date range, each with how many seats are taken and who is booked.",
|
|
1612
|
+
params: [
|
|
1613
|
+
{ name: "startDate", type: "string", required: true, description: "Start of the range as an ISO 8601 UTC date-time such as 2026-12-01T00:00:00Z; sessions from this moment on" },
|
|
1614
|
+
{ name: "endDate", type: "string", required: true, description: "End of the range as an ISO 8601 UTC date-time, later than startDate and at most 366 days after it; sessions before this moment" },
|
|
1615
|
+
{ name: "calendarId", type: "string", required: false, description: "Only sessions on this calendar" }
|
|
1616
|
+
],
|
|
1617
|
+
example: { startDate: "2026-12-01T00:00:00Z", endDate: "2026-12-08T00:00:00Z" },
|
|
1618
|
+
responseShape: "{ sessions: [{ typeId, typeName, typeColor, maxSeats, calendarId, calendarName, staffName, startTime, endTime, seatsBooked, seatsAvailable, isFull, attendees }], total, hasMore }",
|
|
1619
|
+
whenToUse: "To see how full a class is, or who is coming. A person books a seat with scheduling_book_appointment on a type that has isGroup true.",
|
|
1620
|
+
pitfalls: [
|
|
1621
|
+
"seatsBooked counts pending and confirmed bookings only; cancelled, completed and no-show attendees are listed but take no seat.",
|
|
1622
|
+
"maxSeats and seatsAvailable are null when the type has no seat limit, and isFull is then false.",
|
|
1623
|
+
"hasMore true means the range holds more than 1000 bookings and some sessions are missing. Ask for a shorter range.",
|
|
1624
|
+
"Both dates are required. A range longer than 366 days, or one that ends before it starts, is refused with 400.",
|
|
1625
|
+
"Attendees carry names, emails and phone numbers."
|
|
1626
|
+
],
|
|
1627
|
+
dataSensitivity: "sensitive",
|
|
1628
|
+
risk: "observe"
|
|
1629
|
+
}
|
|
1630
|
+
];
|
|
1631
|
+
|
|
1632
|
+
// src/agent/settings-tools.ts
|
|
1633
|
+
var CATEGORY_FIELDS = "id, organizationId, name, sortOrder, createdAt";
|
|
1634
|
+
var TEMPLATE_FIELDS = "id, organizationId, name, channel, trigger, recipientType, subject, body, isActive";
|
|
1635
|
+
var BRAND_FIELDS = "displayName, logoUrl, primaryColor, accentColor, backgroundColor, textColor, fontFamily, footerText, replyToEmail, fromName, fromEmail, updatedAt";
|
|
1636
|
+
var TRIGGERS = ["CONFIRMATION", "REMINDER_24H", "REMINDER_1H", "FOLLOWUP", "CANCELLATION", "RESCHEDULE"];
|
|
1637
|
+
var TEMPLATE_VARIABLES = "Write {{name}} where a value should go. Available: clientName, clientEmail, clientPhone, serviceName, dateTime, duration, calendarName, staffName, location, manageUrl, icalUrl, meetingUrl, time, appointmentStatus, intake_<id of an intake question>, and brandName, brandLogoUrl, brandColor, brandFooter when the server has branding. A value the appointment does not have (for example staffName with no staff name) is left in the message as the literal {{staffName}}.";
|
|
1638
|
+
var BODY_LIMITS = "An email body keeps only b, i, em, strong, a (href), br, p, ul, ol and li tags; an SMS body has every tag removed.";
|
|
1639
|
+
var SETTINGS_TOOLS = [
|
|
1640
|
+
{
|
|
1641
|
+
name: "scheduling_list_categories",
|
|
1642
|
+
module: "scheduling",
|
|
1643
|
+
method: "GET",
|
|
1644
|
+
route: "/admin/categories",
|
|
1645
|
+
auth: "session_cookie",
|
|
1646
|
+
description: "List the appointment categories, in the order they are shown.",
|
|
1647
|
+
params: [],
|
|
1648
|
+
example: {},
|
|
1649
|
+
responseShape: `[{ ${CATEGORY_FIELDS} }]`,
|
|
1650
|
+
whenToUse: "To find a category id, for example to file an appointment type under it.",
|
|
1651
|
+
pitfalls: ["The answer is a plain list with no paging, lowest sortOrder first.", "Needs the scheduling switch to be on for the organization."],
|
|
1652
|
+
dataSensitivity: "none",
|
|
1653
|
+
risk: "observe"
|
|
1654
|
+
},
|
|
1655
|
+
{
|
|
1656
|
+
name: "scheduling_create_category",
|
|
1657
|
+
module: "scheduling",
|
|
1658
|
+
method: "POST",
|
|
1659
|
+
route: "/admin/categories",
|
|
1660
|
+
auth: "session_cookie",
|
|
1661
|
+
description: "Create an appointment category for grouping appointment types on the booking page.",
|
|
1662
|
+
params: [{ name: "name", type: "string", required: true, description: "Category name, 1 to 50 characters" }],
|
|
1663
|
+
example: { name: "Fittings" },
|
|
1664
|
+
responseShape: `{ ${CATEGORY_FIELDS} }`,
|
|
1665
|
+
whenToUse: "When appointment types need a new group. File a type under it with categoryId in scheduling_update_appointment_type.",
|
|
1666
|
+
pitfalls: [
|
|
1667
|
+
"A new category starts at sortOrder 0. Set the order afterwards with scheduling_update_category.",
|
|
1668
|
+
"A category with the same name already existing is refused with 409. Names are unique across the whole database, so a name used by another organization is refused too.",
|
|
1669
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1670
|
+
],
|
|
1671
|
+
dataSensitivity: "none",
|
|
1672
|
+
risk: "act",
|
|
1673
|
+
requiresApproval: {
|
|
1674
|
+
action: "Create a category",
|
|
1675
|
+
reason: "A new category becomes visible to clients on the booking page once a type is filed under it.",
|
|
1676
|
+
prompt: 'Create the appointment category "{name}"?'
|
|
1677
|
+
}
|
|
1678
|
+
},
|
|
1679
|
+
{
|
|
1680
|
+
name: "scheduling_update_category",
|
|
1681
|
+
module: "scheduling",
|
|
1682
|
+
method: "PATCH",
|
|
1683
|
+
route: "/admin/categories",
|
|
1684
|
+
auth: "session_cookie",
|
|
1685
|
+
description: "Rename a category or change its position in the list.",
|
|
1686
|
+
params: [
|
|
1687
|
+
{ name: "id", type: "string", required: true, description: "Category id" },
|
|
1688
|
+
{ name: "name", type: "string", required: false, description: "New name, 1 to 50 characters" },
|
|
1689
|
+
{ name: "sortOrder", type: "number", required: false, description: "Position in lists as a whole number of 0 or more, lowest first" }
|
|
1690
|
+
],
|
|
1691
|
+
example: { id: "cat_1", name: "Suit fittings", sortOrder: 2 },
|
|
1692
|
+
responseShape: `{ ${CATEGORY_FIELDS} }`,
|
|
1693
|
+
whenToUse: "To rename a category or reorder the list. Send name, sortOrder or both.",
|
|
1694
|
+
pitfalls: [
|
|
1695
|
+
"Sending neither name nor sortOrder is refused with 400.",
|
|
1696
|
+
"Another category already having that name is refused with 409. A category of another organization is a plain 404.",
|
|
1697
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1698
|
+
],
|
|
1699
|
+
dataSensitivity: "none",
|
|
1700
|
+
risk: "act",
|
|
1701
|
+
requiresApproval: {
|
|
1702
|
+
action: "Change a category",
|
|
1703
|
+
reason: "The name and order are what clients see on the booking page.",
|
|
1704
|
+
prompt: "Change category {id}?"
|
|
1705
|
+
}
|
|
1706
|
+
},
|
|
1707
|
+
{
|
|
1708
|
+
name: "scheduling_delete_category",
|
|
1709
|
+
module: "scheduling",
|
|
1710
|
+
method: "DELETE",
|
|
1711
|
+
route: "/admin/categories",
|
|
1712
|
+
auth: "session_cookie",
|
|
1713
|
+
description: "Delete a category that no appointment type uses.",
|
|
1714
|
+
params: [{ name: "id", type: "string", required: true, description: "Category id" }],
|
|
1715
|
+
example: { id: "cat_1" },
|
|
1716
|
+
responseShape: "{ success: true }",
|
|
1717
|
+
whenToUse: "To remove a category that is no longer wanted, after moving its types elsewhere.",
|
|
1718
|
+
pitfalls: [
|
|
1719
|
+
"Refused with 409 while any appointment type uses it. Move or clear those types first with categoryId in scheduling_update_appointment_type.",
|
|
1720
|
+
"A deleted category cannot be brought back.",
|
|
1721
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1722
|
+
],
|
|
1723
|
+
dataSensitivity: "none",
|
|
1724
|
+
risk: "act",
|
|
1725
|
+
requiresApproval: {
|
|
1726
|
+
action: "Delete a category",
|
|
1727
|
+
reason: "The category is removed for good.",
|
|
1728
|
+
prompt: "Delete category {id}? This cannot be undone."
|
|
1729
|
+
}
|
|
1730
|
+
},
|
|
1731
|
+
{
|
|
1732
|
+
name: "scheduling_list_message_templates",
|
|
1733
|
+
module: "scheduling",
|
|
1734
|
+
method: "GET",
|
|
1735
|
+
route: "/admin/templates",
|
|
1736
|
+
auth: "session_cookie",
|
|
1737
|
+
description: "List the message templates: the email and text messages sent to clients and staff when a booking is confirmed, reminded, followed up, cancelled or moved.",
|
|
1738
|
+
params: [],
|
|
1739
|
+
example: {},
|
|
1740
|
+
responseShape: `[{ ${TEMPLATE_FIELDS} }]`,
|
|
1741
|
+
whenToUse: "To see what messages are set up and which are switched on, and to find a template id.",
|
|
1742
|
+
pitfalls: [
|
|
1743
|
+
"The answer is a plain list with no paging, ordered by channel, then trigger, then name.",
|
|
1744
|
+
"An organization with no templates sends no messages at all.",
|
|
1745
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1746
|
+
],
|
|
1747
|
+
dataSensitivity: "internal",
|
|
1748
|
+
risk: "observe"
|
|
1749
|
+
},
|
|
1750
|
+
{
|
|
1751
|
+
name: "scheduling_create_message_template",
|
|
1752
|
+
module: "scheduling",
|
|
1753
|
+
method: "POST",
|
|
1754
|
+
route: "/admin/templates",
|
|
1755
|
+
auth: "session_cookie",
|
|
1756
|
+
description: "Create the message sent for one trigger on one channel to one kind of recipient.",
|
|
1757
|
+
params: [
|
|
1758
|
+
{ name: "name", type: "string", required: true, description: "Name for staff to recognise it by, 1 to 100 characters" },
|
|
1759
|
+
{ name: "channel", type: "string", required: true, description: "How it is sent", allowedValues: ["EMAIL", "SMS"] },
|
|
1760
|
+
{ name: "trigger", type: "string", required: true, description: "When it is sent: CONFIRMATION when booked, REMINDER_24H and REMINDER_1H before the visit (the actual lead times are set on each appointment type), FOLLOWUP after it, CANCELLATION and RESCHEDULE when it is cancelled or moved", allowedValues: TRIGGERS },
|
|
1761
|
+
{ name: "recipientType", type: "string", required: false, description: "Who receives it: CLIENT (the booking's client) or STAFF; CLIENT if left out. A STAFF template is sent at once to the calendar's staff email address, only for the CONFIRMATION, CANCELLATION and RESCHEDULE triggers, and only when the calendar has a staff email. Use the EMAIL channel for it: a STAFF template on the SMS channel is queued as a text addressed to an email address and is not delivered as an email. A STAFF template for any other trigger is saved but never sent.", allowedValues: ["CLIENT", "STAFF"] },
|
|
1762
|
+
{ name: "subject", type: "string", required: false, description: "Email subject, up to 200 characters. Required for EMAIL (not blank), refused for SMS. HTML tags are removed. You may use the {{name}} values listed in the body description." },
|
|
1763
|
+
{ name: "body", type: "string", required: true, description: `Message text, 1 to 5000 characters. ${BODY_LIMITS} ${TEMPLATE_VARIABLES}` },
|
|
1764
|
+
{ name: "isActive", type: "boolean", required: false, description: "Whether it is sent; true if left out" }
|
|
1765
|
+
],
|
|
1766
|
+
example: { name: "Day-before reminder", channel: "EMAIL", trigger: "REMINDER_24H", subject: "See you tomorrow, {{clientName}}", body: "<p>Hello {{clientName}}, this is a reminder of your {{serviceName}} on {{dateTime}}.</p>" },
|
|
1767
|
+
responseShape: `{ ${TEMPLATE_FIELDS} }`,
|
|
1768
|
+
whenToUse: "When a kind of message is missing. There is one template for each combination of channel, trigger and recipientType.",
|
|
1769
|
+
pitfalls: [
|
|
1770
|
+
"A template for the same channel, trigger and recipientType already existing is refused with 409. Change the existing one with scheduling_update_message_template.",
|
|
1771
|
+
"An EMAIL template needs a subject and an SMS template must not have one: both refused with 400.",
|
|
1772
|
+
"A CLIENT SMS goes only to bookings that have a client phone number. A STAFF template is sent only for CONFIRMATION, CANCELLATION and RESCHEDULE, at once, to the calendar's staff email, and only on the EMAIL channel; there are no staff reminders or follow-ups.",
|
|
1773
|
+
"A reminder whose time has already passed when the booking is made is skipped, and a lead time of 0 on the appointment type switches that reminder or follow-up off. Bookings waiting for approval get no reminders or follow-ups until they are approved.",
|
|
1774
|
+
"Reminders and follow-ups are scheduled when a booking is made, so a new template does not reach bookings that already exist.",
|
|
1775
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1776
|
+
],
|
|
1777
|
+
dataSensitivity: "internal",
|
|
1778
|
+
risk: "act",
|
|
1779
|
+
requiresApproval: {
|
|
1780
|
+
action: "Create a message template",
|
|
1781
|
+
reason: "From then on, real clients or staff receive this message automatically for every matching booking.",
|
|
1782
|
+
prompt: 'Create the {channel} message "{name}" for {trigger}?'
|
|
1783
|
+
}
|
|
1784
|
+
},
|
|
1785
|
+
{
|
|
1786
|
+
name: "scheduling_update_message_template",
|
|
1787
|
+
module: "scheduling",
|
|
1788
|
+
method: "PUT",
|
|
1789
|
+
route: "/admin/templates/[id]",
|
|
1790
|
+
auth: "session_cookie",
|
|
1791
|
+
description: "Change the name, subject, text or on/off switch of a message template. Only the fields you send change.",
|
|
1792
|
+
params: [
|
|
1793
|
+
{ name: "id", type: "string", required: true, description: "Template id" },
|
|
1794
|
+
{ name: "name", type: "string", required: false, description: "Name for staff, 1 to 100 characters" },
|
|
1795
|
+
{ name: "subject", type: "string", required: false, description: "Email subject, up to 200 characters. An EMAIL template cannot be left without one; an SMS template must have none (send null to clear it)." },
|
|
1796
|
+
{ name: "body", type: "string", required: false, description: `Message text, 1 to 5000 characters. ${BODY_LIMITS} ${TEMPLATE_VARIABLES}` },
|
|
1797
|
+
{ name: "isActive", type: "boolean", required: false, description: "true sends the message; false stops it for bookings and events from then on without deleting the template. Reminders and follow-ups already queued for existing bookings are still sent." }
|
|
1798
|
+
],
|
|
1799
|
+
example: { id: "tpl_1", body: "<p>Hello {{clientName}}, see you on {{dateTime}}.</p>", isActive: true },
|
|
1800
|
+
responseShape: `{ ${TEMPLATE_FIELDS} }`,
|
|
1801
|
+
whenToUse: "To reword a message or pause it for future bookings. To pause temporarily, set isActive false rather than deleting.",
|
|
1802
|
+
pitfalls: [
|
|
1803
|
+
"Channel, trigger and recipientType cannot be changed: sending any of them is refused with 400. Create a new template instead.",
|
|
1804
|
+
"Reminders and follow-ups already scheduled for existing bookings keep their text and are still sent, whether the template is changed, paused or deleted afterwards; only cancelling the appointment drops them. Cancellation, reschedule and staff messages are written from the current template at the moment they are sent, and a booking that is later moved or approved gets its reminders made from the current template.",
|
|
1805
|
+
"A template of another organization is a plain 404.",
|
|
1806
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1807
|
+
],
|
|
1808
|
+
dataSensitivity: "internal",
|
|
1809
|
+
risk: "act",
|
|
1810
|
+
requiresApproval: {
|
|
1811
|
+
action: "Change a message template",
|
|
1812
|
+
reason: "Clients or staff receive the changed wording, or stop receiving the message, for future bookings and for cancellation, reschedule and staff messages sent from then on; reminders already queued are not affected.",
|
|
1813
|
+
prompt: "Change message template {id}?"
|
|
1814
|
+
}
|
|
1815
|
+
},
|
|
1816
|
+
{
|
|
1817
|
+
name: "scheduling_delete_message_template",
|
|
1818
|
+
module: "scheduling",
|
|
1819
|
+
method: "DELETE",
|
|
1820
|
+
route: "/admin/templates/[id]",
|
|
1821
|
+
auth: "session_cookie",
|
|
1822
|
+
description: "Delete a message template for good.",
|
|
1823
|
+
params: [{ name: "id", type: "string", required: true, description: "Template id" }],
|
|
1824
|
+
example: { id: "tpl_1" },
|
|
1825
|
+
responseShape: "{ success: true }",
|
|
1826
|
+
whenToUse: "Only to remove a template that is no longer wanted. To pause one, use scheduling_update_message_template with isActive false.",
|
|
1827
|
+
pitfalls: [
|
|
1828
|
+
"With the template gone, that kind of message is no longer made for new bookings or events. Reminders and follow-ups already queued for existing bookings are still sent.",
|
|
1829
|
+
"A deleted template cannot be brought back.",
|
|
1830
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1831
|
+
],
|
|
1832
|
+
dataSensitivity: "internal",
|
|
1833
|
+
risk: "act",
|
|
1834
|
+
requiresApproval: {
|
|
1835
|
+
action: "Delete a message template",
|
|
1836
|
+
reason: "The template is removed for good and that kind of message is no longer made for new bookings or events.",
|
|
1837
|
+
prompt: "Delete message template {id}? This cannot be undone."
|
|
1838
|
+
}
|
|
1839
|
+
},
|
|
1840
|
+
{
|
|
1841
|
+
name: "scheduling_get_brand",
|
|
1842
|
+
module: "scheduling",
|
|
1843
|
+
method: "GET",
|
|
1844
|
+
route: "/admin/brand",
|
|
1845
|
+
auth: "session_cookie",
|
|
1846
|
+
description: "Read the organization's brand: its name, logo, colours, font, footer text and the sending identity of its emails.",
|
|
1847
|
+
params: [],
|
|
1848
|
+
example: {},
|
|
1849
|
+
responseShape: `{ brand: { ${BRAND_FIELDS} } }`,
|
|
1850
|
+
whenToUse: "Before changing the brand, to see what is set now.",
|
|
1851
|
+
pitfalls: [
|
|
1852
|
+
"brand is null when none has been saved.",
|
|
1853
|
+
"Unlike the public booking page, this answer includes the reply-to and from addresses.",
|
|
1854
|
+
"A server without branding answers 501.",
|
|
1855
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1856
|
+
],
|
|
1857
|
+
dataSensitivity: "internal",
|
|
1858
|
+
risk: "observe"
|
|
1859
|
+
},
|
|
1860
|
+
{
|
|
1861
|
+
name: "scheduling_save_brand",
|
|
1862
|
+
module: "scheduling",
|
|
1863
|
+
method: "PUT",
|
|
1864
|
+
route: "/admin/brand",
|
|
1865
|
+
auth: "session_cookie",
|
|
1866
|
+
description: "Save the organization's brand. This replaces the whole brand: a field you leave out is cleared, not kept.",
|
|
1867
|
+
params: [
|
|
1868
|
+
{ name: "displayName", type: "string", required: true, description: "Business name shown to clients, 1 to 100 characters" },
|
|
1869
|
+
{ name: "logoUrl", type: "string", required: false, description: "Logo address: https only, no user name or password, up to 500 characters" },
|
|
1870
|
+
{ name: "primaryColor", type: "string", required: false, description: "Main colour as hex such as #1a2b3c" },
|
|
1871
|
+
{ name: "accentColor", type: "string", required: false, description: "Accent colour as hex such as #1a2b3c" },
|
|
1872
|
+
{ name: "backgroundColor", type: "string", required: false, description: "Background colour as hex such as #ffffff" },
|
|
1873
|
+
{ name: "textColor", type: "string", required: false, description: "Text colour as hex such as #111111" },
|
|
1874
|
+
{ name: "fontFamily", type: "string", required: false, description: "Font name, up to 100 characters of letters, digits, spaces, commas and dashes" },
|
|
1875
|
+
{ name: "footerText", type: "string", required: false, description: "Footer text, up to 300 characters. It appears in a message only where a template contains {{brandFooter}}, and it is returned to the booking page." },
|
|
1876
|
+
{ name: "replyToEmail", type: "string", required: false, description: "Address that client replies go to: one plain email address, up to 254 characters" },
|
|
1877
|
+
{ name: "fromName", type: "string", required: false, description: "Sender name on emails, up to 100 characters, without quotes, angle brackets, commas, semicolons, @ or backslashes" },
|
|
1878
|
+
{ name: "fromEmail", type: "string", required: false, description: "Address emails are sent from. Its domain must be one the server has confirmed; otherwise the whole save is refused." }
|
|
1879
|
+
],
|
|
1880
|
+
example: { displayName: "Rivera Fittings", primaryColor: "#1a2b3c", accentColor: "#c9a227", footerText: "Thank you for booking with us." },
|
|
1881
|
+
responseShape: `{ brand: { ${BRAND_FIELDS} } }`,
|
|
1882
|
+
whenToUse: "To set or change how the business looks to clients. Read the brand first and send back every field that should stay.",
|
|
1883
|
+
pitfalls: [
|
|
1884
|
+
"It replaces everything. A field left out becomes empty, so a change to one colour must resend all the others.",
|
|
1885
|
+
"A save that breaks a rule is refused with 400 and every problem is listed at once in details, each with its path and reason; nothing is saved. A body of the wrong shape (a text over its size limit, a field that does not exist) is refused earlier with 400 and details that name the field.",
|
|
1886
|
+
"Colours are stored in lower case. Email addresses are stored in lower case.",
|
|
1887
|
+
"fromEmail is accepted only for a domain the server has confirmed it may send from; a check that fails counts as not confirmed.",
|
|
1888
|
+
"A server without branding answers 501.",
|
|
1889
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1890
|
+
],
|
|
1891
|
+
dataSensitivity: "internal",
|
|
1892
|
+
risk: "act",
|
|
1893
|
+
requiresApproval: {
|
|
1894
|
+
action: "Save the brand",
|
|
1895
|
+
reason: "Clients see the new name and colours on the booking page straight away, the sender name, from address and reply-to apply to the emails sent from then on, and a new sending address changes who emails appear to come from.",
|
|
1896
|
+
prompt: 'Save the brand "{displayName}"? This replaces the current brand.'
|
|
1897
|
+
}
|
|
1898
|
+
},
|
|
1899
|
+
{
|
|
1900
|
+
name: "scheduling_remove_brand",
|
|
1901
|
+
module: "scheduling",
|
|
1902
|
+
method: "DELETE",
|
|
1903
|
+
route: "/admin/brand",
|
|
1904
|
+
auth: "session_cookie",
|
|
1905
|
+
description: "Remove the organization's brand, so clients see the server's default look and name.",
|
|
1906
|
+
params: [],
|
|
1907
|
+
example: {},
|
|
1908
|
+
responseShape: "{ removed }",
|
|
1909
|
+
whenToUse: "Only to go back to no custom brand. To change it, use scheduling_save_brand.",
|
|
1910
|
+
pitfalls: [
|
|
1911
|
+
"removed is false when there was no brand to remove; that is not an error.",
|
|
1912
|
+
"A removed brand cannot be brought back; save it again.",
|
|
1913
|
+
"A server without branding answers 501.",
|
|
1914
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1915
|
+
],
|
|
1916
|
+
dataSensitivity: "internal",
|
|
1917
|
+
risk: "act",
|
|
1918
|
+
requiresApproval: {
|
|
1919
|
+
action: "Remove the brand",
|
|
1920
|
+
reason: "Clients lose the custom name, colours and sender at once.",
|
|
1921
|
+
prompt: "Remove the brand? Clients will see the default look."
|
|
1922
|
+
}
|
|
1923
|
+
}
|
|
1924
|
+
];
|
|
1925
|
+
|
|
1926
|
+
// src/agent/type-tools.ts
|
|
1927
|
+
var ID3 = { name: "id", type: "string", required: true, description: "Appointment type id" };
|
|
1928
|
+
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";
|
|
1929
|
+
var LOCATION_TYPES = ["IN_PERSON", "TRAVEL_TO_CLIENT", "VIRTUAL", "PHONE"];
|
|
1930
|
+
var STRATEGIES = ["NONE", "ROUND_ROBIN", "LOAD_BALANCED"];
|
|
1931
|
+
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).";
|
|
1932
|
+
function typeFields(forUpdate) {
|
|
1933
|
+
const when = (create, update) => forUpdate ? update : create;
|
|
1934
|
+
return [
|
|
1935
|
+
{ 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.") },
|
|
1936
|
+
{ 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.") },
|
|
1937
|
+
{ 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") },
|
|
1938
|
+
{ 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 },
|
|
1939
|
+
{ name: "duration", type: "number", required: !forUpdate, description: "Length in whole minutes, 5 to 480" },
|
|
1940
|
+
{ name: "color", type: "string", required: false, description: when("Calendar colour as #RRGGBB hex; #3B82F6 if left out", "Calendar colour as #RRGGBB hex") },
|
|
1941
|
+
{ 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") },
|
|
1942
|
+
{ 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") },
|
|
1943
|
+
{ 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") },
|
|
1944
|
+
{ name: "requiresPayment", type: "boolean", required: false, description: when("Whether booking needs a payment; false if left out", "Whether booking needs a payment") },
|
|
1945
|
+
{ 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") },
|
|
1946
|
+
{ 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") },
|
|
1947
|
+
{ 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") },
|
|
1948
|
+
{ 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") },
|
|
1949
|
+
{ 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") },
|
|
1950
|
+
{ 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") },
|
|
1951
|
+
{ 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") },
|
|
1952
|
+
{ name: "isGroup", type: "boolean", required: false, description: when("Whether several clients share one session; false if left out", "Whether several clients share one session") },
|
|
1953
|
+
{ 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") },
|
|
1954
|
+
{ name: "intakeForm", type: "json-array", required: false, description: when(INTAKE_FORM, `${INTAKE_FORM} Replaces the whole list; null removes the questions.`) },
|
|
1955
|
+
{ 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") },
|
|
1956
|
+
{ 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 },
|
|
1957
|
+
{ 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") }
|
|
1958
|
+
];
|
|
1959
|
+
}
|
|
1960
|
+
var TYPE_TOOLS = [
|
|
1961
|
+
{
|
|
1962
|
+
name: "scheduling_list_all_appointment_types",
|
|
1963
|
+
module: "scheduling",
|
|
1964
|
+
method: "GET",
|
|
1965
|
+
route: "/admin/types",
|
|
1966
|
+
auth: "session_cookie",
|
|
1967
|
+
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.",
|
|
1968
|
+
params: [],
|
|
1969
|
+
example: {},
|
|
1970
|
+
responseShape: `[{ ${TYPE_FIELDS}, calendars: [{ calendar: { id, name } }], categoryRef, roundRobinState }]`,
|
|
1971
|
+
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.",
|
|
1972
|
+
pitfalls: ["The answer is a plain list with no paging.", "Needs the scheduling switch to be on for the organization."],
|
|
1973
|
+
dataSensitivity: "internal",
|
|
1974
|
+
risk: "observe"
|
|
1975
|
+
},
|
|
1976
|
+
{
|
|
1977
|
+
name: "scheduling_create_appointment_type",
|
|
1978
|
+
module: "scheduling",
|
|
1979
|
+
method: "POST",
|
|
1980
|
+
route: "/admin/types",
|
|
1981
|
+
auth: "session_cookie",
|
|
1982
|
+
description: "Create an appointment type. Its web address name (slug) is made from the name, and it starts active.",
|
|
1983
|
+
params: [...typeFields(false)],
|
|
1984
|
+
example: { name: "Consultation", duration: 45, price: 60, deposit: 20, requiresPayment: true, calendarIds: ["cal_1"] },
|
|
1985
|
+
responseShape: `{ ${TYPE_FIELDS}, directoryClaimed }`,
|
|
1986
|
+
whenToUse: "When something new needs to be bookable. Put it on a calendar with calendarIds, and make sure that calendar has opening hours.",
|
|
1987
|
+
pitfalls: [
|
|
1988
|
+
"A type with the same name, or a name that gives the same web address, already exists: refused with 409.",
|
|
1989
|
+
"isGroup true needs maxSeats of at least 2.",
|
|
1990
|
+
"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.",
|
|
1991
|
+
"The first and second reminder must not be the same number of minutes (unless one is 0).",
|
|
1992
|
+
"directoryClaimed false means the short booking address could not be registered; only the organization-qualified address works then.",
|
|
1993
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1994
|
+
],
|
|
1995
|
+
dataSensitivity: "internal",
|
|
1996
|
+
risk: "act",
|
|
1997
|
+
requiresApproval: {
|
|
1998
|
+
action: "Create an appointment type",
|
|
1999
|
+
reason: "A new type becomes something clients can book, with its own price and booking address.",
|
|
2000
|
+
prompt: 'Create the appointment type "{name}"?'
|
|
2001
|
+
}
|
|
2002
|
+
},
|
|
2003
|
+
{
|
|
2004
|
+
name: "scheduling_update_appointment_type",
|
|
2005
|
+
module: "scheduling",
|
|
2006
|
+
method: "PUT",
|
|
2007
|
+
route: "/admin/types/[id]",
|
|
2008
|
+
auth: "session_cookie",
|
|
2009
|
+
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.",
|
|
2010
|
+
params: [
|
|
2011
|
+
ID3,
|
|
2012
|
+
...typeFields(true),
|
|
2013
|
+
{ name: "isActive", type: "boolean", required: false, description: "false switches the type off so it can no longer be booked, true switches it back on" }
|
|
2014
|
+
],
|
|
2015
|
+
example: { id: "type_1", duration: 60, price: 80 },
|
|
2016
|
+
responseShape: `{ ${TYPE_FIELDS} }`,
|
|
2017
|
+
whenToUse: "To change length, price, reminders or intake questions, move a type to other calendars, or switch it off or on.",
|
|
2018
|
+
pitfalls: [
|
|
2019
|
+
"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.",
|
|
2020
|
+
"Bookings that already exist keep their time; a changed length applies to new bookings.",
|
|
2021
|
+
"calendarIds and intakeForm replace the whole list, so read the type first and send back what should stay.",
|
|
2022
|
+
"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.",
|
|
2023
|
+
"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.",
|
|
2024
|
+
"Neither the update nor the delete needs the scheduling switch to be on."
|
|
2025
|
+
],
|
|
2026
|
+
dataSensitivity: "internal",
|
|
2027
|
+
risk: "act",
|
|
2028
|
+
requiresApproval: {
|
|
2029
|
+
action: "Change an appointment type",
|
|
2030
|
+
reason: "Changes can alter what clients pay, how long they are booked for, and whether the type can be booked at all.",
|
|
2031
|
+
prompt: "Change appointment type {id}?"
|
|
2032
|
+
}
|
|
2033
|
+
},
|
|
2034
|
+
{
|
|
2035
|
+
name: "scheduling_delete_appointment_type",
|
|
2036
|
+
module: "scheduling",
|
|
2037
|
+
method: "DELETE",
|
|
2038
|
+
route: "/admin/types/[id]",
|
|
935
2039
|
auth: "session_cookie",
|
|
936
2040
|
description: "Delete an appointment type that no appointment has ever used, and release its short booking address.",
|
|
937
2041
|
params: [ID3],
|
|
@@ -975,15 +2079,225 @@ var TYPE_TOOLS = [
|
|
|
975
2079
|
}
|
|
976
2080
|
];
|
|
977
2081
|
|
|
2082
|
+
// src/agent/waitlist-tools.ts
|
|
2083
|
+
var ENTRY_FIELDS = "id, typeId, calendarId, day, slotStart, clientName, clientEmail, clientPhone, status, offerSlotStart, offerExpiresAt, createdAt";
|
|
2084
|
+
var NOT_ENABLED3 = "A server without the waitlist answers 501.";
|
|
2085
|
+
var WAITLIST_TOOLS = [
|
|
2086
|
+
{
|
|
2087
|
+
name: "scheduling_list_waitlist",
|
|
2088
|
+
module: "scheduling",
|
|
2089
|
+
method: "GET",
|
|
2090
|
+
route: "/admin/waitlist",
|
|
2091
|
+
auth: "session_cookie",
|
|
2092
|
+
description: "List the people on the waitlist, oldest first, with the day they want, and any slot they have been offered.",
|
|
2093
|
+
params: [
|
|
2094
|
+
{ name: "status", type: "string", required: false, description: "Only entries in this state: WAITING (waiting for a slot), OFFERED (holding an offer that has not expired), ACCEPTING (taking the offer right now), BOOKED (took an offer), or EXPIRED (did not take it in time)", allowedValues: ["WAITING", "OFFERED", "ACCEPTING", "BOOKED", "EXPIRED"] },
|
|
2095
|
+
{ name: "limit", type: "number", required: false, description: "How many entries to return (default 50, at most 200)" },
|
|
2096
|
+
{ name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
|
|
2097
|
+
],
|
|
2098
|
+
example: { status: "WAITING" },
|
|
2099
|
+
responseShape: `{ entries: [{ ${ENTRY_FIELDS} }], total, hasMore }`,
|
|
2100
|
+
whenToUse: "To see who is waiting for which day, who holds an offer, and to find an entry id.",
|
|
2101
|
+
pitfalls: [
|
|
2102
|
+
"slotStart is the time the person asked for; null means any time that day. calendarId null means any calendar that offers the type. day is YYYY-MM-DD in the calendar's time zone.",
|
|
2103
|
+
"offerSlotStart and offerExpiresAt are set only while the entry holds an offer.",
|
|
2104
|
+
"The client's private link token is never part of the answer.",
|
|
2105
|
+
"The answer carries names, email addresses and phone numbers.",
|
|
2106
|
+
"Any other status value is refused with 400.",
|
|
2107
|
+
NOT_ENABLED3,
|
|
2108
|
+
"Needs the scheduling switch to be on for the organization."
|
|
2109
|
+
],
|
|
2110
|
+
dataSensitivity: "sensitive",
|
|
2111
|
+
risk: "observe"
|
|
2112
|
+
},
|
|
2113
|
+
{
|
|
2114
|
+
name: "scheduling_remove_waitlist_entry",
|
|
2115
|
+
module: "scheduling",
|
|
2116
|
+
method: "DELETE",
|
|
2117
|
+
route: "/admin/waitlist/[id]",
|
|
2118
|
+
auth: "session_cookie",
|
|
2119
|
+
description: "Take one person off the waitlist. If they were holding an offer, the slot goes to the next person who fits.",
|
|
2120
|
+
params: [{ name: "id", type: "string", required: true, description: "Waitlist entry id" }],
|
|
2121
|
+
example: { id: "wait_1" },
|
|
2122
|
+
responseShape: "{ success: true }",
|
|
2123
|
+
whenToUse: "When someone asked to be taken off, or an entry should be cleared away (including old BOOKED and EXPIRED ones).",
|
|
2124
|
+
pitfalls: [
|
|
2125
|
+
"Works on an entry that is WAITING, OFFERED, EXPIRED or BOOKED. One that is ACCEPTING (taking the offer at this moment) is refused with 404; try again in a moment.",
|
|
2126
|
+
"Removing someone who holds an offer frees that slot, and it is offered to the next person who fits, who is told by the host's own notice.",
|
|
2127
|
+
"The person removed is not sent a message by this tool, and a removed entry cannot be brought back; the client has to join again.",
|
|
2128
|
+
"An entry of another organization is a plain 404.",
|
|
2129
|
+
NOT_ENABLED3,
|
|
2130
|
+
"Needs the scheduling switch to be on for the organization."
|
|
2131
|
+
],
|
|
2132
|
+
dataSensitivity: "sensitive",
|
|
2133
|
+
risk: "act",
|
|
2134
|
+
requiresApproval: {
|
|
2135
|
+
action: "Remove someone from the waitlist",
|
|
2136
|
+
reason: "The person loses their place, and any offer they hold passes to the next person.",
|
|
2137
|
+
prompt: "Remove waitlist entry {id}?"
|
|
2138
|
+
}
|
|
2139
|
+
}
|
|
2140
|
+
];
|
|
2141
|
+
|
|
2142
|
+
// src/agent/webhook-tools.ts
|
|
2143
|
+
var ENDPOINT_FIELDS = "id, url, description, eventTypes, isActive, createdAt";
|
|
2144
|
+
var DELIVERY_FIELDS = "id, endpointId, eventId, eventType, status, attempts, nextAttemptAt, lastStatusCode, lastError, deliveredAt, createdAt, attemptLog: [{ attemptNumber, statusCode, error, durationMs, createdAt }]";
|
|
2145
|
+
var ENDPOINT_ID = { name: "id", type: "string", required: true, description: "Webhook endpoint id" };
|
|
2146
|
+
var NOT_ENABLED4 = "A server without webhooks answers 501.";
|
|
2147
|
+
var WEBHOOK_TOOLS = [
|
|
2148
|
+
{
|
|
2149
|
+
name: "scheduling_list_webhooks",
|
|
2150
|
+
module: "scheduling",
|
|
2151
|
+
method: "GET",
|
|
2152
|
+
route: "/admin/webhooks",
|
|
2153
|
+
auth: "session_cookie",
|
|
2154
|
+
description: "List the webhook endpoints of the organization, with the events each one receives, and the names of all the events that exist.",
|
|
2155
|
+
params: [],
|
|
2156
|
+
example: {},
|
|
2157
|
+
responseShape: `{ endpoints: [{ ${ENDPOINT_FIELDS} }], eventTypes }`,
|
|
2158
|
+
whenToUse: "To see what outside systems are told about bookings, to find an endpoint id, or to learn the event names.",
|
|
2159
|
+
pitfalls: ["The signing secret is never part of this answer; it was shown once when the endpoint was added.", "The answer is a plain list with no paging, newest first.", NOT_ENABLED4, "Needs the scheduling switch to be on for the organization."],
|
|
2160
|
+
dataSensitivity: "internal",
|
|
2161
|
+
risk: "observe"
|
|
2162
|
+
},
|
|
2163
|
+
{
|
|
2164
|
+
name: "scheduling_create_webhook",
|
|
2165
|
+
module: "scheduling",
|
|
2166
|
+
method: "POST",
|
|
2167
|
+
route: "/admin/webhooks",
|
|
2168
|
+
auth: "session_cookie",
|
|
2169
|
+
description: "Add a web address that will be sent a signed message each time one of the chosen events happens.",
|
|
2170
|
+
params: [
|
|
2171
|
+
{ name: "url", type: "string", required: true, description: "Where to send the events: an https address with a public domain name, no user name or password, up to 2000 characters. A server set up for local development may also accept http and local addresses; a production server refuses them." },
|
|
2172
|
+
{ name: "eventTypes", type: "string[]", required: true, description: "The events to send: appointment.booked, appointment.rescheduled, appointment.cancelled, appointment.no_show, reminder.sent, waitlist.offered. Or the single entry * for every event." },
|
|
2173
|
+
{ name: "description", type: "string", required: false, description: "A note for staff about what it is for, up to 200 characters" }
|
|
2174
|
+
],
|
|
2175
|
+
example: { url: "https://hooks.example.com/scheduling", eventTypes: ["appointment.booked", "appointment.cancelled"], description: "Send bookings to the CRM" },
|
|
2176
|
+
responseShape: `{ endpoint: { ${ENDPOINT_FIELDS} }, secret }`,
|
|
2177
|
+
whenToUse: "When an outside system must hear about bookings. Then use scheduling_send_test_webhook to check it receives them.",
|
|
2178
|
+
pitfalls: [
|
|
2179
|
+
"The answer carries the signing secret, and it is shown only this once; it is never returned again. Give it to the person who is setting up the receiver and do not repeat it anywhere else.",
|
|
2180
|
+
"An address that is not https, points at a private or local network, has no domain, or contains a user name or password is refused with 400. An organization can have at most 20 endpoints; the 21st is refused with 400. A list that names an unknown event, or mixes * with other events, is refused with 400; an event named twice is counted once.",
|
|
2181
|
+
"Events are sent from the server and a receiver that keeps failing is retried, then its deliveries are parked as DEAD_LETTER (see scheduling_list_webhook_deliveries).",
|
|
2182
|
+
NOT_ENABLED4,
|
|
2183
|
+
"Needs the scheduling switch to be on for the organization."
|
|
2184
|
+
],
|
|
2185
|
+
dataSensitivity: "critical",
|
|
2186
|
+
risk: "govern",
|
|
2187
|
+
requiresApproval: {
|
|
2188
|
+
action: "Add a webhook",
|
|
2189
|
+
reason: "From then on, booking details (client names and emails among them) are sent to that outside address.",
|
|
2190
|
+
prompt: "Send booking events to {url}?"
|
|
2191
|
+
}
|
|
2192
|
+
},
|
|
2193
|
+
{
|
|
2194
|
+
name: "scheduling_delete_webhook",
|
|
2195
|
+
module: "scheduling",
|
|
2196
|
+
method: "DELETE",
|
|
2197
|
+
route: "/admin/webhooks/[id]",
|
|
2198
|
+
auth: "session_cookie",
|
|
2199
|
+
description: "Remove a webhook endpoint together with its delivery log.",
|
|
2200
|
+
params: [ENDPOINT_ID],
|
|
2201
|
+
example: { id: "hook_1" },
|
|
2202
|
+
responseShape: "{ success: true }",
|
|
2203
|
+
whenToUse: "When an outside system should stop being told about bookings. There is no way to switch one off without deleting it.",
|
|
2204
|
+
pitfalls: ["Its deliveries and their log are deleted too, including any that were still waiting to be sent.", "It cannot be brought back; add the address again for a new endpoint with a new secret.", "An endpoint of another organization is a plain 404.", NOT_ENABLED4, "Needs the scheduling switch to be on for the organization."],
|
|
2205
|
+
dataSensitivity: "internal",
|
|
2206
|
+
risk: "act",
|
|
2207
|
+
requiresApproval: {
|
|
2208
|
+
action: "Remove a webhook",
|
|
2209
|
+
reason: "The endpoint and its delivery history are deleted for good.",
|
|
2210
|
+
prompt: "Remove webhook {id}? This cannot be undone."
|
|
2211
|
+
}
|
|
2212
|
+
},
|
|
2213
|
+
{
|
|
2214
|
+
name: "scheduling_send_test_webhook",
|
|
2215
|
+
module: "scheduling",
|
|
2216
|
+
method: "POST",
|
|
2217
|
+
route: "/admin/webhooks/[id]/test",
|
|
2218
|
+
auth: "session_cookie",
|
|
2219
|
+
description: "Send one signed test event to an endpoint right now, with no retries, and report whether the receiver accepted it.",
|
|
2220
|
+
params: [ENDPOINT_ID],
|
|
2221
|
+
example: { id: "hook_1" },
|
|
2222
|
+
responseShape: "{ deliveryId, ok, statusCode, error }",
|
|
2223
|
+
whenToUse: "After adding an endpoint, or when a receiver seems to be missing events.",
|
|
2224
|
+
pitfalls: [
|
|
2225
|
+
"The answer is 200 whether or not the receiver accepted it: read ok. ok false comes with the receiver's statusCode, or an error when it could not be reached.",
|
|
2226
|
+
"It makes a real outgoing request from the server to the address, and the test shows in the delivery log as the event webhook.test. A test that fails (the receiver answers with an error or cannot be reached) is logged as DEAD_LETTER after its single try, so it appears in that list and could be retried like any other.",
|
|
2227
|
+
"An endpoint of another organization is a plain 404.",
|
|
2228
|
+
NOT_ENABLED4,
|
|
2229
|
+
"Needs the scheduling switch to be on for the organization."
|
|
2230
|
+
],
|
|
2231
|
+
dataSensitivity: "internal",
|
|
2232
|
+
risk: "act",
|
|
2233
|
+
requiresApproval: {
|
|
2234
|
+
action: "Send a test webhook",
|
|
2235
|
+
reason: "The server sends a real request to an outside address.",
|
|
2236
|
+
prompt: "Send a test event to webhook {id}?"
|
|
2237
|
+
}
|
|
2238
|
+
},
|
|
2239
|
+
{
|
|
2240
|
+
name: "scheduling_list_webhook_deliveries",
|
|
2241
|
+
module: "scheduling",
|
|
2242
|
+
method: "GET",
|
|
2243
|
+
route: "/admin/webhooks/[id]/deliveries",
|
|
2244
|
+
auth: "session_cookie",
|
|
2245
|
+
description: "Read the delivery log of one endpoint, newest first: each event, whether it got through, and the last attempts.",
|
|
2246
|
+
params: [
|
|
2247
|
+
ENDPOINT_ID,
|
|
2248
|
+
{ name: "status", type: "string", required: false, description: "Only deliveries in this state: PENDING (waiting to be sent), PROCESSING (being sent), SUCCEEDED, or DEAD_LETTER (ran out of tries)", allowedValues: ["PENDING", "PROCESSING", "SUCCEEDED", "DEAD_LETTER"] },
|
|
2249
|
+
{ name: "limit", type: "number", required: false, description: "How many deliveries to return (default 50, at most 200)" },
|
|
2250
|
+
{ name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
|
|
2251
|
+
],
|
|
2252
|
+
example: { id: "hook_1", status: "DEAD_LETTER" },
|
|
2253
|
+
responseShape: `{ deliveries: [{ ${DELIVERY_FIELDS} }], total, hasMore }`,
|
|
2254
|
+
whenToUse: "To find out why an outside system missed events, and to find the id of a DEAD_LETTER delivery to retry.",
|
|
2255
|
+
pitfalls: ["Each delivery shows only its last 10 attempts.", "Any other status value is refused with 400.", "An endpoint of another organization is a plain 404.", NOT_ENABLED4, "Needs the scheduling switch to be on for the organization."],
|
|
2256
|
+
dataSensitivity: "internal",
|
|
2257
|
+
risk: "observe"
|
|
2258
|
+
},
|
|
2259
|
+
{
|
|
2260
|
+
name: "scheduling_retry_webhook_delivery",
|
|
2261
|
+
module: "scheduling",
|
|
2262
|
+
method: "POST",
|
|
2263
|
+
route: "/admin/webhook-deliveries/[id]/retry",
|
|
2264
|
+
auth: "session_cookie",
|
|
2265
|
+
description: "Put a delivery that ran out of tries back in the queue with a fresh set of tries.",
|
|
2266
|
+
params: [{ name: "id", type: "string", required: true, description: "Delivery id (not the endpoint id), from scheduling_list_webhook_deliveries" }],
|
|
2267
|
+
example: { id: "delivery_1" },
|
|
2268
|
+
responseShape: "{ success: true }",
|
|
2269
|
+
whenToUse: "After fixing a receiver, to send again an event it missed.",
|
|
2270
|
+
pitfalls: [
|
|
2271
|
+
"Only a DEAD_LETTER delivery can be retried (this includes a failed test send); any other delivery, or one of another organization, is a plain 404.",
|
|
2272
|
+
"This only queues it. The server's background delivery sends it, so success true does not mean the receiver has it yet; read the delivery log again later.",
|
|
2273
|
+
"The event is sent again as it was first made, so the receiver may see an event it partly processed before.",
|
|
2274
|
+
NOT_ENABLED4,
|
|
2275
|
+
"Needs the scheduling switch to be on for the organization."
|
|
2276
|
+
],
|
|
2277
|
+
dataSensitivity: "internal",
|
|
2278
|
+
risk: "act",
|
|
2279
|
+
requiresApproval: {
|
|
2280
|
+
action: "Retry a webhook delivery",
|
|
2281
|
+
reason: "The event is sent to the outside address again.",
|
|
2282
|
+
prompt: "Send delivery {id} again?"
|
|
2283
|
+
}
|
|
2284
|
+
}
|
|
2285
|
+
];
|
|
2286
|
+
|
|
978
2287
|
// src/agent/coverage.ts
|
|
979
2288
|
var SCHEDULING_AGENT_EXCLUDED = {
|
|
2289
|
+
"POST /coupons/validate": "Advisory price check for a visitor's booking page. It changes nothing but is a POST, and only GET tools run without approval; staff read a coupon's terms with the coupon list tool.",
|
|
2290
|
+
"POST /waitlist": "A client joining the waitlist for themselves; the answer holds their own private link token, which an agent should never be handed.",
|
|
2291
|
+
"DELETE /waitlist": "A client leaving the waitlist from their own private link; staff remove an entry with the remove-waitlist-entry tool.",
|
|
2292
|
+
"GET /waitlist/offer": "A client reading their own offer from a private link token.",
|
|
2293
|
+
"POST /waitlist/offer/accept": "A client taking their own offer from a private link token; it books the slot.",
|
|
980
2294
|
"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
2295
|
"GET /type": "Public page data for one booking link; the staff tools list the same types.",
|
|
982
2296
|
"GET /calendars": "Public booking-page data for visitors; the admin calendar tools cover this for staff.",
|
|
983
2297
|
"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
|
|
985
|
-
"GET /routing-forms": "Public form shown to a visitor; the
|
|
986
|
-
"POST /routing-forms/route": "Runs a visitor's own answers through a form; staff
|
|
2298
|
+
"GET /brand": "Public copy of the brand settings; the brand tool for staff returns the same data.",
|
|
2299
|
+
"GET /routing-forms": "Public form shown to a visitor; staff read the whole form, rules and fallback included, with scheduling_get_routing_form.",
|
|
2300
|
+
"POST /routing-forms/route": "Runs a visitor's own answers through a form; staff try sample answers with scheduling_test_routing_form.",
|
|
987
2301
|
"GET /appointments/ical": "Calendar feed opened with a private link token, not a staff sign-in.",
|
|
988
2302
|
"GET /appointments/manage": "Client self-service opened with a private link token, not a staff sign-in.",
|
|
989
2303
|
"DELETE /appointments/manage": "Client self-service opened with a private link token; staff cancel with the cancel tool.",
|
|
@@ -997,63 +2311,10 @@ var SCHEDULING_AGENT_EXCLUDED = {
|
|
|
997
2311
|
"GET /calendars/connect-outlook": "Starts a Microsoft sign-in that a person must finish in a browser.",
|
|
998
2312
|
"GET /calendars/connect-outlook/callback": "The address Microsoft sends the person's browser back to."
|
|
999
2313
|
};
|
|
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
|
-
];
|
|
2314
|
+
var SCHEDULING_AGENT_PENDING = [];
|
|
1054
2315
|
|
|
1055
2316
|
// src/agent/index.ts
|
|
1056
|
-
var SCHEDULING_AGENT_TOOLS = [...APPOINTMENT_TOOLS, ...CALENDAR_TOOLS, ...TYPE_TOOLS, ...AVAILABILITY_TOOLS];
|
|
2317
|
+
var SCHEDULING_AGENT_TOOLS = [...APPOINTMENT_TOOLS, ...CALENDAR_TOOLS, ...TYPE_TOOLS, ...AVAILABILITY_TOOLS, ...SERIES_TOOLS, ...SETTINGS_TOOLS, ...POLICY_TOOLS, ...BILLING_TOOLS, ...WEBHOOK_TOOLS, ...ROUTING_TOOLS, ...WAITLIST_TOOLS, ...PRIVACY_TOOLS, ...ANALYTICS_TOOLS];
|
|
1057
2318
|
function createSchedulingAgentTools(options = {}) {
|
|
1058
2319
|
const base = (options.basePath ?? "/api/scheduling").replace(/\/+$/, "");
|
|
1059
2320
|
return SCHEDULING_AGENT_TOOLS.filter((tool) => !options.readOnly || tool.method === "GET").map(({ route, ...tool }) => ({
|