@everfur/sdk 0.1.0 → 0.3.0

package/dist/useRecordsDepth-BHBzJ76R.d.cts

@@ -0,0 +1,237 @@
+import { R as RecordsRequestId, P as PetRef } from './ids-B2GAAifq.cjs';
+import { a5 as RecordsClinicSearchInput, a6 as RecordsClinicSearchPage, a7 as RecordsRecentClinicsInput, a8 as RecordsAuthorizationCopy, a9 as CreateClinicRequestInput, aa as RecordsSignatureUploadPolicy, l as RecordsClinic, O as RecordsClinicBatch, P as RecordsClinicBatchClient, m as RecordsDepthClient } from './depth-CErXCU8J.cjs';
+import { c as EverfurResult, E as EverfurError } from './EverfurResult-DN9pL2Ab.cjs';
+import { f as RecordsRequestGroupView, d as RecordsRequestView } from './models-D2EUxPZY.cjs';
+
+interface RecordsClinicController {
+    searchClinics(input?: RecordsClinicSearchInput): Promise<EverfurResult<RecordsClinicSearchPage>>;
+    /** The clinics this member requested from before, most recent first: the picker's "recent" section. */
+    recentClinics(input?: RecordsRecentClinicsInput): Promise<EverfurResult<RecordsClinicSearchPage>>;
+    /** A multi-clinic batch's rollup and members. Not found until Everfur switches the multi-clinic flag on. */
+    getRequestGroup(requestGroupId: string): Promise<EverfurResult<RecordsRequestGroupView>>;
+    getAuthorizationCopy(): Promise<EverfurResult<RecordsAuthorizationCopy>>;
+    createClinicRequest(input: CreateClinicRequestInput): Promise<EverfurResult<RecordsRequestView>>;
+    retryRequest(id: RecordsRequestId): Promise<EverfurResult<RecordsRequestView>>;
+    revokeRequest(id: RecordsRequestId): Promise<EverfurResult<RecordsRequestView>>;
+    updateClinicEmail(id: RecordsRequestId, clinicEmail: string): Promise<EverfurResult<RecordsRequestView>>;
+    convertToUpload(id: RecordsRequestId): Promise<EverfurResult<RecordsRequestView>>;
+    /** Bytes are uploaded by the host directly to the returned multipart policy; never through the API. */
+    initiateSignatureUpload(fileSize: number): Promise<EverfurResult<RecordsSignatureUploadPolicy>>;
+    completeSignatureUpload(uploadId: string): Promise<EverfurResult<string>>;
+}
+
+/** The exact owner-visible scope at the moment the owner chooses to sign. */
+interface RecordsSignatureContext {
+    readonly petRef: PetRef;
+    readonly petName: string;
+    readonly ownerName: string;
+    readonly clinicName: string;
+    readonly authorizationVersion: string;
+    readonly scopeText: string;
+    /** Cancel native capture/upload when the signed-in user or active pet changes. */
+    readonly signal: AbortSignal;
+}
+/**
+ * A captured signature: a registered signature id (the PNG uploaded through the initiate/complete APIs, the
+ * consumer's own path, which keeps the bytes off the JSON body), or a small inline PNG (the built-in React
+ * Native pad's one-bit image, a few hundred bytes, under the platform's non-upload body cap).
+ */
+type CapturedRecordsSignature = {
+    readonly signatureId: string;
+    readonly signaturePngBase64?: never;
+} | {
+    readonly signatureId?: never;
+    readonly signaturePngBase64: string;
+};
+/**
+ * Capture explicitly at the moment the owner presses Send, after seeing the scope, and return the signature.
+ * null means the owner cancelled. Prefer the registered id for anything but a tiny PNG.
+ */
+type CaptureRecordsSignature = (context: RecordsSignatureContext) => Promise<CapturedRecordsSignature | null>;
+interface ClinicRequestBaseProps {
+    readonly petRef: PetRef;
+    /** Display name for this exact registered petRef; the server owns the final PDF identity. */
+    readonly petName: string;
+    /** Initial value only; the owner can visibly confirm or correct it before signing. */
+    readonly ownerName: string;
+    readonly onCaptureSignature?: CaptureRecordsSignature;
+    readonly onCreated?: (request: RecordsRequestView) => void;
+    readonly onClose?: () => void;
+    /** Host/test seam over the same signed-user controller contract. */
+    readonly controller?: RecordsClinicController;
+}
+
+/** One composed clinic of the batch (the consumer `ClinicRequestDraft`). */
+interface ClinicDraft {
+    /** Stable local key for list rows and removal. */
+    readonly key: string;
+    /** The directory clinic, or null for an owner-typed clinic name. */
+    readonly clinic: RecordsClinic | null;
+    /** The owner-typed clinic name when `clinic` is null. */
+    readonly freeText: string | null;
+    /** The owner-supplied address, when the clinic needs one. */
+    readonly email: string;
+    /** Minted when the draft is added; a whole-batch retry replays it. */
+    readonly idempotencyKey: string;
+}
+interface ClinicBatchBaseProps {
+    readonly petRef: PetRef;
+    /** Display name for this exact registered petRef; the server owns the final PDF identity. */
+    readonly petName: string;
+    /** Initial value only; the owner can visibly confirm or correct it before signing. */
+    readonly ownerName: string;
+    readonly onCaptureSignature?: CaptureRecordsSignature;
+    /** Called once with the batch outcome (created and failed clinics alike). */
+    readonly onCreated?: (batch: RecordsClinicBatch) => void;
+    readonly onClose?: () => void;
+    /** Host/test seams over the same signed-user contracts. */
+    readonly controller?: RecordsClinicController;
+    readonly batchClient?: RecordsClinicBatchClient;
+}
+/**
+ * Turn the pad's inline PNG into a registered signature id, so the batch carries one small id per clinic rather
+ * than one PNG per clinic (the platform caps the inline bytes of a batch at one signature's worth, and the WAF
+ * caps the JSON body). The host supplies the byte transport; the RN and web hosts each have one.
+ */
+type RegisterSignaturePng = (signaturePngBase64: string, signal: AbortSignal) => Promise<{
+    readonly signatureId: string;
+}>;
+
+type RecordsScreen = {
+    readonly name: 'dashboard';
+} | {
+    readonly name: 'request';
+    readonly requestId: RecordsRequestId;
+} | {
+    readonly name: 'timeline';
+} | {
+    readonly name: 'record';
+} | {
+    readonly name: 'document';
+} | {
+    readonly name: 'contributions';
+    readonly docId: string;
+} | {
+    readonly name: 'clinicPicker';
+}
+/**
+ * The multi-clinic composer (`EverfurClinicRequestBatch`). The consumer opens it as a SHEET from the full
+ * record screen's header (RequestFromClinicsAction.tsx); the SDK flow has no sheet layer of its own, so it is
+ * a screen of the same stack, pushed from the same control and popped by the same back.
+ */
+ | {
+    readonly name: 'clinicBatch';
+} | {
+    readonly name: 'consent';
+    readonly clinic: ClinicDraft;
+} | {
+    readonly name: 'upload';
+};
+interface RecordsNavState {
+    readonly stack: readonly RecordsScreen[];
+}
+type RecordsNavAction = {
+    readonly type: 'push';
+    readonly screen: RecordsScreen;
+} | {
+    readonly type: 'pop';
+} | {
+    readonly type: 'replace';
+    readonly screen: RecordsScreen;
+} | {
+    readonly type: 'reset';
+    readonly screen: RecordsScreen;
+}
+/** The screen-declared edge: applies the consumer's push / replace / reset rule for the (from, to) pair. */
+ | {
+    readonly type: 'navigate';
+    readonly screen: RecordsScreen;
+};
+/** A one-screen stack at `initial` (the dashboard when omitted). */
+declare function initialRecordsNav(initial?: RecordsScreen): RecordsNavState;
+/** The screen on top of the stack (a stack is never empty). */
+declare function currentRecordsScreen(state: RecordsNavState): RecordsScreen;
+declare function pushRecordsNav(state: RecordsNavState, screen: RecordsScreen): RecordsNavState;
+declare function replaceRecordsNav(state: RecordsNavState, screen: RecordsScreen): RecordsNavState;
+declare function resetRecordsNav(screen: RecordsScreen): RecordsNavState;
+/**
+ * Pop the top screen. On a one-screen stack the state is returned UNCHANGED with `handled:false`, so the RN
+ * flow's back handler can return `false` and let the host navigator handle the press.
+ */
+declare function popRecordsNav(state: RecordsNavState): {
+    readonly state: RecordsNavState;
+    readonly handled: boolean;
+};
+/**
+ * The consumer's own transition rule for a screen-declared edge:
+ *   - `dashboard` is the root: reaching it resets the stack (consent success `router.replace`s the dashboard,
+ *     a published request pushes it; both end on one dashboard with nothing to pop back into);
+ *   - `upload -> request` replaces (the upload screen's "Done" is a `router.replace`);
+ *   - everything else pushes.
+ */
+declare function transitionRecordsNav(state: RecordsNavState, to: RecordsScreen): RecordsNavState;
+declare function recordsNavReducer(state: RecordsNavState, action: RecordsNavAction): RecordsNavState;
+
+/** The entity a pill refers to: a BE-recognized `type` and `id`, plus compact display facts the host may pass on. */
+interface RecordsAskEntityRef {
+    readonly type: string;
+    readonly id: string;
+    readonly payload?: Readonly<Record<string, string | number | boolean>>;
+}
+interface RecordsAsk {
+    readonly prompt: string;
+    readonly entityRef: RecordsAskEntityRef;
+}
+/** The host seam every Ask pill calls; pills render only when a host supplies it. */
+type RecordsAskHandler = (prompt: string, entityRef: RecordsAskEntityRef) => void;
+
+type ClinicLocation = NonNullable<RecordsClinicSearchInput['location']>;
+
+type RecordsUrlKind = 'share_link' | 'record_pdf';
+interface RecordsHostSeams {
+    /** Open a share link or the record PDF. Default: `Linking.openURL` on React Native, `window.open` on the web. */
+    readonly onOpenUrl?: (url: string, kind: RecordsUrlKind) => void | Promise<void>;
+    /** Copy a share link. Web default: `navigator.clipboard.writeText`; React Native has no default (see above). */
+    readonly onCopy?: (text: string) => Promise<void>;
+    /** The Ask pills' seed prompt and entity, for a host chat. Absent: no Ask pill renders. */
+    readonly onAsk?: RecordsAskHandler;
+    /** Biases the clinic search (the same input the clinic controller takes). */
+    readonly location?: ClinicLocation;
+}
+interface RecordsScreenBaseProps extends RecordsHostSeams {
+    readonly petRef: PetRef;
+    /** The pet's display name for headers and lead copy; absent, the consumer's own `your pet` forms. */
+    readonly petName?: string;
+    /** Called with the exact screen an edge leads to (see `navigation.ts`). Absent, a control that only navigates is hidden, never inert. */
+    readonly onNavigate?: (to: RecordsScreen) => void;
+    /** The header's back control; absent, no back control renders. */
+    readonly onBack?: () => void;
+}
+
+type RecordsDepthStatus = 'loading' | 'empty' | 'error' | 'populated';
+/** One depth read as a render state. `withheld` (no consent, or a fail-closed parse) renders nothing. */
+interface UseRecordsDepthState<T> {
+    readonly status: RecordsDepthStatus;
+    readonly value: T | null;
+    readonly error: EverfurError | null;
+    /**
+     * False once a read got the router's dark 404, which is how a tenant without `partner.records_full_depth_enabled`
+     * answers EVERY depth route. The state is then `empty` with no error, so the surface draws its own nothing
+     * instead of the generic failure leaf and its unusable `Try again`. True otherwise, including for a failure
+     * that never reached the server, which proves nothing about the tenant.
+     */
+    readonly available: boolean;
+    readonly refresh: () => void;
+}
+/** The signed member's depth client over the provider's auth; a surface with no user settles to accessDenied. */
+declare function useEverfurRecordsDepthClient(): RecordsDepthClient;
+/**
+ * Run one depth read for the scoped pet on mount, and again on `refresh`. `isEmpty` decides between `empty`
+ * and `populated`; a withheld answer is `populated` with `withheld:true`, which every depth surface renders as
+ * nothing (never a partial record).
+ */
+declare function useRecordsDepthRead<T extends {
+    readonly withheld: boolean;
+}>(petRef: PetRef, read: (client: RecordsDepthClient, petRef: PetRef) => Promise<EverfurResult<T>>, isEmpty: (value: T) => boolean, extraKey?: string): UseRecordsDepthState<T>;
+
+export { transitionRecordsNav as A, type ClinicDraft as C, type RecordsAskEntityRef as R, type UseRecordsDepthState as U, type ClinicLocation as a, type RecordsAskHandler as b, type RecordsDepthStatus as c, type RecordsHostSeams as d, type RecordsScreen as e, type RecordsScreenBaseProps as f, type RecordsUrlKind as g, useRecordsDepthRead as h, type RecordsClinicController as i, type CaptureRecordsSignature as j, type ClinicRequestBaseProps as k, type ClinicBatchBaseProps as l, type CapturedRecordsSignature as m, type RecordsAsk as n, type RecordsNavAction as o, type RecordsNavState as p, type RecordsSignatureContext as q, type RegisterSignaturePng as r, currentRecordsScreen as s, initialRecordsNav as t, useEverfurRecordsDepthClient as u, popRecordsNav as v, pushRecordsNav as w, recordsNavReducer as x, replaceRecordsNav as y, resetRecordsNav as z };

package/dist/useRecordsDepth-BU-OhzH6.d.ts

@@ -0,0 +1,237 @@
+import { R as RecordsRequestId, P as PetRef } from './ids-B2GAAifq.js';
+import { a5 as RecordsClinicSearchInput, a6 as RecordsClinicSearchPage, a7 as RecordsRecentClinicsInput, a8 as RecordsAuthorizationCopy, a9 as CreateClinicRequestInput, aa as RecordsSignatureUploadPolicy, l as RecordsClinic, O as RecordsClinicBatch, P as RecordsClinicBatchClient, m as RecordsDepthClient } from './depth-DjDcJ6kH.js';
+import { c as EverfurResult, E as EverfurError } from './EverfurResult-DN9pL2Ab.js';
+import { f as RecordsRequestGroupView, d as RecordsRequestView } from './models-B-Uh2LTf.js';
+
+interface RecordsClinicController {
+    searchClinics(input?: RecordsClinicSearchInput): Promise<EverfurResult<RecordsClinicSearchPage>>;
+    /** The clinics this member requested from before, most recent first: the picker's "recent" section. */
+    recentClinics(input?: RecordsRecentClinicsInput): Promise<EverfurResult<RecordsClinicSearchPage>>;
+    /** A multi-clinic batch's rollup and members. Not found until Everfur switches the multi-clinic flag on. */
+    getRequestGroup(requestGroupId: string): Promise<EverfurResult<RecordsRequestGroupView>>;
+    getAuthorizationCopy(): Promise<EverfurResult<RecordsAuthorizationCopy>>;
+    createClinicRequest(input: CreateClinicRequestInput): Promise<EverfurResult<RecordsRequestView>>;
+    retryRequest(id: RecordsRequestId): Promise<EverfurResult<RecordsRequestView>>;
+    revokeRequest(id: RecordsRequestId): Promise<EverfurResult<RecordsRequestView>>;
+    updateClinicEmail(id: RecordsRequestId, clinicEmail: string): Promise<EverfurResult<RecordsRequestView>>;
+    convertToUpload(id: RecordsRequestId): Promise<EverfurResult<RecordsRequestView>>;
+    /** Bytes are uploaded by the host directly to the returned multipart policy; never through the API. */
+    initiateSignatureUpload(fileSize: number): Promise<EverfurResult<RecordsSignatureUploadPolicy>>;
+    completeSignatureUpload(uploadId: string): Promise<EverfurResult<string>>;
+}
+
+/** The exact owner-visible scope at the moment the owner chooses to sign. */
+interface RecordsSignatureContext {
+    readonly petRef: PetRef;
+    readonly petName: string;
+    readonly ownerName: string;
+    readonly clinicName: string;
+    readonly authorizationVersion: string;
+    readonly scopeText: string;
+    /** Cancel native capture/upload when the signed-in user or active pet changes. */
+    readonly signal: AbortSignal;
+}
+/**
+ * A captured signature: a registered signature id (the PNG uploaded through the initiate/complete APIs, the
+ * consumer's own path, which keeps the bytes off the JSON body), or a small inline PNG (the built-in React
+ * Native pad's one-bit image, a few hundred bytes, under the platform's non-upload body cap).
+ */
+type CapturedRecordsSignature = {
+    readonly signatureId: string;
+    readonly signaturePngBase64?: never;
+} | {
+    readonly signatureId?: never;
+    readonly signaturePngBase64: string;
+};
+/**
+ * Capture explicitly at the moment the owner presses Send, after seeing the scope, and return the signature.
+ * null means the owner cancelled. Prefer the registered id for anything but a tiny PNG.
+ */
+type CaptureRecordsSignature = (context: RecordsSignatureContext) => Promise<CapturedRecordsSignature | null>;
+interface ClinicRequestBaseProps {
+    readonly petRef: PetRef;
+    /** Display name for this exact registered petRef; the server owns the final PDF identity. */
+    readonly petName: string;
+    /** Initial value only; the owner can visibly confirm or correct it before signing. */
+    readonly ownerName: string;
+    readonly onCaptureSignature?: CaptureRecordsSignature;
+    readonly onCreated?: (request: RecordsRequestView) => void;
+    readonly onClose?: () => void;
+    /** Host/test seam over the same signed-user controller contract. */
+    readonly controller?: RecordsClinicController;
+}
+
+/** One composed clinic of the batch (the consumer `ClinicRequestDraft`). */
+interface ClinicDraft {
+    /** Stable local key for list rows and removal. */
+    readonly key: string;
+    /** The directory clinic, or null for an owner-typed clinic name. */
+    readonly clinic: RecordsClinic | null;
+    /** The owner-typed clinic name when `clinic` is null. */
+    readonly freeText: string | null;
+    /** The owner-supplied address, when the clinic needs one. */
+    readonly email: string;
+    /** Minted when the draft is added; a whole-batch retry replays it. */
+    readonly idempotencyKey: string;
+}
+interface ClinicBatchBaseProps {
+    readonly petRef: PetRef;
+    /** Display name for this exact registered petRef; the server owns the final PDF identity. */
+    readonly petName: string;
+    /** Initial value only; the owner can visibly confirm or correct it before signing. */
+    readonly ownerName: string;
+    readonly onCaptureSignature?: CaptureRecordsSignature;
+    /** Called once with the batch outcome (created and failed clinics alike). */
+    readonly onCreated?: (batch: RecordsClinicBatch) => void;
+    readonly onClose?: () => void;
+    /** Host/test seams over the same signed-user contracts. */
+    readonly controller?: RecordsClinicController;
+    readonly batchClient?: RecordsClinicBatchClient;
+}
+/**
+ * Turn the pad's inline PNG into a registered signature id, so the batch carries one small id per clinic rather
+ * than one PNG per clinic (the platform caps the inline bytes of a batch at one signature's worth, and the WAF
+ * caps the JSON body). The host supplies the byte transport; the RN and web hosts each have one.
+ */
+type RegisterSignaturePng = (signaturePngBase64: string, signal: AbortSignal) => Promise<{
+    readonly signatureId: string;
+}>;
+
+type RecordsScreen = {
+    readonly name: 'dashboard';
+} | {
+    readonly name: 'request';
+    readonly requestId: RecordsRequestId;
+} | {
+    readonly name: 'timeline';
+} | {
+    readonly name: 'record';
+} | {
+    readonly name: 'document';
+} | {
+    readonly name: 'contributions';
+    readonly docId: string;
+} | {
+    readonly name: 'clinicPicker';
+}
+/**
+ * The multi-clinic composer (`EverfurClinicRequestBatch`). The consumer opens it as a SHEET from the full
+ * record screen's header (RequestFromClinicsAction.tsx); the SDK flow has no sheet layer of its own, so it is
+ * a screen of the same stack, pushed from the same control and popped by the same back.
+ */
+ | {
+    readonly name: 'clinicBatch';
+} | {
+    readonly name: 'consent';
+    readonly clinic: ClinicDraft;
+} | {
+    readonly name: 'upload';
+};
+interface RecordsNavState {
+    readonly stack: readonly RecordsScreen[];
+}
+type RecordsNavAction = {
+    readonly type: 'push';
+    readonly screen: RecordsScreen;
+} | {
+    readonly type: 'pop';
+} | {
+    readonly type: 'replace';
+    readonly screen: RecordsScreen;
+} | {
+    readonly type: 'reset';
+    readonly screen: RecordsScreen;
+}
+/** The screen-declared edge: applies the consumer's push / replace / reset rule for the (from, to) pair. */
+ | {
+    readonly type: 'navigate';
+    readonly screen: RecordsScreen;
+};
+/** A one-screen stack at `initial` (the dashboard when omitted). */
+declare function initialRecordsNav(initial?: RecordsScreen): RecordsNavState;
+/** The screen on top of the stack (a stack is never empty). */
+declare function currentRecordsScreen(state: RecordsNavState): RecordsScreen;
+declare function pushRecordsNav(state: RecordsNavState, screen: RecordsScreen): RecordsNavState;
+declare function replaceRecordsNav(state: RecordsNavState, screen: RecordsScreen): RecordsNavState;
+declare function resetRecordsNav(screen: RecordsScreen): RecordsNavState;
+/**
+ * Pop the top screen. On a one-screen stack the state is returned UNCHANGED with `handled:false`, so the RN
+ * flow's back handler can return `false` and let the host navigator handle the press.
+ */
+declare function popRecordsNav(state: RecordsNavState): {
+    readonly state: RecordsNavState;
+    readonly handled: boolean;
+};
+/**
+ * The consumer's own transition rule for a screen-declared edge:
+ *   - `dashboard` is the root: reaching it resets the stack (consent success `router.replace`s the dashboard,
+ *     a published request pushes it; both end on one dashboard with nothing to pop back into);
+ *   - `upload -> request` replaces (the upload screen's "Done" is a `router.replace`);
+ *   - everything else pushes.
+ */
+declare function transitionRecordsNav(state: RecordsNavState, to: RecordsScreen): RecordsNavState;
+declare function recordsNavReducer(state: RecordsNavState, action: RecordsNavAction): RecordsNavState;
+
+/** The entity a pill refers to: a BE-recognized `type` and `id`, plus compact display facts the host may pass on. */
+interface RecordsAskEntityRef {
+    readonly type: string;
+    readonly id: string;
+    readonly payload?: Readonly<Record<string, string | number | boolean>>;
+}
+interface RecordsAsk {
+    readonly prompt: string;
+    readonly entityRef: RecordsAskEntityRef;
+}
+/** The host seam every Ask pill calls; pills render only when a host supplies it. */
+type RecordsAskHandler = (prompt: string, entityRef: RecordsAskEntityRef) => void;
+
+type ClinicLocation = NonNullable<RecordsClinicSearchInput['location']>;
+
+type RecordsUrlKind = 'share_link' | 'record_pdf';
+interface RecordsHostSeams {
+    /** Open a share link or the record PDF. Default: `Linking.openURL` on React Native, `window.open` on the web. */
+    readonly onOpenUrl?: (url: string, kind: RecordsUrlKind) => void | Promise<void>;
+    /** Copy a share link. Web default: `navigator.clipboard.writeText`; React Native has no default (see above). */
+    readonly onCopy?: (text: string) => Promise<void>;
+    /** The Ask pills' seed prompt and entity, for a host chat. Absent: no Ask pill renders. */
+    readonly onAsk?: RecordsAskHandler;
+    /** Biases the clinic search (the same input the clinic controller takes). */
+    readonly location?: ClinicLocation;
+}
+interface RecordsScreenBaseProps extends RecordsHostSeams {
+    readonly petRef: PetRef;
+    /** The pet's display name for headers and lead copy; absent, the consumer's own `your pet` forms. */
+    readonly petName?: string;
+    /** Called with the exact screen an edge leads to (see `navigation.ts`). Absent, a control that only navigates is hidden, never inert. */
+    readonly onNavigate?: (to: RecordsScreen) => void;
+    /** The header's back control; absent, no back control renders. */
+    readonly onBack?: () => void;
+}
+
+type RecordsDepthStatus = 'loading' | 'empty' | 'error' | 'populated';
+/** One depth read as a render state. `withheld` (no consent, or a fail-closed parse) renders nothing. */
+interface UseRecordsDepthState<T> {
+    readonly status: RecordsDepthStatus;
+    readonly value: T | null;
+    readonly error: EverfurError | null;
+    /**
+     * False once a read got the router's dark 404, which is how a tenant without `partner.records_full_depth_enabled`
+     * answers EVERY depth route. The state is then `empty` with no error, so the surface draws its own nothing
+     * instead of the generic failure leaf and its unusable `Try again`. True otherwise, including for a failure
+     * that never reached the server, which proves nothing about the tenant.
+     */
+    readonly available: boolean;
+    readonly refresh: () => void;
+}
+/** The signed member's depth client over the provider's auth; a surface with no user settles to accessDenied. */
+declare function useEverfurRecordsDepthClient(): RecordsDepthClient;
+/**
+ * Run one depth read for the scoped pet on mount, and again on `refresh`. `isEmpty` decides between `empty`
+ * and `populated`; a withheld answer is `populated` with `withheld:true`, which every depth surface renders as
+ * nothing (never a partial record).
+ */
+declare function useRecordsDepthRead<T extends {
+    readonly withheld: boolean;
+}>(petRef: PetRef, read: (client: RecordsDepthClient, petRef: PetRef) => Promise<EverfurResult<T>>, isEmpty: (value: T) => boolean, extraKey?: string): UseRecordsDepthState<T>;
+
+export { transitionRecordsNav as A, type ClinicDraft as C, type RecordsAskEntityRef as R, type UseRecordsDepthState as U, type ClinicLocation as a, type RecordsAskHandler as b, type RecordsDepthStatus as c, type RecordsHostSeams as d, type RecordsScreen as e, type RecordsScreenBaseProps as f, type RecordsUrlKind as g, useRecordsDepthRead as h, type RecordsClinicController as i, type CaptureRecordsSignature as j, type ClinicRequestBaseProps as k, type ClinicBatchBaseProps as l, type CapturedRecordsSignature as m, type RecordsAsk as n, type RecordsNavAction as o, type RecordsNavState as p, type RecordsSignatureContext as q, type RegisterSignaturePng as r, currentRecordsScreen as s, initialRecordsNav as t, useEverfurRecordsDepthClient as u, popRecordsNav as v, pushRecordsNav as w, recordsNavReducer as x, replaceRecordsNav as y, resetRecordsNav as z };

package/dist/useVetVisit-Bc84hWUU.d.cts

@@ -0,0 +1,187 @@
+import { c as EverfurResult, E as EverfurError } from './EverfurResult-DN9pL2Ab.cjs';
+import { P as PetRef } from './ids-B2GAAifq.cjs';
+import { V as VetVisitIntent } from './visitIntent-D7_yVp1I.cjs';
+
+/** What the hosted page will open for a handoff minted with `visitRef`: the platform's own echo. */
+interface VetVisitHandoffVisit {
+    /** The visit reference the handoff was minted for, as you sent it. */
+    readonly visitRef: string;
+    /** What the hosted page opens for it. `visit` when you named no intent. */
+    readonly intent: VetVisitIntent;
+}
+/** A minted handoff. Open `url` once, promptly; it expires at `expiresAt` and is spent by the first use. */
+interface VetVisitHandoff {
+    /** The hosted Everfur page with the single-use token in its fragment. Never log or persist it. */
+    readonly url: string;
+    /** ISO-8601 timestamp from the server; about 120 seconds after the mint. */
+    readonly expiresAt: string;
+    /**
+     * Present only when the handoff was minted with `returnTo`: the opaque id the user comes back with on your
+     * registered return destination. Keep it to match the return (`parseVetVisitReturn`). It says nothing about
+     * the visit.
+     */
+    readonly flowId?: string;
+    /**
+     * Present only when the handoff was minted with `visitRef`: what the hosted page will open, echoed by the
+     * platform from what it stored with the handoff. The reference never rides the URL, so this is the only
+     * place to read it back. Absent on an ordinary booking handoff.
+     */
+    readonly visit?: VetVisitHandoffVisit;
+}
+/** Where a vet visit was opened from. `'chat'`: the user chose it inside partner Chat, for the chat's pet. */
+type VetVisitEntry = 'chat';
+/** Optional handoff settings. */
+interface VetVisitHandoffOptions {
+    /**
+     * The KEY of a return destination your tenant registered with Everfur. After the hosted visit flow the user
+     * can go back to that destination, and only that one. Never a URL.
+     */
+    readonly returnTo?: string | null;
+    /** `'chat'` when the user opened the visit from Chat. Requires the pet the chat is about. */
+    readonly entry?: VetVisitEntry | null;
+    /**
+     * TV-01. The reference of a visit this member ALREADY has (the `visit_ref` the `visit.*` events carry, and
+     * the one `parseEverfurNotification` reads off a tapped push). The handoff then opens that visit instead of
+     * the booking funnel. Everfur resolves it at the mint against this member's own live link, so a reference
+     * that is not theirs is refused with the same words a malformed one gets: a `validationFailed` you cannot
+     * probe for visits with. At most 64 characters.
+     */
+    readonly visitRef?: string | null;
+    /**
+     * What to open for `visitRef`: the visit itself, its call, its summary or its messages. Absent means
+     * `visit`. An intent with no `visitRef` is refused locally, because it names a route with nothing to route
+     * to. A tapped push already carries the right one on `target.intent`.
+     */
+    readonly intent?: VetVisitIntent | null;
+}
+/** The state preflight's whole answer. Nothing about the account, the plan or the price. */
+interface VetVisitAvailability {
+    /** True when a vet visit can be booked for the state asked about. False for every other reason, alike. */
+    readonly available: boolean;
+}
+/** A partner app's return from the hosted visit flow, read by `parseVetVisitReturn`. Only the flow id. */
+interface VetVisitReturn {
+    /** The opaque flow id from the handoff that led to this return. */
+    readonly flowId: string;
+}
+/**
+ * The closed set a partner branches on, derived from the route's documented outcomes.
+ *
+ * - `sessionRequired`: the integration sent no signed session. Mint one on your backend
+ *   (`@everfur/sdk/server` mintPartnerSession) and hand the token to `EverfurUser.getToken`.
+ * - `authRejected`: the session token was refused after the one refresh the SDK performs.
+ * - `accessDenied`: a signed session whose key or plan does not include vet visits.
+ * - `unavailable`: vet visits are off for this partner or for Everfur right now (the route answers 404).
+ * - `rateLimited`: this user or this partner has opened too many visits recently. Do not retry in a loop.
+ * - `sdkUpdateRequired`: the API refused this SDK version.
+ * - `invalidRequest`: the pet reference was refused (empty, or longer than 128 characters).
+ * - `network`: no response arrived (offline, DNS, timeout).
+ * - `serverError`: the API failed, or answered with something that is not a usable Everfur visit URL.
+ * - `popupBlocked`: web only. The browser refused to open the new tab.
+ * - `openFailed`: React Native only. The host could not open the URL.
+ * - `cancelled`: nothing to show. The visit tab was closed before it loaded, or the signed-in user changed
+ *   while the handoff was being minted, so it was dropped rather than opened for the previous user.
+ * - `unknown`: anything else.
+ */
+type VetVisitErrorReason = 'sessionRequired' | 'authRejected' | 'accessDenied' | 'unavailable' | 'rateLimited' | 'sdkUpdateRequired' | 'invalidRequest' | 'network' | 'serverError' | 'popupBlocked' | 'openFailed' | 'cancelled' | 'unknown';
+/** Map a settled handoff failure to its closed reason. Total and pure. */
+declare function vetVisitErrorReasonOf(error: EverfurError): VetVisitErrorReason;
+/** Mints handoffs for the current session. Built by `useVetVisit`; injectable for tests. */
+interface VetVisitController {
+    /**
+     * Mint one handoff. Optional `petRef` scopes the visit to the partner's pet, shown to the user after
+     * sign-in. `options` names a registered return destination and where the visit was opened from. Settles;
+     * never throws; never retries.
+     */
+    createHandoff(petRef?: PetRef | null, options?: VetVisitHandoffOptions): Promise<EverfurResult<VetVisitHandoff>>;
+    /**
+     * Ask whether a vet visit is available for a US state (for example `'CA'`). Settles. An injected controller
+     * without it is treated as unavailable wherever the hook needs the answer.
+     */
+    checkAvailability?(state: string): Promise<EverfurResult<VetVisitAvailability>>;
+    /** True only while Everfur has the vet entry inside Chat switched on. Never throws; any failure is false. */
+    chatEntryOpen?(): Promise<boolean>;
+}
+/**
+ * Read an Everfur return off the URL your registered return destination was opened with. Returns the opaque
+ * flow id you received from the handoff, or null for any URL that does not carry exactly one well-formed
+ * Everfur flow id in its query. It carries nothing about the visit, the pet or the account.
+ */
+declare function parseVetVisitReturn(url: string): VetVisitReturn | null;
+
+/** `idle` before a tap and after a successful open; `opening` while the handoff is minted; `error` after a failure. */
+type VetVisitStatus = 'idle' | 'opening' | 'error';
+/** What one `open()` call settled to. The URL is deliberately absent. */
+type VetVisitOpenResult = {
+    readonly opened: true;
+    readonly flowId?: string;
+} | {
+    readonly opened: false;
+    readonly reason: VetVisitErrorReason;
+    readonly error: EverfurError | null;
+};
+/** Options for `useVetVisit`. */
+interface UseVetVisitOptions {
+    /** The partner's pet reference to scope the visit to. `open(petRef)` overrides it per call. */
+    readonly petRef?: PetRef | null;
+    /** Host/test seam: inject a controller instead of building one from the provider's session. */
+    readonly controller?: VetVisitController;
+    /**
+     * The KEY of a return destination your tenant registered with Everfur. The visit can then send the user back
+     * to it, and `open()` settles with the `flowId` that return will carry.
+     */
+    readonly returnTo?: string | null;
+    /**
+     * The user's US state (for example `'CA'`). When set, `available` stays false until Everfur confirms a visit
+     * is available there, so the entry is never shown to a user who could not book.
+     */
+    readonly usState?: string | null;
+    /**
+     * `'chat'` for the entry inside Chat. `available` then also needs Everfur's chat entry switch and a pet (the
+     * one the chat is about); the visit itself is the same hosted visit.
+     */
+    readonly entry?: VetVisitEntry | null;
+}
+/** What `useVetVisit` returns. The handoff URL is never part of it. */
+interface UseVetVisitState {
+    /**
+     * True only when the server grants the `televet` capability AND the provider is scoped to a user. A handoff
+     * is minted from the user's session, so a publishable-key-only context could only ever spend a blank tab on
+     * a `sessionRequired` failure. A surface renders nothing otherwise.
+     */
+    readonly available: boolean;
+    /** True while the capability verdict is still resolving. */
+    readonly isPending: boolean;
+    /** Where the last `open()` is: idle, opening, or failed. */
+    readonly status: VetVisitStatus;
+    /** The settled failure of the last `open()`, or null. `error.displayMessage` is safe to show. */
+    readonly error: EverfurError | null;
+    /** The closed reason for the last failure, or null. */
+    readonly errorReason: VetVisitErrorReason | null;
+    /**
+     * Mint a handoff and open the hosted Everfur visit. Call it directly from a press or click handler. A second
+     * call while one is in flight returns the same promise rather than minting a second handoff.
+     */
+    open(petRef?: PetRef | null): Promise<VetVisitOpenResult>;
+    /**
+     * TV-01. Open a visit this member ALREADY has, instead of the booking funnel: the recap of a finished
+     * visit, the thread the vet wrote in, the call a reminder is for. `visitRef` is the reference the
+     * `visit.*` events carry, and `intent` is what to open for it (`visit` when omitted).
+     *
+     * Hand it what a tapped push gave you, unchanged:
+     * ```ts
+     * const n = parseEverfurNotification(response);
+     * if (n?.target.kind === 'visit' && n.target.intent !== null) {
+     *   await visit.openVisit(n.target.visitRef, n.target.intent);
+     * }
+     * ```
+     * A `null` intent on a target means the visit is over without happening (cancelled, missed): there is
+     * nothing left to open, so call `open()` to book a new one instead.
+     *
+     * Everfur resolves the reference at the mint against this member's own visits, so one that is not theirs
+     * settles `invalidRequest` and opens nothing. Shares the single-flight rule with `open`.
+     */
+    openVisit(visitRef: string, intent?: VetVisitIntent | null): Promise<VetVisitOpenResult>;
+}
+
+export { type UseVetVisitOptions as U, type VetVisitEntry as V, type UseVetVisitState as a, type VetVisitErrorReason as b, type VetVisitController as c, type VetVisitAvailability as d, type VetVisitHandoff as e, type VetVisitHandoffOptions as f, type VetVisitHandoffVisit as g, type VetVisitOpenResult as h, type VetVisitReturn as i, type VetVisitStatus as j, parseVetVisitReturn as p, vetVisitErrorReasonOf as v };