@everfur/sdk 0.1.1 → 0.4.0

package/dist/attachments-BorG422I.d.cts

@@ -0,0 +1,146 @@
+import { E as EverfurError } from './EverfurResult-DN9pL2Ab.cjs';
+import { R as RequestFunnel } from './requestFunnel-BjDpqqvm.cjs';
+import { F as FileHandle, U as UploadTransport, a as UploadPolicyWire } from './ports-BN6RHF9W.cjs';
+import { R as ReadableStore, T as Timers } from './ports-BY2ph0_y.cjs';
+
+/** The image MIME types the chat accepts (the server's `CHAT_ATTACHMENT` rule, plus the `image/jpg` alias). */
+declare const ATTACHMENT_MIME_TYPES: readonly string[];
+/** The `accept` list of a web file input: the MIME types and their extensions. */
+declare const ATTACHMENT_ACCEPT = "image/jpeg,image/png,image/webp,image/heic,image/heif,.jpg,.jpeg,.png,.webp,.heic,.heif";
+/** The server's cap on one attachment (`max_content_length: 10485760`). */
+declare const MAX_ATTACHMENT_BYTES: number;
+/** The server's cap on attachments per message (`image_s3_keys`). */
+declare const MAX_ATTACHMENTS_PER_MESSAGE = 5;
+/** The filename cap after sanitising. */
+declare const MAX_FILENAME_LENGTH = 120;
+/** The route the initiate step posts to. */
+declare const ATTACHMENT_INITIATE_PATH = "/widget/v1/uploads/initiate";
+/** True when `mime` is an accepted image type (case-insensitive). */
+declare function isAttachmentMime(mime: string | undefined): boolean;
+/**
+ * Sanitise a user-supplied filename so it can sit in a request body, a label or a log line: path separators
+ * become spaces, control characters and quotes are dropped, whitespace collapses, and the result is capped at
+ * `MAX_FILENAME_LENGTH` keeping the extension. Empty in, `attachment` out.
+ */
+declare function sanitizeFilename(input: string | undefined): string;
+/** `512 B`, `12.3 KB`, `10.0 MB`: the app's byte formatter, for the size copy. */
+declare function formatBytes(bytes: number): string;
+/** The closed set of attachment failures; the React layer maps each to the app's copy. */
+type AttachmentErrorCode = 'too_large' | 'too_many' | 'unsupported_type' | 'network' | 'server' | 'cancelled' | 'rate_limited' | 'quota_exceeded' | 'idempotency_conflict' | 'unknown';
+/** One attachment failure, typed; `retryable` says whether a retry control is honest. */
+interface AttachmentError {
+    readonly code: AttachmentErrorCode;
+    readonly retryable: boolean;
+    /** The sanitised filename the failure is about. */
+    readonly filename: string;
+    /** For `too_large`: the file's size. */
+    readonly sizeBytes?: number;
+    /** For `server`: the HTTP status when one is known. */
+    readonly httpStatus?: number;
+    /** The settled SDK error behind a wire failure, when there is one (`displayMessage` is safe). */
+    readonly cause?: EverfurError;
+}
+/** The settle-shaped outcome of every attachment step: `AttachmentError` on the failure branch, never a throw. */
+type AttachmentOutcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: AttachmentError;
+};
+/** A validated file: what the queue uploads. */
+interface ValidatedAttachment {
+    readonly file: FileHandle;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+}
+/** The byte size of a handle: its `sizeBytes`, else its in-memory `blob`'s size; null when unknown. */
+declare function attachmentSize(file: FileHandle): number | null;
+/**
+ * The picker-boundary check: an accepted image type, at most `MAX_ATTACHMENT_BYTES`, a known size (the initiate
+ * body needs it), and a sanitised filename. Settles; never throws.
+ */
+declare function validateAttachment(file: FileHandle): AttachmentOutcome<ValidatedAttachment>;
+/** The presigned policy `POST /widget/v1/uploads/initiate` returns, plus the key the send names. */
+interface AttachmentUploadPolicy extends UploadPolicyWire {
+    readonly s3_key: string;
+    readonly purpose: string | null;
+}
+/**
+ * Step 2: ask for the presigned policy. Settles `ok(policy)` or a typed failure; a malformed policy is a
+ * non-retryable `server` failure (retrying cannot change the shape).
+ */
+declare function initiateAttachmentUpload(funnel: RequestFunnel, attachment: ValidatedAttachment, opts?: {
+    readonly signal?: AbortSignal;
+}): Promise<AttachmentOutcome<AttachmentUploadPolicy>>;
+/**
+ * Step 3: stage the bytes on S3 through the injected transport (the policy fields first, `file` last). A
+ * rejection is a retryable `server` failure, an abort a `cancelled` one; nothing here throws.
+ */
+declare function uploadAttachmentBytes(transport: UploadTransport, policy: AttachmentUploadPolicy, attachment: ValidatedAttachment, opts?: {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (fraction: number) => void;
+}): Promise<AttachmentOutcome<void>>;
+declare const ATTACHMENT_QUEUE_CONCURRENCY = 2;
+declare const ATTACHMENT_MAX_ATTEMPTS = 3;
+declare const ATTACHMENT_BACKOFF_MS: readonly number[];
+type AttachmentStatus = 'uploading' | 'uploaded' | 'failed';
+/** One attachment as a composer renders it. `s3Key` is set once `status === 'uploaded'`. */
+interface AttachmentState {
+    readonly id: string;
+    readonly filename: string;
+    /** What the thumbnail shows: the handle's `uri` (an object URL on the web, the local file on native). */
+    readonly previewUri: string;
+    readonly contentType: string;
+    readonly sizeBytes: number;
+    readonly status: AttachmentStatus;
+    readonly s3Key: string | null;
+    readonly error: AttachmentError | null;
+    /** 0..1 while uploading (the transport may report completion only). */
+    readonly progress: number;
+}
+/** The queue's frozen snapshot: the attachments in the order they were added. */
+interface AttachmentQueueSnapshot {
+    readonly attachments: readonly AttachmentState[];
+}
+interface AttachmentQueueDeps {
+    /** The request funnel of the current scope (the initiate hop). */
+    readonly funnel: RequestFunnel;
+    /** The host's upload transport (`EverfurConfig.uploadTransport`); the absent sentinel means uploads cannot run. */
+    readonly transport: UploadTransport;
+    /** The cap on attachments in the queue (the composer's slots); default `MAX_ATTACHMENTS_PER_MESSAGE`. */
+    readonly maxPerMessage?: number;
+    readonly concurrency?: number;
+    readonly maxAttempts?: number;
+    readonly backoffMs?: readonly number[];
+    /** Injected clock for deterministic backoff in tests. */
+    readonly timers?: Timers;
+    /** Injected id factory for deterministic tests. */
+    readonly newId?: () => string;
+}
+interface AttachmentQueue extends ReadableStore<AttachmentQueueSnapshot> {
+    /** True when the host wired an upload transport; a surface hides its attach control otherwise. */
+    readonly available: boolean;
+    /**
+     * Validate and enqueue one picked file. Settles `ok(state)` (the row, already `uploading`) or the typed
+     * failure that kept it out (`too_many`, `unsupported_type`, `too_large`, ...). Never throws.
+     */
+    add(file: FileHandle): AttachmentOutcome<AttachmentState>;
+    /** Re-run a failed row from the start (a fresh initiate; the same 3-attempt budget). A no-op otherwise. */
+    retry(id: string): void;
+    /** Drop a row: cancels it when in flight. */
+    remove(id: string): void;
+    /** Drop every row (after a send, or on unmount). */
+    clear(): void;
+    /** True while any row is still uploading (the send is blocked meanwhile). */
+    readonly uploading: boolean;
+    /** The S3 keys of every uploaded row, in order: what `SendOptions.imageS3Keys` takes. */
+    readonly s3Keys: readonly string[];
+    /** Stop everything and drop every listener. */
+    dispose(): void;
+}
+/** Build a queue. Framework-free; a React surface binds it through `useSyncExternalStore`. */
+declare function createAttachmentQueue(deps: AttachmentQueueDeps): AttachmentQueue;
+
+export { type AttachmentError as A, MAX_ATTACHMENTS_PER_MESSAGE as M, type ValidatedAttachment as V, type AttachmentErrorCode as a, type AttachmentOutcome as b, type AttachmentQueue as c, type AttachmentState as d, type AttachmentStatus as e, ATTACHMENT_ACCEPT as f, ATTACHMENT_BACKOFF_MS as g, ATTACHMENT_INITIATE_PATH as h, ATTACHMENT_MAX_ATTEMPTS as i, ATTACHMENT_MIME_TYPES as j, ATTACHMENT_QUEUE_CONCURRENCY as k, type AttachmentQueueDeps as l, type AttachmentQueueSnapshot as m, type AttachmentUploadPolicy as n, MAX_ATTACHMENT_BYTES as o, MAX_FILENAME_LENGTH as p, attachmentSize as q, createAttachmentQueue as r, formatBytes as s, initiateAttachmentUpload as t, isAttachmentMime as u, sanitizeFilename as v, uploadAttachmentBytes as w, validateAttachment as x };

package/dist/attachments-BrUWQYNK.d.ts

@@ -0,0 +1,257 @@
+import { E as EverfurError, c as EverfurResult } from './EverfurResult-DN9pL2Ab.js';
+import { C as ConversationId, P as PetRef, b as ResponseId } from './ids-B2GAAifq.js';
+import { f as ChatFeedbackType, j as ChatStatus, i as ChatMessage, c as ChatConversationListOptions, d as ChatConversationPage, g as ChatHistoryOptions, h as ChatMessagePage, a as ChatCheckinTarget, e as ChatFeedbackReceipt } from './ports-D7YW8qz9.js';
+import { C as CheckinAnswer, a as CheckinOutcome } from './casesRepository-v6QczS9N.js';
+import { i as UrgencyLevel } from './config-C7eb_IMD.js';
+import { W as WidgetPet } from './petsRepository-Bk6GDwLs.js';
+import { U as UploadTransport, F as FileHandle } from './ports-BN6RHF9W.js';
+import { c as AttachmentQueue, d as AttachmentState, A as AttachmentError, b as AttachmentOutcome } from './attachments-DpldrvIW.js';
+
+/** The three thumbs. `'neutral'` is the app's rotated thumbs-down glyph. */
+type ChatSentiment = 'up' | 'neutral' | 'down';
+/** The reason keys of the not-helpful sheet, in the app's order. */
+type ChatFeedbackReason = 'inaccurate' | 'outdated' | 'unsafe' | 'unclear' | 'other';
+interface ChatFeedbackReasonOption {
+    readonly key: ChatFeedbackReason;
+    /** The chip label, verbatim from the app. */
+    readonly label: string;
+    /** The `feedback_type` the chip records. */
+    readonly feedbackType: ChatFeedbackType;
+}
+
+/**
+ * Headless chat state. `isBootstrapping` is a deliberate superset of the SPEC-10 §7.4 minimum: the
+ * controller snapshot carries it (§7.1) and the prebuilt component maps it to the Loading state.
+ */
+interface UseEverfurChatState {
+    readonly status: ChatStatus;
+    readonly messages: ReadonlyArray<ChatMessage>;
+    readonly conversationId: ConversationId | null;
+    /** The pet this surface is scoped to (the option, else the provider's active pet); null when unscoped. */
+    readonly petRef: PetRef | null;
+    readonly error: EverfurError | null;
+    readonly isStreaming: boolean;
+    readonly isBootstrapping: boolean;
+    readonly historyCursor: string | null;
+    readonly isLoadingHistory: boolean;
+    /**
+     * The last turn was stopped before its first token: the question is on screen with no answer under it. The
+     * prebuilt surface renders the app's `Response stopped` notice with a retry; a fresh send, a retry or a
+     * thread change clears it.
+     *
+     * OPTIONAL on the type, always present from the hook. It was added to a shipped interface that partners and
+     * suites already build doubles of, and a required field would have made every one of those a type error for
+     * a flag they have no opinion about; absent reads the same as `false` everywhere it is consumed.
+     */
+    readonly stopped?: boolean;
+    listConversations(opts?: ChatConversationListOptions): Promise<EverfurResult<ChatConversationPage>>;
+    getMessages(id: ConversationId, opts?: ChatHistoryOptions): Promise<EverfurResult<ChatMessagePage>>;
+    resumeConversation(id: ConversationId): Promise<EverfurResult<void>>;
+    loadOlderMessages(): Promise<EverfurResult<void>>;
+    /**
+     * Backend-owned suggested-prompt strings (flattened + de-duplicated) from the chat bootstrap. Empty until the
+     * bootstrap resolves and empty when the backend returns none; the prebuilt component renders them as the
+     * tappable "Follow up questions" list, each string a ready-to-send message.
+     */
+    readonly suggestedPrompts: ReadonlyArray<string>;
+    /** Unread assistant messages in the active thread (see `ChatSnapshot.unreadCount`); null while unknown. */
+    readonly unreadCount: number | null;
+    /**
+     * Does any thread the SDK has listed still carry unread assistant content? The header dot, answerable from
+     * the chat bootstrap's own head read, so it never waits on the history drawer being opened.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is: it was added to a
+     * shipped interface that partners and suites already build doubles of, and absent reads as `false`.
+     */
+    readonly hasUnreadThreads?: boolean;
+    /**
+     * Open the thread a follow-up check-in landed in: the conversation an Everfur push named, or, with only a
+     * pet, the head of that pet's list (the read that also materializes a check-in the member is owed).
+     * Settles to the conversation opened, `ok(null)` when there is no thread yet; never throws.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is: it was added to a
+     * shipped interface that partners and suites already build doubles of, and a required member would have
+     * made every one of those a type error. A double that omits it simply opens nothing.
+     */
+    openCheckin?(target?: ChatCheckinTarget): Promise<EverfurResult<ConversationId | null>>;
+    /** Mark the active thread read and zero `unreadCount`. Settles; a no-op without an active thread. */
+    markRead(): Promise<EverfurResult<void>>;
+    /**
+     * CRN-16. The turn in flight is being re-attempted by the SDK with nothing asked of the reader. The
+     * prebuilt surfaces render the app's `Reconnecting` caption for it.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is.
+     */
+    readonly reconnecting?: boolean;
+    /**
+     * CRN-16. Re-read the active thread's newest window and the limit-1 list, merging in anything the platform
+     * wrote while the host was away. Settles; a no-op without a thread and while a turn is in flight.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is.
+     */
+    refreshActiveThread?(): Promise<EverfurResult<void>>;
+    /**
+     * Record the owner's answer to a follow-up check-in against the scoped pet and reflect it on the message
+     * (`message.checkin`). Settles; without a pet in scope it is `validationFailed` before any I/O.
+     */
+    answerCheckin(caseId: string, answer: CheckinAnswer): Promise<EverfurResult<CheckinOutcome>>;
+    /**
+     * Leave the active thread for a fresh, empty one (the history drawer's "New conversation"): the transcript
+     * clears and the next `send` creates the conversation. Nothing is fetched or deleted.
+     */
+    newConversation(): void;
+    /**
+     * The reader's rating per assistant message (keyed by the message id), for the thumbs: what was last recorded
+     * this session. A message with no entry is unrated. Local state; the server keeps its own copy.
+     */
+    readonly sentimentByMessage: Readonly<Record<string, ChatSentiment>>;
+    /**
+     * Rate an assistant reply (`POST /widget/v1/messages/{message_id}/feedback`). Only a message with a server
+     * `responseId` is eligible (a local or pending id settles to `validationFailed` before any I/O). A tap on the
+     * sentiment already recorded CLEARS it locally and sends nothing (the consumer app's behaviour); a different
+     * one replaces it. `reason` upgrades a thumbs-down to the specific `feedback_type` the not-helpful sheet
+     * picks, `notes` (<= 4000 characters) rides with it. Settles `ok({ feedbackId })` (an empty id on a local
+     * clear); never throws.
+     */
+    feedback(responseId: ResponseId, sentiment: ChatSentiment, reason?: ChatFeedbackReason | null, notes?: string | null): Promise<EverfurResult<ChatFeedbackReceipt>>;
+    /**
+     * Optimistic; the blank user bubble is removed on a pre-first-delta failure (controller-owned). Drives the
+     * controller stream to completion and settles: `ok(responseId)` on a completed turn (the id is null when
+     * the terminal `done` frame carried no message id), or `err` with the terminal EverfurError. `imageS3Keys`
+     * are the keys of images staged through the attachments queue (at most 5).
+     */
+    send(text: string, opts?: {
+        readonly imageS3Keys?: readonly string[];
+    }): Promise<EverfurResult<ResponseId | null>>;
+    /**
+     * CRN-06. Ask a grounded question in a FRESH conversation: the thread on screen is left and `prompt` is
+     * the first turn of a new one (the consumer's "Ask Everfur" handoff from a records card). Settles like
+     * `send`.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is.
+     */
+    askEverfur?(prompt: string): Promise<EverfurResult<ResponseId | null>>;
+    /** Re-sends the last turn with the SAME idempotency key; no duplicate user bubble (§7.4). */
+    retryLast(): Promise<EverfurResult<ResponseId | null>>;
+    /** Aborts the in-flight stream; not an error. */
+    stop(): void;
+}
+/**
+ * @throws {EverfurConfigError} kind 'not-initialized' if called outside an EverfurProvider.
+ * Auto-disposes its controller reference on unmount.
+ */
+declare function useEverfurChat(opts?: {
+    readonly petRef?: PetRef;
+    readonly conversationId?: ConversationId;
+}): UseEverfurChatState;
+
+/**
+ * The host's lifecycle and connectivity signals. Each subscribe returns its own unsubscribe, which the SDK
+ * calls on unmount; a listener that throws is contained by the caller, never by the host.
+ */
+interface LifecyclePort {
+    /**
+     * The host came back to the foreground. Only the real blur-to-focus edge, please: a platform that flips
+     * through an inactive state constantly (iOS control centre, a call banner) would otherwise turn a
+     * notification-shade pull into a request.
+     */
+    onForeground(listener: () => void): () => void;
+    /** Connectivity returned. Omit it and a deferred refresh waits for the next foreground instead. */
+    onOnline?(listener: () => void): () => void;
+    /**
+     * Something told the host THIS member's thread changed: the push that carried the message. Announced
+     * triggers are never coalesced, because that is the one case where the reader is waiting on new content.
+     */
+    onAnnounced?(listener: () => void): () => void;
+    /** Is the host unambiguously offline? Absent reads as online, which is exactly today's behaviour. */
+    isOffline?(): boolean;
+}
+
+/**
+ * CRN-16. The host's own storage for an unsent draft. The SDK ships NO persistence of its own: a draft is
+ * memory-only unless a host passes this, because a question half-typed on a health surface is the reader's
+ * own text and where it may be written down is the host's decision, not the SDK's. `conversationId` is null
+ * for the not-yet-created thread, so a host that keys on it can scope per thread.
+ */
+interface EverfurChatDraftStore {
+    /** The draft you last stored for this thread, or null. May be async. */
+    read(conversationId: string | null): string | null | Promise<string | null>;
+    /** Store the unsent draft for this thread; an empty string means the reader cleared it. May be async. */
+    write(conversationId: string | null, text: string): void | Promise<void>;
+}
+
+/** The three server tiers plus the app's calm `general` tier for an informational turn. */
+type UrgencyDisplayLevel = UrgencyLevel | 'general';
+
+/** The pet list state a header or switcher renders from. */
+interface UseEverfurPetsState {
+    /** The registered pets, newest first as the server lists them; empty until the first fetch settles. */
+    readonly pets: readonly WidgetPet[];
+    /** The provider's active pet (`activePet` prop or `handle.setActivePet`), resolved against the list; null when unscoped or not listed. */
+    readonly activePet: WidgetPet | null;
+    /** True while a fetch is in flight (the first one too, so a header can hold its disc until the name is known). */
+    readonly loading: boolean;
+    /** The last fetch's settled error (`error.displayMessage` is safe to show), or null. */
+    readonly error: EverfurError | null;
+    /** Fetch the list again (after `registerPet`, or a retry). Settles; never throws. */
+    refresh(): Promise<void>;
+}
+/**
+ * @throws {EverfurConfigError} kind 'not-initialized' if called outside an EverfurProvider.
+ */
+declare function useEverfurPets(): UseEverfurPetsState;
+
+/** What a composer renders and calls. */
+interface UseChatAttachmentsState {
+    /** True when the host wired an upload transport; the attach control is hidden otherwise. */
+    readonly available: boolean;
+    /** The rows, in the order they were added. */
+    readonly attachments: readonly AttachmentState[];
+    /** The composer's slots. */
+    readonly maxPerMessage: number;
+    /** True while any row is still uploading: the send is blocked meanwhile. */
+    readonly uploading: boolean;
+    /**
+     * True while any row FAILED to upload. The send is blocked on this too, because the alternative is the
+     * silent drop: `s3Keys` names only the rows that landed and the strip is cleared on dispatch, so a send here
+     * would post the message without the photo the owner picked and leave nothing behind to say so. The consumer
+     * app blocks the same way (everfur-mobile `useAuthenticatedReportChat.ts`, the `blockingAttachment` guard).
+     */
+    readonly failed: boolean;
+    /**
+     * True while the composer must refuse the send: a row is uploading or a row failed. `failed` says which of
+     * the two needs a sentence (the spinner already speaks for the other).
+     */
+    readonly blocked: boolean;
+    /** The S3 keys of every uploaded row, for `send(text, { imageS3Keys })`. */
+    readonly s3Keys: readonly string[];
+    /** The last failure that kept a pick out of the queue (`too_large`, `unsupported_type`, `too_many`), or null. */
+    readonly rejected: AttachmentError | null;
+    /** Validate and enqueue one or more picked files; returns each outcome. Never throws. */
+    add(files: FileHandle | readonly FileHandle[]): readonly AttachmentOutcome<AttachmentState>[];
+    retry(id: string): void;
+    remove(id: string): void;
+    /** Drop every row (after a successful send). */
+    clear(): void;
+    /** Forget the last rejection (the composer showed it). */
+    dismissRejected(): void;
+}
+interface UseChatAttachmentsOptions {
+    /** The composer's slots; default `MAX_ATTACHMENTS_PER_MESSAGE` (5). */
+    readonly maxPerMessage?: number;
+    /** Test seam: a queue to bind instead of building one from the provider. */
+    readonly queue?: AttachmentQueue;
+    /**
+     * The upload transport to bind instead of the provider's `uploadTransport`: the web surface passes its own
+     * fetch-based one, since a browser needs no host adapter to post a multipart form. Absent, the host's.
+     */
+    readonly transport?: UploadTransport;
+}
+/**
+ * The attachment rows of the composer. The queue lives for the scope (user, session epoch) and is disposed on
+ * unmount or re-scope, so a previous user's thumbnails never survive a switch.
+ * @throws {EverfurConfigError} kind 'not-initialized' if called outside an EverfurProvider.
+ */
+declare function useChatAttachments(options?: UseChatAttachmentsOptions): UseChatAttachmentsState;
+
+export { type ChatFeedbackReason as C, type EverfurChatDraftStore as E, type LifecyclePort as L, type UrgencyDisplayLevel as U, type ChatFeedbackReasonOption as a, type ChatSentiment as b, type UseChatAttachmentsOptions as c, type UseChatAttachmentsState as d, type UseEverfurChatState as e, type UseEverfurPetsState as f, useEverfurChat as g, useEverfurPets as h, useChatAttachments as u };

package/dist/attachments-D_SECjr1.d.cts

@@ -0,0 +1,257 @@
+import { E as EverfurError, c as EverfurResult } from './EverfurResult-DN9pL2Ab.cjs';
+import { C as ConversationId, P as PetRef, b as ResponseId } from './ids-B2GAAifq.cjs';
+import { f as ChatFeedbackType, j as ChatStatus, i as ChatMessage, c as ChatConversationListOptions, d as ChatConversationPage, g as ChatHistoryOptions, h as ChatMessagePage, a as ChatCheckinTarget, e as ChatFeedbackReceipt } from './ports-BY2ph0_y.cjs';
+import { C as CheckinAnswer, a as CheckinOutcome } from './casesRepository-DwtZVsbj.cjs';
+import { i as UrgencyLevel } from './config--Wu1Umhd.cjs';
+import { W as WidgetPet } from './petsRepository-B_gKbAzJ.cjs';
+import { U as UploadTransport, F as FileHandle } from './ports-BN6RHF9W.cjs';
+import { c as AttachmentQueue, d as AttachmentState, A as AttachmentError, b as AttachmentOutcome } from './attachments-BorG422I.cjs';
+
+/** The three thumbs. `'neutral'` is the app's rotated thumbs-down glyph. */
+type ChatSentiment = 'up' | 'neutral' | 'down';
+/** The reason keys of the not-helpful sheet, in the app's order. */
+type ChatFeedbackReason = 'inaccurate' | 'outdated' | 'unsafe' | 'unclear' | 'other';
+interface ChatFeedbackReasonOption {
+    readonly key: ChatFeedbackReason;
+    /** The chip label, verbatim from the app. */
+    readonly label: string;
+    /** The `feedback_type` the chip records. */
+    readonly feedbackType: ChatFeedbackType;
+}
+
+/**
+ * Headless chat state. `isBootstrapping` is a deliberate superset of the SPEC-10 §7.4 minimum: the
+ * controller snapshot carries it (§7.1) and the prebuilt component maps it to the Loading state.
+ */
+interface UseEverfurChatState {
+    readonly status: ChatStatus;
+    readonly messages: ReadonlyArray<ChatMessage>;
+    readonly conversationId: ConversationId | null;
+    /** The pet this surface is scoped to (the option, else the provider's active pet); null when unscoped. */
+    readonly petRef: PetRef | null;
+    readonly error: EverfurError | null;
+    readonly isStreaming: boolean;
+    readonly isBootstrapping: boolean;
+    readonly historyCursor: string | null;
+    readonly isLoadingHistory: boolean;
+    /**
+     * The last turn was stopped before its first token: the question is on screen with no answer under it. The
+     * prebuilt surface renders the app's `Response stopped` notice with a retry; a fresh send, a retry or a
+     * thread change clears it.
+     *
+     * OPTIONAL on the type, always present from the hook. It was added to a shipped interface that partners and
+     * suites already build doubles of, and a required field would have made every one of those a type error for
+     * a flag they have no opinion about; absent reads the same as `false` everywhere it is consumed.
+     */
+    readonly stopped?: boolean;
+    listConversations(opts?: ChatConversationListOptions): Promise<EverfurResult<ChatConversationPage>>;
+    getMessages(id: ConversationId, opts?: ChatHistoryOptions): Promise<EverfurResult<ChatMessagePage>>;
+    resumeConversation(id: ConversationId): Promise<EverfurResult<void>>;
+    loadOlderMessages(): Promise<EverfurResult<void>>;
+    /**
+     * Backend-owned suggested-prompt strings (flattened + de-duplicated) from the chat bootstrap. Empty until the
+     * bootstrap resolves and empty when the backend returns none; the prebuilt component renders them as the
+     * tappable "Follow up questions" list, each string a ready-to-send message.
+     */
+    readonly suggestedPrompts: ReadonlyArray<string>;
+    /** Unread assistant messages in the active thread (see `ChatSnapshot.unreadCount`); null while unknown. */
+    readonly unreadCount: number | null;
+    /**
+     * Does any thread the SDK has listed still carry unread assistant content? The header dot, answerable from
+     * the chat bootstrap's own head read, so it never waits on the history drawer being opened.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is: it was added to a
+     * shipped interface that partners and suites already build doubles of, and absent reads as `false`.
+     */
+    readonly hasUnreadThreads?: boolean;
+    /**
+     * Open the thread a follow-up check-in landed in: the conversation an Everfur push named, or, with only a
+     * pet, the head of that pet's list (the read that also materializes a check-in the member is owed).
+     * Settles to the conversation opened, `ok(null)` when there is no thread yet; never throws.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is: it was added to a
+     * shipped interface that partners and suites already build doubles of, and a required member would have
+     * made every one of those a type error. A double that omits it simply opens nothing.
+     */
+    openCheckin?(target?: ChatCheckinTarget): Promise<EverfurResult<ConversationId | null>>;
+    /** Mark the active thread read and zero `unreadCount`. Settles; a no-op without an active thread. */
+    markRead(): Promise<EverfurResult<void>>;
+    /**
+     * CRN-16. The turn in flight is being re-attempted by the SDK with nothing asked of the reader. The
+     * prebuilt surfaces render the app's `Reconnecting` caption for it.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is.
+     */
+    readonly reconnecting?: boolean;
+    /**
+     * CRN-16. Re-read the active thread's newest window and the limit-1 list, merging in anything the platform
+     * wrote while the host was away. Settles; a no-op without a thread and while a turn is in flight.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is.
+     */
+    refreshActiveThread?(): Promise<EverfurResult<void>>;
+    /**
+     * Record the owner's answer to a follow-up check-in against the scoped pet and reflect it on the message
+     * (`message.checkin`). Settles; without a pet in scope it is `validationFailed` before any I/O.
+     */
+    answerCheckin(caseId: string, answer: CheckinAnswer): Promise<EverfurResult<CheckinOutcome>>;
+    /**
+     * Leave the active thread for a fresh, empty one (the history drawer's "New conversation"): the transcript
+     * clears and the next `send` creates the conversation. Nothing is fetched or deleted.
+     */
+    newConversation(): void;
+    /**
+     * The reader's rating per assistant message (keyed by the message id), for the thumbs: what was last recorded
+     * this session. A message with no entry is unrated. Local state; the server keeps its own copy.
+     */
+    readonly sentimentByMessage: Readonly<Record<string, ChatSentiment>>;
+    /**
+     * Rate an assistant reply (`POST /widget/v1/messages/{message_id}/feedback`). Only a message with a server
+     * `responseId` is eligible (a local or pending id settles to `validationFailed` before any I/O). A tap on the
+     * sentiment already recorded CLEARS it locally and sends nothing (the consumer app's behaviour); a different
+     * one replaces it. `reason` upgrades a thumbs-down to the specific `feedback_type` the not-helpful sheet
+     * picks, `notes` (<= 4000 characters) rides with it. Settles `ok({ feedbackId })` (an empty id on a local
+     * clear); never throws.
+     */
+    feedback(responseId: ResponseId, sentiment: ChatSentiment, reason?: ChatFeedbackReason | null, notes?: string | null): Promise<EverfurResult<ChatFeedbackReceipt>>;
+    /**
+     * Optimistic; the blank user bubble is removed on a pre-first-delta failure (controller-owned). Drives the
+     * controller stream to completion and settles: `ok(responseId)` on a completed turn (the id is null when
+     * the terminal `done` frame carried no message id), or `err` with the terminal EverfurError. `imageS3Keys`
+     * are the keys of images staged through the attachments queue (at most 5).
+     */
+    send(text: string, opts?: {
+        readonly imageS3Keys?: readonly string[];
+    }): Promise<EverfurResult<ResponseId | null>>;
+    /**
+     * CRN-06. Ask a grounded question in a FRESH conversation: the thread on screen is left and `prompt` is
+     * the first turn of a new one (the consumer's "Ask Everfur" handoff from a records card). Settles like
+     * `send`.
+     *
+     * OPTIONAL on the type, always present from the hook, for the same reason `stopped` is.
+     */
+    askEverfur?(prompt: string): Promise<EverfurResult<ResponseId | null>>;
+    /** Re-sends the last turn with the SAME idempotency key; no duplicate user bubble (§7.4). */
+    retryLast(): Promise<EverfurResult<ResponseId | null>>;
+    /** Aborts the in-flight stream; not an error. */
+    stop(): void;
+}
+/**
+ * @throws {EverfurConfigError} kind 'not-initialized' if called outside an EverfurProvider.
+ * Auto-disposes its controller reference on unmount.
+ */
+declare function useEverfurChat(opts?: {
+    readonly petRef?: PetRef;
+    readonly conversationId?: ConversationId;
+}): UseEverfurChatState;
+
+/**
+ * The host's lifecycle and connectivity signals. Each subscribe returns its own unsubscribe, which the SDK
+ * calls on unmount; a listener that throws is contained by the caller, never by the host.
+ */
+interface LifecyclePort {
+    /**
+     * The host came back to the foreground. Only the real blur-to-focus edge, please: a platform that flips
+     * through an inactive state constantly (iOS control centre, a call banner) would otherwise turn a
+     * notification-shade pull into a request.
+     */
+    onForeground(listener: () => void): () => void;
+    /** Connectivity returned. Omit it and a deferred refresh waits for the next foreground instead. */
+    onOnline?(listener: () => void): () => void;
+    /**
+     * Something told the host THIS member's thread changed: the push that carried the message. Announced
+     * triggers are never coalesced, because that is the one case where the reader is waiting on new content.
+     */
+    onAnnounced?(listener: () => void): () => void;
+    /** Is the host unambiguously offline? Absent reads as online, which is exactly today's behaviour. */
+    isOffline?(): boolean;
+}
+
+/**
+ * CRN-16. The host's own storage for an unsent draft. The SDK ships NO persistence of its own: a draft is
+ * memory-only unless a host passes this, because a question half-typed on a health surface is the reader's
+ * own text and where it may be written down is the host's decision, not the SDK's. `conversationId` is null
+ * for the not-yet-created thread, so a host that keys on it can scope per thread.
+ */
+interface EverfurChatDraftStore {
+    /** The draft you last stored for this thread, or null. May be async. */
+    read(conversationId: string | null): string | null | Promise<string | null>;
+    /** Store the unsent draft for this thread; an empty string means the reader cleared it. May be async. */
+    write(conversationId: string | null, text: string): void | Promise<void>;
+}
+
+/** The three server tiers plus the app's calm `general` tier for an informational turn. */
+type UrgencyDisplayLevel = UrgencyLevel | 'general';
+
+/** The pet list state a header or switcher renders from. */
+interface UseEverfurPetsState {
+    /** The registered pets, newest first as the server lists them; empty until the first fetch settles. */
+    readonly pets: readonly WidgetPet[];
+    /** The provider's active pet (`activePet` prop or `handle.setActivePet`), resolved against the list; null when unscoped or not listed. */
+    readonly activePet: WidgetPet | null;
+    /** True while a fetch is in flight (the first one too, so a header can hold its disc until the name is known). */
+    readonly loading: boolean;
+    /** The last fetch's settled error (`error.displayMessage` is safe to show), or null. */
+    readonly error: EverfurError | null;
+    /** Fetch the list again (after `registerPet`, or a retry). Settles; never throws. */
+    refresh(): Promise<void>;
+}
+/**
+ * @throws {EverfurConfigError} kind 'not-initialized' if called outside an EverfurProvider.
+ */
+declare function useEverfurPets(): UseEverfurPetsState;
+
+/** What a composer renders and calls. */
+interface UseChatAttachmentsState {
+    /** True when the host wired an upload transport; the attach control is hidden otherwise. */
+    readonly available: boolean;
+    /** The rows, in the order they were added. */
+    readonly attachments: readonly AttachmentState[];
+    /** The composer's slots. */
+    readonly maxPerMessage: number;
+    /** True while any row is still uploading: the send is blocked meanwhile. */
+    readonly uploading: boolean;
+    /**
+     * True while any row FAILED to upload. The send is blocked on this too, because the alternative is the
+     * silent drop: `s3Keys` names only the rows that landed and the strip is cleared on dispatch, so a send here
+     * would post the message without the photo the owner picked and leave nothing behind to say so. The consumer
+     * app blocks the same way (everfur-mobile `useAuthenticatedReportChat.ts`, the `blockingAttachment` guard).
+     */
+    readonly failed: boolean;
+    /**
+     * True while the composer must refuse the send: a row is uploading or a row failed. `failed` says which of
+     * the two needs a sentence (the spinner already speaks for the other).
+     */
+    readonly blocked: boolean;
+    /** The S3 keys of every uploaded row, for `send(text, { imageS3Keys })`. */
+    readonly s3Keys: readonly string[];
+    /** The last failure that kept a pick out of the queue (`too_large`, `unsupported_type`, `too_many`), or null. */
+    readonly rejected: AttachmentError | null;
+    /** Validate and enqueue one or more picked files; returns each outcome. Never throws. */
+    add(files: FileHandle | readonly FileHandle[]): readonly AttachmentOutcome<AttachmentState>[];
+    retry(id: string): void;
+    remove(id: string): void;
+    /** Drop every row (after a successful send). */
+    clear(): void;
+    /** Forget the last rejection (the composer showed it). */
+    dismissRejected(): void;
+}
+interface UseChatAttachmentsOptions {
+    /** The composer's slots; default `MAX_ATTACHMENTS_PER_MESSAGE` (5). */
+    readonly maxPerMessage?: number;
+    /** Test seam: a queue to bind instead of building one from the provider. */
+    readonly queue?: AttachmentQueue;
+    /**
+     * The upload transport to bind instead of the provider's `uploadTransport`: the web surface passes its own
+     * fetch-based one, since a browser needs no host adapter to post a multipart form. Absent, the host's.
+     */
+    readonly transport?: UploadTransport;
+}
+/**
+ * The attachment rows of the composer. The queue lives for the scope (user, session epoch) and is disposed on
+ * unmount or re-scope, so a previous user's thumbnails never survive a switch.
+ * @throws {EverfurConfigError} kind 'not-initialized' if called outside an EverfurProvider.
+ */
+declare function useChatAttachments(options?: UseChatAttachmentsOptions): UseChatAttachmentsState;
+
+export { type ChatFeedbackReason as C, type EverfurChatDraftStore as E, type LifecyclePort as L, type UrgencyDisplayLevel as U, type ChatFeedbackReasonOption as a, type ChatSentiment as b, type UseChatAttachmentsOptions as c, type UseChatAttachmentsState as d, type UseEverfurChatState as e, type UseEverfurPetsState as f, useEverfurChat as g, useEverfurPets as h, useChatAttachments as u };