@ordinatio/scheduling-api 0.3.1 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.1 (2026-11-07)
4
+
5
+ This release adds 20 agent tools and one fix. The tools that take a list of objects (weekly hours, intake form) need an agent runner
6
+ that offers the `json-array` type, which `@ordinatio/agent` 2.2.0 provides.
7
+
8
+ - **New agent tools for calendars (11 more).** `createSchedulingAgentTools()` now also covers the staff options list, listing,
9
+ reading, creating, changing and archiving calendars, reading and saving a calendar's booking page, disconnecting the Google and
10
+ Outlook connections, and the recently used places of a calendar. Everything that changes something carries an approval request.
11
+ The booking page tool takes its theme and config as `json-object` parameters.
12
+ - **New agent tools for appointment types and opening hours (9 more).** `createSchedulingAgentTools()` now also covers listing every
13
+ appointment type (switched-off ones too), creating, changing and deleting a type, restarting a team type's rotation, listing a
14
+ calendar's hours, setting the weekly hours, and adding or removing date exceptions (a closed day, a blocked part of a day, or
15
+ custom hours). Everything that changes something carries an approval request. Setting the weekly hours and an intake form take
16
+ `json-array` parameters (a list of objects), which needs a runner that offers that type; the agent package supports it from the
17
+ version that added `json-array`.
18
+ - **Fix to the calendar tool text.** The create-calendar tool said a calendar with no opening hours offers no times. It is the
19
+ opposite: until weekly hours are set, such a calendar is open around the clock. The text now says so and points to the new tool.
20
+ - **Fix: a change to a calendar's opening hours now shows on the booking page at once.** Setting the weekly hours
21
+ (`PUT /admin/availability/[calendarId]`), adding a blocked day, a blocked time range or custom hours, and removing one
22
+ (`POST` and `DELETE` on the same route) did not clear the availability cache, so with the built-in cache the public times for that
23
+ calendar and day stayed as they were for up to a minute. All three now clear the calendar's cached times after the change is
24
+ saved. A cache that fails is logged and does not turn the answer into an error. Hosts that supply their own `availabilityCache`
25
+ need no change: its `invalidate(calendarId)` is simply called more often.
26
+
27
+ ## 0.4.0 (2026-10-31)
28
+
29
+ This release carries a security fix (the first entry) and a new export. It is a minor version because two answers lose fields and
30
+ there is a new `@ordinatio/scheduling-api/agent` export; apps that pin `^0.3.0` stay on 0.3.1 until they raise the range.
31
+
32
+ - **Security fix: the answers of `POST /admin/calendars` and `PUT /admin/calendars/[id]` no longer carry a calendar's stored secrets.**
33
+ They used to return the whole stored row, which for a calendar connected to Outlook or Google includes the Outlook access and
34
+ refresh tokens, the Outlook token expiry, the Google and Outlook sync tokens, the Google watch channel, resource, expiry and token,
35
+ and the iCloud address. Reading and listing calendars never did. The two answers now hold a fixed list of safe fields (id,
36
+ organizationId, name, slug, type, timezone, isActive, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, staffName,
37
+ staffEmail, staffAvatar, userId, theme, bookingPageConfig, location, slotGranularityMinutes, createdAt, updatedAt), so a column
38
+ added later stays out until it is added on purpose. The removed fields are not meant to be read by a host and are gone on
39
+ purpose. Upgrade soon; tokens already returned in earlier responses may be in your logs.
40
+ - **Fix: `PUT /admin/calendars/[id]` can no longer switch off the last active calendar.** `DELETE` refused it with 409, but an update
41
+ with `isActive: false` went through and left the organization with no calendar that takes bookings. An update that switches an
42
+ active calendar off now archives it first, with the same 409 for the last active one; a 409 changes nothing. If the archive
43
+ succeeds and the other changes in the same request then fail to save, the calendar is switched back on and the request fails as
44
+ before; only if that also fails does it stay archived, with its address and cached pages updated to match.
45
+ - **Fix: a booking page's `logoUrl` and `redirectUrl` must now start with `https://`.** The check accepted plain `http://` although
46
+ its error message said https. A value already saved is not touched until the page is saved again.
47
+ - **New: `@ordinatio/scheduling-api/agent`, tools an AI agent can use to run scheduling.** `createSchedulingAgentTools({ basePath, readOnly })`
48
+ returns one tool description per staff route (name, plain-language description, parameters, example, response, risk level). This
49
+ release covers finding free times and everything on a single appointment: list, book, cancel, move, approve or reject, reassign,
50
+ no-show, follow-up, reminder, notes, location, balance and refund. Every tool that changes something carries an approval request
51
+ for a person to confirm; reads never do. The shape matches `@ordinatio/agent`'s tools, with no extra dependency. A test lists every
52
+ route and fails if one has no tool, no reason to be left out, and no place on the "still to cover" list, so a new route can never be
53
+ forgotten. A limit test stops the "still to cover" list from growing.
54
+
3
55
  ## 0.3.1 (2026-10-29)
4
56
 
5
57
  - **Fix: booking-page theme values that load a web address are rejected.** The theme fields of a booking page refuse CSS that fetches
package/README.md CHANGED
@@ -344,6 +344,25 @@ does not end up in access logs.
344
344
  A body that names nobody, names an invalid address, or carries other fields is a 400. Both actions are rate limited and written to
345
345
  the host's activity feed with counts only. Without `privacy` on the host the routes answer 501.
346
346
 
347
+ ## Agent tools
348
+
349
+ An AI agent can run scheduling through the same routes. Import the tool descriptions and hand them to any agent runner:
350
+
351
+ ```ts
352
+ import { createSchedulingAgentTools } from '@ordinatio/scheduling-api/agent';
353
+
354
+ const tools = createSchedulingAgentTools({ basePath: '/api/scheduling' }); // readOnly: true leaves out everything that changes data
355
+ ```
356
+
357
+ Each tool maps to a route, says when to use it, lists its parameters and gives an example. Reads run freely. Every tool that
358
+ changes something, sends a message or moves money carries an `requiresApproval` entry, so the runner asks a person first. The tools
359
+ call your routes. Tools on staff routes use the signed-in person's session, so the usual sign-in, role and organization checks apply. Tools on the public booking routes (`auth: 'none'`: availability, appointment types, capacity and booking) behave exactly like the public widget: no staff sign-in, rate limited by address, and without the staff member's calendar visibility. Give those to an agent only if that is what you want. Parameter types are `string`, `number`, `boolean`, `string[]` and `json-object`. The booking tool's `intakeResponses` is a `json-object`: a runner that turns types it does not know into text cannot pass intake answers, so it needs to offer that type to the model as an object (`@ordinatio/agent` does, except for Gemini, where booking with intake answers does not work yet).
360
+
361
+ Some routes are left out on purpose, such as the public booking widget, link-token self-service, worker entry points and browser
362
+ sign-in steps; `SCHEDULING_AGENT_EXCLUDED` gives the reason for each. `SCHEDULING_AGENT_PENDING` lists the routes that do not have a
363
+ tool yet (appointment types, availability rules, recurring series, coupons, packages, policy, webhooks, routing forms,
364
+ waitlist, privacy, analytics). That list only gets shorter: a test fails if a route is in none of the three places.
365
+
347
366
  ## Serving the routes
348
367
 
349
368
  - **One handler:** `api.handle(request)` serves every route under `/api/scheduling` (change it with
@@ -0,0 +1,55 @@
1
+ import { H as HttpMethod } from '../routes-CM-ezlv2.mjs';
2
+ import '@ordinatio/scheduling';
3
+
4
+ interface SchedulingToolParam {
5
+ name: string;
6
+ type: string;
7
+ required: boolean;
8
+ description: string;
9
+ allowedValues?: string[];
10
+ }
11
+ interface SchedulingApprovalGate {
12
+ /** Stable text: a runner matches the person's reply against it, so changing it changes behaviour. */
13
+ action: string;
14
+ reason: string;
15
+ /** May use {name} placeholders for the tool's own parameters. */
16
+ prompt: string;
17
+ }
18
+ interface SchedulingAgentTool {
19
+ name: string;
20
+ description: string;
21
+ module: 'scheduling';
22
+ method: HttpMethod;
23
+ /** Full path including the mount point, with {name} placeholders. */
24
+ endpoint: string;
25
+ /** 'none' marks a public route that takes no staff sign-in. */
26
+ auth: 'session_cookie' | 'none';
27
+ params: SchedulingToolParam[];
28
+ example: Record<string, unknown>;
29
+ responseShape: string;
30
+ whenToUse: string;
31
+ pitfalls?: string[];
32
+ dataSensitivity: 'none' | 'internal' | 'sensitive' | 'critical';
33
+ /** observe reads, act changes a booking, govern moves money or changes who may do what. */
34
+ risk: 'observe' | 'act' | 'govern';
35
+ requiresApproval?: SchedulingApprovalGate;
36
+ }
37
+ /** A tool as written in the source: tied to its route by path, mount point not yet applied. */
38
+ type SchedulingToolSource = Omit<SchedulingAgentTool, 'endpoint'> & {
39
+ /** The route path as listed in the route table, with [name] placeholders. */
40
+ route: string;
41
+ };
42
+
43
+ declare const SCHEDULING_AGENT_EXCLUDED: Record<string, string>;
44
+ declare const SCHEDULING_AGENT_PENDING: readonly string[];
45
+
46
+ declare const SCHEDULING_AGENT_TOOLS: SchedulingToolSource[];
47
+ interface SchedulingAgentToolOptions {
48
+ /** Where the host mounts the API. Defaults to /api/scheduling. */
49
+ basePath?: string;
50
+ /** Leave out every tool that changes something. Relies on every GET route being free of side effects. */
51
+ readOnly?: boolean;
52
+ }
53
+ declare function createSchedulingAgentTools(options?: SchedulingAgentToolOptions): SchedulingAgentTool[];
54
+
55
+ export { SCHEDULING_AGENT_EXCLUDED, SCHEDULING_AGENT_PENDING, SCHEDULING_AGENT_TOOLS, type SchedulingAgentTool, type SchedulingAgentToolOptions, type SchedulingApprovalGate, type SchedulingToolParam, type SchedulingToolSource, createSchedulingAgentTools };
@@ -0,0 +1,55 @@
1
+ import { H as HttpMethod } from '../routes-CM-ezlv2.js';
2
+ import '@ordinatio/scheduling';
3
+
4
+ interface SchedulingToolParam {
5
+ name: string;
6
+ type: string;
7
+ required: boolean;
8
+ description: string;
9
+ allowedValues?: string[];
10
+ }
11
+ interface SchedulingApprovalGate {
12
+ /** Stable text: a runner matches the person's reply against it, so changing it changes behaviour. */
13
+ action: string;
14
+ reason: string;
15
+ /** May use {name} placeholders for the tool's own parameters. */
16
+ prompt: string;
17
+ }
18
+ interface SchedulingAgentTool {
19
+ name: string;
20
+ description: string;
21
+ module: 'scheduling';
22
+ method: HttpMethod;
23
+ /** Full path including the mount point, with {name} placeholders. */
24
+ endpoint: string;
25
+ /** 'none' marks a public route that takes no staff sign-in. */
26
+ auth: 'session_cookie' | 'none';
27
+ params: SchedulingToolParam[];
28
+ example: Record<string, unknown>;
29
+ responseShape: string;
30
+ whenToUse: string;
31
+ pitfalls?: string[];
32
+ dataSensitivity: 'none' | 'internal' | 'sensitive' | 'critical';
33
+ /** observe reads, act changes a booking, govern moves money or changes who may do what. */
34
+ risk: 'observe' | 'act' | 'govern';
35
+ requiresApproval?: SchedulingApprovalGate;
36
+ }
37
+ /** A tool as written in the source: tied to its route by path, mount point not yet applied. */
38
+ type SchedulingToolSource = Omit<SchedulingAgentTool, 'endpoint'> & {
39
+ /** The route path as listed in the route table, with [name] placeholders. */
40
+ route: string;
41
+ };
42
+
43
+ declare const SCHEDULING_AGENT_EXCLUDED: Record<string, string>;
44
+ declare const SCHEDULING_AGENT_PENDING: readonly string[];
45
+
46
+ declare const SCHEDULING_AGENT_TOOLS: SchedulingToolSource[];
47
+ interface SchedulingAgentToolOptions {
48
+ /** Where the host mounts the API. Defaults to /api/scheduling. */
49
+ basePath?: string;
50
+ /** Leave out every tool that changes something. Relies on every GET route being free of side effects. */
51
+ readOnly?: boolean;
52
+ }
53
+ declare function createSchedulingAgentTools(options?: SchedulingAgentToolOptions): SchedulingAgentTool[];
54
+
55
+ export { SCHEDULING_AGENT_EXCLUDED, SCHEDULING_AGENT_PENDING, SCHEDULING_AGENT_TOOLS, type SchedulingAgentTool, type SchedulingAgentToolOptions, type SchedulingApprovalGate, type SchedulingToolParam, type SchedulingToolSource, createSchedulingAgentTools };