@ordinatio/scheduling-api 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.0
+
+The first release.
+
+- **Outbound webhooks.** Set `host.webhooks` to turn them on. New staff routes: `GET` and `POST /admin/webhooks`,
+  `DELETE /admin/webhooks/[id]`, `POST /admin/webhooks/[id]/test`, `GET /admin/webhooks/[id]/deliveries`,
+  `POST /admin/webhook-deliveries/[id]/retry`. The signing secret is in the answer to the `POST` and nowhere
+  else. New worker route `POST /internal/webhooks/deliver`. Booked, rescheduled, cancelled and no-show events are
+  queued from the events the routes already announce. With `host.webhooks` unset, the staff routes answer 501 and
+  nothing is queued.
+- Needs `@ordinatio/scheduling` 0.3.0 or newer, which has the webhook tables.
+- **The routes** for booking, managing and running a scheduling system, each a function from a `Request` to a
+  `Response`: the public booking routes, the staff routes for calendars, appointment types, availability,
+  policies, coupons, packages, group sessions, repeat series and appointment actions, and the calendar sign-in
+  routes for Google and Outlook.
+- **`createSchedulingApi({ host })`** serves them all from one `handle(request)`, or one route at a time with
+  `handler(method, path)` for a host that routes by file.
+- **The host.** One object supplies the database, who is signed in, the payment provider, the calendar sync,
+  the cache and the rate limit. Everything but the database has a safe default.
+- **Sign-in helpers.** `createBearerStaffResolver` signs a request in from its bearer token;
+  `createStaffContext` builds the signed-in person for a host that has no group rules.
+- **`createNodeListener`** serves the API from `node:http`: the caller's address comes from the connection, a
+  `Host` or `x-forwarded-for` header the caller wrote is ignored, bodies over 1 MB are refused, every `Set-Cookie`
+  header is kept, and a thrown error answers 500 instead of stopping the server.
+- **Request schemas** for browser code at `@ordinatio/scheduling-api/schemas`.
+
+Needs `@ordinatio/scheduling` 0.2.0 or newer and its database tables.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ordinatio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,284 @@
-# Temporary Holding Version
+# @ordinatio/scheduling-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The web routes for [`@ordinatio/scheduling`](https://www.npmjs.com/package/@ordinatio/scheduling). Each route is
+a function from a standard `Request` to a standard `Response`, so it runs in Node, Next.js, Hono, Bun and
+anything else that speaks the Fetch API. You supply the database, who is signed in, and anything outside the
+database (payment, calendar sync). Everything else has a safe default.
+
+**Status:** version 0.1.0. It needs `@ordinatio/scheduling` 0.3.0 or newer.
+
+## Words used here
+
+- **Host:** your program. It owns the server, the database and the sign-in. This package owns the routes.
+- **Public routes:** what a client's browser calls: open times, booking, manage a booking.
+- **Staff routes:** what your team calls: calendars, appointment types, hours, coupons, reports. They need a
+  signed-in person.
+- **Adapter:** a small piece of code you supply for payment, calendar sync or sign-in.
+
+## What you need
+
+- Node 22 or newer.
+- A Postgres database with nothing in it, and its address. It looks like
+  `postgresql://user:password@localhost:5432/your_empty_database`.
+- npm. (pnpm works too.)
+- A shell that understands `export`, `&` and `$(...)`: bash or zsh on macOS or Linux, or WSL on Windows.
+
+## Quick start
+
+You will build a small server, add one calendar, book a slot over HTTP, see a second booking for the same slot
+refused, and see that staff routes need a token. It takes about five minutes.
+
+### 1. Make a project
+
+Make an empty folder and open a terminal in it. Then run:
+
+```bash
+npm init -y
+npm pkg set type=module
+npm install @ordinatio/scheduling @ordinatio/scheduling-api @prisma/client@7.6.0 @prisma/adapter-pg@7.6.0
+npm install --save-dev prisma@7.6.0 tsx
+```
+
+### 2. Build the tables
+
+Put your own database address in the first line. The engine brings its own table definitions and one
+migration.
+
+```bash
+export DATABASE_URL="postgresql://user:password@localhost:5432/your_empty_database"
+npx prisma generate --config node_modules/@ordinatio/scheduling/prisma.config.ts
+npx prisma migrate deploy --config node_modules/@ordinatio/scheduling/prisma.config.ts
+```
+
+### 3. Write the server
+
+Save this as `server.ts`. It connects to the database, builds the API from a host object, and hands each
+incoming request to `api.handle`. Staff sign in with `Authorization: Bearer <STAFF_TOKEN>`. A real app looks the
+token up in its own user store; here there is one token.
+
+```ts file=server.ts
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { createServer } from 'node:http';
+import { PrismaClient } from '@prisma/client';
+import { PrismaPg } from '@prisma/adapter-pg';
+import { createBearerStaffResolver, createNodeListener, createSchedulingApi } from '@ordinatio/scheduling-api';
+
+const connectionString = process.env.DATABASE_URL?.trim();
+const staffToken = process.env.STAFF_TOKEN?.trim();
+if (!connectionString || !staffToken) {
+  console.error('Set DATABASE_URL and STAFF_TOKEN.');
+  process.exit(2);
+}
+const port = Number(process.env.PORT ?? 3000);
+const publicUrl = `http://localhost:${port}`;
+const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString }) });
+
+// Compares digests so the time taken does not depend on how much of the token matched.
+const digest = (value: string) => createHash('sha256').update(value).digest();
+const isStaffToken = (given: string) => timingSafeEqual(digest(given), digest(staffToken));
+
+const api = createSchedulingApi({
+  host: {
+    publicDb: async () => prisma,
+    // Links in booking messages are built from this address.
+    appUrl: () => publicUrl,
+    staff: createBearerStaffResolver({
+      db: () => prisma,
+      authenticate: async (token) =>
+        isStaffToken(token) ? { userId: 'owner', organizationId: 'demo-org', role: 'OWNER' } : null,
+    }),
+    // This server speaks plain http on your machine. Leave this out when you serve https.
+    secureCookies: () => false,
+  },
+});
+
+createServer(createNodeListener(api, { publicUrl })).listen(port, () =>
+  console.log(`Scheduling API on ${publicUrl}/api/scheduling`),
+);
+```
+
+`createNodeListener` turns each Node request into a standard `Request`. It takes the caller's address from the
+connection, ignores a `Host` header or `x-forwarded-for` the caller wrote, refuses bodies over 1 MB, keeps every
+`Set-Cookie` header, and answers 500 instead of crashing when something throws. The API limits requests by
+caller address, so keep it: a hand-written adapter that copies the headers lets a caller dodge the limits.
+Behind proxies, pass `trustedProxies: n`, the number of proxies in front of your server (a load balancer
+counts as one). The caller's address is then the nth entry from the right of `x-forwarded-for`, so a proxy that
+appends to the header works as well as one that overwrites it.
+
+This one token is for the quick start only. In your own app, look up a random token of 32 bytes or more in your
+user store, and store it hashed.
+
+### 4. Add a calendar
+
+Save this as `seed.ts`. It adds the organization row, one calendar open on weekdays, one 30-minute appointment
+type, and prints the numbers the next step needs.
+
+```ts file=seed.ts
+import { PrismaClient } from '@prisma/client';
+import { PrismaPg } from '@prisma/adapter-pg';
+import {
+  createAppointmentType,
+  createCalendar,
+  getAvailableSlots,
+  setWeeklyAvailability,
+} from '@ordinatio/scheduling';
+
+const connectionString = process.env.DATABASE_URL?.trim();
+if (!connectionString) {
+  console.error('DATABASE_URL is not set.');
+  process.exit(2);
+}
+const prisma = new PrismaClient({ adapter: new PrismaPg({ connectionString }) });
+const timezone = 'America/New_York';
+const suffix = Date.now().toString(36);
+
+const day = new Date();
+day.setUTCHours(12, 0, 0, 0);
+day.setUTCDate(day.getUTCDate() + 2);
+while ([0, 6].includes(day.getUTCDay())) day.setUTCDate(day.getUTCDate() + 1);
+
+await prisma.organization.upsert({ where: { id: 'demo-org' }, update: {}, create: { id: 'demo-org', name: 'Demo Studio' } });
+const calendar = await createCalendar(prisma, {
+  organizationId: 'demo-org',
+  name: 'Front desk',
+  slug: `front-desk-${suffix}`,
+  type: 'STAFF',
+  timezone,
+});
+const appointmentType = await createAppointmentType(prisma, {
+  organizationId: 'demo-org',
+  name: 'Consultation',
+  slug: `consultation-${suffix}`,
+  duration: 30,
+  calendarIds: [calendar.id],
+});
+await setWeeklyAvailability(
+  prisma,
+  calendar.id,
+  [1, 2, 3, 4, 5].map((dayOfWeek) => ({ dayOfWeek, startTime: '09:00', endTime: '17:00', minNotice: 0 })),
+);
+const { slots } = await getAvailableSlots(prisma, { calendarId: calendar.id, date: day, duration: 30, timezone });
+if (slots.length === 0) throw new Error('No open slots were found for the demo day.');
+console.log(`CALENDAR=${calendar.id}`);
+console.log(`TYPE=${appointmentType.id}`);
+console.log(`DAY=${day.toISOString().slice(0, 10)}`);
+console.log(`START=${slots[0].start.toISOString()}`);
+await prisma.$disconnect();
+```
+
+### 5. Run it and try it
+
+This starts the server, then calls it the way a booking page would. Each `curl` prints one line.
+
+```bash
+(
+export STAFF_TOKEN="a-long-random-text"
+export PORT=3100
+npx tsx seed.ts > seed.out || { cat seed.out; exit 1; }
+set -a; . ./seed.out; set +a
+node --import tsx server.ts > server.log 2>&1 &
+SERVER_PID=$!
+trap 'kill $SERVER_PID' EXIT
+for attempt in $(seq 1 30); do
+  kill -0 $SERVER_PID || { echo "The server stopped. Is port $PORT in use? See server.log."; exit 1; }
+  curl -s -o /dev/null "http://localhost:$PORT/api/scheduling/widget-init" && break
+  sleep 1
+done
+API="http://localhost:$PORT/api/scheduling"
+BODY="{\"calendarId\":\"$CALENDAR\",\"typeId\":\"$TYPE\",\"startTime\":\"$START\",\"timezone\":\"America/New_York\",\"clientName\":\"Jane Smith\",\"clientEmail\":\"jane@example.com\"}"
+curl -s -o /dev/null -w "Open times on the day: HTTP %{http_code}\n" "$API/availability?calendarId=$CALENDAR&typeId=$TYPE&date=$DAY&timezone=America/New_York"
+curl -s -o /dev/null -w "First booking: HTTP %{http_code}\n" -X POST -H "content-type: application/json" -d "$BODY" "$API/appointments"
+curl -s -o /dev/null -w "Same slot again: HTTP %{http_code}\n" -X POST -H "content-type: application/json" -d "$BODY" "$API/appointments"
+curl -s -o /dev/null -w "Calendars without a token: HTTP %{http_code}\n" "$API/admin/calendars"
+curl -s -o /dev/null -w "Calendars with the token: HTTP %{http_code}\n" -H "authorization: Bearer $STAFF_TOKEN" "$API/admin/calendars"
+)
+```
+
+The round brackets run all of this in its own shell, so the server stops when the block ends and a failure cannot
+close your terminal. The server's own output goes to `server.log`.
+
+It prints this:
+
+```text expected
+Open times on the day: HTTP 200
+First booking: HTTP 201
+Same slot again: HTTP 409
+Calendars without a token: HTTP 401
+Calendars with the token: HTTP 200
+```
+
+The second booking is refused by the database, not only by the route, so two people who book the same slot at
+the same moment cannot both win.
+
+### Check that this README still works
+
+From this package's folder, run `bash scripts/check-readme.sh`. It follows the steps above in an empty folder
+against a scratch Postgres database and compares the output with the block above. It needs a local Postgres
+that your user can create databases in.
+
+## The host object
+
+`createSchedulingApi({ host })` takes one object. Only `publicDb` is required.
+
+| Member | What it does | Default |
+| --- | --- | --- |
+| `publicDb()` | The database. | required |
+| `appUrl()` | The web address of your server. Booking needs it to build links in messages. | none: booking answers 500 |
+| `staff` | Who is signed in. `createBearerStaffResolver` reads a bearer token; `createStaffContext` builds the person for your own sign-in. | nobody: staff routes answer 401 |
+| `payments` | Charges, verifies and refunds payments. | none: a type that needs payment cannot be booked |
+| `calendarSync` | Keeps Google or Outlook in step. | nothing is synced |
+| `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 |
+| `secureCookies()` | Whether the short-lived sign-in cookies travel only over https. | yes: on plain http the cookies do not stick |
+| `cache`, `availabilityCache` | Stored answers. | in-memory, per process |
+| `publicBooking`, `organizations`, `tenantDb` | Find the organization and database of a request. | one organization |
+| `events`, `activity` | Tell your screens or activity feed what changed. | nothing |
+| `internalAccess`, `workerCommands` | The background worker's own routes. | closed |
+| `calendarConnectors` | The Google and Outlook sign-in flows. | not configured |
+
+Everything else on `SchedulingHost` is documented in its type. If a member you do not set is needed by a route,
+the route says so in its answer instead of guessing.
+
+## Webhooks
+
+Set `webhooks: {}` on the host to tell other systems about bookings. Staff then have these routes, all for
+admins:
+
+| Route | What it does |
+|---|---|
+| `GET /admin/webhooks` | Lists the endpoints and the event names. Never shows a secret. |
+| `POST /admin/webhooks` | Adds one: `{ "url": "https://...", "eventTypes": ["appointment.booked"], "description": "CRM" }`. The answer holds the signing `secret`; it is shown once. |
+| `DELETE /admin/webhooks/[id]` | Removes an endpoint with its deliveries. |
+| `POST /admin/webhooks/[id]/test` | Sends one signed `webhook.test` event now and reports what the receiver answered. |
+| `GET /admin/webhooks/[id]/deliveries` | The delivery log, with every try. `?status=DEAD_LETTER` filters. |
+| `POST /admin/webhook-deliveries/[id]/retry` | Sends a delivery that ran out of tries again. |
+
+Events are queued for you. Sending is done by a timer you run: call `deliverDueWebhooks(db)` from
+`@ordinatio/scheduling` every few seconds, or have your worker `POST /internal/webhooks/deliver` (it needs
+`host.internalAccess`). Without `webhooks` on the host the routes answer 501 and nothing is queued. In local
+development, `webhooks: { allowInsecureTargets: true }` lets an endpoint point at `http://localhost`. The engine
+README explains the retry schedule and how a receiver checks the signature.
+
+## Serving the routes
+
+- **One handler:** `api.handle(request)` serves every route under `/api/scheduling` (change it with
+  `basePath`).
+- **One file per route**, in a framework that routes by file such as Next.js:
+  `export const POST = api.handler('POST', '/coupons/validate');`
+- **Request shapes for your own browser code:** `import { ... } from '@ordinatio/scheduling-api/schemas'`.
+
+## Sign-in
+
+Staff routes ask the host who is calling. The two helpers cover the common cases:
+
+- `createBearerStaffResolver({ db, authenticate })` reads `Authorization: Bearer <token>`; your
+  `authenticate` function turns the token into `{ userId, organizationId, role }` or `null`.
+- `createStaffContext({ userId, organizationId, role, db })` builds the person yourself, for cookies or
+  sessions. Owners, admins and managers count as administrators; pass `adminRoles` to change that.
+
+Both give the person access to every calendar of the organization. If you have groups that should see only
+some calendars, build your own `StaffContext` and implement `visibleCalendars`, `visibleCalendarIds`,
+`canSeeCalendar` and `canSeeAppointment`.
+
+## License
+
+MIT