@everfur/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to `@everfur/sdk`.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions are semver.
+
+This is the first release. The line is deliberately pre-1.0: the API is stable enough to build against and
+is guarded by api-extractor golden reports across all eleven subpaths, but 1.0.0 is a promise about breaking
+changes that has not been earned by any production integration yet.
+
+## [0.1.0] - 2026-08-23
+
+### Fixed — correctness
+
+- **Anonymous mode could never send a message.** The SDK never sent `x-everfur-session-id`, and the server
+  derives the anonymous identity from it, minting a fresh one per request. A conversation was created as one
+  user and the message sent as another, so every send settled `conversationNotFound`. One stable v4 id is
+  now minted per runtime and sent on both the unary and streaming paths.
+- **Sign-out did not sign out.** `identity.clear()` only dropped the token cache, so a capability holding a
+  pre-logout `AuthContext` re-entered the partner's `getToken` and minted a fresh token for the signed-out
+  user. It is now terminal. The anonymous branch no longer carries the signed-out `userRef`, and the session
+  id rotates on logout.
+- **A misconfigured provider was a white screen.** `EverfurProvider` threw synchronously from its own render,
+  above every error boundary a partner can install. Config now settles into a disabled runtime: children
+  render, every capability shows its off-state at `disabled.level === 'sdk_config'`, and the transport
+  refuses.
+- **The runtime is rebuilt when the config identity changes or it has been disposed.** An asynchronously
+  supplied `publishableKey` never took effect, and React StrictMode's double-mount permanently killed it.
+- **Records polled every 4 seconds forever.** `MAX_POLLS` never bound, because the counter lived inside an
+  effect keyed on an object rebuilt each tick. Measured 300 polls against a cap of 30.
+- **Chat message bounds are measured in code points**, as the server measures them; UTF-16 units counted
+  every emoji twice and refused messages at half the real limit.
+- Neither `POST /conversations` nor the SSE send is auto-replayed: the widget lane does not read
+  `Idempotency-Key`, so a retry was a second row, not a dedup.
+
+### Fixed — security
+
+- **`@everfur/sdk/server` is no longer resolvable from a React Native bundle.** The subpath merely omitted a
+  `react-native` export condition, which is not a block; it now maps to `null`. This is the module carrying
+  `sk_partner_`.
+- `mintPartnerSession` validates its base URL instead of concatenating it, so a cleartext
+  `EVERFUR_API_BASE_URL` can no longer put the partner secret key on the wire.
+- Config failure messages echo a redacted origin, never the raw base URL, which could carry userinfo.
+- A secret key pasted into `publishableKey` is refused.
+
+### Added
+
+- `registerPet` on the runtime and the handle, plus `createPetsRepository` on `@everfur/sdk/client`. Records
+  and consent are unreachable for any pet the partner has not registered, and there was previously no way to
+  register one from the SDK.
+- The clinical disclaimer is mounted on every pet-health surface, not only chat.
+- `npm run docs:check` type-checks every documented snippet.
+- `EverfurRequestBase` and `MultipartBody` are exported, so a `TransportPort` wrapper can extend the request
+  shape without depending on the union (see the `EverfurRequest` note below).
+- `EverfurConfig.errorPolicy`'s `shouldRetry` and `maxAttempts` are now actually consulted. They were typed,
+  exported and documented while reaching no request in the SDK. Both narrow only: neither can make a spent
+  daily quota retryable nor resurrect a terminal code, and an SDK per-call cap still outranks them.
+
+### Changed — potentially breaking
+
+- **`DisabledLevel` gained an `sdk_config` member.** A consumer with an exhaustive `switch` over that union
+  will no longer compile. This is the one deliberate widening in this set.
+- **`AuthContext.sessionId` is now required.** Building the context without one silently reintroduced the
+  anonymous-identity defect, so the type now catches it.
+- **`EverfurRequest` is now a union, not an interface.** It was
+  `EverfurRequestBase & ({ body?: unknown; multipart?: undefined } | { body?: undefined; multipart: MultipartBody })`,
+  so carrying both a JSON body and a multipart body is unrepresentable rather than merely discouraged: the
+  combination produces a `content-type` without the platform-generated boundary and the server cannot parse
+  the request. Two ordinary patterns on the `TransportPort` seam stop compiling, both with a one-line fix:
+  - `interface X extends EverfurRequest` fails with TS2312 (an interface cannot extend a union). Extend the
+    newly exported `EverfurRequestBase` instead.
+  - `inner.request({ ...req, body: next })` inside a transport wrapper fails, because TypeScript cannot tell
+    which arm `req` is. Narrow first: `if (req.multipart === undefined) inner.request({ ...req, body: next })`.
+- `RecordsRepository` dropped the `idem` parameters its only implementation ignored.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Everfur Health, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @everfur/sdk (React Native)
+
+Drop Everfur's AI vet assistant and pet-health features (records, gait/video, photo checkup, pet-state
+media) into a React Native app. What each of your customers and users can see is decided **server-side** by
+Everfur's entitlement control plane and rendered by the SDK, so you gate features without shipping an app
+update.
+
+- Hexagonal, framework-free core with a thin RN layer; every surface settles (no thrown domain errors).
+- Server-authoritative entitlements: a feature you are not entitled to renders a deliberate off-state, never
+  a blank screen, and cannot be force-enabled client-side.
+- The app never holds a secret. See [The security model](#the-security-model).
+
+> `0.1.0`, MIT licensed, public on npm. Requires React Native `>=0.74`, and Node `>=18` on the backend
+> that mints sessions.
+
+**Getting keys:** Everfur keys are provisioned by the Everfur team during partner onboarding; there is
+no self-serve signup yet. Contact [support@everfur.com](mailto:support@everfur.com) to get set up. The
+publishable key is designed to ship inside your app; the secret key is not.
+
+## Install
+
+```bash
+npm i @everfur/sdk
+# Always-required peers:
+npm i react react-native react-native-safe-area-context
+```
+
+Peer dependencies by capability (install only what you use):
+
+| Capability | Extra peer deps | Notes |
+| --- | --- | --- |
+| chat, entitlements | none | works with react + react-native alone |
+| records | `expo-file-system`, `expo-image-manipulator` | document upload + client-side image prep |
+| video (gait), photo (checkup) | `react-native-vision-camera` | **use `4.x` on RN 0.74**; `5.x` requires the new architecture |
+
+The camera and file-system peers are optional: if you never mount `./video`, `./photo`, or `./records`,
+you do not need them. `react-native-vision-camera` also needs its config plugin in `app.json` and a camera
+usage description.
+
+### Bundler resolution
+
+No Metro configuration is required. Every subpath (`@everfur/sdk/chat`, `/records`, `/video`, `/photo`,
+`/animations`, `/client`, `/core`, `/testing`, `/testing/rn`) resolves on a stock install. Modern bundlers
+read the package `exports` map; Metro 0.80.x, which ships with Expo 51, defaults to
+`unstable_enablePackageExports: false` and never reads it, so the package also ships classic root-level
+resolution shims for the same subpaths. You do not need to turn package exports on, and turning them on does
+not change what you get.
+
+`@everfur/sdk/server` is the one exception, deliberately: it is your **backend** module and carries the
+`sk_partner_` session minter. If it is ever pulled into an app bundle it throws on import rather than
+shipping the minter to a device. Import it from your server only.
+
+## Quickstart
+
+Wrap your tree once, high, then drop features in behind a gate. This is the exact shape the reference app
+uses:
+
+```tsx
+import { EverfurProvider, EverfurChat, petRef, userRef } from '@everfur/sdk';
+
+export default function App() {
+  return (
+    <EverfurProvider
+      config={{
+        publishableKey: process.env.EXPO_PUBLIC_EVERFUR_PUBLISHABLE_KEY!, // pk_live_...  safe to ship
+        apiBaseUrl: 'https://api.everfur.com/api/v1',
+      }}
+      // Omit `user` entirely for anonymous mode (publishable key alone, general answers).
+      user={{
+          userRef: userRef('your-stable-user-id'),
+          getToken: () => fetch('/everfur-session').then((r) => r.text()),
+        }}
+      activePet={petRef('pet-ref-123')}
+    >
+      {/* Every prebuilt widget self-gates. CapabilityGate is for YOUR surrounding UI - a tab, a nav
+          entry - not for wrapping a widget that already gates itself. */}
+      <EverfurChat petRef={petRef('pet-ref-123')} />
+    </EverfurProvider>
+  );
+}
+```
+
+`getToken` calls **your** backend for a short-lived session token (never a secret in the app):
+
+```ts
+async function getToken(): Promise<string> {
+  const res = await fetch('https://your-backend.example.com/everfur/session', {
+    method: 'POST',
+    headers: { authorization: `Bearer ${yourAppsUserToken}` },
+  });
+  const { sessionToken } = await res.json();
+  return sessionToken;
+}
+```
+
+The SDK calls `getToken` lazily and re-calls it once after a `401`, so a fresh token is always used without
+you managing expiry. Records lives on its own subpath:
+
+```tsx
+import { EverfurRecords } from '@everfur/sdk/records';
+import { petRef } from '@everfur/sdk';
+
+<EverfurRecords petRef={petRef('pet-ref-123')} />
+```
+
+## The security model
+
+The one rule: **the app never holds a secret.** Two credentials, kept apart.
+
+| Credential | Where it lives | What it does |
+| --- | --- | --- |
+| Publishable key `pk_live_...` | In the app (`EXPO_PUBLIC_...`). Safe to ship. | Names your tenant. Cannot mint a session or grant a feature by itself. |
+| Partner secret key `sk_partner_...` | **Only** on your server. Never in the app, its bundle, env, git, or logs. | Mints session tokens. Revocable and rotatable without an app release. |
+| Session token (bearer) | App memory, short-lived. | Authenticates one end user; re-minted via your backend on a 401. |
+
+Your backend exchanges the two provisioning credentials for a short-lived session by calling
+`POST /widget/v1/sessions` with `x-everfur-partner-key: pk_live_...` + `x-everfur-partner-secret-key:
+sk_partner_...`. The SDK ships a **server-only** helper (`mintPartnerSession`, imported from
+`@everfur/sdk/server`) so you do not hand-roll that request. That helper is deliberately absent from every
+React-Native-resolvable bundle: a device can never import it, so the secret has no path onto the phone.
+
+**Do:** ship `pk_live_` in the app; keep `sk_partner_` in a server secret manager; mint sessions on your
+backend; serve everything over HTTPS.
+**Never:** put `sk_partner_` in the app; mint sessions on the device; try to force-enable a feature
+client-side (the server re-checks and returns `403`).
+
+## How feature access works
+
+Access is decided server-side and delivered to the SDK (`GET /widget/v1/entitlements`, fail-closed). Each
+surface sits behind `CapabilityGate`; a capability you are not entitled to renders a deliberate off-state,
+and it cannot be force-enabled client-side because the API re-checks on every request. A coarse feature
+(`chat`, `records`, `video`, ...) is enabled only when every dotted sub-feature resource it requires is
+granted (for example `records` needs both `records.upload.create` and `records.record.read`). You set these
+per customer and per user in Everfur's admin control plane; the app renders the verdict.
+
+Every SDK surface renders all four states (loading, empty, error, populated); a denied surface renders its
+off-state, never a blank region.
+
+## Public entry points
+
+| Import | Contents |
+| --- | --- |
+| `@everfur/sdk` | `EverfurProvider`, `CapabilityGate`, `EverfurChat`, `useEverfurChat`, `CapabilityName`, error/result types, branded id helpers (`petRef`, `userRef`, `conversationId`) |
+| `@everfur/sdk/records` | `EverfurRecords`, records hooks + types |
+| `@everfur/sdk/video` | gait / live-scan surface |
+| `@everfur/sdk/photo` | photo checkup surface |
+| `@everfur/sdk/animations` | server-driven pet-state media surface |
+| `@everfur/sdk/server` | **server-only** `mintPartnerSession` (no React Native resolution; never bundled on-device) |
+| `@everfur/sdk/testing`, `@everfur/sdk/testing/rn` | test seams (`MockTransport`, ...) for your own tests |
+
+`@everfur/sdk/client` and `@everfur/sdk/core` expose the framework-free layers for advanced integrators;
+most apps only need the root entry plus the capability subpaths.
+
+## Reference app
+
+A full, runnable integration (a fictional "Pawtrail" app plus a minimal mint backend that holds the secret)
+lives at [`examples/minimal-integration.tsx`](examples/minimal-integration.tsx) in this repository — it is
+type-checked by `npm run docs:check`, so it cannot rot. It shows anonymous mode, the two-credential session
+mint, pet registration and sign-out. (A separate `everfur-integration-example-rn` app exists internally but
+is not published anywhere a partner can reach, so do not rely on references to it.) It gates every
+capability, and is the copy-paste source for the snippets above.

package/animations/package.json

@@ -0,0 +1,8 @@
+{
+  "//": "GENERATED by scripts/subpath-shims.mjs from the package.json \"exports\" map. Do not edit by hand; run `npm run build`.",
+  "react-native": "../dist/animations/index.js",
+  "module": "../dist/animations/index.js",
+  "main": "../dist/animations/index.cjs",
+  "types": "../dist/animations/index.d.ts",
+  "sideEffects": false
+}

package/chat/package.json

@@ -0,0 +1,8 @@
+{
+  "//": "GENERATED by scripts/subpath-shims.mjs from the package.json \"exports\" map. Do not edit by hand; run `npm run build`.",
+  "react-native": "../dist/chat/index.js",
+  "module": "../dist/chat/index.js",
+  "main": "../dist/chat/index.cjs",
+  "types": "../dist/chat/index.d.ts",
+  "sideEffects": false
+}

package/client/package.json

@@ -0,0 +1,8 @@
+{
+  "//": "GENERATED by scripts/subpath-shims.mjs from the package.json \"exports\" map. Do not edit by hand; run `npm run build`.",
+  "react-native": "../dist/client/index.js",
+  "module": "../dist/client/index.js",
+  "main": "../dist/client/index.cjs",
+  "types": "../dist/client/index.d.ts",
+  "sideEffects": false
+}

package/core/package.json

@@ -0,0 +1,8 @@
+{
+  "//": "GENERATED by scripts/subpath-shims.mjs from the package.json \"exports\" map. Do not edit by hand; run `npm run build`.",
+  "react-native": "../dist/core/index.js",
+  "module": "../dist/core/index.js",
+  "main": "../dist/core/index.cjs",
+  "types": "../dist/core/index.d.ts",
+  "sideEffects": false
+}

package/dist/CameraPort-Cv31Pz7g.d.cts

@@ -0,0 +1,29 @@
+/** Opaque, host-defined capture request. Kept minimal at the spine; video/photo specs extend it. */
+interface CaptureOptions {
+    /** 'photo' | 'video'; the coarse capture mode a capability requests. */
+    readonly mode: 'photo' | 'video';
+    /** Optional soft ceiling for a video capture, in seconds. */
+    readonly maxDurationSeconds?: number;
+}
+/** Opaque handle to captured media the FilePort can upload. Server-owned shape is defined by video/photo. */
+interface MediaSource {
+    /** Local file URI produced by the capture. */
+    readonly uri: string;
+    /** MIME type, e.g. 'image/jpeg' | 'video/mp4'. */
+    readonly mimeType: string;
+    readonly widthPx?: number;
+    readonly heightPx?: number;
+    readonly durationSeconds?: number;
+}
+/**
+ * Camera capture. Absent (or an unavailable native peer) => `isAvailable:false`; the SDK never throws for a
+ * missing capability, it renders the OffState.
+ */
+interface CameraPort {
+    readonly isAvailable: boolean;
+    capture(opts: CaptureOptions): Promise<MediaSource>;
+}
+/** The safe absent default: capture is unavailable and never throws until explicitly awaited. */
+declare const unavailableCamera: CameraPort;
+
+export { type CameraPort as C, type MediaSource as M, type CaptureOptions as a, unavailableCamera as u };

package/dist/CameraPort-Cv31Pz7g.d.ts

@@ -0,0 +1,29 @@
+/** Opaque, host-defined capture request. Kept minimal at the spine; video/photo specs extend it. */
+interface CaptureOptions {
+    /** 'photo' | 'video'; the coarse capture mode a capability requests. */
+    readonly mode: 'photo' | 'video';
+    /** Optional soft ceiling for a video capture, in seconds. */
+    readonly maxDurationSeconds?: number;
+}
+/** Opaque handle to captured media the FilePort can upload. Server-owned shape is defined by video/photo. */
+interface MediaSource {
+    /** Local file URI produced by the capture. */
+    readonly uri: string;
+    /** MIME type, e.g. 'image/jpeg' | 'video/mp4'. */
+    readonly mimeType: string;
+    readonly widthPx?: number;
+    readonly heightPx?: number;
+    readonly durationSeconds?: number;
+}
+/**
+ * Camera capture. Absent (or an unavailable native peer) => `isAvailable:false`; the SDK never throws for a
+ * missing capability, it renders the OffState.
+ */
+interface CameraPort {
+    readonly isAvailable: boolean;
+    capture(opts: CaptureOptions): Promise<MediaSource>;
+}
+/** The safe absent default: capture is unavailable and never throws until explicitly awaited. */
+declare const unavailableCamera: CameraPort;
+
+export { type CameraPort as C, type MediaSource as M, type CaptureOptions as a, unavailableCamera as u };

package/dist/ChatController-CKdBvPj2.d.ts

@@ -0,0 +1,146 @@
+import { R as RequestFunnel } from './requestFunnel-dio5OmR9.js';
+import { A as AuthContext } from './identity-DK9zORrG.js';
+import { a as EverfurErrorCode, f as EverfurError, E as EverfurResult } from './EverfurResult-D92-uL82.js';
+import { b as ResponseId, a as ConversationId, P as PetRef } from './ids-CJ1S6adf.js';
+import { F as Frame } from './config-CiJ0PVBB.js';
+import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.js';
+
+/**
+ * Recovery policy. A host may narrow retry ceilings (e.g. a metered plan) but can never widen the SDK's
+ * settle-don't-throw contract. `attempt` is 0-based (the first try is attempt 0).
+ */
+interface ErrorPolicyPort {
+    /** Whether to retry `code` on this attempt. Default: `isAutoRetryable(code) && attempt < maxAttempts(code)`. */
+    shouldRetry(code: EverfurErrorCode, attempt: number): boolean;
+    /** Total attempts (the initial try plus retries) before the terminal error surfaces. Default 4. */
+    maxAttempts(code: EverfurErrorCode): number;
+    /** Observation hook for a handled, product-expected failure. Never rendered, never thrown. */
+    onExpectedFailure?(error: EverfurError): void;
+}
+/**
+ * The shipped default policy (applied when EverfurConfig omits `errorPolicy`). Pure and total.
+ * `authExpired` is deliberately NOT auto-retried here: it is a token refresh + single replay handled by the
+ * controller / authedSend, not a backoff retry (SPEC-00 §3.2 / §4.3).
+ */
+declare const defaultErrorPolicy: ErrorPolicyPort;
+
+/** Injectable timers so the watchdog + deadlines are testable with a fake clock (no direct setTimeout). */
+interface Timers {
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+
+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;
+    readonly citations?: readonly Citation[];
+    readonly responseId?: ResponseId;
+    /** Optimistic user bubble; removed if the turn fails BEFORE the first delta. */
+    readonly pending?: boolean;
+}
+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;
+    /**
+     * Flattened, de-duplicated suggested-prompt strings from the prompts bootstrap (backend-owned copy; 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[];
+}
+interface SendOptions {
+    readonly conversationId?: ConversationId;
+    readonly petRef?: PetRef;
+    readonly signal?: AbortSignal;
+    readonly idempotencyKey?: string;
+}
+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;
+    /** 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;
+}
+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;
+    /** 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 (§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;
+    /**
+     * 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;
+}
+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;
+
+export { type ChatController as C, type ErrorPolicyPort as E, MESSAGE_MAX_CHARS as M, type SuggestedPromptCategory as S, type Timers as T, type ChatControllerDeps as a, type ChatHandlers as b, type ChatMessage as c, type ChatSnapshot as d, type ChatStatus as e, type Citation as f, type SendOptions as g, createChatController as h, defaultErrorPolicy as i };

package/dist/ChatController-CpUMvvZf.d.cts

@@ -0,0 +1,146 @@
+import { R as RequestFunnel } from './requestFunnel-DuUH-kAe.cjs';
+import { A as AuthContext } from './identity-Brl-lDd6.cjs';
+import { a as EverfurErrorCode, f as EverfurError, E as EverfurResult } from './EverfurResult-D92-uL82.cjs';
+import { b as ResponseId, a as ConversationId, P as PetRef } from './ids-CJ1S6adf.cjs';
+import { F as Frame } from './config-BSjBdxrZ.cjs';
+import { T as TelemetryPort } from './TelemetryPort-BDNr00hu.cjs';
+
+/**
+ * Recovery policy. A host may narrow retry ceilings (e.g. a metered plan) but can never widen the SDK's
+ * settle-don't-throw contract. `attempt` is 0-based (the first try is attempt 0).
+ */
+interface ErrorPolicyPort {
+    /** Whether to retry `code` on this attempt. Default: `isAutoRetryable(code) && attempt < maxAttempts(code)`. */
+    shouldRetry(code: EverfurErrorCode, attempt: number): boolean;
+    /** Total attempts (the initial try plus retries) before the terminal error surfaces. Default 4. */
+    maxAttempts(code: EverfurErrorCode): number;
+    /** Observation hook for a handled, product-expected failure. Never rendered, never thrown. */
+    onExpectedFailure?(error: EverfurError): void;
+}
+/**
+ * The shipped default policy (applied when EverfurConfig omits `errorPolicy`). Pure and total.
+ * `authExpired` is deliberately NOT auto-retried here: it is a token refresh + single replay handled by the
+ * controller / authedSend, not a backoff retry (SPEC-00 §3.2 / §4.3).
+ */
+declare const defaultErrorPolicy: ErrorPolicyPort;
+
+/** Injectable timers so the watchdog + deadlines are testable with a fake clock (no direct setTimeout). */
+interface Timers {
+    setTimeout(handler: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    now(): number;
+}
+
+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;
+    readonly citations?: readonly Citation[];
+    readonly responseId?: ResponseId;
+    /** Optimistic user bubble; removed if the turn fails BEFORE the first delta. */
+    readonly pending?: boolean;
+}
+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;
+    /**
+     * Flattened, de-duplicated suggested-prompt strings from the prompts bootstrap (backend-owned copy; 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[];
+}
+interface SendOptions {
+    readonly conversationId?: ConversationId;
+    readonly petRef?: PetRef;
+    readonly signal?: AbortSignal;
+    readonly idempotencyKey?: string;
+}
+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;
+    /** 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;
+}
+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;
+    /** 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 (§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;
+    /**
+     * 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;
+}
+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;
+
+export { type ChatController as C, type ErrorPolicyPort as E, MESSAGE_MAX_CHARS as M, type SuggestedPromptCategory as S, type Timers as T, type ChatControllerDeps as a, type ChatHandlers as b, type ChatMessage as c, type ChatSnapshot as d, type ChatStatus as e, type Citation as f, type SendOptions as g, createChatController as h, defaultErrorPolicy as i };