@everfur/sdk 0.1.0 → 0.3.0

package/dist/ports-BN6RHF9W.d.cts

@@ -0,0 +1,48 @@
+/** Opaque handle to a local file to upload. Server-owned upload target is defined by records/video specs. */
+interface FileHandle {
+    /** Local file URI. */
+    readonly uri: string;
+    readonly mimeType: string;
+    readonly sizeBytes?: number;
+    /** Original file name, when the host has one. */
+    readonly name?: string;
+    /**
+     * The bytes themselves, for a host that holds them in memory rather than at a dereferenceable `uri` (a
+     * browser `File`). Additive: a native host leaves it unset and uploads from `uri`. A web host sets `uri`
+     * to a marker that is never fetched, and never mints an object URL for the file (records are PHI).
+     */
+    readonly blob?: Blob;
+}
+/**
+ * Presigned PUT upload. `idempotencyKey` is reused on every retry (a re-uploaded identical file dedupes
+ * server-side). `signal` cancels an in-flight upload. Settles at the controller; this port itself may reject,
+ * which the controller normalizes to a typed EverfurError.
+ */
+interface FilePort {
+    presignedPut(file: FileHandle, opts: {
+        readonly idempotencyKey: string;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+interface UploadPolicyWire {
+    readonly upload_id: string;
+    readonly upload_url: string;
+    readonly upload_fields: Readonly<Record<string, string>>;
+    readonly expires_in_seconds: number;
+    readonly max_content_length: number;
+}
+/**
+ * Platform-specific: the rn adapter binds `expo-file-system` (uploadAsync) behind `optionalModule`; the
+ * controller stays platform-neutral and never sees a native module. Resolves on S3's 204; rejects on a
+ * policy 403 / stream failure, which the controller normalizes to a typed `mediaUploadFailed` (never a throw
+ * that escapes the controller).
+ */
+interface UploadTransport {
+    postMultipart(policy: UploadPolicyWire, file: FileHandle, opts: {
+        readonly onProgress?: (fraction: number) => void;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+export type { FileHandle as F, UploadTransport as U, UploadPolicyWire as a, FilePort as b };

package/dist/ports-BN6RHF9W.d.ts

@@ -0,0 +1,48 @@
+/** Opaque handle to a local file to upload. Server-owned upload target is defined by records/video specs. */
+interface FileHandle {
+    /** Local file URI. */
+    readonly uri: string;
+    readonly mimeType: string;
+    readonly sizeBytes?: number;
+    /** Original file name, when the host has one. */
+    readonly name?: string;
+    /**
+     * The bytes themselves, for a host that holds them in memory rather than at a dereferenceable `uri` (a
+     * browser `File`). Additive: a native host leaves it unset and uploads from `uri`. A web host sets `uri`
+     * to a marker that is never fetched, and never mints an object URL for the file (records are PHI).
+     */
+    readonly blob?: Blob;
+}
+/**
+ * Presigned PUT upload. `idempotencyKey` is reused on every retry (a re-uploaded identical file dedupes
+ * server-side). `signal` cancels an in-flight upload. Settles at the controller; this port itself may reject,
+ * which the controller normalizes to a typed EverfurError.
+ */
+interface FilePort {
+    presignedPut(file: FileHandle, opts: {
+        readonly idempotencyKey: string;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+interface UploadPolicyWire {
+    readonly upload_id: string;
+    readonly upload_url: string;
+    readonly upload_fields: Readonly<Record<string, string>>;
+    readonly expires_in_seconds: number;
+    readonly max_content_length: number;
+}
+/**
+ * Platform-specific: the rn adapter binds `expo-file-system` (uploadAsync) behind `optionalModule`; the
+ * controller stays platform-neutral and never sees a native module. Resolves on S3's 204; rejects on a
+ * policy 403 / stream failure, which the controller normalizes to a typed `mediaUploadFailed` (never a throw
+ * that escapes the controller).
+ */
+interface UploadTransport {
+    postMultipart(policy: UploadPolicyWire, file: FileHandle, opts: {
+        readonly onProgress?: (fraction: number) => void;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+export type { FileHandle as F, UploadTransport as U, UploadPolicyWire as a, FilePort as b };

package/dist/ports-DEBzEhbp.d.cts

@@ -0,0 +1,386 @@
+import { R as RequestFunnel } from './requestFunnel-L-BQfi0z.cjs';
+import { C as CheckinAnswer, a as CheckinOutcome } from './casesRepository-DHwtGRYY.cjs';
+import { A as AuthContext } from './identity-DI4eVx9S.cjs';
+import { E as EverfurError, c as EverfurResult } from './EverfurResult-DN9pL2Ab.cjs';
+import { P as PetRef, C as ConversationId, b as ResponseId } from './ids-B2GAAifq.cjs';
+import { i as UrgencyLevel, F as Frame } from './config-CzTZGlfF.cjs';
+import { E as ErrorPolicyPort } from './ErrorPolicyPort-CNf4uQZP.cjs';
+import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.cjs';
+import { F as FileHandle } from './ports-BN6RHF9W.cjs';
+
+/** Injectable timers so the watchdog + deadlines are testable with a fake clock (no direct setTimeout). */
+interface Timers$1 {
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+
+/** User-scoped history. Titles are restricted data; keep them out of logs and persistent storage. */
+interface ChatConversation {
+    readonly id: ConversationId;
+    readonly title: string | null;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /**
+     * Unread assistant messages for the calling user (`unread_message_count`), for a badge. null when the wire
+     * did not carry it, which means the server does not speak unread, never "all read".
+     */
+    readonly unreadCount: number | null;
+}
+interface ChatHistoryOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+interface ChatConversationListOptions extends ChatHistoryOptions {
+    readonly petRef?: PetRef;
+}
+interface ChatConversationPage {
+    readonly conversations: readonly ChatConversation[];
+    readonly nextCursor: string | null;
+}
+/** Each page is chronological; nextCursor loads the older window, to prepend rather than append. */
+interface ChatMessagePage {
+    readonly messages: readonly ChatMessage[];
+    readonly nextCursor: string | null;
+}
+
+/**
+ * The answerable check-in behind an assistant message, derived from its `proactiveOriginRef` and kept up to date
+ * by `ChatController.answerCheckin`. `answer` is the answer on record for this session (null while unanswered);
+ * `resolutionText` is the server's own post-answer line when it sent one.
+ */
+interface ChatCheckin {
+    readonly caseId: string;
+    readonly answer: CheckinAnswer | null;
+    readonly resolutionText: string | null;
+    /**
+     * The case's lifecycle status as last known (`watching` while open, then `resolved`, `escalated`, `lapsed`),
+     * null while UNKNOWN. The server accepts an answer only while the case is watching, so a surface draws no
+     * answer row for any other known status: leaving one tappable produced a 404 that reads to the owner as
+     * "your answer did not save". Unknown does NOT lock, so a surface that cannot read the status keeps exactly
+     * the behaviour it had before this existed.
+     */
+    readonly status: string | null;
+}
+/** The one status that still takes an answer (the consumer's `ANSWERABLE_STATUS`). */
+declare const CHECKIN_ANSWERABLE_STATUS = "watching";
+/** True when the case will no longer take an answer, so the surface draws no answer row. */
+declare function isCheckinSettled(checkin: ChatCheckin): boolean;
+
+type ChatStatus = 'idle' | 'streaming' | 'complete' | 'error';
+/** Opaque citation record (DoneFrame.citations shape). Rendered by the UI layer, never trusted for logic. */
+type Citation = Readonly<Record<string, unknown>>;
+interface ChatMessage {
+    /** Stable list key: a client id for a user turn, the responseId for a finalized assistant turn. */
+    readonly id: string;
+    readonly role: 'user' | 'assistant';
+    readonly text: string;
+    /**
+     * ISO 8601. A history row carries the server's `created_at`; an optimistic user turn and a streamed reply
+     * are stamped from the controller clock when the row is created, and the stamp survives the reply's
+     * finalize. Rendered by the message footer as the app does (`toLocaleTimeString`, hour and minute).
+     */
+    readonly createdAt: string;
+    readonly citations?: readonly Citation[];
+    readonly responseId?: ResponseId;
+    /** Optimistic user bubble; removed if the turn fails BEFORE the first delta. */
+    readonly pending?: boolean;
+    /** Server classification, never inferred by the SDK from message text. */
+    readonly urgencyLevel?: UrgencyLevel | null;
+    readonly urgencyReason?: string | null;
+    /**
+     * True when the done frame carried the urgency slot (`DoneFrame.urgencyProvided`): with `urgencyLevel`
+     * null it means the server classified the turn as informational, which the surfaces show as the calm
+     * "Good to know" tier. Absent on user turns, on history rows and on a turn the server never classified.
+     */
+    readonly urgencyProvided?: boolean;
+    /**
+     * The platform's occasion marker on a message it wrote itself (`checkin:<case_id>:<YYYY-MM-DD>` for a
+     * follow-up check-in), verbatim from the wire. Absent on ordinary turns.
+     */
+    readonly proactiveOriginRef?: string;
+    /** The answerable check-in behind this message, when `proactiveOriginRef` names one (see `answerCheckin`). */
+    readonly checkin?: ChatCheckin;
+}
+interface ChatSnapshot {
+    readonly status: ChatStatus;
+    /** [] => Empty state; length > 0 => Populated. */
+    readonly messages: readonly ChatMessage[];
+    /** nulled on a 404 before recreate. */
+    readonly conversationId: ConversationId | null;
+    /** present iff status === 'error'; NEVER thrown. */
+    readonly error: EverfurError | null;
+    readonly isStreaming: boolean;
+    /** true during the initial conversation prime => Loading. */
+    readonly isBootstrapping: boolean;
+    /** Opaque cursor for older messages in the active conversation, not a forward-page cursor. */
+    readonly historyCursor?: string | null;
+    readonly isLoadingHistory?: boolean;
+    /**
+     * The last turn was STOPPED by the owner before its first delta, so the message they typed is on screen with
+     * no answer under it and nothing said about why. Not an error (nothing failed), which is why it is its own
+     * flag: a surface renders the consumer app's `Response stopped` notice with a retry, and the next send,
+     * retry or thread change clears it.
+     */
+    readonly stopped?: boolean;
+    /**
+     * The turn in flight is being RE-ATTEMPTED by the controller with nothing asked of the owner: the mid-stream
+     * token refresh replay, or the one recreate-and-resend after the conversation went missing. The consumer app
+     * shows its `Reconnecting\u2026` caption for exactly this (`streamStatus === 'reconnecting'`, set from the
+     * stream registry's `recovering`). Cleared by the turn settling either way, by `stop()` and by a thread
+     * change. Optional on the type for the same reason `stopped` is: it was added to a shipped interface.
+     */
+    readonly reconnecting?: boolean;
+    /**
+     * Flattened, de-duplicated suggested-prompt strings (backend-owned copy). After a reply they are THAT reply's
+     * `follow_up_questions` from the done frame; a reply that carries none falls back to the bootstrap set
+     * (empty until the bootstrap resolves, empty when the backend returns none). The UI renders these as the
+     * tappable "Follow up questions" list; each string is a ready-to-send message.
+     */
+    readonly suggestedPrompts: readonly string[];
+    /**
+     * Unread assistant messages in the active thread, for a badge: the count the conversation list last
+     * reported for it (`unread_message_count`), 0 once `markRead()` settles. null while unknown, which is also
+     * what a server that does not speak unread leaves it at; never read null as "all read".
+     */
+    readonly unreadCount: number | null;
+    /**
+     * CRN-01. Does ANY thread this controller has listed still carry unread assistant messages? The header's
+     * dot, answerable without the history drawer ever being opened, because the chat bootstrap reads the head
+     * of the list on mount. False while nothing has been listed and against a server that does not speak
+     * unread, which is the same thing the dot already means: nothing to show.
+     */
+    readonly hasUnreadThreads?: boolean;
+}
+interface SendOptions {
+    readonly conversationId?: ConversationId;
+    readonly petRef?: PetRef;
+    readonly signal?: AbortSignal;
+    readonly idempotencyKey?: string;
+    /**
+     * The S3 keys of images already staged through `core/chat/attachments` (`POST /widget/v1/uploads/initiate`,
+     * then the multipart upload), sent as `image_s3_keys`. At most `MAX_IMAGE_KEYS_PER_MESSAGE`; the server
+     * checks each key is the caller's own. The message text is still required.
+     */
+    readonly imageS3Keys?: readonly string[];
+}
+/** The server's cap on `image_s3_keys` per message (`SendWidgetMessageRequest`, mirrored from the consumer send). */
+declare const MAX_IMAGE_KEYS_PER_MESSAGE = 5;
+/**
+ * The feedback a reader records on an assistant message (`POST /widget/v1/messages/{message_id}/feedback`,
+ * the consumer `MessageFeedbackType` enum): the three sentiments the thumbs record on tap, and the reasons the
+ * not-helpful sheet upgrades a thumbs-down to.
+ */
+type ChatFeedbackType = 'helpful' | 'neutral' | 'not_helpful' | 'wrong' | 'outdated' | 'dangerous' | 'unclear';
+/** Every `ChatFeedbackType`, for a validator or a picker. */
+declare const CHAT_FEEDBACK_TYPES: readonly ChatFeedbackType[];
+/** The server's cap on the free-text `notes` (`notes: Field(None, max_length=4000)`). */
+declare const FEEDBACK_NOTES_MAX_CHARS = 4000;
+/** What a recorded feedback settles to: the server's row id. */
+interface ChatFeedbackReceipt {
+    readonly feedbackId: string;
+}
+/**
+ * What a check-in tap is about: the `case` target of an Everfur push
+ * (src/core/notifications/parse.ts `EverfurNotificationTarget`), which carries the conversation id when the
+ * platform knew it and only the pet when it did not. Both optional, so a host that has just the pet (a
+ * deep link, a home-screen card) passes what it has.
+ */
+interface ChatCheckinTarget {
+    readonly conversationId?: ConversationId | null;
+    readonly petRef?: PetRef | null;
+}
+interface ChatHandlers {
+    onFrame(frame: Frame): void;
+    onDone(responseId: ResponseId | null): void;
+    onError(error: EverfurError): void;
+}
+/** A suggested-prompt category returned by the prompts bootstrap endpoint. */
+interface SuggestedPromptCategory {
+    readonly category: string;
+    readonly prompts: readonly string[];
+}
+interface ChatControllerDeps {
+    /** Device auth context (bearer-XOR-pk precedence + lazy token). Carries the TransportPort. */
+    readonly auth: AuthContext;
+    readonly telemetry?: TelemetryPort;
+    readonly errorPolicy?: ErrorPolicyPort;
+    readonly timers?: Timers$1;
+    /** Injected RNG for deterministic backoff in tests. */
+    readonly rng?: () => number;
+    /** Injected id factory (client message ids) for deterministic tests. */
+    readonly newId?: () => string;
+    /** Injected idempotency-key factory for the TURN identity (see `buildSendRequest`). */
+    readonly makeIdempotencyKey?: () => string;
+    /** The ONE request funnel. Built from `auth` when absent; injected in tests for a deterministic clock. */
+    readonly funnel?: RequestFunnel;
+    readonly budget?: {
+        readonly idleMs?: number;
+        readonly overallMs?: number;
+    };
+    readonly initialConversationId?: ConversationId | null;
+    /** The pet this controller is scoped to (the registry's scope key), the pet a check-in answer is recorded against. */
+    readonly petRef?: PetRef | null;
+}
+interface ChatController {
+    /** useSyncExternalStore subscribe. Returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /** A stable frozen snapshot; identity changes only on real change. */
+    getSnapshot(): ChatSnapshot;
+    /** Stream a reply. The iterable ALWAYS completes cleanly; a failure is a terminal Frame, never a throw. */
+    send(text: string, opts?: SendOptions): AsyncIterable<Frame>;
+    /** Imperative escape hatch; returns a teardown, also torn down on dispose(). */
+    send(text: string, opts: SendOptions, handlers: ChatHandlers): () => void;
+    /**
+     * CRN-06. Ask a grounded question in a FRESH conversation: the thread on screen is left (its transcript
+     * clears and anything in flight is dropped), a new conversation is opened and `prompt` is the first turn
+     * in it. This is the consumer app's "Ask Everfur" handoff, whose whole point is that a question about one
+     * lab marker does not land in the middle of an unrelated thread
+     * (`useConsumerChatRouteHandoffs.ts`: `sendMessage(prompt, { forceFreshConversation: true })`).
+     *
+     * NOT GROUNDED ON THE WIRE YET. The consumer plane carries a `focus_ref` on conversation create, which
+     * orients the SYSTEM PROMPT at the entity the owner is looking at. `CreateWidgetConversationRequest`
+     * declares `title`, `pet_ref` and `pet` and nothing else, and it is a plain pydantic v2 model
+     * (`extra="ignore"`), so a `focus_ref` sent here would be discarded without a 422 and the SDK would be
+     * asserting a grounding that never happened. The prompt the records surfaces build already names the
+     * entity in words, which is what actually reaches the model today.
+     */
+    askEverfur(prompt: string, opts?: SendOptions): AsyncIterable<Frame>;
+    /** Re-send the last turn without a duplicate user bubble, reusing its idempotency key. */
+    retryLast(): AsyncIterable<Frame>;
+    /** Abort in-flight; not an error. Returns to pre-send (idle) and drops a never-answered optimistic bubble. */
+    stop(): void;
+    /** Idempotent. Aborts in-flight, bumps the epoch, drops listeners + handler subscriptions. */
+    dispose(): void;
+    /** Re-scope on user/pet switch: aborts in-flight and bumps the epoch so a late write drops. */
+    rescope(): void;
+    /** Bootstrap helper (§8): create a conversation. Unary, authed, settles. */
+    createConversation(opts?: {
+        readonly petRef?: PetRef;
+    }): Promise<EverfurResult<ConversationId>>;
+    /**
+     * Bootstrap helper (CRN-01): the whole "which thread does chat open in" decision, made HERE rather than in
+     * `bootstrapChat`, because the race guard that stops a send opening a second conversation lives here and
+     * has to cover the head read as well as the create. Reads the head of the pet's list (which is also what
+     * materializes a follow-up check-in the member is owed), resumes it when it carries unread assistant
+     * content, and otherwise creates exactly as `createConversation` did. Settles; never throws.
+     */
+    primeConversation(opts?: {
+        readonly petRef?: PetRef;
+    }): Promise<EverfurResult<ConversationId>>;
+    /** Bootstrap helper (§8): fetch the session's suggested prompts, optionally personalized to a pet. Settles; never throws. */
+    getPrompts(opts?: {
+        readonly petRef?: PetRef;
+    }): Promise<EverfurResult<readonly SuggestedPromptCategory[]>>;
+    /** Adopt (or clear) the active conversation id, e.g. after bootstrap primes one. */
+    adoptConversation(id: ConversationId | null): void;
+    /** Read a page of this user's conversations; optional petRef filters on the server. */
+    listConversations(opts?: ChatConversationListOptions): Promise<EverfurResult<ChatConversationPage>>;
+    /**
+     * CRN-01. Open the thread a follow-up check-in landed in: the conversation the push named, or, with only a
+     * pet, the HEAD of that pet's list. Reading the list is what materializes a check-in the member is owed
+     * (`widget_follow_ups_for_list`), so the pet-only form is not a lookup, it is the trigger. Settles to the
+     * conversation opened, or `ok(null)` when the member has no thread yet, which is not a failure: the empty
+     * chat they are already looking at is the right place for them to be. Never throws.
+     */
+    openCheckin(target?: ChatCheckinTarget): Promise<EverfurResult<ConversationId | null>>;
+    /** Read a chronological message window without changing the active conversation. */
+    getMessages(id: ConversationId, opts?: ChatHistoryOptions): Promise<EverfurResult<ChatMessagePage>>;
+    /** Switch threads and hydrate the latest message window. Clears the old thread immediately. */
+    resumeConversation(id: ConversationId): Promise<EverfurResult<void>>;
+    /** Prepend the next older window, preserving any replies sent while the page was loading. */
+    loadOlderMessages(): Promise<EverfurResult<void>>;
+    /**
+     * CRN-16. Re-read the active thread's NEWEST window and the pet's limit-1 conversation list, and merge
+     * what is new into the transcript. This is how a message the PLATFORM wrote (a follow-up check-in, a
+     * reminder) becomes visible on a plane with no websocket and no polling; the host decides when to call it
+     * by wiring a lifecycle port, and `decideChatRefresh` decides whether it may run. Non-destructive: rows
+     * already on screen keep their place and any older pages the reader scrolled back to are kept. A no-op
+     * without a thread and while a turn is in flight. Settles; never throws.
+     */
+    refreshActiveThread(): Promise<EverfurResult<void>>;
+    /**
+     * Adopt the suggested-prompt categories fetched by the bootstrap (§8): flattened + de-duplicated onto the
+     * snapshot's `suggestedPrompts` so the prebuilt UI can render the tappable follow-up list. Idempotent; a
+     * no-op when the flattened set is empty and none are shown.
+     */
+    adoptPrompts(categories: readonly SuggestedPromptCategory[]): void;
+    /**
+     * Record the owner's answer to a follow-up check-in (`POST /widget/v1/pets/{pet_ref}/cases/{case_id}/checkin`)
+     * against the scoped pet (or `opts.petRef`), and reflect it on the message carrying that case: `checkin.answer`
+     * and the server's `resolutionText`. A stale, closed or foreign case is the ordinary not-found error; without
+     * a pet it settles to `validationFailed` before any I/O. Never posts a message into the thread.
+     */
+    answerCheckin(caseId: string, answer: CheckinAnswer, opts?: {
+        readonly petRef?: PetRef;
+        readonly signal?: AbortSignal;
+    }): Promise<EverfurResult<CheckinOutcome>>;
+    /**
+     * Advance the caller's read watermark on the active thread (`POST /widget/v1/conversations/{id}/read`,
+     * idempotent) and zero `unreadCount`. Called for you when `resumeConversation` opens a thread the list reported
+     * unread; call it yourself when you opened the thread another way. A no-op without an active thread.
+     */
+    markRead(opts?: {
+        readonly signal?: AbortSignal;
+    }): Promise<EverfurResult<void>>;
+    /**
+     * Record the reader's feedback on an assistant message (`POST /widget/v1/messages/{message_id}/feedback`,
+     * body `{ feedback_type, notes? }`). The server upserts per reader, so a second call replaces the first.
+     * Only a message with a server `responseId` can be rated: a local id settles to `validationFailed` before
+     * any I/O, as do an unknown `feedbackType` and notes over `FEEDBACK_NOTES_MAX_CHARS`. Clearing a rating is
+     * local to the surface (the consumer app sends nothing for it). Settles `ok({ feedbackId })`; never throws.
+     */
+    submitFeedback(responseId: ResponseId, feedbackType: ChatFeedbackType, notes?: string | null, opts?: {
+        readonly signal?: AbortSignal;
+    }): Promise<EverfurResult<ChatFeedbackReceipt>>;
+}
+declare function createChatController(deps: ChatControllerDeps): ChatController;
+/**
+ * The server's own limits on a chat message, mirrored here so a violation is caught before any UI is
+ * rendered for it. `SendWidgetMessageRequest.message` on EFBackend main declares
+ * `min_length=1, max_length=4000`; the server remains authoritative and still enforces both.
+ *
+ * These are NOT in the generated contract projection, so they are pinned here with their source rather
+ * than derived. If the server relaxes either bound, this is the one place to update.
+ */
+declare const MESSAGE_MAX_CHARS = 4000;
+
+/** The presigned POST/PUT policy returned by `/uploads/initiate` (SPEC-11b §2.1). */
+interface PresignedPolicy {
+    /** Absolute S3 endpoint URL to POST/PUT the bytes at. */
+    readonly url: string;
+    /** POST-policy form fields to include with the upload (empty for a plain PUT). */
+    readonly fields: Readonly<Record<string, string>>;
+    /** The owned-uploads-prefixed key the analyze call then references. */
+    readonly s3Key: string;
+    /** epoch seconds the policy expires; telemetry only. */
+    readonly expiresAt: number | null;
+}
+/**
+ * The native upload seam. It PUTs `file` at the presigned `target` (SPEC-11b §2.1). `idempotencyKey` is reused
+ * on every retry so a re-uploaded identical file dedupes server-side. A network failure REJECTS; the controller
+ * normalizes that to a `mediaUploadFailed` and exposes a retake affordance (never auto-retried, SPEC-00 §3.2).
+ *
+ * NOTE: the spine `FilePort.presignedPut(file, { idempotencyKey, signal })` has no slot for the presigned
+ * target; this richer port is the shape it must grow to. See the manifest gap note.
+ */
+interface UploadPort {
+    presignedPut(file: FileHandle, opts: {
+        readonly target: PresignedPolicy;
+        readonly idempotencyKey: string;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+interface Timers {
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+/** The useSyncExternalStore contract the rn hooks bind to. */
+interface ReadableStore<S> {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): S;
+}
+
+export { type ChatCheckin as C, FEEDBACK_NOTES_MAX_CHARS as F, MAX_IMAGE_KEYS_PER_MESSAGE as M, type PresignedPolicy as P, type ReadableStore as R, type SendOptions as S, type Timers as T, type UploadPort as U, type ChatCheckinTarget as a, type ChatConversation as b, type ChatConversationListOptions as c, type ChatConversationPage as d, type ChatFeedbackReceipt as e, type ChatFeedbackType as f, type ChatHistoryOptions as g, type ChatMessagePage as h, type ChatMessage as i, type ChatStatus as j, type Citation as k, type SuggestedPromptCategory as l, type ChatController as m, CHAT_FEEDBACK_TYPES as n, CHECKIN_ANSWERABLE_STATUS as o, type ChatControllerDeps as p, type ChatHandlers as q, type ChatSnapshot as r, MESSAGE_MAX_CHARS as s, type Timers$1 as t, createChatController as u, isCheckinSettled as v };