@vuoma/sdk 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,45 @@
+Vuoma Connected Application License
+Version 1.0 — October 19, 2026
+
+Copyright (c) 2026 UPPP LLC, doing business as Vuoma.
+
+Permission is granted, without a separate software license fee, to use, copy,
+modify and distribute this package and its documentation (the Software) solely
+to develop, test, operate and distribute applications that integrate with the
+Vuoma service through authorized Vuoma APIs. This includes commercial,
+studio-branded applications, websites, and development or test versions using
+mocked Vuoma responses. You may share the Software with your developers and
+contractors for these purposes and include it in source or compiled application
+distributions, subject to this license.
+
+You must retain this license and the copyright notice in copies or substantial
+portions of the Software, including an application's third-party notices. Your
+modifications must remain subject to these permitted-use limits. You may not
+use or distribute the Software as a general-purpose library for applications
+unconnected to Vuoma, or to implement or operate a replacement for the Vuoma
+service, without separate written permission from UPPP LLC.
+
+This license applies only to the Software included in this package. It does
+not license Vuoma's backend, databases, customer data, studio branding,
+third-party assets or trademarks. Separately identified third-party software
+remains subject to its own license. You retain any rights you otherwise hold
+in your application code and content.
+
+This license does not grant API credentials, access to any account or data,
+hosting, support, or a right to continued service. Access to Vuoma remains
+subject to applicable service agreements, permissions and charges. Ending
+service does not transfer the backend or authorize continued API access. You
+may retain archival copies and use the Software in development intended for an
+authorized Vuoma integration; operating it for an unrelated replacement service
+requires separate permission.
+
+All rights not expressly granted are reserved. Use outside these terms is not
+licensed. This is a source-available, restricted-use license, not an open-source
+license. Separate written agreements with UPPP LLC may grant additional rights.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE COPYRIGHT HOLDER
+IS NOT LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE
+SOFTWARE OR ITS USE. Nothing in this license limits liability or rights that
+cannot lawfully be limited.

package/README.md

@@ -3,15 +3,29 @@
 Framework-neutral JavaScript and TypeScript client for the existing Vuoma v1
 public organization and member account APIs. Works with a host-provided Fetch
 implementation; it imports no React, Svelte, Expo or Supabase runtime. The package
-does not store credentials, read environment variables, create accounts, or
-grant access. This is a local package foundation; registry publication is a
-separate step.
+does not store credentials, read environment variables, or grant access. Account
+setup and booking use the same reviewed organization-member API methods as the
+Vuoma native apps. Server authorization and studio policies remain authoritative.
+Install the public package in your own application; access to Vuoma's private
+repository is not required:
+
+```sh
+npm install @vuoma/sdk@0.2.0
+```
+
+Use SvelteKit and SvelteKit UI with `@vuoma/web` for website account components
+and same-origin server sessions. Use `@vuoma/native-ui` for React Native account and booking UI and this SDK as
+its framework-neutral API transport. The complete `@vuoma/react-native` studio
+app core remains a private workspace; independent apps do not depend on it.
+The public setup guide is at `/developers` and `/o/<organization_slug>/developers`
+on the same combined Vuoma application and landing-page deployment. The current
+verified API origin is `https://vuoma.com`.
 
 ```js
 import { createVuomaClient } from '@vuoma/sdk'
 
 const vuoma = createVuomaClient({
-  apiOrigin: 'http://localhost:5173', // Use your verified Vuoma HTTPS origin in production.
+  apiOrigin: 'https://vuoma.com', // Use your verified Vuoma origin.
   organizationSlug: 'your-studio',
   fetch: globalThis.fetch,
 })
@@ -24,7 +38,11 @@ const schedule = await vuoma.public.getSchedule({
 })
 ```
 
-No key is needed for these public reads. Schedule timestamps are normalized to
+The organization slug is public routing configuration, built into each studio app.
+Sign-in authenticates a person for that studio. Private calls require their bearer
+token; the server verifies the live session, studio membership and permissions.
+Public schedule and catalog reads need no registration or app key.
+Schedule timestamps are normalized to
 UTC, and ranges must be positive and at most 63 days. The response preserves
 `schedule.has_more`; when it is true, split the requested range and fetch each
 part rather than displaying the first response as a complete schedule.
@@ -39,7 +57,7 @@ server or native host; it does not establish a browser cookie session.
 ```js
 let session = null // Example in-memory host state; no SDK persistence.
 const vuoma = createVuomaClient({
-  apiOrigin: 'http://localhost:5173',
+  apiOrigin: 'https://vuoma.com',
   organizationSlug: 'your-studio',
   tokenAdapter: { getSession: () => session },
 })
@@ -63,6 +81,9 @@ Native, keep refresh tokens in Keychain/Keystore through a secure-storage adapte
 keep access tokens in memory, and refresh through the documented member route.
 Refresh scheduling, retries and persistence remain host responsibilities.
 
+Existing signed-in sessions remain valid while the native app-key system is removed.
+Authorization failures do not trigger SDK retries or change the host session.
+
 The SDK uses `credentials: 'omit'`, prevents redirects, and sends member access
 tokens only to its exact configured origin and organization. It rejects missing,
 expired, cross-organization, platform-account, organization API, identity-only
@@ -78,11 +99,108 @@ business/financial validation, and do not replace the server's authorization or
 canonical schemas. The configured response byte limit is checked after reading
 the response text and against a supplied Content-Length header.
 
+## Signup, activation and password reset
+
+Email confirmation and password creation stay within the host UI; the person
+reads the six-digit code in their email app. No access token, cookie or API key
+is sent by these methods. For new or automatically resolved accounts, collect a
+display name. Choose `auto` to let verified email ownership resolve a new profile,
+an imported profile or an existing studio account; `activate` performs the same
+verified resolution without collecting a new name. `new` and `migrate` retain
+the dedicated signup confirmation path. Recovery uses its own code path.
+
+```js
+await vuoma.auth.requestAccountCode({
+  mode: 'signup', signupIntent: 'auto', email, displayName,
+})
+const capability = await vuoma.auth.confirmAccountCode({
+  mode: 'signup', signupIntent: 'auto', email, code,
+})
+// The resolution contains only the verified display name and masked contacts.
+const resolution = capability.account_resolution
+await vuoma.auth.completePassword({ capability, password })
+session = await vuoma.auth.signIn({ email, password })
+
+// Password reset uses the same scoped completion step.
+await vuoma.auth.requestAccountCode({ mode: 'recovery', email })
+const reset = await vuoma.auth.confirmAccountCode({ mode: 'recovery', email, code })
+await vuoma.auth.completePassword({ capability: reset, password: newPassword })
+```
+
+Keep password capabilities in memory and scoped to their original studio. They
+are not login tokens. A `VuomaApiError` with status `400` and code
+`weak_password_retry` lets the person choose a stronger password using the same
+capability. Other failures retain their HTTP status and safe machine code; raw
+backend messages and credentials are never reflected in SDK error messages.
+
+## Class and appointment booking
+
+Every mutation executes **once**. Create a `source_request_id` before submission
+and retain it with the exact payload until the outcome is confirmed. A timeout,
+abort or invalid response may follow a committed mutation. Retrying the same
+class payload with the same ID uses the server's existing idempotency boundary;
+do not generate a new ID to recover an uncertain result. Availability, credits,
+prices, cancellation policies and current authorization are rechecked by Vuoma.
+
+```js
+const bookingRequest = {
+  service_session_id: selectedSession.id,
+  source_request_id: crypto.randomUUID(),
+  // entitlement_id is optional; the server can select an eligible benefit.
+}
+const receipt = await vuoma.member.bookClass(bookingRequest)
+const terms = await vuoma.member.getCancellationQuote(receipt.booking.id)
+// Present terms and collect confirmation before this call.
+await vuoma.member.cancelBooking(receipt.booking.id, {
+  expectedFeeAmount: terms.quote.fee_amount,
+})
+```
+
+When required by the studio, class requests also supply the complete existing
+policy acceptance: `policy_version`, `policy_consent: true`,
+`payment_authorized: true` and `payment_authorization_id`. Never invent consent
+or a card authorization; payment/card setup is outside these methods. A
+`booking_cancellation_quote_changed` response requires fetching and presenting
+fresh terms before another cancellation attempt. `cancelBooking` also cancels an
+individual appointment booking through the same reviewed API.
+
+```js
+const bookingCatalog = await vuoma.public.getBookingCatalog()
+const availability = await vuoma.public.getAppointmentAvailability({ from, to })
+// If has_more is true, split the range and load both halves before presenting it
+// as complete. Availability accepts half-open ranges spanning at most 14 days.
+const visitRequest = {
+  source_request_id: crypto.randomUUID(),
+  appointments: selectedSlots.map(({ service_offering_id, starts_at, ends_at, credit_cost }) =>
+    ({ service_offering_id, starts_at, ends_at, credit_cost })),
+}
+const visit = await vuoma.member.bookAppointmentVisit(visitRequest)
+// After an uncertain result, read the original receipt before resubmitting.
+const recovered = await vuoma.member.getAppointmentVisit(visitRequest)
+```
+
+Visits contain 1–10 ordered, non-overlapping appointments. Submission and
+reconciliation validate the request ID, each selected offering/time/credit cost,
+receipt totals and unique booking/session IDs. A status `404` alone does not
+prove an earlier in-flight submission cannot finish; retain the saved payload
+and recover/resubmit only with that same ID. The SDK does not persist pending
+requests, retry mutations or decide when to clear recovery state.
+
+Native hosts that keep an access token separately from customer profile data may
+supply `bookingTokenAdapter: { getCredential: () => ({ organization_slug,
+access_token }) }` instead of `tokenAdapter`. Return the **current** credential or
+`null`, so completion after sign-out/account change is rejected. This adapter
+supports only class/visit/quote/cancellation methods, rejects platform-account
+and integration credentials, and does not authorize profile or commerce reads.
+The complete member session adapter is preferred when available. Existing
+Vuoma platform-account flows remain a separate private authority path.
+
 ## Keys and client IDs
 
 - **Organization integration/delegated API keys** are confidential server
-  credentials. Never put them in a website bundle, native binary, URL or SDK
-  token adapter. They do not sign a customer in.
+  credentials. Keep them on an integration server and outside website bundles,
+  native binaries, URLs and the member client's session adapter. Use the separate
+  organization client below for supported scoped API reads.
 - **Registered OAuth client IDs** are public app identifiers. Existing shared
   sign-in grants only `openid`, `profile` and `email`; those identity tokens do
   not authorize this SDK's member account methods.
@@ -92,26 +210,72 @@ the response text and against a supplied Content-Length header.
   Platform-account sessions are a separate boundary and are intentionally not
   accepted by this member client.
 
-This package adds no OAuth grant, CORS policy or backend permission. A third-party
-website still needs its backend adapter. Independent app authorization and
-app-scoped member grants are separate platform work; a public app ID alone must
-never authorize private account data.
+This package adds no OAuth grant or backend permission. Vuoma's member routes
+allow cross-origin requests with explicit bearer credentials and no cookies.
+Browser cookie sessions use the website's same-origin backend adapter. Live user
+sessions and studio permissions are enforced by the API; a studio slug never
+authorizes private account data.
+
+Supported routes include public `/api/v1/o/{slug}/member/{bootstrap,schedule,catalog,booking-catalog,availability}`;
+organization Auth `/api/v1/o/{slug}/auth/{sign-in,refresh,sign-out,sign-up,recovery,password}`
+and the reviewed `sign-up`, `account` and `recovery` `confirm-code` endpoints;
+member profile GET (`/me/profile?view=basic`), PATCH `/me/profile`, GET `/me/commerce`,
+POST `/me/commerce/bookings`, booking `cancellation-quote`/`cancel`, and
+POST/GET `/me/commerce/visits` with receipt lookup by request ID.
+Payments, uploads, staff administration and platform-account authentication
+remain outside this member client.
+
+## Contract-generated organization operations
+
+The server-side `@vuoma/sdk/organization` entry point accepts a confidential
+scoped API token. It shares generated request and response schemas with the
+operation registry, OpenAPI document and organization MCP server. The seven
+reviewed reads cover organization details, locations, services, schedule,
+the user directory, task lists and inventory. Route inventory is not a reviewed
+payload contract and does not automatically become an SDK method.
+
+```js
+import { createOrganizationApiClient } from '@vuoma/sdk/organization'
+
+const api = createOrganizationApiClient({
+  apiOrigin: 'https://vuoma.com',
+  organizationSlug: 'your-studio',
+  getApiToken: () => integrationServerToken,
+})
+const result = await api.operations['users.directory.read']({ limit: 25 })
+```
+
+The host supplies the current token for every request; the client does not store
+it. Queries and responses are validated against the generated contracts, and
+redirects and oversized responses are rejected. The server rechecks the exact
+scope, current organization permissions and tenant access on every call. There
+are no automatic retries. Three explicitly reviewed mutations are available in
+`api.writeOperations`: `messages.send`, `messages.read_state.update` and
+`messages.mute.update`. Supply `{ body: { channel_id, body } }` to send, or
+`{ path: { channel_id }, body: { message_id } }` / `{ path: { channel_id }, body: { is_muted } }`
+to advance read state / mute a channel. The client validates path, payload and response
+contracts and enforces the request byte limit. Each call executes once; reconcile
+an uncertain send by reading the channel before repeating it. Generated MCP tools
+remain reviewed reads only. Run
+`npm run api:generate` from the repository root after changing a reviewed
+contract; `npm run api:check` verifies that generated files are current.
 
-Supported routes are public `/api/v1/o/{slug}/member/{bootstrap,schedule,catalog}`;
-member sign-in, profile GET/PATCH and commerce GET; plus the existing global
-member refresh/sign-out routes. Signup, payments, booking mutations, uploads,
-staff administration and platform-account sessions are outside this initial SDK.
+## Maintainer verification and package artifact
 
-## Verification and package artifact
+From the Vuoma source checkout:
 
 ```sh
-npm test
-npm run verify
+npm run verify --workspace @vuoma/sdk
 ```
 
 Verification tests the actual wire route/header/session boundaries and creates
-an installable npm archive under `artifacts/`. It checks the archive's public
-file list and loads the packed module in an isolated temporary directory.
-Nothing is published and no registry authentication is attempted. The inherited
-license remains `UNLICENSED`; `private: false` prepares packaging without granting
-open-source licensing rights.
+`packages/sdk/artifacts/vuoma-sdk-0.2.0.tgz`. For pre-publication testing, a
+maintainer can provide that reviewed archive to a consumer, which can install it
+with `npm install ./vendor/vuoma-sdk-reviewed.tgz` and retain it with its lockfile. It checks the archive's public
+file list, installs its declared dependencies in an isolated temporary directory,
+and loads both packed entry points.
+The verification command does not publish or attempt registry authentication. The [Vuoma Connected Application License](./LICENSE) permits use, modification
+and redistribution for authorized Vuoma-connected apps, including commercial
+studio apps and mocked development. It does not license an unrelated replacement
+backend or grant API access. It is a restricted-use license, not an open-source
+license. Include the license in your application's third-party notices.

package/package.json

@@ -1,13 +1,24 @@
 {
   "name": "@vuoma/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Framework-neutral client for Vuoma public organization and member account APIs",
   "type": "module",
   "private": false,
-  "license": "UNLICENSED",
-  "files": ["src", "README.md"],
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "exports": {
-    ".": { "types": "./src/index.d.ts", "import": "./src/index.js" }
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./organization": {
+      "types": "./src/organization.d.ts",
+      "import": "./src/organization.js"
+    }
   },
   "types": "./src/index.d.ts",
   "sideEffects": false,
@@ -16,6 +27,14 @@
     "verify": "npm test && node scripts/verify-package.mjs",
     "prepack": "npm test"
   },
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=20" }
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  }
 }

package/src/index.d.ts

@@ -16,14 +16,22 @@ export interface MemberTokenAdapter {
   getSession(): MemberAuthSession | null | Promise<MemberAuthSession | null>
 }
 
+/** For native booking wrappers that hold an access token separately from profile data.
+ * Accepted only by booking/visit methods; never accepts platform-account credentials. */
+export interface MemberBookingTokenAdapter {
+  getCredential(): { organization_slug: string; access_token: string } | null | Promise<{ organization_slug: string; access_token: string } | null>
+}
+
 export interface VuomaClientOptions {
   /** Origin only. HTTPS required except HTTP loopback during local development. */
   apiOrigin: string
   organizationSlug: string
   /** Optional stronger client-side tenant check against the member JWT claim. */
   organizationId?: string
-  fetch?: typeof globalThis.fetch
+  fetch?: (url: string, init: RequestInit) => Promise<Response>
   tokenAdapter?: MemberTokenAdapter
+  /** Mutually exclusive with tokenAdapter. Profile/commerce reads still require a full session. */
+  bookingTokenAdapter?: MemberBookingTokenAdapter
   /** Default 2 MiB; accepted range 1 KiB–16 MiB. */
   maximumResponseBytes?: number
 }
@@ -104,14 +112,61 @@ export interface MemberCommerceSnapshot {
   orders: ApiRecord[]
 }
 
+export type MemberSignupIntent = 'new' | 'migrate' | 'auto' | 'activate'
+export type MemberAccountCodeRequest = RequestOptions & { email: string } & (
+  { mode: 'recovery'; signupIntent?: never; displayName?: never } |
+  { mode: 'signup'; signupIntent: 'new' | 'auto'; displayName: string } |
+  { mode: 'signup'; signupIntent: 'migrate' | 'activate'; displayName?: never }
+)
+export type MemberAccountCodeConfirmation = RequestOptions & { email: string; code: string } & (
+  { mode: 'recovery'; signupIntent?: never } | { mode: 'signup'; signupIntent: MemberSignupIntent }
+)
+export interface MemberAccountResolution { kind: 'existing_account' | 'existing_profile' | 'new_profile'; display_name: string; masked_email: string; masked_phone: string | null }
+export interface MemberPasswordCapability { organization_slug: string; value: string; account_resolution?: MemberAccountResolution }
+export interface MemberBookingPolicyAcceptance { policy_version: string; policy_consent: true; payment_authorized: true; payment_authorization_id: string }
+export type MemberClassBookingInput = { service_session_id: string; entitlement_id?: string | null; source_request_id: string } & (MemberBookingPolicyAcceptance | { policy_version?: never; policy_consent?: never; payment_authorized?: never; payment_authorization_id?: never })
+export interface MemberClassBookingResult { api_version: 1; booking: { id: string; status: 'confirmed' | 'waitlisted' | 'cancelled' | 'attended' | 'no_show' }; redemption: { id: string; status: 'waitlisted' | 'reserved' | 'consumed' | 'released' | 'reversed' } }
+export interface MemberCancellationQuote {
+  policy_version: string | null; can_cancel: boolean; late: boolean; late_cancellation_deadline: string | null;
+  grace_until: string | null; grace_applies: boolean; demand_observed: boolean; fee_amount: number; currency: string;
+  reason: 'no_policy' | 'fees_disabled' | 'legacy_booking' | 'on_time' | 'waitlisted' | 'booking_grace' | 'quiet_class' | 'late_fee_if_unfilled' | 'seat_refilled' | 'teacher_assignment' | 'started';
+  waive_if_filled: boolean; credit_return: boolean; quoted_at: string; policy_context?: ApiRecord | null
+}
+export interface MemberCancellationQuoteResult { api_version: 1; booking_id: string; quote: MemberCancellationQuote }
+export interface MemberBookingCancellation { api_version: 1; booking_id: string; status: 'cancelled'; canceled: true; cancellation_quote: MemberCancellationQuote | null }
+export interface MemberAppointmentSelection { service_offering_id: string; starts_at: string; ends_at: string; credit_cost: number }
+export interface MemberAppointmentVisitRequest { source_request_id: string; appointments: MemberAppointmentSelection[] }
+export interface MemberAppointmentVisitResult {
+  api_version: 1; visit_id: string; source_request_id: string; credit_cost: number;
+  bookings: Array<MemberAppointmentSelection & { booking_id: string; service_session_id: string; status: 'confirmed' | 'cancelled' | 'attended' | 'no_show' }>
+}
+export interface MemberLocation { public_id: string; name: string; timezone: string; city: string | null; region: string | null }
+export interface MemberAppointmentCandidate extends MemberAppointmentSelection {
+  candidate_id: string; service_id: string; duration_minutes: number; location: MemberLocation;
+  service: { id: string; name: string; description: string | null }
+}
+export interface MemberPublicAvailability { api_version: 1; generated_at: string; range: { from: string; to: string }; slots: MemberAppointmentCandidate[]; has_more: boolean }
+export interface MemberBookingCatalog {
+  api_version: 1; generated_at: string; cancellation_notice_minutes?: number;
+  experience: { classes: boolean; appointments: boolean; default_view: 'classes' | 'appointments' };
+  services: Array<{ id: string; name: string; description: string | null; offerings: Array<{ id: string; duration_minutes: number; location_public_id: string; credit_cost: number | null }> }>;
+  locations: MemberLocation[]
+}
+
 export interface VuomaClient {
   readonly public: {
     getBootstrap(options?: RequestOptions & { includeEvents?: boolean }): Promise<MemberBootstrap>
     /** Returns one server range. If has_more is true, split the range and request again. */
     getSchedule(options: RequestOptions & { from: string; to: string; includeEvents?: boolean; fresh?: boolean }): Promise<MemberPublicSchedule>
+    getBookingCatalog(options?: RequestOptions): Promise<MemberBookingCatalog>
+    /** One half-open range, up to 14 days. Split when has_more is true. */
+    getAppointmentAvailability(options: RequestOptions & { from: string; to: string }): Promise<MemberPublicAvailability>
     getCatalog(options?: RequestOptions & { includeCreditPurchases?: boolean }): Promise<MemberPublicCatalog>
   }
   readonly auth: {
+    requestAccountCode(options: MemberAccountCodeRequest): Promise<{ ok: true; mode: 'signup' | 'recovery'; requires_email_code: true }>
+    confirmAccountCode(options: MemberAccountCodeConfirmation): Promise<MemberPasswordCapability>
+    completePassword(options: RequestOptions & { capability: MemberPasswordCapability; password: string }): Promise<void>
     /** Returns credentials to the host; the SDK neither stores nor installs them. */
     signIn(options: RequestOptions & { email: string; password: string }): Promise<MemberAuthSession>
     refresh(options: RequestOptions & { refreshToken: string }): Promise<MemberAuthSession>
@@ -119,6 +174,14 @@ export interface VuomaClient {
     signOut(options: RequestOptions & { refreshToken: string }): Promise<void>
   }
   readonly member: {
+    /** Executes once. Retain source_request_id and the exact payload for uncertain-result recovery. */
+    bookClass(input: MemberClassBookingInput, options?: RequestOptions): Promise<MemberClassBookingResult>
+    getCancellationQuote(bookingId: string, options?: RequestOptions): Promise<MemberCancellationQuoteResult>
+    /** Applies to individual class and appointment bookings. Recheck a changed quote before retrying. */
+    cancelBooking(bookingId: string, options?: RequestOptions & { expectedFeeAmount?: number }): Promise<MemberBookingCancellation>
+    bookAppointmentVisit(input: MemberAppointmentVisitRequest, options?: RequestOptions): Promise<MemberAppointmentVisitResult>
+    /** Read the original receipt using its saved request; validates every returned selection. */
+    getAppointmentVisit(input: MemberAppointmentVisitRequest, options?: RequestOptions): Promise<MemberAppointmentVisitResult>
     getProfile(options?: RequestOptions): Promise<MemberProfile>
     updateProfile(changes: MemberProfileChanges, options?: RequestOptions): Promise<MemberProfile>
     getCommerce(options?: RequestOptions): Promise<MemberCommerceSnapshot>

package/src/index.js

@@ -1,3 +1,5 @@
+import { bookingInput, visitInput, bookingId, feeAmount, validBookingResult, validQuote, validVisitResult, availabilityRange, validAvailability, validBookingCatalog, accountInput, displayName, emailCode, validCapability, accountResolution } from "./member-contracts.js"
+
 // Public package: no environment reads, provider clients, persistence or secrets.
 const slugPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u
 const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu
@@ -138,16 +140,38 @@ export function createVuomaClient(options) {
   if (typeof requestFetch !== "function") throw new TypeError("A fetch implementation is required.")
   const tokenAdapter = options.tokenAdapter
   if (tokenAdapter !== undefined && (!object(tokenAdapter) || typeof tokenAdapter.getSession !== "function")) throw new TypeError("Provide a member session adapter.")
+  const bookingTokenAdapter = options.bookingTokenAdapter
+  if (bookingTokenAdapter !== undefined && (!object(bookingTokenAdapter) || typeof bookingTokenAdapter.getCredential !== "function" || tokenAdapter)) throw new TypeError("Provide either a member session adapter or a booking credential adapter.")
   const maximumBytes = options.maximumResponseBytes ?? 2 * 1024 * 1024
   if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 1024 || maximumBytes > 16 * 1024 * 1024) throw new TypeError("Use a response limit between 1 KiB and 16 MiB.")
   const memberRoot = `/api/v1/o/${organizationSlug}/member`
+  const selfRoot = `/api/v1/o/${organizationSlug}/me`
+  const authRoot = `/api/v1/o/${organizationSlug}/auth`
 
   async function readSession() {
     if (!tokenAdapter) throw invalidSession()
     return verifySession(await tokenAdapter.getSession(), organizationSlug, organizationId)
   }
 
+  async function readBookingSession() {
+    if (!bookingTokenAdapter) return readSession()
+    const credential = await bookingTokenAdapter.getCredential()
+    if (!object(credential) || credential.organization_slug !== organizationSlug) throw invalidSession()
+    const claims = memberClaims(credential.access_token)
+    if (organizationId && claims.app_metadata.organization_id !== organizationId) throw invalidSession()
+    return { session: credential, identity: `${organizationSlug}:${claims.sub}:${claims.session_id}:${claims.app_metadata.organization_id}` }
+  }
+  function checkSignal(signal) {
+    if (signal?.aborted) { const error = new Error("The request was cancelled."); error.name = "AbortError"; throw error }
+  }
+  function checked(value, valid) { if (!valid(value)) throw invalidResponse(); return value }
+  function setupResult(value) {
+    if (value.ok !== true || value.organization_slug != null && value.organization_slug !== organizationSlug) throw invalidResponse()
+    return value
+  }
+
   async function request(path, { method = "GET", body, accessToken, signal, query, privateResponse = false, empty = false } = {}) {
+    checkSignal(signal)
     const url = new URL(path, origin)
     if (query) for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value)
     const headers = { accept: "application/json" }
@@ -158,11 +182,13 @@ export function createVuomaClient(options) {
       cache: privateResponse ? "no-store" : "default",
       ...(body === undefined ? {} : { body: JSON.stringify(body) }),
     })
+    checkSignal(signal)
     // Custom fetch adapters must also honor the no-redirect destination boundary.
     if (response.redirected || (response.url && response.url !== url.href)) throw invalidResponse()
     const declared = Number(response.headers.get("content-length"))
     if (Number.isFinite(declared) && declared > maximumBytes) throw invalidResponse()
     const text = await response.text()
+    checkSignal(signal)
     if (utf8Length(text) > maximumBytes) throw invalidResponse()
     let value
     try { value = text ? JSON.parse(text) : null } catch { if (response.ok) throw invalidResponse() }
@@ -181,12 +207,14 @@ export function createVuomaClient(options) {
     return value
   }
 
-  async function accountRequest(path, requestOptions = {}, parse = value => value) {
-    const initial = await readSession()
-    const value = await request(`${memberRoot}${path}`, { ...requestOptions, accessToken: initial.session.access_token, privateResponse: true })
-    const current = await readSession()
+  async function accountRequest(path, requestOptions = {}, parse = value => value, booking = false) {
+    const read = booking ? readBookingSession : readSession
+    const initial = await read()
+    const value = await request(`${selfRoot}${path}`, { ...requestOptions, accessToken: initial.session.access_token, privateResponse: true })
+    const current = await read()
+    checkSignal(requestOptions.signal)
     if (current.identity !== initial.identity) throw new VuomaApiError(401, "member_session_changed", "Your signed-in account changed. Try again.")
-    return parse(value, initial.session.customer.id)
+    return parse(value, initial.session.customer?.id)
   }
 
   function profile(value, customerId) {
@@ -221,24 +249,74 @@ export function createVuomaClient(options) {
         if (value.schedule.sessions.length > 250) throw invalidResponse()
         return value
       },
+      async getBookingCatalog({ signal } = {}) {
+        return checked(await request(`${memberRoot}/booking-catalog`, { signal }), validBookingCatalog)
+      },
+      async getAppointmentAvailability({ from, to, signal }) {
+        const range = availabilityRange({ from, to })
+        return checked(await request(`${memberRoot}/availability`, { query: range, signal }), value => validAvailability(value, range))
+      },
       async getCatalog({ includeCreditPurchases = false, signal } = {}) {
         return catalog(await request(`${memberRoot}/catalog`, { signal, query: includeCreditPurchases ? { include_credit_purchases: "true" } : undefined }))
       },
     }),
     auth: Object.freeze({
+      async requestAccountCode({ mode, email, signupIntent, displayName: name, signal }) {
+        accountInput({ mode, email, signupIntent })
+        const body = mode === "signup" ? { email, signup_intent: signupIntent, ...(["new", "auto"].includes(signupIntent) ? { display_name: displayName(name) } : {}) } : { email }
+        const value = setupResult(await request(`${authRoot}/${mode === "signup" ? "sign-up" : "recovery"}`, { method: "POST", body, signal, privateResponse: true }))
+        if (value.mode !== mode || value.requires_email_code !== true) throw invalidResponse()
+        return { ok: true, mode, requires_email_code: true }
+      },
+      async confirmAccountCode({ mode, email, signupIntent, code, signal }) {
+        accountInput({ mode, email, signupIntent })
+        const resolve = mode === "signup" && ["auto", "activate"].includes(signupIntent)
+        const path = mode === "signup" ? resolve ? "account" : "sign-up" : "recovery"
+        const value = setupResult(await request(`${authRoot}/${path}/confirm-code`, { method: "POST", body: { email, code: emailCode(code) }, signal, privateResponse: true }))
+        if (!validCapability(value.capability)) throw invalidResponse()
+        let resolution
+        try { if (resolve) resolution = accountResolution(value.account_resolution) } catch { throw invalidResponse() }
+        return { organization_slug: organizationSlug, value: value.capability, ...(resolution ? { account_resolution: resolution } : {}) }
+      },
+      async completePassword({ capability, password, signal }) {
+        if (!object(capability) || capability.organization_slug !== organizationSlug || !validCapability(capability.value)) throw invalidSession()
+        if (typeof password !== "string" || !password || password.length > 1024) throw new TypeError("Provide a password.")
+        setupResult(await request(`${authRoot}/password`, { method: "POST", body: { capability: capability.value, password, password_confirmation: password }, signal, privateResponse: true }))
+      },
       async signIn({ email, password, signal }) {
         if (typeof email !== "string" || !email.trim() || email.length > 320 || typeof password !== "string" || !password || password.length > 1024) throw new TypeError("Provide an email address and password.")
-        return sessionResponse(await request(`${memberRoot}/auth/sign-in`, { method: "POST", body: { email, password }, signal, privateResponse: true }), organizationSlug, organizationId)
+        return sessionResponse(await request(`${authRoot}/sign-in`, { method: "POST", body: { email, password }, signal, privateResponse: true }), organizationSlug, organizationId)
       },
       async refresh({ refreshToken: token, signal }) {
-        return sessionResponse(await request("/api/v1/member/auth/refresh", { method: "POST", body: { refresh_token: refreshToken(token) }, signal, privateResponse: true }), organizationSlug, organizationId)
+        return sessionResponse(await request(`${authRoot}/refresh`, { method: "POST", body: { refresh_token: refreshToken(token) }, signal, privateResponse: true }), organizationSlug, organizationId)
       },
       async signOut({ refreshToken: token, signal }) {
-        await request("/api/v1/member/auth/sign-out", { method: "POST", body: { refresh_token: refreshToken(token) }, signal, privateResponse: true, empty: true })
+        await request(`${authRoot}/sign-out`, { method: "POST", body: { refresh_token: refreshToken(token) }, signal, privateResponse: true, empty: true })
       },
     }),
     member: Object.freeze({
-      getProfile({ signal } = {}) { return accountRequest("/profile", { signal }, profile) },
+      bookClass(input, { signal } = {}) {
+        const body = bookingInput(input)
+        return accountRequest("/commerce/bookings", { method: "POST", body, signal }, value => checked(value, validBookingResult), true)
+      },
+      getCancellationQuote(id, { signal } = {}) {
+        bookingId(id)
+        return accountRequest(`/commerce/bookings/${id}/cancellation-quote`, { signal, query: { include_booking_policy_context: "true" } }, value => checked(value, result => result.api_version === 1 && result.booking_id === id && validQuote(result.quote)), true)
+      },
+      cancelBooking(id, { expectedFeeAmount, signal } = {}) {
+        bookingId(id)
+        const body = expectedFeeAmount === undefined ? {} : { expected_fee_amount: feeAmount(expectedFeeAmount) }
+        return accountRequest(`/commerce/bookings/${id}/cancel`, { method: "POST", body, signal }, value => checked(value, result => result.api_version === 1 && result.booking_id === id && result.status === "cancelled" && result.canceled === true && (result.cancellation_quote === null || validQuote(result.cancellation_quote))), true)
+      },
+      bookAppointmentVisit(input, { signal } = {}) {
+        const body = visitInput(input)
+        return accountRequest("/commerce/visits", { method: "POST", body, signal }, value => checked(value, result => validVisitResult(result, body)), true)
+      },
+      getAppointmentVisit(input, { signal } = {}) {
+        const body = visitInput(input)
+        return accountRequest(`/commerce/visits/${body.source_request_id}`, { signal }, value => checked(value, result => validVisitResult(result, body)), true)
+      },
+      getProfile({ signal } = {}) { return accountRequest("/profile", { signal, query: { view: "basic" } }, profile) },
       updateProfile(changes, { signal } = {}) {
         const allowed = new Set(["first_name", "last_name", "phone", "birth_date"])
         if (!object(changes) || !Object.keys(changes).length || Object.entries(changes).some(([key, value]) =>