@hipnation-truth/sdk 0.5.0 → 0.7.0

package/dist/react.d.mts

@@ -2,6 +2,194 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { ConvexReactClient } from 'convex/react';
 
+/**
+ * React hooks for Truth SDK — reactive conversation + message data.
+ *
+ * Wraps Convex queries owned by the Truth backend so consumers (CommHub
+ * Expo frontend) get live-updating conversation lists, message threads,
+ * and unread totals without managing subscriptions themselves.
+ *
+ * **Hook contract:** every hook in this file returns
+ * `{ data, loading, error }`. `data` is `undefined` while loading and
+ * also when the underlying query is `"skip"`'d (caller didn't pass the
+ * required arg yet). `loading` is `true` only while a real subscription
+ * is in-flight; once `data` resolves (even to `null`) `loading` flips
+ * to `false`. `error` is reserved for SDK-side validation — Convex
+ * itself throws on subscribe rather than returning an error value, so
+ * unhandled query errors propagate as React errors and should be caught
+ * with an error boundary.
+ *
+ * **Backed by PR #110 schema (commit `41dbb59` on
+ * `feat/migrate-dialpad-webhook-and-messages-to-truth`):**
+ *  - `conversations:listForUser` → `useConversations`
+ *  - `conversations:getUnreadTotalForUser` → `useUnreadCount`
+ *  - `conversations:getByPhonePair` → `useConversationByPhonePair`
+ *  - `conversationMessages:getByConversationId` → `useMessages`
+ *
+ * **Deliberately NOT shipped here (no backend query yet — flagged in
+ * PR #111 body for follow-up):**
+ *  - Single-conversation-by-id lookup. Convex `conversations` has no
+ *    `get(id)` query — only `getByPhonePair`. CommHub uses phonePair as
+ *    the primary handle, so the byPair flavor is what consumers need;
+ *    if id-based lookup is needed later we can add a `conversations:get`
+ *    in Truth.
+ *  - Participants / "seen by" hook. The migrated schema has no
+ *    `conversationParticipants` table — read state is per-user via
+ *    `conversationReads` and there's no public list query for it yet.
+ *  - `markRead` mutation. PR #110 declares `markRead` as
+ *    `internalMutation`, so the frontend can't invoke it directly — it
+ *    has to go through a Truth HTTP endpoint, or webhook-migrator needs
+ *    to flip it to a public `mutation`. Flagged for a follow-up.
+ *
+ * Must be used within `<TruthProvider />` (see `./provider`).
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   useConversations,
+ *   useConversationByPhonePair,
+ *   useMessages,
+ *   useUnreadCount,
+ * } from '@hipnation-truth/sdk/react';
+ *
+ * function Inbox({ userId }: { userId: string }) {
+ *   const { data: convos, loading } = useConversations({ userId });
+ *   const { data: unread } = useUnreadCount(userId);
+ *   if (loading) return <Spinner />;
+ *   return (
+ *     <div>
+ *       <Badge count={unread ?? 0} />
+ *       {convos?.map((c) => <ConvoRow key={c.id} convo={c} />)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+/**
+ * Row shape returned by `conversations:listForUser` — joins the base
+ * `conversations` row with the caller's per-user `conversationReads`
+ * entry so unread state lives on each item.
+ */
+interface ConversationListItem {
+    /** Convex id of the conversation row. */
+    id: string;
+    patientPhone: string;
+    providerPhone: string;
+    /** Sorted-digit-pair key (commutative — same regardless of direction). */
+    phonePair: string;
+    /** Truth-side patient id, when the kinesis pipeline could resolve it. */
+    patientId: string | null;
+    /** ISO timestamp of the most recent message in the conversation. */
+    lastMessageAt: string;
+    /** Caller's unread count for this conversation. */
+    unreadCount: number;
+    /** ISO timestamp of when the caller last marked the conversation read. */
+    lastReadAt: string | null;
+}
+/**
+ * Raw `conversations` table row — what `getByPhonePair` returns. No
+ * unread / read joining; for that, prefer `useConversations`.
+ */
+interface ConversationRow {
+    _id: string;
+    _creationTime: number;
+    patientPhone: string;
+    providerPhone: string;
+    phonePair: string;
+    patientId: string | null;
+    lastEventId: string | null;
+    lastMessageAt: string;
+    createdAt: string;
+}
+/**
+ * Message row returned by `conversationMessages:getByConversationId` —
+ * calls + SMS merged chronologically. Mirrors `ConversationMessage`
+ * already exported from the SDK; re-exported here under a clearer name
+ * for the new hook surface.
+ */
+interface ConversationMessageRow {
+    kind: "call" | "sms";
+    id: string;
+    providerId: string;
+    state: string | null;
+    direction: string | null;
+    fromNumber: string | null;
+    toNumber: string | null;
+    voicemailLink: string | null;
+    duration: number | null;
+    text: string | null;
+    mms: boolean;
+    mmsUrl: string | null;
+    messageStatus: string | null;
+    occurredAt: string;
+    conversationId: string | null;
+    patientId: string | null;
+}
+interface UseQueryResult<T> {
+    /**
+     * Query data. `undefined` while loading or while the query is
+     * intentionally skipped (e.g. caller hasn't supplied `userId` yet).
+     */
+    data: T | undefined;
+    /** True only while a real subscription is in-flight. */
+    loading: boolean;
+    /**
+     * Reserved for client-side validation errors surfaced by the SDK
+     * itself. Convex query errors propagate as React errors and should
+     * be caught with an error boundary.
+     */
+    error: Error | undefined;
+}
+interface UseConversationsFilters {
+    /**
+     * Truth user id (the Better Auth subject). Pass `undefined` to skip
+     * the query — useful when the auth session is still loading.
+     */
+    userId: string | null | undefined;
+    /** Page size. Server caps at 100 by default. */
+    limit?: number;
+}
+interface UseMessagesOptions {
+    /** Page size. Server caps at 200 by default. */
+    limit?: number;
+}
+/**
+ * Subscribe to a user's conversations — joined with their per-conversation
+ * unread count, sorted by most recent message. Updates live as new
+ * SMS / calls land in Convex and the webhook bumps `unreadCount`.
+ *
+ * Returns `{ data: undefined, loading: false }` while the auth session
+ * resolves (`userId === undefined`); not an error, just a skip.
+ */
+declare function useConversations(filters: UseConversationsFilters): UseQueryResult<ConversationListItem[]>;
+/**
+ * Look up a single conversation by its normalized phonePair (sorted
+ * digit-pair, e.g. `"5125550123|6505551234"`). Returns `null` if no
+ * conversation exists yet for that pair.
+ *
+ * Use the `phonePairKey(patientPhone, providerPhone)` helper exposed by
+ * the Truth Convex module to derive the key from raw phone strings.
+ */
+declare function useConversationByPhonePair(phonePair: string | null | undefined): UseQueryResult<ConversationRow | null>;
+/**
+ * Subscribe to a paginated message stream for a single conversation.
+ * Calls + SMS merged chronologically, newest-first. Live as the
+ * kinesis consumer writes to `messageCalls` / `messageSms`.
+ *
+ * Pass the Convex `_id` of the conversation row (from
+ * `useConversations` / `useConversationByPhonePair`) as
+ * `conversationId`.
+ */
+declare function useMessages(conversationId: string | null | undefined, options?: UseMessagesOptions): UseQueryResult<ConversationMessageRow[]>;
+/**
+ * Subscribe to the user's total unread message count across all
+ * conversations. Backs the inbox tab badge in CommHub.
+ *
+ * Returns `0` when the underlying query resolves with no unread
+ * messages, `undefined` while loading or when `userId` is missing.
+ */
+declare function useUnreadCount(userId: string | null | undefined): UseQueryResult<number>;
+
 /**
  * React hooks for Truth SDK — real-time Convex-backed data access.
  *
@@ -184,6 +372,98 @@ interface UsePatientPhotoOptions {
  * binary from Elation + upload to S3.
  */
 declare function usePatientPhoto(elationId: number | undefined, options?: UsePatientPhotoOptions): any;
+interface ConversationMessage {
+    kind: "call" | "sms";
+    id: string;
+    providerId: string;
+    state: string | null;
+    direction: string | null;
+    fromNumber: string | null;
+    toNumber: string | null;
+    voicemailLink: string | null;
+    duration: number | null;
+    text: string | null;
+    mms: boolean;
+    mmsUrl: string | null;
+    messageStatus: string | null;
+    occurredAt: string;
+    conversationId: string | null;
+    patientId: string | null;
+}
+interface UseConversationMessagesOptions {
+    /** Max items to return (default 200). */
+    limit?: number;
+}
+/**
+ * Subscribe to a conversation's calls + SMS merged chronologically.
+ * Pass the patient phone + the provider phone — Truth computes a
+ * normalized pair key server-side so formatting differences don't
+ * matter.
+ *
+ * Returns `undefined` while loading, then `ConversationMessage[]`
+ * sorted newest-first. Updates live as new webhook events land in
+ * Convex via the kinesis consumer.
+ */
+declare function useConversationMessages(input: {
+    phoneA?: string;
+    phoneB?: string;
+    conversationId?: string;
+}, options?: UseConversationMessagesOptions): ConversationMessage[] | undefined;
+
+/**
+ * useNotifications — Truth SDK React hook for push notifications.
+ *
+ * Shape-compatible with `expo-notifications` where practical so
+ * consumers port with minimal change. The hook dynamically imports
+ * `expo-notifications` so the SDK doesn't hard-depend on Expo —
+ * consumers running on a non-Expo runtime (e.g. a server test harness)
+ * can still import the SDK without Metro blowing up.
+ *
+ * Exposes:
+ *   - permissionStatus  — "granted" / "denied" / "undetermined"
+ *   - devicePushToken   — native APNs/FCM token (undefined until register)
+ *   - register()        — request permission, fetch token, register with Truth
+ *   - unregister()      — revoke the device
+ *   - addReceivedListener / addResponseListener — re-exports of expo's
+ *   - getBadgeCount / setBadgeCount — re-exports of expo's
+ *
+ * Web push (VAPID subscription) lands in Phase 3.
+ */
+type PermissionStatus = "granted" | "denied" | "undetermined" | "unknown";
+interface UseNotificationsOptions {
+    /** Truth API base URL, e.g. https://app.truth.communication-hub.com */
+    apiBaseUrl: string;
+    /** `hn_live_*` API key for the caller's application. */
+    apiKey: string;
+    /** Current user id — used when registering the device. */
+    userId: string | null | undefined;
+    /** Optional app version string stored on the device row. */
+    appVersion?: string;
+    /**
+     * Auto-register on mount when permission is already granted.
+     * Default: true. Set false if you want to control the registration
+     * lifecycle yourself.
+     */
+    autoRegister?: boolean;
+    /** VAPID public key for web push. Fetched automatically if omitted. */
+    vapidPublicKey?: string;
+    /** Path to the service worker file. Default: "/truth-sw.js" */
+    serviceWorkerPath?: string;
+}
+interface UseNotificationsResult {
+    permissionStatus: PermissionStatus;
+    devicePushToken: string | null;
+    register: () => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    unregister: () => Promise<void>;
+    addReceivedListener: (listener: (n: unknown) => void) => () => void;
+    addResponseListener: (listener: (r: unknown) => void) => () => void;
+    getBadgeCount: () => Promise<number>;
+    setBadgeCount: (count: number) => Promise<void>;
+}
+declare function useNotifications(options: UseNotificationsOptions): UseNotificationsResult;
 
 interface TruthProviderProps {
     /** Truth environment — determines which Convex deployment to connect to */
@@ -615,4 +895,4 @@ interface PatientListOptions {
     cursor?: string;
 }
 
-export { type Appointment, type AppointmentListOptions, type EventPayloadMap, type EventType, type Patient, type PatientListOptions, type Physician, type TrackOptions, TruthProvider, type TruthProviderProps, type TruthTrackingContextValue, TruthTrackingProvider, type TruthTrackingProviderProps, type UseAppointmentListOptions, type UsePatientBasicOptions, type UsePatientBasicResult, type UsePatientListOptions, type UsePatientMedicalOptions, type UsePatientPhotoOptions, useAppointment, useAppointmentByElationId, useAppointments, usePatient, usePatientBasic, usePatientByElationId, usePatientByHintId, usePatientMedical, usePatientPhoto, usePatients, usePharmacyByNcpdpId, usePhysicianByElationId, usePhysiciansByElationIds, useTruth };
+export { type Appointment, type AppointmentListOptions, type ConversationListItem, type ConversationMessage, type ConversationMessageRow, type ConversationRow, type EventPayloadMap, type EventType, type Patient, type PatientListOptions, type PermissionStatus, type Physician, type TrackOptions, TruthProvider, type TruthProviderProps, type TruthTrackingContextValue, TruthTrackingProvider, type TruthTrackingProviderProps, type UseAppointmentListOptions, type UseConversationMessagesOptions, type UseConversationsFilters, type UseMessagesOptions, type UseNotificationsOptions, type UseNotificationsResult, type UsePatientBasicOptions, type UsePatientBasicResult, type UsePatientListOptions, type UsePatientMedicalOptions, type UsePatientPhotoOptions, type UseQueryResult, useAppointment, useAppointmentByElationId, useAppointments, useConversationByPhonePair, useConversationMessages, useConversations, useMessages, useNotifications, usePatient, usePatientBasic, usePatientByElationId, usePatientByHintId, usePatientMedical, usePatientPhoto, usePatients, usePharmacyByNcpdpId, usePhysicianByElationId, usePhysiciansByElationIds, useTruth, useUnreadCount };

package/dist/react.d.ts

@@ -2,6 +2,194 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import { ConvexReactClient } from 'convex/react';
 
+/**
+ * React hooks for Truth SDK — reactive conversation + message data.
+ *
+ * Wraps Convex queries owned by the Truth backend so consumers (CommHub
+ * Expo frontend) get live-updating conversation lists, message threads,
+ * and unread totals without managing subscriptions themselves.
+ *
+ * **Hook contract:** every hook in this file returns
+ * `{ data, loading, error }`. `data` is `undefined` while loading and
+ * also when the underlying query is `"skip"`'d (caller didn't pass the
+ * required arg yet). `loading` is `true` only while a real subscription
+ * is in-flight; once `data` resolves (even to `null`) `loading` flips
+ * to `false`. `error` is reserved for SDK-side validation — Convex
+ * itself throws on subscribe rather than returning an error value, so
+ * unhandled query errors propagate as React errors and should be caught
+ * with an error boundary.
+ *
+ * **Backed by PR #110 schema (commit `41dbb59` on
+ * `feat/migrate-dialpad-webhook-and-messages-to-truth`):**
+ *  - `conversations:listForUser` → `useConversations`
+ *  - `conversations:getUnreadTotalForUser` → `useUnreadCount`
+ *  - `conversations:getByPhonePair` → `useConversationByPhonePair`
+ *  - `conversationMessages:getByConversationId` → `useMessages`
+ *
+ * **Deliberately NOT shipped here (no backend query yet — flagged in
+ * PR #111 body for follow-up):**
+ *  - Single-conversation-by-id lookup. Convex `conversations` has no
+ *    `get(id)` query — only `getByPhonePair`. CommHub uses phonePair as
+ *    the primary handle, so the byPair flavor is what consumers need;
+ *    if id-based lookup is needed later we can add a `conversations:get`
+ *    in Truth.
+ *  - Participants / "seen by" hook. The migrated schema has no
+ *    `conversationParticipants` table — read state is per-user via
+ *    `conversationReads` and there's no public list query for it yet.
+ *  - `markRead` mutation. PR #110 declares `markRead` as
+ *    `internalMutation`, so the frontend can't invoke it directly — it
+ *    has to go through a Truth HTTP endpoint, or webhook-migrator needs
+ *    to flip it to a public `mutation`. Flagged for a follow-up.
+ *
+ * Must be used within `<TruthProvider />` (see `./provider`).
+ *
+ * @example
+ * ```tsx
+ * import {
+ *   useConversations,
+ *   useConversationByPhonePair,
+ *   useMessages,
+ *   useUnreadCount,
+ * } from '@hipnation-truth/sdk/react';
+ *
+ * function Inbox({ userId }: { userId: string }) {
+ *   const { data: convos, loading } = useConversations({ userId });
+ *   const { data: unread } = useUnreadCount(userId);
+ *   if (loading) return <Spinner />;
+ *   return (
+ *     <div>
+ *       <Badge count={unread ?? 0} />
+ *       {convos?.map((c) => <ConvoRow key={c.id} convo={c} />)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+/**
+ * Row shape returned by `conversations:listForUser` — joins the base
+ * `conversations` row with the caller's per-user `conversationReads`
+ * entry so unread state lives on each item.
+ */
+interface ConversationListItem {
+    /** Convex id of the conversation row. */
+    id: string;
+    patientPhone: string;
+    providerPhone: string;
+    /** Sorted-digit-pair key (commutative — same regardless of direction). */
+    phonePair: string;
+    /** Truth-side patient id, when the kinesis pipeline could resolve it. */
+    patientId: string | null;
+    /** ISO timestamp of the most recent message in the conversation. */
+    lastMessageAt: string;
+    /** Caller's unread count for this conversation. */
+    unreadCount: number;
+    /** ISO timestamp of when the caller last marked the conversation read. */
+    lastReadAt: string | null;
+}
+/**
+ * Raw `conversations` table row — what `getByPhonePair` returns. No
+ * unread / read joining; for that, prefer `useConversations`.
+ */
+interface ConversationRow {
+    _id: string;
+    _creationTime: number;
+    patientPhone: string;
+    providerPhone: string;
+    phonePair: string;
+    patientId: string | null;
+    lastEventId: string | null;
+    lastMessageAt: string;
+    createdAt: string;
+}
+/**
+ * Message row returned by `conversationMessages:getByConversationId` —
+ * calls + SMS merged chronologically. Mirrors `ConversationMessage`
+ * already exported from the SDK; re-exported here under a clearer name
+ * for the new hook surface.
+ */
+interface ConversationMessageRow {
+    kind: "call" | "sms";
+    id: string;
+    providerId: string;
+    state: string | null;
+    direction: string | null;
+    fromNumber: string | null;
+    toNumber: string | null;
+    voicemailLink: string | null;
+    duration: number | null;
+    text: string | null;
+    mms: boolean;
+    mmsUrl: string | null;
+    messageStatus: string | null;
+    occurredAt: string;
+    conversationId: string | null;
+    patientId: string | null;
+}
+interface UseQueryResult<T> {
+    /**
+     * Query data. `undefined` while loading or while the query is
+     * intentionally skipped (e.g. caller hasn't supplied `userId` yet).
+     */
+    data: T | undefined;
+    /** True only while a real subscription is in-flight. */
+    loading: boolean;
+    /**
+     * Reserved for client-side validation errors surfaced by the SDK
+     * itself. Convex query errors propagate as React errors and should
+     * be caught with an error boundary.
+     */
+    error: Error | undefined;
+}
+interface UseConversationsFilters {
+    /**
+     * Truth user id (the Better Auth subject). Pass `undefined` to skip
+     * the query — useful when the auth session is still loading.
+     */
+    userId: string | null | undefined;
+    /** Page size. Server caps at 100 by default. */
+    limit?: number;
+}
+interface UseMessagesOptions {
+    /** Page size. Server caps at 200 by default. */
+    limit?: number;
+}
+/**
+ * Subscribe to a user's conversations — joined with their per-conversation
+ * unread count, sorted by most recent message. Updates live as new
+ * SMS / calls land in Convex and the webhook bumps `unreadCount`.
+ *
+ * Returns `{ data: undefined, loading: false }` while the auth session
+ * resolves (`userId === undefined`); not an error, just a skip.
+ */
+declare function useConversations(filters: UseConversationsFilters): UseQueryResult<ConversationListItem[]>;
+/**
+ * Look up a single conversation by its normalized phonePair (sorted
+ * digit-pair, e.g. `"5125550123|6505551234"`). Returns `null` if no
+ * conversation exists yet for that pair.
+ *
+ * Use the `phonePairKey(patientPhone, providerPhone)` helper exposed by
+ * the Truth Convex module to derive the key from raw phone strings.
+ */
+declare function useConversationByPhonePair(phonePair: string | null | undefined): UseQueryResult<ConversationRow | null>;
+/**
+ * Subscribe to a paginated message stream for a single conversation.
+ * Calls + SMS merged chronologically, newest-first. Live as the
+ * kinesis consumer writes to `messageCalls` / `messageSms`.
+ *
+ * Pass the Convex `_id` of the conversation row (from
+ * `useConversations` / `useConversationByPhonePair`) as
+ * `conversationId`.
+ */
+declare function useMessages(conversationId: string | null | undefined, options?: UseMessagesOptions): UseQueryResult<ConversationMessageRow[]>;
+/**
+ * Subscribe to the user's total unread message count across all
+ * conversations. Backs the inbox tab badge in CommHub.
+ *
+ * Returns `0` when the underlying query resolves with no unread
+ * messages, `undefined` while loading or when `userId` is missing.
+ */
+declare function useUnreadCount(userId: string | null | undefined): UseQueryResult<number>;
+
 /**
  * React hooks for Truth SDK — real-time Convex-backed data access.
  *
@@ -184,6 +372,98 @@ interface UsePatientPhotoOptions {
  * binary from Elation + upload to S3.
  */
 declare function usePatientPhoto(elationId: number | undefined, options?: UsePatientPhotoOptions): any;
+interface ConversationMessage {
+    kind: "call" | "sms";
+    id: string;
+    providerId: string;
+    state: string | null;
+    direction: string | null;
+    fromNumber: string | null;
+    toNumber: string | null;
+    voicemailLink: string | null;
+    duration: number | null;
+    text: string | null;
+    mms: boolean;
+    mmsUrl: string | null;
+    messageStatus: string | null;
+    occurredAt: string;
+    conversationId: string | null;
+    patientId: string | null;
+}
+interface UseConversationMessagesOptions {
+    /** Max items to return (default 200). */
+    limit?: number;
+}
+/**
+ * Subscribe to a conversation's calls + SMS merged chronologically.
+ * Pass the patient phone + the provider phone — Truth computes a
+ * normalized pair key server-side so formatting differences don't
+ * matter.
+ *
+ * Returns `undefined` while loading, then `ConversationMessage[]`
+ * sorted newest-first. Updates live as new webhook events land in
+ * Convex via the kinesis consumer.
+ */
+declare function useConversationMessages(input: {
+    phoneA?: string;
+    phoneB?: string;
+    conversationId?: string;
+}, options?: UseConversationMessagesOptions): ConversationMessage[] | undefined;
+
+/**
+ * useNotifications — Truth SDK React hook for push notifications.
+ *
+ * Shape-compatible with `expo-notifications` where practical so
+ * consumers port with minimal change. The hook dynamically imports
+ * `expo-notifications` so the SDK doesn't hard-depend on Expo —
+ * consumers running on a non-Expo runtime (e.g. a server test harness)
+ * can still import the SDK without Metro blowing up.
+ *
+ * Exposes:
+ *   - permissionStatus  — "granted" / "denied" / "undetermined"
+ *   - devicePushToken   — native APNs/FCM token (undefined until register)
+ *   - register()        — request permission, fetch token, register with Truth
+ *   - unregister()      — revoke the device
+ *   - addReceivedListener / addResponseListener — re-exports of expo's
+ *   - getBadgeCount / setBadgeCount — re-exports of expo's
+ *
+ * Web push (VAPID subscription) lands in Phase 3.
+ */
+type PermissionStatus = "granted" | "denied" | "undetermined" | "unknown";
+interface UseNotificationsOptions {
+    /** Truth API base URL, e.g. https://app.truth.communication-hub.com */
+    apiBaseUrl: string;
+    /** `hn_live_*` API key for the caller's application. */
+    apiKey: string;
+    /** Current user id — used when registering the device. */
+    userId: string | null | undefined;
+    /** Optional app version string stored on the device row. */
+    appVersion?: string;
+    /**
+     * Auto-register on mount when permission is already granted.
+     * Default: true. Set false if you want to control the registration
+     * lifecycle yourself.
+     */
+    autoRegister?: boolean;
+    /** VAPID public key for web push. Fetched automatically if omitted. */
+    vapidPublicKey?: string;
+    /** Path to the service worker file. Default: "/truth-sw.js" */
+    serviceWorkerPath?: string;
+}
+interface UseNotificationsResult {
+    permissionStatus: PermissionStatus;
+    devicePushToken: string | null;
+    register: () => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    unregister: () => Promise<void>;
+    addReceivedListener: (listener: (n: unknown) => void) => () => void;
+    addResponseListener: (listener: (r: unknown) => void) => () => void;
+    getBadgeCount: () => Promise<number>;
+    setBadgeCount: (count: number) => Promise<void>;
+}
+declare function useNotifications(options: UseNotificationsOptions): UseNotificationsResult;
 
 interface TruthProviderProps {
     /** Truth environment — determines which Convex deployment to connect to */
@@ -615,4 +895,4 @@ interface PatientListOptions {
     cursor?: string;
 }
 
-export { type Appointment, type AppointmentListOptions, type EventPayloadMap, type EventType, type Patient, type PatientListOptions, type Physician, type TrackOptions, TruthProvider, type TruthProviderProps, type TruthTrackingContextValue, TruthTrackingProvider, type TruthTrackingProviderProps, type UseAppointmentListOptions, type UsePatientBasicOptions, type UsePatientBasicResult, type UsePatientListOptions, type UsePatientMedicalOptions, type UsePatientPhotoOptions, useAppointment, useAppointmentByElationId, useAppointments, usePatient, usePatientBasic, usePatientByElationId, usePatientByHintId, usePatientMedical, usePatientPhoto, usePatients, usePharmacyByNcpdpId, usePhysicianByElationId, usePhysiciansByElationIds, useTruth };
+export { type Appointment, type AppointmentListOptions, type ConversationListItem, type ConversationMessage, type ConversationMessageRow, type ConversationRow, type EventPayloadMap, type EventType, type Patient, type PatientListOptions, type PermissionStatus, type Physician, type TrackOptions, TruthProvider, type TruthProviderProps, type TruthTrackingContextValue, TruthTrackingProvider, type TruthTrackingProviderProps, type UseAppointmentListOptions, type UseConversationMessagesOptions, type UseConversationsFilters, type UseMessagesOptions, type UseNotificationsOptions, type UseNotificationsResult, type UsePatientBasicOptions, type UsePatientBasicResult, type UsePatientListOptions, type UsePatientMedicalOptions, type UsePatientPhotoOptions, type UseQueryResult, useAppointment, useAppointmentByElationId, useAppointments, useConversationByPhonePair, useConversationMessages, useConversations, useMessages, useNotifications, usePatient, usePatientBasic, usePatientByElationId, usePatientByHintId, usePatientMedical, usePatientPhoto, usePatients, usePharmacyByNcpdpId, usePhysicianByElationId, usePhysiciansByElationIds, useTruth, useUnreadCount };