@hipnation-truth/sdk 0.6.0 → 0.7.1

package/dist/react.d.ts

@@ -1,655 +0,0 @@
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { ConvexReactClient } from 'convex/react';
-
-/**
- * React hooks for Truth SDK — real-time Convex-backed data access.
- *
- * These hooks use Convex React subscriptions for live-updating data.
- * Must be used within a ConvexProvider (see TruthProvider).
- *
- * @example
- * ```tsx
- * import { usePatients, useAppointments } from '@hipnation-truth/sdk/react';
- *
- * function PatientList() {
- *   const patients = usePatients({ limit: 20 });
- *   return patients?.map(p => <div key={p._id}>{p.firstName} {p.lastName}</div>);
- * }
- * ```
- */
-interface UsePatientListOptions {
-    search?: string;
-    lastName?: string;
-    limit?: number;
-}
-/**
- * Subscribe to a list of patients with optional search and filtering.
- * Returns undefined while loading, then an array of patients.
- */
-declare function usePatients(options?: UsePatientListOptions): any;
-/**
- * Subscribe to a single patient by Convex document ID.
- */
-declare function usePatient(id: string): any;
-/**
- * Subscribe to a patient by their Elation ID.
- */
-declare function usePatientByElationId(elationId: string): any;
-/**
- * Subscribe to a patient by their Hint ID.
- */
-declare function usePatientByHintId(hintId: string): any;
-interface UseAppointmentListOptions {
-    patientId?: string;
-    status?: string;
-    startDate?: string;
-    endDate?: string;
-    limit?: number;
-}
-/**
- * Subscribe to a list of appointments with optional filtering.
- */
-declare function useAppointments(options?: UseAppointmentListOptions): any;
-/**
- * Subscribe to a single appointment by Convex document ID.
- */
-declare function useAppointment(id: string): any;
-/**
- * Subscribe to an appointment by its Elation ID.
- */
-declare function useAppointmentByElationId(elationId: string): any;
-interface Physician {
-    _id: string;
-    elationId: number;
-    firstName?: string;
-    lastName?: string;
-    npi?: string;
-    credentials?: string;
-    specialties?: string[];
-    practice?: number;
-    email?: string;
-    phone?: string;
-    lastSyncedAt: string;
-}
-/**
- * Resolve a batch of physicians by their Elation IDs. Returns an array
- * of physicians that exist in Convex; missing ids are silently dropped.
- *
- * Use this to resolve medication `prescribing_physician` / appointment
- * physician ids to display names, avoiding the per-physician HTTP
- * round-trip through Truth's Elation proxy.
- *
- * Pass `undefined` (or an empty array) to skip the query — the hook
- * returns `undefined` until you pass a populated list.
- */
-declare function usePhysiciansByElationIds(ids: number[] | undefined): any;
-/**
- * Subscribe to a single physician by their Elation ID.
- */
-declare function usePhysicianByElationId(id: number | undefined): any;
-interface UsePatientMedicalOptions {
-    /**
-     * Base URL of the Truth API. Required to trigger the background refresh
-     * (e.g. `https://app.truth.communication-hub.com`). If omitted, the hook
-     * only reads from Convex and does not refresh.
-     */
-    apiBaseUrl?: string;
-    /** API key used for the refresh call. */
-    apiKey?: string;
-    /**
-     * If true, suppress the background refresh. Useful when you know the
-     * data was just refreshed by another component on the page.
-     */
-    skipRefresh?: boolean;
-}
-/**
- * Composite hook that returns a patient's medical records — medications,
- * problems, allergies, appointments — from the Convex cache.
- *
- * On mount (and when `elationId` changes) fires a background refresh
- * 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.
- */
-declare function usePatientMedical(elationId: number | undefined, options?: UsePatientMedicalOptions): {
-    medications: unknown[] | undefined;
-    problems: unknown[] | undefined;
-    allergies: unknown[] | undefined;
-    appointments: unknown[] | undefined;
-};
-interface UsePatientBasicOptions {
-    /** Truth API base URL used for the background refresh. */
-    apiBaseUrl?: string;
-    /** API key for the refresh call. */
-    apiKey?: string;
-    /** Suppress the background refresh. */
-    skipRefresh?: boolean;
-}
-interface UsePatientBasicResult {
-    /**
-     * Raw Elation patient payload (matches the shape Elation's
-     * `/patients/{id}` returns — `first_name`, `last_name`, `phones`, etc).
-     * Returns `undefined` while the cache miss is loading, `null` if the
-     * patient isn't in Convex yet (first-open-after-backfill).
-     */
-    elationPatient: Record<string, unknown> | null | undefined;
-    /**
-     * Raw Hint patient payload (matches the shape Hint's
-     * `/provider/patients/{id}` returns — `memberships`, `account`,
-     * `phones`, etc).
-     */
-    hintPatient: Record<string, unknown> | null | undefined;
-    /**
-     * The full Convex row for Elation (includes `elationId`, `lastSyncedAt`,
-     * `photoS3Key`, `preferredPharmacyNcpdpId`, etc). Use this when you
-     * need the structured/typed fields rather than the raw Elation payload.
-     */
-    elationRow: Record<string, unknown> | null | undefined;
-    /**
-     * The full Convex row for Hint. Similar relationship to `hintPatient`.
-     */
-    hintRow: Record<string, unknown> | null | undefined;
-    /** True while either cache miss is still pending. */
-    loading: boolean;
-}
-/**
- * Composite hook returning a patient's basic details — Hint demographics
- * + memberships + account, Elation demographics + clinical metadata —
- * from the Convex cache.
- *
- * On mount (and when inputs change) fires a background refresh against
- * `/api/patients/basic/refresh` so stale rows get pulled fresh without
- * blocking render. Returns cached data immediately; Convex subscription
- * updates the UI when refresh completes.
- */
-declare function usePatientBasic(input: {
-    hintId?: string;
-    elationId?: number;
-}, options?: UsePatientBasicOptions): UsePatientBasicResult;
-/**
- * Read a shared pharmacy row by NCPDP id. Backs the pharmacy card in
- * the patient panel (from Elation's preferred_pharmacy reference).
- */
-declare function usePharmacyByNcpdpId(ncpdpId: string | undefined): any;
-interface UsePatientPhotoOptions {
-    apiBaseUrl?: string;
-    apiKey?: string;
-    skipRefresh?: boolean;
-}
-/**
- * Subscribe to a patient's profile photo (s3Key + metadata). The
- * consumer constructs a download URL via the Truth attachments resource
- * (signed S3 URL). Fires a background refresh to pull the latest photo
- * 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;
-
-interface TruthProviderProps {
-    /** Truth environment — determines which Convex deployment to connect to */
-    environment?: string;
-    /** Override the Convex URL directly */
-    convexUrl?: string;
-    children: ReactNode;
-}
-declare function TruthProvider({ environment, convexUrl, children, }: TruthProviderProps): react.FunctionComponentElement<{
-    client: ConvexReactClient;
-    children?: React.ReactNode;
-}>;
-
-/**
- * Typed event definitions for the Truth Platform event store.
- *
- * All 26 event types from the Communication Hub -> Truth Event Store Contract.
- * Events are grouped by domain and include typed payload interfaces.
- */
-declare const CONVERSATION_EVENTS: {
-    readonly created: "conversation.created.v1";
-    readonly messageSent: "conversation.message_sent.v1";
-    readonly messageReceived: "conversation.message_received.v1";
-    readonly markedRead: "conversation.marked_read.v1";
-    readonly attachmentUploaded: "conversation.attachment_uploaded.v1";
-    readonly attachmentDownloaded: "conversation.attachment_downloaded.v1";
-};
-declare const CALL_EVENTS: {
-    readonly initiated: "call.initiated.v1";
-    readonly connected: "call.connected.v1";
-    readonly ended: "call.ended.v1";
-    readonly missed: "call.missed.v1";
-};
-declare const TASK_EVENTS: {
-    readonly created: "task.created.v1";
-    readonly assigned: "task.assigned.v1";
-    readonly statusChanged: "task.status_changed.v1";
-};
-declare const REMINDER_EVENTS: {
-    readonly scheduled: "reminder.scheduled.v1";
-    readonly triggered: "reminder.triggered.v1";
-};
-declare const TRANSLATION_EVENTS: {
-    readonly requested: "translation.requested.v1";
-    readonly completed: "translation.completed.v1";
-};
-declare const NOTIFICATION_EVENTS: {
-    readonly sent: "notification.sent.v1";
-    readonly delivered: "notification.delivered.v1";
-    readonly opened: "notification.opened.v1";
-};
-declare const PROVIDER_EVENTS: {
-    readonly syncStarted: "provider.sync_started.v1";
-    readonly syncSucceeded: "provider.sync_succeeded.v1";
-    readonly syncFailed: "provider.sync_failed.v1";
-};
-declare const AUTH_EVENTS: {
-    readonly loginSucceeded: "auth.login_succeeded.v1";
-    readonly loginFailed: "auth.login_failed.v1";
-};
-declare const SECURITY_EVENTS: {
-    readonly accessDenied: "security.access_denied.v1";
-};
-type ConversationEventType = (typeof CONVERSATION_EVENTS)[keyof typeof CONVERSATION_EVENTS];
-type CallEventType = (typeof CALL_EVENTS)[keyof typeof CALL_EVENTS];
-type TaskEventType = (typeof TASK_EVENTS)[keyof typeof TASK_EVENTS];
-type ReminderEventType = (typeof REMINDER_EVENTS)[keyof typeof REMINDER_EVENTS];
-type TranslationEventType = (typeof TRANSLATION_EVENTS)[keyof typeof TRANSLATION_EVENTS];
-type NotificationEventType = (typeof NOTIFICATION_EVENTS)[keyof typeof NOTIFICATION_EVENTS];
-type ProviderEventType = (typeof PROVIDER_EVENTS)[keyof typeof PROVIDER_EVENTS];
-type AuthEventType = (typeof AUTH_EVENTS)[keyof typeof AUTH_EVENTS];
-type SecurityEventType = (typeof SECURITY_EVENTS)[keyof typeof SECURITY_EVENTS];
-/**
- * Union of all 26 registered event type strings.
- */
-type EventType = ConversationEventType | CallEventType | TaskEventType | ReminderEventType | TranslationEventType | NotificationEventType | ProviderEventType | AuthEventType | SecurityEventType;
-interface ConversationCreatedPayload {
-    channel: string;
-    origin_system: string;
-    participant_count: number;
-}
-interface ConversationMessageSentPayload {
-    channel: string;
-    direction: string;
-    message_chars: number;
-    has_attachment: boolean;
-    provider_system: string;
-}
-interface ConversationMessageReceivedPayload {
-    channel: string;
-    direction: string;
-    message_chars: number;
-    provider_system: string;
-}
-interface ConversationMarkedReadPayload {
-    read_by_actor_id: string;
-    unread_count_before: number;
-    unread_count_after: number;
-}
-interface ConversationAttachmentUploadedPayload {
-    attachment_id: string;
-    mime_type: string;
-    size_bytes: number;
-    storage_class: string;
-}
-interface ConversationAttachmentDownloadedPayload {
-    attachment_id: string;
-    download_actor_type: string;
-    access_path: string;
-}
-interface CallInitiatedPayload {
-    direction: string;
-    provider_system: string;
-    from_number_ref: string;
-    to_number_ref: string;
-}
-interface CallConnectedPayload {
-    provider_system: string;
-    ring_duration_ms: number;
-}
-interface CallEndedPayload {
-    provider_system: string;
-    duration_ms: number;
-    end_reason: string;
-    disposition: string;
-}
-interface CallMissedPayload {
-    provider_system: string;
-    miss_reason: string;
-}
-interface TaskCreatedPayload {
-    task_id: string;
-    created_by: string;
-    assigned_to: string;
-    priority: string;
-    due_at: string;
-}
-interface TaskAssignedPayload {
-    task_id: string;
-    assigned_to: string;
-    assigned_by: string;
-}
-interface TaskStatusChangedPayload {
-    task_id: string;
-    status_from: string;
-    status_to: string;
-    changed_by: string;
-}
-interface ReminderScheduledPayload {
-    reminder_id: string;
-    conversation_id: string;
-    scheduled_for: string;
-    scheduled_by: string;
-}
-interface ReminderTriggeredPayload {
-    reminder_id: string;
-    trigger_result: string;
-    notification_attempted: boolean;
-}
-interface TranslationRequestedPayload {
-    target_language: string;
-    source_language: string;
-    char_count: number;
-    mode: string;
-}
-interface TranslationCompletedPayload {
-    target_language: string;
-    provider: string;
-    latency_ms: number;
-    success: boolean;
-    error_code?: string;
-}
-interface NotificationSentPayload {
-    notification_id: string;
-    channel: string;
-    platform: string;
-    recipient_ref: string;
-    success: boolean;
-}
-interface NotificationDeliveredPayload {
-    notification_id: string;
-    platform: string;
-    delivered_at: string;
-}
-interface NotificationOpenedPayload {
-    notification_id: string;
-    platform: string;
-    opened_at: string;
-}
-interface ProviderSyncStartedPayload {
-    provider_system: string;
-    operation: string;
-    scope: string;
-    batch_id: string;
-}
-interface ProviderSyncSucceededPayload {
-    provider_system: string;
-    operation: string;
-    batch_id: string;
-    records_processed: number;
-    duration_ms: number;
-}
-interface ProviderSyncFailedPayload {
-    provider_system: string;
-    operation: string;
-    batch_id: string;
-    error_code: string;
-    retryable: boolean;
-}
-interface AuthLoginSucceededPayload {
-    auth_provider: string;
-    platform: string;
-    session_ref: string;
-}
-interface AuthLoginFailedPayload {
-    auth_provider: string;
-    platform: string;
-    failure_code: string;
-}
-interface SecurityAccessDeniedPayload {
-    resource: string;
-    policy: string;
-    reason_code: string;
-    actor_id: string;
-}
-/**
- * Maps each event type string to its required payload interface.
- */
-interface EventPayloadMap {
-    "conversation.created.v1": ConversationCreatedPayload;
-    "conversation.message_sent.v1": ConversationMessageSentPayload;
-    "conversation.message_received.v1": ConversationMessageReceivedPayload;
-    "conversation.marked_read.v1": ConversationMarkedReadPayload;
-    "conversation.attachment_uploaded.v1": ConversationAttachmentUploadedPayload;
-    "conversation.attachment_downloaded.v1": ConversationAttachmentDownloadedPayload;
-    "call.initiated.v1": CallInitiatedPayload;
-    "call.connected.v1": CallConnectedPayload;
-    "call.ended.v1": CallEndedPayload;
-    "call.missed.v1": CallMissedPayload;
-    "task.created.v1": TaskCreatedPayload;
-    "task.assigned.v1": TaskAssignedPayload;
-    "task.status_changed.v1": TaskStatusChangedPayload;
-    "reminder.scheduled.v1": ReminderScheduledPayload;
-    "reminder.triggered.v1": ReminderTriggeredPayload;
-    "translation.requested.v1": TranslationRequestedPayload;
-    "translation.completed.v1": TranslationCompletedPayload;
-    "notification.sent.v1": NotificationSentPayload;
-    "notification.delivered.v1": NotificationDeliveredPayload;
-    "notification.opened.v1": NotificationOpenedPayload;
-    "provider.sync_started.v1": ProviderSyncStartedPayload;
-    "provider.sync_succeeded.v1": ProviderSyncSucceededPayload;
-    "provider.sync_failed.v1": ProviderSyncFailedPayload;
-    "auth.login_succeeded.v1": AuthLoginSucceededPayload;
-    "auth.login_failed.v1": AuthLoginFailedPayload;
-    "security.access_denied.v1": SecurityAccessDeniedPayload;
-}
-/**
- * Subject references for the event. Uses tokenized references only -- no PHI.
- */
-interface EventSubject {
-    patient_ref?: string;
-    conversation_id?: string;
-    task_id?: string;
-    call_id?: string;
-}
-/**
- * Actor who triggered the event.
- */
-interface EventActor {
-    actor_id: string;
-    actor_type: "user" | "system" | "webhook";
-}
-/**
- * Compliance metadata for the event.
- */
-interface EventCompliance {
-    pii_level: "none" | "limited" | "full";
-    contains_phi: boolean;
-    consent_context: string;
-    retention_class: string;
-}
-/**
- * Optional overrides when calling truth.track().
- */
-interface TrackOptions {
-    /** Override the default actor for this event */
-    actor?: EventActor;
-    /** Subject references for this event */
-    subject?: EventSubject;
-    /** Compliance metadata for this event */
-    compliance?: EventCompliance;
-    /** Override the default tenant ID for this event */
-    tenantId?: string;
-    /** Override the occurred_at timestamp (ISO 8601) */
-    occurredAt?: string;
-}
-
-/**
- * Actor context attached to tracked events.
- */
-interface ActorContext {
-    actorId: string;
-    actorType: "user" | "system" | "webhook";
-}
-
-interface TruthTrackingContextValue {
-    track: <T extends EventType>(eventType: T, payload: EventPayloadMap[T], options?: TrackOptions) => void;
-    identify: (actorId: string, actorType: ActorContext["actorType"]) => void;
-}
-interface TruthTrackingProviderProps {
-    /** Truth environment — determines API URL for event delivery */
-    environment?: string;
-    /** Event source identifier */
-    source?: string;
-    /** Source version (git SHA) */
-    sourceVersion?: string;
-    /** Default tenant ID */
-    tenantId?: string;
-    /** API key for authentication */
-    apiKey?: string;
-    children: ReactNode;
-}
-declare function TruthTrackingProvider({ environment, source, sourceVersion, tenantId, apiKey, children, }: TruthTrackingProviderProps): react.FunctionComponentElement<react.ProviderProps<TruthTrackingContextValue | null>>;
-/**
- * Access the Truth tracking context. Must be within a TruthTrackingProvider.
- * Returns `{ track, identify }` for emitting events to Kinesis.
- */
-declare function useTruth(): TruthTrackingContextValue;
-
-/**
- * Appointment interfaces for the Truth SDK.
- */
-/**
- * Normalized appointment record from the Truth platform.
- */
-interface Appointment {
-    /** Truth platform appointment ID */
-    id: string;
-    /** Associated patient ID */
-    patientId: string;
-    /** Provider/practitioner ID */
-    providerId?: string;
-    /** Provider/practitioner name */
-    providerName?: string;
-    /** Appointment start time (ISO 8601) */
-    startTime: string;
-    /** Appointment end time (ISO 8601) */
-    endTime: string;
-    /** Appointment status */
-    status: string;
-    /** Appointment type or reason */
-    appointmentType?: string;
-    /** Visit reason or chief complaint */
-    reason?: string;
-    /** Location or facility name */
-    location?: string;
-    /** Source EHR system (e.g. "elation", "hint") */
-    sourceSystem?: string;
-    /** ID in the source EHR system */
-    sourceId?: string;
-    /** Associated organization/tenant ID */
-    tenantId: string;
-    /** ISO 8601 timestamp of record creation */
-    createdAt: string;
-    /** ISO 8601 timestamp of last update */
-    updatedAt: string;
-}
-/**
- * Options for listing appointments.
- */
-interface AppointmentListOptions {
-    /** Filter by patient ID */
-    patientId?: string;
-    /** Filter by start date (ISO 8601 date string) */
-    startDate?: string;
-    /** Filter by end date (ISO 8601 date string) */
-    endDate?: string;
-    /** Filter by appointment status */
-    status?: string;
-    /** Maximum number of results to return */
-    limit?: number;
-    /** Cursor for pagination */
-    cursor?: string;
-}
-
-/**
- * Patient interfaces for the Truth SDK.
- */
-/**
- * Normalized patient record from the Truth platform.
- */
-interface Patient {
-    /** Truth platform patient ID */
-    id: string;
-    /** Elation EHR patient ID (if linked) */
-    elationId?: string;
-    /** Hint EHR patient ID (if linked) */
-    hintId?: string;
-    /** Patient first name */
-    firstName: string;
-    /** Patient last name */
-    lastName: string;
-    /** Date of birth (ISO 8601 date string, e.g. "1990-01-15") */
-    dateOfBirth?: string;
-    /** Patient sex */
-    sex?: string;
-    /** Primary email address */
-    email?: string;
-    /** Primary phone number */
-    phone?: string;
-    /** Patient status in the system */
-    status: string;
-    /** Associated organization/tenant ID */
-    tenantId: string;
-    /** ISO 8601 timestamp of record creation */
-    createdAt: string;
-    /** ISO 8601 timestamp of last update */
-    updatedAt: string;
-}
-/**
- * Options for listing patients.
- */
-interface PatientListOptions {
-    /** Search patients by name, email, or phone */
-    search?: string;
-    /** Maximum number of results to return */
-    limit?: number;
-    /** Cursor for pagination */
-    cursor?: string;
-}
-
-export { type Appointment, type AppointmentListOptions, type ConversationMessage, type EventPayloadMap, type EventType, type Patient, type PatientListOptions, type Physician, type TrackOptions, TruthProvider, type TruthProviderProps, type TruthTrackingContextValue, TruthTrackingProvider, type TruthTrackingProviderProps, type UseAppointmentListOptions, type UseConversationMessagesOptions, type UsePatientBasicOptions, type UsePatientBasicResult, type UsePatientListOptions, type UsePatientMedicalOptions, type UsePatientPhotoOptions, useAppointment, useAppointmentByElationId, useAppointments, useConversationMessages, usePatient, usePatientBasic, usePatientByElationId, usePatientByHintId, usePatientMedical, usePatientPhoto, usePatients, usePharmacyByNcpdpId, usePhysicianByElationId, usePhysiciansByElationIds, useTruth };