kaafil-react-uikit 0.1.0-beta.1

package/dist/useNotifications-D262i5BQ.d.ts

@@ -0,0 +1,356 @@
+import { PartyDeltaRow, TravellersResource, AddPartyOptions, OutboxOp, PatchPartyOptions, RemovePartyOptions, PickupStopDeltaRow, CreatePickupStopOptions, PatchPickupStopOptions, DeletePickupStopOptions, ReorderPickupStopsOptions, AssignPickupTravellerOptions, PickupsResource, BoardPickupTravellerOptions, CorrectPickupBoardStatusOptions, ClosePickupStopOptions, ReopenPickupStopOptions, ReadManifestByPickupOptions, SeatingVehicleDeltaRow, SeatingOccupant, AssignSeatingOptions, AutoAssignSeatingOptions, SeatingResource, CreateSeatingVehicleOptions, PatchSeatingVehicleOptions, DeleteSeatingVehicleOptions, LinkSeatingManagerOptions, UnlinkSeatingManagerOptions, CloseoutResource, SaveCloseoutHandoverOptions, LockCloseoutOptions, UnlockCloseoutOptions, ExportCloseoutPackOptions, KaafilBinaryResponse, ManagerOwnTripsResponse, ManagerTodayResponse, NotificationsResource } from 'kaafil-js/client';
+import { h as ErrorClassification, D as DomainHookResult } from './useVendors-DXOuZWhZ.js';
+
+/** The live half of `PartyDeltaRow` — this hook never sends `since`, so no
+ * tombstone member is ever returned; see this file's header. */
+type PartyRow = Exclude<PartyDeltaRow, {
+    readonly _tombstone: true;
+}>;
+/** One row of `travellers.listForTrip()` — the trip's manifest, the search
+ * space `PartyEditor`'s member picker filters client-side. See this file's
+ * header for why this is not a `q`-parameterised search. */
+type PartiesTripRosterRow = Awaited<ReturnType<TravellersResource['listForTrip']>>[number];
+type AddPartyInput = Omit<AddPartyOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type PatchPartyInput = Omit<PatchPartyOptions, 'tripRef' | 'signal'>;
+type RemovePartyInput = Omit<RemovePartyOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+/** The live-fetched party list — see this file's header for why this is a
+ * live read rather than a snapshot subscription. Same `loaded`/
+ * `lastFetchFailed`/`fetchedAt`/`refresh` contract `RoomingUnassignedPool`
+ * and `TrekBoardState` already establish for this shape. */
+interface PartiesListState {
+    readonly rows: readonly PartyRow[];
+    readonly loaded: boolean;
+    readonly lastFetchFailed: boolean;
+    readonly fetchedAt: string | undefined;
+    readonly refresh: () => Promise<void>;
+}
+/** The trip's traveller manifest — the member picker's search space. */
+interface PartiesTripRosterState {
+    readonly rows: readonly PartiesTripRosterRow[];
+    readonly loaded: boolean;
+    readonly lastFetchFailed: boolean;
+    readonly fetchedAt: string | undefined;
+    readonly refresh: () => Promise<void>;
+}
+interface PartiesReady {
+    readonly list: PartiesListState;
+    readonly tripRoster: PartiesTripRosterState;
+    readonly add: (input: AddPartyInput) => Promise<OutboxOp>;
+    readonly patch: (input: PatchPartyInput) => Promise<OutboxOp>;
+    readonly remove: (input: RemovePartyInput) => Promise<OutboxOp>;
+}
+/**
+ * `parties` has no capability triple to resolve, so this union carries no
+ * `'dark'` member (contrast `DomainHookResult`, `../types/domain.types.ts`,
+ * which every OTHER §3 domain hook returns). `'loading'` covers the window
+ * before the first `list` fetch settles; `'error'` is reserved for that
+ * first fetch failing outright (a later `refresh()` failure instead flips
+ * `list.lastFetchFailed`/`tripRoster.lastFetchFailed`, matching the "loaded
+ * once, stay usable" contract those two states already carry elsewhere in
+ * this package).
+ */
+type PartiesResult = {
+    readonly status: 'loading';
+} | ({
+    readonly status: 'ready';
+} & PartiesReady) | {
+    readonly status: 'error';
+    readonly error: ErrorClassification;
+    /** Re-runs the failed initial fetch — a composite's only retry
+     * affordance while `status` is `'error'` (there is no `list.refresh`
+     * to reach for yet, since the `'ready'` branch hasn't happened). */
+    readonly retry: () => Promise<void>;
+};
+declare function useParties(tripRef: string): PartiesResult;
+
+type CreateStopInput = Omit<CreatePickupStopOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type PatchStopInput = Omit<PatchPickupStopOptions, 'tripRef' | 'signal'>;
+type RemoveStopInput = Omit<DeletePickupStopOptions, 'tripRef' | 'signal'>;
+type ReorderStopsInput = Omit<ReorderPickupStopsOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type AssignInput$1 = Omit<AssignPickupTravellerOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+/** Derived off the resource method, not imported — see this file's header. */
+type ReassignInput = Omit<Parameters<PickupsResource['reassign']>[0], 'tripRef' | 'idempotencyKey' | 'signal'>;
+type BoardInput = Omit<BoardPickupTravellerOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type CorrectBoardStatusInput = Omit<CorrectPickupBoardStatusOptions, 'tripRef' | 'signal'>;
+type CloseStopInput = Omit<ClosePickupStopOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type ReopenStopInput = Omit<ReopenPickupStopOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type ManifestInput = Omit<ReadManifestByPickupOptions, 'tripRef' | 'signal'>;
+/** `Awaited<ReturnType<...>>` off the resource method — `ManifestByPickup
+ * Response`/`ReassignResponse`/`BoardResponse`/`AssignResponse`/
+ * `CloseResponse`/`ReopenResponse` are not individually re-exported by name
+ * from `kaafil-js/client`'s public surface (only the nine `*Options` input
+ * types and `PickupStopDeltaRow` are — verified), so every result type below
+ * is derived structurally off `PickupsResource`, the one type that IS
+ * exported, rather than invented or widened to `unknown`. */
+type PickupManifestResult = Awaited<ReturnType<PickupsResource['manifestByPickup']>>;
+type PickupReassignResult = Awaited<ReturnType<PickupsResource['reassign']>>;
+interface PickupsReady {
+    readonly stops: readonly PickupStopDeltaRow[];
+    readonly syncedAt: string | undefined;
+    /**
+     * Re-reads the live lane after a write. A NO-OP on a field device, where
+     * the outbox drain already emits `snapshot.updated` and the cache-first
+     * read re-renders itself — calling it there costs nothing and means a
+     * composite does not have to know which lane it is on.
+     */
+    readonly refreshLive: () => Promise<void>;
+    readonly create: (input: CreateStopInput) => Promise<OutboxOp | null>;
+    readonly patch: (input: PatchStopInput) => Promise<OutboxOp | null>;
+    readonly remove: (input: RemoveStopInput) => Promise<OutboxOp | null>;
+    readonly reorder: (input: ReorderStopsInput) => Promise<OutboxOp | null>;
+    readonly assign: (input: AssignInput$1) => Promise<OutboxOp | null>;
+    /** `pickups.reassign` — moves every live, not-yet-boarded traveller off
+     * one stop onto a sibling stop of the same kind in one call
+     * (`FRD §8`'s "delete a stop with travellers on it" flow). Not enqueued
+     * through the outbox like the other writes here — its response
+     * (`movedCount`/`skippedBoardedCount`/both rebased stops) is needed
+     * synchronously by the calling composite to render the outcome, the same
+     * `autoAssign`-shaped exception `useRooming.ts`'s header documents. */
+    readonly reassign: (input: ReassignInput) => Promise<PickupReassignResult>;
+    /** Manager-only origination — an eyewitness statement
+     * (`06-capability-and-personas.md §7`'s canonical `✏️` case). */
+    readonly board: (input: BoardInput) => Promise<OutboxOp>;
+    /** manager/apiKey/agencyAdmin correction of an existing board record —
+     * never a relaxed version of `board`, and refused
+     * `422 pickups.correctionRequiresObservation` on a still-`PENDING` row.
+     * Not `If-Match`-guarded on the wire (`pickups.ts`'s own doc comment) —
+     * no `version`/`ifMatch` on this input, unlike the other stop writes. */
+    readonly correctBoardStatus: (input: CorrectBoardStatusInput) => Promise<OutboxOp | null>;
+    readonly close: (input: CloseStopInput) => Promise<OutboxOp>;
+    readonly reopen: (input: ReopenStopInput) => Promise<OutboxOp>;
+    /** Live read, not cache-first — see this file's header. */
+    readonly manifestByPickup: (input?: ManifestInput) => Promise<PickupManifestResult>;
+}
+/**
+ * PERSONALIZED mode-dark. Returns `{ status: 'dark', reason }` before any
+ * fetch when the `'pickup-points'` capability triple isn't `lit`
+ * (`06-capability-and-personas.md §3`).
+ */
+declare function usePickups(tripRef: string): DomainHookResult<PickupsReady>;
+
+type AssignInput = Omit<AssignSeatingOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type AutoAssignInput = Omit<AutoAssignSeatingOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type CreateVehicleInput = Omit<CreateSeatingVehicleOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type PatchVehicleInput = Omit<PatchSeatingVehicleOptions, 'tripRef' | 'signal'>;
+type RemoveVehicleInput = Omit<DeleteSeatingVehicleOptions, 'tripRef' | 'signal'>;
+type LinkManagerInput = Omit<LinkSeatingManagerOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type UnlinkManagerInput = Omit<UnlinkSeatingManagerOptions, 'tripRef' | 'signal'>;
+/**
+ * The unassigned-traveller roster — `SeatingBoardResponse.unassignedPool[]`
+ * (`kaafil-js/openapi/openapi.json`, verified). See this file's header for
+ * why it is its own live-fetch state rather than folded into `vehicles`.
+ */
+interface SeatingUnassignedPool {
+    readonly travellers: readonly SeatingOccupant[];
+    /** `true` once at least one `client.seating.read()` call has settled
+     * (success or failure). */
+    readonly loaded: boolean;
+    /** `true` when the MOST RECENT fetch threw — rendered differently from
+     * `travellers: [], loaded: true`; those are never the same state. */
+    readonly lastFetchFailed: boolean;
+    /** The server time (`meta.serverTime`) of the last successful fetch. */
+    readonly fetchedAt: string | undefined;
+    /** Re-runs the live read. `assign` already calls this on its own
+     * success; a composite calls it again after any other action that can
+     * move someone in or out of the pool (e.g. a vehicle delete releasing
+     * its occupants). */
+    readonly refresh: () => Promise<void>;
+}
+interface SeatingReady {
+    readonly vehicles: readonly SeatingVehicleDeltaRow[];
+    readonly syncedAt: string | undefined;
+    readonly unassignedPool: SeatingUnassignedPool;
+    /** 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>;
+    readonly assign: (input: AssignInput) => Promise<OutboxOp | null>;
+    readonly autoAssign: (input: AutoAssignInput) => ReturnType<SeatingResource['autoAssign']>;
+    readonly createVehicle: (input: CreateVehicleInput) => Promise<OutboxOp | null>;
+    readonly patchVehicle: (input: PatchVehicleInput) => Promise<OutboxOp | null>;
+    readonly removeVehicle: (input: RemoveVehicleInput) => Promise<OutboxOp | null>;
+    /** The one day-coverage write this hook exposes — a whole-array replace,
+     * never a per-day CRUD method. See this file's header `DECISION` for why
+     * this takes no `version` parameter. */
+    readonly patchVehicleDays: (vehicleRef: string, days: readonly number[]) => Promise<OutboxOp | null>;
+    readonly linkManager: (input: LinkManagerInput) => Promise<OutboxOp | null>;
+    readonly unlinkManager: (input: UnlinkManagerInput) => Promise<OutboxOp | null>;
+}
+/**
+ * PERSONALIZED mode-dark. Returns `{ status: 'dark', reason }` before any
+ * fetch when the `'transport-seating'` capability triple isn't `lit`
+ * (`06-capability-and-personas.md §3`).
+ */
+declare function useSeating(tripRef: string): DomainHookResult<SeatingReady>;
+
+type CloseoutGetResult = Awaited<ReturnType<CloseoutResource['get']>>;
+/** The whole closing-day aggregate, verbatim off the wire
+ * (`CloseoutAggregateResponse`, `kaafil-js/src/generated/schema.d.ts`) plus
+ * the envelope's own `meta`. Indexed-access off the real SDK return type
+ * rather than restated, per this file's own convention (`useItinerary.ts`'s
+ * `ItineraryReadResult`, `useRooming.ts`'s `RoomingStayWindowRow`). */
+type CloseoutAggregate = CloseoutGetResult;
+/** One row of `CloseoutAggregate['blockers']` — what is still open, and
+ * which screen clears it (`actionKey`). The inventory is closed at eleven
+ * keys; a twelfth is a spec change, not a release. */
+type CloseoutBlockerRow = CloseoutAggregate['blockers'][number];
+type SaveCloseoutHandoverInput = Omit<SaveCloseoutHandoverOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type LockCloseoutInput = Omit<LockCloseoutOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type UnlockCloseoutInput = Omit<UnlockCloseoutOptions, 'tripRef' | 'idempotencyKey' | 'signal'>;
+type ExportCloseoutPackInput = Omit<ExportCloseoutPackOptions, 'tripRef' | 'signal'>;
+interface CloseoutReady {
+    /** `undefined` until the first `closeout.get()` has settled — never a
+     * fabricated empty aggregate (`RoomingReady.unassignedPool`'s own
+     * discipline, applied here). */
+    readonly aggregate: CloseoutAggregate | undefined;
+    /** `true` once the first `closeout.get()` has settled (success or
+     * failure) — distinguishes "never fetched yet" from "fetched, and this
+     * trip is genuinely clean" (`ItineraryReady.loaded`'s own contract). */
+    readonly loaded: boolean;
+    /** `true` when the MOST RECENT fetch threw. `loaded`/`aggregate` stay
+     * whatever they already were; only this flips (mirrors
+     * `RoomingReady.unassignedPool.lastFetchFailed`). */
+    readonly lastFetchFailed: boolean;
+    readonly syncedAt: string | undefined;
+    /** Re-runs the live read. Every write below already calls this on its own
+     * success (`recordChangedSince`'s own header note: a write's response is
+     * already the freshest possible aggregate, but `refresh()` still exists
+     * for a caller that wants to re-poll independently of a write, e.g. after
+     * a deep-linked blocker screen clears one elsewhere). */
+    readonly refresh: () => Promise<void>;
+    /** `expectedVersion` REQUIRED (`SaveCloseoutHandoverRequest`) — read it
+     * off `aggregate.handover.version`. A stale one is answered `409
+     * CONFLICT_VERSION`. Not offline-queued — see this file's header. */
+    readonly saveHandover: (input: SaveCloseoutHandoverInput) => Promise<CloseoutAggregate>;
+    /** `expectedVersion` optional — `canLock` is re-derived inside the request
+     * regardless, so a stale client-side `true` never wins. Not
+     * offline-queued — see this file's header. */
+    readonly lock: (input?: LockCloseoutInput) => Promise<CloseoutAggregate>;
+    /** `apiKeyAuth`-only on the wire — see this file's header. Calling it from
+     * any browser persona this hook serves throws `UnsatisfiableSchemeError`
+     * before any request is sent. No composite in this build calls it. */
+    readonly unlock: (input: UnlockCloseoutInput) => Promise<CloseoutAggregate>;
+    /** Returns bytes, not an envelope — see `CloseoutResource.exportPdf`'s own
+     * doc comment. No composite in this build's `closing-day` module calls
+     * this (`04-closing-day.md §ClosingDayScreen`'s own `Does NOT`). */
+    readonly exportPdf: (input?: ExportCloseoutPackInput) => Promise<KaafilBinaryResponse>;
+}
+/**
+ * PERSONALIZED mode-dark. Returns `{ status: 'dark', reason }` before any
+ * fetch when the `'closing-day'` capability triple isn't `lit`
+ * (`04-closing-day.md`'s own `Gating`). `manager`/`agencyAdmin` both call
+ * this same hook — the spec's `COORDINATOR`-role read-only resolution
+ * happens on the open session server-side, never as a UIKit prop or a
+ * second hook (`useItinerary.ts`'s identical note for its own module).
+ */
+declare function useCloseout(tripRef: string): DomainHookResult<CloseoutReady>;
+
+/** `useStaleness()`'s return shape (`08-core-hooks.md §2.4`). */
+interface StalenessState {
+    readonly syncedAt: string | undefined;
+    readonly ageSeconds: number | undefined;
+    readonly isStale: boolean;
+}
+/**
+ * One entry of `useConflicts()`'s `conflicts` array (`08-core-hooks.md
+ * §2.7`). `queuedValue` is the parked op's own queued body; `currentValue`
+ * is the fresh server row the reconciler already wrote back into the
+ * snapshot before parking (`kaafil-js/src/offline/reconcile.ts`, verified) —
+ * this hook reads it from there rather than the park record itself, which
+ * carries no row, only `{ status, code, userMessage }`
+ * (`kaafil-js/src/offline/outbox.ts`'s `OutboxParkReason`, verified).
+ */
+interface ConflictRecord {
+    readonly opId: string;
+    readonly entity: string;
+    readonly queuedValue: unknown;
+    readonly currentValue: unknown;
+}
+/** `useOutboxStatus()`'s return shape (`08-core-hooks.md §2.9`). */
+interface OutboxState {
+    readonly pending: number;
+    readonly parked: number;
+    readonly lanes: readonly string[];
+    readonly isOnline: boolean;
+}
+/**
+ * The six-event map `useOfflineEvent()` is typed over (`08-core-hooks.md
+ * §2.6`), verified against `kaafil-js/src/offline/events.ts`'s
+ * `OfflineEventMap` this session — exactly these six, no more, no fewer.
+ */
+type SyncEventKind = 'sync.drained' | 'sync.error' | 'session.expired' | 'share.expired' | 'share.revoked' | 'snapshot.updated';
+
+interface ManagerMeLoading {
+    readonly status: 'loading';
+}
+interface ManagerMeError {
+    readonly status: 'error';
+}
+interface ManagerMeReady extends ManagerOwnTripsResponse {
+    readonly status: 'ready';
+    /** The server timestamp this read landed with (`meta.serverTime`) — never
+     * a local clock read (hard rule #6). */
+    readonly syncedAt: string;
+}
+type ManagerMeResult = ManagerMeLoading | ManagerMeError | ManagerMeReady;
+/**
+ * `client.managerMe.listTrips()` behind a plain fetch-on-mount effect —
+ * this read takes no parameter (it resolves entirely off the authenticated
+ * principal, `manager-me.routes.ts`'s own header, cited), so it never
+ * re-fetches on a prop change the way `useManagerToday(tripRef)` does.
+ * A caller wanting "refresh now" re-mounts this hook's owning component.
+ */
+declare function useManagerMe(): ManagerMeResult;
+
+interface ManagerTodayLoading {
+    readonly status: 'loading';
+}
+interface ManagerTodayError {
+    readonly status: 'error';
+}
+type ManagerTodayReady = ManagerTodayResponse & {
+    readonly status: 'ready';
+    /** The server timestamp this read landed with (`meta.serverTime`) —
+     * never a local clock read (hard rule #6). */
+    readonly syncedAt: string;
+};
+type ManagerTodayResult = ManagerTodayLoading | ManagerTodayError | ManagerTodayReady;
+/**
+ * `client.managerToday.read({ tripRef })` behind a plain fetch-on-mount/
+ * fetch-on-`tripRef`-change effect. Re-fetches whenever `tripRef` changes;
+ * never re-fetches on an interval or a focus event of its own — a caller
+ * that wants "refresh now" re-mounts this hook's owning component or (once
+ * this hook grows one) calls a future `refresh()` return field.
+ */
+declare function useManagerToday(tripRef: string): ManagerTodayResult;
+
+type NotificationListResponse = Awaited<ReturnType<NotificationsResource['list']>>;
+type NotificationListItem = NotificationListResponse['items'][number];
+/** The live-row half of `NotificationListItem`'s union — a tombstone never
+ * reaches a caller of this hook (see this file's own header). */
+type ManagerNotification = Exclude<NotificationListItem, {
+    _tombstone: true;
+}>;
+interface NotificationsLoading {
+    readonly status: 'loading';
+}
+interface NotificationsError {
+    readonly status: 'error';
+}
+interface NotificationsReady {
+    readonly status: 'ready';
+    readonly notifications: readonly ManagerNotification[];
+    /** `notifications.filter((n) => n.readAt === null).length` — the wire
+     * carries no numeric unread field of its own (verified against
+     * `NotificationListResponse`), so this is a real derivation off real
+     * rows, never a fabricated count. */
+    readonly unreadCount: number;
+    readonly markRead: (id: string) => Promise<void>;
+    /** The server timestamp this read landed with (`meta.serverTime`) —
+     * never a local clock read (hard rule #6). */
+    readonly syncedAt: string;
+}
+type NotificationsResult = NotificationsLoading | NotificationsError | NotificationsReady;
+declare function useNotifications(): NotificationsResult;
+
+export { type ConflictRecord as C, type ManagerMeReady as M, type NotificationsReady as N, type OutboxState as O, type PartiesReady as P, type StalenessState as S, type CloseoutReady as a, type ManagerMeResult as b, type ManagerNotification as c, type ManagerTodayReady as d, type ManagerTodayResult as e, type NotificationsResult as f, type PickupsReady as g, type SeatingReady as h, type SyncEventKind as i, useManagerMe as j, useManagerToday as k, useNotifications as l, useParties as m, usePickups as n, useSeating as o, type CloseoutBlockerRow as p, type PickupManifestResult as q, type CloseoutAggregate as r, type PartiesTripRosterRow as s, useCloseout as u };