kaafil-react-uikit 0.1.0-beta.1

package/dist/useVendors-DXOuZWhZ.d.cts

@@ -0,0 +1,784 @@
+import { ChecklistItemDeltaRow, ChecklistsResource, AddChecklistItemOptions, OutboxOp, PatchChecklistItemOptions, DeleteChecklistItemOptions, ToggleChecklistItemOptions, ListChecklistTemplatesOptions, ChecklistTemplatesResource, PullChecklistTemplateOptions, KaafilClient, FilesResource, ExpensesResource, LogExpenseOptions, LinkExpenseReceiptOptions, VoidExpenseOptions, SubmitExpenseClaimOptions, WithdrawExpenseClaimOptions, FloatResource, IssueFloatOptions, ReturnFloatOptions, AdjustFloatOptions, FormsResource, ManagerCreateFormResponseOptions, DispatchFormOptions, ExportFormResponsesOptions, KaafilBinaryResponse, ReadFormConsentReceiptOptions, BoundCreateFormOptions, PatchFormOptions, CloneFormOptions, ReorderFormOptions, CreateFormSectionOptions, PatchFormSectionOptions, DeleteFormSectionOptions, CreateFormFieldOptions, PatchFormFieldOptions, DeleteFormFieldOptions, ItineraryResource, ListItineraryChangeLogOptions, PatchItineraryDayOptions, AddItineraryItemOptions, PatchItineraryItemOptions, DeleteItineraryItemOptions, ReorderItineraryItemOptions, RoomingResource, RoomingRoomDeltaRow, RoomingOccupant, AssignRoomingBedOptions, AutoAssignRoomingOptions, CreateRoomingStayWindowOptions, PatchRoomingStayWindowOptions, DeleteRoomingStayWindowOptions, CreateRoomingRoomOptions, PatchRoomingRoomOptions, DeleteRoomingRoomOptions, VendorsResource, CreateVendorOptions, UpsertVendorOptions, DeleteVendorOptions } from 'kaafil-js/client';
+
+/** The four handling paths a `/core` hook ever takes for a classified error. */
+type ErrorHandlingPath = 'retryable' | 'parked' | 'surface-to-user' | 're-auth';
+/**
+ * Exactly the 24 codes `architecture/10-conventions.md §7` lists, each
+ * mapped to exactly one `ErrorHandlingPath`:
+ *
+ * - `re-auth` (1 code): `UNAUTHENTICATED` — the SDK's own credential
+ *   resolver already attempted one silent refresh before this ever reaches
+ *   `/core` (`10 §7`'s "*SDK attempts one token refresh first"); a hook
+ *   seeing this classification is seeing a refresh that already failed, so
+ *   the one correct action left is surfacing `session.expired`.
+ * - `retryable` (3 codes): the three the offline table (`06 §7`) marks
+ *   TRANSIENT — `RATE_LIMITED`, `INTERNAL_ERROR`, `TENANT_SCOPE_MISSING`.
+ * - `parked` (3 codes): the closed three-code subset `07-offline-and-sync.md
+ *   §10` names explicitly as "never retried" — `PLAN_FEATURE_DISABLED`,
+ *   `FILE_PURGED`, `LOCKED`. (`UnsatisfiableSchemeError` — not a wire code,
+ *   thrown locally by `kaafil-js`'s credential resolver before any request —
+ *   is the fourth member of that same closed set; `./classify.ts` handles it
+ *   by `instanceof`, not through this table, because it never carries a
+ *   `KaafilErrorCode`.)
+ * - `surface-to-user` (the remaining 17 codes): every code that is neither
+ *   retryable, parked, nor a re-auth signal — a human needs to see it and,
+ *   in most cases, act on it (fix a validation error, resolve a conflict via
+ *   `useConflicts()`, request a fresh share link). `CONFLICT_VERSION` and
+ *   `SECRET_NOT_REPLAYABLE` land here too: both ARE surfaced to a human, just
+ *   through the one shared `ConflictResolver` shape (`07-offline-and-sync.md
+ *   §6`) rather than a generic toast — that richer shape is `useConflicts()`'s
+ *   job, not this classifier's.
+ */
+declare const ERROR_HANDLING_PATH: Readonly<Record<string, ErrorHandlingPath>>;
+
+/** The normalised shape every `/core` hook's `'error'` branch carries. */
+interface ErrorClassification {
+    readonly path: ErrorHandlingPath;
+    /** The catalog code, when the failure reached a real response
+     * (`kind: 'api'`). `undefined` for a transport failure (network, timeout,
+     * abort) or for `UnsatisfiableSchemeError`, neither of which ever carries
+     * one (`kaafil-js/src/http/errors.ts`, verified: `KaafilTransportError`
+     * fixes `code: undefined`). */
+    readonly code: string | undefined;
+    readonly status: number | undefined;
+    /** `true` when the SDK's own credential resolver refused the call locally,
+     * before any request was built — `UnsatisfiableSchemeError`
+     * (`kaafil-js/src/auth/credentials.ts`, verified). A hook surfacing this
+     * to a composite renders it as a structural "this persona cannot do that",
+     * never a transient failure worth retrying. */
+    readonly unsatisfiableScheme: boolean;
+    /** The original error, for a caller that needs more than the
+     * classification (support escalation, a `details` field a specific hook
+     * knows how to read). */
+    readonly cause: unknown;
+}
+/**
+ * Turns any caught value into the shape every `/core` hook's error branch
+ * needs. Never throws — an unrecognised shape (a bare `Error`, a rejected
+ * promise from something outside the SDK) still classifies, conservatively,
+ * as `surface-to-user` with no code and no status, rather than propagating
+ * an uncaught exception up through a hook that promised a `{ status:
+ * 'error' }` branch instead.
+ */
+declare function classifyError(error: unknown): ErrorClassification;
+
+/**
+ * Which of the three gates failed, in the priority order the three
+ * darkness treatments are picked in (`06-capability-and-personas.md §2`).
+ * `'mode'` wins over `'data'` wins over `'flag'` is NOT the rule here — the
+ * wire's own gate order is flag-before-data (`06 §1`, "why 402 wins"), but
+ * `DarkReason` names which single boolean a *component* should read to pick
+ * its treatment, and mode-dark is checked first because it is the one
+ * treatment that renders nothing at all (`06 §2`'s table, row 1).
+ */
+type DarkReason = 'mode' | 'data' | 'flag';
+/**
+ * The wire shape of one row of `journey.capabilities()`
+ * (`06-capability-and-personas.md §6`, verified against
+ * `kaafil-js/src/resources/journey.ts`'s `JourneyCapabilitiesResponse`).
+ * `capability` is an open string set (§6 point 5) — never exhaustively
+ * switched on.
+ */
+interface CapabilityRow {
+    readonly capability: string;
+    readonly modeOk: boolean;
+    readonly dataOk: boolean;
+    readonly flagOk: boolean;
+    readonly enabled: boolean;
+}
+/**
+ * `useCapability()`'s per-key return shape (`08-core-hooks.md §1.4`).
+ * `status` is derived client-side from the triple, once, here — never
+ * re-derived by a composite (§6 point 2).
+ */
+interface CapabilityTriple {
+    readonly enabled: boolean;
+    readonly modeOk: boolean;
+    readonly dataOk: boolean;
+    readonly flagOk: boolean;
+    readonly status: 'lit' | 'mode-dark' | 'data-dark' | 'flag-dark';
+}
+
+/**
+ * `TReady` is merged into the `'ready'` branch (never nested under a `data`
+ * key) so a composite destructures `{ status, rows, mutate }` directly once
+ * it has narrowed on `status === 'ready'`, with no extra unwrap.
+ */
+type DomainHookResult<TReady extends object> = {
+    readonly status: 'loading';
+} | {
+    readonly status: 'dark';
+    readonly reason: DarkReason;
+} | ({
+    readonly status: 'ready';
+} & TReady) | {
+    readonly status: 'error';
+    readonly error: ErrorClassification;
+};
+
+/** `Awaited<ReturnType<...>>` off the resource methods, never imported by
+ * name — `ChecklistAggregateResponse`/`ChecklistItemResponse`/
+ * `ToggleResponse`/`TemplatesListResponse`/`DeleteItemResponse` are not
+ * individually re-exported from `kaafil-js/client`'s public surface
+ * (verified — only `ChecklistItemDeltaRow` and the `*Options` input types
+ * are), the identical gap `usePickups.ts`'s own header documents for its
+ * resource's response shapes. */
+type ChecklistReadResult = Awaited<ReturnType<ChecklistsResource['read']>>;
+type ChecklistTemplatesListResult = Awaited<ReturnType<ChecklistTemplatesResource['list']>>;
+/** One row of `ChecklistReadResult['sections']` — always the full set,
+ * never narrowed by `?since=` (this file's header). */
+type ChecklistSectionRow = ChecklistReadResult['sections'][number];
+/** One row of `ChecklistReadResult['availableTemplates']` — the agency's
+ * templates this trip hasn't pulled yet, as returned inline on the
+ * aggregate (a smaller shape than `listTemplates()`'s own
+ * `TemplatesListResponse`, which additionally carries `itemCount`/
+ * `lastUsedAt`). */
+type ChecklistAvailableTemplateRow = ChecklistReadResult['availableTemplates'][number];
+type AddChecklistItemInput = Omit<AddChecklistItemOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type PatchChecklistItemInput = Omit<PatchChecklistItemOptions, 'tripRef' | 'signal'>;
+type RemoveChecklistItemInput = Omit<DeleteChecklistItemOptions, 'tripRef' | 'signal'>;
+type ToggleChecklistItemInput = Omit<ToggleChecklistItemOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type ListChecklistTemplatesInput = Omit<ListChecklistTemplatesOptions, 'tripRef' | 'signal'>;
+type PullChecklistTemplateInput = Omit<PullChecklistTemplateOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type BoundAgencyChecklistTemplates = KaafilClient['checklists']['agencyTemplates'];
+type ListAgencyChecklistTemplatesInput = Parameters<BoundAgencyChecklistTemplates['list']>[0];
+type CreateAgencyChecklistTemplateInput = Parameters<BoundAgencyChecklistTemplates['create']>[0];
+type PatchAgencyChecklistTemplateInput = Parameters<BoundAgencyChecklistTemplates['patch']>[0];
+type RemoveAgencyChecklistTemplateInput = Parameters<BoundAgencyChecklistTemplates['remove']>[0];
+type PublishAgencyChecklistTemplateInput = Parameters<BoundAgencyChecklistTemplates['publish']>[0];
+/**
+ * The live-fetched remainder of `ChecklistAggregateResponse` — everything
+ * that isn't `items[]` (this file's header explains the split). Same
+ * `loaded`/`lastFetchFailed`/`fetchedAt`/`refresh` contract
+ * `RoomingUnassignedPool`/`FloatManagerSummaryState` already establish.
+ */
+interface ChecklistAggregateState {
+    readonly title: string | undefined;
+    readonly subtitle: string | undefined;
+    readonly progress: {
+        readonly total: number;
+        readonly complete: number;
+    } | undefined;
+    readonly hasOpenMandatoryByPhase: {
+        readonly PRE_DEPARTURE: boolean;
+        readonly IN_TRIP: boolean;
+        readonly POST_TRIP: boolean;
+    } | undefined;
+    readonly sections: readonly ChecklistSectionRow[];
+    /** The aggregate's OWN `items[]`, in the identical live-row-or-tombstone
+     * union the snapshot list holds. Kept because a desk console mounts no
+     * `OfflineShell`, so the snapshot list is permanently empty there and
+     * this fetch is the only place a desk's rows come from — see
+     * `ChecklistsReady.items`. */
+    readonly items: readonly ChecklistItemDeltaRow[];
+    readonly availableTemplates: readonly ChecklistAvailableTemplateRow[];
+    /** `true` once at least one `client.checklists.read()` call has settled
+     * (success or failure) — distinguishes "never fetched yet" from "fetched
+     * and genuinely empty." */
+    readonly loaded: boolean;
+    /** `true` when the MOST RECENT fetch threw. */
+    readonly lastFetchFailed: boolean;
+    readonly fetchedAt: string | undefined;
+    readonly refresh: () => Promise<void>;
+}
+interface ChecklistsReady {
+    /** Cache-first — `SnapshotStore`'s `'checklist'` list. */
+    readonly items: readonly ChecklistItemDeltaRow[];
+    readonly syncedAt: string | undefined;
+    readonly aggregate: ChecklistAggregateState;
+    /** `null` rather than an `OutboxOp` when the write took the DESK lane —
+     * a direct call has no outbox row to hand back. A field surface with an
+     * `OfflineShell` still gets its op. */
+    readonly addItem: (input: AddChecklistItemInput) => Promise<OutboxOp | null>;
+    readonly patchItem: (input: PatchChecklistItemInput) => Promise<OutboxOp | null>;
+    readonly removeItem: (input: RemoveChecklistItemInput) => Promise<OutboxOp | null>;
+    readonly toggleItem: (input: ToggleChecklistItemInput) => Promise<OutboxOp | null>;
+    /** Live, on-demand — see this file's header for why this is a plain
+     * function rather than auto-fetched hook state. */
+    readonly listTemplates: (input?: ListChecklistTemplatesInput) => Promise<ChecklistTemplatesListResult>;
+    readonly pullTemplate: (input: PullChecklistTemplateInput) => Promise<OutboxOp | null>;
+    /** Out of THIS family's own scope (this file's header) — wired for the
+     * future admin-family template-authoring composite. */
+    readonly listAgencyTemplates: (input: ListAgencyChecklistTemplatesInput) => ReturnType<BoundAgencyChecklistTemplates['list']>;
+    readonly createAgencyTemplate: (input: CreateAgencyChecklistTemplateInput) => ReturnType<BoundAgencyChecklistTemplates['create']>;
+    readonly patchAgencyTemplate: (input: PatchAgencyChecklistTemplateInput) => ReturnType<BoundAgencyChecklistTemplates['patch']>;
+    readonly removeAgencyTemplate: (input: RemoveAgencyChecklistTemplateInput) => ReturnType<BoundAgencyChecklistTemplates['remove']>;
+    readonly publishAgencyTemplate: (input: PublishAgencyChecklistTemplateInput) => ReturnType<BoundAgencyChecklistTemplates['publish']>;
+}
+/**
+ * PERSONALIZED mode-dark. Returns `{ status: 'dark', reason }` before any
+ * fetch when the `'checklists'` capability triple isn't `lit`
+ * (`06-capability-and-personas.md §3`).
+ */
+declare function useChecklists(tripRef: string): DomainHookResult<ChecklistsReady>;
+
+interface FilesContext {
+    readonly tripRef: string;
+}
+type RequestOptions = Omit<Parameters<FilesResource['request']>[0], 'tripRef'>;
+type ConfirmOptions = Omit<Parameters<FilesResource['confirm']>[0], 'signal'>;
+type ListOptions = Omit<Parameters<FilesResource['list']>[0], 'tripRef'>;
+type FileMeta = Awaited<ReturnType<FilesResource['meta']>>;
+type FileUrl = Awaited<ReturnType<FilesResource['url']>>;
+type FileListItem = Awaited<ReturnType<FilesResource['list']>>['items'][number];
+type ManagerFileView = Awaited<ReturnType<FilesResource['managerView']>>;
+type FilePurpose = FileMeta['purpose'];
+interface FilesReady {
+    /** `POST /api/v1/files` — mints a `pending` row + a presigned `PUT`. */
+    readonly request: (input: RequestOptions) => ReturnType<FilesResource['request']>;
+    /** `POST /api/v1/files/{id}/confirm` — verifies what landed, flips
+     * `pending` → `ready`. `422 UPLOAD_MISMATCH` leaves the file `pending`;
+     * the caller re-`PUT`s and re-confirms (`FileAttachmentFlow` does this
+     * itself, see its own file). */
+    readonly confirm: (input: ConfirmOptions) => ReturnType<FilesResource['confirm']>;
+    /** `GET /api/v1/files/{id}` — the metadata skeleton; `200` even once
+     * `purged` — the one read that never 404s on a gone file. */
+    readonly meta: (fileId: string) => Promise<FileMeta>;
+    /** `GET /api/v1/files/{id}/url` — a fresh 5-minute signed GET, minted on
+     * every call, never cached across calls. `410 FILE_PURGED` once the
+     * bytes are gone. */
+    readonly url: (fileId: string) => Promise<FileUrl>;
+    /** `GET /api/v1/files?tripRef=…` — every file for this trip, newest
+     * first, optionally narrowed by `purpose`/`status`. Needs no `fileId`. */
+    readonly list: (query?: ListOptions) => Promise<readonly FileListItem[]>;
+    /** `GET /api/v1/files/{id}/manager-view` — `meta()` + `url()` composed
+     * server-side into one manager-doc-viewer-shaped response. Never refuses
+     * on a non-`ready` file the way `url()` does — `url`/`urlExpiresAt` come
+     * back `null` instead. */
+    readonly managerView: (fileId: string) => Promise<ManagerFileView>;
+    /**
+     * The full presign → direct-`PUT` → confirm sequence for one local
+     * `File`, run in the foreground. On a `422 UPLOAD_MISMATCH` OR a presign
+     * window that lapsed mid-`PUT` (the underlying `PUT`/`confirm` answering
+     * a plain network failure once the 15-minute signature has expired) this
+     * re-requests a fresh slot and retries silently, up to `maxAttempts` —
+     * `07-files.md`'s own "must never surface as an error" contract for the
+     * routine case. Bytes never pass through this SDK or the Kaafil API
+     * itself; only the presign/confirm calls do.
+     */
+    readonly upload: (input: {
+        readonly file: File;
+        readonly purpose: FilePurpose;
+        /** REQUIRED for `trip_document`, refused (422) for every other purpose —
+         * nothing else names that file. */
+        readonly title?: string;
+        /** Only for `trip_document`. Omit and the document belongs to the whole
+         * trip; name a traveller and only they see it on their own share link.
+         * It also decides retention (scoped → `TRAVELLER_PII`). */
+        readonly travellerRef?: string;
+        readonly maxAttempts?: number;
+        readonly signal?: AbortSignal;
+    }) => Promise<FileMeta>;
+}
+declare function useFiles(context: FilesContext): FilesReady;
+
+/** One row of `ExpensesReady['expenses']` — a live expense (the full
+ * `ExpenseResponse` shape) or the tombstone for one voided-and-purged since
+ * the last cursor. Structurally identical split to `RoomingRoomDeltaRow`
+ * (`useRooming.ts`) — `ExpenseListResponse.items[]` is `anyOf` the two,
+ * verified against `kaafil-js/openapi/openapi.json`. */
+type ExpenseDeltaRow = Awaited<ReturnType<ExpensesResource['list']>>['items'][number];
+/** `ExpenseDeltaRow`, narrowed to the live shape — a voided-and-purged row
+ * carries no `category`/`paymentMode`/etc. at all. Composites built on this
+ * hook (`manager/composite/expenses/*`) filter to this narrowed type before
+ * rendering, the same `isLive*` pattern `useRooming.ts`'s consumers use. */
+type ExpenseLiveRow = Exclude<ExpenseDeltaRow, {
+    readonly _tombstone: true;
+}>;
+type LogExpenseInput = Omit<LogExpenseOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type LinkExpenseReceiptInput = Omit<LinkExpenseReceiptOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type VoidExpenseInput = Omit<VoidExpenseOptions, 'tripRef' | 'signal'>;
+type SubmitExpenseClaimInput = Omit<SubmitExpenseClaimOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type WithdrawExpenseClaimInput = Omit<WithdrawExpenseClaimOptions, 'tripRef' | 'signal'>;
+type LogInput = LogExpenseInput;
+type LinkReceiptInput = LinkExpenseReceiptInput;
+type VoidInput = VoidExpenseInput;
+type SubmitClaimInput = SubmitExpenseClaimInput;
+type WithdrawClaimInput = WithdrawExpenseClaimInput;
+interface ExpensesReady {
+    readonly expenses: readonly ExpenseDeltaRow[];
+    readonly syncedAt: string | undefined;
+    /** Re-reads the desk lane after a write. A NO-OP on a field device, where
+     * the outbox drain emits `snapshot.updated` and the cache-first read
+     * re-renders itself — a composite need not know which lane it is on. */
+    readonly refreshLive: () => Promise<void>;
+    /** Live read (`client.expenses.read()`), not cache-first — for a detail
+     * screen that wants the freshest single row rather than whatever the last
+     * pull cached. The list above stays the cache-first source for every list
+     * view. */
+    readonly read: (expenseId: string) => ReturnType<ExpensesResource['read']>;
+    readonly log: (input: LogInput) => Promise<OutboxOp | null>;
+    /** FIELD-ONLY — see the mutation's own note: its route requires a
+     * client-minted idempotency key, which hard rule #4 forbids this layer
+     * from supplying, so there is no desk lane and a desk must not offer it. */
+    readonly linkReceipt: (input: LinkReceiptInput) => Promise<OutboxOp>;
+    readonly void: (input: VoidInput) => Promise<OutboxOp | null>;
+    readonly submitClaim: (input: SubmitClaimInput) => Promise<OutboxOp>;
+    readonly withdrawClaim: (input: WithdrawClaimInput) => Promise<OutboxOp>;
+    /**
+     * The SERVER's own spend rollup for this trip — `spendTotalMinor` and the
+     * per-category breakdown, straight off `expenses.list()`'s envelope.
+     *
+     * Its own live state rather than a field on the snapshot list, for the
+     * reason `useFloat.summary` and `useCollections.eligible` are: these are
+     * DERIVED figures with no `id`/`version`, so there is nothing for
+     * `SnapshotStore` to key on, and `useSnapshotList`'s `live` contract
+     * returns `{rows, syncedAt}` with no slot for an envelope.
+     *
+     * Exposed because summing the rows in the browser is the wrong answer
+     * twice over: it would miss anything outside the page and it would put a
+     * money figure's correctness in the client. `deriveOverview.ts` wanted
+     * exactly this and said so ("wants a server-side rollup … until it lands
+     * this card states the two numbers it can stand behind").
+     */
+    readonly totals: ExpenseTotalsState;
+}
+/** The server's spend rollup, and whether it could be read at all. */
+interface ExpenseTotalsState {
+    /** `undefined` until a read lands — NEVER 0. A money figure the surface
+     * could not read must not be drawn as zero. */
+    readonly spendTotalMinor: number | undefined;
+    readonly categoryTotals: Readonly<Record<string, number>> | undefined;
+    readonly loaded: boolean;
+    readonly lastFetchFailed: boolean;
+    readonly refresh: () => Promise<void>;
+}
+/**
+ * PERSONALIZED mode-dark. Returns `{ status: 'dark', reason }` before any
+ * fetch when the `'expenses'` capability triple isn't `lit`
+ * (`06-capability-and-personas.md §3`).
+ */
+declare function useExpenses(tripRef: string): DomainHookResult<ExpensesReady>;
+
+/** One row of the calling manager's own float ledger — verified against
+ * `FloatLedgerResponse.data[number]` (`generated/schema.d.ts`). See this
+ * file's header for why no tombstone variant is modelled. */
+type FloatMovementRow = Awaited<ReturnType<FloatResource['readLedger']>>['data'][number];
+/** One row of `FloatSummaryResponse.data[]` — entirely derived, never
+ * delta-mergeable. See this file's header. */
+type FloatSummaryRow = Awaited<ReturnType<FloatResource['readSummary']>>['data'][number];
+type IssueFloatInput = Omit<IssueFloatOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type ReturnFloatInput = Omit<ReturnFloatOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type AdjustFloatInput = Omit<AdjustFloatOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+/**
+ * The live-fetched balance/breakdown state — `readSummary()`'s own rows,
+ * refreshed explicitly rather than subscribed to `snapshot.updated`. Carries
+ * every manager row the calling credential is entitled to see (a manager
+ * session is answered its own row only, per `float.ts`'s own header — this
+ * hook does not re-filter that, since it has no independent way to verify
+ * which row is "self" beyond what the server already scoped the response
+ * to); a composite that needs "my own row" specifically matches on the
+ * `managerRef`/`managerId` it was itself handed as a prop.
+ */
+interface FloatManagerSummaryState {
+    readonly rows: readonly FloatSummaryRow[];
+    /** `true` once at least one `client.float.readSummary()` call has settled
+     * (success or failure) — distinguishes "never fetched yet" from "fetched
+     * and genuinely empty," the same contract `RoomingUnassignedPool.loaded`
+     * documents. */
+    readonly loaded: boolean;
+    /** `true` when the MOST RECENT fetch threw. */
+    readonly lastFetchFailed: boolean;
+    /** The server time (`meta.serverTime`) of the last successful fetch. */
+    readonly fetchedAt: string | undefined;
+    readonly refresh: () => Promise<void>;
+}
+interface FloatReady {
+    /** The calling manager's own movement history, cache-first — see this
+     * file's header for why this is the one cache-first field on this hook. */
+    readonly movements: readonly FloatMovementRow[];
+    readonly syncedAt: string | undefined;
+    readonly summary: FloatManagerSummaryState;
+    /**
+     * ONE NAMED MANAGER's movement history — `GET .../float/{managerId}/ledger`.
+     *
+     * Distinct from `movements` above, and the distinction matters on a desk:
+     * `movements` is the CALLING MANAGER's own ledger, read from the `'float'`
+     * pull section, which is scoped that way. An agency admin has no `Manager`
+     * row, so there is no "own ledger" for them to read and no live lane that
+     * could sensibly fill one — a desk asks "show me THIS manager's
+     * movements", which is what this is for. `summary` names every manager who
+     * has ever had a movement on the trip, so a caller always has an id to
+     * pass.
+     */
+    readonly readLedger: (managerId: string) => ReturnType<FloatResource['readLedger']>;
+    /** `POST .../float/issue` — `type=ISSUE`, `direction=IN`, never
+     * negative-float guarded. */
+    readonly issue: (input: IssueFloatInput) => Promise<OutboxOp | null>;
+    /** `POST .../float/return` — `type=RETURN`, `direction=OUT`,
+     * negative-float guarded. A manager, an API key OR an agency admin may
+     * call it: this comment previously claimed `managerAuth`-only and that an
+     * admin "gets refused by the server", which is wrong —
+     * `float.routes.ts` declares the admin triple on it and its route
+     * description calls the parity a deliberate owner decision. An office
+     * reconciling a returned cash box is the case it exists for. */
+    readonly return: (input: ReturnFloatInput) => Promise<OutboxOp | null>;
+    /** `POST .../float/adjust` — `type=ADJUSTMENT`; `direction: 'OUT'` is
+     * negative-float guarded identically to `return`, `direction: 'IN'`
+     * never is. `note` is required by the wire request type itself. */
+    readonly adjust: (input: AdjustFloatInput) => Promise<OutboxOp | null>;
+}
+/**
+ * PERSONALIZED mode-dark. Returns `{ status: 'dark', reason }` before any
+ * fetch when the `'float'` capability triple isn't `lit`
+ * (`06-capability-and-personas.md §3`).
+ */
+declare function useFloat(tripRef: string): DomainHookResult<FloatReady>;
+
+/** One row of `GET /api/v1/trips/{ref}/forms` — `TripFormsListResponse.items[]`
+ * (verified, `kaafil-js/src/generated/schema.d.ts`). Carries `id`/`version`
+ * like a delta row, but is NOT one — `SYNC_PULL_SECTIONS` has no `forms`
+ * entry (this file's own header, corrected this pass), so this is a live
+ * fetch (`forms.trip.list`), never a snapshot-list read. */
+type TripFormRow = Awaited<ReturnType<FormsResource['trip']['list']>>['items'][number];
+/** One row of `GET /api/v1/trips/{ref}/forms/completion` — PER FORM, not
+ * per traveller. See `completion()`'s own note. */
+type FormCompletionRow = Awaited<ReturnType<FormsResource['trip']['completion']>>['items'][number];
+type DispatchFormInput = Omit<DispatchFormOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type ExportFormResponsesInput = Omit<ExportFormResponsesOptions, 'signal'>;
+type ConsentReceiptInput = Omit<ReadFormConsentReceiptOptions, 'signal'>;
+/** `GET /api/v1/forms/{formId}` — `FormDetailResponse`: sections + fields +
+ * resolved options, the definition `FormFillRenderer` renders. A live read
+ * (mirrors `useShareForms.renderForm`'s own "live call, not cached" note) —
+ * there is no per-form definition slot in the trip snapshot's `'forms'`
+ * section, only the summary row list. */
+type FormDefinitionDetail = Awaited<ReturnType<FormsResource['get']>>;
+/** `GET /api/v1/forms/{formId}/responses/{responseId}` —
+ * `ResponseDetailResponse`: the full answer set plus staleness flags against
+ * the current form version. */
+type FormResponseDetail = Awaited<ReturnType<FormsResource['responses']['get']>>;
+/** One row of `GET /api/v1/trips/{ref}/travellers/{travellerRef}/forms/
+ * responses` — this traveller's `FormResponse` rows across every form on the
+ * trip (the per-traveller cross-form read `TripFormResponsesResource.list`,
+ * scoped to one `formId`, cannot give). Used to resolve "has this filler
+ * already got a response for this form, and what's its id/status" without a
+ * second per-form list call per row. */
+type TravellerFormResponseRow = Awaited<ReturnType<FormsResource['trip']['travellerResponses']['list']>>['items'][number];
+/** One row of `GET /api/v1/trips/{ref}/forms/{formId}/responses` — EVERY
+ * respondent's row for one form (the per-form cross-traveller read
+ * `TripFormResponsesResource.list`, the other axis from
+ * `travellerResponses` above — same underlying `ResponsesListResponse`
+ * shape, verified identical, just a different URL/fixed axis). `managerAuth`
+ * is allowed (`generated/security.ts`, verified) — this is what a manager
+ * needs to browse "who has answered this form" for a `TRAVELLER`-audience
+ * form, never a browsable-all-travellers index of its own (that stays out
+ * of scope, `manager/05-forms.md`'s own boundary). */
+type TripFormResponseRow = Awaited<ReturnType<FormsResource['trip']['responses']['list']>>['items'][number];
+/** `POST /api/v1/trips/{ref}/forms/{formId}/responses` body — a manager
+ * self-fill (`travellerRef` omitted) or on-behalf capture
+ * (`travellerRef` set), `submit: false` for a draft save and `true` for a
+ * final submit. No `clientToken` on this route (unlike the share-surface's
+ * `save`/`submit`, `useShareForms.ts`'s own header note) — the standard
+ * `Idempotency-Key` header `OfflineEngine.enqueue()` mints once per op is
+ * this route's only de-dupe key. */
+type SubmitFormResponseInput = Omit<ManagerCreateFormResponseOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+/** `GET /api/v1/agencies/{ref}/forms` row — `FormListResponse.items[]`, the
+ * agency's whole catalog (every locale/status/scope), `FormsCatalogScreen`'s
+ * own read. Structurally identical to `FormDefinitionResponse`; named
+ * separately here because it is reached through a different call
+ * (`forms.list`, not `forms.get`). */
+type FormAgencyRow = Awaited<ReturnType<FormsResource['list']>>['items'][number];
+/** The patch-transition family's own return shape — `forms.patch`/
+ * `.publish`/`.close`/`.reopen`/`.archive`/`.unarchive`/`.clone` all answer
+ * `FormDefinitionResponse`, the metadata-only row (no `sections`/`fields`) —
+ * distinct from `FormDefinitionDetail`, which only `.get`/`.create` return. */
+type FormDefinitionSummary = Awaited<ReturnType<FormsResource['patch']>>;
+type FormSectionDetail = FormDefinitionDetail['sections'][number];
+type FormFieldDetail = FormDefinitionDetail['fields'][number];
+/** `GET /api/v1/forms/bindings` row — the closed 16-key binding registry
+ * `BindingCatalogBrowser` browses. */
+type BindingEntry = Awaited<ReturnType<FormsResource['bindings']['list']>>['items'][number];
+/** `forms.create`'s own body, `agencyRef` dropped (browser-bound, see this
+ * file's own header) and the request-plumbing fields excluded — the exact
+ * shape `FormBuilder` composes from its metadata/section/field draft. */
+type CreateFormInput = Omit<BoundCreateFormOptions, 'idempotencyKey' | 'signal'>;
+type PatchFormInput = Omit<PatchFormOptions, 'signal'>;
+type CloneFormInput = Omit<CloneFormOptions, 'idempotencyKey' | 'signal'>;
+type ReorderFormInput = Omit<ReorderFormOptions, 'signal'>;
+type CreateFormSectionInput = Omit<CreateFormSectionOptions, 'signal'>;
+type PatchFormSectionInput = Omit<PatchFormSectionOptions, 'signal'>;
+type DeleteFormSectionInput = Omit<DeleteFormSectionOptions, 'signal'>;
+type CreateFormFieldInput = Omit<CreateFormFieldOptions, 'signal'>;
+type PatchFormFieldInput = Omit<PatchFormFieldOptions, 'signal'>;
+type DeleteFormFieldInput = Omit<DeleteFormFieldOptions, 'signal'>;
+interface FormsReady {
+    /** This trip's applicable forms, each with its resolved `window` and
+     * `dispatched`/`submitted` counts — `TripFormsPanel`'s own read. Live-
+     * fetched and explicitly refreshed (this file's header, corrected this
+     * pass) — NOT a cache-first snapshot-list read. */
+    readonly forms: readonly TripFormRow[];
+    /** The last successful live fetch's own `meta.serverTime` — `undefined`
+     * before the first fetch settles. */
+    readonly syncedAt: string | undefined;
+    /** Live read of one form's definition (sections + fields). */
+    readonly getDefinition: (formId: string) => Promise<FormDefinitionDetail>;
+    /** Live read of one response's full answer set + staleness flags. */
+    readonly getResponse: (formId: string, responseId: string) => Promise<FormResponseDetail>;
+    /** Live read of one traveller's responses across every form on the trip —
+     * how `FormFillFlow` resolves "already submitted" / prefill without a
+     * per-form response list call. */
+    readonly travellerResponses: (travellerRef: string) => Promise<readonly TravellerFormResponseRow[]>;
+    /** Live read of EVERY respondent's row for one form — how a manager
+     * browses "who has answered this `TRAVELLER`-audience form" (the other
+     * axis from `travellerResponses`). */
+    readonly formResponses: (formId: string) => Promise<readonly TripFormResponseRow[]>;
+    /** Save (`submit: false`) or finalize (`submit: true`) a response —
+     * self-fill or on-behalf, same endpoint, same outbox-backed write. */
+    /** `null` rather than an `OutboxOp` when the write took the DESK lane —
+     * a direct call has no outbox row to hand back. */
+    readonly submitResponse: (input: SubmitFormResponseInput) => Promise<OutboxOp | null>;
+    /** `forms.list` — the agency's whole catalog, browser-bound (no
+     * `agencyRef` to supply). */
+    /** `getFormsCompletionMatrix` — one row PER FORM, not a traveller grid.
+     * See the callback's own note. */
+    /** Re-reads the live trip forms list. Exposed because a composite
+     * showing a failed read needs a retry, and `forms`/`syncedAt` are
+     * fetched, not subscribed. */
+    readonly refresh: () => Promise<void>;
+    readonly completion: () => Promise<readonly FormCompletionRow[]>;
+    /** `dispatchForm` — sends a form to travellers and refreshes the list,
+     * since it moves `dispatched`. */
+    readonly dispatch: (input: DispatchFormInput) => Promise<void>;
+    readonly exportResponses: (input: ExportFormResponsesInput) => Promise<KaafilBinaryResponse>;
+    readonly consentReceipt: (input: ConsentReceiptInput) => Promise<KaafilBinaryResponse>;
+    readonly listAgencyForms: () => Promise<readonly FormAgencyRow[]>;
+    /** `forms.create` — authors a fresh `DRAFT`, browser-bound. */
+    readonly createForm: (input: CreateFormInput) => Promise<FormDefinitionDetail>;
+    readonly patchForm: (input: PatchFormInput) => Promise<FormDefinitionSummary>;
+    readonly publishForm: (formId: string) => Promise<FormDefinitionSummary>;
+    readonly closeForm: (formId: string) => Promise<FormDefinitionSummary>;
+    readonly reopenForm: (formId: string) => Promise<FormDefinitionSummary>;
+    readonly archiveForm: (formId: string) => Promise<FormDefinitionSummary>;
+    readonly unarchiveForm: (formId: string) => Promise<FormDefinitionSummary>;
+    readonly cloneForm: (input: CloneFormInput) => Promise<FormDefinitionSummary>;
+    /** `forms.reorder` — one idempotent transaction over every section's and
+     * field's `sortOrder`, never one call per row (this spec entry's own
+     * `Does NOT`). */
+    readonly reorderForm: (input: ReorderFormInput) => Promise<void>;
+    readonly createSection: (input: CreateFormSectionInput) => Promise<FormSectionDetail>;
+    readonly patchSection: (input: PatchFormSectionInput) => Promise<FormSectionDetail>;
+    readonly deleteSection: (input: DeleteFormSectionInput) => Promise<void>;
+    readonly createField: (input: CreateFormFieldInput) => Promise<FormFieldDetail>;
+    readonly patchField: (input: PatchFormFieldInput) => Promise<FormFieldDetail>;
+    readonly deleteField: (input: DeleteFormFieldInput) => Promise<void>;
+    /** `forms.bindings.list` — the closed 16-key registry; `apiKeyAuth`/
+     * `agencyAdminAuth`/`managerAuth` all accepted (`generated/security.ts`). */
+    readonly listBindings: () => Promise<readonly BindingEntry[]>;
+}
+/**
+ * Not mode-dark (`manager/05-forms.md`'s own framing note) — a dark result
+ * from this trip's `'forms'` capability row is always data- or flag-shaped
+ * in practice. Returns `{ status: 'dark', reason }` before any fetch when
+ * that row isn't `lit`.
+ */
+declare function useForms(tripRef: string): DomainHookResult<FormsReady>;
+
+type ItineraryReadResult = Awaited<ReturnType<ItineraryResource['read']>>;
+/** One row of `ItineraryReadResponse.days[]` — no tombstone branch (this
+ * section is never delta-pulled; see this file's header). */
+type ItineraryDayRow = ItineraryReadResult['days'][number];
+/** `ItineraryReadResponse.items[]`'s generated shape is `anyOf` a live item
+ * or a tombstone — the same shared shape the delta (`?since=`) mode uses,
+ * even though a full/no-`since` read (the only mode this hook ever calls)
+ * has nothing to report a tombstone against. This hook filters the
+ * tombstone variant out in `refresh()` below rather than exposing the raw
+ * union, so every `ItineraryItemRow` a composite reads is unconditionally
+ * live — the same `isLiveRoom`/`Exclude<..., {_tombstone:true}>` pattern
+ * `useRooming.ts`'s own consumers use, applied inside the hook here since
+ * this hook, unlike `useRooming()`, has no separate delta-row type the spec
+ * asks composites to narrow themselves. */
+type ItineraryItemUnion = ItineraryReadResult['items'][number];
+type ItineraryItemRow = Exclude<ItineraryItemUnion, {
+    readonly _tombstone: true;
+}>;
+type ItineraryTripSummary = ItineraryReadResult['trip'];
+type ItineraryChangeLogRow = Awaited<ReturnType<ItineraryResource['changeLog']['list']>>[number];
+type AddItineraryItemInput = Omit<AddItineraryItemOptions, 'tripRef' | 'signal'>;
+type PatchItineraryItemInput = Omit<PatchItineraryItemOptions, 'tripRef' | 'signal'>;
+type RemoveItineraryItemInput = Omit<DeleteItineraryItemOptions, 'tripRef' | 'signal'>;
+type ReorderItineraryItemInput = Omit<ReorderItineraryItemOptions, 'tripRef' | 'signal'>;
+type PatchItineraryDayInput = Omit<PatchItineraryDayOptions, 'tripRef' | 'signal'>;
+type LoadItineraryChangeLogInput = Omit<ListItineraryChangeLogOptions, 'tripRef' | 'signal'>;
+interface ItineraryReady {
+    readonly trip: ItineraryTripSummary | undefined;
+    /** Server's own pick of which day the itinerary screen should land on
+     * (today → first future day → Day 1, `FRD:itinerary §5`) — never
+     * computed client-side. */
+    readonly initialDayIso: string | undefined;
+    readonly canAddItems: boolean;
+    readonly canAddItemsReason: string | null;
+    readonly days: readonly ItineraryDayRow[];
+    readonly items: readonly ItineraryItemRow[];
+    /** `true` once the first `itinerary.read()` has settled (success or
+     * failure) — distinguishes "never fetched yet" from "fetched, trip has
+     * zero days," the same discipline `RoomingReady.unassignedPool.loaded`
+     * documents. */
+    readonly loaded: boolean;
+    readonly lastFetchFailed: boolean;
+    readonly syncedAt: string | undefined;
+    readonly refresh: () => Promise<void>;
+    readonly changeLog: readonly ItineraryChangeLogRow[];
+    readonly changeLogLoaded: boolean;
+    readonly changeLogFetchFailed: boolean;
+    readonly loadChangeLog: (input?: LoadItineraryChangeLogInput) => Promise<void>;
+    readonly patchDay: (input: PatchItineraryDayInput) => Promise<OutboxOp | null>;
+    readonly addItem: (input: AddItineraryItemInput) => Promise<OutboxOp | null>;
+    readonly patchItem: (input: PatchItineraryItemInput) => Promise<OutboxOp | null>;
+    readonly removeItem: (input: RemoveItineraryItemInput) => Promise<OutboxOp | null>;
+    readonly reorderItem: (input: ReorderItineraryItemInput) => Promise<OutboxOp | null>;
+}
+type ItineraryResult = {
+    readonly status: 'loading';
+} | ({
+    readonly status: 'ready';
+} & ItineraryReady) | {
+    readonly status: 'error';
+};
+/**
+ * Ungated (see this file's header) — never returns `{status:'dark'}`.
+ * `manager`/`agencyAdmin` both call this same hook (`FRD:itinerary`'s
+ * `COORDINATOR`-role read-only resolution happens on the OPEN SESSION,
+ * server-side, never as a UIKit prop or a second hook).
+ */
+declare function useItinerary(tripRef: string): ItineraryResult;
+
+type RoomingStayWindowRow = Awaited<ReturnType<RoomingResource['stayWindows']['list']>>[number];
+type AssignBedInput = Omit<AssignRoomingBedOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type AutoAssignInput = Omit<AutoAssignRoomingOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type CreateWindowInput = Omit<CreateRoomingStayWindowOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type PatchWindowInput = Omit<PatchRoomingStayWindowOptions, 'tripRef' | 'signal'>;
+type RemoveWindowInput = Omit<DeleteRoomingStayWindowOptions, 'tripRef' | 'signal'>;
+type CreateRoomInput = Omit<CreateRoomingRoomOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type PatchRoomInput = Omit<PatchRoomingRoomOptions, 'tripRef' | 'signal'>;
+type RemoveRoomInput = Omit<DeleteRoomingRoomOptions, 'tripRef' | 'signal'>;
+/**
+ * The unassigned-traveller roster — `RoomingBoardResponse.unassigned[]`
+ * (`kaafil-js/openapi/openapi.json`, verified). Its own state, deliberately
+ * NOT folded into `rooms`/`stayWindows`'s cache-first shape, so a consumer
+ * can never mistake one for the other.
+ */
+interface RoomingUnassignedPool {
+    readonly travellers: readonly RoomingOccupant[];
+    /** `true` once at least one `client.rooming.read()` call has settled
+     * (success or failure) — distinguishes "never fetched yet" from "fetched
+     * and genuinely empty." */
+    readonly loaded: boolean;
+    /** `true` when the MOST RECENT fetch threw (offline, network, server
+     * error) — a consumer must render this differently from `travellers: []`
+     * with `loaded: true`; those two states are never the same thing. */
+    readonly lastFetchFailed: boolean;
+    /** The server time (`meta.serverTime`) of the last successful fetch —
+     * `undefined` before any fetch has ever succeeded. Never a locally-minted
+     * timestamp (hard rule #6). */
+    readonly fetchedAt: string | undefined;
+    /** Re-runs the live read, optionally scoped to one stay window.
+     *
+     * `stayWindowId` matters: the engine's own `readBoard` (`kaafil-engine`
+     * `rooming.service.ts#unassignedCountForWindow`'s doc comment) computes
+     * "unassigned" PER WINDOW deliberately — "a trip-wide unassigned count
+     * would have to decide whether a traveller with a bed on night 1 and none
+     * on night 2 is assigned, and there is no answer to that a subscriber
+     * could use." Passing the board's currently-active window here is what
+     * makes the pool answer "who still needs a bed IN THIS WINDOW," which is
+     * the only question a manager looking at one window's board is actually
+     * asking. Omitting it (this hook's own initial mount-time fetch, before
+     * any window is known) falls back to the engine's unscoped trip-wide
+     * read — genuinely ambiguous, per the same comment, so a caller that
+     * knows the active window should always pass it.
+     *
+     * `assign` already calls this on its own success (a bed assignment
+     * changes who is unassigned); a composite calls it again after any OTHER
+     * action that can move someone in or out of the pool. */
+    readonly refresh: (stayWindowId?: string) => Promise<void>;
+}
+interface RoomingReady {
+    readonly rooms: readonly RoomingRoomDeltaRow[];
+    readonly stayWindows: readonly RoomingStayWindowRow[];
+    readonly syncedAt: string | undefined;
+    /**
+     * LIVE-READ, NOT cache-first — deliberately. `RoomingBoardResponse`
+     * (`openapi/openapi.json`) carries three arrays; only `rooms[]` is
+     * delta-shaped (`anyOf` a live row or a `_tombstone`, with `id`/
+     * `version`). `unassigned[]` is a plain object keyed on `travellerId`
+     * with no tombstone branch and no version — a DERIVED projection the
+     * engine recomputes per read, not a durable delta feed
+     * (`kaafil-js/src/offline/pull.ts`'s `extractSectionRows` docstring,
+     * verified this session). Caching it as a delta row would be a real bug:
+     * no tombstone can ever arrive for a traveller who GETS a bed, and
+     * `SnapshotStore.applyPull` rebases by id rather than replacing, so a
+     * cached pool would grow monotonically and never shrink. This field is
+     * therefore sourced from its own `client.rooming.read()` call, refreshed
+     * explicitly rather than subscribed to `snapshot.updated`.
+     */
+    readonly unassignedPool: RoomingUnassignedPool;
+    /** Re-reads both desk lanes after a write. A NO-OP on a field device,
+     * where the outbox drain emits `snapshot.updated` and the cache-first
+     * reads re-render themselves — a composite need not know which lane it is
+     * on. */
+    readonly refreshLive: () => Promise<void>;
+    readonly assign: (input: AssignBedInput) => Promise<OutboxOp | null>;
+    readonly autoAssign: (input: AutoAssignInput) => ReturnType<RoomingResource['autoAssign']>;
+    readonly createStayWindow: (input: CreateWindowInput) => Promise<OutboxOp | null>;
+    readonly patchStayWindow: (input: PatchWindowInput) => Promise<OutboxOp | null>;
+    readonly removeStayWindow: (input: RemoveWindowInput) => Promise<OutboxOp | null>;
+    readonly createRoom: (input: CreateRoomInput) => Promise<OutboxOp | null>;
+    readonly patchRoom: (input: PatchRoomInput) => Promise<OutboxOp | null>;
+    readonly removeRoom: (input: RemoveRoomInput) => Promise<OutboxOp | null>;
+}
+
+/**
+ * PERSONALIZED mode-dark. Returns `{ status: 'dark', reason }` before any
+ * fetch when the `'rooming'` capability triple isn't `lit`
+ * (`06-capability-and-personas.md §3`).
+ */
+declare function useRooming(tripRef: string): DomainHookResult<RoomingReady>;
+
+/** One row of `vendors.list()`'s array — `VendorSummaryResponse`
+ * (`kaafil-js/src/generated/schema.d.ts`, verified): `id`/`name`/`category`/
+ * `phone`/`city`. `phone`/`city` are nullable — absent until the CRM feeds
+ * one. Still no `status`, no `expenseTotalMinor` on the wire — a consumer
+ * that needs either is reading a field this response does not send.
+ * `KaafilResponse<readonly VendorSummaryResponse[]>` is `T & { meta }`
+ * (`kaafil-js/src/types/meta.ts`'s own intersection, verified) — the
+ * response IS the array, `meta` attached, never a nested `.data` field. */
+type TripVendorRow = Awaited<ReturnType<VendorsResource['list']>>[number];
+type UpsertVendorInput = Omit<UpsertVendorOptions, 'agencyRef' | 'idempotencyKey' | 'signal'>;
+type RemoveVendorInput = Omit<DeleteVendorOptions, 'agencyRef' | 'idempotencyKey' | 'signal'>;
+/** `create` takes neither an external id nor a `sourceUpdatedAt` — the
+ * server mints the first and stamps the second. See `VendorsReady.create`. */
+type CreateVendorInput = Omit<CreateVendorOptions, 'agencyRef' | 'idempotencyKey' | 'signal'>;
+interface VendorsReady {
+    readonly vendors: readonly TripVendorRow[];
+    /** `true` once at least one `client.vendors.list()` call has settled
+     * (success or failure) — same `loaded` contract `TrekBoardState`/
+     * `RoomingUnassignedPool` document. */
+    readonly loaded: boolean;
+    /** `true` when the MOST RECENT fetch threw — distinct from an honest
+     * empty directory (`loaded: true`, `vendors: []`). */
+    readonly lastFetchFailed: boolean;
+    /** The server time (`meta.serverTime`) of the last successful fetch. */
+    readonly syncedAt: string | undefined;
+    readonly refresh: () => Promise<void>;
+    /**
+     * Agency-scoped create for a vendor the AGENCY authored, not one a CRM
+     * pushed (`POST /agencies/:ref/vendors`).
+     *
+     * Takes NO external id and NO `sourceUpdatedAt`: `Vendor.externalId` is
+     * `NOT NULL`, so before this route existed the only create path was
+     * `upsert`, which is addressed by the caller's own CRM id — something an
+     * operator adding a supplier by hand does not have and must not be asked
+     * to invent. The server mints it (prefixed `kf-`) and stamps the write
+     * with its own clock.
+     */
+    readonly create: (input: CreateVendorInput) => ReturnType<VendorsResource['create']>;
+    /** Agency-scoped CRM upsert — see this file's header. Doubles as the EDIT
+     * of an existing vendor: `sourceUpdatedAt` is optional on the wire now, and
+     * omitting it has the server stamp the edit rather than letting it lose an
+     * LWW comparison against the very row the operator is looking at. */
+    readonly upsert: (input: UpsertVendorInput) => ReturnType<VendorsResource['upsert']>;
+    /** Agency-scoped CRM soft-delete — see this file's header. */
+    readonly remove: (input: RemoveVendorInput) => ReturnType<VendorsResource['remove']>;
+}
+declare function useVendors(tripRef: string, agencyRef: string): DomainHookResult<VendorsReady>;
+
+export { useItinerary as A, useRooming as B, type ChecklistSectionRow as C, type DomainHookResult as D, type ExpenseDeltaRow as E, type FileListItem as F, useVendors as G, type CreateAgencyChecklistTemplateInput as H, type ItineraryDayRow as I, type RemoveAgencyChecklistTemplateInput as J, type PublishAgencyChecklistTemplateInput as K, type FormDefinitionDetail as L, type FormResponseDetail as M, type TravellerFormResponseRow as N, type ExpenseLiveRow as O, type PatchAgencyChecklistTemplateInput as P, type ChecklistAvailableTemplateRow as Q, type RoomingStayWindowRow as R, type FilePurpose as S, type TripFormRow as T, type ManagerFileView as U, type VendorsReady as V, type ChecklistsReady as a, type FloatMovementRow as b, type TripFormResponseRow as c, type ItineraryItemRow as d, type TripVendorRow as e, type FloatSummaryRow as f, type CapabilityTriple as g, type ErrorClassification as h, type CapabilityRow as i, type DarkReason as j, ERROR_HANDLING_PATH as k, type ErrorHandlingPath as l, type ExpensesReady as m, type FilesContext as n, type FilesReady as o, type FloatReady as p, type FormsReady as q, type ItineraryReady as r, type RoomingReady as s, type RoomingUnassignedPool as t, classifyError as u, useChecklists as v, useExpenses as w, useFiles as x, useFloat as y, useForms as z };