@everfur/sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,17 +1,17 @@
-# @everfur/sdk (React Native)
+# @everfur/sdk (React Native and the web)
 
 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.
+media) into a React Native app, and the assistant into a website. 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.
+> `0.3.0`, MIT licensed, public on npm. Requires React Native `>=0.74` (or React `>=18` with `react-dom`
+> for the web entry), 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
@@ -21,7 +21,8 @@ publishable key is designed to ship inside your app; the secret key is not.
 
 ```bash
 npm i @everfur/sdk
-# Always-required peers:
+# A React Native app installs these itself (react-native and react-native-safe-area-context are declared
+# optional peers, so a web project is not handed them):
 npm i react react-native react-native-safe-area-context
 ```
 
@@ -30,17 +31,18 @@ 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 |
+| records | Host-supplied document picker and upload transport | The SDK does not import Expo file-system or image-manipulator modules. |
 | 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.
+The camera peer is optional: if you never mount `./video` or `./photo`, you do not need it.
+`EverfurRecords` accepts the host's picker and upload transport, so use the native modules that fit your
+app (including Expo SDK 57) without an SDK peer-dependency constraint. `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
+No Metro configuration is required. Every subpath (`@everfur/sdk/chat`, `/records`, `/televet`, `/video`, `/photo`,
+`/animations`, `/client`, `/core`, `/testing`, `/testing/rn`, `/testing/web`) 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
@@ -50,10 +52,33 @@ not change what you get.
 `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.
 
+### On the web
+
+Two ways, one wire contract, documented in
+[docs/partner-integration/13-WEB-INTEGRATION.md](docs/partner-integration/13-WEB-INTEGRATION.md):
+
+- **In-page**, for a page whose React tree you own: `import { EverfurProvider, EverfurChat } from
+  '@everfur/sdk/web'` (peers: `react`, `react-dom`). The copy-paste shape is
+  [`examples/minimal-web.tsx`](examples/minimal-web.tsx). Take the `/web` entry, not the package root: the
+  root is the React Native entry and imports `react-native` and `react-native-safe-area-context`, so in a
+  browser project it fails to resolve them rather than rendering. The `/web` entries need `react`,
+  `react/jsx-runtime` and `zod` and nothing native, which `npm run verify:pack` proves on every CI run by
+  importing all seven of them in a React web project.
+- **Frame mode**, for a page you do not fully control (a storefront theme, a CMS page): one `<script
+  src="https://sdk.everfur.com/v1/everfur.js">` puts the surface in an iframe on `sdk.everfur.com`, and
+  the frame refuses to initialise on any page origin your tenant has not registered. The copy-paste shape
+  is [`examples/frame-embed.html`](examples/frame-embed.html).
+
+Chat and records are the web surfaces (records on its own subpath and its own frame document, available
+when Everfur enables records for your account); photo and video remain React Native for now. Vet visits (not yet enabled)
+have their own entry on both hosts, `@everfur/sdk/web/televet` and `@everfur/sdk/televet`:
+[docs/partner-integration/16-TELEVET-VISITS.md](docs/partner-integration/16-TELEVET-VISITS.md).
+
 ## Quickstart
 
 Wrap your tree once, high, then drop features in behind a gate. This is the exact shape the reference app
-uses:
+uses, for a **React Native** host; a browser host imports the same names from `@everfur/sdk/web` (see [On
+the web](#on-the-web)):
 
 ```tsx
 import { EverfurProvider, EverfurChat, petRef, userRef } from '@everfur/sdk';
@@ -80,7 +105,9 @@ export default function App() {
 }
 ```
 
-`getToken` calls **your** backend for a short-lived session token (never a secret in the app):
+`getToken` calls **your** backend for a short-lived session token (never a secret in the app). Your route
+answers with the token as a plain-text body, which is the shape the MCP planner generates and every example
+in the docs uses:
 
 ```ts
 async function getToken(): Promise<string> {
@@ -88,13 +115,14 @@ async function getToken(): Promise<string> {
     method: 'POST',
     headers: { authorization: `Bearer ${yourAppsUserToken}` },
   });
-  const { sessionToken } = await res.json();
-  return sessionToken;
+  if (!res.ok) throw new Error('session mint failed: ' + res.status);
+  return res.text();
 }
 ```
 
 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:
+you managing expiry. Everfur never sees how you signed the person in (OAuth, a JWT, Firebase, Cognito, a
+session, a magic link all work); it needs one stable, opaque, non-guessable id per person as `userRef`. Records lives on its own subpath:
 
 ```tsx
 import { EverfurRecords } from '@everfur/sdk/records';
@@ -105,13 +133,16 @@ import { petRef } from '@everfur/sdk';
 
 ## The security model
 
-The one rule: **the app never holds a secret.** Two credentials, kept apart.
+The one rule: **the app never holds a secret.** Two provisioning credentials, kept apart, plus a read-only
+docs key for tooling. Test mode is a sandbox tenant on the staging API with an ordinary `pk_live_` key
+(`livemode: false` in its entitlements); no deployed environment accepts a `pk_test_` key.
 
 | 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. |
+| Session token (bearer) | App memory, short-lived. | Authenticates one end user; re-minted via your backend on a 401. Signed, holds no secret, 15 minutes by default (1 minute to 1 hour). |
+| Docs key `dk_partner_...` | Only in the MCP server or CLI configuration on a developer machine. | Read-only: fetches the Everfur contract from `GET /partners/contract` and opens no other route. |
 
 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:
@@ -141,12 +172,16 @@ off-state, never a blank region.
 | 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/records` | `EverfurRecords`, `EverfurClinicRequest`, `EverfurClinicRequestBatch`, `SignaturePad`, records hooks + types |
+| `@everfur/sdk/records/depth`, `@everfur/sdk/web/records/depth` | record depth (the timeline, the withheld record sections, per-document contributions) on their own entries, dark until Everfur enables it per deployment; see [chapter 9](docs/partner-integration/09-GUIDE-RECORDS-AND-CONSENT.md#record-depth-behind-a-separate-switch) |
 | `@everfur/sdk/video` | gait / live-scan surface |
 | `@everfur/sdk/photo` | photo checkup surface |
 | `@everfur/sdk/animations` | server-driven pet-state media surface |
+| `@everfur/sdk/web` | the browser entry: `EverfurProvider`, `CapabilityGate`, `EverfurChat`, `useEverfurChat`, the theme hook, rendered with `react-dom`; withheld from React Native bundles the way `./server` is |
+| `@everfur/sdk/web/records` | records for a browser host: `EverfurRecords`, `useEverfurRecords`, `createWebRecordsUploadTransport`, `fileToHandle`; its own entry, withheld from React Native like `./web`; available when Everfur enables records for the account. Frame mode serves it with `surface: 'records'` (see [chapter 13](docs/partner-integration/13-WEB-INTEGRATION.md)) |
 | `@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/server/events` | **server-only, Node only** partner events (preview): `constructEvent` to verify webhooks, `sendPartnerEvent`; see [chapter 15](docs/partner-integration/15-EVENTS-AND-WEBHOOKS.md) |
+| `@everfur/sdk/testing`, `@everfur/sdk/testing/rn`, `@everfur/sdk/testing/web` | test seams (`MockTransport`, `useEverfurTestEntitlements`, ...) 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.
@@ -154,7 +189,7 @@ 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
+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

package/consent/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/consent/index.js",
+  "module": "../dist/consent/index.js",
+  "main": "../dist/consent/index.cjs",
+  "types": "../dist/consent/index.d.ts",
+  "sideEffects": false
+}

package/dist/Chat-DPUD6dnc.d.cts

@@ -0,0 +1,128 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+import { P as PetRef, C as ConversationId } from './ids-B2GAAifq.cjs';
+import { F as FileHandle } from './ports-BN6RHF9W.cjs';
+import { a as ChatCheckinTarget } from './ports-DEBzEhbp.cjs';
+import { b as WidgetPet, P as PetProfileInput } from './casesRepository-DHwtGRYY.cjs';
+import { U as UrgencyDisplayLevel, L as LifecyclePort, E as EverfurChatDraftStore } from './attachments-D8T5re7e.cjs';
+
+/** Where a picked image comes from: the host's photo library, or its camera. */
+type AttachmentSource = 'photo' | 'camera';
+
+/** The host's own action for the two vet-care tiers, in place of Everfur's pill. */
+type RenderVetAction = (level: UrgencyDisplayLevel) => ReactNode;
+
+/**
+ * The host's image picker for chat attachments. The SDK depends on no picker or camera module: open your own
+ * (for example `expo-image-picker`'s `launchImageLibraryAsync({ mediaTypes: ['images'] })`, or your camera
+ * screen) and resolve `null` when the user cancels, else one `FileHandle` or several (a multi-select pick),
+ * each with the local `uri`, the image `mimeType` (`image/jpeg`, `image/png`, `image/webp`, `image/heic`,
+ * `image/heif`) and `sizeBytes`. The queue validates type and size (10 MiB) before any request.
+ *
+ * RESIZING AND EXIF ARE YOURS. The consumer app resizes to 1920 px, re-encodes as JPEG 0.85 and strips EXIF
+ * (location, device) before an upload; the SDK uploads the bytes at the `uri` as they are, so do the same in
+ * `pick` (for example with `expo-image-manipulator`) before resolving.
+ */
+interface EverfurChatAttachments {
+    readonly pick: (source: AttachmentSource) => Promise<FileHandle | readonly FileHandle[] | null>;
+    /** The sources to offer, one popover tile each; default `['photo']`. */
+    readonly sources?: readonly AttachmentSource[];
+    /** Images per message; default 1 (the app's composer), at most 5 (the server's cap). */
+    readonly maxPerMessage?: number;
+}
+interface EverfurChatProps {
+    readonly petRef?: PetRef;
+    readonly conversationId?: ConversationId;
+    readonly style?: StyleProp<ViewStyle>;
+    /**
+     * Your own placeholder for the two moments Everfur would otherwise draw a waiting view of its own: the
+     * entitlement verdict still pending, and the chat still bootstrapping on a cold mount. Return null to draw
+     * nothing. A mount `prepare()` warmed up never reaches either. Absent, Everfur's skeleton and delayed spinner.
+     */
+    readonly renderPending?: () => ReactNode;
+    /**
+     * Your clipboard (for example `expo-clipboard`'s `setStringAsync`). Given, every message gets the app's
+     * copy control; absent, no copy control renders (the SDK depends on no clipboard module).
+     */
+    readonly onCopy?: (text: string) => Promise<void> | void;
+    /** Called after the user picked another pet in the header switcher and the provider re-scoped to it. */
+    readonly onPetChange?: (petRef: PetRef) => void;
+    /**
+     * Your vet-visit preparation screen. Given, the empty thread's `Help me prep for {pet}'s vet visit.` chip
+     * routes to it with the pet; absent, that chip is the Everfur vet visit entry inside Chat, shown only
+     * while Everfur has it switched on for your tenant, else not shown at all.
+     */
+    readonly onVetPrep?: (pet: WidgetPet | null) => void;
+    /**
+     * Your vet finder. On an `emergency` or `schedule_soon` reply the banner's `Find a vet` pill opens the
+     * Everfur vet visit entry when it is on for your tenant, else calls this, else does not render.
+     */
+    readonly onFindVet?: (level: UrgencyDisplayLevel) => void;
+    /** Your own control in the banner's action slot for those two tiers, in place of the pill. */
+    readonly renderVetAction?: RenderVetAction;
+    /** Your image picker: given, the composer gets the app's attachment control, previews and lightbox. */
+    readonly attachments?: EverfurChatAttachments;
+    /**
+     * The pet this chat is about, as YOUR system holds it: the whole partner pet body (name, species, breed,
+     * age, weight, and every health field, allergies, medications, supplements and conditions included). Given
+     * with `petRef`, the surface registers it with Everfur once, before the first conversation, and then names
+     * it in the header and the switcher. Nothing is trimmed: what you pass is what is sent.
+     */
+    readonly pet?: PetProfileInput;
+    /**
+     * Your own add-a-pet screen. Given, the switcher gets an `Add another pet` row, and a chat that cannot start
+     * because the `petRef` is not registered offers `Add a pet` in place of a retry that could only fail again.
+     * Absent, neither control is drawn: the partner plane never shows a route Everfur cannot honour.
+     */
+    readonly onAddPet?: () => void;
+    /**
+     * The check-in a tapped Everfur push is about: the `case` target `parseEverfurNotification` returned. Chat
+     * opens that thread on mount, once per target, so a due follow-up question is the first thing the member
+     * sees instead of something they would have to find in the history drawer. Absent, chat opens as usual.
+     */
+    readonly checkinTarget?: ChatCheckinTarget;
+    /**
+     * A question to ask on arrival, in a conversation of its own: the prompt one of your own screens built
+     * (an Everfur records "Ask Everfur" pill hands you one). It is asked once, after chat has finished
+     * opening, and the thread that was on screen is left behind so the answer is not buried in an unrelated
+     * conversation. Pass `composerSeed` instead when the user should decide whether to send it.
+     */
+    readonly initialAsk?: string;
+    /**
+     * Text to put in the composer on arrival. It is never sent for the user: they edit it, send it or clear
+     * it. Only an empty composer is seeded, so nothing they typed is ever replaced.
+     */
+    readonly composerSeed?: string;
+    /**
+     * Your app's lifecycle signals. Everfur has no socket and no polling here, so a message the platform
+     * writes into the thread (a follow-up check-in, a reminder) is not visible until something re-reads it.
+     * Tell Everfur when your app comes back to the foreground, when connectivity returns and when a push
+     * announced a change, and the thread and the unread dot catch up on that signal alone. Without this, chat
+     * refreshes only when the user does something.
+     */
+    readonly lifecycle?: LifecyclePort;
+    /**
+     * Your own storage for an unsent draft. Given, what the user typed and did not send survives leaving this
+     * screen; absent, the draft lives in memory for as long as the surface is mounted and nowhere else.
+     * Everfur writes a draft down only through this.
+     */
+    readonly draftStore?: EverfurChatDraftStore;
+    /**
+     * The KEY of a return destination your tenant registered with Everfur. Every vet entry inside chat (the
+     * header, the urgency banner's pill and the empty thread's vet-prep chip) then sends the user back to your
+     * app when the visit ends.
+     */
+    readonly vetReturnTo?: string;
+    /**
+     * The user's US state (for example `'CA'`). Set it and no vet entry is drawn until Everfur confirms a visit
+     * is available there, so it is never offered to someone who could not book.
+     */
+    readonly vetUsState?: string;
+}
+/**
+ * Entitlement-gated, four-state chat surface. Entitlement-OFF renders the CapabilityGate OffState;
+ * otherwise the body maps the controller snapshot to exactly one deliberate state.
+ */
+declare function EverfurChat(props: EverfurChatProps): ReactNode;
+
+export { type AttachmentSource as A, EverfurChat as E, type RenderVetAction as R, type EverfurChatAttachments as a, type EverfurChatProps as b };

package/dist/Chat-DwAC2vhB.d.ts

@@ -0,0 +1,128 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+import { P as PetRef, C as ConversationId } from './ids-B2GAAifq.js';
+import { F as FileHandle } from './ports-BN6RHF9W.js';
+import { a as ChatCheckinTarget } from './ports-DMolTRzU.js';
+import { b as WidgetPet, P as PetProfileInput } from './casesRepository-ClLv6qMl.js';
+import { U as UrgencyDisplayLevel, L as LifecyclePort, E as EverfurChatDraftStore } from './attachments-5NeobOCd.js';
+
+/** Where a picked image comes from: the host's photo library, or its camera. */
+type AttachmentSource = 'photo' | 'camera';
+
+/** The host's own action for the two vet-care tiers, in place of Everfur's pill. */
+type RenderVetAction = (level: UrgencyDisplayLevel) => ReactNode;
+
+/**
+ * The host's image picker for chat attachments. The SDK depends on no picker or camera module: open your own
+ * (for example `expo-image-picker`'s `launchImageLibraryAsync({ mediaTypes: ['images'] })`, or your camera
+ * screen) and resolve `null` when the user cancels, else one `FileHandle` or several (a multi-select pick),
+ * each with the local `uri`, the image `mimeType` (`image/jpeg`, `image/png`, `image/webp`, `image/heic`,
+ * `image/heif`) and `sizeBytes`. The queue validates type and size (10 MiB) before any request.
+ *
+ * RESIZING AND EXIF ARE YOURS. The consumer app resizes to 1920 px, re-encodes as JPEG 0.85 and strips EXIF
+ * (location, device) before an upload; the SDK uploads the bytes at the `uri` as they are, so do the same in
+ * `pick` (for example with `expo-image-manipulator`) before resolving.
+ */
+interface EverfurChatAttachments {
+    readonly pick: (source: AttachmentSource) => Promise<FileHandle | readonly FileHandle[] | null>;
+    /** The sources to offer, one popover tile each; default `['photo']`. */
+    readonly sources?: readonly AttachmentSource[];
+    /** Images per message; default 1 (the app's composer), at most 5 (the server's cap). */
+    readonly maxPerMessage?: number;
+}
+interface EverfurChatProps {
+    readonly petRef?: PetRef;
+    readonly conversationId?: ConversationId;
+    readonly style?: StyleProp<ViewStyle>;
+    /**
+     * Your own placeholder for the two moments Everfur would otherwise draw a waiting view of its own: the
+     * entitlement verdict still pending, and the chat still bootstrapping on a cold mount. Return null to draw
+     * nothing. A mount `prepare()` warmed up never reaches either. Absent, Everfur's skeleton and delayed spinner.
+     */
+    readonly renderPending?: () => ReactNode;
+    /**
+     * Your clipboard (for example `expo-clipboard`'s `setStringAsync`). Given, every message gets the app's
+     * copy control; absent, no copy control renders (the SDK depends on no clipboard module).
+     */
+    readonly onCopy?: (text: string) => Promise<void> | void;
+    /** Called after the user picked another pet in the header switcher and the provider re-scoped to it. */
+    readonly onPetChange?: (petRef: PetRef) => void;
+    /**
+     * Your vet-visit preparation screen. Given, the empty thread's `Help me prep for {pet}'s vet visit.` chip
+     * routes to it with the pet; absent, that chip is the Everfur vet visit entry inside Chat, shown only
+     * while Everfur has it switched on for your tenant, else not shown at all.
+     */
+    readonly onVetPrep?: (pet: WidgetPet | null) => void;
+    /**
+     * Your vet finder. On an `emergency` or `schedule_soon` reply the banner's `Find a vet` pill opens the
+     * Everfur vet visit entry when it is on for your tenant, else calls this, else does not render.
+     */
+    readonly onFindVet?: (level: UrgencyDisplayLevel) => void;
+    /** Your own control in the banner's action slot for those two tiers, in place of the pill. */
+    readonly renderVetAction?: RenderVetAction;
+    /** Your image picker: given, the composer gets the app's attachment control, previews and lightbox. */
+    readonly attachments?: EverfurChatAttachments;
+    /**
+     * The pet this chat is about, as YOUR system holds it: the whole partner pet body (name, species, breed,
+     * age, weight, and every health field, allergies, medications, supplements and conditions included). Given
+     * with `petRef`, the surface registers it with Everfur once, before the first conversation, and then names
+     * it in the header and the switcher. Nothing is trimmed: what you pass is what is sent.
+     */
+    readonly pet?: PetProfileInput;
+    /**
+     * Your own add-a-pet screen. Given, the switcher gets an `Add another pet` row, and a chat that cannot start
+     * because the `petRef` is not registered offers `Add a pet` in place of a retry that could only fail again.
+     * Absent, neither control is drawn: the partner plane never shows a route Everfur cannot honour.
+     */
+    readonly onAddPet?: () => void;
+    /**
+     * The check-in a tapped Everfur push is about: the `case` target `parseEverfurNotification` returned. Chat
+     * opens that thread on mount, once per target, so a due follow-up question is the first thing the member
+     * sees instead of something they would have to find in the history drawer. Absent, chat opens as usual.
+     */
+    readonly checkinTarget?: ChatCheckinTarget;
+    /**
+     * A question to ask on arrival, in a conversation of its own: the prompt one of your own screens built
+     * (an Everfur records "Ask Everfur" pill hands you one). It is asked once, after chat has finished
+     * opening, and the thread that was on screen is left behind so the answer is not buried in an unrelated
+     * conversation. Pass `composerSeed` instead when the user should decide whether to send it.
+     */
+    readonly initialAsk?: string;
+    /**
+     * Text to put in the composer on arrival. It is never sent for the user: they edit it, send it or clear
+     * it. Only an empty composer is seeded, so nothing they typed is ever replaced.
+     */
+    readonly composerSeed?: string;
+    /**
+     * Your app's lifecycle signals. Everfur has no socket and no polling here, so a message the platform
+     * writes into the thread (a follow-up check-in, a reminder) is not visible until something re-reads it.
+     * Tell Everfur when your app comes back to the foreground, when connectivity returns and when a push
+     * announced a change, and the thread and the unread dot catch up on that signal alone. Without this, chat
+     * refreshes only when the user does something.
+     */
+    readonly lifecycle?: LifecyclePort;
+    /**
+     * Your own storage for an unsent draft. Given, what the user typed and did not send survives leaving this
+     * screen; absent, the draft lives in memory for as long as the surface is mounted and nowhere else.
+     * Everfur writes a draft down only through this.
+     */
+    readonly draftStore?: EverfurChatDraftStore;
+    /**
+     * The KEY of a return destination your tenant registered with Everfur. Every vet entry inside chat (the
+     * header, the urgency banner's pill and the empty thread's vet-prep chip) then sends the user back to your
+     * app when the visit ends.
+     */
+    readonly vetReturnTo?: string;
+    /**
+     * The user's US state (for example `'CA'`). Set it and no vet entry is drawn until Everfur confirms a visit
+     * is available there, so it is never offered to someone who could not book.
+     */
+    readonly vetUsState?: string;
+}
+/**
+ * Entitlement-gated, four-state chat surface. Entitlement-OFF renders the CapabilityGate OffState;
+ * otherwise the body maps the controller snapshot to exactly one deliberate state.
+ */
+declare function EverfurChat(props: EverfurChatProps): ReactNode;
+
+export { type AttachmentSource as A, EverfurChat as E, type RenderVetAction as R, type EverfurChatAttachments as a, type EverfurChatProps as b };

package/dist/DepthViews-DNEM96Se.d.ts

@@ -0,0 +1,16 @@
+import { CSSProperties, ReactNode } from 'react';
+import { f as RecordsScreenBaseProps } from './useRecordsDepth-BU-OhzH6.js';
+
+interface EverfurRecordsDepthProps extends Pick<RecordsScreenBaseProps, 'petRef' | 'petName' | 'onNavigate' | 'onBack'> {
+    readonly style?: CSSProperties;
+    readonly className?: string;
+}
+interface EverfurDocumentContributionsProps extends EverfurRecordsDepthProps {
+    /** A `docId` from the record's `documents`. */
+    readonly docId: string;
+}
+declare function EverfurRecordsTimeline({ petRef, style, className, onBack }: EverfurRecordsDepthProps): ReactNode;
+declare function EverfurRecordDepth({ petRef, style, className, onBack }: EverfurRecordsDepthProps): ReactNode;
+declare function EverfurDocumentContributions({ petRef, docId, style, className, onBack }: EverfurDocumentContributionsProps): ReactNode;
+
+export { EverfurDocumentContributions as E, type EverfurDocumentContributionsProps as a, EverfurRecordDepth as b, type EverfurRecordsDepthProps as c, EverfurRecordsTimeline as d };

package/dist/DepthViews-DP0R-DhB.d.cts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+import { f as RecordsScreenBaseProps } from './useRecordsDepth-BHBzJ76R.cjs';
+
+interface EverfurRecordsDepthProps extends Pick<RecordsScreenBaseProps, 'petRef' | 'petName' | 'onNavigate' | 'onBack'> {
+    readonly style?: StyleProp<ViewStyle>;
+}
+interface EverfurDocumentContributionsProps extends EverfurRecordsDepthProps {
+    /** A `docId` from the record's `documents`. */
+    readonly docId: string;
+}
+/** The consumer timeline screen: `Timeline` over visits, vaccines, weights and medications merged newest first. */
+declare function EverfurRecordsTimeline({ petRef, style, onBack }: EverfurRecordsDepthProps): ReactNode;
+/** The four sections the base record withholds: lab work, visits, physical exams and visit notes. */
+declare function EverfurRecordDepth({ petRef, style, onBack }: EverfurRecordsDepthProps): ReactNode;
+/** What one published document contributed to the record, in the record's own row vocabulary. */
+declare function EverfurDocumentContributions({ petRef, docId, style, onBack }: EverfurDocumentContributionsProps): ReactNode;
+
+export { EverfurDocumentContributions as E, type EverfurDocumentContributionsProps as a, EverfurRecordDepth as b, type EverfurRecordsDepthProps as c, EverfurRecordsTimeline as d };

package/dist/DepthViews-D_3hl4xk.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+import { f as RecordsScreenBaseProps } from './useRecordsDepth-BU-OhzH6.js';
+
+interface EverfurRecordsDepthProps extends Pick<RecordsScreenBaseProps, 'petRef' | 'petName' | 'onNavigate' | 'onBack'> {
+    readonly style?: StyleProp<ViewStyle>;
+}
+interface EverfurDocumentContributionsProps extends EverfurRecordsDepthProps {
+    /** A `docId` from the record's `documents`. */
+    readonly docId: string;
+}
+/** The consumer timeline screen: `Timeline` over visits, vaccines, weights and medications merged newest first. */
+declare function EverfurRecordsTimeline({ petRef, style, onBack }: EverfurRecordsDepthProps): ReactNode;
+/** The four sections the base record withholds: lab work, visits, physical exams and visit notes. */
+declare function EverfurRecordDepth({ petRef, style, onBack }: EverfurRecordsDepthProps): ReactNode;
+/** What one published document contributed to the record, in the record's own row vocabulary. */
+declare function EverfurDocumentContributions({ petRef, docId, style, onBack }: EverfurDocumentContributionsProps): ReactNode;
+
+export { EverfurDocumentContributions as E, type EverfurDocumentContributionsProps as a, EverfurRecordDepth as b, type EverfurRecordsDepthProps as c, EverfurRecordsTimeline as d };

package/dist/DepthViews-DbFhR4Du.d.cts

@@ -0,0 +1,16 @@
+import { CSSProperties, ReactNode } from 'react';
+import { f as RecordsScreenBaseProps } from './useRecordsDepth-BHBzJ76R.cjs';
+
+interface EverfurRecordsDepthProps extends Pick<RecordsScreenBaseProps, 'petRef' | 'petName' | 'onNavigate' | 'onBack'> {
+    readonly style?: CSSProperties;
+    readonly className?: string;
+}
+interface EverfurDocumentContributionsProps extends EverfurRecordsDepthProps {
+    /** A `docId` from the record's `documents`. */
+    readonly docId: string;
+}
+declare function EverfurRecordsTimeline({ petRef, style, className, onBack }: EverfurRecordsDepthProps): ReactNode;
+declare function EverfurRecordDepth({ petRef, style, className, onBack }: EverfurRecordsDepthProps): ReactNode;
+declare function EverfurDocumentContributions({ petRef, docId, style, className, onBack }: EverfurDocumentContributionsProps): ReactNode;
+
+export { EverfurDocumentContributions as E, type EverfurDocumentContributionsProps as a, EverfurRecordDepth as b, type EverfurRecordsDepthProps as c, EverfurRecordsTimeline as d };

package/dist/ErrorPolicyPort-CNf4uQZP.d.cts

@@ -0,0 +1,22 @@
+import { b as EverfurErrorCode, E as EverfurError } from './EverfurResult-DN9pL2Ab.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;
+
+export { type ErrorPolicyPort as E, defaultErrorPolicy as d };

package/dist/ErrorPolicyPort-CwbfmxzJ.d.ts

@@ -0,0 +1,22 @@
+import { b as EverfurErrorCode, E as EverfurError } from './EverfurResult-DN9pL2Ab.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;
+
+export { type ErrorPolicyPort as E, defaultErrorPolicy as d };

package/dist/{EverfurResult-D92-uL82.d.cts → EverfurResult-DN9pL2Ab.d.cts}

@@ -131,6 +131,12 @@ interface EverfurError {
     readonly requestId?: string;
     /** Site-relative documentation path for the wire code, from the contract registry. No host is implied. */
     readonly docUrl?: string;
+    /**
+     * The server's stable sub-reason for this failure, when it sent one (for example `pet_not_registered` or
+     * `species_unsupported` on the records routes). Safe to branch on, unlike `wireMessage`. Only a lowercase
+     * snake_case token is kept; anything else is dropped rather than carried.
+     */
+    readonly reasonCode?: string;
     /** raw wire text; telemetry / logs only, NEVER rendered. NON-ENUMERABLE. */
     readonly wireMessage?: string;
     /** Opaque parsed wire payload for debugging (untrusted, unvalidated). NON-ENUMERABLE. */
@@ -155,20 +161,15 @@ interface MakeEverfurErrorOptions {
      * the code exactly as the server sent it; a code that is not in the registry simply yields no docUrl.
      */
     readonly wireCode?: string | null;
+    /** The envelope the wire code arrived in, when known; a code registered on both envelopes resolves to its own row. */
+    readonly wireEnvelope?: 'http_envelope' | 'sse_frame';
     /** Untrusted wire text. Carried NON-ENUMERABLY for telemetry; never rendered. */
     readonly wireMessage?: string | null;
+    /** The server's `reason_code`, kept only when it is a lowercase snake_case token (see `EverfurError.reasonCode`). */
+    readonly reasonCode?: string | null;
     /** Opaque parsed wire payload. Carried NON-ENUMERABLY for debugging; never rendered. */
     readonly raw?: unknown;
 }
-/**
- * Build a normalized, frozen `EverfurError` from a normalized code plus optional wire/HTTP context.
- *
- * `displayMessage` is always the SAFE code-derived string. `retryable` defaults to the code's policy
- * (`isRetryableCode`) unless the caller overrides it, e.g. a frame carrying explicit `retryable:true`.
- * `requestId` and `docUrl` are the two support-facing additions: the id a partner quotes, and the
- * site-relative registry path for the wire code. `wireMessage` and `raw` are carried NON-ENUMERABLY and
- * are dropped when empty.
- */
 declare function makeEverfurError(code: EverfurErrorCode, opts?: MakeEverfurErrorOptions): EverfurError;
 
 /**
@@ -237,4 +238,4 @@ declare class EverfurConfigError extends Error {
     constructor(kind: 'not-initialized' | 'invalid-argument' | 'missing-peer-dependency', message: string);
 }
 
-export { AUTO_RETRYABLE_CODES as A, BACKOFF_BASE_MS as B, type EverfurResult as E, MAX_RETRY_ATTEMPTS as M, RETRYABLE_CONTRACT_CODES as R, type EverfurErrorCode as a, BACKOFF_CAP_MS as b, EVERFUR_ERROR_CATEGORIES as c, EVERFUR_ERROR_CODES as d, EverfurConfigError as e, type EverfurError as f, type EverfurErrorCategory as g, EverfurThrownError as h, type MakeEverfurErrorOptions as i, backoffDelayMs as j, canRecreateOnNotFound as k, categoryFor as l, err as m, fromHttpStatus as n, fromWire as o, isAutoRetryable as p, isErr as q, isOk as r, isRetryableCode as s, makeEverfurError as t, ok as u, shouldRetry as v, unwrap as w, userFacingError as x };
+export { AUTO_RETRYABLE_CODES as A, BACKOFF_BASE_MS as B, type EverfurError as E, MAX_RETRY_ATTEMPTS as M, RETRYABLE_CONTRACT_CODES as R, type EverfurErrorCategory as a, type EverfurErrorCode as b, type EverfurResult as c, EverfurConfigError as d, EverfurThrownError as e, categoryFor as f, isOk as g, isRetryableCode as h, isErr as i, userFacingError as j, BACKOFF_CAP_MS as k, EVERFUR_ERROR_CATEGORIES as l, EVERFUR_ERROR_CODES as m, type MakeEverfurErrorOptions as n, backoffDelayMs as o, canRecreateOnNotFound as p, err as q, fromHttpStatus as r, fromWire as s, isAutoRetryable as t, unwrap as u, makeEverfurError as v, ok as w, shouldRetry as x };