@medalsocial/sdk 1.7.0 → 1.8.0

package/openapi/medal-social.openapi.yaml

@@ -26,6 +26,11 @@ tags:
       Appointment bookings — the service catalogue, free slots, staff actions
       on a booking, and the customer-facing manage-token routes. Money is
       always integer øre.
+  - name: Portal
+    description: >-
+      Customer self-service portal — e-mail one-time-code login, then
+      session-bound access to the signed-in contact's own profile, bookings,
+      data export and erasure. Session routes carry `X-Portal-Session`.
   - name: GDPR
     description: Manage exports, consent records, and cookie consent.
   - name: Workspaces
@@ -898,6 +903,184 @@ paths:
                 $ref: "#/components/schemas/ApiResponse_BookingRescheduleResult"
         default:
           $ref: "#/components/responses/ApiError"
+  /api/v1/portal/login/start:
+    post:
+      tags: [Portal]
+      operationId: startPortalLogin
+      summary: E-mail a one-time login code
+      description: >-
+        Always answers 202 `{ status: "sent" }`, whether or not the address
+        belongs to a contact — enumeration-safe by design. Rate-limited per
+        address and per caller (`429 RATE_LIMITED`). Not idempotency-keyed.
+        Errors: `400 VALIDATION_ERROR`, `403 FORBIDDEN` (key lacks
+        `write:portal`), `429 RATE_LIMITED`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PortalLoginStartInput"
+      responses:
+        "202":
+          description: Code queued (or silently not, for an unknown address).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_PortalLoginStartResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/portal/login/verify:
+    post:
+      tags: [Portal]
+      operationId: verifyPortalLogin
+      summary: Exchange the e-mailed code for a session
+      description: >-
+        A wrong, burned or expired code all answer `401 PORTAL_CODE_INVALID` —
+        the three are not distinguished, so the response is not an oracle for
+        which codes exist. The returned `session_token` is a bearer credential
+        for ONE contact: keep it in an HttpOnly cookie on the site's server and
+        never hand it to the browser. Not idempotency-keyed. Errors:
+        `400 VALIDATION_ERROR`, `401 PORTAL_CODE_INVALID`, `403 FORBIDDEN`,
+        `429 RATE_LIMITED`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PortalVerifyInput"
+      responses:
+        "200":
+          description: The new session.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_PortalSession"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/portal/logout:
+    parameters:
+      - $ref: "#/components/parameters/PortalSession"
+    post:
+      tags: [Portal]
+      operationId: logoutPortal
+      summary: Revoke the session
+      description: >-
+        Revoking twice reaches the same state — the second call answers
+        `401 PORTAL_SESSION_INVALID`. Not idempotency-keyed. Errors:
+        `401 PORTAL_SESSION_REQUIRED` (header missing),
+        `401 PORTAL_SESSION_INVALID` (unknown, expired or revoked),
+        `403 FORBIDDEN`, `429 RATE_LIMITED`.
+      responses:
+        "204":
+          description: Session revoked.
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/portal/me:
+    parameters:
+      - $ref: "#/components/parameters/PortalSession"
+    get:
+      tags: [Portal]
+      operationId: getPortalProfile
+      summary: The signed-in contact's profile
+      description: >-
+        Errors: `401 PORTAL_SESSION_REQUIRED`, `401 PORTAL_SESSION_INVALID`,
+        `403 FORBIDDEN` (key lacks `read:portal`), `429 RATE_LIMITED`.
+      responses:
+        "200":
+          description: Profile.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_PortalProfile"
+        default:
+          $ref: "#/components/responses/ApiError"
+    patch:
+      tags: [Portal]
+      operationId: updatePortalProfile
+      summary: Update the signed-in contact's profile
+      description: >-
+        Only the supplied fields change. `phone: null` clears the number,
+        `family` replaces the whole list, and `marketing_consent` records a
+        `marketing_email` consent decision with source `portal`. Answers the
+        profile as it is after the change. Errors: `400 VALIDATION_ERROR`,
+        `401 PORTAL_SESSION_REQUIRED`, `401 PORTAL_SESSION_INVALID`,
+        `403 FORBIDDEN` (key lacks `write:portal`), `429 RATE_LIMITED`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PortalProfilePatch"
+      responses:
+        "200":
+          description: Updated profile.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_PortalProfile"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/portal/me/bookings:
+    parameters:
+      - $ref: "#/components/parameters/PortalSession"
+    get:
+      tags: [Portal]
+      operationId: listPortalBookings
+      summary: The signed-in contact's bookings
+      description: >-
+        Split into `upcoming` and `past`. An upcoming booking still inside the
+        workspace's policy windows carries `manage_token` and
+        `can_manage: true`; the token opens the site's manage page. Errors:
+        `401 PORTAL_SESSION_REQUIRED`, `401 PORTAL_SESSION_INVALID`,
+        `403 FORBIDDEN`, `429 RATE_LIMITED`.
+      responses:
+        "200":
+          description: Bookings.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_PortalBookings"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/portal/me/export:
+    parameters:
+      - $ref: "#/components/parameters/PortalSession"
+    post:
+      tags: [Portal]
+      operationId: exportPortalData
+      summary: Export everything held about the signed-in contact
+      description: >-
+        A synchronous GDPR Art. 15 export of the contact's profile, family,
+        consents and bookings, as one JSON document. Read-only, so not
+        idempotency-keyed. Errors: `401 PORTAL_SESSION_REQUIRED`,
+        `401 PORTAL_SESSION_INVALID`, `403 FORBIDDEN`, `429 RATE_LIMITED`.
+      responses:
+        "200":
+          description: The export.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_PortalExport"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/portal/me/delete:
+    parameters:
+      - $ref: "#/components/parameters/PortalSession"
+    post:
+      tags: [Portal]
+      operationId: deletePortalAccount
+      summary: Erase the signed-in contact
+      description: >-
+        GDPR Art. 17 erasure. The session is revoked as part of the deletion,
+        so a retry answers `401 PORTAL_SESSION_INVALID` rather than deleting
+        anything else. Not idempotency-keyed. Errors:
+        `401 PORTAL_SESSION_REQUIRED`, `401 PORTAL_SESSION_INVALID`,
+        `403 FORBIDDEN` (key lacks `write:portal`), `429 RATE_LIMITED`.
+      responses:
+        "204":
+          description: Contact erased and session revoked.
+        default:
+          $ref: "#/components/responses/ApiError"
   /api/v1/gdpr/export:
     post:
       tags: [GDPR]
@@ -1541,6 +1724,18 @@ components:
         Possession of it authorizes the customer's own cancel or reschedule.
       schema:
         type: string
+    PortalSession:
+      name: X-Portal-Session
+      in: header
+      required: true
+      description: >-
+        The `session_token` returned by `verifyPortalLogin`. A bearer
+        credential for ONE contact — the site's server keeps it in an HttpOnly
+        cookie and forwards it here. Missing answers
+        `401 PORTAL_SESSION_REQUIRED`; unknown, expired or revoked answers
+        `401 PORTAL_SESSION_INVALID`.
+      schema:
+        type: string
     Cursor:
       name: cursor
       in: query
@@ -3615,6 +3810,16 @@ components:
       $ref: "#/components/schemas/Envelope_BookingRescheduleResult"
     ApiResponse_ManageSummary:
       $ref: "#/components/schemas/Envelope_ManageSummary"
+    ApiResponse_PortalLoginStartResult:
+      $ref: "#/components/schemas/Envelope_PortalLoginStartResult"
+    ApiResponse_PortalSession:
+      $ref: "#/components/schemas/Envelope_PortalSession"
+    ApiResponse_PortalProfile:
+      $ref: "#/components/schemas/Envelope_PortalProfile"
+    ApiResponse_PortalBookings:
+      $ref: "#/components/schemas/Envelope_PortalBookings"
+    ApiResponse_PortalExport:
+      $ref: "#/components/schemas/Envelope_PortalExport"
     ApiResponse_GdprExportRequest:
       $ref: "#/components/schemas/Envelope_GdprExportRequest"
     ApiResponse_GdprExportArray:
@@ -3946,6 +4151,247 @@ components:
       properties:
         data:
           $ref: "#/components/schemas/ManageSummary"
+    PortalLoginStartInput:
+      type: object
+      required: [email]
+      properties:
+        email:
+          type: string
+          format: email
+          description: The address the code is sent to.
+        locale:
+          type: string
+          description: Locale for the e-mail (e.g. `nb`, `en`); the workspace default when omitted.
+    PortalLoginStartResult:
+      description: >-
+        Always `sent`, whether or not the address is a known contact — the
+        route is enumeration-safe by design.
+      type: object
+      required: [status]
+      properties:
+        status:
+          type: string
+          const: sent
+    PortalVerifyInput:
+      type: object
+      required: [email, code]
+      properties:
+        email:
+          type: string
+          format: email
+        code:
+          type: string
+          description: The one-time code from the e-mail.
+    PortalContactSummary:
+      type: object
+      required: [contact_id, first_name]
+      properties:
+        contact_id:
+          type: string
+        first_name:
+          type: [string, "null"]
+    PortalSession:
+      description: >-
+        A portal session. `session_token` is a bearer credential for ONE
+        contact — keep it in an HttpOnly cookie on the site's server and never
+        hand it to the browser.
+      type: object
+      required: [session_token, expires_at, contact]
+      properties:
+        session_token:
+          type: string
+        expires_at:
+          type: integer
+          description: Unix timestamp in milliseconds.
+        contact:
+          $ref: "#/components/schemas/PortalContactSummary"
+    PortalFamilyMember:
+      type: object
+      required: [name, birth_year]
+      properties:
+        name:
+          type: string
+        birth_year:
+          type: integer
+    PortalProfile:
+      type: object
+      required:
+        - contact_id
+        - email
+        - first_name
+        - last_name
+        - phone
+        - family
+        - marketing_consent
+        - created_at
+      properties:
+        contact_id:
+          type: string
+        email:
+          type: string
+        first_name:
+          type: [string, "null"]
+        last_name:
+          type: [string, "null"]
+        phone:
+          type: [string, "null"]
+        family:
+          type: array
+          items:
+            $ref: "#/components/schemas/PortalFamilyMember"
+        marketing_consent:
+          type: boolean
+        created_at:
+          type: integer
+          description: Unix timestamp in milliseconds.
+    PortalProfilePatch:
+      description: Only the supplied fields change.
+      type: object
+      properties:
+        first_name:
+          type: string
+        last_name:
+          type: string
+        phone:
+          type: [string, "null"]
+          description: "`null` clears the number."
+        family:
+          type: array
+          description: Replaces the whole list.
+          items:
+            $ref: "#/components/schemas/PortalFamilyMember"
+        marketing_consent:
+          type: boolean
+          description: Records a `marketing_email` consent change with source `portal`.
+    PortalBooking:
+      type: object
+      required:
+        - booking_id
+        - status
+        - start_ts
+        - end_ts
+        - service_id
+        - service_name
+        - resource_id
+        - resource_name
+        - booked_for_name
+        - amount_ore
+        - notes
+        - manage_token
+        - can_manage
+      properties:
+        booking_id:
+          type: string
+        status:
+          $ref: "#/components/schemas/BookingStatus"
+        start_ts:
+          type: integer
+          description: Unix timestamp in milliseconds.
+        end_ts:
+          type: integer
+          description: Unix timestamp in milliseconds.
+        service_id:
+          type: [string, "null"]
+        service_name:
+          type: [string, "null"]
+        resource_id:
+          type: [string, "null"]
+        resource_name:
+          type: [string, "null"]
+        booked_for_name:
+          type: [string, "null"]
+        amount_ore:
+          type: [integer, "null"]
+          description: Integer øre, or `null` when the service has no price.
+        notes:
+          type: [string, "null"]
+        manage_token:
+          type: [string, "null"]
+          description: >-
+            Present only while the booking is upcoming and manageable; opens
+            the site's manage page.
+        can_manage:
+          type: boolean
+    PortalBookings:
+      type: object
+      required: [upcoming, past]
+      properties:
+        upcoming:
+          type: array
+          items:
+            $ref: "#/components/schemas/PortalBooking"
+        past:
+          type: array
+          items:
+            $ref: "#/components/schemas/PortalBooking"
+    PortalConsentRecord:
+      type: object
+      required: [consent_type, granted, granted_at, revoked_at, source]
+      properties:
+        consent_type:
+          type: string
+        granted:
+          type: boolean
+        granted_at:
+          type: [integer, "null"]
+          description: Unix timestamp in milliseconds, or `null`.
+        revoked_at:
+          type: [integer, "null"]
+          description: Unix timestamp in milliseconds, or `null`.
+        source:
+          type: string
+    PortalExport:
+      description: Everything the workspace holds about the signed-in contact (GDPR Art. 15).
+      type: object
+      required: [exported_at, contact, family, consents, bookings]
+      properties:
+        exported_at:
+          type: integer
+          description: Unix timestamp in milliseconds.
+        contact:
+          $ref: "#/components/schemas/PortalProfile"
+        family:
+          type: array
+          items:
+            $ref: "#/components/schemas/PortalFamilyMember"
+        consents:
+          type: array
+          items:
+            $ref: "#/components/schemas/PortalConsentRecord"
+        bookings:
+          type: array
+          items:
+            $ref: "#/components/schemas/PortalBooking"
+    Envelope_PortalLoginStartResult:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/PortalLoginStartResult"
+    Envelope_PortalSession:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/PortalSession"
+    Envelope_PortalProfile:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/PortalProfile"
+    Envelope_PortalBookings:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/PortalBookings"
+    Envelope_PortalExport:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/PortalExport"
     ScanCreateInput:
       type: object
       description: Provide exactly one of `url`, `orgnr`, or `name`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medalsocial/sdk",
-  "version": "1.7.0",
+  "version": "1.8.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",

package/skills/client/SKILL.md

@@ -57,6 +57,8 @@ Every request gets:
 - `x-workspace-id: <workspaceId>` (only if `workspaceId` was set on the constructor)
 - `User-Agent: medalsocial-sdk/<version>` (best-effort — browsers reject custom User-Agent; the SDK swallows that error silently)
 
+Per-call extras go in `RequestOptions.headers` (accepted by `get`, `post`, `postOnce`, `patch`, `delete` on `BaseClient`). The named options win over a same-named bag entry: `{ headers: { "idempotency-key": "a" }, idempotencyKey: "b" }` sends `b`. The SDK uses this itself for the customer portal's `X-Portal-Session` header — you never set that one by hand; pass the session token to `medal.portal.*` instead. Bag keys are lower-cased before the protected names (`content-type`, the named options) are applied, so capitalisation cannot smuggle a duplicate past them. `retry: false` sends a request exactly once (no 429/5xx retry) on every verb (`post`, `patch`, `delete`) — used by `portal.login.verify`, `portal.logout` and `portal.deleteMe`, where the first attempt may have consumed the code or revoked the session and a retry would misreport success as failure, and by `portal.updateMe`, where a `marketing_consent` change records a consent event a retry would repeat.
+
 ## Retry behavior
 
 `BaseClient.request` retries on **429 and 5xx** for up to **3 attempts total**:

package/skills/resources/SKILL.md

@@ -1,19 +1,20 @@
 ---
 name: resources
-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`.
+description: Use when calling any of the SDK resources (bookings, contacts, deals, emails, gdpr, portal, 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, signing a customer into the self-service portal and reading their own profile/bookings/export, 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.bookings.*`, `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.portal.*`, `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).
+- Building a customer self-service portal: e-mail code login, then the signed-in contact's own profile, bookings, export and erasure.
 - Importing contacts from a CSV-like source.
 - Needing OpenAPI-derived types for a custom fetch wrapper, generated mocks, or contract tests.
 
@@ -42,6 +43,8 @@ Errors throw `MedalApiError` (see the `client` skill for details).
 | `medal.emails.templates` | `src/resources/emails.ts` (`EmailTemplates`) | `list()`, `get(slug, opts?)` |
 | `medal.emails` | `src/resources/emails.ts` (`Emails`) | `send(input)`, `get(id)`, `batch(input)` |
 | `medal.gdpr` | `src/resources/gdpr.ts` | `requestExport()`, `listExports()`, `getExport(id)`, `recordConsent(input)`, `getConsent(email)`, `cookieConsent(input)` |
+| `medal.portal.login` | `src/resources/portal.ts` (`PortalLogin`) | `start({ email, locale? })` (always 202 `{ status: 'sent' }`), `verify({ email, code })` → `PortalSession` |
+| `medal.portal` | `src/resources/portal.ts` | `me(session)`, `updateMe(session, patch)`, `myBookings(session)`, `exportMyData(session)`, `deleteMe(session)`, `logout(session)` — every one takes the `session_token` first and sends it as `X-Portal-Session`; `deleteMe`/`logout` resolve to `undefined` (204) |
 | `medal.scan` | `src/resources/scan.ts` | `create(input)` (exactly one of `url`/`orgnr`/`name`; 202 async job), `get(id)`, `companies(q)` (Norwegian registry typeahead), `waitForResult(id, opts?)` (polls until done/failed; returns the job either way, throws only on deadline) |
 | `medal.posts` | `src/resources/posts.ts` | `list(opts?)`, `create(input)`, `get(id)`, `update(id, input)`, `remove(id)`, `schedule(id, input)`, `publish(id)`, `channels()` |
 | `medal.workspaces` | `src/resources/workspaces.ts` | `list()` |
@@ -223,6 +226,45 @@ const { data: summary } = await medal.emails.batch({
 
 For more than 100 recipients, chunk into multiple `batch()` calls. There is no built-in chunker.
 
+## Customer portal — e-mail code login, then session-bound self-service
+
+`medal.portal` is for the workspace's **own customers**, not staff. A customer proves they own an e-mail address, gets a session, and can then see and change what the workspace holds about *them* — profile, family members, bookings, consents — export it, or erase it. The API key needs `read:portal` + `write:portal` (`403 FORBIDDEN` otherwise).
+
+**The session token is a bearer credential for ONE contact.** `verify()` returns it once; your site's *server* keeps it in an HttpOnly, Secure cookie on the site's own domain and forwards it on every call. Never send it to the browser as JSON, never put it in a URL, and never let the browser call Medal directly — the API key would leak with it.
+
+```ts
+// Step 1 — send the code. ALWAYS { status: 'sent' }, whether or not the address is a
+// contact: enumeration-safe, so do not treat "sent" as "this customer exists".
+await medal.portal.login.start({ email, locale: 'nb' });
+
+// Step 2 — exchange the code. Wrong, burned and expired codes ALL answer
+// 401 PORTAL_CODE_INVALID; there is no way to tell them apart, by design.
+const { data: session } = await medal.portal.login.verify({ email, code });
+cookies.set('portal_session', session.session_token, {
+  httpOnly: true, secure: true, sameSite: 'lax', expires: new Date(session.expires_at),
+});
+
+// Step 3 — session-bound calls, token read back from the cookie
+const token = cookies.get('portal_session');
+const { data: me } = await medal.portal.me(token);
+const { data: mine } = await medal.portal.myBookings(token);          // { upcoming, past }
+await medal.portal.updateMe(token, { family: [{ name: 'Ola', birth_year: 2018 }] });
+const { data: exported } = await medal.portal.exportMyData(token);    // GDPR Art. 15 — synchronous JSON
+await medal.portal.logout(token);                                     // 204 — revokes this session only
+// …or, terminal (a later logout() on the same token answers 401 PORTAL_SESSION_INVALID):
+await medal.portal.deleteMe(token);                                   // GDPR Art. 17 — 204
+```
+
+**`myBookings` hands you manage tokens.** An `upcoming` booking still inside the workspace's policy windows carries `manage_token` (string) and `can_manage: true`; everything else has `manage_token: null`. Use it with `medal.bookings.manage.*` — the customer routes, where the windows are enforced — never with the id-addressed staff routes.
+
+**`updateMe` is a partial patch.** Only supplied fields change; `phone: null` clears the number; `family` replaces the whole list (send the full new list, not the delta); `marketing_consent` records a `marketing_email` consent decision with source `portal`, so it shows up in `medal.gdpr.getConsent(email)`.
+
+**Two 401s, one meaning.** `PORTAL_SESSION_REQUIRED` (header missing) and `PORTAL_SESSION_INVALID` (unknown, expired, revoked — including after `deleteMe` or `logout`) both mean "sign in again": clear the cookie and send the customer back to step 1. Do not retry them.
+
+**Nothing here is idempotency-keyed.** The login routes cannot duplicate anything (a retried `start` sends at most one more code; a retried `verify` meets a burned code), `me`/`myBookings`/`exportMyData` are reads, and `logout`/`deleteMe` are terminal — a retry meets a revoked session. Passing `idempotencyKey` is not possible on these methods and would change nothing if it were.
+
+**Portal export vs. GDPR export.** `medal.portal.exportMyData(token)` is one contact's data, synchronous, returned inline. `medal.gdpr.requestExport()` is the whole *workspace*, asynchronous, polled via `getExport`. They are not interchangeable.
+
 ## GDPR — consent + export workflow
 
 **Consent (per-contact):**
@@ -340,4 +382,10 @@ The `with { type: "json" }` import-attribute syntax requires Node 24+ or a bundl
 | `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 |
+| Sending `session_token` to the browser (JSON, URL, non-HttpOnly cookie) | It is a bearer credential for that contact — whoever holds it is them | HttpOnly, Secure cookie on the site's server; the server calls `medal.portal.*` |
+| Treating `login.start` → `{ status: 'sent' }` as "this customer exists" | Enumeration-safe: unknown addresses answer `sent` too | Show "check your e-mail" unconditionally |
+| Branching on why `verify` failed | Wrong, burned and expired codes all answer `PORTAL_CODE_INVALID` | One message: "that code did not work — request a new one" |
+| Retrying a `PORTAL_SESSION_INVALID` | The session is gone (expired, revoked, or the contact was deleted) | Clear the cookie and restart the login |
+| Passing a portal `manage_token` to `medal.bookings.cancel(id)` | Wrong route: staff semantics, and it takes an id not a token | `medal.bookings.manage.cancel(manage_token)` |
+| `updateMe(token, { family: [newMember] })` to add one member | `family` REPLACES the list — the others are dropped | Send the full list: `[...me.family, newMember]` |
 | Building a custom client when only types are needed | Reinventing the wheel | Import from `@medalsocial/sdk/openapi-types` |