@ordinatio/scheduling-api 0.8.0 → 0.10.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 +13 -0
- package/README.md +10 -0
- package/package.json +3 -3
- package/dist/agent/index.d.mts +0 -55
- package/dist/agent/index.d.ts +0 -55
- package/dist/agent/index.js +0 -2411
- package/dist/agent/index.mjs +0 -2381
- package/dist/chunk-X5BVCLX6.mjs +0 -488
- package/dist/index.d.mts +0 -597
- package/dist/index.d.ts +0 -597
- package/dist/index.js +0 -9491
- package/dist/index.mjs +0 -8993
- package/dist/routes-mii9tsbA.d.mts +0 -462
- package/dist/routes-mii9tsbA.d.ts +0 -462
- package/dist/schemas/index.d.mts +0 -529
- package/dist/schemas/index.d.ts +0 -529
- package/dist/schemas/index.js +0 -553
- package/dist/schemas/index.mjs +0 -84
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,18 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.10.0 (prepared 2026-11-21)
|
|
4
|
+
|
|
5
|
+
- **New: a client can pay for a booking with a gift certificate.** With `host.giftCertificates: {}`, `POST /appointments` takes a `giftCode`. A certificate that covers the whole price books with no card at all: the appointment is stored with no payment id, `paymentProvider: 'gift_certificate'`, `paymentStatus` `PAID` (or `DEPOSIT_PAID` for a type that takes a deposit) and `paymentAmount: 0`, and the price (or deposit) after any coupon is spent on the new appointment. A certificate that covers only part is paid together with a card: `POST /payments/intent` takes a `giftCode` too, charges the card only what the certificate does not pay (leaving it at least 50 cents), writes the certificate's id and amount into the payment itself, and answers `giftAppliedCents`; when the certificate pays everything it answers 200 with `fullyCoveredByGift: true`, `amount: 0` and no payment to confirm. The booking then checks the card amount against the price less exactly that amount, and refuses a payment made with a certificate unless the booking names the same one, and a code named on a payment made without one. The amount to spend is read from the payment, never from the request. `paymentAmount` on the appointment is what the card was charged, so a refund of the card can never be more than that.
|
|
6
|
+
- **A code that cannot be used is refused the same way whatever the reason.** An unknown, void, expired, used-up or other-currency certificate, a code of the wrong shape, and another business's code all get `This gift certificate cannot be used for this booking`. Two other answers do say more, because the client needs them: `GIFT_PARTIAL` (the certificate is valid but covers only part, so a card payment is needed) and a refusal when the payment does not match the certificate it was made with. `POST /payments/intent` answers with `Cache-Control: no-store` when it was sent a code. The code is never written to the activity log or to error logs, and anything shaped like a code is removed from an error text before it is logged or returned. A code sent to a host without the switch is refused with 400 (not 501, since the booking itself is not a gift route); a code sent with a free type is ignored.
|
|
7
|
+
- **If the certificate cannot be spent after the booking is saved** (another booking spent it in the same moment, or it was voided), the booking is cancelled and the client is told: `GIFT_UNAVAILABLE` (409), saying nothing was charged, or that the card payment was refunded; `REFUND_PENDING` if the card refund fails, and staff see an activity entry (`scheduling.gift_booking_refund_pending`). If the cancellation itself fails (tried twice) the card is left alone, the client gets `GIFT_REVIEW_NEEDED`, and staff see `scheduling.gift_booking_needs_review`. The certificate is spent before a coupon use or a package session is counted, so a failure there uses nothing else up; a coupon that turns out to be used up after the certificate was spent gives the certificate back. A certificate that now holds less than the booking needed pays nothing: what it did pay is given back at once, and if that fails the log names the certificate and amount.
|
|
8
|
+
- **Known gaps, closed in the next release.** Cancelling a booking that was paid with a certificate does not give the money back to the certificate by itself; staff can do it with `POST /admin/gift-certificates/[id]/restore` (`appointmentId` links the line). The booking is saved before the certificate is spent, so a server that dies between the two leaves a booking with the certificate unspent. Selling certificates online, and emailing the recipient, are not part of this release.
|
|
9
|
+
- The `scheduling_book_appointment` agent tool takes `giftCode`. The `@ordinatio/scheduling` peer range is now `^0.9.0`.
|
|
10
|
+
|
|
11
|
+
## 0.9.0 (prepared 2026-11-19)
|
|
12
|
+
|
|
13
|
+
- **New: gift certificates.** `host.giftCertificates: {}` turns on `GET` and `POST /admin/gift-certificates`, `GET /admin/gift-certificates/[id]`, `POST /admin/gift-certificates/[id]/void` and `POST /admin/gift-certificates/[id]/restore` for admins, and a public `POST /gift-certificates/check` (`{ code, calendarId }`) that tells a visitor the balance of a code they hold. Without the switch every one answers 501. Answers that can carry a code are `Cache-Control: no-store`; the activity log never records a code and neither do error logs (anything shaped like a code is removed); a failure to write the log never turns a completed change into an error. **A read-only API key sees only the last four characters of each code** (`…JKMN`, with `codeHidden: true`); a person and a full key see whole codes. Issuing again for a payment that already made a certificate answers 200 with the first one and records no second sale. The check answers the same `not_found` for a malformed code, an unknown code, an unknown calendar and another business's code, and is rate limited as a public booking route. Errors: 400 (bad request, every problem listed), 404, 409 (void, used up, repeat or oversized give-back, currency or payment-amount mismatch). New agent tools `scheduling_list_gift_certificates`, `scheduling_get_gift_certificate`, `scheduling_issue_gift_certificate`, `scheduling_void_gift_certificate` and `scheduling_restore_gift_certificate` (the last three ask a person first); the public check has none. Needs `@ordinatio/scheduling` 0.8.0 (now the required version, for `issueGiftCertificateOnce` among others) and its two new tables. Redeeming a certificate at booking, and paying the rest by card, is not part of this release.
|
|
14
|
+
- **The `@ordinatio/scheduling` peer range is now `^0.8.0`.** (An interim change made it accept 0.7.x too; this release needs 0.8.0 for the gift certificate functions, so it asks for 0.8.0.)
|
|
15
|
+
|
|
3
16
|
## 0.8.0 (prepared 2026-11-18)
|
|
4
17
|
|
|
5
18
|
- **New: API keys for outside tools.** `host.apiKeys: { db }` lets a request carry `Authorization: Bearer osk_...` and act as that key's business: the router checks the key before any route runs, makes it the request's staff (counted against the key's own rate limit, not the person's), refuses a `READ` key for anything but `GET` with 403, refuses every key on the routes that need a person at a browser (the calendar-connect routes, marked `personOnly` in the route table) with 403, never looks at a key on a public route, and answers 401 for a revoked or unknown key. A header that does not start `osk_` is left to your own sign-in. New admin routes `GET` and `POST /admin/api-keys` and `DELETE /admin/api-keys/[id]` (the secret is in the answer to `POST` once, with `Cache-Control: no-store`; the activity log records the key's id and access, never the secret). A request made with a key cannot manage keys. The three routes have no agent tools, on purpose. Needs the `OrganizationApiKey` table and `@ordinatio/scheduling` 0.7.0 (now the required version). `bearerKeyOf` and the `ApiKeySettings` type are exported. `host.apiKeys.db()` must be the database your staff context uses, because keys are made through that one and looked up before the business is known.
|
package/README.md
CHANGED
|
@@ -440,6 +440,16 @@ Admins then get `GET /admin/api-keys`, `POST /admin/api-keys` (`{ name, access }
|
|
|
440
440
|
|
|
441
441
|
A tool sends `Authorization: Bearer osk_...` and the request runs as that business's admin, counted against the key's own rate limit. A request with a `READ` key is refused with 403 unless it is a `GET`, whatever the route. The calendar-connect routes (`/calendars/connect-google`, `/calendars/connect-outlook` and their callbacks) need a person at a browser, so they refuse every API key, `FULL` too; a route marks itself like that with `personOnly: true`. Public routes never look at a key. A revoked or unknown key is a 401. A request made with a key cannot manage keys, so a key cannot make more keys. A header that does not start `osk_` is left for your own sign-in. Rows a key writes name the key (`api-key:<id>`) as the person, so a column that must point at a real user needs your own handling. The key routes have no agent tools: an agent should never handle credentials.
|
|
442
442
|
|
|
443
|
+
## Gift certificates
|
|
444
|
+
|
|
445
|
+
Prepaid value a client holds and spends at booking. Turn it on with `host.giftCertificates: {}` (it needs the `GiftCertificate` and `GiftCertificateTransaction` tables from `@ordinatio/scheduling` 0.8.0); without it every gift certificate route answers 501.
|
|
446
|
+
|
|
447
|
+
Admins get `GET /admin/gift-certificates` (`?status=ACTIVE|VOID&limit=`), `POST /admin/gift-certificates` (`{ amountCents, currency?, expiresAt?, recipientName?, recipientEmail?, purchaserName?, purchaserEmail?, message?, paymentId?, notes? }`), `GET /admin/gift-certificates/[id]` (with its history), `POST /admin/gift-certificates/[id]/void` and `POST /admin/gift-certificates/[id]/restore` (`{ amountCents, appointmentId?, note? }`). Amounts are whole cents. Issuing with a `paymentId` already used returns the first certificate with 200 instead of 201, and writes no second "issued" entry (409 if the amount or currency differs), so a payment notice delivered twice makes one certificate and one record. A visitor's booking page can call `POST /gift-certificates/check` (`{ code, calendarId }`): it answers the balance, currency and expiry of a usable code, or `valid: false` with a reason (`void`, `expired`, `used_up`, or `not_found`, which is also the answer for a malformed code or another business's), never anything about the owner. It is rate limited like the other public booking routes; give it a stricter limit if your host allows one.
|
|
448
|
+
|
|
449
|
+
**Paying with a certificate.** `POST /appointments` takes a `giftCode`. A certificate that covers the whole price (or the deposit, for a type that takes one) books with no card: send no `paymentId`. If it covers only part, create the card payment first with `POST /payments/intent` and the same `giftCode`: it charges the rest, answers `giftAppliedCents`, and the booking then names that payment and the same code. When the certificate pays everything the intent answers 200 with `fullyCoveredByGift: true` and no payment to confirm. A code that cannot be used is refused with 400 and the same message whatever the reason. If the certificate cannot be spent after all (someone else spent it in the same moment), the booking is cancelled, any card payment is refunded, and the client gets `GIFT_UNAVAILABLE`. This release does not yet give money back to a certificate when a booking paid with one is cancelled; staff use the restore route.
|
|
450
|
+
|
|
451
|
+
A certificate's code spends like cash, so every answer that can carry one is sent with `Cache-Control: no-store`, the activity log records ids and amounts, never a code, and error logs have anything shaped like a code removed. **A read-only API key sees only the last four characters of each code (`…JKMN`, with `codeHidden: true`)**, so a reporting tool can read balances and history but cannot spend; a person and a full key see whole codes, since they resend them. Errors: 400 for a bad request (every problem listed), 404 for an unknown or other business's certificate (or a void one, when voiding), 409 when the state forbids it (void, used up, a repeat or too large a give-back, a different currency or payment amount). The routes have agent tools for list and read, and for issue, void and give back, which ask a person first; the public check has none.
|
|
452
|
+
|
|
443
453
|
## Agent tools
|
|
444
454
|
|
|
445
455
|
An AI agent can run scheduling through the same routes. Import the tool descriptions and hand them to any agent runner:
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ordinatio/scheduling-api",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.10.0",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"description": "HTTP API for @ordinatio/scheduling. Every handler takes a Request and returns a Response.",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
"sanitize-html": "^2.16.0"
|
|
12
12
|
},
|
|
13
13
|
"peerDependencies": {
|
|
14
|
-
"@ordinatio/scheduling": "^0.
|
|
14
|
+
"@ordinatio/scheduling": "^0.9.0"
|
|
15
15
|
},
|
|
16
16
|
"devDependencies": {
|
|
17
17
|
"@types/sanitize-html": "^2.13.0",
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"tsup": "^8.0.0",
|
|
20
20
|
"typescript": "5",
|
|
21
21
|
"vitest": "4.0.18",
|
|
22
|
-
"@ordinatio/scheduling": "0.
|
|
22
|
+
"@ordinatio/scheduling": "0.9.0"
|
|
23
23
|
},
|
|
24
24
|
"engines": {
|
|
25
25
|
"node": ">=22.0.0"
|
package/dist/agent/index.d.mts
DELETED
|
@@ -1,55 +0,0 @@
|
|
|
1
|
-
import { H as HttpMethod } from '../routes-mii9tsbA.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 };
|
package/dist/agent/index.d.ts
DELETED
|
@@ -1,55 +0,0 @@
|
|
|
1
|
-
import { H as HttpMethod } from '../routes-mii9tsbA.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 };
|