@medalsocial/sdk 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medalsocial/sdk",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "TypeScript SDK for Medal Social API — posts, emails, contacts, deals, helpdesk, webhooks, and GDPR compliance",
   "license": "Apache-2.0",
   "author": "Medal Social / Ali Aljumaili",
@@ -76,27 +76,27 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.6",
-    "@changesets/changelog-github": "^0.7.0",
-    "@changesets/cli": "^2.31.1",
-    "@commitlint/cli": "^21.2.1",
-    "@commitlint/config-conventional": "^21.2.0",
-    "@redocly/cli": "^2.42.0",
+    "@biomejs/biome": "^2.5.10",
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.1",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@redocly/cli": "^2.47.0",
     "@secretlint/secretlint-rule-preset-recommend": "^13.0.4",
     "@tanstack/intent": "0.3.6",
-    "@types/node": "^24.13.3",
-    "@vitest/coverage-v8": "^4.1.10",
-    "husky": "^9.1.6",
+    "@types/node": "^26.3.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "husky": "^9.1.7",
     "jsr": "^0.14.3",
-    "knip": "^6.29.0",
-    "lint-staged": "^17.2.0",
-    "only-allow": "^1.2.1",
+    "knip": "^6.32.2",
+    "lint-staged": "^17.3.0",
+    "only-allow": "^1.2.2",
     "openapi-typescript": "^7.13.0",
     "secretlint": "^13.0.4",
-    "tsup": "^8.3.0",
+    "tsup": "^8.5.1",
     "typedoc": "^0.28.20",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "preinstall": "npx only-allow pnpm",
@@ -104,12 +104,13 @@
     "dev": "tsup src/index.ts --watch",
     "clean": "rm -rf dist",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "docs": "typedoc",
     "lint": "biome check .",
     "lint:fix": "biome check --fix .",
-    "quality": "pnpm lint && pnpm test",
-    "typecheck": "tsc --noEmit",
+    "quality": "pnpm lint && pnpm typecheck && pnpm test",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
     "verify:paths": "node scripts/verify-package-paths.mjs",
     "openapi:lint": "redocly lint openapi/medal-social.openapi.yaml",
     "openapi:types": "openapi-typescript && biome format --write src/openapi.generated.ts",

package/skills/client/SKILL.md

@@ -65,9 +65,9 @@ Every request gets:
 - Otherwise it waits `250 * attempt` ms (so 250, 500 between the first three attempts).
 - Other 4xx errors are NOT retried — they throw `MedalApiError` immediately.
 - Network errors (fetch throws) are NOT retried — they bubble up.
-- The request is aborted via `AbortController` after `timeout` ms.
+- The request is aborted via `AbortController` after `timeout` ms. That budget covers the **whole exchange** — headers and body — per attempt. It is fixed wall-clock time: progress on the body does not extend it, so raise `timeout` if you pull responses large enough to take longer than it to arrive. Retry backoff is not charged against it.
 
-The SDK does **not** drain the response body between retries — if you observe a connection leak in long-running processes, that's worth investigating.
+The SDK **drains** the response body of any attempt it abandons to a retry, so the connection returns to the pool instead of being held open. The body is streamed to a sink rather than buffered, so a large error page costs no memory. A drain that fails is ignored — the retry proceeds on the status.
 
 ## Errors
 

package/skills/resources/SKILL.md

@@ -1,16 +1,18 @@
 ---
 name: resources
-description: Use when calling any of the SDK resources (contacts, deals, emails, gdpr, posts, scan, workspaces) — listing with pagination, sending transactional or batch emails, scheduling and publishing posts, recording GDPR consent or running an export workflow, fetching a contact's activity timeline — or when needing OpenAPI-derived TypeScript types or the raw OpenAPI document from `@medalsocial/sdk`.
+description: Use when calling any of the SDK resources (bookings, contacts, deals, emails, gdpr, posts, scan, workspaces) — listing with pagination, sending transactional or batch emails, scheduling and publishing posts, booking appointments or querying free slots, cancelling or rescheduling a booking as staff or on a customer's behalf, recording GDPR consent or running an export workflow, fetching a contact's activity timeline — or when needing OpenAPI-derived TypeScript types or the raw OpenAPI document from `@medalsocial/sdk`.
 ---
 
 # Medal Social SDK — Resources
 
 ## When to load this skill
 
-- Calling `medal.contacts.*`, `medal.deals.*`, `medal.emails.*`, `medal.gdpr.*`, `medal.posts.*`, `medal.scan.*`, or `medal.workspaces.*`.
+- Calling `medal.bookings.*`, `medal.contacts.*`, `medal.deals.*`, `medal.emails.*`, `medal.gdpr.*`, `medal.posts.*`, `medal.scan.*`, or `medal.workspaces.*`.
 - Looking up an exact method signature or response shape.
 - Building a list view that needs pagination.
 - Sending a single transactional email or a bulk batch.
+- Booking an appointment: reading the catalogue, querying free slots, creating a booking or party.
+- Cancelling or rescheduling a booking — and deciding between the staff route and the customer manage-token route.
 - Running a GDPR data-export workflow (request → poll → fetch).
 - Importing contacts from a CSV-like source.
 - Needing OpenAPI-derived types for a custom fetch wrapper, generated mocks, or contract tests.
@@ -22,7 +24,10 @@ Most methods return one of:
 - **`ApiResponse<T>`** — single-result envelope: `{ data: T }` plus optional metadata.
 - **`PaginatedResponse<T>`** — list envelope: `{ data: T[], pagination: { has_more: boolean, next_cursor: string | null } }`.
 
-**One documented exception:** `medal.gdpr.cookieConsent(input)` returns a plain `{ success: boolean, logId?: string }` directly — no `data` envelope. Don't destructure `{ data }` from it. See the GDPR section below.
+**Two documented deviations:**
+
+- `medal.gdpr.cookieConsent(input)` returns a plain `{ success: boolean, logId?: string }` directly — no `data` envelope. Don't destructure `{ data }` from it. See the GDPR section below.
+- `medal.bookings.list(opts?)` returns `BookingsPage`, not `PaginatedResponse<Booking>` — its `pagination` carries an extra `truncated: boolean`. See the Bookings section below.
 
 Errors throw `MedalApiError` (see the `client` skill for details).
 
@@ -30,6 +35,8 @@ Errors throw `MedalApiError` (see the `client` skill for details).
 
 | Namespace | Source | Methods |
 |---|---|---|
+| `medal.bookings` | `src/resources/bookings.ts` | `listServices(opts?)`, `listResources()`, `availability(opts)`, `schedule(opts)`, `list(opts?)`, `create(input, opts?)`, `get(id)`, `update(id, input, opts?)`, `cancel(id, input?, opts?)`, `reschedule(id, input, opts?)`, `markNoShow(id, opts?)` — all **staff** semantics (policy windows bypassed) |
+| `medal.bookings.manage` | `src/resources/bookings.ts` (`BookingsManage`) | `get(token)`, `cancel(token, input?, opts?)`, `reschedule(token, input, opts?)` — **customer** semantics (policy windows enforced) |
 | `medal.contacts` | `src/resources/contacts.ts` | `list(opts?)`, `create(input)`, `get(id)`, `update(id, input)`, `remove(id)`, `activities(id, opts?)`, `addNote(id, { content })`, `import(contacts[])` |
 | `medal.deals` | `src/resources/deals.ts` | `list(opts?)`, `create(input)`, `get(id)`, `update(id, input)`, `remove(id)` |
 | `medal.emails.templates` | `src/resources/emails.ts` (`EmailTemplates`) | `list()`, `get(slug, opts?)` |
@@ -90,6 +97,92 @@ await medal.posts.publish(post.id);
 
 `channels()` is the canonical way to discover what publishing destinations a workspace has connected — don't hard-code channel IDs.
 
+## Bookings — catalogue, slots, and the two cancel/reschedule semantics
+
+**Money is integer øre.** `amount_ore` and `price_ore` are whole øre — never divide into a float for storage or comparison, and never invent a "kroner" field. `499.90` is not representable and a rounding error in a price is a wrong invoice.
+
+**Timestamps are asymmetric.** Responses render every timestamp as an ISO 8601 string. Requests accept *either* Unix milliseconds or an ISO string (`BookingTimestampInput = number | string`), so echoing a slot's `start_ts` straight back into `create()` is supported and is the intended flow. Don't normalise on the client.
+
+```ts
+const { data: services } = await medal.bookings.listServices();          // active-only
+const { data: all } = await medal.bookings.listServices({ include_inactive: true });
+const { data: resources } = await medal.bookings.listResources();        // staff / rooms / equipment
+
+// Free slots — service_id, from_ts and to_ts are all REQUIRED; to_ts must be after from_ts
+const { data: slots } = await medal.bookings.availability({
+  service_id: services[0].id,
+  from_ts: Date.now(),
+  to_ts: Date.now() + 7 * 86_400_000,
+  resource_id: resources[0].id,   // optional
+});
+```
+
+Slots are computed at call time and are **not held** — a slot can be taken between `availability()` and `create()`. Handle the conflict error; don't assume a fetched slot is reserved.
+
+**An empty `availability()` does not say why.** A closed day, an evening past closing and a fully booked day all come back as `[]`. `schedule()` is the other half — one entry per date the workspace keeps hours on, same parameters as `availability()`:
+
+```ts
+const { data: days } = await medal.bookings.schedule({
+  service_id: services[0].id,
+  from_ts: Date.now(),
+  to_ts: Date.now() + 7 * 86_400_000,
+});
+// A date ABSENT from `days` is closed. On a listed date, `last_start_ts` is the last
+// start THIS service could occupy (duration + buffers, not the closing time) — compare
+// it against the clock to tell "too late today" from "fully booked"; it is `null` on a
+// date with posted hours that is shut outright (a public holiday).
+```
+
+**Creating is a party operation.** `items` is an array because one request books a whole family in one all-or-nothing transaction (max 50). A single appointment is just `items` of length 1.
+
+```ts
+const { data } = await medal.bookings.create(
+  {
+    items: [{ service_id: services[0].id, start_ts: slots[0].start_ts! }],
+    contact: { phone: '+4790000000', name: 'Ida' },   // phone is the CRM dedupe key and is required
+    created_via: 'web',   // only from the workspace's OWN site; omit (=> 'api') from integrations
+  },
+  { idempotencyKey: crypto.randomUUID() },
+);
+data.bookings[0].manage_token;  // SHOW-ONCE
+data.contact_id;
+```
+
+`created_via` is optional and defaults to `api`. Send `web` **only** from the workspace's own website, so its bookings can be told apart from integrations'. `dashboard` and `walk_in` are staff-only and the API rejects them with 400 — an API key proves which workspace is calling, not that a member typed the booking in.
+
+`manage_token` is a capability: whoever holds it can cancel or move that booking. Only its SHA-256 hash is stored, so the create response is the **only** place the plaintext token ever appears — persist it there if you need to build the customer's manage link. It is **absent** (the key is dropped, not nulled) when the response is replayed from an `Idempotency-Key`, which is why the type is `manage_token?: string`.
+
+**A lost token cannot be recovered.** `bookings.get(id)` returns a `Booking`, which has no token field — there is nothing to re-read, and the stored hash is one-way. The only ways forward are to reschedule the booking (`reschedule` mints a fresh token) or to have staff act on it by id.
+
+**The two semantics are picked by which namespace you call, not by an argument:**
+
+| | `medal.bookings.cancel(id)` / `.reschedule(id, …)` | `medal.bookings.manage.cancel(token)` / `.reschedule(token, …)` |
+|---|---|---|
+| Who is acting | the business (your API key **is** the salon) | the customer, relayed by you |
+| Policy windows | **bypassed** | **enforced** |
+| Cancel attributed to | `staff` | `customer` |
+| Addressed by | booking id | manage token |
+
+Use the manage routes when you are relaying a customer's own click on the link in their confirmation email. Use the id routes for anything staff do. Reaching for the id route because "it always works" silently records a customer's cancellation as a staff one and skips the window the salon configured.
+
+```ts
+const { data: summary } = await medal.bookings.manage.get(manageToken);
+if (summary.can_cancel) await medal.bookings.manage.cancel(manageToken, { reason: 'Endret plan' });
+```
+
+`can_cancel` / `can_reschedule` already apply the windows — honour them instead of re-deriving from `cancel_window_hours` and `start_ts`.
+
+**A reschedule returns a NEW booking.** Both reschedule methods cancel the old row and insert a new one, so the result's `booking_id` is a new id and `manage_token` a newly minted token. The id and token you passed in are dead afterwards — re-store both, or the next manage link you send will 404.
+
+**Listing carries a third pagination field.** `pagination.truncated` is separate from `has_more`: the underlying read is capped, and when the cap binds there are matching bookings that **no cursor from this call reaches**. Walking `has_more` to the end will not find them — narrow `from_ts`/`to_ts` and page again.
+
+```ts
+const page = await medal.bookings.list({ status: 'confirmed', from_ts: Date.now(), limit: 50 });
+if (page.pagination.truncated) { /* window too wide — split the range */ }
+```
+
+`update(id, input)` is annotation only — `notes` (customer-visible) and `internal_notes` (staff-only); at least one is required, and `""` clears a field. It cannot move a booking or change its status.
+
 ## Emails — transactional + batch
 
 **Single send (HTTP 202 — queued, not delivered):**
@@ -239,4 +332,12 @@ The `with { type: "json" }` import-attribute syntax requires Node 24+ or a bundl
 | `contacts.import` with > 500 contacts | API rejects | Chunk into 500-contact batches yourself |
 | Hard-coded channel IDs in `posts.create` | Channels are workspace-specific | Call `posts.channels()` to discover them |
 | Looping on `next_cursor` alone for pagination | Can be non-null when `has_more: false` | Loop on `pagination.has_more` |
+| `medal.bookings.cancel(id)` to relay a customer's cancel | Bypasses the policy window and records `cancelled_by: 'staff'` | `medal.bookings.manage.cancel(token)` |
+| Dividing `amount_ore` / `price_ore` into kroner for storage | Integer øre; a float rounds and the invoice is wrong | Keep the integer; format only at the point of display |
+| Reusing the old id or manage token after a reschedule | Reschedule inserts a NEW booking and mints a NEW token | Store `result.booking_id` and `result.manage_token` |
+| Expecting `manage_token` on an idempotent replay | Tokens are redacted from replayed responses | Persist it from the first response — a replay cannot give it back |
+| Re-reading a booking to recover a lost `manage_token` | `Booking` has no token field and only the hash is stored — it is unrecoverable | Reschedule to mint a fresh token, or act by booking id as staff |
+| `medal.bookings.update(id, {})` | Rejected by the API; now also a compile error | Pass at least one of `notes` / `internal_notes` |
+| Ignoring `pagination.truncated` on `bookings.list` | Matching bookings exist that no cursor reaches | Narrow `from_ts`/`to_ts` and page again |
+| Converting `start_ts` to a fixed format before sending | The API takes Unix ms **or** ISO 8601 | Pass a slot's `start_ts` straight through |
 | Building a custom client when only types are needed | Reinventing the wheel | Import from `@medalsocial/sdk/openapi-types` |