@medalsocial/sdk 1.5.0 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # Medal Social SDK
 
-TypeScript SDK for the [Medal Social](https://medalsocial.com) API. Manage posts, emails, contacts, deals, helpdesk conversations, webhooks, and GDPR compliance programmatically.
+TypeScript SDK for the [Medal Social](https://medalsocial.com) API. Manage posts, emails, contacts, deals, helpdesk conversations, webhooks, company/site scans, and GDPR compliance programmatically.
 
 ## Install
 
@@ -204,6 +204,74 @@ 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.
+
 ### GDPR
 
 ```ts
@@ -236,6 +304,22 @@ await medal.gdpr.cookieConsent({
 });
 ```
 
+### Scan
+
+```ts
+// Find the company in the Norwegian registry (typeahead)
+const { data: hits } = await medal.scan.companies('Eksempel Bygg');
+
+// Queue a scan — exactly one of url / orgnr / name
+const { data: job } = await medal.scan.create({ orgnr: hits[0].orgnr });
+
+// Poll until it settles (~30 s; done or failed)
+const finished = await medal.scan.waitForResult(job.id);
+if (finished.status === 'done' && finished.result) {
+  console.log(finished.result.nettskaar, finished.result.subScores);
+}
+```
+
 ### Helpdesk
 
 ```ts
@@ -269,6 +353,19 @@ const { data: reply } = await medal.helpdesk.replies.create(
 );
 ```
 
+**A `201` from `replies.create` means accepted, not delivered.** The channel hand-off happens asynchronously afterwards. Each message carries `delivery_status` (`pending` | `sent` | `delivered` | `failed`) and `delivery_error`, both `null` for inbound messages and internal notes (neither is ever sent to a channel):
+
+```ts
+const { data: messages } = await medal.helpdesk.conversations.messages('conv_id');
+for (const message of messages) {
+  if (message.delivery_status === 'failed') {
+    console.error(message.id, message.delivery_error);
+  }
+}
+```
+
+Subscribe to `helpdesk.message_delivery_updated` for the same values pushed instead of polled.
+
 ### Webhooks
 
 ```ts
@@ -298,6 +395,8 @@ await medal.webhooks.test(endpoint.id); // queues a 'test.ping' delivery
 
 Failed deliveries retry with exponential backoff (up to 6 attempts) before being dead-lettered.
 
+`deliveries()` returns the most recent attempts only — it takes a `limit` and is **not** cursor-paginated. A delivery's `id` is the same value sent as the `X-Medal-Delivery-Id` and `Idempotency-Key` headers on the outbound request, so you can join your own receiving log to this listing exactly. Deliveries **never carry payload bodies** (payloads can contain customer PII); instead each one exposes correlation fields — `resource_id`, `conversation_id`, `message_id`, `connection_ref`, `channel`, `channel_connection_id` — that let you look the subject up through the regular API. All six are nullable and **fail closed to `null`** when no canonical event exists for the delivery (e.g. `test.ping` deliveries, or events that have aged out of retention), so always null-check them.
+
 ### Channels (partner connect)
 
 Mint hosted connect links that let an external person — e.g. a partner's operator, with no Medal account — attach a channel account (today `telegram_inbox`) to the workspace's helpdesk, then track and disconnect the resulting connections. Requires the `channel.connect.manage` scope; OAuth callers additionally need the workspace `admin` role for the writes.
@@ -324,10 +423,123 @@ await medal.channels.connectLinks.revoke(link.id);
 const { data: connections } = await medal.channels.connections.list();
 // state: 'connecting' | 'active' | 'disconnected' | 'disabled'
 await medal.channels.connections.disconnect(connections[0].id);
+
+// Both listings are cursor-paginated (limit defaults to 50, capped at 100)
+let cursor: string | undefined;
+do {
+  const page = await medal.channels.connections.list({ limit: 100, cursor });
+  for (const connection of page.data) console.log(connection.id, connection.state);
+  cursor = page.pagination.has_more ? page.pagination.next_cursor ?? undefined : undefined;
+} while (cursor);
 ```
 
+Filters (`channel_type`, `status`) are applied **within** each page, so a page may hold fewer than `limit` items while `pagination.has_more` is still `true` — drive the loop off `has_more`, never off the item count.
+
 When the person completes the hosted sign-in, the link flips to `consumed` and your webhook endpoint receives `helpdesk.channel_connected` (subscribe via the Webhooks resource above); disconnects emit `helpdesk.channel_disconnected` with a `reason`. Inbound messages on the connected account then flow into the helpdesk — consume them via `helpdesk.message_received` and reply with `medal.helpdesk.replies.create`.
 
+### Capability confirmations
+
+Medal's confirmable write routes require **both** an `Idempotency-Key` and an `X-Capability-Confirmation` token whenever the calling credential holds the capability scope *directly* — which is the case for every correctly-scoped partner key and OAuth grant. (API keys carrying only legacy scopes are exempt.) Affected routes and their capability ids:
+
+| Capability id | Route |
+|---|---|
+| `channel.connect_link.create.execute` | `POST /api/v1/channels/connect-links` |
+| `channel.connect_link.revoke.execute` | `DELETE /api/v1/channels/connect-links/{id}` |
+| `channel.connection.disconnect.execute` | `DELETE /api/v1/channels/connections/{id}` |
+| `helpdesk.conversation.reply.execute` | `POST /api/v1/helpdesk/replies` |
+| `helpdesk.conversation.update.execute` | `PATCH /api/v1/helpdesk/conversations/{id}` |
+| `helpdesk.webhook.create.execute` | `POST /api/v1/webhooks` |
+| `helpdesk.webhook.update.execute` | `PATCH /api/v1/webhooks/{id}` |
+| `helpdesk.webhook.delete.execute` | `DELETE /api/v1/webhooks/{id}` |
+
+These are exported as `CAPABILITY_IDS` (a typed union via `CapabilityId`) and `CAPABILITY_ROUTES`.
+
+#### Explicit flow
+
+```ts
+const idempotencyKey = crypto.randomUUID();
+
+const { data: confirmation } = await medal.capabilityConfirmations.create({
+  capability_id: 'channel.connect_link.create.execute',
+  idempotency_key: idempotencyKey,   // the token is bound to this exact key
+  preview_summary: 'Mint a Telegram connect link for Acme Support',
+  user_approved: true,               // a human on your side approved this action
+});
+
+const { data: link } = await medal.channels.connectLinks.create(
+  { channel_type: 'telegram_inbox', label: 'Acme Support' },
+  { idempotencyKey, capabilityConfirmation: confirmation.confirmation_token },
+);
+```
+
+For an id-bound route, pass `path_params` so the token binds to the concrete path:
+
+```ts
+const { data: confirmation } = await medal.capabilityConfirmations.create({
+  capability_id: 'channel.connection.disconnect.execute',
+  path_params: { id: connectionId },
+  idempotency_key: idempotencyKey,
+  preview_summary: `Disconnect ${connectionId} — approved by ${operator.email}`,
+  user_approved: true,
+});
+
+await medal.channels.connections.disconnect(connectionId, {
+  idempotencyKey,
+  capabilityConfirmation: confirmation.confirmation_token,
+});
+```
+
+Tokens expire within 15 minutes and are single-purpose: bound to the workspace, the auth subject, the method + path, the capability's required scopes, and the idempotency key.
+
+#### Auto-confirm (opt-in, off by default)
+
+If your integration already gates these writes behind a real human approval, let the SDK mint both halves for you:
+
+```ts
+const medal = new Medal(process.env.MEDAL_API_KEY, {
+  autoConfirmCapabilities: {
+    previewSummary: (ctx) => {
+      // `ctx` is a discriminated union on `capabilityId` — narrowing gives you
+      // the exact request payload type, so the summary can describe the
+      // specific action rather than just the route.
+      switch (ctx.capabilityId) {
+        case 'channel.connect_link.create.execute':
+          return `${operator.email} approved a ${ctx.body.channel_type} connect link for "${ctx.body.label}"`;
+        case 'helpdesk.conversation.reply.execute':
+          return `${operator.email} approved replying to ${ctx.body.conversation_id}: "${ctx.body.body}"`;
+        default:
+          // DELETE routes have no body; identify them by path instead.
+          return `${operator.email} approved ${ctx.method} ${ctx.path}`;
+      }
+    },
+  },
+});
+
+// Both headers are minted and attached automatically.
+const { data: link } = await medal.channels.connectLinks.create({
+  channel_type: 'telegram_inbox',
+  label: 'Acme Support',
+});
+```
+
+The callback receives `{ capabilityId, method, path, pathParams, idempotencyKey, body }`. `body` is the exact object you passed to the SDK method, by reference and unmodified — treat it as read-only, since mutating it would change what is actually sent. Prefer a payload-aware summary: `"Reply to conv_1: 'Refund issued'"` is an audit record, `"POST /api/v1/helpdesk/replies"` is not. The server caps `preview_summary` at 4000 characters, so summarise the payload rather than serialising it wholesale.
+
+> **Read before enabling.** Every minted token carries `user_approved: true`, which asserts to Medal that *a human on your side approved that specific action*, and the `previewSummary` you return is retained as the audit record of what they approved. Enable it only on code paths where that is genuinely true — never to rubber-stamp unattended writes. Returning a blank summary throws rather than asserting an approval with no description.
+
+Per-call control:
+
+```ts
+// Opt in for one call only (client default stays off)
+await medal.webhooks.delete(endpointId, {
+  autoConfirm: { previewSummary: () => `${operator.email} approved removing ${endpointId}` },
+});
+
+// Opt out of a client-level default for one call
+await medal.webhooks.delete(endpointId, { autoConfirm: false });
+```
+
+Auto-confirm never overrides what you supply: if a call already carries both `idempotencyKey` and `capabilityConfirmation`, nothing is minted. If it carries only `idempotencyKey`, that key is reused when binding the token.
+
 ### Workspaces
 
 ```ts