@ordinatio/scheduling-api 0.7.0 → 0.9.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 +8 -0
- package/README.md +16 -0
- package/dist/agent/index.d.mts +1 -1
- package/dist/agent/index.d.ts +1 -1
- package/dist/agent/index.js +159 -26
- package/dist/agent/index.mjs +159 -26
- package/dist/{chunk-IW6AN5WE.mjs → chunk-W3SY2DAU.mjs} +37 -1
- package/dist/index.d.mts +7 -4
- package/dist/index.d.ts +7 -4
- package/dist/index.js +667 -364
- package/dist/index.mjs +341 -71
- package/dist/{routes-LaFljBCF.d.mts → routes-h90wEQuD.d.mts} +25 -1
- package/dist/{routes-LaFljBCF.d.ts → routes-h90wEQuD.d.ts} +25 -1
- package/dist/schemas/index.d.mts +29 -1
- package/dist/schemas/index.d.ts +29 -1
- package/dist/schemas/index.js +40 -0
- package/dist/schemas/index.mjs +9 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.0 (prepared 2026-11-19)
|
|
4
|
+
|
|
5
|
+
- **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.
|
|
6
|
+
- **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.)
|
|
7
|
+
|
|
8
|
+
## 0.8.0 (prepared 2026-11-18)
|
|
9
|
+
|
|
10
|
+
- **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.
|
|
3
11
|
## 0.7.0 (prepared 2026-11-17)
|
|
4
12
|
|
|
5
13
|
- **New route: `GET /admin/brand/sending-domain?domain=...`.** Admins get the record-by-record check of a sending domain (found, missing, wrong or unknown, with the exact name and a plain sentence for each) so a setup screen can show what to fix. It is rate limited as a settings action and has no agent tool (it makes the server look up names under a domain the caller chooses). The host turns it on with `brand.checkSendingDomain` (pass the verifier's `check`); without it the route answers 501. A value that is not a domain answers 400 before any lookup. It changes nothing.
|
package/README.md
CHANGED
|
@@ -432,6 +432,22 @@ It returns `reply`, `opt-out`, `opt-in`, `delivery` or `ignored`; saving them is
|
|
|
432
432
|
For Twilio, pass the raw form body, the headers and the exact address Twilio calls:
|
|
433
433
|
`handleTwilioWebhook(rawBody, request.headers, { authToken, url: 'https://your.app/hooks/sms' })`.
|
|
434
434
|
|
|
435
|
+
## API keys for outside tools
|
|
436
|
+
|
|
437
|
+
Let an automation service, a script or an AI assistant act for one business without a person signing in. Switch it on with `host.apiKeys: { db: async () => db }`, where `db` is the database that holds the engine's `OrganizationApiKey` table (run its migration first). It must be the same database your staff context points at, because the key routes make keys through that one. Without `host.apiKeys` a Bearer key is ignored and the key routes answer 501.
|
|
438
|
+
|
|
439
|
+
Admins then get `GET /admin/api-keys`, `POST /admin/api-keys` (`{ name, access }`) and `DELETE /admin/api-keys/[id]`. `access` is `READ` (look things up only) or `FULL`. The secret, which starts `osk_`, is in the answer to `POST` once and cannot be read again; only a hash is stored. A business may have 25 live keys.
|
|
440
|
+
|
|
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
|
+
|
|
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
|
+
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). Spending a certificate at booking and paying the rest by card is not part of these routes yet. 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.
|
|
450
|
+
|
|
435
451
|
## Agent tools
|
|
436
452
|
|
|
437
453
|
An AI agent can run scheduling through the same routes. Import the tool descriptions and hand them to any agent runner:
|
package/dist/agent/index.d.mts
CHANGED
package/dist/agent/index.d.ts
CHANGED
package/dist/agent/index.js
CHANGED
|
@@ -1157,6 +1157,135 @@ var CALENDAR_TOOLS = [
|
|
|
1157
1157
|
}
|
|
1158
1158
|
];
|
|
1159
1159
|
|
|
1160
|
+
// src/agent/gift-certificate-tools.ts
|
|
1161
|
+
var CERTIFICATE_FIELDS = "id, code, status, currency, initialCents, balanceCents, expiresAt, recipientName, recipientEmail, purchaserName, purchaserEmail, message, notes, paymentId, createdByUserId, createdAt";
|
|
1162
|
+
var LINE_FIELDS = "id, seq, type, amountCents, balanceAfterCents, appointmentId, note, createdByUserId, createdAt";
|
|
1163
|
+
var NOT_ENABLED = "A server without gift certificates answers 501.";
|
|
1164
|
+
var ID3 = { name: "id", type: "string", required: true, description: "Gift certificate id" };
|
|
1165
|
+
var CODE_CARE = "The code in the answer spends like cash: give it only to the person it is for, and do not repeat it anywhere else. A read-only API key sees only the last four characters of each code.";
|
|
1166
|
+
var GIFT_CERTIFICATE_TOOLS = [
|
|
1167
|
+
{
|
|
1168
|
+
name: "scheduling_list_gift_certificates",
|
|
1169
|
+
module: "scheduling",
|
|
1170
|
+
method: "GET",
|
|
1171
|
+
route: "/admin/gift-certificates",
|
|
1172
|
+
auth: "session_cookie",
|
|
1173
|
+
description: "List the organization's gift certificates, newest first, with their balances.",
|
|
1174
|
+
params: [
|
|
1175
|
+
{ name: "status", type: "string", required: false, description: "Only this status", allowedValues: ["ACTIVE", "VOID"] },
|
|
1176
|
+
{ name: "limit", type: "number", required: false, description: "How many to return (default 100, at most 500)" }
|
|
1177
|
+
],
|
|
1178
|
+
example: { status: "ACTIVE" },
|
|
1179
|
+
responseShape: `{ certificates: [{ ${CERTIFICATE_FIELDS} }] }`,
|
|
1180
|
+
whenToUse: "To find a certificate id, see how much value is outstanding, or look up who a certificate was sold to.",
|
|
1181
|
+
pitfalls: [CODE_CARE, "status is ACTIVE or VOID only: a certificate that has expired or been used up is still ACTIVE here; read its expiresAt and balanceCents.", "There is no total and no paging: the newest 100 come back unless limit says more.", NOT_ENABLED, "Needs the scheduling switch to be on for the organization."],
|
|
1182
|
+
dataSensitivity: "critical",
|
|
1183
|
+
risk: "observe"
|
|
1184
|
+
},
|
|
1185
|
+
{
|
|
1186
|
+
name: "scheduling_get_gift_certificate",
|
|
1187
|
+
module: "scheduling",
|
|
1188
|
+
method: "GET",
|
|
1189
|
+
route: "/admin/gift-certificates/[id]",
|
|
1190
|
+
auth: "session_cookie",
|
|
1191
|
+
description: "Read one gift certificate with its history: the issue, every spend, every give-back and any void, in order.",
|
|
1192
|
+
params: [ID3],
|
|
1193
|
+
example: { id: "gc_1" },
|
|
1194
|
+
responseShape: `{ certificate: { ${CERTIFICATE_FIELDS} }, transactions: [{ ${LINE_FIELDS} }], truncated }`,
|
|
1195
|
+
whenToUse: 'To answer "what is left on this certificate" or "what was it spent on". Amounts are whole cents: 1250 is 12.50.',
|
|
1196
|
+
pitfalls: [CODE_CARE, "Spends have a negative amountCents and give-backs a positive one. truncated is true when the history has more than 1000 lines and only the first are shown.", NOT_ENABLED, "Needs the scheduling switch to be on for the organization."],
|
|
1197
|
+
dataSensitivity: "critical",
|
|
1198
|
+
risk: "observe"
|
|
1199
|
+
},
|
|
1200
|
+
{
|
|
1201
|
+
name: "scheduling_issue_gift_certificate",
|
|
1202
|
+
module: "scheduling",
|
|
1203
|
+
method: "POST",
|
|
1204
|
+
route: "/admin/gift-certificates",
|
|
1205
|
+
auth: "session_cookie",
|
|
1206
|
+
description: "Issue a gift certificate worth an amount, with a random code the holder types at booking.",
|
|
1207
|
+
params: [
|
|
1208
|
+
{ name: "amountCents", type: "number", required: true, description: "Value in whole cents, from 100 to 1000000: 5000 is 50.00" },
|
|
1209
|
+
{ name: "currency", type: "string", required: false, description: "Three-letter currency code, default usd. A certificate only pays a bill in its own currency." },
|
|
1210
|
+
{ name: "expiresAt", type: "string", required: false, description: "When it stops working, an ISO date or time in the future. Leave out for no expiry." },
|
|
1211
|
+
{ name: "recipientName", type: "string", required: false, description: "Who it is for" },
|
|
1212
|
+
{ name: "recipientEmail", type: "string", required: false, description: "Where to send it" },
|
|
1213
|
+
{ name: "purchaserName", type: "string", required: false, description: "Who bought it" },
|
|
1214
|
+
{ name: "purchaserEmail", type: "string", required: false, description: "The buyer's email" },
|
|
1215
|
+
{ name: "message", type: "string", required: false, description: "A note for the recipient, up to 500 characters" },
|
|
1216
|
+
{ name: "paymentId", type: "string", required: false, description: "The payment that bought it. A payment makes one certificate: asking again with the same id returns the first one." },
|
|
1217
|
+
{ name: "notes", type: "string", required: false, description: "A note for staff, up to 1000 characters" }
|
|
1218
|
+
],
|
|
1219
|
+
example: { amountCents: 5e3, recipientName: "Jane Smith", recipientEmail: "jane@example.com", message: "Happy birthday" },
|
|
1220
|
+
responseShape: `{ certificate: { ${CERTIFICATE_FIELDS} } }`,
|
|
1221
|
+
whenToUse: "When a certificate is sold at the counter, given as a gift or issued to make up for a problem. It works at once.",
|
|
1222
|
+
pitfalls: [
|
|
1223
|
+
CODE_CARE,
|
|
1224
|
+
"This creates value the business owes the holder: nothing is charged here. Take payment separately and pass its id as paymentId so a repeat cannot issue a second certificate.",
|
|
1225
|
+
"A paymentId already used for a different amount or currency is refused with 409. An amount outside 100 to 1000000 cents, a past expiry or an email that is not an address is refused with 400, with every problem listed.",
|
|
1226
|
+
NOT_ENABLED,
|
|
1227
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1228
|
+
],
|
|
1229
|
+
dataSensitivity: "critical",
|
|
1230
|
+
risk: "govern",
|
|
1231
|
+
requiresApproval: {
|
|
1232
|
+
action: "Issue a gift certificate",
|
|
1233
|
+
reason: "It creates spendable value that the business owes the holder, and the code in the answer can be spent by anyone who has it.",
|
|
1234
|
+
prompt: "Issue a gift certificate worth {amountCents} cents?"
|
|
1235
|
+
}
|
|
1236
|
+
},
|
|
1237
|
+
{
|
|
1238
|
+
name: "scheduling_void_gift_certificate",
|
|
1239
|
+
module: "scheduling",
|
|
1240
|
+
method: "POST",
|
|
1241
|
+
route: "/admin/gift-certificates/[id]/void",
|
|
1242
|
+
auth: "session_cookie",
|
|
1243
|
+
description: "Stop a gift certificate from being spent. Its balance and history stay on record.",
|
|
1244
|
+
params: [ID3],
|
|
1245
|
+
example: { id: "gc_1" },
|
|
1246
|
+
responseShape: "{ voided: true }",
|
|
1247
|
+
whenToUse: "When a certificate was issued by mistake, was lost or stolen, or the sale was refunded.",
|
|
1248
|
+
pitfalls: ["A void certificate cannot be spent or topped up, and cannot be made active again: issue a new one if the holder is owed value.", "Answers 404 for a certificate that does not exist, belongs to another business, or is already void.", NOT_ENABLED, "Needs the scheduling switch to be on for the organization."],
|
|
1249
|
+
dataSensitivity: "sensitive",
|
|
1250
|
+
risk: "govern",
|
|
1251
|
+
requiresApproval: {
|
|
1252
|
+
action: "Void a gift certificate",
|
|
1253
|
+
reason: "The holder can no longer spend it, and a voided certificate cannot be brought back.",
|
|
1254
|
+
prompt: "Void gift certificate {id}?"
|
|
1255
|
+
}
|
|
1256
|
+
},
|
|
1257
|
+
{
|
|
1258
|
+
name: "scheduling_restore_gift_certificate",
|
|
1259
|
+
module: "scheduling",
|
|
1260
|
+
method: "POST",
|
|
1261
|
+
route: "/admin/gift-certificates/[id]/restore",
|
|
1262
|
+
auth: "session_cookie",
|
|
1263
|
+
description: "Give value back to a gift certificate, for a cancelled or refunded booking or to correct a mistake.",
|
|
1264
|
+
params: [
|
|
1265
|
+
ID3,
|
|
1266
|
+
{ name: "amountCents", type: "number", required: true, description: "Value to give back in whole cents: 1250 is 12.50" },
|
|
1267
|
+
{ name: "appointmentId", type: "string", required: false, description: "The appointment the value was spent on. With it, no more than was spent on that appointment and not yet returned can come back." },
|
|
1268
|
+
{ name: "note", type: "string", required: false, description: "Why, up to 1000 characters" }
|
|
1269
|
+
],
|
|
1270
|
+
example: { id: "gc_1", amountCents: 2500, appointmentId: "appt_1", note: "Booking cancelled" },
|
|
1271
|
+
responseShape: "{ restored: { certificateId, transactionId, restoredCents, balanceCents } }",
|
|
1272
|
+
whenToUse: "After a booking paid with a certificate is cancelled or refunded, or to put right a wrong spend. Give the appointment whenever there is one.",
|
|
1273
|
+
pitfalls: [
|
|
1274
|
+
"Without appointmentId the only limit is the amount the certificate was issued for, so a correction cannot go above it.",
|
|
1275
|
+
"A repeated give-back for the same appointment returns nothing more and is refused with 409. A void certificate is refused with 409. An expired certificate takes the value back but its expiry is not extended.",
|
|
1276
|
+
NOT_ENABLED,
|
|
1277
|
+
"Needs the scheduling switch to be on for the organization."
|
|
1278
|
+
],
|
|
1279
|
+
dataSensitivity: "sensitive",
|
|
1280
|
+
risk: "govern",
|
|
1281
|
+
requiresApproval: {
|
|
1282
|
+
action: "Give value back to a gift certificate",
|
|
1283
|
+
reason: "It adds spendable value to the certificate.",
|
|
1284
|
+
prompt: "Give {amountCents} cents back to gift certificate {id}?"
|
|
1285
|
+
}
|
|
1286
|
+
}
|
|
1287
|
+
];
|
|
1288
|
+
|
|
1160
1289
|
// src/agent/policy-tools.ts
|
|
1161
1290
|
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
1291
|
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).";
|
|
@@ -1225,7 +1354,7 @@ var POLICY_TOOLS = [
|
|
|
1225
1354
|
|
|
1226
1355
|
// src/agent/privacy-tools.ts
|
|
1227
1356
|
var COUNTS = "{ appointments, notifications, waitlistEntries, packagePurchases, recurringSeries, webhookDeliveries }";
|
|
1228
|
-
var
|
|
1357
|
+
var NOT_ENABLED2 = "A server without data export and erasure answers 501.";
|
|
1229
1358
|
var WHO = "Name the person with email, clientId or both. A client id also stands for every address that client has booked with.";
|
|
1230
1359
|
var SUBJECT_PARAMS = [
|
|
1231
1360
|
{ name: "email", type: "string", required: false, description: "The person's email address: one valid address, up to 254 characters, in any letter case" },
|
|
@@ -1249,7 +1378,7 @@ var PRIVACY_TOOLS = [
|
|
|
1249
1378
|
"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
1379
|
"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
1380
|
"The request is recorded with only a digest of the address, never the address itself.",
|
|
1252
|
-
|
|
1381
|
+
NOT_ENABLED2,
|
|
1253
1382
|
"Needs the scheduling switch to be on for the organization."
|
|
1254
1383
|
],
|
|
1255
1384
|
dataSensitivity: "critical",
|
|
@@ -1281,7 +1410,7 @@ var PRIVACY_TOOLS = [
|
|
|
1281
1410
|
"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
1411
|
"warnings notes sessions left on an active package: after erasure it can no longer be matched to the person.",
|
|
1283
1412
|
"Copies already sent elsewhere, such as emails, webhook receivers or backups outside this system, are not recalled.",
|
|
1284
|
-
|
|
1413
|
+
NOT_ENABLED2,
|
|
1285
1414
|
"Needs the scheduling switch to be on for the organization."
|
|
1286
1415
|
],
|
|
1287
1416
|
dataSensitivity: "critical",
|
|
@@ -1308,7 +1437,7 @@ var PRIVACY_TOOLS = [
|
|
|
1308
1437
|
whenToUse: "To show that a request was handled, or to see who has been exporting or erasing data.",
|
|
1309
1438
|
pitfalls: [
|
|
1310
1439
|
"kind is EXPORT or ERASE. The log holds counts and who asked, never the person's name or address.",
|
|
1311
|
-
|
|
1440
|
+
NOT_ENABLED2,
|
|
1312
1441
|
"Needs the scheduling switch to be on for the organization."
|
|
1313
1442
|
],
|
|
1314
1443
|
dataSensitivity: "internal",
|
|
@@ -1320,7 +1449,7 @@ var PRIVACY_TOOLS = [
|
|
|
1320
1449
|
var SUMMARY_FIELDS = "id, name, slug, description, isActive, updatedAt";
|
|
1321
1450
|
var FORM_FIELDS = "id, name, slug, description, isActive, questions, rules, fallback, createdAt, updatedAt";
|
|
1322
1451
|
var FORM_ID = { name: "id", type: "string", required: true, description: "Routing form id" };
|
|
1323
|
-
var
|
|
1452
|
+
var NOT_ENABLED3 = "A server without routing forms answers 501.";
|
|
1324
1453
|
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
1454
|
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
1455
|
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.`;
|
|
@@ -1337,7 +1466,7 @@ var ROUTING_TOOLS = [
|
|
|
1337
1466
|
example: {},
|
|
1338
1467
|
responseShape: `{ forms: [{ ${SUMMARY_FIELDS} }] }`,
|
|
1339
1468
|
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.",
|
|
1469
|
+
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_ENABLED3, "Needs the scheduling switch to be on for the organization."],
|
|
1341
1470
|
dataSensitivity: "internal",
|
|
1342
1471
|
risk: "observe"
|
|
1343
1472
|
},
|
|
@@ -1352,7 +1481,7 @@ var ROUTING_TOOLS = [
|
|
|
1352
1481
|
example: { id: "form_1" },
|
|
1353
1482
|
responseShape: `{ form: { ${FORM_FIELDS} } }`,
|
|
1354
1483
|
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.",
|
|
1484
|
+
pitfalls: ["A form of another organization is a plain 404.", NOT_ENABLED3, "Needs the scheduling switch to be on for the organization."],
|
|
1356
1485
|
dataSensitivity: "internal",
|
|
1357
1486
|
risk: "observe"
|
|
1358
1487
|
},
|
|
@@ -1386,7 +1515,7 @@ var ROUTING_TOOLS = [
|
|
|
1386
1515
|
"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
1516
|
"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
1517
|
"At least one rule is required.",
|
|
1389
|
-
|
|
1518
|
+
NOT_ENABLED3,
|
|
1390
1519
|
"Needs the scheduling switch to be on for the organization."
|
|
1391
1520
|
],
|
|
1392
1521
|
dataSensitivity: "internal",
|
|
@@ -1422,7 +1551,7 @@ var ROUTING_TOOLS = [
|
|
|
1422
1551
|
DETAILS,
|
|
1423
1552
|
"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
1553
|
"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
|
-
|
|
1554
|
+
NOT_ENABLED3,
|
|
1426
1555
|
"Needs the scheduling switch to be on for the organization."
|
|
1427
1556
|
],
|
|
1428
1557
|
dataSensitivity: "internal",
|
|
@@ -1444,7 +1573,7 @@ var ROUTING_TOOLS = [
|
|
|
1444
1573
|
example: { id: "form_1" },
|
|
1445
1574
|
responseShape: "{ success: true }",
|
|
1446
1575
|
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.",
|
|
1576
|
+
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_ENABLED3, "Needs the scheduling switch to be on for the organization."],
|
|
1448
1577
|
dataSensitivity: "internal",
|
|
1449
1578
|
risk: "act",
|
|
1450
1579
|
requiresApproval: {
|
|
@@ -1473,7 +1602,7 @@ var ROUTING_TOOLS = [
|
|
|
1473
1602
|
"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
1603
|
"Answers that do not fit the form are refused with 400 and details.",
|
|
1475
1604
|
"It changes nothing, but it is a POST, so it asks first.",
|
|
1476
|
-
|
|
1605
|
+
NOT_ENABLED3
|
|
1477
1606
|
],
|
|
1478
1607
|
dataSensitivity: "none",
|
|
1479
1608
|
risk: "act",
|
|
@@ -1999,7 +2128,7 @@ var SETTINGS_TOOLS = [
|
|
|
1999
2128
|
];
|
|
2000
2129
|
|
|
2001
2130
|
// src/agent/type-tools.ts
|
|
2002
|
-
var
|
|
2131
|
+
var ID4 = { name: "id", type: "string", required: true, description: "Appointment type id" };
|
|
2003
2132
|
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";
|
|
2004
2133
|
var LOCATION_TYPES = ["IN_PERSON", "TRAVEL_TO_CLIENT", "VIRTUAL", "PHONE"];
|
|
2005
2134
|
var STRATEGIES = ["NONE", "ROUND_ROBIN", "LOAD_BALANCED"];
|
|
@@ -2083,7 +2212,7 @@ var TYPE_TOOLS = [
|
|
|
2083
2212
|
auth: "session_cookie",
|
|
2084
2213
|
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.",
|
|
2085
2214
|
params: [
|
|
2086
|
-
|
|
2215
|
+
ID4,
|
|
2087
2216
|
...typeFields(true),
|
|
2088
2217
|
{ name: "isActive", type: "boolean", required: false, description: "false switches the type off so it can no longer be booked, true switches it back on" }
|
|
2089
2218
|
],
|
|
@@ -2113,7 +2242,7 @@ var TYPE_TOOLS = [
|
|
|
2113
2242
|
route: "/admin/types/[id]",
|
|
2114
2243
|
auth: "session_cookie",
|
|
2115
2244
|
description: "Delete an appointment type that no appointment has ever used, and release its short booking address.",
|
|
2116
|
-
params: [
|
|
2245
|
+
params: [ID4],
|
|
2117
2246
|
example: { id: "type_1" },
|
|
2118
2247
|
responseShape: "{ success: true }",
|
|
2119
2248
|
whenToUse: "Only to remove a type that was created by mistake and never booked.",
|
|
@@ -2136,7 +2265,7 @@ var TYPE_TOOLS = [
|
|
|
2136
2265
|
route: "/admin/types/[id]/round-robin-state",
|
|
2137
2266
|
auth: "session_cookie",
|
|
2138
2267
|
description: "Restart the turn-taking of a team appointment type, so the next booking goes to whoever the rotation starts with.",
|
|
2139
|
-
params: [
|
|
2268
|
+
params: [ID4],
|
|
2140
2269
|
example: { id: "type_1" },
|
|
2141
2270
|
responseShape: "{ success: true }",
|
|
2142
2271
|
whenToUse: "After a staff member joins or leaves a team type and the rotation should begin again.",
|
|
@@ -2156,7 +2285,7 @@ var TYPE_TOOLS = [
|
|
|
2156
2285
|
|
|
2157
2286
|
// src/agent/waitlist-tools.ts
|
|
2158
2287
|
var ENTRY_FIELDS = "id, typeId, calendarId, day, slotStart, clientName, clientEmail, clientPhone, status, offerSlotStart, offerExpiresAt, createdAt";
|
|
2159
|
-
var
|
|
2288
|
+
var NOT_ENABLED4 = "A server without the waitlist answers 501.";
|
|
2160
2289
|
var WAITLIST_TOOLS = [
|
|
2161
2290
|
{
|
|
2162
2291
|
name: "scheduling_list_waitlist",
|
|
@@ -2179,7 +2308,7 @@ var WAITLIST_TOOLS = [
|
|
|
2179
2308
|
"The client's private link token is never part of the answer.",
|
|
2180
2309
|
"The answer carries names, email addresses and phone numbers.",
|
|
2181
2310
|
"Any other status value is refused with 400.",
|
|
2182
|
-
|
|
2311
|
+
NOT_ENABLED4,
|
|
2183
2312
|
"Needs the scheduling switch to be on for the organization."
|
|
2184
2313
|
],
|
|
2185
2314
|
dataSensitivity: "sensitive",
|
|
@@ -2201,7 +2330,7 @@ var WAITLIST_TOOLS = [
|
|
|
2201
2330
|
"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.",
|
|
2202
2331
|
"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.",
|
|
2203
2332
|
"An entry of another organization is a plain 404.",
|
|
2204
|
-
|
|
2333
|
+
NOT_ENABLED4,
|
|
2205
2334
|
"Needs the scheduling switch to be on for the organization."
|
|
2206
2335
|
],
|
|
2207
2336
|
dataSensitivity: "sensitive",
|
|
@@ -2218,7 +2347,7 @@ var WAITLIST_TOOLS = [
|
|
|
2218
2347
|
var ENDPOINT_FIELDS = "id, url, description, eventTypes, isActive, createdAt";
|
|
2219
2348
|
var DELIVERY_FIELDS = "id, endpointId, eventId, eventType, status, attempts, nextAttemptAt, lastStatusCode, lastError, deliveredAt, createdAt, attemptLog: [{ attemptNumber, statusCode, error, durationMs, createdAt }]";
|
|
2220
2349
|
var ENDPOINT_ID = { name: "id", type: "string", required: true, description: "Webhook endpoint id" };
|
|
2221
|
-
var
|
|
2350
|
+
var NOT_ENABLED5 = "A server without webhooks answers 501.";
|
|
2222
2351
|
var WEBHOOK_TOOLS = [
|
|
2223
2352
|
{
|
|
2224
2353
|
name: "scheduling_list_webhooks",
|
|
@@ -2231,7 +2360,7 @@ var WEBHOOK_TOOLS = [
|
|
|
2231
2360
|
example: {},
|
|
2232
2361
|
responseShape: `{ endpoints: [{ ${ENDPOINT_FIELDS} }], eventTypes }`,
|
|
2233
2362
|
whenToUse: "To see what outside systems are told about bookings, to find an endpoint id, or to learn the event names.",
|
|
2234
|
-
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.",
|
|
2363
|
+
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_ENABLED5, "Needs the scheduling switch to be on for the organization."],
|
|
2235
2364
|
dataSensitivity: "internal",
|
|
2236
2365
|
risk: "observe"
|
|
2237
2366
|
},
|
|
@@ -2254,7 +2383,7 @@ var WEBHOOK_TOOLS = [
|
|
|
2254
2383
|
"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.",
|
|
2255
2384
|
"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.",
|
|
2256
2385
|
"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).",
|
|
2257
|
-
|
|
2386
|
+
NOT_ENABLED5,
|
|
2258
2387
|
"Needs the scheduling switch to be on for the organization."
|
|
2259
2388
|
],
|
|
2260
2389
|
dataSensitivity: "critical",
|
|
@@ -2276,7 +2405,7 @@ var WEBHOOK_TOOLS = [
|
|
|
2276
2405
|
example: { id: "hook_1" },
|
|
2277
2406
|
responseShape: "{ success: true }",
|
|
2278
2407
|
whenToUse: "When an outside system should stop being told about bookings. There is no way to switch one off without deleting it.",
|
|
2279
|
-
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.",
|
|
2408
|
+
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_ENABLED5, "Needs the scheduling switch to be on for the organization."],
|
|
2280
2409
|
dataSensitivity: "internal",
|
|
2281
2410
|
risk: "act",
|
|
2282
2411
|
requiresApproval: {
|
|
@@ -2300,7 +2429,7 @@ var WEBHOOK_TOOLS = [
|
|
|
2300
2429
|
"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.",
|
|
2301
2430
|
"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.",
|
|
2302
2431
|
"An endpoint of another organization is a plain 404.",
|
|
2303
|
-
|
|
2432
|
+
NOT_ENABLED5,
|
|
2304
2433
|
"Needs the scheduling switch to be on for the organization."
|
|
2305
2434
|
],
|
|
2306
2435
|
dataSensitivity: "internal",
|
|
@@ -2327,7 +2456,7 @@ var WEBHOOK_TOOLS = [
|
|
|
2327
2456
|
example: { id: "hook_1", status: "DEAD_LETTER" },
|
|
2328
2457
|
responseShape: `{ deliveries: [{ ${DELIVERY_FIELDS} }], total, hasMore }`,
|
|
2329
2458
|
whenToUse: "To find out why an outside system missed events, and to find the id of a DEAD_LETTER delivery to retry.",
|
|
2330
|
-
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.",
|
|
2459
|
+
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_ENABLED5, "Needs the scheduling switch to be on for the organization."],
|
|
2331
2460
|
dataSensitivity: "internal",
|
|
2332
2461
|
risk: "observe"
|
|
2333
2462
|
},
|
|
@@ -2346,7 +2475,7 @@ var WEBHOOK_TOOLS = [
|
|
|
2346
2475
|
"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.",
|
|
2347
2476
|
"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.",
|
|
2348
2477
|
"The event is sent again as it was first made, so the receiver may see an event it partly processed before.",
|
|
2349
|
-
|
|
2478
|
+
NOT_ENABLED5,
|
|
2350
2479
|
"Needs the scheduling switch to be on for the organization."
|
|
2351
2480
|
],
|
|
2352
2481
|
dataSensitivity: "internal",
|
|
@@ -2361,7 +2490,11 @@ var WEBHOOK_TOOLS = [
|
|
|
2361
2490
|
|
|
2362
2491
|
// src/agent/coverage.ts
|
|
2363
2492
|
var SCHEDULING_AGENT_EXCLUDED = {
|
|
2493
|
+
"GET /admin/api-keys": "Lists credentials. Agents do not handle API keys; the owner manages them in the dashboard.",
|
|
2494
|
+
"POST /admin/api-keys": "Makes a credential whose secret would be shown in the agent's own transcript. The owner makes keys in the dashboard.",
|
|
2495
|
+
"DELETE /admin/api-keys/[id]": "Credential management is left to the owner in the dashboard, not to an agent.",
|
|
2364
2496
|
"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.",
|
|
2497
|
+
"POST /gift-certificates/check": "A visitor checking the balance of a code they hold, from the public booking page. It changes nothing but is a POST, and only GET tools run without approval; staff read a certificate with the get tool.",
|
|
2365
2498
|
"POST /waitlist": "A client joining the waitlist for themselves; the answer holds their own private link token, which an agent should never be handed.",
|
|
2366
2499
|
"DELETE /waitlist": "A client leaving the waitlist from their own private link; staff remove an entry with the remove-waitlist-entry tool.",
|
|
2367
2500
|
"GET /waitlist/offer": "A client reading their own offer from a private link token.",
|
|
@@ -2391,7 +2524,7 @@ var SCHEDULING_AGENT_EXCLUDED = {
|
|
|
2391
2524
|
var SCHEDULING_AGENT_PENDING = [];
|
|
2392
2525
|
|
|
2393
2526
|
// src/agent/index.ts
|
|
2394
|
-
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];
|
|
2527
|
+
var SCHEDULING_AGENT_TOOLS = [...APPOINTMENT_TOOLS, ...CALENDAR_TOOLS, ...TYPE_TOOLS, ...AVAILABILITY_TOOLS, ...SERIES_TOOLS, ...SETTINGS_TOOLS, ...POLICY_TOOLS, ...BILLING_TOOLS, ...GIFT_CERTIFICATE_TOOLS, ...WEBHOOK_TOOLS, ...ROUTING_TOOLS, ...WAITLIST_TOOLS, ...PRIVACY_TOOLS, ...ANALYTICS_TOOLS];
|
|
2395
2528
|
function createSchedulingAgentTools(options = {}) {
|
|
2396
2529
|
const base = (options.basePath ?? "/api/scheduling").replace(/\/+$/, "");
|
|
2397
2530
|
return SCHEDULING_AGENT_TOOLS.filter((tool) => !options.readOnly || tool.method === "GET").map(({ route, ...tool }) => ({
|