kaafil-js 0.1.0-beta.0

package/dist/index.d.cts

@@ -0,0 +1,2311 @@
+import { a3 as components, w as KaafilResponse, a4 as operations, t as KaafilPaginator, p as KaafilPagedResponse, R as Resolvable, E as Environment, V as VendorsResource, J as JourneyResource, W as ResponseMeta, a5 as RoomingHeuristicKey, G as Gender } from './paginator-CE9JhsLi.cjs';
+export { A as AgencyAdminRefreshResult, a6 as ApiKeyEnvironmentMismatchError, a7 as BoardStatus, B as BookingStatus, a8 as ChecklistAudience, a9 as ChecklistGate, aa as ChecklistItemStatus, ab as ChecklistPhase, ac as ChecklistPullTemplateMode, C as ClaimStatusIngest, ad as CollectionMode, ae as Currency, a as CursorPageMeta, b as ERROR_CODE_TABLE, c as ErrorCodeTableEntry, d as EventType, af as ExpenseCategory, ag as ExpensePaymentMode, F as FetchPage, ah as FileContentType, ai as FilePurpose, aj as FloatDirection, ak as ItineraryItemStatusUpdate, al as ItineraryItemType, am as JourneyTriggersResource, K as KaafilAbortError, e as KaafilApiError, f as KaafilCapabilityUnavailableError, an as KaafilConfigError, g as KaafilEntitlementError, h as KaafilError, i as KaafilErrorCode, j as KaafilErrorKind, k as KaafilInvalidRequestError, l as KaafilLockedError, m as KaafilNetworkError, n as KaafilNotFoundError, o as KaafilNotImplementedError, q as KaafilPaginationError, r as KaafilPaginationExhaustedError, s as KaafilPaginationInFlightError, u as KaafilRateLimitedError, v as KaafilReadOnlyRoleError, x as KaafilShareTokenExpiredError, y as KaafilShareTokenRevokedError, z as KaafilTimeoutError, D as KaafilTransportError, H as KaafilUnauthenticatedError, I as KaafilValidationError, L as KaafilVersionConflictError, ao as ListJourneyTriggersOptions, ap as ListTripVendorsOptions, M as ManagerRefreshResult, N as ManagerRole, O as ManifestMode, P as OutboxClass, Q as PagedResponseMeta, S as PaginatorPage, T as PartyKind, aq as PatchJourneyTriggerOptions, ar as PickupKind, U as PlanRefusalReason, as as ReadJourneyCapabilitiesOptions, at as ReadJourneyOptions, au as RebuildJourneyOptions, X as Retryability, av as RoomType, aw as RoomingFillOrder, ax as RoomingGenderPolicy, ay as RunJourneyStepOptions, az as SeatingFillOrder, aA as SeatingGenderAdjacency, aB as SeatingHeuristicKey, Y as TriggerAnchor, Z as TripMode, _ as TripStatus, $ as UnsatisfiableSchemeError, aC as VehicleLayout, aD as VehicleType, a0 as WaitUntilJourneyReadyOptions, a1 as isKaafilError, a2 as isRetryable } from './paginator-CE9JhsLi.cjs';
+
+/**
+ * `auth` — minting a manager session or an agency-admin session.
+ * `architecture/08-sdk.md §3.2, §4`.
+ *
+ * Rotation is deliberately absent as a public method for either kind:
+ * `../auth/credentials.ts` calls each kind's own refresh endpoint itself,
+ * pre-emptively and reactively, as part of resolving every request's
+ * credential — a consumer never calls it directly (this wave's governing
+ * principle: the SDK does the refresh, the consumer only ever hands the SDK
+ * the tokens it was given).
+ *
+ * `08-sdk.md §4`'s table also lists a `revoke` method for this group. No such
+ * operation exists anywhere in the vendored spec: the `Auth` tag in
+ * `openapi/openapi.json` names exactly four operations —
+ * `mintManagerTokens`, `refreshManagerTokens`, `mintAgencyAdminTokens`,
+ * `refreshAgencyAdminTokens` (verified via `jq '.paths[][] | select(.tags ==
+ * ["Auth"]) | .operationId'`) — and the two `refresh*` ones are the
+ * resolver's job, not a public method here. Per this lane's brief — "if this
+ * list and the spec disagree, the spec wins, and you say so" — no `revoke`
+ * method ships. Flagged here rather than silently dropped.
+ */
+
+type MintManagerTokenRequest = components['schemas']['MintManagerTokensRequest'];
+type ManagerSessionResponse = components['schemas']['ManagerSessionResponse'];
+type MintAgencyAdminTokenRequest = components['schemas']['MintAgencyAdminTokensRequest'];
+type AgencyAdminSessionResponse = components['schemas']['AgencyAdminSessionResponse'];
+interface MintManagerTokenOptions extends MintManagerTokenRequest {
+    readonly signal?: AbortSignal;
+}
+interface MintAgencyAdminTokenOptions extends MintAgencyAdminTokenRequest {
+    readonly signal?: AbortSignal;
+}
+interface AuthResource {
+    /**
+     * `POST /api/v1/auth/manager-tokens` — opens a manager session. Server-side
+     * only (API key; `mintManagerTokens` accepts only `apiKeyAuth`). The
+     * returned `refreshToken` is shown exactly once, here and at every
+     * subsequent rotation — hand `accessToken`, `refreshToken`, and
+     * `expiresAt` straight to a `managerSession`-credentialed client
+     * (`../auth/credentials.ts`'s `ManagerSessionCredentialConfig`, or the
+     * browser entry's `session.open(...)`).
+     *
+     * Not idempotent — no `idempotencyKey` field on this options type — by the
+     * operation's own design (`refreshManagerTokens`'s response carries a
+     * plaintext refresh token; replaying it from an idempotency cache would
+     * mean persisting that secret, which the hash-only refresh-token storage
+     * rule forbids). A caller that loses this response to a network error
+     * simply mints again.
+     */
+    mintManagerToken(options: MintManagerTokenOptions): Promise<KaafilResponse<ManagerSessionResponse>>;
+    /**
+     * `POST /api/v1/auth/agency-admin-tokens` — opens an agency-admin session,
+     * the agency-admin analogue of `mintManagerToken` above. Server-side only
+     * (API key; `mintAgencyAdminTokens` accepts only `apiKeyAuth`) — hand the
+     * response's `accessToken`, `refreshToken`, and `expiresAt` straight to an
+     * `agencyAdmin`-credentialed client (`../auth/credentials.ts`'s
+     * `AgencyAdminCredentialConfig`, or the browser entry's `admin.open(...)`).
+     *
+     * Not idempotent, for the same reason as `mintManagerToken`: the response
+     * carries a plaintext refresh token, and the hash-only refresh-token
+     * storage rule forbids persisting one in an idempotency cache to replay.
+     */
+    mintAgencyAdminToken(options: MintAgencyAdminTokenOptions): Promise<KaafilResponse<AgencyAdminSessionResponse>>;
+}
+
+/**
+ * `checklists` — sections, items, toggle, and the agency's reusable template
+ * library. `architecture/08-sdk.md §4`. `checklists` FRD §3, RULES R1–R14,
+ * `D-029` (pull-template copy semantics), `modules/checklists/checklists
+ * .routes.ts`'s own header (the source of every auth/lock line below).
+ *
+ * `read` and `templates.list` accept a manager session OR an API key; every
+ * WRITE (`items.add/patch/remove/toggle`, `templates.pull`) is
+ * `managerAuth`-only — admin template CONFIG (`POST/PATCH` against the
+ * library itself) does not exist yet (`checklists.routes.ts`'s "ADMIN
+ * TEMPLATE CONFIG IS DEFERRED" note), so there is no write here an API key
+ * could ever reach even in principle. Every write also declares
+ * `closeoutLock: 'ref'` engine-side — a write racing trip close-out answers
+ * `423 LOCKED` (`KaafilLockedError`), terminal, never retried.
+ *
+ * ── FOUR QUIRKS A CONSUMER WILL OTHERWISE GET WRONG ─────────────────────────
+ *
+ * 1. **`toggle`'s concurrency guard is on the item's STATUS, not its
+ *    `version`.** Every OTHER version-guarded write in this API takes an
+ *    `If-Match`/`version` and answers `409 CONFLICT_VERSION` with
+ *    `details.currentVersion` on staleness. `toggle` takes `expectedStatus`
+ *    in the BODY instead, and a stale value still answers
+ *    `409 CONFLICT_VERSION` — same code, `KaafilVersionConflictError` still
+ *    catches it — but the payload carries `details.currentStatus`, never
+ *    `details.currentVersion`. Reading `.currentVersion` off the caught
+ *    error here is silently `undefined`; read `error.details?.currentStatus`
+ *    (typed `ChecklistItemStatus`) instead. This file does not add a second
+ *    getter to `KaafilVersionConflictError` for it — `../http/errors.ts`'s
+ *    own header states the bar for a code-specific getter, and one class per
+ *    code that merely carries an unusual `details` shape is exactly what
+ *    that bar exists to avoid.
+ * 2. **A `COMPLETE` item cannot be deleted.** `items.remove` on a `COMPLETE`
+ *    item answers `422 BUSINESS_RULE_VIOLATION` with
+ *    `details.rule: 'item_complete_delete_blocked'` — un-toggle it first.
+ *    Not a module-local code: the FRD only describes the refusal, never
+ *    names it as an identity a client branches on, so it never got minted
+ *    one (`checklists.constants.ts`'s own line on the point).
+ * 3. **`templates.pull` COPIES (`D-029`).** Both `append` and `replace`
+ *    write TRIP-OWNED rows; neither creates a live link. A template edited
+ *    AFTER a pull never reaches the trip's copy, and an edit to the trip's
+ *    copy never reaches the template. `sourceSectionId` on the pulled
+ *    section is the only trace of where it came from, stamped once, on
+ *    first pull only — a second pull of the same template onto a section
+ *    that already exists never rewrites it.
+ * 4. **Editing an item's `phase` RE-DERIVES its `gate`, unless `gate` is
+ *    sent in the SAME request.** `phase` is a hint only — `ChecklistItem`
+ *    has no `phase` column (phase is the SECTION's) — so `items.patch` never
+ *    echoes it back on the response, and an explicit `gate` in the same call
+ *    always wins over the fixed phase→gate map.
+ *
+ * Beyond those four: the aggregate's `sections[]` is always the FULL live
+ * set (a trip's sections are a handful); `items[]` is the ONLY delta axis —
+ * `?since=` narrows it, with a deletion arriving as the same tombstone shape
+ * `itinerary`/`pickups` already use. `progress` and `hasOpenMandatoryByPhase`
+ * are always computed over the full live set, independent of `?since=`. The
+ * four reserved sections (`medical`/`documents`/`logistics`/`handover`) are
+ * seeded at TRIP-INGEST, inside the upsert transaction — never by this
+ * read — so a fresh trip's `read()` already carries them on its very first
+ * call; there is no seed-on-read call to make or race against.
+ *
+ * ── THE SIX `console`-PLANE READS ARE NOT IN THIS PACKAGE ───────────────────
+ *
+ * `GET /api/v1/console/trips/{ref}/checklist` (`readConsoleChecklist`) and
+ * its five siblings (`listConsoleTrips`, `…/itinerary`, `…/rooming`,
+ * `…/seating`, `…/pickups`) exist in the vendored spec and are excluded from
+ * this SDK on purpose — the same decision `../auth/credentials.ts` and
+ * `webhooks.ts` already state for `consoleAuth` generally. They authenticate
+ * with a console session cookie (`consoleAuth`), which is the partner
+ * console's OWN administrative UI's credential, never something a CRM
+ * integrating this package holds — a partner API key satisfies none of
+ * `readConsoleChecklist`'s `security` alternatives (there is only one:
+ * `consoleAuth`), so a method wrapping it would be uncallable by every
+ * consumer of this package. `scripts/gen-meta.mjs`'s
+ * `nonIntegrationRequestSchemaNames` already enforces the analogous exclusion
+ * for request-body enums reachable only from a console/platform path; this
+ * resource file is the read-side statement of the identical decision. If a
+ * console read ever gains a second, API-key-satisfiable security
+ * alternative, that is a spec change this SDK would need to notice and
+ * decide about again — not something to pre-empt here.
+ */
+
+type ChecklistAggregateResponse = components['schemas']['ChecklistAggregateResponse'];
+type ChecklistItemResponse = components['schemas']['ChecklistItemResponse'];
+type DeleteItemResponse = components['schemas']['DeleteItemResponse'];
+type ToggleResponse = components['schemas']['ToggleResponse'];
+type TemplatesListResponse = components['schemas']['TemplatesListResponse'];
+type AddChecklistItemRequest = components['schemas']['AddChecklistItemRequest'];
+type PatchChecklistItemRequest = components['schemas']['PatchChecklistItemRequest'];
+type ToggleChecklistItemRequest = components['schemas']['ToggleChecklistItemRequest'];
+type PullChecklistTemplateRequest = components['schemas']['PullChecklistTemplateRequest'];
+/**
+ * One row of `read`'s `items[]`: a live item, or the tombstone for one
+ * deleted since the cursor. Aliased off the response type, never restated —
+ * `itinerary.ts#ItineraryItemDeltaRow`'s own reasoning applies verbatim.
+ */
+type ChecklistItemDeltaRow = ChecklistAggregateResponse['items'][number];
+interface ReadChecklistOptions {
+    readonly tripRef: string;
+    /**
+     * The delta cursor: a previous response's own `meta.serverTime`, and
+     * nothing else. Omit for the full aggregate — `sections[]` and the two
+     * progress figures are always full regardless; only `items[]` narrows.
+     * Prefer `createDeltaCursor` (`../delta/cursor.ts`) over passing this by
+     * hand, same as every other delta read in this SDK.
+     */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface AddChecklistItemOptions extends AddChecklistItemRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface PatchChecklistItemOptions extends PatchChecklistItemRequest {
+    readonly tripRef: string;
+    readonly itemId: string;
+    /**
+     * Required, not optional — `itinerary.ts#PatchItineraryItemOptions
+     * .version`'s own argument for why a missing `If-Match` and a stale one
+     * answering the identical `409 CONFLICT_VERSION` means this SDK should
+     * make forgetting it impossible rather than merely discouraged. Pass the
+     * `version` from the item as last read; the SDK builds the `If-Match`
+     * header itself. NOT the same guard as `toggle`'s `expectedStatus` — see
+     * this file's header, quirk 1.
+     */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface DeleteChecklistItemOptions {
+    readonly tripRef: string;
+    readonly itemId: string;
+    /** See `PatchChecklistItemOptions.version` — same contract. Refused with
+     * `422 BUSINESS_RULE_VIOLATION` while the item is `COMPLETE` — this file's
+     * header, quirk 2. */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface ToggleChecklistItemOptions extends ToggleChecklistItemRequest {
+    readonly tripRef: string;
+    readonly itemId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ChecklistItemsResource {
+    /**
+     * `POST …/checklist/items` — auto-creates the section when `sectionKey`
+     * is new FOR THIS TRIP (taking `sectionTitle`/`audience` as the new
+     * section's display; both are ignored on an already-existing section). An
+     * omitted `key` is slugged from `title` and de-duplicated within the
+     * section; an explicit colliding `key` is `422 VALIDATION_ERROR`, never a
+     * silent rename. `gate` is derived from the section's `phase` — the
+     * create body carries no `gate` of its own.
+     */
+    add(options: AddChecklistItemOptions): Promise<KaafilResponse<ChecklistItemResponse>>;
+    /** See this file's header, quirk 4 — a `phase` sent here without an
+     * explicit `gate` re-derives the item's `gate`. */
+    patch(options: PatchChecklistItemOptions): Promise<KaafilResponse<ChecklistItemResponse>>;
+    /** See this file's header, quirk 2. */
+    remove(options: DeleteChecklistItemOptions): Promise<KaafilResponse<DeleteItemResponse>>;
+    /**
+     * `POST …/checklist/items/{itemId}/toggle` — flips OPEN↔COMPLETE. See
+     * this file's header, quirk 1, before catching `KaafilVersionConflictError`
+     * off this call. Returns the updated item PLUS its section's and the
+     * trip's own progress, so a caller patches its local state without a
+     * refetch. `checklist.item_completed` fires on every `OPEN → COMPLETE`
+     * transition; `checklist.completed` fires additionally when it was the
+     * LAST mandatory item trip-wide. `COMPLETE → OPEN` emits nothing.
+     */
+    toggle(options: ToggleChecklistItemOptions): Promise<KaafilResponse<ToggleResponse>>;
+}
+interface ListChecklistTemplatesOptions {
+    readonly tripRef: string;
+    /** Default `"en"`, with `"en"` fallback on no exact match. */
+    readonly locale?: string;
+    readonly signal?: AbortSignal;
+}
+interface PullChecklistTemplateOptions extends PullChecklistTemplateRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ChecklistTemplatesResource {
+    /** `GET …/checklist/templates` — the agency's library (`tripId` is
+     * `null`), resolved to `?locale=`. `lastUsedAt` is `null` until this
+     * template is pulled onto some trip, or the pull marker has expired. */
+    list(options: ListChecklistTemplatesOptions): Promise<KaafilResponse<TemplatesListResponse>>;
+    /** See this file's header, quirk 3 — COPY semantics, never a live link.
+     * Returns the FULL new aggregate (cold, no `?since=`) for atomic
+     * replacement. */
+    pull(options: PullChecklistTemplateOptions): Promise<KaafilResponse<ChecklistAggregateResponse>>;
+}
+interface ChecklistsResource {
+    /** `GET …/trips/{ref}/checklist` — the full aggregate: sections, items,
+     * both progress figures, and the agency's available templates. A PURE
+     * READ — it never seeds; the four reserved sections are already present
+     * by trip-ingest time (this file's header). */
+    read(options: ReadChecklistOptions): Promise<KaafilResponse<ChecklistAggregateResponse>>;
+    readonly items: ChecklistItemsResource;
+    readonly templates: ChecklistTemplatesResource;
+}
+
+/**
+ * Coercion for the caller-supplied date-time fields scattered across the
+ * ingest surface (`trips.upsert`, `trips.travellers.*`, `trips.managers.*`,
+ * `trips.balance.push`, `trips.bulk.push`, `shareTokens.create`). Every one
+ * of those fields is, in the generated schema, a bare `string` that the API
+ * requires to be a full ISO-8601 datetime WITH an offset — a caller who
+ * hand-builds that string is the single most common way to fail this API's
+ * validation, and JavaScript already has a `Date` for exactly this job.
+ *
+ * This module is the one seam every such field routes through. It is not
+ * wired into the generated schema types (those stay a faithful mirror of
+ * the OpenAPI spec) — it is wired into the hand-written `*Options` types in
+ * `resources/trips.ts` and `resources/share-tokens.ts`, which widen the
+ * relevant fields from `string` to `DateTimeInput` and normalize back down
+ * to the schema's `string` shape before the body reaches `client.execute`.
+ */
+/**
+ * What a caller may hand a date-time field on the ingest surface.
+ *
+ * - `Date` is the point of this whole module: build it however you like,
+ *   the SDK converts it correctly.
+ * - `number` is epoch milliseconds — `Date.now()` and friends, without
+ *   forcing a caller to wrap it in `new Date(...)` first.
+ * - `string` is the escape hatch for a caller who already has a correctly
+ *   formatted ISO datetime (e.g. echoed back from another system) and does
+ *   not want it touched — see `normalizeDateTimeInput` for why a full
+ *   datetime string passes through byte-for-byte instead of round-tripping
+ *   through `Date`.
+ */
+type DateTimeInput = Date | number | string;
+
+/**
+ * `collections` — customer payments recorded against a traveller's balance,
+ * who still owes, and the void correction. `architecture/08-sdk.md §4`.
+ *
+ * `list`/`eligible` accept a manager session OR an API key; `record`/`void`
+ * are `managerAuth`-only — collecting cash and correcting a mistake both
+ * happen on the ground.
+ *
+ * `mode ∈ CollectionMode` (`CASH|UPI|CARD|BANK`) is a CUSTOMER payment
+ * mode, disjoint from `expenses`' agency-spend `paymentMode` — the two
+ * enums never overlap and are never interchangeable even where a value
+ * name might coincide.
+ *
+ * ── THE OVERPAY GUARD IS A HARD REFUSAL ──────────────────────────────────
+ *
+ * `record()`'s `amountMinor` must not exceed the traveller's DERIVED
+ * `outstandingMinor` (computed live from the ingested `Balance`, never
+ * stored) — a caller cannot record more than what is actually owed.
+ * Exceeding it answers `422 BUSINESS_RULE_VIOLATION` with
+ * `details.remainingMinor`, the room actually left. `eligible()` is the
+ * companion read: only travellers with `outstandingMinor > 0` appear in
+ * it — a traveller with nothing outstanding, or with no `Balance` row at
+ * all, is simply absent, though still recordable through `record()` as an
+ * advance.
+ *
+ * `void()` is a correction, never an edit or a hard delete — there is no
+ * edit-after-record. `If-Match: <version>` is required; a missing or stale
+ * one answers `409 CONFLICT_VERSION` with `details.currentVersion`, never
+ * silently overwriting a version the caller has not seen.
+ */
+
+type CollectionResponse = components['schemas']['CollectionResponse'];
+type CollectionDeltaResponse = components['schemas']['CollectionDeltaResponse'];
+type EligibleRowResponse = components['schemas']['EligibleRowResponse'];
+type RecordCollectionRequest = components['schemas']['RecordCollectionRequest'];
+type VoidCollectionRequest = components['schemas']['VoidCollectionRequest'];
+/**
+ * One row of `list`'s result: a live collection with its derived
+ * `outstandingMinor`, or the tombstone for one deleted since the cursor.
+ * Aliased off the response type rather than restated — see
+ * `../delta/cursor.ts`'s `isTombstone`.
+ */
+type CollectionDeltaRow = CollectionDeltaResponse;
+interface ListCollectionsOptions {
+    readonly tripRef: string;
+    /** Narrows to one traveller. Omitted lists every traveller's rows. */
+    readonly travellerId?: string;
+    /**
+     * The delta cursor: a previous response's own `meta.serverTime`, and
+     * nothing else. Omit it for the full list. Prefer `createDeltaCursor`
+     * (`../delta/cursor.ts`) over passing this by hand — the window is
+     * INCLUSIVE and overlapped by five seconds, so a pull is at-least-once
+     * and re-delivers rows a caller already holds; that module owns the
+     * bookkeeping this endpoint's overlap assumes.
+     */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface ListEligibleCollectionsOptions {
+    readonly tripRef: string;
+    readonly signal?: AbortSignal;
+}
+interface RecordCollectionOptions extends Omit<RecordCollectionRequest, 'collectedAt'> {
+    readonly tripRef: string;
+    readonly collectedAt?: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface VoidCollectionOptions extends VoidCollectionRequest {
+    readonly tripRef: string;
+    readonly collectionId: string;
+    /**
+     * Required, not optional. A missing `If-Match` and a stale one both
+     * answer `409 CONFLICT_VERSION` — identically confusing either way — so
+     * this method makes forgetting it impossible instead of merely
+     * discouraged. Pass the `version` from a collection just read via
+     * `list()` or the row `record()` returned. The SDK builds the `If-Match`
+     * header itself; never set it in `headers`.
+     */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface CollectionsResource {
+    /** `GET /api/v1/trips/{ref}/collections` — recorded collections, each row's
+     * `outstandingMinor` derived live on this read. See this file's header for
+     * the delta-cursor semantics. */
+    list(options: ListCollectionsOptions): Promise<KaafilResponse<readonly CollectionDeltaRow[]>>;
+    /** `GET /api/v1/trips/{ref}/collections/eligible` — travellers with a
+     * derived `outstandingMinor > 0`; "who has a balance to chase", not "who
+     * may be collected from". */
+    eligible(options: ListEligibleCollectionsOptions): Promise<KaafilResponse<readonly EligibleRowResponse[]>>;
+    /** `POST /api/v1/trips/{ref}/collections` — records a customer payment.
+     * See this file's header for the overpay guard. */
+    record(options: RecordCollectionOptions): Promise<KaafilResponse<CollectionResponse>>;
+    /** `DELETE /api/v1/trips/{ref}/collections/{id}/void` — a correction, not
+     * an edit or a hard delete. `DELETE`, not the FRD table's nominal `POST`:
+     * a real `If-Match` guard is unsatisfiable on a `POST` under this
+     * engine's OpenAPI generator, and a version-guarded soft void is the
+     * shape the generator already blesses `DELETE` for — same path, same
+     * body, same response either way. */
+    void(options: VoidCollectionOptions): Promise<KaafilResponse<CollectionResponse>>;
+}
+
+/**
+ * `events` — the event feed. `architecture/08-sdk.md §4`: "the delta feed for
+ * missed-webhook recovery." `listEvents` is `apiKeyAuth`-only and
+ * cursor-paginated (`cursor`+`limit` query params, `meta.page.hasNext`);
+ * `list()` returns a `KaafilPaginator` and `listPage()` is the manual
+ * single-page escape hatch (`../pagination/paginator.ts`).
+ */
+
+type EventEnvelopeResponse = components['schemas']['EventEnvelopeResponse'];
+type ListEventsQuery = NonNullable<operations['listEvents']['parameters']['query']>;
+/** The filterable half of `listEvents`'s query params — `cursor` and
+ * `limit` are the paginator's job, never the caller's to hold. */
+type EventFilters = Omit<ListEventsQuery, 'cursor' | 'limit'>;
+interface ListEventsOptions {
+    readonly filters?: EventFilters;
+    /** Page size sent as the `limit` query param on every page this paginator fetches. */
+    readonly limit?: number;
+}
+interface ListEventsPageOptions extends EventFilters {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+interface EventsResource {
+    /** `GET /api/v1/events` as a `KaafilPaginator` — the SDK holds the cursor;
+     * the consumer never sees or stores one. */
+    list(options?: ListEventsOptions): KaafilPaginator<EventEnvelopeResponse, EventFilters>;
+    /** The manual single-page escape hatch: fetches exactly one page and
+     * returns it directly, for a caller who wants to drive paging itself
+     * rather than use the paginator `list()` returns. */
+    listPage(options?: ListEventsPageOptions): Promise<KaafilPagedResponse<readonly EventEnvelopeResponse[]>>;
+}
+
+/**
+ * `expenses` — on-trip agency spend, its receipt lane, and the claim
+ * lifecycle for a manager's own `PERSONAL` spend. `architecture/08-
+ * sdk.md §4`.
+ *
+ * `list`/`read` accept a manager session OR an API key; `log`,
+ * `linkReceipt`, `void` and every `claims.*` method except
+ * `claims.ingest` are `managerAuth`-only. `claims.ingest` is the one
+ * method on this resource an API key alone may call — see its own doc
+ * below.
+ *
+ * `paymentMode ∈ ExpensePaymentMode` (`FLOAT_CASH|PERSONAL|OTHER`) is
+ * IMMUTABLE after `log()` and never accepted on any later call — an agency
+ * spend mode, disjoint from `collections`' customer payment `mode`.
+ * `category ∈ ExpenseCategory`.
+ *
+ * ── FLOAT_CASH AUTO-COUPLES TO THE FLOAT LEDGER ──────────────────────────
+ *
+ * `log()` with `paymentMode: 'FLOAT_CASH'` creates, in ONE transaction, the
+ * expense, a paired `FloatMovement.EXPENSE(OUT)`, and sets the expense's
+ * `floatMovementId` — the negative-float guard (`float.ts`'s header)
+ * applies unconditionally, so an expense that would overdraw the manager's
+ * float is refused rather than logged. `PERSONAL`/`OTHER` touch no float
+ * at all. `log({ submitClaim: true, ... })` (PERSONAL only) files the
+ * claim in the SAME transaction — equivalent to a `log()` immediately
+ * followed by `claims.submit()`, but atomic.
+ *
+ * ── THE CLAIM STATE MACHINE, AND WHO MAY MOVE IT ─────────────────────────
+ *
+ * `ExpenseResponse.claimStatus` is a five-member vocabulary —
+ * `SUBMITTED|WITHDRAWN|APPROVED|PAID|REJECTED` — split down the middle by
+ * WHO can set each value. `claims.submit()`/`claims.withdraw()` are the
+ * only two a Kaafil caller ever drives, and neither takes a `status` field
+ * at all: submitting always produces `SUBMITTED`, withdrawing always
+ * produces `WITHDRAWN`, so there is no enum a manager writes here.
+ * `APPROVED|PAID|REJECTED` arrive ONLY through `claims.ingest()` — the
+ * CRM's own decision, mirrored, never decided by Kaafil. That three-member
+ * subset is `ClaimStatusIngest` (`../generated/enums.ts`), deliberately not
+ * named `ClaimStatus` — see `scripts/gen-meta.mjs`'s `REQUEST_ENUM_NAMES`
+ * comment on that entry for why a bare domain name here would be the same
+ * trap as `ItineraryItemStatusUpdate`'s.
+ *
+ * `claims.submit()` only succeeds on a row the caller themselves logged —
+ * a different manager's row answers `404 RESOURCE_NOT_FOUND`, never `403`
+ * — with `paymentMode: 'PERSONAL'` and `claimStatus` currently `null` or
+ * `WITHDRAWN`. `claims.withdraw()` requires `If-Match` and only succeeds
+ * while `claimStatus = SUBMITTED` AND no CRM decision has landed yet — a
+ * decision arriving mid-flight wins the race cleanly, the withdraw loses.
+ * `claims.ingest()` accepts ONLY the three CRM-only values; `SUBMITTED` or
+ * `WITHDRAWN` on this route is `422 VALIDATION_ERROR` — the ingest route is
+ * one-directional by contract, not just by convention.
+ *
+ * `void()` reverses the paired float movement (if any) and cascades an
+ * open claim; `linkReceipt()` back-fills `receiptFileKey` for a client that
+ * logged an expense offline before an upload could confirm — it takes an
+ * `Idempotency-Key`, never an `If-Match`: it addresses no client-held
+ * version, only a key the log call could not carry offline. Both refuse on
+ * an already-voided row or one the CRM has already decided.
+ */
+
+type ExpenseResponse = components['schemas']['ExpenseResponse'];
+type ExpenseListResponse = components['schemas']['ExpenseListResponse'];
+type ClaimStatusIngestResponse = components['schemas']['ClaimStatusIngestResponse'];
+type LogExpenseRequest = components['schemas']['LogExpenseRequest'];
+type LinkExpenseReceiptRequest = components['schemas']['LinkExpenseReceiptRequest'];
+type VoidExpenseRequest = components['schemas']['VoidExpenseRequest'];
+type ClaimStatusIngestRequest = components['schemas']['ClaimStatusIngestRequest'];
+type ListExpensesQuery = NonNullable<operations['listExpenses']['parameters']['query']>;
+/** The filterable half of `list`'s query params — `since` is the delta
+ * cursor and is passed as its own option, never bundled in here. */
+type ExpenseFilters = Omit<ListExpensesQuery, 'since'>;
+interface ListExpensesOptions extends ExpenseFilters {
+    readonly tripRef: string;
+    /**
+     * The delta cursor: a previous response's own `meta.serverTime`, and
+     * nothing else. Omit it for the full list. Prefer `createDeltaCursor`
+     * (`../delta/cursor.ts`) over passing this by hand — the window is
+     * INCLUSIVE and overlapped by five seconds, so a pull is at-least-once.
+     */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReadExpenseOptions {
+    readonly tripRef: string;
+    readonly expenseId: string;
+    readonly signal?: AbortSignal;
+}
+interface LogExpenseOptions extends Omit<LogExpenseRequest, 'spentAt'> {
+    readonly tripRef: string;
+    readonly spentAt?: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface LinkExpenseReceiptOptions extends LinkExpenseReceiptRequest {
+    readonly tripRef: string;
+    readonly expenseId: string;
+    /** Required — this route addresses no client-held version; see this
+     * file's header for why `If-Match` never applies here. */
+    readonly idempotencyKey: string;
+    readonly signal?: AbortSignal;
+}
+interface VoidExpenseOptions extends VoidExpenseRequest {
+    readonly tripRef: string;
+    readonly expenseId: string;
+    /**
+     * Required, not optional. A missing `If-Match` and a stale one both
+     * answer `409 CONFLICT_VERSION` — identically confusing either way — so
+     * this method makes forgetting it impossible instead of merely
+     * discouraged. Pass the `version` from an expense just read via `list()`
+     * or `read()`. The SDK builds the `If-Match` header itself; never set it
+     * in `headers`.
+     */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface SubmitExpenseClaimOptions {
+    readonly tripRef: string;
+    readonly expenseId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface WithdrawExpenseClaimOptions {
+    readonly tripRef: string;
+    readonly expenseId: string;
+    /** Required — see `VoidExpenseOptions.version` above for why this SDK
+     * never makes `If-Match` optional on a versioned write. */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface IngestClaimStatusOptions extends Omit<ClaimStatusIngestRequest, 'decisionAt'> {
+    readonly tripRef: string;
+    readonly expenseId: string;
+    readonly decisionAt: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ExpenseClaimsResource {
+    /** `POST /api/v1/trips/{ref}/expenses/{id}/claim` — files a claim on the
+     * caller's own `PERSONAL` expense. No body: submitting always produces
+     * `SUBMITTED`, never a status the caller names. */
+    submit(options: SubmitExpenseClaimOptions): Promise<KaafilResponse<ExpenseResponse>>;
+    /** `DELETE /api/v1/trips/{ref}/expenses/{id}/claim/withdraw` — only while
+     * still `SUBMITTED` with no CRM decision landed. `DELETE`, not the FRD
+     * table's nominal `POST` — the same forced deviation `expenses.void()`
+     * and `collections.void()` make, for the identical `If-Match`-on-`POST`
+     * reason; nothing else about the contract changes. */
+    withdraw(options: WithdrawExpenseClaimOptions): Promise<KaafilResponse<ExpenseResponse>>;
+    /** `POST /api/v1/trips/{ref}/expenses/{id}/claim-status` — partner API
+     * key ONLY; a manager bearer answers `401 UNAUTHENTICATED`, never `403`.
+     * The CRM's own decision, mirrored — Kaafil never approves, rejects or
+     * pays. `status` accepts only `ClaimStatusIngest`'s three values;
+     * `SUBMITTED`/`WITHDRAWN` here is `422 VALIDATION_ERROR`. The response's
+     * `verdict` (`applied`/`ignored_stale`) tells the CRM whether this
+     * decision actually landed or arrived after a newer one already had. */
+    ingest(options: IngestClaimStatusOptions): Promise<KaafilResponse<ClaimStatusIngestResponse>>;
+}
+interface ExpensesResource {
+    /** `GET /api/v1/trips/{ref}/expenses` — a trip's expenses, with category
+     * totals and a spend summary over the filtered set (live rows only). See
+     * this file's header for the delta-cursor semantics. */
+    list(options: ListExpensesOptions): Promise<KaafilResponse<ExpenseListResponse>>;
+    /** `GET /api/v1/trips/{ref}/expenses/{id}` — one expense, including its
+     * claim view. `id` is a plain Kaafil id, never dual-resolved. */
+    read(options: ReadExpenseOptions): Promise<KaafilResponse<ExpenseResponse>>;
+    /** `POST /api/v1/trips/{ref}/expenses` — logs an on-trip spend. See this
+     * file's header for `FLOAT_CASH` auto-coupling and `submitClaim`. */
+    log(options: LogExpenseOptions): Promise<KaafilResponse<ExpenseResponse>>;
+    /** `PATCH /api/v1/trips/{ref}/expenses/{id}/receipt` — back-fills
+     * `receiptFileKey` against a confirmed (`ready`) upload from `files.*`. */
+    linkReceipt(options: LinkExpenseReceiptOptions): Promise<KaafilResponse<ExpenseResponse>>;
+    /** `DELETE /api/v1/trips/{ref}/expenses/{id}/void` — reverses the paired
+     * float movement and cascades an open claim. See this file's header for
+     * the `DELETE`-not-`POST` note. */
+    void(options: VoidExpenseOptions): Promise<KaafilResponse<ExpenseResponse>>;
+    readonly claims: ExpenseClaimsResource;
+}
+
+/**
+ * `files` — the blob lane: request a presigned upload slot, confirm it,
+ * read metadata, and mint a short-lived signed GET. `architecture/08-
+ * sdk.md §4`. `request`/`meta`/`url` accept a manager session OR an API
+ * key; `confirm` is `managerAuth`-only — a manager confirms the upload
+ * they themselves just made.
+ *
+ * ── THE FOUR-STATUS LIFECYCLE ────────────────────────────────────────────
+ *
+ * `FileResponse.status` is `pending → ready → orphaned`/`purged`. Bytes
+ * never pass through this SDK or the Kaafil API at all: `request()` hands
+ * back a presigned `PUT` URL (`CreateFileResponse.uploadUrl`) that the
+ * caller's own HTTP stack uses to write directly to object storage, with
+ * NO Kaafil auth header — the signed URL itself is the authorization. This
+ * package does not perform that `PUT`; it only mints the URL and later
+ * confirms what landed.
+ *
+ * `confirm()` verifies the object actually arrived — existence, the
+ * declared `sizeBytes`, and the leading bytes against `contentType`'s file
+ * signature — because the presigned `PUT` pins `sizeBytes` into its
+ * signature but NOT `contentType`, so a caller-declared type is otherwise
+ * unverified. A mismatch answers `422 UPLOAD_MISMATCH` and the file stays
+ * `pending`; re-`PUT` and re-confirm until the presigned URL's window
+ * lapses. On success `retentionClass` is stamped SERVER-SIDE from
+ * `purpose` (never client-declared) and the file flips to `ready`.
+ *
+ * `url()` mints a fresh 5-minute signed GET on every call — never stored,
+ * never reused — and only for a `ready` file. A `purged` file answers
+ * `410 FILE_PURGED`: the metadata row survives forever, the bytes do not.
+ * `meta()` itself never 404s for a purged file — it is the one read that
+ * still answers `200` whatever `status` says, which is how a caller tells
+ * "gone" (`410` from `url()`) apart from "never existed" (`404` from
+ * `meta()`) without a second not-found class.
+ *
+ * `purpose ∈ FilePurpose` gates what `contentType ∈ FileContentType` may
+ * accompany it server-side; both are `../generated/enums.ts` constants
+ * that come from the same vendored spec.
+ */
+
+type CreateFileResponse = components['schemas']['CreateFileResponse'];
+type FileResponse = components['schemas']['FileResponse'];
+type FileUrlResponse = components['schemas']['FileUrlResponse'];
+type RequestFileUploadRequest = components['schemas']['RequestFileUploadRequest'];
+interface RequestFileUploadOptions extends RequestFileUploadRequest {
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReadFileOptions {
+    readonly fileId: string;
+    readonly signal?: AbortSignal;
+}
+interface ConfirmFileUploadOptions {
+    readonly fileId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReadFileUrlOptions {
+    readonly fileId: string;
+    readonly signal?: AbortSignal;
+}
+interface FilesResource {
+    /** `POST /api/v1/files` — mints a `pending` metadata row plus a presigned
+     * `PUT`, 15-minute window, `contentType`/`sizeBytes` pinned as request
+     * conditions. This method never uploads bytes itself — see this file's
+     * header. */
+    request(options: RequestFileUploadOptions): Promise<KaafilResponse<CreateFileResponse>>;
+    /** `GET /api/v1/files/{id}` — the metadata skeleton, `200` for every
+     * status including `purged`. Never carries `storageKey`, `tripRef` or
+     * `agencyId`; `retentionClass` is `null` until the file is `ready`. */
+    meta(options: ReadFileOptions): Promise<KaafilResponse<FileResponse>>;
+    /** `POST /api/v1/files/{id}/confirm` — verifies the uploaded object and
+     * flips `pending` → `ready`. See this file's header for the mismatch and
+     * retention-stamping behaviour. */
+    confirm(options: ConfirmFileUploadOptions): Promise<KaafilResponse<FileResponse>>;
+    /** `GET /api/v1/files/{id}/url` — a fresh 5-minute signed GET for a
+     * `ready` file. `410 FILE_PURGED` once the bytes are gone. */
+    url(options: ReadFileUrlOptions): Promise<KaafilResponse<FileUrlResponse>>;
+}
+
+/**
+ * `float` — cash advanced to a manager, its ledger, and the derived
+ * per-manager balance. `architecture/08-sdk.md §4`.
+ *
+ * `readSummary`/`readLedger`/`issue`/`adjust` accept a manager session, an
+ * API key, OR an agency-admin session; `return` is `managerAuth`-only —
+ * only the manager holding the cash may hand it back (an admin is
+ * view-only on that row).
+ *
+ * Every movement is one of four `type`s (`ISSUE|RETURN|ADJUSTMENT|EXPENSE`)
+ * with a `direction ∈ FloatDirection` (`IN|OUT`) — `EXPENSE` movements are
+ * created by `expenses.log` when `paymentMode: 'FLOAT_CASH'`, never by a
+ * method on this resource directly.
+ *
+ * ── THE NEGATIVE-FLOAT GUARD ─────────────────────────────────────────────
+ *
+ * Every `OUT` movement — `return()` and `adjust()` with `direction: 'OUT'`
+ * — is guarded: `amountMinor` must not exceed the manager's current
+ * derived `balanceMinor`, checked and enforced under an advisory lock so
+ * two concurrent `OUT`s can never both pass the same stale read. A refusal
+ * is `422 BUSINESS_RULE_VIOLATION` with `details.currentBalanceMinor` — the
+ * figure the guard actually compared against. `issue()` (`direction: 'IN'`,
+ * always additive) and `adjust()` with `direction: 'IN'` are never guarded.
+ *
+ * `adjust()`'s `note` is REQUIRED (the audit trail of every manual
+ * correction) — unlike `issue()`/`return()`, where it is optional.
+ * `issue()` never accepts a `currency` field: every write takes the trip's
+ * own currency, never a caller-named one.
+ *
+ * ── DERIVED, NOT DELTA-MERGEABLE ─────────────────────────────────────────
+ *
+ * `readSummary()`'s rows are entirely derived (`issuedMinor`,
+ * `returnedMinor`, `spentMinor`, `adjustmentsMinor`, `balanceMinor`) —
+ * nothing here is stored. `since` narrows WHICH managers are returned (only
+ * those with a movement at or after the cursor) but every returned row
+ * still carries its FULL current balance, never a partial delta — a
+ * derived scalar cannot be delta-merged the way a versioned list row can.
+ * `mergeDeltaRows`/`isTombstone` (`../delta/cursor.ts`) do not apply here:
+ * there is no tombstone case and no per-row `version` to compare.
+ * `readLedger()` carries no `since` at all — it always returns one
+ * manager's complete movement history, each row stamped with
+ * `runningBalanceMinor` immediately after that row.
+ */
+
+type FloatSummaryResponse = components['schemas']['FloatSummaryResponse'];
+type FloatLedgerResponse = components['schemas']['FloatLedgerResponse'];
+type AdjustFloatResponse = components['schemas']['AdjustFloatResponse'];
+type IssueFloatResponse = components['schemas']['IssueFloatResponse'];
+type ReturnFloatResponse = components['schemas']['ReturnFloatResponse'];
+type AdjustFloatRequest = components['schemas']['AdjustFloatRequest'];
+type IssueFloatRequest = components['schemas']['IssueFloatRequest'];
+type ReturnFloatRequest = components['schemas']['ReturnFloatRequest'];
+interface ReadFloatSummaryOptions {
+    readonly tripRef: string;
+    /** Narrows which managers are returned to those with a movement at or
+     * after this cursor. See this file's header — the rows themselves are
+     * never partial, so this is not a `../delta/cursor.ts` cursor. */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReadFloatLedgerOptions {
+    readonly tripRef: string;
+    readonly managerId: string;
+    readonly signal?: AbortSignal;
+}
+interface IssueFloatOptions extends IssueFloatRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReturnFloatOptions extends ReturnFloatRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface AdjustFloatOptions extends AdjustFloatRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface FloatResource {
+    /** `GET /api/v1/trips/{ref}/float` — one row per manager who has ever had
+     * a movement on this trip, entirely derived. See this file's header. */
+    readSummary(options: ReadFloatSummaryOptions): Promise<KaafilResponse<FloatSummaryResponse>>;
+    /** `GET /api/v1/trips/{ref}/float/{managerId}/ledger` — one manager's
+     * full movement history, ordered `(createdAt asc, id asc)`, each row
+     * carrying `runningBalanceMinor`. `404` if `managerId` does not name a
+     * manager currently assigned to this trip. */
+    readLedger(options: ReadFloatLedgerOptions): Promise<KaafilResponse<FloatLedgerResponse>>;
+    /** `POST /api/v1/trips/{ref}/float/issue` — `type=ISSUE`, `direction=IN`,
+     * never negative-float guarded. An admin or the manager themselves may
+     * call this; both paths produce the identical row. */
+    issue(options: IssueFloatOptions): Promise<KaafilResponse<IssueFloatResponse>>;
+    /** `POST /api/v1/trips/{ref}/float/return` — `type=RETURN`,
+     * `direction=OUT`, `managerAuth`-only and negative-float guarded. See
+     * this file's header. */
+    return(options: ReturnFloatOptions): Promise<KaafilResponse<ReturnFloatResponse>>;
+    /** `POST /api/v1/trips/{ref}/float/adjust` — `type=ADJUSTMENT`, direction
+     * named by the caller; `note` is required. `direction: 'OUT'` is
+     * negative-float guarded identically to `return()`; `direction: 'IN'`
+     * never is. */
+    adjust(options: AdjustFloatOptions): Promise<KaafilResponse<AdjustFloatResponse>>;
+}
+
+/**
+ * `itinerary` — the day cards and their ordered items, plus the change log.
+ * `architecture/08-sdk.md §4`.
+ *
+ * `read` and `changeLog.list` accept an API key, a manager session OR an
+ * agency-admin session (`readItinerary`/`readItineraryChangeLog` declare all
+ * three as alternatives, never an AND) — the consumer never chooses which;
+ * `../auth/credentials.ts`'s `CredentialResolver` picks whichever scheme the
+ * configured credential satisfies. Every WRITE here is `managerAuth`-only: the
+ * itinerary is edited on the ground, and an API-key write answers `401`.
+ *
+ * Every path parameter is a named field on its options object — never a
+ * positional string — so `items.patch` (a trip ref AND an item id) and
+ * `days.patch` (a trip ref AND a day index) can't be called with their
+ * arguments swapped.
+ *
+ * `read` is one operation with three modes, because OpenAPI keys an operation
+ * by (path, method) and all three are `GET /trips/{ref}/itinerary`: the full
+ * aggregate, `?dayIndex=` for one day, and `?since=` for a delta. The two
+ * compose. For the delta mode, drive `since` through
+ * `../delta/cursor.ts`'s `createDeltaCursor` rather than by hand — that file's
+ * header is the argument for why any other cursor loses rows.
+ */
+
+type ItineraryReadResponse = components['schemas']['ItineraryReadResponse'];
+type ItineraryDayResponse = components['schemas']['ItineraryDayResponse'];
+type ItineraryItemResponse = components['schemas']['ItineraryItemResponse'];
+type ItineraryItemTombstoneResponse = components['schemas']['ItineraryItemTombstoneResponse'];
+type ItineraryReorderResponse = components['schemas']['ItineraryReorderResponse'];
+type ItineraryChangeLogEntryResponse = components['schemas']['ItineraryChangeLogEntryResponse'];
+type AddItineraryItemRequest = components['schemas']['AddItineraryItemRequest'];
+type PatchItineraryItemRequest = components['schemas']['PatchItineraryItemRequest'];
+type ReorderItineraryItemRequest = components['schemas']['ReorderItineraryItemRequest'];
+type PatchItineraryDayRequest = components['schemas']['PatchItineraryDayRequest'];
+/**
+ * One row of `read`'s `items[]`: a live item, or the tombstone for one deleted
+ * since the cursor. Aliased off the response type rather than restated, so the
+ * union stays whatever the contract says it is.
+ *
+ * Named and exported because a consumer writing a render function over
+ * `items` has to name its parameter, and the union is the whole point — see
+ * `../delta/cursor.ts`'s `isTombstone`.
+ */
+type ItineraryItemDeltaRow = ItineraryReadResponse['items'][number];
+interface ReadItineraryOptions {
+    readonly tripRef: string;
+    /** Narrows the same shape to one day. 0-based, as `days[].dayIndex` reports it. */
+    readonly dayIndex?: number;
+    /**
+     * The delta cursor: a previous response's own `meta.serverTime`, and nothing
+     * else. Omit it for the full aggregate. Prefer `createDeltaCursor`
+     * (`../delta/cursor.ts`) over passing this by hand — the boundary is the one
+     * thing that silently loses rows, and that module owns it.
+     */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface AddItineraryItemOptions extends Omit<AddItineraryItemRequest, 'isoDate' | 'startTime' | 'endTime'> {
+    readonly tripRef: string;
+    /**
+     * Which day the item belongs to, as a date. The engine resolves it to a day
+     * index in the TRIP's timezone and find-or-creates the day — a client never
+     * computes a day index itself, and must not, because the answer depends on a
+     * timezone the client may not be in.
+     */
+    readonly isoDate: DateTimeInput;
+    readonly startTime?: DateTimeInput | null;
+    readonly endTime?: DateTimeInput | null;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface PatchItineraryItemOptions extends Omit<PatchItineraryItemRequest, 'startTime' | 'endTime'> {
+    readonly tripRef: string;
+    readonly itemId: string;
+    readonly startTime?: DateTimeInput | null;
+    readonly endTime?: DateTimeInput | null;
+    /**
+     * Required, not optional. A missing `If-Match` and a stale one both answer
+     * `409 CONFLICT_VERSION` — identically confusing either way — so this method
+     * makes forgetting it impossible instead of merely discouraged. Pass the
+     * `version` from the item as last read. The SDK builds the `If-Match` header
+     * itself; never set it in `headers`.
+     */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface DeleteItineraryItemOptions {
+    readonly tripRef: string;
+    readonly itemId: string;
+    /** See `PatchItineraryItemOptions.version` — same contract. */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface ReorderItineraryItemOptions extends ReorderItineraryItemRequest {
+    readonly tripRef: string;
+    readonly itemId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ItineraryItemsResource {
+    /** `POST …/itinerary/items` — appends at the tail of its day. */
+    add(options: AddItineraryItemOptions): Promise<KaafilResponse<ItineraryItemResponse>>;
+    patch(options: PatchItineraryItemOptions): Promise<KaafilResponse<ItineraryItemResponse>>;
+    /**
+     * Soft-deletes the item. Answers the TOMBSTONE — the same `_tombstone`
+     * marker a later `?since=` pull would carry for it — rather than an empty
+     * body, so the caller that issued the delete applies the identical drop to
+     * its local store as one that learned about it from a delta.
+     */
+    remove(options: DeleteItineraryItemOptions): Promise<KaafilResponse<ItineraryItemTombstoneResponse>>;
+    /**
+     * Moves the item to `index` within its own day; the index is clamped
+     * server-side, and the whole day is re-stamped densely so two devices
+     * replaying the same reorder land on identical `sortOrder` values.
+     *
+     * No `version` and no `If-Match`, deliberately: a reorder is last-write-wins
+     * by design, and a conflict is resolved by re-reading the day (the response
+     * already carries the day's full item list, in its new order).
+     */
+    reorder(options: ReorderItineraryItemOptions): Promise<KaafilResponse<ItineraryReorderResponse>>;
+}
+interface PatchItineraryDayOptions extends PatchItineraryDayRequest {
+    readonly tripRef: string;
+    /** 0-based, as `days[].dayIndex` reports it — the day's position, not its id. */
+    readonly dayIndex: number;
+    /** See `PatchItineraryItemOptions.version` — same contract. */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface ItineraryDaysResource {
+    /** `PATCH …/itinerary/days/{dayIndex}` — the card title and the summary line. */
+    patch(options: PatchItineraryDayOptions): Promise<KaafilResponse<ItineraryDayResponse>>;
+}
+interface ListItineraryChangeLogOptions {
+    readonly tripRef: string;
+    /** See `ReadItineraryOptions.since`. */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface ItineraryChangeLogResource {
+    /** `GET …/itinerary/change-log` — the most recent entries, newest first.
+     * Not cursor-paginated (no `cursor`/`limit` query params in the spec). */
+    list(options: ListItineraryChangeLogOptions): Promise<KaafilResponse<readonly ItineraryChangeLogEntryResponse[]>>;
+}
+interface ItineraryResource {
+    read(options: ReadItineraryOptions): Promise<KaafilResponse<ItineraryReadResponse>>;
+    readonly items: ItineraryItemsResource;
+    readonly days: ItineraryDaysResource;
+    readonly changeLog: ItineraryChangeLogResource;
+}
+
+/**
+ * `pickups` — the stop list, reorder, manifest-by-pickup, assign/board and
+ * the close/reopen policy. `architecture/08-sdk.md §4`.
+ *
+ * `list` and `manifestByPickup` accept a manager session, an agency-admin
+ * session OR an API key (three alternatives, never an AND); every WRITE is
+ * `managerAuth`-only, the same split `seating`, `rooming` and `itinerary`
+ * have and for the same reason — pickups are worked on the ground.
+ *
+ * Every path parameter is a named field on its options object — never a
+ * positional string — so `assign` (a trip ref AND a stop id) can't be called
+ * with its arguments swapped.
+ *
+ * ── ONE `close` METHOD, TWO POLICIES, ONE CODE ──────────────────────────────
+ *
+ * `close()` is a single operation whichever `Trip.eventType` the trip carries
+ * — never two endpoints and never two codes. On a `TRIP`, every `PENDING`
+ * traveller must appear in `resolutions[]` with a terminal status, and
+ * `confirm` is ignored; on a `TREK`, `resolutions[]` is optional and a short
+ * close (`boardedCount < expectedCount`) needs `confirm: true` PLUS
+ * `confirmedHeadCount`. Both branches answer the SAME `422 STOP_HAS_PENDING`
+ * when they refuse — a TREK short-close refusal additionally carries
+ * `details.requiresConfirm: true`, which is what tells a caller to show the
+ * confirm sheet rather than the per-traveller resolver, and NOT a second
+ * code. `details` is untyped at the transport boundary (the envelope
+ * schema's own `additionalProperties: {}`), so read it defensively:
+ * `error.details?.requiresConfirm === true`.
+ *
+ * `confirmedHeadCount` disagreeing with the actual count is FLAGGED
+ * (`CloseResponse.headCountMismatch`), never blocking — "a manager on a
+ * trailhead can't wait forever."
+ */
+
+type PickupStopResponse = components['schemas']['PickupStopResponse'];
+type PickupStopDeltaResponse = components['schemas']['PickupStopDeltaResponse'];
+type PickupStopDeleteResponse = components['schemas']['PickupStopDeleteResponse'];
+type ManifestByPickupResponse = components['schemas']['ManifestByPickupResponse'];
+type AssignResponse = components['schemas']['AssignResponse'];
+type BoardResponse = components['schemas']['BoardResponse'];
+type CloseResponse = components['schemas']['CloseResponse'];
+type ReopenResponse = components['schemas']['ReopenResponse'];
+type CreatePickupStopRequest = components['schemas']['CreatePickupStopRequest'];
+type PatchPickupStopRequest = components['schemas']['PatchPickupStopRequest'];
+type ReorderPickupStopsRequest = components['schemas']['ReorderPickupStopsRequest'];
+type AssignPickupTravellerRequest = components['schemas']['AssignPickupTravellerRequest'];
+type BoardPickupTravellerRequest = components['schemas']['BoardPickupTravellerRequest'];
+type ClosePickupStopRequest = components['schemas']['ClosePickupStopRequest'];
+/**
+ * One row of `list`'s result: a live stop, or the tombstone for one deleted
+ * since the cursor. Aliased off the response type rather than restated, so
+ * the union stays whatever the contract says it is. See `../delta/cursor.ts`'s
+ * `isTombstone`.
+ */
+type PickupStopDeltaRow = PickupStopDeltaResponse;
+interface ListPickupStopsOptions {
+    readonly tripRef: string;
+    /** Narrows to one stop kind. Omitted lists both `PICKUP` and `DROP`. */
+    readonly kind?: components['schemas']['PickupStopResponse']['kind'];
+    /**
+     * The delta cursor: a previous response's own `meta.serverTime`, and
+     * nothing else. Omit it for the full list. Prefer `createDeltaCursor`
+     * (`../delta/cursor.ts`) over passing this by hand — the boundary is the
+     * one thing that silently loses rows, and that module owns it.
+     */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReadManifestByPickupOptions {
+    readonly tripRef: string;
+    /** See `ListPickupStopsOptions.kind`. */
+    readonly kind?: components['schemas']['PickupStopResponse']['kind'];
+    readonly signal?: AbortSignal;
+}
+interface CreatePickupStopOptions extends Omit<CreatePickupStopRequest, 'scheduledTime'> {
+    readonly tripRef: string;
+    readonly scheduledTime: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface PatchPickupStopOptions extends Omit<PatchPickupStopRequest, 'scheduledTime'> {
+    readonly tripRef: string;
+    readonly pointId: string;
+    readonly scheduledTime?: DateTimeInput;
+    /**
+     * Required, not optional. A missing `If-Match` and a stale one both answer
+     * `409 CONFLICT_VERSION` — identically confusing either way — so this
+     * method makes forgetting it impossible instead of merely discouraged.
+     * Pass the `version` from the stop as last read. The SDK builds the
+     * `If-Match` header itself; never set it in `headers`.
+     *
+     * Changing `kind` while the stop holds assignments is refused with
+     * `422 BUSINESS_RULE_VIOLATION` and `details.assignedCount` — reassign or
+     * clear the stop first.
+     */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface DeletePickupStopOptions {
+    readonly tripRef: string;
+    readonly pointId: string;
+    /** See `PatchPickupStopOptions.version` — same contract. */
+    readonly version: number;
+    /** Releases every assignment on this stop back to unassigned before
+     * deleting it. Without it, a stop with assignments is refused. */
+    readonly force?: boolean;
+    readonly signal?: AbortSignal;
+}
+interface ReorderPickupStopsOptions extends ReorderPickupStopsRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface AssignPickupTravellerOptions extends AssignPickupTravellerRequest {
+    readonly tripRef: string;
+    readonly pointId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface BoardPickupTravellerOptions extends BoardPickupTravellerRequest {
+    readonly tripRef: string;
+    readonly pointId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ClosePickupStopOptions extends ClosePickupStopRequest {
+    readonly tripRef: string;
+    readonly pointId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReopenPickupStopOptions {
+    readonly tripRef: string;
+    readonly pointId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface PickupsResource {
+    /** `GET /api/v1/trips/{ref}/pickups`. With `?since=` the rows are
+     * `PickupStopDeltaResponse` — a union with the tombstone, so the drop case
+     * cannot be forgotten. Without one, no tombstone can appear. */
+    list(options: ListPickupStopsOptions): Promise<KaafilResponse<readonly PickupStopDeltaRow[]>>;
+    create(options: CreatePickupStopOptions): Promise<KaafilResponse<PickupStopResponse>>;
+    patch(options: PatchPickupStopOptions): Promise<KaafilResponse<PickupStopResponse>>;
+    remove(options: DeletePickupStopOptions): Promise<KaafilResponse<PickupStopDeleteResponse>>;
+    reorder(options: ReorderPickupStopsOptions): Promise<KaafilResponse<readonly PickupStopResponse[]>>;
+    /**
+     * `POST …/pickups/{pointId}/assign` — puts one traveller on one stop. If
+     * they were already on a different stop of the SAME `kind`, the move is one
+     * atomic delete+create (R1: at most one `PICKUP` and one `DROP` per
+     * traveller, enforced by a composite unique, not merely a service-layer
+     * promise), and the response's `previousPickupPointId` names where they
+     * moved from.
+     */
+    assign(options: AssignPickupTravellerOptions): Promise<KaafilResponse<AssignResponse>>;
+    board(options: BoardPickupTravellerOptions): Promise<KaafilResponse<BoardResponse>>;
+    /** See this file's header for the close policy: one method, two branches
+     * on `Trip.eventType`, one code (`STOP_HAS_PENDING`) either way. */
+    close(options: ClosePickupStopOptions): Promise<KaafilResponse<CloseResponse>>;
+    /** Flips `CLOSED → OPEN` and clears `closedAt`/`closedByManagerId` — there
+     * is no `REOPENED` state. The next `close()` on this stop emits a fresh
+     * CORRECTIVE `pickup.stop_closed` event, `reopened: true`. */
+    reopen(options: ReopenPickupStopOptions): Promise<KaafilResponse<ReopenResponse>>;
+    /** `GET …/manifest-by-pickup` — the roster grouped by stop, for a printed
+     * or on-screen boarding sheet. Renders the same glyph/tone canon as
+     * `rooming`'s and `seating`'s occupants — no second derivation. */
+    manifestByPickup(options: ReadManifestByPickupOptions): Promise<KaafilResponse<ManifestByPickupResponse>>;
+}
+
+/**
+ * `rooming` — the board, stay windows, rooms, manual bed assignment and
+ * auto-assign. `architecture/08-sdk.md §4`.
+ *
+ * `board.read` and `stayWindows.list` accept a manager session, an
+ * agency-admin session OR an API key (three alternatives, never an AND); every
+ * WRITE is `managerAuth`-only, the same split `itinerary` has and for the same
+ * reason — rooming is decided on the ground.
+ *
+ * Rooming is a gated capability (`GROUP` trips only, behind the `rooming` plan
+ * flag), so its refusals are ordinary typed errors a caller should expect:
+ * `402` for a flag that is off, `422 CAPABILITY_UNAVAILABLE` on a
+ * `PERSONALIZED` trip, `422 READ_ONLY_ROLE` for a COORDINATOR. See
+ * `../http/errors.ts`.
+ *
+ * Every path parameter is a named field on its options object — never a
+ * positional string — so `rooms.patch` (a trip ref AND a room id) and
+ * `stayWindows.patch` (a trip ref AND a window id) can't be called with their
+ * arguments swapped. The two child ids are named `roomId` and `windowId` after
+ * the thing they identify, never both `id`.
+ *
+ * `HEURISTIC_SEVERITY` and the glyph/tone vocabulary a client needs to RENDER
+ * this module's output are not here — they are not on the wire. See
+ * `../rooming/vocabulary.ts`.
+ */
+
+type RoomingBoardResponse = components['schemas']['RoomingBoardResponse'];
+type RoomingStayWindowResponse = components['schemas']['RoomingStayWindowResponse'];
+type RoomingStayWindowDeltaResponse = components['schemas']['RoomingStayWindowDeltaResponse'];
+type RoomingRoomResponse = components['schemas']['RoomingRoomResponse'];
+type RoomingDeleteResponse = components['schemas']['RoomingDeleteResponse'];
+type RoomingAssignResponse = components['schemas']['RoomingAssignResponse'];
+type RoomingAutoAssignResponse = components['schemas']['RoomingAutoAssignResponse'];
+type CreateRoomingStayWindowRequest = components['schemas']['CreateRoomingStayWindowRequest'];
+type PatchRoomingStayWindowRequest = components['schemas']['PatchRoomingStayWindowRequest'];
+type CreateRoomingRoomRequest = components['schemas']['CreateRoomingRoomRequest'];
+type PatchRoomingRoomRequest = components['schemas']['PatchRoomingRoomRequest'];
+type AssignRoomingBedRequest = components['schemas']['AssignRoomingBedRequest'];
+type AutoAssignRoomingRequest = components['schemas']['AutoAssignRoomingRequest'];
+/**
+ * One row of the board's `rooms[]`: a live room, or the tombstone for one
+ * deleted since the cursor. Aliased off the response type, never restated.
+ */
+type RoomingRoomDeltaRow = RoomingBoardResponse['rooms'][number];
+/** One traveller's chip, wherever it appears — in a bed, or in `unassigned[]`. */
+type RoomingOccupant = RoomingBoardResponse['unassigned'][number];
+/**
+ * `autoAssign`'s rules block, named so a caller can build one and hold it in a
+ * variable. Indexed off the request type, so the three knobs stay whatever the
+ * contract says they are.
+ */
+type RoomingAutoAssignRules = NonNullable<AutoAssignRoomingRequest['rules']>;
+interface ReadRoomingBoardOptions {
+    readonly tripRef: string;
+    /** Narrows the board to one stay window. Omitted reads every window. */
+    readonly stayWindowId?: string;
+    /**
+     * The delta cursor: a previous response's own `meta.serverTime`, and nothing
+     * else. Omit it for the full board. Prefer `createDeltaCursor`
+     * (`../delta/cursor.ts`) over passing this by hand — the boundary is the one
+     * thing that silently loses rows, and that module owns it.
+     */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface ListRoomingStayWindowsOptions {
+    readonly tripRef: string;
+    /** See `ReadRoomingBoardOptions.since`. */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface CreateRoomingStayWindowOptions extends Omit<CreateRoomingStayWindowRequest, 'startDate' | 'endDate'> {
+    readonly tripRef: string;
+    readonly startDate: DateTimeInput;
+    /**
+     * Half-open with `startDate`: a checkout date equal to the next window's
+     * check-in is legal, because multi-hotel trips are contiguous by nature.
+     * Overlap beyond that is refused with `422 BUSINESS_RULE_VIOLATION` and
+     * `details.rule === 'stay_window_overlap'`.
+     */
+    readonly endDate: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface PatchRoomingStayWindowOptions extends Omit<PatchRoomingStayWindowRequest, 'startDate' | 'endDate'> {
+    readonly tripRef: string;
+    readonly windowId: string;
+    readonly startDate?: DateTimeInput;
+    readonly endDate?: DateTimeInput;
+    /**
+     * Required, not optional. A missing `If-Match` and a stale one both answer
+     * `409 CONFLICT_VERSION` — identically confusing either way — so this method
+     * makes forgetting it impossible instead of merely discouraged. Pass the
+     * `version` from the window as last read. The SDK builds the `If-Match`
+     * header itself; never set it in `headers`.
+     */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface DeleteRoomingStayWindowOptions {
+    readonly tripRef: string;
+    readonly windowId: string;
+    /** See `PatchRoomingStayWindowOptions.version` — same contract. */
+    readonly version: number;
+    /**
+     * Deleting a window that still has rooms with occupants is REFUSED
+     * (`422 BUSINESS_RULE_VIOLATION`, `details.rule ===
+     * 'stay_window_has_assignments'`) unless this is `true`, which also releases
+     * the beds. A query param and never a body, because a DELETE body is not
+     * reliably carried; an explicit opt-in and never the default, because the
+     * refusal is the whole safety property — a manager who did not mean to empty
+     * a hotel gets told, not obeyed.
+     */
+    readonly force?: boolean;
+    readonly signal?: AbortSignal;
+}
+interface RoomingStayWindowsResource {
+    /**
+     * `GET …/rooming/stay-windows`. With `?since=` the rows are
+     * `RoomingStayWindowDeltaResponse` — a union with the tombstone, so the drop
+     * case cannot be forgotten (`../delta/cursor.ts`'s `isTombstone`). Without
+     * one, no tombstone can appear: a cold read has nothing to drop.
+     */
+    list(options: ListRoomingStayWindowsOptions): Promise<KaafilResponse<readonly RoomingStayWindowDeltaResponse[]>>;
+    create(options: CreateRoomingStayWindowOptions): Promise<KaafilResponse<RoomingStayWindowResponse>>;
+    patch(options: PatchRoomingStayWindowOptions): Promise<KaafilResponse<RoomingStayWindowResponse>>;
+    remove(options: DeleteRoomingStayWindowOptions): Promise<KaafilResponse<RoomingDeleteResponse>>;
+}
+interface CreateRoomingRoomOptions extends CreateRoomingRoomRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface PatchRoomingRoomOptions extends PatchRoomingRoomRequest {
+    readonly tripRef: string;
+    readonly roomId: string;
+    /** See `PatchRoomingStayWindowOptions.version` — same contract. */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface DeleteRoomingRoomOptions {
+    readonly tripRef: string;
+    readonly roomId: string;
+    /** See `PatchRoomingStayWindowOptions.version` — same contract. */
+    readonly version: number;
+    /** See `DeleteRoomingStayWindowOptions.force` — same contract, one room's worth. */
+    readonly force?: boolean;
+    readonly signal?: AbortSignal;
+}
+interface RoomingRoomsResource {
+    create(options: CreateRoomingRoomOptions): Promise<KaafilResponse<RoomingRoomResponse>>;
+    /**
+     * Beds are synthesised from `capacity` (`A`..`H`, truncated), never stored,
+     * so `beds[]` on the response is derived — dropping `capacity` below the
+     * room's current occupancy is refused with `422 BUSINESS_RULE_VIOLATION` and
+     * `details.rule === 'room_capacity_below_occupancy'` rather than silently
+     * evicting whoever was in the last bed.
+     */
+    patch(options: PatchRoomingRoomOptions): Promise<KaafilResponse<RoomingRoomResponse>>;
+    remove(options: DeleteRoomingRoomOptions): Promise<KaafilResponse<RoomingDeleteResponse>>;
+}
+interface AssignRoomingBedOptions extends AssignRoomingBedRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface AutoAssignRoomingOptions extends AutoAssignRoomingRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface RoomingResource {
+    /** `GET /api/v1/trips/{ref}/rooming` — windows, rooms with their beds, the
+     * unassigned roster, and the summary counters. */
+    read(options: ReadRoomingBoardOptions): Promise<KaafilResponse<RoomingBoardResponse>>;
+    /**
+     * `POST …/rooming/assign` — puts one traveller in one bed. `bedLabel: null`
+     * un-assigns them. If the target bed is taken the occupant is displaced, and
+     * the response names them in `displacedTravellerId` rather than leaving the
+     * caller to diff two boards to notice a second person moved.
+     */
+    assign(options: AssignRoomingBedOptions): Promise<KaafilResponse<RoomingAssignResponse>>;
+    /**
+     * `POST …/rooming/auto-assign`. `dryRun: true` returns the plan without
+     * writing it; `dryRun: false` returns the plan it actually applied. The two
+     * are the SAME computation — the solver is pure and the only difference is
+     * whether the result is also written — so a preview and its apply agree by
+     * construction, and a client that stored the preview can diff it against the
+     * applied plan to see whether the rooms moved underneath it.
+     *
+     * Every rule reports an outcome in `perRule`, including rules that had
+     * nothing to do; a relaxation is never silent. How loudly to render each one
+     * is `HEURISTIC_SEVERITY` in `../rooming/vocabulary.ts`. A traveller who got
+     * no bed is in `unassigned[]` WITH a reason — absence from `plan` alone is
+     * ambiguous, because a manually-pinned traveller is also absent and is fine.
+     */
+    autoAssign(options: AutoAssignRoomingOptions): Promise<KaafilResponse<RoomingAutoAssignResponse>>;
+    readonly stayWindows: RoomingStayWindowsResource;
+    readonly rooms: RoomingRoomsResource;
+}
+
+/**
+ * `seating` — the transport board, vehicles, manual seat assignment,
+ * auto-assign and the vehicle-manager link. `architecture/08-sdk.md §4`.
+ *
+ * `read` accepts a manager session, an agency-admin session OR an API key
+ * (three alternatives, never an AND); every WRITE is `managerAuth`-only, the
+ * same split `rooming` and `itinerary` have and for the same reason — seating
+ * is decided on the ground.
+ *
+ * Every path parameter is a named field on its options object — never a
+ * positional string — so `vehicles.patch` (a trip ref AND a vehicle id) can't
+ * be called with its arguments swapped.
+ *
+ * `deriveOccupantMark` and `synthesiseBedLabels` — the glyph/tone and
+ * bed-label logic a client needs to RENDER this module's output — are not
+ * here; they are rooming's, imported by the engine's seating module rather
+ * than re-derived (`architecture` 10B notes), and are not on the wire either.
+ * A client renders an occupant's `glyph`/`tone` fields straight off the
+ * response, the same as `rooming`'s occupants.
+ *
+ * ── THE TYPE↔LAYOUT RULE, AND WHY `seatLabel` CANNOT BE STATICALLY TIED TO IT ──
+ *
+ * A vehicle's `layout` is non-null only for `type ∈ {FLIGHT, TRAIN}`
+ * (`Vehicle_layout_requires_seatable_type`, enforced server-side by a CHECK).
+ * `layout: null` means the vehicle carries no seat map at all — most road
+ * vehicles, because "the label grid was a fiction the manager maintained and
+ * the driver ignored" — and on such a vehicle every assignment's `seatLabel`
+ * is `null`, enforced on write. The converse is deliberately NOT an invariant:
+ * a seat-mapped vehicle may still hold `seatLabel: null` rows (a group
+ * confirmed on a flight before the airline issues seat numbers), so `layout`
+ * being non-null does not mean `seatLabel` is required either.
+ *
+ * `assign()` below is intentionally NOT generic over "which vehicle", so
+ * `AssignSeatingOptions.seatLabel` cannot be narrowed to "required when this
+ * vehicle has a layout, forbidden when it doesn't" at the type level: the
+ * call site names a `vehicleId`, not the vehicle object it was read from, and
+ * whether that id currently has a layout is server-side state this SDK does
+ * not — and must not — cache and re-derive locally (the whole point of a
+ * board read is that the server is the source of truth for it). Encoding the
+ * rule here would mean either accepting a vehicle object just to read one
+ * field, which no other write on this surface does, or building a second,
+ * client-side copy of `seatMapped` that could drift from what the server
+ * actually enforces. So `seatLabel` stays `string | null | undefined` on every
+ * vehicle unconditionally, and the rule is enforced where the truth lives:
+ * the server accepts a `seatLabel` for a seat-less vehicle and silently
+ * ignores it into `null`; the honest type-level statement of this surface is
+ * that `seatLabel` is ALWAYS optional and ALWAYS nullable, never that it
+ * varies by vehicle. Read a vehicle's own `seatMapped` (`SeatingBoardResponse`
+ * / `SeatingVehicleResponse`) before deciding whether to show a seat picker.
+ */
+
+type SeatingBoardResponse = components['schemas']['SeatingBoardResponse'];
+type SeatingVehicleResponse = components['schemas']['SeatingVehicleResponse'];
+type SeatingDeleteVehicleResponse = components['schemas']['SeatingDeleteVehicleResponse'];
+type SeatingAssignResponse = components['schemas']['SeatingAssignResponse'];
+type SeatingAutoAssignResponse = components['schemas']['SeatingAutoAssignResponse'];
+type SeatingManagerLinkResponse = components['schemas']['SeatingManagerLinkResponse'];
+type CreateSeatingVehicleRequest = components['schemas']['CreateSeatingVehicleRequest'];
+type PatchSeatingVehicleRequest = components['schemas']['PatchSeatingVehicleRequest'];
+type AssignSeatingRequest = components['schemas']['AssignSeatingRequest'];
+type AutoAssignSeatingRequest = components['schemas']['AutoAssignSeatingRequest'];
+type LinkSeatingManagerRequest = components['schemas']['LinkSeatingManagerRequest'];
+/**
+ * One row of the board's `vehicles[]`: a live vehicle, or the tombstone for
+ * one deleted since the cursor. Aliased off the response type, never
+ * restated.
+ */
+type SeatingVehicleDeltaRow = SeatingBoardResponse['vehicles'][number];
+/** One traveller's chip in `unassignedPool[]`, or (per vehicle) in
+ * `occupants[]`/`unseatedOnVehicle[]`/a seat's `occupant`. */
+type SeatingOccupant = SeatingBoardResponse['unassignedPool'][number];
+/**
+ * `autoAssign`'s rules block, named so a caller can build one and hold it in
+ * a variable. Indexed off the request type, so the three knobs stay whatever
+ * the contract says they are.
+ */
+type SeatingAutoAssignRules = NonNullable<AutoAssignSeatingRequest['rules']>;
+interface ReadSeatingBoardOptions {
+    readonly tripRef: string;
+    /**
+     * The delta cursor: a previous response's own `meta.serverTime`, and
+     * nothing else. Omit it for the full board. Prefer `createDeltaCursor`
+     * (`../delta/cursor.ts`) over passing this by hand — the boundary is the
+     * one thing that silently loses rows, and that module owns it.
+     */
+    readonly since?: string;
+    readonly signal?: AbortSignal;
+}
+interface CreateSeatingVehicleOptions extends CreateSeatingVehicleRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface PatchSeatingVehicleOptions extends PatchSeatingVehicleRequest {
+    readonly tripRef: string;
+    readonly vehicleId: string;
+    /**
+     * Required, not optional. A missing `If-Match` and a stale one both answer
+     * `409 CONFLICT_VERSION` — identically confusing either way — so this
+     * method makes forgetting it impossible instead of merely discouraged.
+     * Pass the `version` from the vehicle as last read. The SDK builds the
+     * `If-Match` header itself; never set it in `headers`.
+     *
+     * A capacity-down or a `layout` change that would orphan a recorded seat
+     * label is refused with `422 SEATING_CAPACITY_ORPHAN` rather than silently
+     * dropping whoever held that label — see this file's header for the three
+     * forms of the guard.
+     */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface DeleteSeatingVehicleOptions {
+    readonly tripRef: string;
+    readonly vehicleId: string;
+    /** See `PatchSeatingVehicleOptions.version` — same contract. */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface LinkSeatingManagerOptions extends LinkSeatingManagerRequest {
+    readonly tripRef: string;
+    readonly vehicleId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface UnlinkSeatingManagerOptions {
+    readonly tripRef: string;
+    readonly vehicleId: string;
+    /** See `PatchSeatingVehicleOptions.version` — same contract. */
+    readonly version: number;
+    readonly signal?: AbortSignal;
+}
+interface SeatingVehicleManagerResource {
+    /** `POST …/seating/vehicles/{vehicleId}/manager` — links a manager to this
+     * vehicle. Demotes whichever vehicle that manager was previously linked to,
+     * atomically: a manager only ever rides one vehicle. */
+    link(options: LinkSeatingManagerOptions): Promise<KaafilResponse<SeatingManagerLinkResponse>>;
+    unlink(options: UnlinkSeatingManagerOptions): Promise<KaafilResponse<SeatingManagerLinkResponse>>;
+}
+interface SeatingVehiclesResource {
+    create(options: CreateSeatingVehicleOptions): Promise<KaafilResponse<SeatingVehicleResponse>>;
+    patch(options: PatchSeatingVehicleOptions): Promise<KaafilResponse<SeatingVehicleResponse>>;
+    /** Clears every occupant on this vehicle back to the unassigned pool and
+     * unlinks its manager, then deletes it. */
+    remove(options: DeleteSeatingVehicleOptions): Promise<KaafilResponse<SeatingDeleteVehicleResponse>>;
+    readonly manager: SeatingVehicleManagerResource;
+}
+interface AssignSeatingOptions extends AssignSeatingRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface AutoAssignSeatingOptions extends AutoAssignSeatingRequest {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface SeatingResource {
+    /** `GET /api/v1/trips/{ref}/seating` — vehicles with their seats and
+     * occupants, the unassigned pool, and the summary counters. */
+    read(options: ReadSeatingBoardOptions): Promise<KaafilResponse<SeatingBoardResponse>>;
+    /**
+     * `POST …/seating/assign` — puts one traveller in one vehicle (and, on a
+     * seat-mapped vehicle, one seat). `vehicleId: null` moves them to the
+     * unassigned pool. If the target seat is taken the occupant is displaced,
+     * and the response names them in `displacedTravellerId` (plus
+     * `displacedVehicleId`/`displacedSeatLabel`) rather than leaving the caller
+     * to diff two boards to notice a second person moved.
+     */
+    assign(options: AssignSeatingOptions): Promise<KaafilResponse<SeatingAssignResponse>>;
+    /**
+     * `POST …/seating/auto-assign`. `dryRun: true` returns the plan without
+     * writing it; `dryRun: false` returns the plan it actually applied. The two
+     * are the SAME computation — the solver is pure and the only difference is
+     * whether the result is also written — so a preview and its apply agree by
+     * construction.
+     *
+     * Every rule reports an outcome in `perRule`: `applied`, `relaxed`, or
+     * `noop` with `noopReason: 'no_seat_map'` — the third outcome seating has
+     * that rooming does not, because `medicalFirst` and `gender` are
+     * seat-adjacency heuristics with nothing to do on a seat-less vehicle. A
+     * `noop` and a relaxed rule are different facts (a heuristic that could not
+     * apply vs. one that applied a weaker version of itself), so both are
+     * reported rather than one masquerading as the other.
+     */
+    autoAssign(options: AutoAssignSeatingOptions): Promise<KaafilResponse<SeatingAutoAssignResponse>>;
+    readonly vehicles: SeatingVehiclesResource;
+}
+
+/**
+ * `shareTokens` — create, read, revoke. `architecture/08-sdk.md §3.3, §4`;
+ * all three operations are `apiKeyAuth`-only in the spec (server-side mint,
+ * matching `03-auth-and-tokens.md §1`: browsers only ever hold the *minted*
+ * token, never the key that mints it).
+ */
+
+type MintShareTokenRequest = components['schemas']['MintShareTokenRequest'];
+type MintedShareTokenViewResponse = components['schemas']['MintedShareTokenViewResponse'];
+type ShareTokenViewResponse = components['schemas']['ShareTokenViewResponse'];
+interface CreateShareTokenOptions extends Omit<MintShareTokenRequest, 'expiresAt'> {
+    /** Optional on the wire (`ttlDays` is the other way to set expiry) — see
+     * `../datetime` for the coercion contract; a full ISO string with an
+     * offset still passes through unchanged. */
+    readonly expiresAt?: DateTimeInput;
+    /** Stable across retries — reused as-is, never re-minted per attempt. */
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReadShareTokenOptions {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+interface RevokeShareTokenOptions {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+interface ShareTokensResource {
+    /**
+     * `POST /api/v1/share-tokens` — mints a config-scoped, expiring share
+     * token. Expiry is top-level (`ttlDays` OR `expiresAt` on this options
+     * object — never inside `config`); the server clamps it as documented on
+     * `MintShareTokenRequest`. The CRM builds its own link around the returned
+     * `token`; this SDK never constructs one.
+     */
+    create(options: CreateShareTokenOptions): Promise<KaafilResponse<MintedShareTokenViewResponse>>;
+    /** `GET /api/v1/share-tokens/{id}` — a share token's metadata, never its plaintext value. */
+    read(options: ReadShareTokenOptions): Promise<KaafilResponse<ShareTokenViewResponse>>;
+    /** `DELETE /api/v1/share-tokens/{id}`. */
+    revoke(options: RevokeShareTokenOptions): Promise<KaafilResponse<ShareTokenViewResponse>>;
+}
+
+/**
+ * `treks` — the boarding-day board, walk-ins, and postpone. `architecture/08-
+ * sdk.md §4`. Deliberately small: board/close/reopen belong to `pickups`, and
+ * this module contributes only trek POLICY on top of them.
+ *
+ * `board` and `walkIns.meta` accept a manager session OR an API key; `postpone`
+ * and `walkIns.create` are `managerAuth`-only — a trek is worked and postponed
+ * on the ground.
+ *
+ * ── THE `active` SENTINEL ────────────────────────────────────────────────────
+ *
+ * `trekRef` in these paths is a dual-mode identity like every other `ref` in
+ * this SDK — Kaafil id or the CRM's external id — PLUS one reserved word,
+ * `ACTIVE_TREK_REF` (`'active'`), which resolves to the manager's CURRENT
+ * trek rather than being looked up as an id at all. `RESERVED_TREK_REF` in the
+ * engine already guards the ingest direction (an external trip id can never
+ * literally be `"active"`); this path position is a second, distinct place
+ * the same reservation applies, and the engine's own docblock says a new path
+ * position "must opt in explicitly" rather than inheriting the ingest guard
+ * for free. Exposed here as a named constant rather than left for a caller to
+ * type the string, so `treks.board({ trekRef: ACTIVE_TREK_REF })` reads as
+ * "whichever trek this manager is on" at the call site instead of a magic
+ * string that happens to mean something special.
+ *
+ * The consequence for a real external trip id: one literally equal to
+ * `"active"` can NEVER be addressed through any of these four routes — it
+ * would always resolve as the sentinel instead. That is a property of the
+ * contract, not a bug in this SDK; a CRM minting external ids should treat
+ * `"active"` as unusable here the same way it would a reserved keyword in any
+ * other system.
+ *
+ * When no trek is currently assigned, `board` still answers `200` with an
+ * `emptyState` block (`{ reason: 'no_trek_assigned', message }`) rather than
+ * `404` — the manager stays where they tapped instead of hitting an error
+ * screen. Every OTHER trek endpoint (`walkIns.*`, `postpone`) answers `404`
+ * for "no such trek" the normal way.
+ *
+ * A trek endpoint reached on an `eventType: 'TRIP'` trip is `422 NOT_A_TREK`
+ * — wrong kind, not missing. Unknown or cross-scope stays `404`, the same
+ * not-found used everywhere else in this SDK (`../http/errors.ts`'s standing
+ * argument for why there is exactly one not-found class applies here too).
+ */
+
+type TrekBoardResponse = components['schemas']['TrekBoardResponse'];
+type WalkInMetaResponse = components['schemas']['WalkInMetaResponse'];
+type WalkInResponse = components['schemas']['WalkInResponse'];
+type PostponeResponse = components['schemas']['PostponeResponse'];
+type CreateTrekWalkInRequest = components['schemas']['CreateTrekWalkInRequest'];
+type PostponeTrekRequest = components['schemas']['PostponeTrekRequest'];
+/**
+ * The reserved `trekRef` value meaning "the manager's current trek" — see
+ * this file's header. Never a real external trip id: the engine refuses to
+ * ingest one equal to this string (`RESERVED_TREK_REF` in
+ * `shared/ingest/external-ref.resolver.ts`), so no trip that reaches this SDK
+ * can ever collide with it.
+ */
+declare const ACTIVE_TREK_REF = "active";
+interface ReadTrekBoardOptions {
+    /** A trek's dual-mode ref, or `ACTIVE_TREK_REF` for the manager's current
+     * one — see this file's header. */
+    readonly trekRef: string;
+    readonly signal?: AbortSignal;
+}
+interface ReadTrekWalkInMetaOptions {
+    readonly trekRef: string;
+    readonly signal?: AbortSignal;
+}
+interface CreateTrekWalkInOptions extends CreateTrekWalkInRequest {
+    readonly trekRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface TrekWalkInsResource {
+    /** `GET /api/v1/treks/{trekRef}/walk-ins/meta` — the open pickup points a
+     * walk-in may be assigned to, plus field hints for the intake form. */
+    meta(options: ReadTrekWalkInMetaOptions): Promise<KaafilResponse<WalkInMetaResponse>>;
+    /**
+     * `POST /api/v1/treks/{trekRef}/walk-ins` — mints a Kaafil-owned traveller
+     * (no `externalId`) plus a `WalkIn` row, and upserts the manifest so
+     * rooming, seating and this trek's own board see them immediately. Name and
+     * phone live on the traveller, never on the walk-in row — one PII home.
+     * Reconciliation against a later CRM upsert happens by normalised phone and
+     * emits no event of its own; a walk-in on a `CLOSED` stop auto-reopens it
+     * through `pickups.reopen` in-process, so the eventual re-close carries the
+     * corrective event, not this call.
+     */
+    create(options: CreateTrekWalkInOptions): Promise<KaafilResponse<WalkInResponse>>;
+}
+interface PostponeTrekOptions extends Omit<PostponeTrekRequest, 'newStartDate' | 'newEndDate'> {
+    readonly trekRef: string;
+    /** Must be in the future AND after the trek's current `startDate` — a
+     * postpone moves the trip forward, never back. `CANCELLED`/`COMPLETED`
+     * trips answer `422 CANNOT_POSTPONE`; a write racing the close-out lock
+     * answers `423 LOCKED`. */
+    readonly newStartDate: DateTimeInput;
+    readonly newEndDate: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface TreksResource {
+    /** `GET /api/v1/treks/{trekRef}/board` — stops with expected-vs-boarded,
+     * the running head-count, and the current phase. See this file's header
+     * for the sentinel and the no-trek `emptyState`. */
+    board(options: ReadTrekBoardOptions): Promise<KaafilResponse<TrekBoardResponse>>;
+    readonly walkIns: TrekWalkInsResource;
+    /**
+     * `POST /api/v1/treks/{trekRef}/postpone`. Shifts every `ItineraryDay` and
+     * `StayWindow` by the same delta in ONE transaction; `sortOrder` and bed/seat
+     * assignments are untouched throughout. Pickup `scheduledTime` is
+     * DELIBERATELY NOT shifted — stop times are re-confirmed by the manager on
+     * the ground, because they usually change with the new departure — so
+     * `ripple` on the response reports itinerary and stay-window counts only,
+     * never a pickup count. `postponedFromDate` on the response always holds the
+     * FIRST original start date, even across a second postpone.
+     */
+    postpone(options: PostponeTrekOptions): Promise<KaafilResponse<PostponeResponse>>;
+}
+
+/**
+ * `trips` — upsert, get, cancel, plus `travellers`, `managers`, `balance`,
+ * and the bulk push. `architecture/08-sdk.md §4`. All operations here are
+ * `apiKeyAuth`-only in the spec (CRM-backend ingest, `03-auth-and-tokens.md
+ * §1`).
+ *
+ * Every path parameter is a named field on its options object — never a
+ * positional string — so a two-parameter route (`travellers.remove` takes a
+ * trip ref AND a traveller ref; `managers.unassign` takes a trip ref AND a
+ * manager ref) can't be called with its arguments swapped.
+ */
+
+type UpsertTripRequest = components['schemas']['UpsertTripRequest'];
+type TripUpsertResponse = components['schemas']['TripUpsertResponse'];
+type TripEchoResponse = components['schemas']['TripEchoResponse'];
+type TripCancelResponse = components['schemas']['TripCancelResponse'];
+type UpsertTravellerProfileRequest = components['schemas']['UpsertTravellerProfileRequest'];
+type TravellerUpsertResponse = components['schemas']['TravellerUpsertResponse'];
+type PushManifestRequest = components['schemas']['PushManifestRequest'];
+type ManifestPushResponse = components['schemas']['ManifestPushResponse'];
+type ManifestRemoveResponse = components['schemas']['ManifestRemoveResponse'];
+type UpsertManagerRequest = components['schemas']['UpsertManagerRequest'];
+type ManagerResponse = components['schemas']['ManagerResponse'];
+type AssignManagerRequest = components['schemas']['AssignManagerRequest'];
+type TripManagerResponse = components['schemas']['TripManagerResponse'];
+/** `PushTripBalancesRequest` is itself an array in the spec — there is no wrapper object. */
+type PushTripBalancesRow = components['schemas']['PushTripBalancesRequest'][number];
+type BalancePushResponse = components['schemas']['BalancePushResponse'];
+/** Likewise `PushBulkTripsRequest`. */
+type PushBulkTripsItem = components['schemas']['PushBulkTripsRequest'][number];
+type BulkTripsPushResponse = components['schemas']['BulkTripsPushResponse'];
+type UpsertTripSegment = NonNullable<UpsertTripRequest['segments']>[number];
+type UpsertTripSegmentInput = Omit<UpsertTripSegment, 'startDate' | 'endDate'> & {
+    readonly startDate: DateTimeInput;
+    readonly endDate: DateTimeInput;
+};
+type PushManifestTraveller = PushManifestRequest['travellers'][number];
+type PushManifestTravellerInput = Omit<PushManifestTraveller, 'sourceUpdatedAt'> & {
+    readonly sourceUpdatedAt: DateTimeInput;
+};
+type PushBulkTripsTraveller = NonNullable<PushBulkTripsItem['travellers']>[number];
+type PushBulkTripsTravellerInput = Omit<PushBulkTripsTraveller, 'sourceUpdatedAt'> & {
+    readonly sourceUpdatedAt: DateTimeInput;
+};
+type PushBulkTripsBalanceRow = NonNullable<PushBulkTripsItem['balance']>[number];
+type PushBulkTripsBalanceRowInput = Omit<PushBulkTripsBalanceRow, 'sourceUpdatedAt'> & {
+    readonly sourceUpdatedAt: DateTimeInput;
+};
+type PushBulkTripsManager = NonNullable<PushBulkTripsItem['managers']>[number];
+type PushBulkTripsManagerInput = Omit<PushBulkTripsManager, 'sourceUpdatedAt'> & {
+    readonly sourceUpdatedAt: DateTimeInput;
+};
+type PushBulkTripsItemInput = Omit<PushBulkTripsItem, 'startDate' | 'endDate' | 'sourceUpdatedAt' | 'travellers' | 'balance' | 'managers'> & {
+    readonly startDate: DateTimeInput;
+    readonly endDate: DateTimeInput;
+    readonly sourceUpdatedAt: DateTimeInput;
+    readonly travellers?: readonly PushBulkTripsTravellerInput[];
+    readonly balance?: readonly PushBulkTripsBalanceRowInput[];
+    readonly managers?: readonly PushBulkTripsManagerInput[];
+};
+interface UpsertTripOptions extends Omit<UpsertTripRequest, 'startDate' | 'endDate' | 'sourceUpdatedAt' | 'segments'> {
+    readonly startDate: DateTimeInput;
+    readonly endDate: DateTimeInput;
+    /** The CRM's own record-updated timestamp, used for last-write-wins
+     * staleness detection (`06-offline-first.md §6`). Deliberately still
+     * required, with no "defaults to now" — defaulting it would make every
+     * write look like the newest write and silently defeat the staleness
+     * check on out-of-order delivery. Accepting a `Date` here (via
+     * `DateTimeInput`) is the correct amount of help: the caller still
+     * supplies the CRM's real timestamp, just without hand-formatting it. */
+    readonly sourceUpdatedAt: DateTimeInput;
+    readonly segments?: readonly UpsertTripSegmentInput[];
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface GetTripOptions {
+    readonly tripRef: string;
+    readonly signal?: AbortSignal;
+}
+interface CancelTripOptions {
+    readonly tripRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface UpsertTravellerProfileOptions extends Omit<UpsertTravellerProfileRequest, 'sourceUpdatedAt'> {
+    /** The traveller's own ref — dual-mode identity (Kaafil id or the CRM's
+     * `externalTravellerId`); resolution is the engine's job. */
+    readonly travellerRef: string;
+    /** See the comment on `UpsertTripOptions.sourceUpdatedAt` — same contract,
+     * required, never defaulted. */
+    readonly sourceUpdatedAt: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface PushManifestOptions extends Omit<PushManifestRequest, 'travellers'> {
+    readonly tripRef: string;
+    readonly travellers: readonly PushManifestTravellerInput[];
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface RemoveFromManifestOptions {
+    readonly tripRef: string;
+    readonly travellerRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface TripTravellersResource {
+    upsert(options: UpsertTravellerProfileOptions): Promise<KaafilResponse<TravellerUpsertResponse>>;
+    pushManifest(options: PushManifestOptions): Promise<KaafilResponse<ManifestPushResponse>>;
+    remove(options: RemoveFromManifestOptions): Promise<KaafilResponse<ManifestRemoveResponse>>;
+}
+interface UpsertManagerOptions extends Omit<UpsertManagerRequest, 'sourceUpdatedAt'> {
+    /** See the comment on `UpsertTripOptions.sourceUpdatedAt` — same contract,
+     * required, never defaulted. */
+    readonly sourceUpdatedAt: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface AssignManagerOptions extends Omit<AssignManagerRequest, 'sourceUpdatedAt'> {
+    readonly tripRef: string;
+    /** See the comment on `UpsertTripOptions.sourceUpdatedAt` — same contract,
+     * required, never defaulted. */
+    readonly sourceUpdatedAt: DateTimeInput;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface UnassignManagerOptions {
+    readonly tripRef: string;
+    readonly managerRef: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface TripManagersResource {
+    /** Not trip-scoped — `POST /api/v1/managers` upserts the manager entity
+     * itself (dual-mode identity), independent of any one trip assignment. */
+    upsert(options: UpsertManagerOptions): Promise<KaafilResponse<ManagerResponse>>;
+    assign(options: AssignManagerOptions): Promise<KaafilResponse<TripManagerResponse>>;
+    unassign(options: UnassignManagerOptions): Promise<KaafilResponse<TripManagerResponse>>;
+}
+type PushTripBalancesRowInput = Omit<PushTripBalancesRow, 'sourceUpdatedAt'> & {
+    readonly sourceUpdatedAt: DateTimeInput;
+};
+interface PushTripBalancesOptions {
+    readonly tripRef: string;
+    readonly balances: readonly PushTripBalancesRowInput[];
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface TripBalanceResource {
+    push(options: PushTripBalancesOptions): Promise<KaafilResponse<BalancePushResponse>>;
+}
+interface PushBulkTripsOptions {
+    readonly trips: readonly PushBulkTripsItemInput[];
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface TripsBulkResource {
+    /** `POST /api/v1/bulk/trips` — a batch of full trip bundles (trip +
+     * manifest + balance + managers) in one call. */
+    push(options: PushBulkTripsOptions): Promise<KaafilResponse<BulkTripsPushResponse>>;
+}
+interface TripsResource {
+    upsert(options: UpsertTripOptions): Promise<KaafilResponse<TripUpsertResponse>>;
+    get(options: GetTripOptions): Promise<KaafilResponse<TripEchoResponse>>;
+    cancel(options: CancelTripOptions): Promise<KaafilResponse<TripCancelResponse>>;
+    readonly travellers: TripTravellersResource;
+    readonly managers: TripManagersResource;
+    readonly balance: TripBalanceResource;
+    readonly bulk: TripsBulkResource;
+}
+
+/**
+ * `webhooks` — the delivery operations only: list deliveries, read a
+ * delivery, redeliver, replay. `architecture/08-sdk.md §4`, amended `C-028`:
+ * "the delivery-facing operations … and `replayEndpoint` are API-key" —
+ * `configure`/`rotateSecret` (console-session, endpoint CRUD) are a
+ * different auth model entirely and are out of this lane's scope by the
+ * brief's own instruction.
+ *
+ * `listWebhookDeliveries` is cursor-paginated (`cursor`+`limit` query params,
+ * `meta.page.hasNext`); `deliveries.list()` returns a `KaafilPaginator` and
+ * `deliveries.listPage()` is the manual single-page escape hatch for a
+ * caller who wants to drive paging itself (`../pagination/paginator.ts`).
+ */
+
+type DeliveryResponse = components['schemas']['DeliveryResponse'];
+type DeliveryDetailResponse = components['schemas']['DeliveryDetailResponse'];
+type RedeliverResponse = components['schemas']['RedeliverResponse'];
+type ReplayResponse = components['schemas']['ReplayResponse'];
+type ReplayWebhookEndpointRequest = components['schemas']['ReplayWebhookEndpointRequest'];
+type ListWebhookDeliveriesQuery = NonNullable<operations['listWebhookDeliveries']['parameters']['query']>;
+/** The filterable half of `listWebhookDeliveries`'s query params — `cursor`
+ * and `limit` are the paginator's job, never the caller's to hold. */
+type WebhookDeliveryFilters = Omit<ListWebhookDeliveriesQuery, 'cursor' | 'limit'>;
+interface ListWebhookDeliveriesOptions {
+    readonly filters?: WebhookDeliveryFilters;
+    /** Page size sent as the `limit` query param on every page this paginator fetches. */
+    readonly limit?: number;
+}
+interface ListWebhookDeliveriesPageOptions extends WebhookDeliveryFilters {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+interface ReadWebhookDeliveryOptions {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+interface RedeliverWebhookDeliveryOptions {
+    readonly id: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface ReplayWebhookEndpointOptions extends ReplayWebhookEndpointRequest {
+    /** The endpoint to replay against — `replayWebhookEndpoint`'s path
+     * parameter is the webhook endpoint id, not a delivery id. */
+    readonly endpointId: string;
+    readonly idempotencyKey?: string;
+    readonly signal?: AbortSignal;
+}
+interface WebhookDeliveriesResource {
+    /** `GET /api/v1/webhooks/deliveries` as a `KaafilPaginator` — the SDK holds
+     * the cursor; the consumer never sees or stores one. */
+    list(options?: ListWebhookDeliveriesOptions): KaafilPaginator<DeliveryResponse, WebhookDeliveryFilters>;
+    /** The manual single-page escape hatch: fetches exactly one page and
+     * returns it directly, for a caller who wants to drive paging itself
+     * rather than use the paginator `list()` returns. */
+    listPage(options?: ListWebhookDeliveriesPageOptions): Promise<KaafilPagedResponse<readonly DeliveryResponse[]>>;
+    read(options: ReadWebhookDeliveryOptions): Promise<KaafilResponse<DeliveryDetailResponse>>;
+    redeliver(options: RedeliverWebhookDeliveryOptions): Promise<KaafilResponse<RedeliverResponse>>;
+}
+interface WebhooksResource {
+    readonly deliveries: WebhookDeliveriesResource;
+    /** `POST /api/v1/webhooks/endpoints/{id}/replay` — re-delivers every event
+     * since `from` to one endpoint. */
+    replay(options: ReplayWebhookEndpointOptions): Promise<KaafilResponse<ReplayResponse>>;
+}
+
+/**
+ * `Kaafil` — the server client, exported from `src/index.ts`
+ * (`kaafil-js`). Constructed with the partner API key; carries every
+ * resource group an API key can reach. `architecture/08-sdk.md §2, §3.1`.
+ *
+ * This module is the ONLY place an API-key credential is ever assembled and
+ * checked — `guardApiKeyEnvironment`/`assertApiKeyMatchesEnvironment`
+ * (`./config.ts`) and the `{ kind: 'apiKey', apiKey }` config object below.
+ * `./client-entry.ts` (the browser entry) does not import this file, does
+ * not import those two guards, and builds no credential of this shape —
+ * see that file's header comment for the structural argument, not just a
+ * convention, for why a bundler following only the browser entry's import
+ * graph has no path to this one.
+ */
+
+interface KaafilOptions {
+    /** `kf_live_…` / `kf_test_…`, checked against `environment` at
+     * construction for a literal key, or on every resolution for a resolver
+     * (`./config.ts`'s `guardApiKeyEnvironment`). */
+    readonly apiKey: Resolvable<string>;
+    readonly environment: Environment;
+    /** Overrides the environment's default base URL outright — see
+     * `./config.ts`'s `resolveBaseUrl` for why the two are never merged. */
+    readonly baseUrl?: string;
+    readonly timeoutMs?: number;
+    readonly maxAttempts?: number;
+    readonly userAgent?: string;
+    readonly random?: () => number;
+}
+/**
+ * Thrown by any resource method called after `close()`. Every resource
+ * getter reads through `#requireState()`, so a stale reference to
+ * `kaafil.trips` obtained before `close()` still throws this on its next
+ * call — there is no way to keep using a closed client's credential.
+ */
+declare class KaafilClosedError extends Error {
+    constructor();
+}
+declare class Kaafil {
+    #private;
+    constructor(options: KaafilOptions);
+    get auth(): AuthResource;
+    get shareTokens(): ShareTokensResource;
+    get trips(): TripsResource;
+    get itinerary(): ItineraryResource;
+    get rooming(): RoomingResource;
+    get seating(): SeatingResource;
+    get pickups(): PickupsResource;
+    get treks(): TreksResource;
+    get checklists(): ChecklistsResource;
+    get vendors(): VendorsResource;
+    get journey(): JourneyResource;
+    get webhooks(): WebhooksResource;
+    get events(): EventsResource;
+    get files(): FilesResource;
+    get collections(): CollectionsResource;
+    get expenses(): ExpensesResource;
+    get float(): FloatResource;
+    /**
+     * Total teardown. One assignment, no field to forget — see `KaafilState`
+     * above. Every subsequent call through any resource getter throws
+     * `KaafilClosedError` instead of quietly continuing to work off a
+     * credential this client no longer considers live.
+     */
+    close(): void;
+    /**
+     * Mints an idempotency key outside the normal per-call flow. Every
+     * mutating method already mints and reuses one automatically
+     * (`http/client.ts`) — this exists for the rare case of pinning a key
+     * ahead of time, to replay the exact same logical operation across a
+     * process restart.
+     */
+    static newIdempotencyKey(): string;
+}
+
+/**
+ * The `?since=` delta cursor. `architecture/06-offline-first.md §1, §5`.
+ *
+ * ── WHY THE CURSOR IS THE SERVER'S OWN CLOCK, AND NOTHING ELSE ──────────────
+ *
+ * Every delta read on this API answers with `meta.serverTime`. That value —
+ * the timestamp of the response you are holding, taken by the machine that ran
+ * the query — is the ONLY correct cursor to send back as the next `?since=`.
+ * The two tempting alternatives both lose rows, silently, and only under load:
+ *
+ * - **A local clock** (`new Date()` when the response arrived) is skewed
+ *   against the server's by an unknown amount and drifts. Skew in the wrong
+ *   direction advances the cursor past rows the server had not committed yet
+ *   when it answered, and those rows are then never in any window again.
+ * - **A row's own `updatedAt`** (the newest row in the page) is worse: it is a
+ *   bound on the rows you RECEIVED, not on the interval the server READ. Any
+ *   row committed between the query's snapshot and the response being stamped
+ *   sits after your cursor and before the server's, and is lost permanently.
+ *   An empty page also leaves you with no cursor at all.
+ *
+ * This module exists so that reasoning happens once, here, instead of at every
+ * integrator's call site. `pull()` takes the cursor from the response's own
+ * `meta.serverTime` and nothing else, and it advances it only after a
+ * successful read — a failed pull leaves the cursor exactly where it was, so
+ * the next attempt re-reads the same interval rather than skipping it.
+ *
+ * ── WHY DUPLICATES ARE EXPECTED, AND WHY THEY ARE FREE ──────────────────────
+ *
+ * The server window is deliberately AT-LEAST-ONCE: it matches
+ * `updatedAt >= since - 5s`, and a cursor in the future clamps to now rather
+ * than erroring. So a pull normally re-delivers rows you already have. That is
+ * the design, not a defect, and the asymmetry is the reason:
+ *
+ * - A DUPLICATED row costs nothing. Every row — live or tombstone — carries
+ *   `id` and `version`, so re-applying one is a no-op rebase onto the state
+ *   you already hold. `mergeDeltaRows` below does exactly that, by version.
+ * - A SKIPPED row is DATA LOSS. It is a hotel booking, a cancelled activity or
+ *   a deleted bed that the offline client never learns about and never asks
+ *   for again, because the cursor has already moved past it. Nothing detects
+ *   it; the client is simply, quietly wrong.
+ *
+ * A strict `> since` boundary would be exactly that trade in reverse — no
+ * duplicates, and permanent loss from three separate mechanisms (the interval
+ * between reading rows and stamping the response, clock skew between replicas,
+ * and millisecond truncation). The engine chose the overlap; a consumer must
+ * not undo it by narrowing the window on the client side.
+ *
+ * ── WHY A DELTA ROW IS A UNION ──────────────────────────────────────────────
+ *
+ * A delta read returns `Row | DeltaTombstone` in ONE array, never a second
+ * `deleted[]` array, so a consumer cannot forget the drop case: the union does
+ * not typecheck until the tombstone branch is handled. Ordering is
+ * `(updatedAt asc, id asc)`, so each id appears at most once per page and at
+ * its final state — "deleted before or after updated" is already answered
+ * server-side.
+ */
+
+/**
+ * The drop marker on a delta read.
+ *
+ * Aliased off the generated schema rather than hand-restated. The spec uses
+ * one tombstone shape for every delta read (itinerary items, rooming rooms,
+ * rooming stay windows) and `ItineraryItemTombstoneResponse` is the single
+ * place it appears as a NAMED component — the others inline it inside their
+ * own `anyOf`, so there is no more general name to alias. If the engine ever
+ * gives the shape its own component, this alias moves; the four fields are
+ * still never typed by hand here.
+ */
+type DeltaTombstone = components['schemas']['ItineraryItemTombstoneResponse'];
+/** One row from a delta read: the live row, or the marker saying it is gone. */
+type DeltaRow<TRow> = TRow | DeltaTombstone;
+/**
+ * Narrows a delta row to the drop case.
+ *
+ * Structural, and provably safe rather than conventional: every response
+ * schema in this contract is `additionalProperties: false`, so a live row can
+ * never carry a `_tombstone` key and the two branches of the union are
+ * disjoint.
+ */
+declare function isTombstone<TRow extends object>(row: DeltaRow<TRow>): row is DeltaTombstone;
+/**
+ * What `mergeDeltaRows` requires of a live row, and what makes a duplicate
+ * free: an identity and a version. Both delta variants carry them.
+ */
+interface DeltaIdentity {
+    readonly id: string;
+    readonly version: number;
+}
+/** What one `mergeDeltaRows` call actually changed. */
+interface DeltaMergeStats {
+    /** Rows written that the store had not seen before. */
+    readonly added: number;
+    /** Rows written over an older version of a row already held. */
+    readonly updated: number;
+    /** Rows dropped because a tombstone arrived for them. */
+    readonly removed: number;
+    /**
+     * Rows the store already held at this version or newer. This is the
+     * at-least-once overlap doing its job — a non-zero count is normal on every
+     * pull after the first and is not worth reporting to a user.
+     */
+    readonly unchanged: number;
+}
+/**
+ * Rebases one delta page onto a local store, keyed by `id`.
+ *
+ * Version-guarded in both directions, which is what makes re-applying a
+ * duplicated row a genuine no-op instead of merely a harmless-looking one: a
+ * row whose `version` is not NEWER than the held one is left alone, and a
+ * tombstone whose `version` is older than the held row is ignored rather than
+ * deleting a row that has since been recreated or updated. The store is
+ * mutated in place — a caller's `Map` is its own cache, and returning a fresh
+ * copy per page would make a long offline catch-up quadratic.
+ */
+declare function mergeDeltaRows<TRow extends DeltaIdentity>(store: Map<string, TRow>, rows: readonly DeltaRow<TRow>[]): DeltaMergeStats;
+/**
+ * Runs one delta read for a given cursor. A caller supplies this as a thin
+ * closure over a resource method — this module knows nothing about operation
+ * ids, paths or query-param names, only that a read takes a `since` and
+ * answers with an envelope carrying `meta.serverTime`.
+ *
+ * `since` is `undefined` on a cold start, which is a full read: the server
+ * emits no tombstones without a cursor, because a client that has never
+ * synced has nothing to drop.
+ */
+type FetchDelta<T> = (request: {
+    readonly since: string | undefined;
+    readonly signal: AbortSignal | undefined;
+}) => Promise<KaafilResponse<T>>;
+/** One completed pull, with the cursor bookkeeping made visible. */
+interface DeltaPull<T> {
+    readonly data: T;
+    readonly meta: ResponseMeta;
+    /** The cursor now stored: THIS response's `meta.serverTime`. */
+    readonly cursor: string;
+    /** What was sent as `?since=` — `undefined` on the cold start. */
+    readonly previousCursor: string | undefined;
+}
+/** `pull()` was re-entered while a previous pull on the same cursor was in flight. */
+declare class KaafilDeltaCursorInFlightError extends Error {
+    constructor();
+}
+interface KaafilDeltaCursor<T> {
+    /**
+     * The cursor that will be sent as `?since=` on the next `pull()`, or
+     * `undefined` before the first successful one. Read this to PERSIST it; a
+     * durable consumer stores it beside its rows and hands it back to
+     * `restore()` after a restart, so a process death costs one overlapping
+     * window rather than a full resync.
+     */
+    readonly cursor: string | undefined;
+    readonly isLoading: boolean;
+    /** Whether any pull has succeeded yet — i.e. whether the next one is a cold start. */
+    readonly hasSynced: boolean;
+    /**
+     * Reads everything that changed since the stored cursor, then advances the
+     * cursor to this response's own `meta.serverTime`. On failure the cursor is
+     * left untouched, so a retry re-reads the same interval instead of stepping
+     * over it.
+     */
+    pull(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<DeltaPull<T>>;
+    /**
+     * Adopts a cursor persisted from an earlier session. Takes a `string`
+     * only — deliberately not a `Date` or an epoch number, the two things that
+     * would let a local clock become a cursor, which is the failure this whole
+     * module exists to prevent. Must be a value some response's
+     * `meta.serverTime` actually carried.
+     */
+    restore(cursor: string): void;
+    /**
+     * Discards the cursor, so the next `pull()` is a cold start: a full read,
+     * with no tombstones. The honest recovery when a local store is corrupt or
+     * of unknown provenance — cheaper to re-read the trip than to reconcile a
+     * cache you cannot vouch for.
+     */
+    reset(): void;
+}
+interface CreateDeltaCursorConfig<T> {
+    readonly fetchDelta: FetchDelta<T>;
+    /** A cursor persisted from an earlier session, as `restore()` would take it. */
+    readonly cursor?: string;
+}
+declare function createDeltaCursor<T>(config: CreateDeltaCursorConfig<T>): KaafilDeltaCursor<T>;
+
+/**
+ * The rooming vocabulary a client needs to RENDER what
+ * `rooming.autoAssign` and `rooming.read` answer — and which is deliberately
+ * not on the wire.
+ *
+ * Two things live here, for the same reason: each is a property of the RULE or
+ * of the CANON, not of a particular run, so shipping either inside every
+ * response would put a second copy of one judgement in every payload and let
+ * the two disagree after a contract change. The engine states this in
+ * `src/modules/rooming/index.ts`, which re-exports both explicitly "for the
+ * SDK". This file is that re-export's other end, so a client renders
+ * relaxations and traveller chips without inventing its own severity map or
+ * its own colour maths.
+ *
+ * ── HOW THIS STAYS HONEST ────────────────────────────────────────────────────
+ *
+ * These values are not in `openapi.json`, so `gen:check` cannot police them.
+ * What does: both maps are typed as TOTAL `Record`s over GENERATED key types
+ * (`RoomingHeuristicKey` and `Gender`, from `../generated/enums.ts`, which
+ * `scripts/gen-meta.mjs` builds out of the vendored spec's own request enums).
+ * Add a heuristic or a gender to the contract and re-vendor, and this file
+ * stops compiling until someone decides what the new member's severity or hue
+ * family is. A `Record<string, …>` here would have accepted the drift
+ * silently, which is exactly the failure a hand-maintained mirror invites.
+ */
+
+/**
+ * How loudly to render a rule's relaxation.
+ *
+ * - `warn` — the manager should look: a preference they set was given up.
+ * - `split` — a group was broken up. Louder than `warn`; it is the complaint
+ *   the trip will actually generate.
+ * - `info` — a soft preference, worth showing but not worth interrupting for.
+ * - `never` — this rule is never relaxed at all. It exists so the map is TOTAL:
+ *   a missing entry would be indistinguishable from a rule nobody had
+ *   classified yet.
+ */
+type RoomingHeuristicSeverity = 'warn' | 'split' | 'info' | 'never';
+/**
+ * The frozen severity map, mirroring the engine's `HEURISTIC_SEVERITY`.
+ *
+ * `gender` is `'never'` because a gender rule is never relaxed — the traveller
+ * stays unassigned instead, and turns up in `autoAssign`'s `unassigned[]` with
+ * a reason. So a `perRule` entry for `gender` with `outcome: 'relaxed'` is not
+ * something to render loudly; it is a contract violation, and a client is
+ * entitled to treat it as a bug rather than as a user-facing warning.
+ */
+declare const HEURISTIC_SEVERITY: Readonly<Record<RoomingHeuristicKey, RoomingHeuristicSeverity>>;
+/**
+ * Whether a string is one of the heuristic keys this SDK knows about.
+ *
+ * Exists because `autoAssign`'s `perRule[].rule` is an open `string` on the
+ * wire, not the closed enum `strategyOrder` is on the request side — so a
+ * response may name a rule a given SDK build has never heard of, and a client
+ * must be able to ask.
+ */
+declare function isRoomingHeuristicKey(rule: string): rule is RoomingHeuristicKey;
+/**
+ * How loudly to render one `perRule` entry's relaxation.
+ *
+ * ── WHY THIS FUNCTION EXISTS AND THE MAP IS NOT ENOUGH ──────────────────────
+ *
+ * `HEURISTIC_SEVERITY[entry.rule]` does not compile, and that is correct
+ * rather than an oversight to paper over: `entry.rule` is `string` in the
+ * contract, and a total `Record` over a closed key set legitimately refuses a
+ * `string` index. The two possible fixes are not equivalent. Loosening the map
+ * to `Record<string, …>` would also throw away the compile-time drift gate
+ * described in this file's header, which is the only thing keeping this
+ * hand-maintained mirror honest against a re-vendored spec. So the map stays
+ * total and this accessor takes the wire's `string`.
+ *
+ * Returns `undefined` for a rule this build does not know. A caller should
+ * render that entry rather than drop it — an unrecognised rule that was
+ * RELAXED is still a relaxation the manager needs to see, and hiding it
+ * because the severity lookup missed is the silent-relaxation failure the
+ * `perRule` array exists to prevent. `'info'` is a reasonable default to draw
+ * it at; `undefined` is deliberately not pre-defaulted here, so that choice is
+ * visible at the call site instead of buried in this function.
+ */
+declare function roomingHeuristicSeverity(rule: string): RoomingHeuristicSeverity | undefined;
+/**
+ * The hue FAMILIES a `tone` token is built from, keyed by the occupant's
+ * `gender`.
+ *
+ * `null` gender and `UNKNOWN` map to the SAME family: the field is nullable
+ * AND the enum has an `UNKNOWN` member, so unknown-ness arrives two ways and
+ * means one thing. Rendering them in two palettes would show the same fact
+ * twice over as two different facts.
+ */
+declare const TONE_FAMILIES: Readonly<Record<Gender, string>>;
+/** The family for a `null` gender. Identical to `UNKNOWN`'s, by the reasoning above. */
+declare const UNKNOWN_TONE_FAMILY: string;
+/**
+ * How many shades each family has, so a client's palette knows how many to
+ * define: `shade` in a `tone` token is always `0 .. SHADES_PER_FAMILY - 1`.
+ *
+ * It equals the maximum room capacity, and that is the whole argument. The
+ * promise is that two same-gender travellers IN ONE ROOM still look different —
+ * a room being the only place two chips sit side by side and have to be told
+ * apart. A room holds at most 8 people, so with 8 shades per family a
+ * collision is never FORCED inside that scope. It is frozen rather than
+ * configurable because the mark is a property of the TRAVELLER, not of the
+ * viewer: two agencies with different values would render the same person in
+ * two different shades, and `transport-seating` — which draws the same chip
+ * from the same canon — would have to know whose grid it was on to agree with
+ * the rooming board.
+ */
+declare const SHADES_PER_FAMILY = 8;
+/**
+ * The glyph the engine sends for a traveller whose `fullName` has no
+ * renderable characters at all. Reachable, because the name is CRM-supplied,
+ * and an unnameable traveller must still get a chip rather than vanish off the
+ * board.
+ */
+declare const FALLBACK_GLYPH = "?";
+/** A parsed `tone` token. */
+interface RoomingTone {
+    /** One of `TONE_FAMILIES`' values. */
+    readonly family: string;
+    /** `0 .. SHADES_PER_FAMILY - 1`. */
+    readonly shade: number;
+}
+/**
+ * Splits an occupant's `tone` into its family and shade.
+ *
+ * ── `tone` IS A TOKEN, NEVER A COLOUR ───────────────────────────────────────
+ *
+ * The engine sends `"male.3"`, not `"#3B82F6"`, and that is deliberate: the
+ * engine must not own brand colour values. If it did, an agency re-theme would
+ * be an engine deploy, and the same traveller would render in two different
+ * palettes depending on which module's copy of the hex table was newer. What
+ * the engine owns is the CONSISTENCY claim — `rooming` and `transport-seating`
+ * handing you the same string for the same person IS the consistency —
+ * and what you paint it is entirely yours. So the shape a consumer wants is
+ * `palette[family][shade]`, with `palette` living in your own design system,
+ * and this function is how you get the two indices out without string-slicing
+ * by hand.
+ *
+ * Returns `undefined` rather than throwing for anything that is not a
+ * recognisable token, because this runs while drawing a board: a chip with an
+ * unreadable tone should fall back to a neutral swatch, not take the screen
+ * down. The family is NOT checked against `TONE_FAMILIES` — a family added to
+ * the contract before your palette knows about it should still parse, so you
+ * can fall back on the family you do not recognise instead of on every chip.
+ */
+declare function parseRoomingTone(tone: string): RoomingTone | undefined;
+
+export { ACTIVE_TREK_REF, type AddChecklistItemOptions, type AddItineraryItemOptions, type AdjustFloatOptions, type AssignManagerOptions, type AssignPickupTravellerOptions, type AssignRoomingBedOptions, type AssignSeatingOptions, type AuthResource, type AutoAssignRoomingOptions, type AutoAssignSeatingOptions, type BoardPickupTravellerOptions, type CancelTripOptions, type ChecklistItemDeltaRow, type ChecklistItemsResource, type ChecklistTemplatesResource, type ChecklistsResource, type ClosePickupStopOptions, type CollectionDeltaRow, type CollectionsResource, type ConfirmFileUploadOptions, type CreateDeltaCursorConfig, type CreatePickupStopOptions, type CreateRoomingRoomOptions, type CreateRoomingStayWindowOptions, type CreateSeatingVehicleOptions, type CreateShareTokenOptions, type CreateTrekWalkInOptions, type DateTimeInput, type DeleteChecklistItemOptions, type DeleteItineraryItemOptions, type DeletePickupStopOptions, type DeleteRoomingRoomOptions, type DeleteRoomingStayWindowOptions, type DeleteSeatingVehicleOptions, type DeltaIdentity, type DeltaMergeStats, type DeltaPull, type DeltaRow, type DeltaTombstone, Environment, type EventFilters, type EventsResource, type ExpenseClaimsResource, type ExpenseFilters, type ExpensesResource, FALLBACK_GLYPH, type FetchDelta, type FilesResource, type FloatResource, Gender, type GetTripOptions, HEURISTIC_SEVERITY, type IngestClaimStatusOptions, type IssueFloatOptions, type ItineraryChangeLogResource, type ItineraryDaysResource, type ItineraryItemDeltaRow, type ItineraryItemsResource, type ItineraryResource, JourneyResource, Kaafil, KaafilClosedError, type KaafilDeltaCursor, KaafilDeltaCursorInFlightError, type KaafilOptions, KaafilPagedResponse, KaafilPaginator, KaafilResponse, type LinkExpenseReceiptOptions, type LinkSeatingManagerOptions, type ListChecklistTemplatesOptions, type ListCollectionsOptions, type ListEligibleCollectionsOptions, type ListEventsOptions, type ListEventsPageOptions, type ListExpensesOptions, type ListItineraryChangeLogOptions, type ListPickupStopsOptions, type ListRoomingStayWindowsOptions, type ListWebhookDeliveriesOptions, type ListWebhookDeliveriesPageOptions, type LogExpenseOptions, type MintAgencyAdminTokenOptions, type MintManagerTokenOptions, type PatchChecklistItemOptions, type PatchItineraryDayOptions, type PatchItineraryItemOptions, type PatchPickupStopOptions, type PatchRoomingRoomOptions, type PatchRoomingStayWindowOptions, type PatchSeatingVehicleOptions, type PickupStopDeltaRow, type PickupsResource, type PostponeTrekOptions, type PullChecklistTemplateOptions, type PushBulkTripsOptions, type PushManifestOptions, type PushTripBalancesOptions, type ReadChecklistOptions, type ReadExpenseOptions, type ReadFileOptions, type ReadFileUrlOptions, type ReadFloatLedgerOptions, type ReadFloatSummaryOptions, type ReadItineraryOptions, type ReadManifestByPickupOptions, type ReadRoomingBoardOptions, type ReadSeatingBoardOptions, type ReadShareTokenOptions, type ReadTrekBoardOptions, type ReadTrekWalkInMetaOptions, type ReadWebhookDeliveryOptions, type RecordCollectionOptions, type RedeliverWebhookDeliveryOptions, type RemoveFromManifestOptions, type ReopenPickupStopOptions, type ReorderItineraryItemOptions, type ReorderPickupStopsOptions, type ReplayWebhookEndpointOptions, type RequestFileUploadOptions, Resolvable, ResponseMeta, type ReturnFloatOptions, type RevokeShareTokenOptions, type RoomingAutoAssignRules, RoomingHeuristicKey, type RoomingHeuristicSeverity, type RoomingOccupant, type RoomingResource, type RoomingRoomDeltaRow, type RoomingRoomsResource, type RoomingStayWindowsResource, type RoomingTone, SHADES_PER_FAMILY, type SeatingAutoAssignRules, type SeatingOccupant, type SeatingResource, type SeatingVehicleDeltaRow, type SeatingVehicleManagerResource, type SeatingVehiclesResource, type ShareTokensResource, type SubmitExpenseClaimOptions, TONE_FAMILIES, type ToggleChecklistItemOptions, type TrekWalkInsResource, type TreksResource, type TripBalanceResource, type TripManagersResource, type TripTravellersResource, type TripsBulkResource, type TripsResource, UNKNOWN_TONE_FAMILY, type UnassignManagerOptions, type UnlinkSeatingManagerOptions, type UpsertManagerOptions, type UpsertTravellerProfileOptions, type UpsertTripOptions, VendorsResource, type VoidCollectionOptions, type VoidExpenseOptions, type WebhookDeliveriesResource, type WebhookDeliveryFilters, type WebhooksResource, type WithdrawExpenseClaimOptions, createDeltaCursor, isRoomingHeuristicKey, isTombstone, mergeDeltaRows, parseRoomingTone, roomingHeuristicSeverity };