@medalsocial/sdk 1.6.0 → 1.8.0

package/openapi/medal-social.openapi.yaml

@@ -21,6 +21,16 @@ tags:
     description: Manage workspace CRM contacts.
   - name: Deals
     description: Manage sponsorship and brand deals.
+  - name: Bookings
+    description: >-
+      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
@@ -543,6 +553,534 @@ paths:
                 $ref: "#/components/schemas/ApiResponse_DealRemoveResult"
         default:
           $ref: "#/components/responses/ApiError"
+  /api/v1/bookings:
+    get:
+      tags: [Bookings]
+      operationId: listBookings
+      summary: List bookings
+      parameters:
+        - $ref: "#/components/parameters/Limit"
+        - $ref: "#/components/parameters/Cursor"
+        - name: from_ts
+          in: query
+          description: Only bookings starting at or after this instant.
+          schema:
+            $ref: "#/components/schemas/BookingTimestampInput"
+        - name: to_ts
+          in: query
+          description: Only bookings starting before this instant.
+          schema:
+            $ref: "#/components/schemas/BookingTimestampInput"
+        - name: status
+          in: query
+          schema:
+            $ref: "#/components/schemas/BookingStatus"
+        - name: resource_id
+          in: query
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Bookings page.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PaginatedResponse_Booking"
+        default:
+          $ref: "#/components/responses/ApiError"
+    post:
+      tags: [Bookings]
+      operationId: createBooking
+      summary: Create a booking or party
+      description: >-
+        Books every item or none of them. Each created booking carries a
+        `manage_token` returned exactly once — only its hash is stored, and an
+        idempotent replay omits it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateBookingInput"
+      responses:
+        "201":
+          description: Created bookings, in request order.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingCreateResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/services:
+    get:
+      tags: [Bookings]
+      operationId: listBookingServices
+      summary: List bookable services
+      parameters:
+        - name: include_inactive
+          in: query
+          description: >-
+            Include services with `active: false`. Defaults to active-only.
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: Bookable service catalogue.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingServiceArray"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/resources:
+    get:
+      tags: [Bookings]
+      operationId: listBookingResources
+      summary: List bookable resources
+      responses:
+        "200":
+          description: Bookable resources — staff, rooms, and equipment.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingResourceArray"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/availability:
+    get:
+      tags: [Bookings]
+      operationId: listBookingAvailability
+      summary: List free slots for a service
+      description: >-
+        Slots reflect opening hours, time off, buffers, and existing bookings
+        at the moment of the call. They are not held.
+      parameters:
+        - name: service_id
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: from_ts
+          in: query
+          required: true
+          description: Start of the window.
+          schema:
+            $ref: "#/components/schemas/BookingTimestampInput"
+        - name: to_ts
+          in: query
+          required: true
+          description: End of the window; must be after `from_ts`.
+          schema:
+            $ref: "#/components/schemas/BookingTimestampInput"
+        - name: resource_id
+          in: query
+          description: Restrict slots to one resource.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Free slots.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingSlotArray"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/schedule:
+    get:
+      tags: [Bookings]
+      operationId: listBookingSchedule
+      summary: List the dates a service can be booked on
+      description: >-
+        The other half of `availability`. Availability returns free slots and
+        nothing else, so a closed day, an evening past closing and a fully
+        booked day all come back as the same empty array. This returns one
+        entry per date the workspace keeps opening hours on; a date ABSENT from
+        the response is closed. `last_start_ts` is the last start this service
+        could occupy on that date (it depends on the service's duration and
+        buffers, not just the closing time) and is `null` for a date with
+        posted hours that is shut outright, such as a public holiday.
+      parameters:
+        - name: service_id
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: from_ts
+          in: query
+          required: true
+          description: Start of the window.
+          schema:
+            $ref: "#/components/schemas/BookingTimestampInput"
+        - name: to_ts
+          in: query
+          required: true
+          description: End of the window; must be after `from_ts`.
+          schema:
+            $ref: "#/components/schemas/BookingTimestampInput"
+        - name: resource_id
+          in: query
+          description: Restrict to one resource's hours.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Open dates.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingScheduleDayArray"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/{id}:
+    parameters:
+      - $ref: "#/components/parameters/Id"
+    get:
+      tags: [Bookings]
+      operationId: getBooking
+      summary: Get a booking
+      responses:
+        "200":
+          description: Booking.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_Booking"
+        default:
+          $ref: "#/components/responses/ApiError"
+    patch:
+      tags: [Bookings]
+      operationId: updateBooking
+      summary: Annotate a booking
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateBookingInput"
+      responses:
+        "200":
+          description: The updated booking.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_Booking"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/{id}/cancel:
+    parameters:
+      - $ref: "#/components/parameters/Id"
+    post:
+      tags: [Bookings]
+      operationId: cancelBooking
+      summary: Cancel a booking as the business
+      description: >-
+        Staff semantics — the workspace's cancel window is bypassed and the
+        cancellation is attributed to staff.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CancelBookingInput"
+      responses:
+        "200":
+          description: Cancel result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingActionResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/{id}/reschedule:
+    parameters:
+      - $ref: "#/components/parameters/Id"
+    post:
+      tags: [Bookings]
+      operationId: rescheduleBooking
+      summary: Reschedule a booking as the business
+      description: >-
+        Staff semantics — the reschedule window is bypassed. The old booking is
+        cancelled and a new one inserted, so the response carries a new booking
+        id and a freshly minted manage token.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RescheduleBookingInput"
+      responses:
+        "200":
+          description: Reschedule result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingRescheduleResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/{id}/no-show:
+    parameters:
+      - $ref: "#/components/parameters/Id"
+    post:
+      tags: [Bookings]
+      operationId: markBookingNoShow
+      summary: Mark a booking as a no-show
+      responses:
+        "200":
+          description: No-show result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingActionResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/manage/{token}:
+    parameters:
+      - $ref: "#/components/parameters/ManageToken"
+    get:
+      tags: [Bookings]
+      operationId: getManagedBooking
+      summary: Get the customer manage summary for a token
+      responses:
+        "200":
+          description: >-
+            Manage summary. An unknown token and a token belonging to another
+            workspace both answer 404, so this is not an existence oracle.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_ManageSummary"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/manage/{token}/cancel:
+    parameters:
+      - $ref: "#/components/parameters/ManageToken"
+    post:
+      tags: [Bookings]
+      operationId: cancelManagedBooking
+      summary: Cancel on the customer's behalf
+      description: >-
+        Customer semantics — the workspace's cancel window is ENFORCED and the
+        cancellation is attributed to the customer.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CancelBookingInput"
+      responses:
+        "200":
+          description: Cancel result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ApiResponse_BookingActionResult"
+        default:
+          $ref: "#/components/responses/ApiError"
+  /api/v1/bookings/manage/{token}/reschedule:
+    parameters:
+      - $ref: "#/components/parameters/ManageToken"
+    post:
+      tags: [Bookings]
+      operationId: rescheduleManagedBooking
+      summary: Reschedule on the customer's behalf
+      description: >-
+        Customer semantics — the reschedule window is ENFORCED. The response
+        carries a new booking id and a new manage token; the old token stops
+        working.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RescheduleBookingInput"
+      responses:
+        "200":
+          description: Reschedule result.
+          content:
+            application/json:
+              schema:
+                $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]
@@ -1177,6 +1715,27 @@ components:
       required: true
       schema:
         type: string
+    ManageToken:
+      name: token
+      in: path
+      required: true
+      description: >-
+        The show-once manage token handed out when the booking was created.
+        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
@@ -2035,22 +2594,512 @@ components:
           type: string
         brand_website:
           type: string
-          format: uri
+          format: uri
+        contact_id:
+          type: [string, "null"]
+        contact_name:
+          type: string
+        contact_email:
+          type: string
+          format: email
+        start_date:
+          type: string
+          format: date
+        end_date:
+          type: string
+          format: date
+        notes:
+          type: string
+    BookingTimestampInput:
+      description: >-
+        A timestamp on the way in — Unix milliseconds, or an ISO 8601
+        date-time string. Responses always render timestamps as ISO 8601.
+      type: [integer, string]
+    BookingStatus:
+      type: string
+      enum: [pending, confirmed, completed, cancelled, no_show]
+    BookingCancelledBy:
+      description: >-
+        Who cancelled. `staff` for the id-addressed cancel, `customer` for the
+        manage-token cancel, `system` for an automated one.
+      type: string
+      enum: [customer, staff, system]
+    BookingPaymentStatus:
+      type: string
+      enum: [none, reserved, captured, refunded]
+    BookingCreatedVia:
+      type: string
+      enum: [web, dashboard, walk_in, api]
+    BookingResourceType:
+      type: string
+      enum: [staff, room, equipment]
+    Booking:
+      type: object
+      required:
+        - id
+        - contact_id
+        - service_id
+        - resource_id
+        - start_ts
+        - end_ts
+        - booked_for_name
+        - booked_for_birth_year
+        - party_sequence_id
+        - status
+        - cancelled_by
+        - cancel_reason
+        - rescheduled_from_id
+        - payment_status
+        - amount_ore
+        - notes
+        - internal_notes
+        - created_via
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+        contact_id:
+          type: [string, "null"]
+        service_id:
+          type: [string, "null"]
+        resource_id:
+          type: [string, "null"]
+        start_ts:
+          type: [string, "null"]
+          format: date-time
+        end_ts:
+          type: [string, "null"]
+          format: date-time
+        booked_for_name:
+          type: [string, "null"]
+        booked_for_birth_year:
+          description: A birth year, not a birthdate — the age bracket is all that is stored.
+          type: [integer, "null"]
+        party_sequence_id:
+          description: Shared by every booking created in the same party request.
+          type: [string, "null"]
+        status:
+          $ref: "#/components/schemas/BookingStatus"
+        cancelled_by:
+          oneOf:
+            - $ref: "#/components/schemas/BookingCancelledBy"
+            - type: "null"
+        cancel_reason:
+          type: [string, "null"]
+        rescheduled_from_id:
+          description: On a booking created by a reschedule, the booking it replaced.
+          type: [string, "null"]
+        payment_status:
+          $ref: "#/components/schemas/BookingPaymentStatus"
+        amount_ore:
+          description: Price in integer øre. Never a float and never kroner.
+          type: [integer, "null"]
+        notes:
+          description: Customer-visible note.
+          type: [string, "null"]
+        internal_notes:
+          description: Staff-only note; never shown to the customer.
+          type: [string, "null"]
+        created_via:
+          oneOf:
+            - $ref: "#/components/schemas/BookingCreatedVia"
+            - type: "null"
+        created_at:
+          type: [string, "null"]
+          format: date-time
+        updated_at:
+          type: [string, "null"]
+          format: date-time
+    BookingService:
+      type: object
+      required:
+        - id
+        - name
+        - description
+        - category
+        - duration_minutes
+        - buffer_before_minutes
+        - buffer_after_minutes
+        - price_ore
+        - weekend_surcharge_pct
+        - resource_requirements
+        - bookable_online
+        - max_per_booking
+        - color
+        - sort_order
+        - active
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+        name:
+          type: [string, "null"]
+        description:
+          type: [string, "null"]
+        category:
+          type: [string, "null"]
+        duration_minutes:
+          type: [integer, "null"]
+        buffer_before_minutes:
+          type: [integer, "null"]
+        buffer_after_minutes:
+          type: [integer, "null"]
+        price_ore:
+          description: Price in integer øre.
+          type: [integer, "null"]
+        weekend_surcharge_pct:
+          type: [number, "null"]
+        resource_requirements:
+          description: Resource types this service needs, e.g. `["staff"]`.
+          type: array
+          items:
+            type: string
+        bookable_online:
+          type: boolean
+        max_per_booking:
+          type: [integer, "null"]
+        color:
+          type: [string, "null"]
+        sort_order:
+          type: [integer, "null"]
+        active:
+          type: boolean
+        created_at:
+          type: [string, "null"]
+          format: date-time
+        updated_at:
+          type: [string, "null"]
+          format: date-time
+    BookingResource:
+      type: object
+      required:
+        - id
+        - type
+        - name
+        - photo_url
+        - bio
+        - service_ids
+        - capacity
+        - sort_order
+        - active
+        - created_at
+        - updated_at
+      properties:
+        id:
+          type: string
+        type:
+          oneOf:
+            - $ref: "#/components/schemas/BookingResourceType"
+            - type: "null"
+        name:
+          type: [string, "null"]
+        photo_url:
+          type: [string, "null"]
+          format: uri
+        bio:
+          type: [string, "null"]
+        service_ids:
+          description: Services this resource can perform.
+          type: array
+          items:
+            type: string
+        capacity:
+          type: [integer, "null"]
+        sort_order:
+          type: [integer, "null"]
+        active:
+          type: boolean
+        created_at:
+          type: [string, "null"]
+          format: date-time
+        updated_at:
+          type: [string, "null"]
+          format: date-time
+    BookingSlot:
+      type: object
+      required: [start_ts, end_ts, resource_id]
+      properties:
+        start_ts:
+          type: [string, "null"]
+          format: date-time
+        end_ts:
+          type: [string, "null"]
+          format: date-time
+        resource_id:
+          type: [string, "null"]
+    BookingScheduleDay:
+      description: One date a service can be booked on. `date` is the workspace's own calendar date, not a timestamp.
+      type: object
+      required: [date, opens_ts, closes_ts, last_start_ts]
+      properties:
+        date:
+          type: [string, "null"]
+          format: date
+        opens_ts:
+          type: [string, "null"]
+          format: date-time
+        closes_ts:
+          type: [string, "null"]
+          format: date-time
+        last_start_ts:
+          description: Last start this service could occupy on the date; `null` when the date is shut outright.
+          type: [string, "null"]
+          format: date-time
+    BookingContactInput:
+      description: The person the booking is made under. Phone is the CRM dedupe key.
+      type: object
+      required: [phone]
+      properties:
+        phone:
+          type: string
+          maxLength: 40
+        email:
+          type: string
+          maxLength: 320
+        name:
+          type: string
+          maxLength: 200
+    CreateBookingItemInput:
+      description: One line of a party — a single service on a single slot.
+      type: object
+      required: [service_id, start_ts]
+      properties:
+        service_id:
+          type: string
+        resource_id:
+          description: Omit to let the engine pick a free resource.
+          type: string
+        start_ts:
+          $ref: "#/components/schemas/BookingTimestampInput"
+        booked_for_name:
+          type: string
+          maxLength: 200
+        booked_for_birth_year:
+          type: integer
+          minimum: 1900
+          maximum: 2200
+    CreateBookingInput:
+      type: object
+      required: [items, contact]
+      properties:
+        items:
+          description: >-
+            A PARTY — one request books a whole family in one all-or-nothing
+            transaction.
+          type: array
+          minItems: 1
+          maxItems: 50
+          items:
+            $ref: "#/components/schemas/CreateBookingItemInput"
+        contact:
+          $ref: "#/components/schemas/BookingContactInput"
+        notes:
+          type: string
+          maxLength: 5000
+        created_via:
+          description: >-
+            Where the booking came from. Defaults to `api`. A workspace's OWN
+            website should send `web`, so its bookings can be told apart from
+            integrations. `dashboard` and `walk_in` are staff-only and are
+            rejected with 400 — a bearer token proves which workspace is calling,
+            not that a member typed the booking in.
+          type: string
+          enum: [web, api]
+    CreatedBooking:
+      type: object
+      required: [id]
+      properties:
+        id:
+          type: string
+        manage_token:
+          description: >-
+            Show-once secret for the customer's manage link. Only its hash is
+            stored, and an idempotent replay omits this field entirely.
+          type: string
+    BookingCreateResult:
+      type: object
+      required: [bookings, contact_id]
+      properties:
+        bookings:
+          description: One entry per created booking, in request order.
+          type: array
+          items:
+            $ref: "#/components/schemas/CreatedBooking"
+        contact_id:
+          type: string
+    BookingActionResult:
+      type: object
+      required: [success]
+      properties:
+        success:
+          type: boolean
+          const: true
+    BookingRescheduleResult:
+      type: object
+      required: [success, booking_id]
+      properties:
+        success:
+          type: boolean
+          const: true
+        booking_id:
+          description: >-
+            The NEW booking's id — a reschedule cancels the old row and inserts
+            a new one.
+          type: string
+        manage_token:
+          description: >-
+            Freshly minted manage token for the new booking; omitted on an
+            idempotent replay.
+          type: string
+    ManageSummary:
+      description: >-
+        What the holder of a manage token may see and do. `can_cancel` and
+        `can_reschedule` already apply the workspace's policy windows.
+      type: object
+      required:
+        - booking_id
+        - contact_id
+        - status
+        - cancelled_by
+        - cancel_reason
+        - rescheduled_from_id
+        - start_ts
+        - end_ts
+        - service_id
+        - service_name
+        - resource_id
+        - resource_name
+        - booked_for_name
+        - party_sequence_id
+        - amount_ore
+        - payment_status
+        - time_zone
+        - cancel_window_hours
+        - reschedule_window_hours
+        - can_cancel
+        - can_reschedule
+      properties:
+        booking_id:
+          type: string
         contact_id:
           type: [string, "null"]
-        contact_name:
-          type: string
-        contact_email:
-          type: string
-          format: email
-        start_date:
-          type: string
-          format: date
-        end_date:
+        status:
+          oneOf:
+            - $ref: "#/components/schemas/BookingStatus"
+            - type: "null"
+        cancelled_by:
+          oneOf:
+            - $ref: "#/components/schemas/BookingCancelledBy"
+            - type: "null"
+        cancel_reason:
+          type: [string, "null"]
+        rescheduled_from_id:
+          type: [string, "null"]
+        start_ts:
+          type: [string, "null"]
+          format: date-time
+        end_ts:
+          type: [string, "null"]
+          format: date-time
+        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"]
+        party_sequence_id:
+          type: [string, "null"]
+        amount_ore:
+          description: Price in integer øre.
+          type: [integer, "null"]
+        payment_status:
+          oneOf:
+            - $ref: "#/components/schemas/BookingPaymentStatus"
+            - type: "null"
+        time_zone:
+          description: IANA zone the booking's local times should be rendered in.
+          type: [string, "null"]
+        cancel_window_hours:
+          type: [number, "null"]
+        reschedule_window_hours:
+          type: [number, "null"]
+        can_cancel:
+          type: boolean
+        can_reschedule:
+          type: boolean
+    UpdateBookingInput:
+      description: >-
+        At least one of `notes` or `internal_notes` is required — the API
+        rejects a body carrying neither with a 400. `""` is a meaningful value
+        that clears the field, so the constraint is on presence.
+      # Spelled out as two fully-typed branches rather than the terser
+      # `anyOf: [{required: [notes]}, {required: [internal_notes]}]`, because a
+      # branch carrying only `required` generates as `unknown` — and `T |
+      # unknown` collapses to `unknown`, which accepts everything and is worse
+      # than the unconstrained object. Each branch therefore repeats the
+      # properties so openapi-typescript emits a real discriminating union.
+      #
+      # `minProperties: 1` is deliberately absent: `anyOf` on two named
+      # properties already implies it and is strictly stronger (it also rejects
+      # `{ unrelated_key: 1 }`), so keeping both would be two statements of one
+      # invariant to drift apart.
+      anyOf:
+        - type: object
+          required: [notes]
+          properties:
+            notes:
+              description: Customer-visible note.
+              type: string
+              maxLength: 5000
+            internal_notes:
+              description: Staff-only note.
+              type: string
+              maxLength: 5000
+        - type: object
+          required: [internal_notes]
+          properties:
+            notes:
+              description: Customer-visible note.
+              type: string
+              maxLength: 5000
+            internal_notes:
+              description: Staff-only note.
+              type: string
+              maxLength: 5000
+    CancelBookingInput:
+      type: object
+      properties:
+        reason:
           type: string
-          format: date
-        notes:
+          maxLength: 500
+    RescheduleBookingInput:
+      type: object
+      required: [new_start_ts]
+      properties:
+        new_start_ts:
+          $ref: "#/components/schemas/BookingTimestampInput"
+        new_resource_id:
           type: string
+    BookingsPagination:
+      description: >-
+        Pagination for a bookings page. `truncated` is the extra statement:
+        the underlying read is capped, and when the cap binds there are
+        matching bookings no cursor from this call reaches — narrow the window.
+      type: object
+      required: [has_more, next_cursor, truncated]
+      properties:
+        has_more:
+          type: boolean
+        next_cursor:
+          type: [string, "null"]
+        truncated:
+          type: boolean
     GdprExport:
       type: object
       required: [id, request_type, status, submitted_at, completed_at]
@@ -2743,6 +3792,34 @@ components:
       $ref: "#/components/schemas/Envelope_DealUpdateResult"
     ApiResponse_DealRemoveResult:
       $ref: "#/components/schemas/Envelope_DealRemoveResult"
+    ApiResponse_Booking:
+      $ref: "#/components/schemas/Envelope_Booking"
+    ApiResponse_BookingServiceArray:
+      $ref: "#/components/schemas/Envelope_BookingServiceArray"
+    ApiResponse_BookingResourceArray:
+      $ref: "#/components/schemas/Envelope_BookingResourceArray"
+    ApiResponse_BookingSlotArray:
+      $ref: "#/components/schemas/Envelope_BookingSlotArray"
+    ApiResponse_BookingScheduleDayArray:
+      $ref: "#/components/schemas/Envelope_BookingScheduleDayArray"
+    ApiResponse_BookingCreateResult:
+      $ref: "#/components/schemas/Envelope_BookingCreateResult"
+    ApiResponse_BookingActionResult:
+      $ref: "#/components/schemas/Envelope_BookingActionResult"
+    ApiResponse_BookingRescheduleResult:
+      $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:
@@ -2832,6 +3909,16 @@ components:
             $ref: "#/components/schemas/Deal"
         pagination:
           $ref: "#/components/schemas/Pagination"
+    PaginatedResponse_Booking:
+      type: object
+      required: [data, pagination]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/Booking"
+        pagination:
+          $ref: "#/components/schemas/BookingsPagination"
     PaginatedResponse_HelpdeskConversation:
       type: object
       required: [data, pagination]
@@ -3002,6 +4089,309 @@ components:
       properties:
         data:
           $ref: "#/components/schemas/DealRemoveResult"
+    Envelope_Booking:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/Booking"
+    Envelope_BookingServiceArray:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/BookingService"
+    Envelope_BookingResourceArray:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/BookingResource"
+    Envelope_BookingSlotArray:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/BookingSlot"
+    Envelope_BookingScheduleDayArray:
+      type: object
+      required: [data]
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/BookingScheduleDay"
+    Envelope_BookingCreateResult:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/BookingCreateResult"
+    Envelope_BookingActionResult:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/BookingActionResult"
+    Envelope_BookingRescheduleResult:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/BookingRescheduleResult"
+    Envelope_ManageSummary:
+      type: object
+      required: [data]
+      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`.