@hipnation-truth/sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,858 @@
+import { ConvexHttpClient } from 'convex/browser';
+
+/**
+ * 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;
+}
+
+/**
+ * Configuration interfaces for the Truth SDK.
+ */
+/**
+ * Environment options for the Truth platform.
+ */
+declare const ENVIRONMENTS: {
+    readonly local: "local";
+    readonly staging: "staging";
+    readonly uat: "uat";
+    readonly production: "production";
+};
+type Environment = (typeof ENVIRONMENTS)[keyof typeof ENVIRONMENTS];
+/**
+ * Configuration for initializing a TruthClient.
+ */
+interface TruthClientConfig {
+    /** API key for authenticating with the Truth platform (e.g. "hn_live_...") */
+    apiKey: string;
+    /** Target environment */
+    environment: Environment;
+    /** Override the default Convex URL for data access */
+    convexUrl?: string;
+    /** Event source identifier (e.g. "communication-hub.backend") */
+    source?: string;
+    /** Git SHA or version string for event source versioning */
+    sourceVersion?: string;
+    /** Default tenant (organization) ID for events */
+    tenantId?: string;
+    /** Number of events to buffer before flushing (default: 25) */
+    batchSize?: number;
+    /** Interval in milliseconds between automatic flushes (default: 5000) */
+    flushIntervalMs?: number;
+    /** Base URL for the Truth API (overrides environment-based default) */
+    apiBaseUrl?: string;
+}
+/**
+ * Actor context attached to tracked events.
+ */
+interface ActorContext {
+    actorId: string;
+    actorType: "user" | "system" | "webhook";
+}
+/**
+ * Paginated result wrapper for list operations.
+ */
+interface PaginatedResult<T> {
+    data: T[];
+    cursor: string | null;
+    hasMore: boolean;
+}
+
+/**
+ * AppointmentResource provides data access to normalized appointment records
+ * backed by Convex.
+ */
+
+declare class AppointmentResource {
+    private readonly convex;
+    constructor(convexClient: ConvexHttpClient);
+    /**
+     * Get an appointment by its Truth platform ID.
+     */
+    get(id: string): Promise<Appointment | null>;
+    /**
+     * List appointments with optional filters, pagination, and limit.
+     */
+    list(options?: AppointmentListOptions): Promise<PaginatedResult<Appointment>>;
+}
+
+/**
+ * Dialpad resource — typed access to Truth's Dialpad proxy endpoints.
+ *
+ * @example
+ * ```ts
+ * const sms = await truth.messages.dialpad.sendSms({ from_number, to_number, message });
+ * const call = await truth.messages.dialpad.initiateCall(userId, phoneNumber);
+ * await truth.messages.dialpad.hangupCall(callId);
+ * const url = await truth.messages.dialpad.authenticateVoicemail(voicemailLink);
+ * ```
+ */
+interface SendSmsParams {
+    from_number: string;
+    to_number: string;
+    message?: string;
+    media?: string;
+}
+interface SendSmsResponse {
+    id: string;
+    message_status: string;
+    [key: string]: unknown;
+}
+interface InitiateCallResponse {
+    call_id: number;
+    [key: string]: unknown;
+}
+interface CallStatusResponse {
+    state: string;
+    [key: string]: unknown;
+}
+interface DialpadUser {
+    id: number;
+    emails: string[];
+    first_name?: string;
+    last_name?: string;
+    [key: string]: unknown;
+}
+interface DialpadNumberInfo {
+    user_id?: number;
+    type?: string;
+    [key: string]: unknown;
+}
+interface VoicemailAuthResponse {
+    success: boolean;
+    authenticated_url: string | null;
+    error?: string;
+}
+declare class DialpadResource {
+    private readonly baseUrl;
+    constructor(apiBaseUrl: string);
+    /**
+     * Send an SMS or MMS message via Dialpad.
+     */
+    sendSms(params: SendSmsParams): Promise<SendSmsResponse>;
+    /**
+     * Initiate an outbound call from a Dialpad user to a phone number.
+     */
+    initiateCall(userId: number, phoneNumber: string): Promise<InitiateCallResponse>;
+    /**
+     * Hang up an active call.
+     */
+    hangupCall(callId: number): Promise<void>;
+    /**
+     * Get the status of a call.
+     */
+    getCallStatus(callId: number): Promise<CallStatusResponse | null>;
+    /**
+     * Get a Dialpad user by their user ID.
+     */
+    getUser(userId: string | number): Promise<DialpadUser | null>;
+    /**
+     * Find a Dialpad user by email.
+     */
+    getUserByEmail(email: string): Promise<DialpadUser | null>;
+    /**
+     * Find a Dialpad user by phone number.
+     */
+    getUserByPhoneNumber(phoneNumber: string): Promise<DialpadUser | null>;
+    /**
+     * Get information about a Dialpad phone number.
+     */
+    getNumberInfo(phoneNumber: string): Promise<DialpadNumberInfo | null>;
+    /**
+     * Authenticate a voicemail download URL. Truth appends the Dialpad API key,
+     * follows redirects, and returns the clean URL for client-side playback.
+     */
+    authenticateVoicemail(voicemailLink: string): Promise<string | null>;
+    private get;
+    private post;
+    private put;
+}
+declare class MessagesResource {
+    readonly dialpad: DialpadResource;
+    constructor(apiBaseUrl: string);
+}
+declare class DialpadProxyError extends Error {
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    constructor(method: string, path: string, status: number);
+}
+
+/**
+ * EHR proxy resource — typed access to Truth's EHR proxy endpoints.
+ *
+ * Provides per-provider proxy methods so consumers never construct
+ * proxy URLs manually.
+ *
+ * @example
+ * ```ts
+ * const patient = await truth.ehr.elation.get('/patients/123/');
+ * const notes = await truth.ehr.elation.post('/non_visit_notes/', noteData);
+ * const hintPatient = await truth.ehr.hint.get('/provider/patients/456');
+ * ```
+ */
+declare class EhrProviderProxy {
+    private readonly baseUrl;
+    private readonly provider;
+    constructor(apiBaseUrl: string, provider: string);
+    /**
+     * GET request to the EHR proxy.
+     * @param path — path relative to the provider root (e.g., "/patients/123/")
+     * @param params — optional query parameters
+     */
+    get<T = unknown>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    /**
+     * POST request to the EHR proxy.
+     */
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /**
+     * PUT request to the EHR proxy.
+     */
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /**
+     * PATCH request to the EHR proxy.
+     */
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    /**
+     * DELETE request to the EHR proxy.
+     */
+    delete<T = unknown>(path: string): Promise<T>;
+}
+declare class EhrResource {
+    /** Elation EHR proxy */
+    readonly elation: EhrProviderProxy;
+    /** Hint Health proxy */
+    readonly hint: EhrProviderProxy;
+    constructor(apiBaseUrl: string);
+}
+declare class EhrProxyError extends Error {
+    readonly provider: string;
+    readonly method: string;
+    readonly path: string;
+    readonly status: number;
+    constructor(provider: string, method: string, path: string, status: number);
+}
+
+/**
+ * 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;
+}
+
+/**
+ * PatientResource provides data access to normalized patient records
+ * backed by Convex.
+ */
+
+declare class PatientResource {
+    private readonly convex;
+    constructor(convexClient: ConvexHttpClient);
+    /**
+     * Get a patient by their Truth platform ID.
+     */
+    get(id: string): Promise<Patient | null>;
+    /**
+     * Get a patient by their Elation EHR ID.
+     */
+    getByElationId(elationId: string): Promise<Patient | null>;
+    /**
+     * Get a patient by their Hint EHR ID.
+     */
+    getByHintId(hintId: string): Promise<Patient | null>;
+    /**
+     * List patients with optional search, pagination, and limit.
+     */
+    list(options?: PatientListOptions): Promise<PaginatedResult<Patient>>;
+}
+
+/**
+ * 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";
+};
+/**
+ * All event type constants grouped by domain.
+ */
+declare const EVENT_TYPES: {
+    readonly conversation: {
+        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";
+    };
+    readonly call: {
+        readonly initiated: "call.initiated.v1";
+        readonly connected: "call.connected.v1";
+        readonly ended: "call.ended.v1";
+        readonly missed: "call.missed.v1";
+    };
+    readonly task: {
+        readonly created: "task.created.v1";
+        readonly assigned: "task.assigned.v1";
+        readonly statusChanged: "task.status_changed.v1";
+    };
+    readonly reminder: {
+        readonly scheduled: "reminder.scheduled.v1";
+        readonly triggered: "reminder.triggered.v1";
+    };
+    readonly translation: {
+        readonly requested: "translation.requested.v1";
+        readonly completed: "translation.completed.v1";
+    };
+    readonly notification: {
+        readonly sent: "notification.sent.v1";
+        readonly delivered: "notification.delivered.v1";
+        readonly opened: "notification.opened.v1";
+    };
+    readonly provider: {
+        readonly syncStarted: "provider.sync_started.v1";
+        readonly syncSucceeded: "provider.sync_succeeded.v1";
+        readonly syncFailed: "provider.sync_failed.v1";
+    };
+    readonly auth: {
+        readonly loginSucceeded: "auth.login_succeeded.v1";
+        readonly loginFailed: "auth.login_failed.v1";
+    };
+    readonly security: {
+        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;
+}
+/**
+ * Canonical event envelope. Every tracked event is wrapped in this structure
+ * before being sent to the Truth API.
+ */
+interface EventEnvelope {
+    event_id: string;
+    event_type: string;
+    schema_version: number;
+    occurred_at: string;
+    received_at: string;
+    source: string;
+    source_version: string;
+    tenant_id: string;
+    actor?: EventActor;
+    subject?: EventSubject;
+    compliance?: EventCompliance;
+    payload: Record<string, unknown>;
+}
+/**
+ * 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;
+}
+
+/**
+ * TruthClient -- main entry point for the @hipnation-truth/sdk package.
+ *
+ * Provides:
+ * - `.patients`      Resource-based patient data access (Convex-backed)
+ * - `.appointments`  Resource-based appointment data access (Convex-backed)
+ * - `.ehr`           EHR proxy access (Elation, Hint)
+ * - `.messages`      Messaging proxy access (Dialpad)
+ * - `.track()`       Fire-and-forget event tracking (batched HTTP -> Truth API)
+ * - `.identify()`    Set default actor context for subsequent events
+ * - `.flush()`       Force flush of buffered events (for graceful shutdown)
+ */
+
+declare class TruthClient {
+    /** Patient data resource (Convex-backed) */
+    readonly patients: PatientResource;
+    /** Appointment data resource (Convex-backed) */
+    readonly appointments: AppointmentResource;
+    /** EHR proxy — typed access to Elation and Hint APIs through Truth */
+    readonly ehr: EhrResource;
+    /** Messaging proxy — typed access to Dialpad APIs through Truth */
+    readonly messages: MessagesResource;
+    private readonly convex;
+    private readonly tracker;
+    constructor(config: TruthClientConfig);
+    /**
+     * The resolved Truth API base URL for this environment.
+     * Use this when making HTTP calls to Truth's proxy endpoints
+     * (e.g., EHR proxy, messages proxy).
+     *
+     * @example
+     * ```ts
+     * const url = `${truth.apiBaseUrl}/api/ehr/elation/patients/123`;
+     * ```
+     */
+    get apiBaseUrl(): string;
+    /**
+     * Track an event. Fire-and-forget -- the event is buffered internally
+     * and flushed in batches to the Truth API.
+     *
+     * @example
+     * ```ts
+     * truth.track('conversation.message_sent.v1', {
+     *   channel: 'sms',
+     *   direction: 'outbound',
+     *   message_chars: 140,
+     *   has_attachment: false,
+     *   provider_system: 'dialpad',
+     * });
+     * ```
+     */
+    track<T extends EventType>(eventType: T, payload: EventPayloadMap[T], options?: TrackOptions): void;
+    /**
+     * Set the default actor context for all subsequent tracked events.
+     * Can be overridden per-event via TrackOptions.
+     *
+     * @example
+     * ```ts
+     * truth.identify('user_123', 'user');
+     * ```
+     */
+    identify(actorId: string, actorType: ActorContext["actorType"]): void;
+    /**
+     * Flush all buffered events immediately. Returns a Promise that resolves
+     * when the flush completes. Use this for graceful shutdown.
+     *
+     * @example
+     * ```ts
+     * process.on('SIGTERM', async () => {
+     *   await truth.flush();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Gracefully shut down the client. Flushes all pending events and
+     * releases resources.
+     */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Event tracker with batching, retry, and flush support.
+ *
+ * Buffers events in an internal queue and flushes them to the Truth API
+ * endpoint. Flushes occur when the buffer reaches `batchSize` or every
+ * `flushIntervalMs` milliseconds, whichever comes first.
+ */
+
+/**
+ * Generates a UUID v7 string. Uses crypto.randomUUID where available,
+ * falling back to a timestamp + random bytes implementation.
+ *
+ * UUID v7 layout (RFC 9562):
+ *   48 bits - unix timestamp (ms)
+ *   4 bits  - version (0b0111)
+ *   12 bits - random
+ *   2 bits  - variant (0b10)
+ *   62 bits - random
+ */
+declare function generateUuidV7(): string;
+interface TrackerConfig {
+    apiKey: string;
+    environment: string;
+    source: string;
+    sourceVersion: string;
+    tenantId: string;
+    batchSize: number;
+    flushIntervalMs: number;
+    apiBaseUrl?: string;
+}
+declare class Tracker {
+    private readonly config;
+    readonly apiUrl: string;
+    private queue;
+    private flushTimer;
+    private defaultActor;
+    private isFlushing;
+    private isShutdown;
+    constructor(config: TrackerConfig);
+    /**
+     * Set the default actor context for subsequent events.
+     */
+    setActor(actor: ActorContext): void;
+    /**
+     * Enqueue a typed event for delivery. This is fire-and-forget from
+     * the caller's perspective -- events are buffered and flushed in batches.
+     */
+    track<T extends EventType>(eventType: T, payload: EventPayloadMap[T], options?: TrackOptions): void;
+    /**
+     * Force an immediate flush of all buffered events.
+     * Returns a promise that resolves when the flush completes.
+     */
+    flush(): Promise<void>;
+    /**
+     * Gracefully shut down the tracker. Flushes remaining events and
+     * clears the flush interval.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Send a batch of events to the Truth API with exponential backoff retry.
+     */
+    private sendBatch;
+    private startFlushInterval;
+    private stopFlushInterval;
+    private registerShutdownHooks;
+}
+
+export { AUTH_EVENTS, type ActorContext, type Appointment, type AppointmentListOptions, AppointmentResource, type AuthEventType, type AuthLoginFailedPayload, type AuthLoginSucceededPayload, CALL_EVENTS, CONVERSATION_EVENTS, type CallConnectedPayload, type CallEndedPayload, type CallEventType, type CallInitiatedPayload, type CallMissedPayload, type CallStatusResponse, type ConversationAttachmentDownloadedPayload, type ConversationAttachmentUploadedPayload, type ConversationCreatedPayload, type ConversationEventType, type ConversationMarkedReadPayload, type ConversationMessageReceivedPayload, type ConversationMessageSentPayload, type DialpadNumberInfo, DialpadProxyError, DialpadResource, type DialpadUser, ENVIRONMENTS, EVENT_TYPES, EhrProviderProxy, EhrProxyError, EhrResource, type Environment, type EventActor, type EventCompliance, type EventEnvelope, type EventPayloadMap, type EventSubject, type EventType, type InitiateCallResponse, MessagesResource, NOTIFICATION_EVENTS, type NotificationDeliveredPayload, type NotificationEventType, type NotificationOpenedPayload, type NotificationSentPayload, PROVIDER_EVENTS, type PaginatedResult, type Patient, type PatientListOptions, PatientResource, type ProviderEventType, type ProviderSyncFailedPayload, type ProviderSyncStartedPayload, type ProviderSyncSucceededPayload, REMINDER_EVENTS, type ReminderEventType, type ReminderScheduledPayload, type ReminderTriggeredPayload, SECURITY_EVENTS, type SecurityAccessDeniedPayload, type SecurityEventType, type SendSmsParams, type SendSmsResponse, TASK_EVENTS, TRANSLATION_EVENTS, type TaskAssignedPayload, type TaskCreatedPayload, type TaskEventType, type TaskStatusChangedPayload, type TrackOptions, Tracker, type TranslationCompletedPayload, type TranslationEventType, type TranslationRequestedPayload, TruthClient, type TruthClientConfig, type VoicemailAuthResponse, generateUuidV7 };