@medalsocial/sdk 1.6.0 → 1.8.0

package/README.md

@@ -204,6 +204,112 @@ const { data: removed } = await medal.deals.remove(deal.id);
 console.log(updated.success, unlinked.success, removed.success);
 ```
 
+### Bookings
+
+Money is always **integer øre** (`amount_ore`, `price_ore`) — never a float, never kroner. Timestamps come back as ISO 8601 strings; on the way in, either Unix milliseconds or an ISO string is accepted.
+
+```ts
+// Catalogue + free slots
+const { data: services } = await medal.bookings.listServices();
+const { data: resources } = await medal.bookings.listResources();
+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 — defaults to every capable resource
+});
+
+// Book a party — all items succeed or none do (max 50)
+const { data: created } = await medal.bookings.create(
+  {
+    items: [
+      { service_id: services[0].id, start_ts: slots[0].start_ts! },
+      { service_id: services[0].id, start_ts: slots[1].start_ts!, booked_for_name: 'Ida', booked_for_birth_year: 2018 },
+    ],
+    contact: { phone: '+4790000000', email: 'ida@example.com', name: 'Ida Hansen' },
+    notes: 'Bursdag',
+  },
+  { idempotencyKey: crypto.randomUUID() },   // optional — see the note below
+);
+// created.bookings[i].manage_token is returned EXACTLY ONCE (only its hash is
+// stored, and an idempotent replay omits it) — persist it for the manage link.
+// It is UNRECOVERABLE if lost: `Booking` has no token field, so re-reading the
+// booking gives you nothing. Reschedule to mint a fresh one, or act by id.
+
+// Staff actions — policy windows are bypassed, cancels attributed to staff
+const { data: booking } = await medal.bookings.get(created.bookings[0].id);
+await medal.bookings.update(booking.id, { internal_notes: 'Allergisk mot parfyme' });
+await medal.bookings.cancel(booking.id, { reason: 'Sykdom' });
+const { data: moved } = await medal.bookings.reschedule(booking.id, {
+  new_start_ts: '2026-09-02T09:00:00.000Z',
+  new_resource_id: resources[0].id,
+});
+// moved.booking_id is a NEW id with a NEW manage_token — the old booking is cancelled
+await medal.bookings.markNoShow(moved.booking_id);
+
+// Listing — check `truncated`: when true, matching bookings exist that no
+// cursor reaches, so narrow the from_ts/to_ts window
+const page = await medal.bookings.list({ status: 'confirmed', from_ts: Date.now(), limit: 50 });
+console.log(page.pagination.has_more, page.pagination.next_cursor, page.pagination.truncated);
+```
+
+**Customer actions go through `medal.bookings.manage`**, keyed by the manage token instead of the booking id. This is not the same route with a different lookup key: the workspace's cancel/reschedule windows are **enforced**, and the cancel is attributed to the customer. Use it to relay a customer's own click on the link in their confirmation email.
+
+```ts
+const { data: summary } = await medal.bookings.manage.get(manageToken);
+if (summary.can_cancel) await medal.bookings.manage.cancel(manageToken, { reason: 'Endret plan' });
+if (summary.can_reschedule) {
+  const { data } = await medal.bookings.manage.reschedule(manageToken, {
+    new_start_ts: '2026-09-02T09:00:00.000Z',
+  });
+  console.log(data.booking_id, data.manage_token); // old token stops working
+}
+```
+
+`can_cancel` / `can_reschedule` already apply the policy windows — honour them rather than re-deriving from `cancel_window_hours`.
+
+**Booking writes are idempotent by default.** The SDK retries 429/5xx automatically, so every booking `POST` (`create`, `cancel`, `reschedule`, `markNoShow`, and both `manage` writes) carries a generated `Idempotency-Key` — a retry after a gateway failure replays the original result instead of booking the slot twice. Supply your own `options.idempotencyKey` to extend that guarantee across *your* retries too: the server remembers a key for 24 hours, keyed by `(key, workspace, method + path)`.
+
+`update(id, input)` requires at least one of `notes` / `internal_notes`; `update(id, {})` is a compile error, matching the API's own 400.
+
+### Customer portal
+
+Self-service for the workspace's own customers: they sign in with an e-mailed one-time code, then see and change their profile, list their bookings, export their data, or erase their account. The API key needs `read:portal` and `write:portal`.
+
+The session token is a **bearer credential for one contact**. Your site's server exchanges the code for it and keeps it in an **HttpOnly cookie on the site's own domain** — never hand it to the browser, and never let the browser call Medal directly. Session-bound methods take the token as their first argument and send it as `X-Portal-Session`.
+
+```ts
+// 1. Send the code. Always { status: 'sent' } — enumeration-safe, so "sent" does
+//    not confirm the address belongs to a contact.
+await medal.portal.login.start({ email: 'ida@example.com', locale: 'nb' });
+
+// 2. Exchange the code the customer typed. Wrong, burned and expired codes all
+//    answer 401 PORTAL_CODE_INVALID.
+const { data: session } = await medal.portal.login.verify({ email: 'ida@example.com', code: '123456' });
+// -> set an HttpOnly, Secure, SameSite cookie holding session.session_token,
+//    expiring at session.expires_at (Unix ms)
+
+// 3. Session-bound calls, from your server, with the token read back from the cookie
+const { data: me } = await medal.portal.me(session.session_token);
+const { data: bookings } = await medal.portal.myBookings(session.session_token);
+// bookings.upcoming[i].manage_token is set while the booking is still manageable —
+// it opens your site's manage page (medal.bookings.manage.*); past bookings carry null
+await medal.portal.updateMe(session.session_token, {
+  phone: '+4790000000',
+  family: [{ name: 'Ola', birth_year: 2018 }],   // replaces the whole list
+  marketing_consent: true,                        // recorded as a marketing_email consent, source 'portal'
+});
+const { data: exported } = await medal.portal.exportMyData(session.session_token); // GDPR Art. 15, synchronous
+await medal.portal.logout(session.session_token);     // 204 — revokes this session only
+// …or, when the customer asks to be forgotten (terminal — the session is revoked, a later
+// logout() would answer 401 PORTAL_SESSION_INVALID):
+await medal.portal.deleteMe(session.session_token);   // GDPR Art. 17 — 204
+```
+
+`401 PORTAL_SESSION_REQUIRED` (header missing) and `401 PORTAL_SESSION_INVALID` (unknown, expired or revoked) both mean "sign in again" — clear the cookie and send the customer back to step 1. `403 FORBIDDEN` means the key lacks the portal scopes; `429 RATE_LIMITED` applies per address and per caller on `login.start`.
+
+None of the portal calls carries an `Idempotency-Key`: the two login routes cannot duplicate anything, and the session routes are either reads or terminal.
+
 ### GDPR
 
 ```ts