@hipnation-truth/sdk 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,493 @@
+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 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 EventPayloadMap, type EventType, type Patient, type PatientListOptions, type TrackOptions, TruthProvider, type TruthProviderProps, type TruthTrackingContextValue, TruthTrackingProvider, type TruthTrackingProviderProps, type UseAppointmentListOptions, type UsePatientListOptions, useAppointment, useAppointmentByElationId, useAppointments, usePatient, usePatientByElationId, usePatientByHintId, usePatients, useTruth };