@hipnation-truth/sdk 0.23.2 → 0.25.1

package/dist/react.d.ts

@@ -599,6 +599,14 @@ interface UsePatientMedicalOptions {
  * against Truth's `/api/patients/medical/refresh` endpoint so stale data
  * is pulled in without blocking render. Returns cached data immediately;
  * Convex subscription updates the UI when refresh completes.
+ *
+ * OFFLINE-READS POLICY: these medical-record queries ARE mirrored offline
+ * via `usePersistentQuery`, so medications, problems, allergies and
+ * appointments render from the at-rest mirror when the device is offline.
+ * Full medical records are the most sensitive PHI we hold, so they are
+ * only ever written to the encrypted-at-rest store (256-bit MMKV key held
+ * in the device keychain), never to any plaintext storage. Keep them on
+ * the encrypted mirror only — do not relax the store's encryption.
  */
 declare function usePatientMedical(elationId: number | undefined, options?: UsePatientMedicalOptions): {
     medications: unknown[] | undefined;
@@ -834,6 +842,77 @@ interface UseNotificationsActions {
 }
 declare function useNotificationsActions(): UseNotificationsActions;
 
+/**
+ * Offline mirror storage seam.
+ *
+ * The Truth SDK is consumed by two apps with very different storage
+ * stories:
+ *  - `ch/` (Expo / React Native) — has access to native, encrypted,
+ *    synchronous KV (MMKV) and wants durable offline reads.
+ *  - `truth/apps/web` (Next.js) — has no such store and must behave
+ *    exactly as it does today.
+ *
+ * So the SDK never imports a native module. Instead the consuming app
+ * *injects* an `OfflineStore` implementation through `<TruthProvider>`.
+ * When none is injected the SDK falls back to {@link NoopStore} and the
+ * entire offline layer becomes a transparent pass-through.
+ *
+ * The interface is deliberately **synchronous**: cold-start hydration
+ * has to read the last-known value during the first render, before any
+ * effect or promise resolves, so async storage (AsyncStorage) is not
+ * sufficient here. MMKV's `getString`/`set` are synchronous and map
+ * onto this directly.
+ */
+/** Synchronous KV mirror. Sync getters enable instant cold-start hydration. */
+interface OfflineStore {
+    /** Return the stored string for `key`, or `null` when absent. */
+    get(key: string): string | null;
+    /** Write `value` under `key`, overwriting any prior value. */
+    set(key: string, value: string): void;
+    /** Remove a single `key`. No-op when absent. */
+    delete(key: string): void;
+    /**
+     * Wipe every key this store owns. Called on logout / user switch so a
+     * second user on the same device never sees the first user's cached
+     * PHI. MUST clear durably (survive the next cold start).
+     */
+    clearAll(): void;
+}
+/**
+ * Used when no store is injected (e.g. `truth/apps/web`) → the offline
+ * layer is a no-op and behavior is identical to a build without it.
+ */
+declare class NoopStore implements OfflineStore {
+    get(): string | null;
+    set(): void;
+    delete(): void;
+    clearAll(): void;
+}
+
+/**
+ * TanStack Query persister backed by the injected {@link OfflineStore}.
+ *
+ * Under Path A the whole dehydrated query cache is serialized as a
+ * single blob and written through the synchronous `OfflineStore` (MMKV
+ * on `ch/`). On cold start `PersistQueryClientProvider` calls
+ * `restoreClient()` to rehydrate that blob before the Convex websocket
+ * reconnects, which is what makes last-known data render with no
+ * network.
+ *
+ * The store is synchronous, so all three methods resolve immediately —
+ * but the `Persister` contract allows returning a value or a promise, so
+ * returning the raw values is fine.
+ */
+
+/**
+ * Read the epoch-millis timestamp the persisted cache was last written
+ * (TanStack stamps `timestamp` on every persist → it tracks the most
+ * recent successful sync). Returns `null` when nothing is persisted or
+ * the blob is unreadable. Powers the "Offline · updated {relative}"
+ * indicator without the app having to know the dehydrated cache format.
+ */
+declare function readPersistedSavedAt(store: OfflineStore, cacheKey?: string): number | null;
+
 /**
  * React hook for patient family-member lookup — Truth SDK.
  *
@@ -1178,12 +1257,26 @@ declare const ENVIRONMENTS: {
     readonly production: "production";
 };
 type Environment = (typeof ENVIRONMENTS)[keyof typeof ENVIRONMENTS];
+/**
+ * Fetches a user-identity JWT for Convex calls. Return the token from
+ * your identity provider's Clerk JWT template named "convex"
+ * (e.g. `getToken({ template: "convex" })` from `@clerk/expo`), or
+ * `null` when no user is signed in.
+ */
+type AuthTokenFetcher = () => Promise<string | null | undefined>;
 /**
  * Configuration for initializing a TruthClient.
  */
 interface TruthClientConfig {
     /** API key for authenticating with the Truth platform (e.g. "hn_live_...") */
     apiKey: string;
+    /**
+     * Per-call Clerk JWT fetcher for Convex data access. When provided,
+     * every Convex query/mutation/action carries the caller's identity;
+     * Convex deployments with `CLERK_AUTH_REQUIRED` enabled reject calls
+     * without it. Omit for service contexts that don't act as a user.
+     */
+    getAuthToken?: AuthTokenFetcher;
     /** Target environment */
     environment: Environment;
     /** Override the default Convex URL for data access */
@@ -2651,6 +2744,10 @@ interface TruthSdkContextValue {
     apiKey: string;
     environment: string;
     client: TruthClient;
+    /** Injected offline mirror (or the Noop default on web / flag off). */
+    offlineStore: OfflineStore;
+    /** Whether the offline-reads layer is active for this provider. */
+    offlineEnabled: boolean;
 }
 /**
  * Read the Truth REST API base URL + API key + shared client from
@@ -2659,6 +2756,17 @@ interface TruthSdkContextValue {
  * compatibility.
  */
 declare function useTruthSdkContext(): TruthSdkContextValue | null;
+/**
+ * Read the injected offline mirror. Returns the shared `NoopStore`
+ * (transparent pass-through) when no provider is mounted or no store was
+ * injected — so callers never have to null-check.
+ */
+declare function useOfflineStore(): OfflineStore;
+/**
+ * Whether the offline-reads layer is active. `false` when no provider is
+ * mounted or the feature flag is off.
+ */
+declare function useOfflineEnabled(): boolean;
 /**
  * Hook variant of `getTruthClient()` for code that lives inside the
  * React tree. Returns the shared `TruthClient` instance from
@@ -2696,9 +2804,34 @@ interface TruthProviderProps {
     source?: string;
     sourceVersion?: string;
     tenantId?: string;
+    /**
+     * Per-call Clerk JWT fetcher (template "convex") identifying the
+     * signed-in user to Convex. Wire it to your identity provider, e.g.
+     * `useAuth().getToken({ template: "convex" })` from `@clerk/expo`.
+     * Applied to both the live websocket client (React hooks) and the
+     * shared `TruthClient` (resource methods). Identity changes are
+     * picked up without remounting — the latest fetcher is read through
+     * a ref on every call.
+     */
+    getAuthToken?: AuthTokenFetcher;
+    /**
+     * Synchronous encrypted KV mirror for durable offline reads, injected
+     * by the consuming app (e.g. MMKV on `ch/`). Omit on web — the SDK
+     * falls back to a `NoopStore` and the offline layer is a transparent
+     * pass-through. Never import a native module into the SDK; inject it
+     * here instead.
+     */
+    offlineStore?: OfflineStore;
+    /**
+     * Feature flag for the offline-reads layer. Default `false`. Has no
+     * effect unless a real (non-Noop) `offlineStore` is also injected.
+     * When both are set, the TanStack query cache is persisted to the
+     * store so last-known reads survive a cold start with no network.
+     */
+    offlineEnabled?: boolean;
     children: ReactNode;
 }
-declare function TruthProvider({ environment, convexUrl, apiBaseUrl, apiKey, source, sourceVersion, tenantId, children, }: TruthProviderProps): react.FunctionComponentElement<react.ProviderProps<TruthSdkContextValue | null>>;
+declare function TruthProvider({ environment, convexUrl, apiBaseUrl, apiKey, source, sourceVersion, tenantId, getAuthToken, offlineStore, offlineEnabled, children, }: TruthProviderProps): react.FunctionComponentElement<react.ProviderProps<TruthSdkContextValue | null>>;
 
 /**
  * React hooks for conversation reminders — bulk lookup keyed by
@@ -2897,4 +3030,4 @@ interface UseVoicemailUrlResult {
  */
 declare function useVoicemailUrl(client: TruthClient): UseVoicemailUrlResult;
 
-export { ACTIVE_CALL_STATES, API_BASE_URLS, type Appointment, type AppointmentListOptions, CONNECTED_CALL_STATES, CONVEX_URLS, type ConversationListItem, type ConversationMessage, type ConversationMessageRow, type ConversationNoteRow, type ConversationRow, type ConversationTaskForUserRow, type ConversationTaskRow, type DialpadCallLogRow, type DialpadCallRow, DialpadCallState, type EventPayloadMap, type EventType, type FamilyMemberRow, type Patient, type PatientListOptions, type PatientSearchResult, type PermissionStatus, type Physician$1 as Physician, RINGING_CALL_STATES, TERMINAL_CALL_STATES, type TrackOptions, TruthProvider, type TruthProviderProps, type TruthTrackingContextValue, TruthTrackingProvider, type TruthTrackingProviderProps, type UseActiveCallsOptions, type UseAppointmentListOptions, type UseConversationMessagesOptions, type UseConversationsFilters, type UseMessagesOptions, type UseNotificationsActions, type UseNotificationsOptions, type UseNotificationsResult, type UsePatientBasicOptions, type UsePatientBasicResult, type UsePatientFamilyMembersInput, type UsePatientListOptions, type UsePatientMedicalOptions, type UsePatientPhotoOptions, type UsePatientSearchOptions, type UseQueryResult, type UseUserSyncInput, type UseUserSyncResult, getTruthClient, resolveApiBaseUrl, resolveConvexUrl, useActiveCalls, useAppointment, useAppointmentByElationId, useAppointments, useConversationById, useConversationByPhonePair, useConversationMessages, useConversationNotes, useConversationNotesByPhonePair, useConversationTaskMarkSeen, useConversationTasks, useConversationTasksByPhonePair, useConversationTasksForUser, useConversations, useDialpadCallByCallId, useDialpadCallLog, useDialpadCallsForConversation, useMessages, useNotifications, useNotificationsActions, usePatient, usePatientBasic, usePatientByElationId, usePatientByHintId, usePatientFamilyMembers, usePatientMedical, usePatientPhoto, usePatientSearch, usePatients, usePatientsByIds, usePatientsByPhones, usePharmacyByNcpdpId, usePhysicianByElationId, usePhysiciansByElationIds, useRemindersForConversations, useTruth, useTruthClient, useTruthSdkContext, useUnreadAggregate, useUnreadCount, useUserSettings, useUserSync, useVoicemailUrl };
+export { ACTIVE_CALL_STATES, API_BASE_URLS, type Appointment, type AppointmentListOptions, CONNECTED_CALL_STATES, CONVEX_URLS, type ConversationListItem, type ConversationMessage, type ConversationMessageRow, type ConversationNoteRow, type ConversationRow, type ConversationTaskForUserRow, type ConversationTaskRow, type DialpadCallLogRow, type DialpadCallRow, DialpadCallState, type EventPayloadMap, type EventType, type FamilyMemberRow, NoopStore, type OfflineStore, type Patient, type PatientListOptions, type PatientSearchResult, type PermissionStatus, type Physician$1 as Physician, RINGING_CALL_STATES, TERMINAL_CALL_STATES, type TrackOptions, TruthProvider, type TruthProviderProps, type TruthTrackingContextValue, TruthTrackingProvider, type TruthTrackingProviderProps, type UseActiveCallsOptions, type UseAppointmentListOptions, type UseConversationMessagesOptions, type UseConversationsFilters, type UseMessagesOptions, type UseNotificationsActions, type UseNotificationsOptions, type UseNotificationsResult, type UsePatientBasicOptions, type UsePatientBasicResult, type UsePatientFamilyMembersInput, type UsePatientListOptions, type UsePatientMedicalOptions, type UsePatientPhotoOptions, type UsePatientSearchOptions, type UseQueryResult, type UseUserSyncInput, type UseUserSyncResult, getTruthClient, readPersistedSavedAt, resolveApiBaseUrl, resolveConvexUrl, useActiveCalls, useAppointment, useAppointmentByElationId, useAppointments, useConversationById, useConversationByPhonePair, useConversationMessages, useConversationNotes, useConversationNotesByPhonePair, useConversationTaskMarkSeen, useConversationTasks, useConversationTasksByPhonePair, useConversationTasksForUser, useConversations, useDialpadCallByCallId, useDialpadCallLog, useDialpadCallsForConversation, useMessages, useNotifications, useNotificationsActions, useOfflineEnabled, useOfflineStore, usePatient, usePatientBasic, usePatientByElationId, usePatientByHintId, usePatientFamilyMembers, usePatientMedical, usePatientPhoto, usePatientSearch, usePatients, usePatientsByIds, usePatientsByPhones, usePharmacyByNcpdpId, usePhysicianByElationId, usePhysiciansByElationIds, useRemindersForConversations, useTruth, useTruthClient, useTruthSdkContext, useUnreadAggregate, useUnreadCount, useUserSettings, useUserSync, useVoicemailUrl };