@ordinatio/scheduling-api 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -403,11 +403,554 @@ var APPOINTMENT_TOOLS = [
403
403
  }
404
404
  ];
405
405
 
406
+ // src/agent/availability-tools.ts
407
+ var CALENDAR_ID = { name: "calendarId", type: "string", required: true, description: "Calendar id" };
408
+ var RULE_FIELDS = "id, calendarId, dayOfWeek, startTime, endTime, specificDate, isBlocked, blockReason, maxPerDay, bufferBefore, bufferAfter, minNotice, maxAdvanceBooking, createdAt";
409
+ var WEEKLY_RULE = "A list with one object per open day. Each object has dayOfWeek (a whole number from 0 (Sunday) to 6 (Saturday); each day at most once), startTime and endTime (HH:MM on a 24-hour clock, startTime before endTime), and optionally bufferBefore and bufferAfter (minutes kept free around a booking, 0 to 120; 0 and 15 if left out), minNotice (minutes of warning needed before a booking, 0 to 10080; 60 if left out), maxAdvanceBooking (how many days ahead clients may book, 1 to 365; 60 if left out) and maxPerDay (most bookings in the day, a whole number of 1 or more, or null for no limit; no limit if left out).";
410
+ var AVAILABILITY_TOOLS = [
411
+ {
412
+ name: "scheduling_list_availability_rules",
413
+ module: "scheduling",
414
+ method: "GET",
415
+ route: "/admin/availability/[calendarId]",
416
+ auth: "session_cookie",
417
+ description: "List the opening hours of one calendar: the weekly rules (they have a dayOfWeek) and the exceptions for single dates (they have a specificDate).",
418
+ params: [
419
+ CALENDAR_ID,
420
+ { name: "limit", type: "number", required: false, description: "How many rules to return (default 200, at most 500)" },
421
+ { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
422
+ ],
423
+ example: { calendarId: "cal_1" },
424
+ responseShape: `{ rules: [{ ${RULE_FIELDS} }], total, hasMore }`,
425
+ whenToUse: "Before changing the hours, to see what is set now, and to find the ruleId of an exception to remove.",
426
+ pitfalls: [
427
+ "A blocked whole day is an exception with isBlocked true and startTime and endTime both 00:00; a blocked part of a day has real times.",
428
+ "A calendar of another organization, or one the person may not see, is a plain 404."
429
+ ],
430
+ dataSensitivity: "internal",
431
+ risk: "observe"
432
+ },
433
+ {
434
+ name: "scheduling_set_weekly_availability",
435
+ module: "scheduling",
436
+ method: "PUT",
437
+ route: "/admin/availability/[calendarId]",
438
+ auth: "session_cookie",
439
+ description: "Set the weekly opening hours of a calendar. This replaces every weekly rule the calendar has now with the list you send.",
440
+ params: [
441
+ CALENDAR_ID,
442
+ { name: "rules", type: "json-array", required: true, description: WEEKLY_RULE }
443
+ ],
444
+ example: {
445
+ calendarId: "cal_1",
446
+ rules: [
447
+ { dayOfWeek: 1, startTime: "09:00", endTime: "17:00" },
448
+ { dayOfWeek: 2, startTime: "09:00", endTime: "17:00", bufferAfter: 10, maxPerDay: 8 }
449
+ ]
450
+ },
451
+ responseShape: `[{ ${RULE_FIELDS} }]`,
452
+ whenToUse: "To give a new calendar its opening hours, or to change them. Send the whole week every time.",
453
+ pitfalls: [
454
+ "Days not listed become closed. To keep a day as it is, send it again.",
455
+ "An empty list does not close the calendar: a calendar with no weekly hours and no custom-hours exception is open around the clock. To stop bookings, block dates or switch the appointment types off.",
456
+ "Date exceptions are kept; only the weekly rules are replaced.",
457
+ "Times are in the time zone of the calendar.",
458
+ "The buffers, notice, advance limit and daily limit are part of each day, so a day sent without them goes back to the defaults.",
459
+ "A runner that cannot offer a list of objects to the model cannot use this tool."
460
+ ],
461
+ dataSensitivity: "internal",
462
+ risk: "act",
463
+ requiresApproval: {
464
+ action: "Set weekly opening hours",
465
+ reason: "The hours decide which times clients can book; days left out stop taking bookings, and an empty list opens the calendar around the clock.",
466
+ prompt: "Replace the weekly opening hours of calendar {calendarId}?"
467
+ }
468
+ },
469
+ {
470
+ name: "scheduling_add_availability_exception",
471
+ module: "scheduling",
472
+ method: "POST",
473
+ route: "/admin/availability/[calendarId]",
474
+ auth: "session_cookie",
475
+ description: "Add an exception for one date: close the whole day, block part of a day, or open custom hours that day.",
476
+ params: [
477
+ CALENDAR_ID,
478
+ { name: "date", type: "string", required: true, description: "The date, YYYY-MM-DD" },
479
+ { name: "isBlocked", type: "boolean", required: false, description: "true blocks time (true if left out); false opens custom hours that day, 09:00 to 17:00 unless startTime and endTime say otherwise" },
480
+ { name: "startTime", type: "string", required: false, description: "HH:MM on a 24-hour clock. With isBlocked true, together with endTime, it blocks only that part of the day; with isBlocked false it is when the custom hours begin" },
481
+ { name: "endTime", type: "string", required: false, description: "HH:MM on a 24-hour clock, after startTime" },
482
+ { name: "blockReason", type: "string", required: false, description: "A short note for staff, up to 500 characters" }
483
+ ],
484
+ example: { calendarId: "cal_1", date: "2026-12-24", isBlocked: true, blockReason: "Holiday" },
485
+ responseShape: `{ ${RULE_FIELDS}, warning? }`,
486
+ whenToUse: "For a holiday, a meeting, a short day or a special opening. Use scheduling_set_weekly_availability for the regular week.",
487
+ pitfalls: [
488
+ "Leave startTime and endTime out to close the whole day.",
489
+ "Closing the whole day or opening custom hours replaces every exception already set for that date, part-day blocks included. A part-day block is added next to the others.",
490
+ "Times are in the time zone of the calendar.",
491
+ "Blocking part of a day does not cancel bookings already in it; a warning says how many overlap, if any.",
492
+ "On a calendar that has no weekly hours at all, a part-day block closes that whole day instead of leaving the rest of it open.",
493
+ "On a calendar that has no weekly hours at all, the first custom-hours exception (isBlocked false) closes every other day, which until then were open around the clock. Set the weekly hours first.",
494
+ "A part-day block in the past, one that overlaps another block that day, or a 21st block on the same day is refused with 400.",
495
+ "Send both startTime and endTime or neither: with isBlocked true and only one of them, the whole day is closed and the time is ignored."
496
+ ],
497
+ dataSensitivity: "internal",
498
+ risk: "act",
499
+ requiresApproval: {
500
+ action: "Add an availability exception",
501
+ reason: "Closing or opening time on a date changes which times clients can book.",
502
+ prompt: "Add an exception for {date} on calendar {calendarId}?"
503
+ }
504
+ },
505
+ {
506
+ name: "scheduling_remove_availability_exception",
507
+ module: "scheduling",
508
+ method: "DELETE",
509
+ route: "/admin/availability/[calendarId]",
510
+ auth: "session_cookie",
511
+ description: "Remove one date exception, which gives that day or time back to the normal weekly hours.",
512
+ params: [
513
+ CALENDAR_ID,
514
+ { name: "ruleId", type: "string", required: true, description: "Id of the exception, from scheduling_list_availability_rules" }
515
+ ],
516
+ example: { calendarId: "cal_1", ruleId: "rule_1" },
517
+ responseShape: "{ success: true }",
518
+ whenToUse: "When a holiday or block was added by mistake or no longer applies. Find the id with scheduling_list_availability_rules.",
519
+ pitfalls: [
520
+ "Use only an id whose rule has a specificDate. The route does not check, so the id of a weekly rule is deleted too, and that weekday is closed.",
521
+ "An id that is not on this calendar is a 404.",
522
+ "Removing the last weekly rule leaves the calendar with no weekly hours. With no custom-hours exception either, it is then open around the clock, not closed; with one, only the dates of its custom hours are open and every other day is closed."
523
+ ],
524
+ dataSensitivity: "internal",
525
+ risk: "act",
526
+ requiresApproval: {
527
+ action: "Remove an availability exception",
528
+ reason: "The date goes back to the weekly hours, which can open times that were closed.",
529
+ prompt: "Remove exception {ruleId} from calendar {calendarId}?"
530
+ }
531
+ }
532
+ ];
533
+
534
+ // src/agent/calendar-tools.ts
535
+ var ID2 = { name: "id", type: "string", required: true, description: "Calendar id" };
536
+ var CALENDAR_FIELDS = "id, name, slug, type, timezone, isActive, staffName, staffEmail, staffAvatar, userId, location, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, slotGranularityMinutes";
537
+ var THEME_KEYS = "primaryColor, accentColor, backgroundColor, textColor, mutedTextColor, borderColor, borderRadius, fontFamily";
538
+ var CONFIG_KEYS = "title, description, logoUrl, confirmationMessage, redirectUrl, redirectDelay, showContactInfo";
539
+ var SLOT_SIZES = "one of 5, 10, 15, 30 or 60 (minutes between the start times offered)";
540
+ var CALENDAR_TOOLS = [
541
+ {
542
+ name: "scheduling_list_staff_options",
543
+ module: "scheduling",
544
+ method: "GET",
545
+ route: "/admin/calendars/staff-options",
546
+ auth: "session_cookie",
547
+ description: "List the active people in the organization that a calendar can be linked to, with id, name and email.",
548
+ params: [],
549
+ example: {},
550
+ responseShape: "{ staff: [{ id, name, email }] }",
551
+ whenToUse: "Before linking a calendar to a person: the id returned here is the userId to use, provided it is in the cuid format the calendar tools accept (other ids are refused with 400).",
552
+ pitfalls: ["Admin roles only, because it lists every staff member's name and email.", "A host that has no staff directory returns an empty list."],
553
+ dataSensitivity: "sensitive",
554
+ risk: "observe"
555
+ },
556
+ {
557
+ name: "scheduling_list_calendars",
558
+ module: "scheduling",
559
+ method: "GET",
560
+ route: "/admin/calendars",
561
+ auth: "session_cookie",
562
+ description: "List the organization's calendars, active and archived, with how many appointments each has. A person limited by group visibility sees only their groups' calendars.",
563
+ params: [
564
+ { name: "limit", type: "number", required: false, description: "How many to return (default 500, at most 1000)" },
565
+ { name: "offset", type: "number", required: false, description: "How many to skip, for the next page" }
566
+ ],
567
+ example: { limit: 100 },
568
+ responseShape: `{ calendars: [{ ${CALENDAR_FIELDS}, _count }], total, hasMore }`,
569
+ whenToUse: "To find a calendar id, or to see which calendars exist and which are archived (isActive false).",
570
+ pitfalls: ["Only counts: appointments are listed with the appointments tool."],
571
+ dataSensitivity: "internal",
572
+ risk: "observe"
573
+ },
574
+ {
575
+ name: "scheduling_get_calendar",
576
+ module: "scheduling",
577
+ method: "GET",
578
+ route: "/admin/calendars/[id]",
579
+ auth: "session_cookie",
580
+ description: "Read one calendar: its name, type, time zone, staff details, outside-calendar connections and slot size.",
581
+ params: [ID2],
582
+ example: { id: "cal_1" },
583
+ responseShape: `{ calendar: { ${CALENDAR_FIELDS}, organizationId, _count } }`,
584
+ whenToUse: "To check one calendar before changing it.",
585
+ pitfalls: ["A calendar of another organization, or one the person may not see, is a plain 404."],
586
+ dataSensitivity: "internal",
587
+ risk: "observe"
588
+ },
589
+ {
590
+ name: "scheduling_create_calendar",
591
+ module: "scheduling",
592
+ method: "POST",
593
+ route: "/admin/calendars",
594
+ auth: "session_cookie",
595
+ description: "Create a calendar. Its web address name (slug) is made from the name, and it starts active.",
596
+ params: [
597
+ { name: "name", type: "string", required: true, description: "Calendar name, 1 to 100 characters" },
598
+ { name: "type", type: "string", required: false, description: "What the calendar stands for; STAFF if left out", allowedValues: ["STAFF", "LOCATION", "RESOURCE"] },
599
+ { name: "timezone", type: "string", required: false, description: "IANA timezone of the calendar, such as America/New_York (the default)" },
600
+ { name: "staffName", type: "string", required: false, description: "Name shown on the booking page, up to 100 characters" },
601
+ { name: "staffEmail", type: "string", required: false, description: "Email of the person, where notices go" },
602
+ { name: "staffAvatar", type: "string", required: false, description: "Address (URL) of a picture, up to 500 characters" },
603
+ { name: "userId", type: "string", required: false, description: "The person this calendar belongs to, from the staff options tool: an id in cuid format who is a member of the organization (any other id is refused with 400)" },
604
+ { name: "location", type: "string", required: false, description: "Where appointments happen by default, up to 200 characters" },
605
+ { name: "slotGranularityMinutes", type: "number", required: false, description: `Slot size: ${SLOT_SIZES}; 15 if left out` }
606
+ ],
607
+ example: { name: "Front desk", type: "STAFF", timezone: "America/New_York", slotGranularityMinutes: 15 },
608
+ responseShape: "{ calendar, directoryClaimed } where calendar holds id, organizationId, name, slug, type, timezone, isActive, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, staffName, staffEmail, staffAvatar, userId, theme, bookingPageConfig, location, slotGranularityMinutes, createdAt, updatedAt; sync settings and tokens are never returned",
609
+ whenToUse: "When a new person, room or resource needs its own bookable calendar. Give it opening hours with scheduling_set_weekly_availability.",
610
+ pitfalls: [
611
+ 'A calendar with the same name, or a name that gives the same web address ("Front Desk" and "front-desk!" do), already exists: refused with 409.',
612
+ "A new calendar has no opening hours, which means it is open around the clock (up to the booking limits) until weekly hours are set with scheduling_set_weekly_availability. Set them straight away.",
613
+ "directoryClaimed false means the short booking address could not be registered; only the organization-qualified address works then."
614
+ ],
615
+ dataSensitivity: "internal",
616
+ risk: "act",
617
+ requiresApproval: {
618
+ action: "Create a calendar",
619
+ reason: "A new calendar becomes a bookable resource with its own public booking address.",
620
+ prompt: 'Create the calendar "{name}"?'
621
+ }
622
+ },
623
+ {
624
+ name: "scheduling_update_calendar",
625
+ module: "scheduling",
626
+ method: "PUT",
627
+ route: "/admin/calendars/[id]",
628
+ auth: "session_cookie",
629
+ description: "Change a calendar. Only the fields you send change; a field left out stays as it is. Setting isActive to false archives it.",
630
+ params: [
631
+ ID2,
632
+ { name: "name", type: "string", required: false, description: "New name, 1 to 100 characters" },
633
+ { name: "type", type: "string", required: false, description: "New type", allowedValues: ["STAFF", "LOCATION", "RESOURCE"] },
634
+ { name: "timezone", type: "string", required: false, description: "New IANA timezone" },
635
+ { name: "staffName", type: "string", required: false, description: "New staff name, up to 100 characters, or null to clear it" },
636
+ { name: "staffEmail", type: "string", required: false, description: "New staff email, or null to clear it" },
637
+ { name: "staffAvatar", type: "string", required: false, description: "New picture address (URL), or null to clear it" },
638
+ { name: "userId", type: "string", required: false, description: "The person this calendar belongs to: an id in cuid format who is a member of the organization (any other id is refused with 400); null unlinks it" },
639
+ { name: "location", type: "string", required: false, description: "New default location, up to 200 characters, or null to clear it" },
640
+ { name: "slotGranularityMinutes", type: "number", required: false, description: `New slot size: ${SLOT_SIZES}` },
641
+ { name: "isActive", type: "boolean", required: false, description: "false archives the calendar, true brings it back" },
642
+ { name: "syncDirection", type: "string", required: false, description: "How an outside calendar is synced", allowedValues: ["one-way", "two-way"] }
643
+ ],
644
+ example: { id: "cal_1", timezone: "America/Chicago", slotGranularityMinutes: 30 },
645
+ responseShape: "{ calendar } where calendar holds id, organizationId, name, slug, type, timezone, isActive, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, staffName, staffEmail, staffAvatar, userId, theme, bookingPageConfig, location, slotGranularityMinutes, createdAt, updatedAt; sync settings and tokens are never returned",
646
+ whenToUse: "To rename a calendar, change its time zone or slot size, link it to a person, or switch it off or on.",
647
+ pitfalls: [
648
+ "Changing the time zone changes what the opening hours mean in real time.",
649
+ "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.",
650
+ "Linking a calendar to a person (userId) changes who can see it when staff are limited to their groups.",
651
+ "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."
652
+ ],
653
+ dataSensitivity: "internal",
654
+ risk: "act",
655
+ requiresApproval: {
656
+ action: "Change a calendar",
657
+ reason: "Changes can stop a calendar taking bookings, move its opening hours in real time, and link it to a person, which decides who can see it.",
658
+ prompt: "Change calendar {id}?"
659
+ }
660
+ },
661
+ {
662
+ name: "scheduling_archive_calendar",
663
+ module: "scheduling",
664
+ method: "DELETE",
665
+ route: "/admin/calendars/[id]",
666
+ auth: "session_cookie",
667
+ description: "Archive a calendar: it stops taking bookings and its short address is released. Its appointments are kept, and the update tool can bring it back.",
668
+ params: [ID2],
669
+ example: { id: "cal_1" },
670
+ responseShape: "{ success: true }",
671
+ whenToUse: "When a person, room or resource is no longer bookable.",
672
+ pitfalls: [
673
+ "The last active calendar can never be archived: refused with 409. Create another calendar first.",
674
+ "Appointments already booked on the calendar are not cancelled by this.",
675
+ "Restoring it later with the update tool does not give back its short booking address; only the organization-qualified address works until it is registered again."
676
+ ],
677
+ dataSensitivity: "internal",
678
+ risk: "act",
679
+ requiresApproval: {
680
+ action: "Archive a calendar",
681
+ reason: "The calendar stops taking bookings and its public address stops working.",
682
+ prompt: "Archive calendar {id}? It stops taking bookings."
683
+ }
684
+ },
685
+ {
686
+ name: "scheduling_get_booking_page",
687
+ module: "scheduling",
688
+ method: "GET",
689
+ route: "/admin/calendars/[id]/booking-page",
690
+ auth: "session_cookie",
691
+ description: "Read how a calendar's public booking page looks and what it says: the theme colours and fonts, and the page wording and settings.",
692
+ params: [ID2],
693
+ example: { id: "cal_1" },
694
+ responseShape: "{ theme, config, name, slug, staffName }",
695
+ whenToUse: "Before changing the booking page, to see what is set now.",
696
+ pitfalls: ["theme and config are null when nothing was ever saved."],
697
+ dataSensitivity: "internal",
698
+ risk: "observe"
699
+ },
700
+ {
701
+ name: "scheduling_update_booking_page",
702
+ module: "scheduling",
703
+ method: "PUT",
704
+ route: "/admin/calendars/[id]/booking-page",
705
+ auth: "session_cookie",
706
+ description: "Save the look and wording of a calendar's public booking page. Send theme, config or both; a part left out is untouched, and null clears that part.",
707
+ params: [
708
+ ID2,
709
+ { name: "theme", type: "json-object", required: false, description: `A JSON object of look settings, each optional: ${THEME_KEYS}. Colours and sizes are written as CSS values (such as #1a4d3a or 8px); a value that could load a web address or break out of the style is refused. null clears the theme.` },
710
+ { name: "config", type: "json-object", required: false, description: `A JSON object of page wording and settings, each optional: ${CONFIG_KEYS}. title is up to 100 characters; description and confirmationMessage up to 500; logoUrl and redirectUrl must start with https://; redirectDelay is whole seconds from 0 to 30 (5 if left out); showContactInfo is true or false (true if left out). null clears the config.` }
711
+ ],
712
+ example: { id: "cal_1", theme: { primaryColor: "#1a4d3a", borderRadius: "8px" }, config: { title: "Book a visit", redirectDelay: 5 } },
713
+ responseShape: "{ success: true }",
714
+ whenToUse: "To brand a booking page or change what the client reads on it.",
715
+ pitfalls: [
716
+ "The theme or config you send replaces the saved one as a whole: read it first and send back what should stay.",
717
+ "A runner that cannot offer an object to the model cannot use this tool."
718
+ ],
719
+ dataSensitivity: "internal",
720
+ risk: "act",
721
+ requiresApproval: {
722
+ action: "Change a booking page",
723
+ reason: "The booking page is what clients see when they book.",
724
+ prompt: "Change the booking page of calendar {id}?"
725
+ }
726
+ },
727
+ {
728
+ name: "scheduling_disconnect_google_calendar",
729
+ module: "scheduling",
730
+ method: "POST",
731
+ route: "/admin/calendars/[id]/disconnect-google",
732
+ auth: "session_cookie",
733
+ description: "Disconnect a calendar from Google Calendar. This stops syncing both ways and clears the connection and its sync state. Google may keep sending notices for a while; whether they are accepted is up to the host application that receives them. Appointments already created stay.",
734
+ params: [ID2],
735
+ example: { id: "cal_1" },
736
+ responseShape: "{ success: true }",
737
+ whenToUse: "When a person no longer wants their Google Calendar tied to this calendar.",
738
+ pitfalls: [
739
+ "A calendar that is not connected to Google is refused with 400.",
740
+ "Connecting needs a person to sign in to Google in a browser; no tool can do that."
741
+ ],
742
+ dataSensitivity: "internal",
743
+ risk: "act",
744
+ requiresApproval: {
745
+ action: "Disconnect Google Calendar",
746
+ reason: "Syncing stops, and the connection can only be restored by a person signing in to Google again.",
747
+ prompt: "Disconnect Google Calendar from calendar {id}?"
748
+ }
749
+ },
750
+ {
751
+ name: "scheduling_disconnect_outlook_calendar",
752
+ module: "scheduling",
753
+ method: "POST",
754
+ route: "/admin/calendars/[id]/disconnect-outlook",
755
+ auth: "session_cookie",
756
+ description: "Disconnect a calendar from Outlook Calendar. This stops syncing and removes the stored Outlook sign-in. Appointments already created stay.",
757
+ params: [ID2],
758
+ example: { id: "cal_1" },
759
+ responseShape: "{ success: true }",
760
+ whenToUse: "When a person no longer wants their Outlook calendar tied to this calendar.",
761
+ pitfalls: [
762
+ "A calendar that is not connected to Outlook is refused with 400.",
763
+ "Connecting needs a person to sign in to Microsoft in a browser; no tool can do that."
764
+ ],
765
+ dataSensitivity: "internal",
766
+ risk: "act",
767
+ requiresApproval: {
768
+ action: "Disconnect Outlook Calendar",
769
+ reason: "Syncing stops, and the connection can only be restored by a person signing in to Microsoft again.",
770
+ prompt: "Disconnect Outlook Calendar from calendar {id}?"
771
+ }
772
+ },
773
+ {
774
+ name: "scheduling_list_location_recents",
775
+ module: "scheduling",
776
+ method: "GET",
777
+ route: "/admin/calendars/[id]/location-recents",
778
+ auth: "session_cookie",
779
+ description: "List up to five places that recent appointments on this calendar happened at, most recent first, with a client's preferred place first when a client is named.",
780
+ params: [
781
+ ID2,
782
+ { name: "clientId", type: "string", required: false, description: "A client whose preferred place should come first" }
783
+ ],
784
+ example: { id: "cal_1" },
785
+ responseShape: "{ locations }",
786
+ whenToUse: "When filling in a location for a booking: suggests places already used.",
787
+ pitfalls: ["Open to any signed-in member, not only admin roles.", "A client the person may not see counts as absent, so the answer is the same as for a missing client."],
788
+ dataSensitivity: "internal",
789
+ risk: "observe"
790
+ }
791
+ ];
792
+
793
+ // src/agent/type-tools.ts
794
+ var ID3 = { name: "id", type: "string", required: true, description: "Appointment type id" };
795
+ 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";
796
+ var LOCATION_TYPES = ["IN_PERSON", "TRAVEL_TO_CLIENT", "VIRTUAL", "PHONE"];
797
+ var STRATEGIES = ["NONE", "ROUND_ROBIN", "LOAD_BALANCED"];
798
+ 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).";
799
+ function typeFields(forUpdate) {
800
+ const when = (create, update) => forUpdate ? update : create;
801
+ return [
802
+ { 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.") },
803
+ { 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.") },
804
+ { 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") },
805
+ { 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 },
806
+ { name: "duration", type: "number", required: !forUpdate, description: "Length in whole minutes, 5 to 480" },
807
+ { name: "color", type: "string", required: false, description: when("Calendar colour as #RRGGBB hex; #3B82F6 if left out", "Calendar colour as #RRGGBB hex") },
808
+ { 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") },
809
+ { 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") },
810
+ { 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") },
811
+ { name: "requiresPayment", type: "boolean", required: false, description: when("Whether booking needs a payment; false if left out", "Whether booking needs a payment") },
812
+ { 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") },
813
+ { 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") },
814
+ { 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") },
815
+ { 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") },
816
+ { 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") },
817
+ { 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") },
818
+ { 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") },
819
+ { name: "isGroup", type: "boolean", required: false, description: when("Whether several clients share one session; false if left out", "Whether several clients share one session") },
820
+ { 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") },
821
+ { name: "intakeForm", type: "json-array", required: false, description: when(INTAKE_FORM, `${INTAKE_FORM} Replaces the whole list; null removes the questions.`) },
822
+ { 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") },
823
+ { 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 },
824
+ { 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") }
825
+ ];
826
+ }
827
+ var TYPE_TOOLS = [
828
+ {
829
+ name: "scheduling_list_all_appointment_types",
830
+ module: "scheduling",
831
+ method: "GET",
832
+ route: "/admin/types",
833
+ auth: "session_cookie",
834
+ 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.",
835
+ params: [],
836
+ example: {},
837
+ responseShape: `[{ ${TYPE_FIELDS}, calendars: [{ calendar: { id, name } }], categoryRef, roundRobinState }]`,
838
+ 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.",
839
+ pitfalls: ["The answer is a plain list with no paging.", "Needs the scheduling switch to be on for the organization."],
840
+ dataSensitivity: "internal",
841
+ risk: "observe"
842
+ },
843
+ {
844
+ name: "scheduling_create_appointment_type",
845
+ module: "scheduling",
846
+ method: "POST",
847
+ route: "/admin/types",
848
+ auth: "session_cookie",
849
+ description: "Create an appointment type. Its web address name (slug) is made from the name, and it starts active.",
850
+ params: [...typeFields(false)],
851
+ example: { name: "Consultation", duration: 45, price: 60, deposit: 20, requiresPayment: true, calendarIds: ["cal_1"] },
852
+ responseShape: `{ ${TYPE_FIELDS}, directoryClaimed }`,
853
+ whenToUse: "When something new needs to be bookable. Put it on a calendar with calendarIds, and make sure that calendar has opening hours.",
854
+ pitfalls: [
855
+ "A type with the same name, or a name that gives the same web address, already exists: refused with 409.",
856
+ "isGroup true needs maxSeats of at least 2.",
857
+ "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.",
858
+ "The first and second reminder must not be the same number of minutes (unless one is 0).",
859
+ "directoryClaimed false means the short booking address could not be registered; only the organization-qualified address works then.",
860
+ "Needs the scheduling switch to be on for the organization."
861
+ ],
862
+ dataSensitivity: "internal",
863
+ risk: "act",
864
+ requiresApproval: {
865
+ action: "Create an appointment type",
866
+ reason: "A new type becomes something clients can book, with its own price and booking address.",
867
+ prompt: 'Create the appointment type "{name}"?'
868
+ }
869
+ },
870
+ {
871
+ name: "scheduling_update_appointment_type",
872
+ module: "scheduling",
873
+ method: "PUT",
874
+ route: "/admin/types/[id]",
875
+ auth: "session_cookie",
876
+ 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.",
877
+ params: [
878
+ ID3,
879
+ ...typeFields(true),
880
+ { name: "isActive", type: "boolean", required: false, description: "false switches the type off so it can no longer be booked, true switches it back on" }
881
+ ],
882
+ example: { id: "type_1", duration: 60, price: 80 },
883
+ responseShape: `{ ${TYPE_FIELDS} }`,
884
+ whenToUse: "To change length, price, reminders or intake questions, move a type to other calendars, or switch it off or on.",
885
+ pitfalls: [
886
+ "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.",
887
+ "Bookings that already exist keep their time; a changed length applies to new bookings.",
888
+ "calendarIds and intakeForm replace the whole list, so read the type first and send back what should stay.",
889
+ "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.",
890
+ "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.",
891
+ "Neither the update nor the delete needs the scheduling switch to be on."
892
+ ],
893
+ dataSensitivity: "internal",
894
+ risk: "act",
895
+ requiresApproval: {
896
+ action: "Change an appointment type",
897
+ reason: "Changes can alter what clients pay, how long they are booked for, and whether the type can be booked at all.",
898
+ prompt: "Change appointment type {id}?"
899
+ }
900
+ },
901
+ {
902
+ name: "scheduling_delete_appointment_type",
903
+ module: "scheduling",
904
+ method: "DELETE",
905
+ route: "/admin/types/[id]",
906
+ auth: "session_cookie",
907
+ description: "Delete an appointment type that no appointment has ever used, and release its short booking address.",
908
+ params: [ID3],
909
+ example: { id: "type_1" },
910
+ responseShape: "{ success: true }",
911
+ whenToUse: "Only to remove a type that was created by mistake and never booked.",
912
+ pitfalls: [
913
+ "Refused with 409 while any appointment, past or future, uses the type. Switch it off with isActive false in the update tool instead.",
914
+ "A deleted type cannot be brought back."
915
+ ],
916
+ dataSensitivity: "internal",
917
+ risk: "act",
918
+ requiresApproval: {
919
+ action: "Delete an appointment type",
920
+ reason: "The type is removed for good and its booking address stops working.",
921
+ prompt: "Delete appointment type {id}? This cannot be undone."
922
+ }
923
+ },
924
+ {
925
+ name: "scheduling_reset_round_robin",
926
+ module: "scheduling",
927
+ method: "DELETE",
928
+ route: "/admin/types/[id]/round-robin-state",
929
+ auth: "session_cookie",
930
+ description: "Restart the turn-taking of a team appointment type, so the next booking goes to whoever the rotation starts with.",
931
+ params: [ID3],
932
+ example: { id: "type_1" },
933
+ responseShape: "{ success: true }",
934
+ whenToUse: "After a staff member joins or leaves a team type and the rotation should begin again.",
935
+ pitfalls: [
936
+ "This does not change the strategy or the calendars; it only forgets whose turn was last.",
937
+ "Bookings already made are untouched."
938
+ ],
939
+ dataSensitivity: "internal",
940
+ risk: "act",
941
+ requiresApproval: {
942
+ action: "Reset a rotation",
943
+ reason: "The next bookings are shared out as if the rotation were new, which can shift work between staff.",
944
+ prompt: "Restart the rotation of appointment type {id}?"
945
+ }
946
+ }
947
+ ];
948
+
406
949
  // src/agent/coverage.ts
407
950
  var SCHEDULING_AGENT_EXCLUDED = {
408
951
  "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.",
409
952
  "GET /type": "Public page data for one booking link; the staff tools list the same types.",
410
- "GET /calendars": "Public booking-page data for visitors; the admin calendar tools (still to come) cover this for staff.",
953
+ "GET /calendars": "Public booking-page data for visitors; the admin calendar tools cover this for staff.",
411
954
  "POST /payments/intent": "Creates a card payment in the visitor's own browser session; staff take payment with the collect-balance tool.",
412
955
  "GET /brand": "Public copy of the brand settings; the admin brand tools (still to come) return the same data.",
413
956
  "GET /routing-forms": "Public form shown to a visitor; the admin routing-form tools (still to come) cover it.",
@@ -431,26 +974,6 @@ var SCHEDULING_AGENT_PENDING = [
431
974
  "DELETE /waitlist",
432
975
  "GET /waitlist/offer",
433
976
  "POST /waitlist/offer/accept",
434
- "GET /admin/calendars/staff-options",
435
- "GET /admin/calendars",
436
- "POST /admin/calendars",
437
- "GET /admin/calendars/[id]",
438
- "PUT /admin/calendars/[id]",
439
- "DELETE /admin/calendars/[id]",
440
- "GET /admin/calendars/[id]/booking-page",
441
- "PUT /admin/calendars/[id]/booking-page",
442
- "POST /admin/calendars/[id]/disconnect-google",
443
- "POST /admin/calendars/[id]/disconnect-outlook",
444
- "GET /admin/calendars/[id]/location-recents",
445
- "GET /admin/types",
446
- "POST /admin/types",
447
- "PUT /admin/types/[id]",
448
- "DELETE /admin/types/[id]",
449
- "DELETE /admin/types/[id]/round-robin-state",
450
- "GET /admin/availability/[calendarId]",
451
- "PUT /admin/availability/[calendarId]",
452
- "POST /admin/availability/[calendarId]",
453
- "DELETE /admin/availability/[calendarId]",
454
977
  "GET /admin/recurring",
455
978
  "POST /admin/recurring",
456
979
  "GET /admin/recurring/[id]",
@@ -501,7 +1024,7 @@ var SCHEDULING_AGENT_PENDING = [
501
1024
  ];
502
1025
 
503
1026
  // src/agent/index.ts
504
- var SCHEDULING_AGENT_TOOLS = [...APPOINTMENT_TOOLS];
1027
+ var SCHEDULING_AGENT_TOOLS = [...APPOINTMENT_TOOLS, ...CALENDAR_TOOLS, ...TYPE_TOOLS, ...AVAILABILITY_TOOLS];
505
1028
  function createSchedulingAgentTools(options = {}) {
506
1029
  const base = (options.basePath ?? "/api/scheduling").replace(/\/+$/, "");
507
1030
  return SCHEDULING_AGENT_TOOLS.filter((tool) => !options.readOnly || tool.method === "GET").map(({ route, ...tool }) => ({
package/dist/index.js CHANGED
@@ -5141,6 +5141,15 @@ async function requireOwnedVisibleCalendar(staff, calendarId) {
5141
5141
  return calendar ?? NOT_FOUND8();
5142
5142
  }
5143
5143
 
5144
+ // src/availability/clear-availability-cache.ts
5145
+ async function clearAvailabilityCache(host, calendarId) {
5146
+ try {
5147
+ await host.availabilityCache.invalidate(calendarId);
5148
+ } catch (error) {
5149
+ console.warn("[availability-cache-clear-failed]", calendarId, error);
5150
+ }
5151
+ }
5152
+
5144
5153
  // src/availability/validate-weekly-rules.ts
5145
5154
  function validateWeeklyRules(rules) {
5146
5155
  for (const rule of rules) {
@@ -5210,6 +5219,7 @@ async function setWeeklyRules(request, { host, params }) {
5210
5219
  const validationError = validateWeeklyRules(rules);
5211
5220
  if (validationError) return Response.json({ error: validationError }, { status: 400 });
5212
5221
  const created = await (0, import_scheduling39.setWeeklyAvailability)(db, calendarId, rules);
5222
+ await clearAvailabilityCache(host, calendarId);
5213
5223
  const activeDays = rules.map((r) => ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"][r.dayOfWeek]).join(", ");
5214
5224
  await host.activity.log(db, {
5215
5225
  action: "scheduling.availability_updated",
@@ -5284,6 +5294,7 @@ async function addOverride(request, { host, params }) {
5284
5294
  endTime: body.endTime
5285
5295
  });
5286
5296
  }
5297
+ await clearAvailabilityCache(host, calendarId);
5287
5298
  let overlapWarning;
5288
5299
  if (isBlockedFlag && body.startTime && body.endTime) {
5289
5300
  const dateStr = body.date.split("T")[0];
@@ -5330,6 +5341,7 @@ async function removeOverride(request, { host, params }) {
5330
5341
  const { ruleId } = await request.json();
5331
5342
  if (!ruleId) return Response.json({ error: "ruleId is required" }, { status: 400 });
5332
5343
  const deletedRule = await (0, import_scheduling41.removeDateOverride)(db, calendarId, ruleId);
5344
+ await clearAvailabilityCache(host, calendarId);
5333
5345
  const deletedIsTimeBlock = deletedRule?.isBlocked && !(deletedRule.startTime === "00:00" && deletedRule.endTime === "00:00");
5334
5346
  await host.activity.log(db, {
5335
5347
  action: "scheduling.date_override_removed",