@ordinatio/scheduling-api 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,39 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.0 (2026-10-31)
4
+
5
+ This release carries a security fix (the first entry) and a new export. It is a minor version because two answers lose fields and
6
+ 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.
7
+
8
+ - **Security fix: the answers of `POST /admin/calendars` and `PUT /admin/calendars/[id]` no longer carry a calendar's stored secrets.**
9
+ They used to return the whole stored row, which for a calendar connected to Outlook or Google includes the Outlook access and
10
+ refresh tokens, the Outlook token expiry, the Google and Outlook sync tokens, the Google watch channel, resource, expiry and token,
11
+ and the iCloud address. Reading and listing calendars never did. The two answers now hold a fixed list of safe fields (id,
12
+ organizationId, name, slug, type, timezone, isActive, googleCalendarId, outlookCalendarId, syncDirection, lastSyncAt, staffName,
13
+ staffEmail, staffAvatar, userId, theme, bookingPageConfig, location, slotGranularityMinutes, createdAt, updatedAt), so a column
14
+ 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
15
+ purpose. Upgrade soon; tokens already returned in earlier responses may be in your logs.
16
+ - **Fix: `PUT /admin/calendars/[id]` can no longer switch off the last active calendar.** `DELETE` refused it with 409, but an update
17
+ with `isActive: false` went through and left the organization with no calendar that takes bookings. An update that switches an
18
+ active calendar off now archives it first, with the same 409 for the last active one; a 409 changes nothing. If the archive
19
+ succeeds and the other changes in the same request then fail to save, the calendar is switched back on and the request fails as
20
+ before; only if that also fails does it stay archived, with its address and cached pages updated to match.
21
+ - **Fix: a booking page's `logoUrl` and `redirectUrl` must now start with `https://`.** The check accepted plain `http://` although
22
+ its error message said https. A value already saved is not touched until the page is saved again.
23
+ - **New: `@ordinatio/scheduling-api/agent`, tools an AI agent can use to run scheduling.** `createSchedulingAgentTools({ basePath, readOnly })`
24
+ returns one tool description per staff route (name, plain-language description, parameters, example, response, risk level). This
25
+ release covers finding free times and everything on a single appointment: list, book, cancel, move, approve or reject, reassign,
26
+ no-show, follow-up, reminder, notes, location, balance and refund. Every tool that changes something carries an approval request
27
+ for a person to confirm; reads never do. The shape matches `@ordinatio/agent`'s tools, with no extra dependency. A test lists every
28
+ 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
29
+ forgotten. A limit test stops the "still to cover" list from growing.
30
+
31
+ ## 0.3.1 (2026-10-29)
32
+
33
+ - **Fix: booking-page theme values that load a web address are rejected.** The theme fields of a booking page refuse CSS that fetches
34
+ a URL, including forms written with escapes (`\75rl(...)`) and `image-set()`, `src()`, `cross-fade()`, `element()` and `paint()`.
35
+ A theme that already holds such a value is no longer accepted when saved.
36
+
3
37
  ## 0.3.0 (2026-10-29)
4
38
 
5
39
  - **Security fix: the staff routes `GET /appointments`, `GET /analytics` and `GET /admin/group-sessions` now limit what they return to
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 (calendars, 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 };