@ordinatio/scheduling-api 0.6.0 → 0.8.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,20 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.8.0 (prepared 2026-11-18)
4
+
5
+ - **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.
6
+ ## 0.7.0 (prepared 2026-11-17)
7
+
8
+ - **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.
9
+ - **New: check a business's sending domain.** `createSendingDomainVerifier({ records, resolver })` looks up the SPF, DKIM and DMARC records a mail provider asks for and reports each as `found`, `missing`, `wrong` or `unknown`, with a plain sentence to act on. `verifier.isSendingDomainVerified` fits the host's `brand.isSendingDomainVerified`, `verifier.check(domain)` feeds a setup screen, and `verifier.instructions(domain)` lists what to publish. `records` may be a function of the domain for providers that issue a token per domain. It works with any mail provider and any DNS lookup (`node:dns/promises` fits). `checkSendingDomain`, `normalizeSendingDomain` and the record and result types are exported too.
10
+ - **New: `createTextSettingsResolver`, so a business's saved text settings send real texts.** `createTextSettingsResolver({ db, telnyx?, twilio? })` returns the `resolve` function for `createPerBusinessSmsAdapter`: it reads the business's saved provider and number and builds a Telnyx or Twilio sender with the host's own account. A business with no settings, with texting paused (`enabled: false`), or that chose a provider the host gave no account for gets no sender, so its texts are skipped, never sent from another number. A missing or empty key, or a stored number the sender refuses, skips only that business and is logged. The router keeps each business's sender for `adapterTtlMs` (5 minutes by default), so **pausing texting or changing a number takes up to that long to reach every worker**: use a shorter `adapterTtlMs` where a pause must be quick, or call `forget(organizationId)` on the worker that handled the change. The host's keys are passed in once and never stored or logged by the package.
11
+ - **New: routes for a business's text-message settings.** `GET`, `PUT` and `DELETE /admin/text-settings` (admins) read, save and remove the provider (`TELNYX` or `TWILIO`) and sending number, with the agent tools `scheduling_get_text_settings`, `scheduling_save_text_settings` and `scheduling_remove_text_settings` (save and remove need approval). The host turns them on with `host.textMessages` (optionally listing the `providers` it has accounts for); without it they answer 501. A save that breaks a rule answers 400 with every problem at once. The activity log records the provider and whether texting is on, never the number. Needs the `OrganizationTextSettings` table from `@ordinatio/scheduling` 0.6.1.
12
+ - **New: a number and provider per business.** `createPerBusinessSmsAdapter({ resolve })` sends each text through the adapter you return for that business (build it with `createTelnyxSmsAdapter` or `createTwilioSmsAdapter`). A message only ever goes through its own business's adapter; one that names no business is skipped with a reason, never sent from another number. An adapter is reused for 5 minutes (`adapterTtlMs`) and a business with no number is rechecked after 1 minute (`noNumberTtlMs`), so a new number starts working soon in every worker; `forget(organizationId)` drops it at once. It needs `@ordinatio/scheduling` 0.6.1 or newer (now the required version) and the sender run with `processPendingNotifications(..., { organization: true })`.
13
+ - **New: a ready-made Twilio text-message adapter and webhook handler, so a business can use Twilio or Telnyx.** `createTwilioSmsAdapter({ accountSid, authToken, from, messagingServiceSid })` and `handleTwilioWebhook(rawBody, headers, { authToken, url })` behave exactly like the Telnyx ones: the adapter sends only the SMS channel, skips bad numbers, empty messages and opted-out recipients (Twilio code 21610), and throws `SmsSendError` (`retryable`, `outcomeUnknown`); the webhook handler checks Twilio's signature (the exact public `url` you gave Twilio is part of what is signed; Twilio sends no timestamp, so there is no age check) and returns the same events: `reply`, `opt-out`, `opt-in`, `delivery`, `ignored`. The shared parts are exported too: `SmsSendError` (`TelnyxSendError` is the same class; an error's `name` is now `SmsSendError`), `classifyReply`, and the `SmsInboundEvent` / `SmsWebhookResult` / `WebhookHeaders` types. Not yet tried against a live Twilio account.
14
+ - **New: incoming Telnyx webhooks.** `handleTelnyxWebhook(rawBody, headers, { publicKey })` checks the Ed25519 signature (and refuses a timestamp more than five minutes old), then returns one plain event: `reply` (a client texted back), `opt-out` (STOP, STOPALL, UNSUBSCRIBE, END, QUIT as the whole message; CANCEL and YES stay replies because clients use them about appointments), `opt-in` (START, UNSTOP), `delivery` (`delivered` or `failed`, with Telnyx's error code) or `ignored`. A bad signature answers `401`, a malformed event `400`. It stores nothing: the host saves replies and remembers opt-outs. Headers can be a plain object or a web `Headers`. Pass the raw body exactly as received; a re-serialized body fails the signature. `verifyTelnyxSignature` is exported too. Not yet tried against a live Telnyx account.
15
+ - **New: a ready-made Telnyx text-message adapter.** `createTelnyxSmsAdapter({ apiKey, from, messagingProfileId })` is a `NotificationAdapter` that sends the SMS channel through Telnyx and skips everything else, so it can sit beside an email adapter. Give it a sending number, a messaging profile, or both. Numbers are read in international format; ten US digits get +1. A number that cannot be valid, an empty message, and a recipient who has opted out are skipped (nothing is sent, retrying cannot help). A reply of 2xx counts as sent, with or without a message id. A timeout (including a stalled reply), network failure, rate limit or server error throws a `TelnyxSendError` with `retryable: true`; its `outcomeUnknown` is `true` when the text may already have been sent (timeout, network, server error), because Telnyx has no idempotency key and a retry can send it twice. Any other refusal throws it with `retryable: false`. The key is trimmed (a pasted trailing newline is the usual cause of "invalid key") and never appears in an error. It passes `checkNotificationContract`. Not yet tested against a live Telnyx account: the opt-out code (40300) and response shape follow Telnyx's documentation. `normalizePhoneNumber` and the `TelnyxSmsConfig` type are exported too.
16
+ - **New: a ready-made Microsoft Outlook calendar sync.** `createOutlookCalendarSync(config, hooks)` returns `{ adapter, pull }`. `adapter` is the `CalendarSyncAdapter` for `SchedulingHost.calendarSync`: it writes each appointment to the person's connected Outlook calendar (one event per appointment, updated when the appointment moves) and removes the event when the appointment is cancelled; an event already gone from Outlook counts as removed. `pull(calendarId)` reads changes made in Outlook back in, using Microsoft's delta query: an Outlook event that is not an appointment blocks that time as a "Blocked" appointment (never offered for booking), a moved appointment follows its event, and a deleted event cancels the appointment through your `hooks.cancelAppointment`. Run `pull` on a schedule for each connected calendar. `config` takes your Azure app's `clientId` and `clientSecret` and the database; access tokens are refreshed and the rotated refresh token is saved. A calendar whose refresh is refused is skipped until the person reconnects. An expired delta link starts one full sync; a second refusal on that fresh start is thrown, not retried. Also: the first pull of each month starts a new year-long window; a change your hooks could not handle stops the pull before its place is saved, so the next run sees it again (`onAppointmentMoved` can therefore run more than once for one change); a "Blocked" appointment is never written to or deleted from Outlook, because its event is the person's own; delta links are only followed when they point at Microsoft Graph; and run one pull at a time per calendar. `db` must be the database of the one organization whose calendars are synced: no organization check is made, so a host with a database per organization builds one sync per organization.
17
+
3
18
  ## 0.6.0 (prepared 2026-11-13)
4
19
 
5
20
  - **New route: `GET /calendars/active`.** The active calendars the signed-in person may see, as a short list (`id`, `name`, `slug`, `staffName`) for pickers. Any member of the organization may ask, whatever their role, and the "scheduling is switched on" setting is not checked. Calendars outside the person's groups are left out, and the list never reaches beyond their organization. It is counted against the person under `admin-calendars-list`, the same name `GET /admin/calendars` uses. A host that served this list from its own route can serve it from here instead.
package/README.md CHANGED
@@ -226,7 +226,7 @@ that your user can create databases in.
226
226
  | `appUrl()` | The web address of your server. Booking needs it to build links in messages. | none: booking answers 500 |
227
227
  | `staff` | Who is signed in. `createBearerStaffResolver` reads a bearer token; `createStaffContext` builds the person for your own sign-in. | nobody: staff routes answer 401 |
228
228
  | `payments` | Charges, verifies and refunds payments. | none: a type that needs payment cannot be booked |
229
- | `calendarSync` | Keeps Google or Outlook in step. | nothing is synced |
229
+ | `calendarSync` | Keeps Google or Outlook in step. `createOutlookCalendarSync` is ready-made for Outlook. | nothing is synced |
230
230
  | `rateLimit` | Counts requests, by caller address. Return a response (normally 429) to stop one. Your server must set the address from the connection (see `createNodeListener`). | in-memory, per process |
231
231
  | `secureCookies()` | Whether the short-lived sign-in cookies travel only over https. | yes: on plain http the cookies do not stick |
232
232
  | `cache`, `availabilityCache` | Stored answers. | in-memory, per process |
@@ -260,6 +260,39 @@ README explains the retry schedule and how a receiver checks the signature. The
260
260
  `appointment.rescheduled`, `appointment.cancelled`, `appointment.no_show` and `waitlist.offered`; `reminder.sent` is sent when
261
261
  the worker that sends reminders passes `webhooks: true` to `processPendingNotifications`.
262
262
 
263
+ ## Sending domain
264
+
265
+ A business can send booking emails from its own address (`fromEmail` in the brand) only after the domain is confirmed.
266
+ `createSendingDomainVerifier({ records, resolver })` does the confirming. Put its `isSendingDomainVerified` in the host's `brand` member. `records` lists what your mail provider asks a
267
+ business to publish at its domain host (SPF, DKIM, DMARC), or is a function of the domain when the provider issues a token per domain; `resolver` is any object with `resolveTxt` and `resolveCname`, and
268
+ `node:dns/promises` fits as it is.
269
+
270
+ ```ts
271
+ import { promises as dns } from 'node:dns';
272
+ import { createSendingDomainVerifier } from '@ordinatio/scheduling-api';
273
+
274
+ const verifier = createSendingDomainVerifier({
275
+ resolver: dns,
276
+ records: [
277
+ { purpose: 'spf', type: 'TXT', name: '@', value: 'include:spf.mail.example', match: 'contains' },
278
+ { purpose: 'dkim', type: 'CNAME', name: 's1._domainkey', value: 's1.dkim.mail.example' },
279
+ { purpose: 'dmarc', type: 'TXT', name: '_dmarc', value: 'v=DMARC1; p=none', required: false },
280
+ ],
281
+ });
282
+
283
+ verifier.instructions('mail.acme.example'); // each record with the full name to publish at
284
+ await verifier.check('mail.acme.example'); // { verified, records: [{ status, message, ... }] }
285
+ // In the host: brand: { isSendingDomainVerified: verifier.isSendingDomainVerified, checkSendingDomain: verifier.check }
286
+ ```
287
+
288
+ With `checkSendingDomain` set, `GET /admin/brand/sending-domain?domain=mail.acme.example` (admins) returns `{ check }` for a setup screen. It is rate limited as a settings action and has no agent tool, because it makes your resolver look up names under a domain the caller chooses. It answers 400 for something that is not a domain and 501 when the host did not set `checkSendingDomain`.
289
+
290
+ Each record comes back `found`, `missing`, `wrong` or `unknown`, with a sentence a business owner can act on. A lookup that
291
+ fails is `unknown` and leaves the domain unverified; the check never throws. A record with `required: false` never blocks, and a
292
+ list with no required record never verifies. A `contains` match (for SPF) needs the wanted entry as a whole term. The package does not talk to any mail provider: the record values are the host's to supply.
293
+ Records that are the same for every domain prove only that the provider was set up at that domain, not who is claiming it; where several
294
+ businesses share one provider, use the function form with a token that belongs to the claiming organization.
295
+
263
296
  ## Waitlist
264
297
 
265
298
  Set `waitlist: {}` on the host to let clients wait for a full slot or day. A cancelled, rejected or moved booking offers
@@ -344,6 +377,69 @@ does not end up in access logs.
344
377
  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
378
  the host's activity feed with counts only. Without `privacy` on the host the routes answer 501.
346
379
 
380
+ ## Text messages (Telnyx or Twilio)
381
+
382
+ Pick a provider per business: `createTelnyxSmsAdapter` or `createTwilioSmsAdapter` (same shape; Twilio takes `accountSid`, `authToken` and a `from` number or `messagingServiceSid`). Their webhook handlers, `handleTelnyxWebhook` and `handleTwilioWebhook`, return the same events. `createTelnyxSmsAdapter` sends the SMS channel through Telnyx. Pass your own key and sending number:
383
+
384
+ ```ts
385
+ import { createTelnyxSmsAdapter } from '@ordinatio/scheduling-api';
386
+
387
+ const sms = createTelnyxSmsAdapter({
388
+ apiKey: process.env.TELNYX_API_KEY!,
389
+ from: '+13135550100', // your Telnyx number
390
+ // messagingProfileId: '...', // or use a profile instead of, or with, a number
391
+ });
392
+ ```
393
+
394
+ It is a `NotificationAdapter`, so use it wherever the engine takes one. It skips email, bad numbers, empty messages and
395
+ people who opted out (STOP). A timeout, rate limit or server error throws a `TelnyxSendError` whose `retryable` is `true`;
396
+ when its `outcomeUnknown` is also `true` the text may already have gone out, so retrying can send it twice.
397
+ Your number must be registered for US text messaging (10DLC) before carriers will deliver.
398
+
399
+ Each business can choose its own provider and number. Switch it on with `host.textMessages: {}` (or `{ providers: ['TELNYX'] }` to offer fewer): admins then get `GET`, `PUT` and `DELETE /admin/text-settings`, with agent tools to read, save and remove. It stores only the provider and the number, never keys: your server holds the provider accounts. Run the engine's `OrganizationTextSettings` migration first. Without `host.textMessages` the routes answer 501.
400
+
401
+ To give each business its own number or provider, wrap the adapters in a router and run the sender with `organization: true`. A business with no number, and a message that names no business, are skipped (never sent from another number):
402
+
403
+ ```ts
404
+ import { createPerBusinessSmsAdapter, createTextSettingsResolver } from '@ordinatio/scheduling-api';
405
+
406
+ const sms = createPerBusinessSmsAdapter({
407
+ // Looks up each business's saved provider and number and builds its sender with YOUR provider accounts.
408
+ resolve: createTextSettingsResolver({
409
+ db: (organizationId) => dbForOrganization(organizationId),
410
+ telnyx: { apiKey: process.env.TELNYX_API_KEY! },
411
+ twilio: { accountSid: process.env.TWILIO_ACCOUNT_SID!, authToken: process.env.TWILIO_AUTH_TOKEN! },
412
+ }),
413
+ });
414
+ // processPendingNotifications and adaptersToCallbacks come from '@ordinatio/scheduling'
415
+ const { sendNotification } = adaptersToCallbacks({ notifications: sms, payments: yourPaymentAdapter });
416
+ await processPendingNotifications(db, sendNotification!, { organization: true });
417
+ ```
418
+
419
+ A business with no saved settings, with texting paused, or that chose a provider you gave no account for, sends nothing (its texts are skipped, not sent from another number). Leave out `telnyx` or `twilio` if you have no account with that provider. The router keeps each business's sender for 5 minutes (`adapterTtlMs`), so a pause or a new number takes up to that long to reach every worker; set a shorter `adapterTtlMs` where a pause must be quick.
420
+
421
+ Point your Telnyx messaging profile's webhook at a route of yours and pass the raw body to `handleTelnyxWebhook`:
422
+
423
+ ```ts
424
+ // In a Fetch-style route: const rawBody = await request.text();
425
+ const result = handleTelnyxWebhook(rawBody, request.headers, { publicKey: process.env.TELNYX_PUBLIC_KEY! });
426
+ if (!result.ok) return new Response(result.reason, { status: result.status });
427
+ if (result.event.type === 'opt-out') await stopTexting(result.event.from); // you store it
428
+ ```
429
+
430
+ It returns `reply`, `opt-out`, `opt-in`, `delivery` or `ignored`; saving them is up to you.
431
+
432
+ For Twilio, pass the raw form body, the headers and the exact address Twilio calls:
433
+ `handleTwilioWebhook(rawBody, request.headers, { authToken, url: 'https://your.app/hooks/sms' })`.
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
+
347
443
  ## Agent tools
348
444
 
349
445
  An AI agent can run scheduling through the same routes. Import the tool descriptions and hand them to any agent runner:
@@ -1,4 +1,4 @@
1
- import { H as HttpMethod } from '../routes-CM-ezlv2.mjs';
1
+ import { H as HttpMethod } from '../routes-mii9tsbA.mjs';
2
2
  import '@ordinatio/scheduling';
3
3
 
4
4
  interface SchedulingToolParam {
@@ -1,4 +1,4 @@
1
- import { H as HttpMethod } from '../routes-CM-ezlv2.js';
1
+ import { H as HttpMethod } from '../routes-mii9tsbA.js';
2
2
  import '@ordinatio/scheduling';
3
3
 
4
4
  interface SchedulingToolParam {
@@ -1920,6 +1920,81 @@ var SETTINGS_TOOLS = [
1920
1920
  reason: "Clients lose the custom name, colours and sender at once.",
1921
1921
  prompt: "Remove the brand? Clients will see the default look."
1922
1922
  }
1923
+ },
1924
+ {
1925
+ name: "scheduling_get_text_settings",
1926
+ module: "scheduling",
1927
+ method: "GET",
1928
+ route: "/admin/text-settings",
1929
+ auth: "session_cookie",
1930
+ description: "Read which text-message provider and sending number the organization uses, and which providers the server offers.",
1931
+ params: [],
1932
+ example: {},
1933
+ responseShape: "{ settings: { provider, fromNumber, enabled, updatedAt } | null, providers: string[] }",
1934
+ whenToUse: "Before changing the text-message settings, or when the owner asks which number their texts come from.",
1935
+ pitfalls: [
1936
+ "settings is null when none has been saved; the organization then sends no texts of its own.",
1937
+ "The provider accounts belong to the server; this holds only the choice and the number.",
1938
+ "A server without text-message settings answers 501.",
1939
+ "Needs the scheduling switch to be on for the organization."
1940
+ ],
1941
+ dataSensitivity: "internal",
1942
+ risk: "observe"
1943
+ },
1944
+ {
1945
+ name: "scheduling_save_text_settings",
1946
+ module: "scheduling",
1947
+ method: "PUT",
1948
+ route: "/admin/text-settings",
1949
+ auth: "session_cookie",
1950
+ description: "Save the organization's text-message provider and sending number. This replaces the whole setting: enabled you leave out becomes true.",
1951
+ params: [
1952
+ { name: "provider", type: "string", required: true, description: "The text provider: one of the providers the server offers (TELNYX or TWILIO)" },
1953
+ { name: "fromNumber", type: "string", required: true, description: "The number texts are sent from, such as +13135550100; ten US digits are read as a US number" },
1954
+ { name: "enabled", type: "boolean", required: false, description: "False pauses texting without losing the number. Default true." }
1955
+ ],
1956
+ example: { provider: "TELNYX", fromNumber: "+13135550100" },
1957
+ responseShape: "{ settings: { provider, fromNumber, enabled, updatedAt } }",
1958
+ whenToUse: "To set up or change the number clients are texted from. Read the settings first.",
1959
+ pitfalls: [
1960
+ "It replaces everything; send enabled again to keep texting paused.",
1961
+ "The number must be one the owner has with that provider; this does not buy or register a number.",
1962
+ "A save that breaks a rule is refused with 400 and every problem is listed at once in details; nothing is saved.",
1963
+ "A server without text-message settings answers 501.",
1964
+ "Needs the scheduling switch to be on for the organization."
1965
+ ],
1966
+ dataSensitivity: "internal",
1967
+ risk: "act",
1968
+ requiresApproval: {
1969
+ action: "Save the text-message settings",
1970
+ reason: "Clients are texted from this number from now on, and a number that is not set up with the provider means their reminders are not delivered.",
1971
+ prompt: "Save the text-message settings: send from {fromNumber} with {provider}?"
1972
+ }
1973
+ },
1974
+ {
1975
+ name: "scheduling_remove_text_settings",
1976
+ module: "scheduling",
1977
+ method: "DELETE",
1978
+ route: "/admin/text-settings",
1979
+ auth: "session_cookie",
1980
+ description: "Remove the organization's text-message settings, so it sends no texts of its own.",
1981
+ params: [],
1982
+ example: {},
1983
+ responseShape: "{ removed }",
1984
+ whenToUse: "Only to stop texting from the organization's own number. To pause or change it, use scheduling_save_text_settings.",
1985
+ pitfalls: [
1986
+ "removed is false when there were no settings; that is not an error.",
1987
+ "Text reminders stop being sent until settings are saved again.",
1988
+ "A server without text-message settings answers 501.",
1989
+ "Needs the scheduling switch to be on for the organization."
1990
+ ],
1991
+ dataSensitivity: "internal",
1992
+ risk: "act",
1993
+ requiresApproval: {
1994
+ action: "Remove the text-message settings",
1995
+ reason: "Clients stop receiving text reminders and confirmations at once.",
1996
+ prompt: "Remove the text-message settings? Clients will no longer be texted."
1997
+ }
1923
1998
  }
1924
1999
  ];
1925
2000
 
@@ -2286,6 +2361,9 @@ var WEBHOOK_TOOLS = [
2286
2361
 
2287
2362
  // src/agent/coverage.ts
2288
2363
  var SCHEDULING_AGENT_EXCLUDED = {
2364
+ "GET /admin/api-keys": "Lists credentials. Agents do not handle API keys; the owner manages them in the dashboard.",
2365
+ "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.",
2366
+ "DELETE /admin/api-keys/[id]": "Credential management is left to the owner in the dashboard, not to an agent.",
2289
2367
  "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.",
2290
2368
  "POST /waitlist": "A client joining the waitlist for themselves; the answer holds their own private link token, which an agent should never be handed.",
2291
2369
  "DELETE /waitlist": "A client leaving the waitlist from their own private link; staff remove an entry with the remove-waitlist-entry tool.",
@@ -2296,6 +2374,7 @@ var SCHEDULING_AGENT_EXCLUDED = {
2296
2374
  "GET /calendars": "Public booking-page data for visitors; the admin calendar tools cover this for staff.",
2297
2375
  "GET /calendars/active": "A short calendar list for the pickers in a staff dashboard; the admin calendar list tool, for admin roles, returns every calendar with more detail, inactive ones too.",
2298
2376
  "POST /payments/intent": "Creates a card payment in the visitor's own browser session; staff take payment with the collect-balance tool.",
2377
+ "GET /admin/brand/sending-domain": "Makes the server look up DNS names under a domain the caller chooses, with no approval step for a GET tool; an agent steered by injected text could use it to send data to a name server it controls. Admins use the dashboard setup screen.",
2299
2378
  "GET /brand": "Public copy of the brand settings; the brand tool for staff returns the same data.",
2300
2379
  "GET /routing-forms": "Public form shown to a visitor; staff read the whole form, rules and fallback included, with scheduling_get_routing_form.",
2301
2380
  "POST /routing-forms/route": "Runs a visitor's own answers through a form; staff try sample answers with scheduling_test_routing_form.",
@@ -1891,6 +1891,81 @@ var SETTINGS_TOOLS = [
1891
1891
  reason: "Clients lose the custom name, colours and sender at once.",
1892
1892
  prompt: "Remove the brand? Clients will see the default look."
1893
1893
  }
1894
+ },
1895
+ {
1896
+ name: "scheduling_get_text_settings",
1897
+ module: "scheduling",
1898
+ method: "GET",
1899
+ route: "/admin/text-settings",
1900
+ auth: "session_cookie",
1901
+ description: "Read which text-message provider and sending number the organization uses, and which providers the server offers.",
1902
+ params: [],
1903
+ example: {},
1904
+ responseShape: "{ settings: { provider, fromNumber, enabled, updatedAt } | null, providers: string[] }",
1905
+ whenToUse: "Before changing the text-message settings, or when the owner asks which number their texts come from.",
1906
+ pitfalls: [
1907
+ "settings is null when none has been saved; the organization then sends no texts of its own.",
1908
+ "The provider accounts belong to the server; this holds only the choice and the number.",
1909
+ "A server without text-message settings answers 501.",
1910
+ "Needs the scheduling switch to be on for the organization."
1911
+ ],
1912
+ dataSensitivity: "internal",
1913
+ risk: "observe"
1914
+ },
1915
+ {
1916
+ name: "scheduling_save_text_settings",
1917
+ module: "scheduling",
1918
+ method: "PUT",
1919
+ route: "/admin/text-settings",
1920
+ auth: "session_cookie",
1921
+ description: "Save the organization's text-message provider and sending number. This replaces the whole setting: enabled you leave out becomes true.",
1922
+ params: [
1923
+ { name: "provider", type: "string", required: true, description: "The text provider: one of the providers the server offers (TELNYX or TWILIO)" },
1924
+ { name: "fromNumber", type: "string", required: true, description: "The number texts are sent from, such as +13135550100; ten US digits are read as a US number" },
1925
+ { name: "enabled", type: "boolean", required: false, description: "False pauses texting without losing the number. Default true." }
1926
+ ],
1927
+ example: { provider: "TELNYX", fromNumber: "+13135550100" },
1928
+ responseShape: "{ settings: { provider, fromNumber, enabled, updatedAt } }",
1929
+ whenToUse: "To set up or change the number clients are texted from. Read the settings first.",
1930
+ pitfalls: [
1931
+ "It replaces everything; send enabled again to keep texting paused.",
1932
+ "The number must be one the owner has with that provider; this does not buy or register a number.",
1933
+ "A save that breaks a rule is refused with 400 and every problem is listed at once in details; nothing is saved.",
1934
+ "A server without text-message settings answers 501.",
1935
+ "Needs the scheduling switch to be on for the organization."
1936
+ ],
1937
+ dataSensitivity: "internal",
1938
+ risk: "act",
1939
+ requiresApproval: {
1940
+ action: "Save the text-message settings",
1941
+ reason: "Clients are texted from this number from now on, and a number that is not set up with the provider means their reminders are not delivered.",
1942
+ prompt: "Save the text-message settings: send from {fromNumber} with {provider}?"
1943
+ }
1944
+ },
1945
+ {
1946
+ name: "scheduling_remove_text_settings",
1947
+ module: "scheduling",
1948
+ method: "DELETE",
1949
+ route: "/admin/text-settings",
1950
+ auth: "session_cookie",
1951
+ description: "Remove the organization's text-message settings, so it sends no texts of its own.",
1952
+ params: [],
1953
+ example: {},
1954
+ responseShape: "{ removed }",
1955
+ whenToUse: "Only to stop texting from the organization's own number. To pause or change it, use scheduling_save_text_settings.",
1956
+ pitfalls: [
1957
+ "removed is false when there were no settings; that is not an error.",
1958
+ "Text reminders stop being sent until settings are saved again.",
1959
+ "A server without text-message settings answers 501.",
1960
+ "Needs the scheduling switch to be on for the organization."
1961
+ ],
1962
+ dataSensitivity: "internal",
1963
+ risk: "act",
1964
+ requiresApproval: {
1965
+ action: "Remove the text-message settings",
1966
+ reason: "Clients stop receiving text reminders and confirmations at once.",
1967
+ prompt: "Remove the text-message settings? Clients will no longer be texted."
1968
+ }
1894
1969
  }
1895
1970
  ];
1896
1971
 
@@ -2257,6 +2332,9 @@ var WEBHOOK_TOOLS = [
2257
2332
 
2258
2333
  // src/agent/coverage.ts
2259
2334
  var SCHEDULING_AGENT_EXCLUDED = {
2335
+ "GET /admin/api-keys": "Lists credentials. Agents do not handle API keys; the owner manages them in the dashboard.",
2336
+ "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.",
2337
+ "DELETE /admin/api-keys/[id]": "Credential management is left to the owner in the dashboard, not to an agent.",
2260
2338
  "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.",
2261
2339
  "POST /waitlist": "A client joining the waitlist for themselves; the answer holds their own private link token, which an agent should never be handed.",
2262
2340
  "DELETE /waitlist": "A client leaving the waitlist from their own private link; staff remove an entry with the remove-waitlist-entry tool.",
@@ -2267,6 +2345,7 @@ var SCHEDULING_AGENT_EXCLUDED = {
2267
2345
  "GET /calendars": "Public booking-page data for visitors; the admin calendar tools cover this for staff.",
2268
2346
  "GET /calendars/active": "A short calendar list for the pickers in a staff dashboard; the admin calendar list tool, for admin roles, returns every calendar with more detail, inactive ones too.",
2269
2347
  "POST /payments/intent": "Creates a card payment in the visitor's own browser session; staff take payment with the collect-balance tool.",
2348
+ "GET /admin/brand/sending-domain": "Makes the server look up DNS names under a domain the caller chooses, with no approval step for a GET tool; an agent steered by injected text could use it to send data to a name server it controls. Admins use the dashboard setup screen.",
2270
2349
  "GET /brand": "Public copy of the brand settings; the brand tool for staff returns the same data.",
2271
2350
  "GET /routing-forms": "Public form shown to a visitor; staff read the whole form, rules and fallback included, with scheduling_get_routing_form.",
2272
2351
  "POST /routing-forms/route": "Runs a visitor's own answers through a form; staff try sample answers with scheduling_test_routing_form.",
@@ -429,6 +429,21 @@ var BrandSchema = z8.object({
429
429
  fromEmail: optionalText(400)
430
430
  }).strict();
431
431
 
432
+ // src/schemas/text-settings.schema.ts
433
+ import { z as z9 } from "zod";
434
+ var TextSettingsSchema = z9.object({
435
+ provider: z9.string().max(40),
436
+ fromNumber: z9.string().max(40),
437
+ enabled: z9.boolean().optional()
438
+ }).strict();
439
+
440
+ // src/schemas/api-key.schema.ts
441
+ import { z as z10 } from "zod";
442
+ var ApiKeySchema = z10.object({
443
+ name: z10.string().max(200),
444
+ access: z10.string().max(20)
445
+ }).strict();
446
+
432
447
  export {
433
448
  IntakeFormFieldSchema,
434
449
  CreateAppointmentTypeSchema,
@@ -467,5 +482,7 @@ export {
467
482
  TestRoutingFormSchema,
468
483
  PrivacySubjectSchema,
469
484
  PrivacyEraseSchema,
470
- BrandSchema
485
+ BrandSchema,
486
+ TextSettingsSchema,
487
+ ApiKeySchema
471
488
  };