@hipnation-truth/sdk 0.26.19 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  import * as convex_browser from 'convex/browser';
2
2
  import { ConvexHttpClient } from 'convex/browser';
3
+ import { z } from 'zod';
4
+ import { FunctionReference } from 'convex/server';
3
5
 
4
6
  /**
5
7
  * Appointment interfaces for the Truth SDK.
@@ -208,7 +210,6 @@ declare class AttachmentsError extends Error {
208
210
  }
209
211
  declare class AttachmentsResource {
210
212
  private readonly baseUrl;
211
- private readonly apiKey;
212
213
  private readonly auth;
213
214
  private readonly convex;
214
215
  constructor(apiBaseUrl: string, apiKey: string, convexClient: ConvexHttpClient, getAuthToken?: AuthTokenFetcher);
@@ -247,6 +248,349 @@ declare class AttachmentsResource {
247
248
  }>;
248
249
  }
249
250
 
251
+ /**
252
+ * CareInboxResource — care-team shared-mailbox email (T12).
253
+ *
254
+ * Writes go through the Truth oRPC `careInbox` router (all
255
+ * `verifiedUserProcedure`, so every call REQUIRES the user JWT):
256
+ * - `linkMessage` POST /api/care-inbox/link
257
+ * - `unlinkMessage` POST /api/care-inbox/unlink
258
+ * - `replyToThread` POST /api/care-inbox/outbound/thread-reply
259
+ * - `composeEmail` POST /api/care-inbox/outbound/compose
260
+ * Reads are Convex queries; use the hooks in `@hipnation-truth/sdk/react`
261
+ * (`useEmailThreads`, …) or `createCareInboxSource`. Nothing here is
262
+ * persisted offline.
263
+ *
264
+ * Two type layers:
265
+ * - `*View` types are the raw Convex query payloads (nullable where the
266
+ * stored row can lack a value).
267
+ * - The contract types (`EmailMessage`, `EmailThreadSummary`, `ThreadPage`,
268
+ * …) mirror comhub's `lib/email/careInboxSource.ts` exactly. `to*`
269
+ * projections turn views into contract shapes: a missing string becomes
270
+ * "" and a missing participant `{ address: "", name: null }` because the
271
+ * contract declares those fields non-null.
272
+ *
273
+ * Errors: every rejection is a `CareInboxError` whose `code` is the comhub
274
+ * `CareInboxErrorCode`, so it satisfies comhub's `Error & { code }` contract
275
+ * as-is. `status` (0 = no HTTP response), `rpcCode` (oRPC / transport code),
276
+ * `reason` and `detail` carry the server detail. `toCareInboxError()` maps
277
+ * anything thrown — including a Convex `ConvexError` from a hook — onto it.
278
+ */
279
+
280
+ type EmailDirection = "inbound" | "outbound";
281
+ /**
282
+ * Thread-list filter. "unlinked" is served only to triage callers (threads
283
+ * with at least one unlinked message); others get forbidden/not_triage.
284
+ */
285
+ type ThreadListFilter = "all" | "unread" | "unlinked";
286
+ interface EmailMailbox {
287
+ id: string;
288
+ /** Shared mailbox address. "" for non-triage callers (server-redacted). */
289
+ address: string;
290
+ displayName: string;
291
+ }
292
+ interface MailboxAccess {
293
+ mailboxes: EmailMailbox[];
294
+ /** May see Unlinked and link/unlink (admin-only until G-TRIAGE). */
295
+ canTriage: boolean;
296
+ }
297
+ interface EmailParticipant {
298
+ address: string;
299
+ name: string | null;
300
+ }
301
+ interface EmailMessage {
302
+ id: string;
303
+ threadId: string;
304
+ mailboxId: string;
305
+ direction: EmailDirection;
306
+ from: EmailParticipant;
307
+ to: EmailParticipant[];
308
+ subject: string;
309
+ /** Epoch milliseconds. */
310
+ sentAt: number;
311
+ hasAttachments: boolean;
312
+ linkedPatientId: string | null;
313
+ linkedPatientName: string | null;
314
+ /** Always null in build 1 (metadata only). */
315
+ bodyText: string | null;
316
+ }
317
+ interface EmailThreadSummary {
318
+ id: string;
319
+ mailboxId: string;
320
+ subject: string;
321
+ /** Epoch milliseconds of the newest message. */
322
+ lastMessageAt: number;
323
+ lastDirection: EmailDirection;
324
+ counterpart: EmailParticipant;
325
+ messageCount: number;
326
+ unreadCount: number;
327
+ /** Triage callers only; always 0 for staff. */
328
+ unlinkedCount: number;
329
+ linkedPatientName: string | null;
330
+ hasAttachments: boolean;
331
+ }
332
+ interface LinkedPatientContact {
333
+ patientId: string;
334
+ name: string;
335
+ email: string | null;
336
+ phone: string | null;
337
+ office: string | null;
338
+ }
339
+ interface EmailThreadDetail {
340
+ summary: EmailThreadSummary;
341
+ mailbox: EmailMailbox;
342
+ /** Oldest first. */
343
+ messages: EmailMessage[];
344
+ /** Not provided in build 1 (always null). */
345
+ patientContact?: LinkedPatientContact | null;
346
+ }
347
+ interface ListThreadsArgs {
348
+ mailboxId?: string;
349
+ filter?: ThreadListFilter;
350
+ cursor?: string | null;
351
+ /** Server default 25, max 50. */
352
+ limit?: number;
353
+ }
354
+ interface ThreadPage {
355
+ threads: EmailThreadSummary[];
356
+ /** A mailbox-filtered page can be short; keep paging while non-null. */
357
+ nextCursor: string | null;
358
+ }
359
+ interface PatientLinkCandidate {
360
+ patientId: string;
361
+ displayName: string;
362
+ /** Office name when known; never an email address. */
363
+ detail: string | null;
364
+ }
365
+ interface LinkMessageArgs {
366
+ messageId: string;
367
+ patientId: string;
368
+ /**
369
+ * Client idempotency key (8-128 chars of `[A-Za-z0-9_:.-]`). A key the
370
+ * server already recorded for the message is a no-op that returns the
371
+ * current state, so a late retry can never undo a newer unlink.
372
+ */
373
+ requestId: string;
374
+ }
375
+ interface UnlinkMessageArgs {
376
+ messageId: string;
377
+ /** Client idempotency key; see `LinkMessageArgs.requestId`. */
378
+ requestId: string;
379
+ }
380
+ interface LinkResult {
381
+ message: EmailMessage;
382
+ }
383
+ interface SendReplyArgs {
384
+ threadId: string;
385
+ body: string;
386
+ clientRequestId: string;
387
+ }
388
+ interface SendEmailArgs {
389
+ to: string;
390
+ subject: string;
391
+ body: string;
392
+ patientId?: string;
393
+ mailboxId: string;
394
+ clientRequestId: string;
395
+ }
396
+ /** Send is disabled in this build (always rejects forbidden/send_disabled). */
397
+ interface SendResult {
398
+ message: EmailMessage;
399
+ thread: EmailThreadSummary;
400
+ }
401
+ interface MarkReadArgs {
402
+ threadId: string;
403
+ }
404
+ interface MarkReadResult {
405
+ thread: EmailThreadSummary;
406
+ }
407
+ /** comhub `CareInboxErrorCode`. */
408
+ type CareInboxErrorCode = "forbidden" | "not_found" | "offline" | "unavailable" | "validation" | "unknown";
409
+ /** `EmailMailbox` plus the server-derived switches. */
410
+ interface CareInboxMailbox extends EmailMailbox {
411
+ mode: "mirror" | "live";
412
+ /** Live mailbox AND send enabled on the deployment. */
413
+ canSend: boolean;
414
+ /** bodyVisibility !== "none" (bodies still need openThreadBodies). */
415
+ bodyVisible: boolean;
416
+ }
417
+ interface CareInboxMailboxAccess extends MailboxAccess {
418
+ mailboxes: CareInboxMailbox[];
419
+ }
420
+ interface CareInboxThreadDetail extends EmailThreadDetail {
421
+ mailbox: CareInboxMailbox;
422
+ /** Whether `openThreadBodies` would serve bodies to this caller. */
423
+ bodyVisible: boolean;
424
+ patientContact: null;
425
+ }
426
+ /** Triage-only unlinked message page (`listUnlinked`). */
427
+ interface UnlinkedMessagePage {
428
+ messages: EmailMessage[];
429
+ nextCursor: string | null;
430
+ }
431
+ /** Back-compat aliases (T12 names). */
432
+ type CareInboxEmailMessage = EmailMessage;
433
+ type CareInboxEmailThreadSummary = EmailThreadSummary;
434
+ type CareInboxLinkResult = LinkResult;
435
+ type CareInboxSendResult = SendResult;
436
+ /**
437
+ * SDK call input: the contract args with `requestId` optional. Omit it and
438
+ * the SDK generates one for this call; pass your own to make retries across
439
+ * calls idempotent.
440
+ */
441
+ type LinkEmailMessageInput = Omit<LinkMessageArgs, "requestId"> & Partial<Pick<LinkMessageArgs, "requestId">>;
442
+ type UnlinkEmailMessageInput = Omit<UnlinkMessageArgs, "requestId"> & Partial<Pick<UnlinkMessageArgs, "requestId">>;
443
+ type ReplyToEmailThreadInput = SendReplyArgs;
444
+ type ComposeEmailInput = SendEmailArgs;
445
+ type EmailParticipantView = EmailParticipant;
446
+ /** `careInboxQueries` message row. `bodyText` is always null from queries. */
447
+ interface EmailMessageView {
448
+ id: string;
449
+ threadId: string | null;
450
+ mailboxId: string;
451
+ direction: EmailDirection;
452
+ from: EmailParticipantView | null;
453
+ to: EmailParticipantView[];
454
+ subject: string | null;
455
+ sentAt: number;
456
+ hasAttachments: boolean;
457
+ linkedPatientId: string | null;
458
+ linkedPatientName: string | null;
459
+ bodyText: null;
460
+ }
461
+ interface EmailThreadSummaryView {
462
+ id: string;
463
+ mailboxId: string;
464
+ subject: string | null;
465
+ lastMessageAt: number;
466
+ lastDirection: EmailDirection | null;
467
+ counterpart: EmailParticipantView | null;
468
+ messageCount: number;
469
+ unreadCount: number;
470
+ unlinkedCount: number;
471
+ linkedPatientId: string | null;
472
+ linkedPatientName: string | null;
473
+ hasAttachments: boolean;
474
+ }
475
+ interface EmailMailboxView {
476
+ id: string;
477
+ displayName: string;
478
+ mode: "mirror" | "live";
479
+ canSend: boolean;
480
+ bodyVisible: boolean;
481
+ /** Present only when the caller can triage. */
482
+ address?: string;
483
+ }
484
+ interface EmailMailboxAccessView {
485
+ mailboxes: EmailMailboxView[];
486
+ canTriage: boolean;
487
+ }
488
+ /** Filters `listThreadsForUser` serves ("unlinked": triage only). */
489
+ type EmailThreadListFilter = ThreadListFilter;
490
+ interface EmailThreadPageView {
491
+ threads: EmailThreadSummaryView[];
492
+ nextCursor: string | null;
493
+ }
494
+ interface EmailThreadDetailView {
495
+ summary: EmailThreadSummaryView;
496
+ mailbox: EmailMailboxView;
497
+ /** Oldest first. Staff: linked only; triage: linked + unlinked. */
498
+ messages: EmailMessageView[];
499
+ bodyVisible: boolean;
500
+ patientContact: null;
501
+ }
502
+ interface UnlinkedEmailPageView {
503
+ messages: EmailMessageView[];
504
+ nextCursor: string | null;
505
+ }
506
+ type PatientLinkCandidateView = PatientLinkCandidate;
507
+ interface MarkEmailThreadReadResult {
508
+ thread: EmailThreadSummaryView;
509
+ }
510
+ interface EmailThreadBodiesView {
511
+ messages: {
512
+ id: string;
513
+ bodyText: string | null;
514
+ }[];
515
+ }
516
+ declare function toEmailMessage(m: EmailMessageView): EmailMessage;
517
+ /**
518
+ * `lastDirection` is null only for a thread with no visible message (it
519
+ * cannot happen for a summary the server lists; kept defensive). Projects to
520
+ * "inbound".
521
+ */
522
+ declare function toEmailThreadSummary(t: EmailThreadSummaryView): EmailThreadSummary;
523
+ declare function toEmailMailbox(m: EmailMailboxView): CareInboxMailbox;
524
+ declare function toMailboxAccess(a: EmailMailboxAccessView): CareInboxMailboxAccess;
525
+ declare function toEmailThreadDetail(d: EmailThreadDetailView): CareInboxThreadDetail;
526
+ declare function toThreadPage(p: EmailThreadPageView): ThreadPage;
527
+ declare function toUnlinkedMessagePage(p: UnlinkedEmailPageView): UnlinkedMessagePage;
528
+ declare function toMarkReadResult(r: MarkEmailThreadReadResult): MarkReadResult;
529
+ /**
530
+ * Machine-readable sub-code. Server-sent: `send_disabled` | `not_triage` |
531
+ * `body_gated` | `unauthenticated` (Convex: no identity). SDK-derived:
532
+ * `unauthenticated` (no user JWT, or HTTP 401). The contract has no auth
533
+ * code, so `unauthenticated` surfaces as `forbidden` on every path.
534
+ */
535
+ type CareInboxErrorReason = "send_disabled" | "not_triage" | "body_gated" | "unauthenticated";
536
+ interface CareInboxErrorFields {
537
+ /** HTTP status; 0 when there was no HTTP response (incl. Convex errors). */
538
+ status?: number;
539
+ /**
540
+ * oRPC code (`FORBIDDEN`, `NOT_FOUND`, …) or, for status 0, `TRANSPORT`
541
+ * (fetch threw), `TIMEOUT`, `NO_API_KEY`, `NO_USER_TOKEN`.
542
+ */
543
+ rpcCode?: string | null;
544
+ reason?: CareInboxErrorReason | null;
545
+ /** Fixed server marker (e.g. `PATIENT_HAS_NO_OFFICE`), when present. */
546
+ detail?: string | null;
547
+ }
548
+ /**
549
+ * The single care-inbox error. `code` is the comhub `CareInboxErrorCode`, so
550
+ * an instance satisfies comhub's `CareInboxError` (`Error & { code }`). The
551
+ * message never carries content, addresses or ids.
552
+ */
553
+ declare class CareInboxError extends Error {
554
+ readonly code: CareInboxErrorCode;
555
+ readonly status: number;
556
+ readonly rpcCode: string | null;
557
+ readonly reason: CareInboxErrorReason | null;
558
+ readonly detail: string | null;
559
+ constructor(code: CareInboxErrorCode, fields?: CareInboxErrorFields);
560
+ }
561
+ /** True for any value carrying a contract `code` (comhub `isCareInboxError`). */
562
+ declare function isCareInboxError(value: unknown): value is Error & {
563
+ code: CareInboxErrorCode;
564
+ };
565
+ /**
566
+ * Coerce anything thrown by the resource, a care-inbox Convex function
567
+ * (`ConvexError({ code, reason? })`, payload on `.data`) or a comhub-style
568
+ * error into a `CareInboxError`. Never throws; unrecognised → `unknown`.
569
+ */
570
+ declare function toCareInboxError(value: unknown): CareInboxError;
571
+ interface CareInboxErrorInfo {
572
+ code: CareInboxErrorCode;
573
+ reason: CareInboxErrorReason | null;
574
+ }
575
+ /** `{ code, reason }` of anything thrown (see `toCareInboxError`). */
576
+ declare function careInboxErrorInfo(err: unknown): CareInboxErrorInfo;
577
+ declare class CareInboxResource {
578
+ /** 30s upstream timeout — matches ConversationsResource. */
579
+ private static readonly REQUEST_TIMEOUT_MS;
580
+ private readonly baseUrl;
581
+ private readonly auth;
582
+ constructor(apiBaseUrl: string, apiKey: string, getAuthToken?: AuthTokenFetcher);
583
+ /** Link one message to a patient (triage only). */
584
+ linkMessage(input: LinkEmailMessageInput): Promise<LinkResult>;
585
+ /** Undo a manual link (triage only). */
586
+ unlinkMessage(input: UnlinkEmailMessageInput): Promise<LinkResult>;
587
+ /** Reply into a thread. This build always rejects 403 `send_disabled`. */
588
+ replyToThread(input: SendReplyArgs): Promise<SendResult>;
589
+ /** Start a new email. This build always rejects 403 `send_disabled`. */
590
+ composeEmail(input: SendEmailArgs): Promise<SendResult>;
591
+ private post;
592
+ }
593
+
250
594
  /** Address a conversation by either Convex `_id` or the phonePair. */
251
595
  interface ConversationAddress {
252
596
  conversationId?: string;
@@ -403,6 +747,19 @@ declare class ConversationsResource {
403
747
  }): Promise<{
404
748
  updated: true;
405
749
  }>;
750
+ /**
751
+ * Mark / unmark a conversation Urgent (conversation-level, shared by
752
+ * participants). Refused if `userId` is not a participant.
753
+ */
754
+ setUrgent(input: {
755
+ conversationId: string;
756
+ userId: string;
757
+ isUrgent: boolean;
758
+ }): Promise<{
759
+ updated: true;
760
+ isUrgent: boolean;
761
+ changed: boolean;
762
+ }>;
406
763
  /**
407
764
  * Zero unread on every conversation the user has reads for, except
408
765
  * those whose `providerPhone` is in `excludedProviderPhones`.
@@ -473,7 +830,6 @@ interface VoicemailAuthResponse {
473
830
  }
474
831
  declare class DialpadResource {
475
832
  private readonly baseUrl;
476
- private readonly apiKey;
477
833
  private readonly auth;
478
834
  constructor(apiBaseUrl: string, apiKey: string, getAuthToken?: AuthTokenFetcher);
479
835
  /**
@@ -539,7 +895,6 @@ declare class DialpadResource {
539
895
  declare class MessagesResource {
540
896
  readonly dialpad: DialpadResource;
541
897
  private readonly baseUrl;
542
- private readonly apiKey;
543
898
  private readonly auth;
544
899
  constructor(apiBaseUrl: string, apiKey: string, getAuthToken?: AuthTokenFetcher);
545
900
  /**
@@ -636,6 +991,16 @@ declare class EhrProxyError extends Error {
636
991
  * Caller assembles the note body (text + bullets). Truth owns the Elation
637
992
  * OAuth token and the HTTP call so applications can drop Elation
638
993
  * credentials from their own config.
994
+ *
995
+ * BREAKING — 0.26.20, `pushConversationToElation`:
996
+ * - AUTH CLASS CHANGED. The server route moved from `applicationProcedure`
997
+ * to `verifiedUserProcedure`, so an API key alone (including a secret
998
+ * `hn_sk_*` or legacy `hn_live_*` key) now gets 401. Callers MUST supply
999
+ * `getAuthToken` on the client so a verified Clerk JWT accompanies the
1000
+ * request; this resource already sends it with `requireUserToken: true`.
1001
+ * - `input.initiatedBy` is DEPRECATED and ignored server-side. The audit
1002
+ * row's actor is the JWT `sub`. Passing a differing value is logged as a
1003
+ * warning server-side and will be removed in a future major.
639
1004
  */
640
1005
 
641
1006
  interface NonVisitNoteBullet {
@@ -666,14 +1031,27 @@ interface PushConversationToElationInput {
666
1031
  /** One-of: conversationId (Convex) or phonePair. */
667
1032
  conversationId?: string;
668
1033
  phonePair?: string;
669
- /** Actor user id — recorded on the audit row. */
670
- initiatedBy: string;
1034
+ /**
1035
+ * @deprecated Ignored by the server; the actor recorded on the audit row is
1036
+ * derived from the verified Clerk JWT (`sub`). Supplying a value has no
1037
+ * effect and will be removed in a future major.
1038
+ */
1039
+ initiatedBy?: string;
671
1040
  /** Pre-assembled note body (transcript-style text). */
672
1041
  noteText: string;
673
1042
  bullets?: NonVisitNoteBullet[];
674
1043
  notesPushed?: number;
675
1044
  messagesPushed?: number;
676
1045
  tasksPushed?: number;
1046
+ /**
1047
+ * Convex ids of the `conversationNotes` rows included in this push. When
1048
+ * set, Truth rejects the call with 409 CONFLICT if any is already marked
1049
+ * sent (unless `resend`), rejects ids that are not in this conversation with
1050
+ * 404, and stamps each note sent on success (never on failure).
1051
+ */
1052
+ noteIds?: string[];
1053
+ /** Explicitly allow re-sending notes already marked sent. Default false. */
1054
+ resend?: boolean;
677
1055
  }
678
1056
  interface PushConversationToElationResult {
679
1057
  success: true;
@@ -682,10 +1060,11 @@ interface PushConversationToElationResult {
682
1060
  notesPushed: number;
683
1061
  messagesPushed: number;
684
1062
  tasksPushed: number;
1063
+ /** Notes stamped sent by this call (empty when no `noteIds` were supplied). */
1064
+ sentNoteIds: string[];
685
1065
  }
686
1066
  declare class NotesResource {
687
1067
  private readonly baseUrl;
688
- private readonly apiKey;
689
1068
  private readonly auth;
690
1069
  constructor(apiBaseUrl: string, apiKey: string, getAuthToken?: AuthTokenFetcher);
691
1070
  /** 30s upstream timeout — Elation API has occasional slow hops; we
@@ -704,6 +1083,11 @@ declare class NotesResource {
704
1083
  * physician/practice in Elation, posts the note, and writes an audit
705
1084
  * row to `elationSyncEvents`. Replaces CommHub's `pushNotesToElation`
706
1085
  * Hasura action.
1086
+ *
1087
+ * Auth: requires a user token. The server runs this route under
1088
+ * `verifiedUserProcedure`, so the API key alone is rejected with 401 —
1089
+ * configure `getAuthToken` on the client. `input.initiatedBy` is ignored;
1090
+ * the audit row's actor is the verified JWT `sub`.
707
1091
  */
708
1092
  pushConversationToElation(input: PushConversationToElationInput): Promise<PushConversationToElationResult>;
709
1093
  }
@@ -831,7 +1215,6 @@ declare class NotificationsError extends Error {
831
1215
  }
832
1216
  declare class NotificationsResource {
833
1217
  private readonly baseUrl;
834
- private readonly apiKey;
835
1218
  private readonly auth;
836
1219
  constructor(apiBaseUrl: string, apiKey: string, getAuthToken?: AuthTokenFetcher);
837
1220
  private post;
@@ -917,7 +1300,6 @@ declare class PatientDetailsError extends Error {
917
1300
  }
918
1301
  declare class PatientDetailsResource {
919
1302
  private readonly baseUrl;
920
- private readonly apiKey;
921
1303
  private readonly auth;
922
1304
  constructor(apiBaseUrl: string, apiKey: string, getAuthToken?: AuthTokenFetcher);
923
1305
  private post;
@@ -1123,6 +1505,126 @@ declare class RemindersResource {
1123
1505
  listByConversation(conversationId: string): Promise<Reminder[]>;
1124
1506
  }
1125
1507
 
1508
+ /**
1509
+ * ReportsResource — member activation report from truth.
1510
+ *
1511
+ * Accesses the Truth API at GET /reports/member-activation,
1512
+ * authenticated with X-API-Key + user JWT (verifiedUserProcedure).
1513
+ *
1514
+ * Replaces the broker pattern: frontend calls truth directly via SDK,
1515
+ * no comhub hop.
1516
+ */
1517
+
1518
+ declare const reportSchema: z.ZodObject<{
1519
+ synthetic: z.ZodBoolean;
1520
+ generatedAt: z.ZodString;
1521
+ employers: z.ZodArray<z.ZodObject<{
1522
+ id: z.ZodString;
1523
+ name: z.ZodString;
1524
+ activeMembers: z.ZodNumber;
1525
+ }, z.core.$strip>>;
1526
+ selected: z.ZodNullable<z.ZodObject<{
1527
+ employerId: z.ZodString;
1528
+ employerName: z.ZodString;
1529
+ kpis: z.ZodObject<{
1530
+ active: z.ZodNumber;
1531
+ linked: z.ZodNumber;
1532
+ activated: z.ZodNumber;
1533
+ needsOutreach: z.ZodNumber;
1534
+ scheduled: z.ZodNumber;
1535
+ needsReview: z.ZodNumber;
1536
+ dataIssue: z.ZodNumber;
1537
+ activationRate: z.ZodNumber;
1538
+ }, z.core.$strip>;
1539
+ coverage: z.ZodObject<{
1540
+ active: z.ZodNumber;
1541
+ linked: z.ZodNumber;
1542
+ unlinked: z.ZodNumber;
1543
+ pct: z.ZodNumber;
1544
+ }, z.core.$strip>;
1545
+ breakdown: z.ZodArray<z.ZodObject<{
1546
+ status: z.ZodEnum<{
1547
+ data: "data";
1548
+ activated: "activated";
1549
+ outreach: "outreach";
1550
+ scheduled: "scheduled";
1551
+ review: "review";
1552
+ }>;
1553
+ label: z.ZodString;
1554
+ count: z.ZodNumber;
1555
+ pct: z.ZodNumber;
1556
+ }, z.core.$strip>>;
1557
+ aging: z.ZodArray<z.ZodObject<{
1558
+ bucket: z.ZodString;
1559
+ total: z.ZodNumber;
1560
+ outreach: z.ZodNumber;
1561
+ scheduled: z.ZodNumber;
1562
+ review: z.ZodNumber;
1563
+ }, z.core.$strip>>;
1564
+ doctors: z.ZodArray<z.ZodObject<{
1565
+ name: z.ZodString;
1566
+ counts: z.ZodObject<{
1567
+ outreach: z.ZodNumber;
1568
+ scheduled: z.ZodNumber;
1569
+ review: z.ZodNumber;
1570
+ data: z.ZodNumber;
1571
+ }, z.core.$strip>;
1572
+ members: z.ZodArray<z.ZodObject<{
1573
+ elationId: z.ZodString;
1574
+ name: z.ZodString;
1575
+ lastName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
1576
+ firstName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
1577
+ doctor: z.ZodNullable<z.ZodString>;
1578
+ status: z.ZodEnum<{
1579
+ data: "data";
1580
+ activated: "activated";
1581
+ outreach: "outreach";
1582
+ scheduled: "scheduled";
1583
+ review: "review";
1584
+ }>;
1585
+ membershipStart: z.ZodString;
1586
+ daysSinceMembershipStart: z.ZodNumber;
1587
+ activationDate: z.ZodNullable<z.ZodString>;
1588
+ futureApptDate: z.ZodNullable<z.ZodString>;
1589
+ reason: z.ZodNullable<z.ZodString>;
1590
+ hasLink: z.ZodBoolean;
1591
+ }, z.core.$strip>>;
1592
+ }, z.core.$strip>>;
1593
+ }, z.core.$strip>>;
1594
+ pending: z.ZodBoolean;
1595
+ }, z.core.$strip>;
1596
+ type MemberActivationReport = z.infer<typeof reportSchema>;
1597
+ declare class ReportsError extends Error {
1598
+ readonly status: number;
1599
+ /**
1600
+ * Wraps a failed reports HTTP call with the operation name and status
1601
+ * code so callers can branch on `status` without re-parsing the message.
1602
+ * Falls back to a generated message when the server response body is
1603
+ * empty or unreadable.
1604
+ */
1605
+ constructor(operation: string, status: number, message?: string);
1606
+ }
1607
+ declare class ReportsResource {
1608
+ private readonly baseUrl;
1609
+ private readonly auth;
1610
+ /**
1611
+ * Captures the Truth API base URL and the auth inputs (API key + optional
1612
+ * user-token fetcher) needed to authenticate every request this resource
1613
+ * makes.
1614
+ */
1615
+ constructor(apiBaseUrl: string, apiKey: string, getAuthToken?: AuthTokenFetcher);
1616
+ /**
1617
+ * Fetches the member activation report from GET /reports/member-activation,
1618
+ * optionally scoped to a single employer. Requires the user JWT (not just
1619
+ * the API key) since the server hardens this route to
1620
+ * `verifiedUserProcedure` for PHI access — throws via `ReportsError` on a
1621
+ * non-OK response, including the response body (truncated) when present.
1622
+ */
1623
+ memberActivation(params?: {
1624
+ employerId?: string;
1625
+ }): Promise<MemberActivationReport>;
1626
+ }
1627
+
1126
1628
  type TaskStatus = "open" | "in_progress" | "resolved" | "cancelled";
1127
1629
  interface Task {
1128
1630
  _id: string;
@@ -1246,7 +1748,6 @@ declare class TranslationError extends Error {
1246
1748
  }
1247
1749
  declare class TranslationResource {
1248
1750
  private readonly baseUrl;
1249
- private readonly apiKey;
1250
1751
  private readonly auth;
1251
1752
  constructor(apiBaseUrl: string, apiKey: string, getAuthToken?: AuthTokenFetcher);
1252
1753
  private post;
@@ -1675,6 +2176,8 @@ declare class TruthClient {
1675
2176
  readonly patientDetails: PatientDetailsResource;
1676
2177
  /** Attachments — presigned S3 upload/download + Convex metadata */
1677
2178
  readonly attachments: AttachmentsResource;
2179
+ /** Reports — member activation report (Truth API) */
2180
+ readonly reports: ReportsResource;
1678
2181
  /** Notes — push formatted notes to Elation */
1679
2182
  readonly notes: NotesResource;
1680
2183
  /** Physicians (Convex-backed cache from Elation) */
@@ -1683,6 +2186,8 @@ declare class TruthClient {
1683
2186
  readonly notifications: NotificationsResource;
1684
2187
  /** Conversation-tied writes — notes, tasks, outbound messages. */
1685
2188
  readonly conversations: ConversationsResource;
2189
+ /** Care-team email inbox — link/unlink and (gated) send via oRPC. */
2190
+ readonly careInbox: CareInboxResource;
1686
2191
  /** User settings — notification preferences (Convex-backed) */
1687
2192
  readonly userSettings: UserSettingsResource;
1688
2193
  private readonly convex;
@@ -1691,8 +2196,18 @@ declare class TruthClient {
1691
2196
  private _vapidPublicKey;
1692
2197
  private _webPushReady;
1693
2198
  private readonly _serviceWorkerPath;
2199
+ /**
2200
+ * Builds the Convex client and event tracker from `config`, then wires up
2201
+ * every resource (patients, appointments, EHR proxy, reports, etc.) so
2202
+ * each shares the same Convex connection / API base URL / auth token
2203
+ * fetcher. When running in a browser that supports web push and the
2204
+ * caller hasn't opted out, kicks off best-effort service-worker
2205
+ * registration and push subscription in the background.
2206
+ */
1694
2207
  constructor(config: TruthClientConfig);
2208
+ /** The VAPID public key fetched during web-push init, or `null` until `webPushReady` resolves (or if push is unsupported/disabled). */
1695
2209
  get vapidPublicKey(): string | null;
2210
+ /** Resolves once background web-push initialization (service worker registration + subscription) finishes; `null` if it was never started (SSR, unsupported browser, or opted out via config). */
1696
2211
  get webPushReady(): Promise<void> | null;
1697
2212
  /**
1698
2213
  * When a Clerk token fetcher is configured (publishable-key clients),
@@ -1702,6 +2217,14 @@ declare class TruthClient {
1702
2217
  * → resolve immediately (secret-key path is unaffected).
1703
2218
  */
1704
2219
  private waitForAuthToken;
2220
+ /**
2221
+ * Best-effort web-push bootstrap: waits for auth (if configured), fetches
2222
+ * the VAPID key, registers the service worker, subscribes to push, and
2223
+ * registers the device with a placeholder `__pending__` userId (the
2224
+ * backend reconciles this once the real user is known). Any failure
2225
+ * along the way is swallowed — push notifications are opportunistic and
2226
+ * must never break client construction.
2227
+ */
1705
2228
  private initWebPush;
1706
2229
  /**
1707
2230
  * The resolved Truth API base URL for this environment.
@@ -1760,6 +2283,74 @@ declare class TruthClient {
1760
2283
  destroy(): Promise<void>;
1761
2284
  }
1762
2285
 
2286
+ /**
2287
+ * `createCareInboxSource` — a promise-based object with exactly the method
2288
+ * set of comhub's `CareInboxSource` (lib/email/careInboxSource.ts), so the
2289
+ * comhub adapter is a pass-through. Reads are one-shot Convex queries
2290
+ * (never persisted); link/unlink/send go through `CareInboxResource`.
2291
+ *
2292
+ * Every rejection is a `CareInboxError` (`Error & { code }` with the comhub
2293
+ * code set). `getThread` rejects `unavailable` when the feature flag is off
2294
+ * (the query returns null then). In React use `useCareInboxSource()` from
2295
+ * `@hipnation-truth/sdk/react`, which rebuilds the source when Convex auth
2296
+ * flips so comhub's query hooks refetch.
2297
+ */
2298
+
2299
+ declare const careInboxRefs: {
2300
+ listThreadsForUser: FunctionReference<"query", "public", {
2301
+ mailboxId?: string;
2302
+ filter?: ThreadListFilter;
2303
+ cursor?: string | null;
2304
+ limit?: number;
2305
+ }, EmailThreadPageView, string | undefined>;
2306
+ getThread: FunctionReference<"query", "public", {
2307
+ threadId: string;
2308
+ }, EmailThreadDetailView | null, string | undefined>;
2309
+ listUnlinked: FunctionReference<"query", "public", {
2310
+ mailboxId: string;
2311
+ cursor?: string | null;
2312
+ limit?: number;
2313
+ }, UnlinkedEmailPageView, string | undefined>;
2314
+ unreadEmailCount: FunctionReference<"query", "public", {
2315
+ mailboxId?: string;
2316
+ }, number, string | undefined>;
2317
+ listMailboxesForUser: FunctionReference<"query", "public", Record<string, never>, EmailMailboxAccessView, string | undefined>;
2318
+ searchPatientsForLink: FunctionReference<"query", "public", {
2319
+ q: string;
2320
+ }, PatientLinkCandidate[], string | undefined>;
2321
+ markRead: FunctionReference<"mutation", "public", {
2322
+ threadId: string;
2323
+ }, MarkEmailThreadReadResult, string | undefined>;
2324
+ openThreadBodies: FunctionReference<"mutation", "public", {
2325
+ threadId: string;
2326
+ }, EmailThreadBodiesView, string | undefined>;
2327
+ };
2328
+ /** The Convex surface the source needs (`ConvexReactClient` satisfies it). */
2329
+ interface CareInboxConvexClient {
2330
+ query(ref: FunctionReference<"query">, args: Record<string, unknown>): Promise<unknown>;
2331
+ mutation(ref: FunctionReference<"mutation">, args: Record<string, unknown>): Promise<unknown>;
2332
+ }
2333
+ interface CareInboxSourceDeps {
2334
+ convex: CareInboxConvexClient;
2335
+ careInbox: Pick<CareInboxResource, "linkMessage" | "unlinkMessage" | "replyToThread" | "composeEmail">;
2336
+ }
2337
+ /** Method set of comhub's `CareInboxSource` (minus optional `subscribe`). */
2338
+ interface CareInboxSdkSource {
2339
+ listThreads(args?: ListThreadsArgs): Promise<ThreadPage>;
2340
+ getUnreadCount(args?: {
2341
+ mailboxId?: string;
2342
+ }): Promise<number>;
2343
+ getThread(threadId: string): Promise<CareInboxThreadDetail>;
2344
+ listMailboxesForUser(): Promise<CareInboxMailboxAccess>;
2345
+ searchPatientsForLink(query: string): Promise<PatientLinkCandidate[]>;
2346
+ linkMessage(args: LinkMessageArgs): Promise<LinkResult>;
2347
+ unlinkMessage(args: UnlinkMessageArgs): Promise<LinkResult>;
2348
+ sendReply(args: SendReplyArgs): Promise<SendResult>;
2349
+ sendEmail(args: SendEmailArgs): Promise<SendResult>;
2350
+ markRead(args: MarkReadArgs): Promise<MarkReadResult>;
2351
+ }
2352
+ declare function createCareInboxSource({ convex, careInbox, }: CareInboxSourceDeps): CareInboxSdkSource;
2353
+
1763
2354
  /**
1764
2355
  * Event tracker with batching, retry, and flush support.
1765
2356
  *
@@ -1849,4 +2440,4 @@ declare function subscriptionToJSON(sub: PushSubscription): {
1849
2440
  };
1850
2441
  declare function onServiceWorkerMessage(type: string, callback: (payload: unknown) => void): () => void;
1851
2442
 
1852
- export { AUTH_EVENTS, type ActorContext, type Appointment, type AppointmentListOptions, AppointmentResource, type Attachment, AttachmentsError, AttachmentsResource, type AuthEventType, type AuthLoginFailedPayload, type AuthLoginSucceededPayload, type AuthTokenFetcher, CALL_EVENTS, CONVERSATION_EVENTS, type CallConnectedPayload, type CallEndedPayload, type CallEventType, type CallInitiatedPayload, type CallMissedPayload, type CallStatusResponse, type CancelScheduledNotificationResult, type ConversationAddress, type ConversationAttachmentDownloadedPayload, type ConversationAttachmentUploadedPayload, type ConversationCreatedPayload, type ConversationEventType, type ConversationMarkedReadPayload, type ConversationMessageReceivedPayload, type ConversationMessageSentPayload, type ConversationTaskPriority, type ConversationTaskStatus, ConversationsError, ConversationsResource, type CreateConversationNoteInput, type CreateConversationTaskInput, type CreateTaskInput, type CreateUploadUrlInput, type CreateUploadUrlResult, type DetectionResult, 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 GetDownloadUrlResult, type InitiateCallResponse, MessagesResource, NOTIFICATION_EVENTS, type NonVisitNoteBullet, NotesError, NotesResource, type NotificationDeliveredPayload, type NotificationEventType, type NotificationOpenedPayload, type NotificationPlatform, type NotificationPreferences, type NotificationSentPayload, NotificationsError, NotificationsResource, PROVIDER_EVENTS, type PaginatedResult, type Patient, type PatientBasicDetailsResult, PatientDetailsError, type PatientDetailsInput, PatientDetailsResource, type PatientDetailsResult, type PatientListOptions, type PatientMedicalDetailsResult, PatientResource, type Physician, PhysiciansResource, type ProviderEventType, type ProviderSyncFailedPayload, type ProviderSyncStartedPayload, type ProviderSyncSucceededPayload, type PushEventPayload, type PushNoteToElationInput, type PushNoteToElationResult, REMINDER_EVENTS, type RecordAttachmentInput, type RegisterDeviceInput, type RegisterDeviceResult, type Reminder, type ReminderEventType, type ReminderScheduledPayload, type ReminderStatus, type ReminderTriggeredPayload, RemindersResource, SECURITY_EVENTS, type ScheduleNotificationInput, type ScheduleNotificationResult, type ScheduleReminderInput, type ScheduleReminderResult, type ScheduledJobStatus, type ScheduledNotification, type SecurityAccessDeniedPayload, type SecurityEventType, type SendConversationMessageInput, type SendConversationMessageResult, type SendNotificationInput, type SendNotificationResult, type SendSmsParams, type SendSmsResponse, type SetConversationTaskStatusInput, TASK_EVENTS, TRANSLATION_EVENTS, type Task, type TaskAssignedPayload, type TaskCreatedPayload, type TaskEventType, type TaskStatus, type TaskStatusChangedPayload, TasksResource, type TrackOptions, Tracker, type TranslateBatchInput, type TranslateTextInput, type TranslationCompletedPayload, TranslationError, type TranslationEventType, type TranslationRequestedPayload, TranslationResource, type TranslationResult, TruthClient, type TruthClientConfig, type UnregisterDeviceInput, type UpdateNotificationsInput, type UpdateNotificationsResult, type UpdatePreferencesInput, type UpdateTaskStatusInput, type UserSettings, UserSettingsResource, type VoicemailAuthResponse, type WebPushConfig, generateUuidV7, isWebPushSupported, onServiceWorkerMessage, registerServiceWorker, subscribeToPush, subscriptionToJSON };
2443
+ export { AUTH_EVENTS, type ActorContext, type Appointment, type AppointmentListOptions, AppointmentResource, type Attachment, AttachmentsError, AttachmentsResource, type AuthEventType, type AuthLoginFailedPayload, type AuthLoginSucceededPayload, type AuthTokenFetcher, CALL_EVENTS, CONVERSATION_EVENTS, type CallConnectedPayload, type CallEndedPayload, type CallEventType, type CallInitiatedPayload, type CallMissedPayload, type CallStatusResponse, type CancelScheduledNotificationResult, type CareInboxConvexClient, type CareInboxEmailMessage, type CareInboxEmailThreadSummary, CareInboxError, type CareInboxErrorCode, type CareInboxErrorFields, type CareInboxErrorInfo, type CareInboxErrorReason, type CareInboxLinkResult, type CareInboxMailbox, type CareInboxMailboxAccess, CareInboxResource, type CareInboxSdkSource, type CareInboxSendResult, type CareInboxSourceDeps, type CareInboxThreadDetail, type ComposeEmailInput, type ConversationAddress, type ConversationAttachmentDownloadedPayload, type ConversationAttachmentUploadedPayload, type ConversationCreatedPayload, type ConversationEventType, type ConversationMarkedReadPayload, type ConversationMessageReceivedPayload, type ConversationMessageSentPayload, type ConversationTaskPriority, type ConversationTaskStatus, ConversationsError, ConversationsResource, type CreateConversationNoteInput, type CreateConversationTaskInput, type CreateTaskInput, type CreateUploadUrlInput, type CreateUploadUrlResult, type DetectionResult, type DialpadNumberInfo, DialpadProxyError, DialpadResource, type DialpadUser, ENVIRONMENTS, EVENT_TYPES, EhrProviderProxy, EhrProxyError, EhrResource, type EmailDirection, type EmailMailbox, type EmailMailboxAccessView, type EmailMailboxView, type EmailMessage, type EmailMessageView, type EmailParticipant, type EmailParticipantView, type EmailThreadBodiesView, type EmailThreadDetail, type EmailThreadDetailView, type EmailThreadListFilter, type EmailThreadPageView, type EmailThreadSummary, type EmailThreadSummaryView, type Environment, type EventActor, type EventCompliance, type EventEnvelope, type EventPayloadMap, type EventSubject, type EventType, type GetDownloadUrlResult, type InitiateCallResponse, type LinkEmailMessageInput, type LinkMessageArgs, type LinkResult, type LinkedPatientContact, type ListThreadsArgs, type MailboxAccess, type MarkEmailThreadReadResult, type MarkReadArgs, type MarkReadResult, type MemberActivationReport, MessagesResource, NOTIFICATION_EVENTS, type NonVisitNoteBullet, NotesError, NotesResource, type NotificationDeliveredPayload, type NotificationEventType, type NotificationOpenedPayload, type NotificationPlatform, type NotificationPreferences, type NotificationSentPayload, NotificationsError, NotificationsResource, PROVIDER_EVENTS, type PaginatedResult, type Patient, type PatientBasicDetailsResult, PatientDetailsError, type PatientDetailsInput, PatientDetailsResource, type PatientDetailsResult, type PatientLinkCandidate, type PatientLinkCandidateView, type PatientListOptions, type PatientMedicalDetailsResult, PatientResource, type Physician, PhysiciansResource, type ProviderEventType, type ProviderSyncFailedPayload, type ProviderSyncStartedPayload, type ProviderSyncSucceededPayload, type PushEventPayload, type PushNoteToElationInput, type PushNoteToElationResult, REMINDER_EVENTS, type RecordAttachmentInput, type RegisterDeviceInput, type RegisterDeviceResult, type Reminder, type ReminderEventType, type ReminderScheduledPayload, type ReminderStatus, type ReminderTriggeredPayload, RemindersResource, type ReplyToEmailThreadInput, ReportsError, ReportsResource, SECURITY_EVENTS, type ScheduleNotificationInput, type ScheduleNotificationResult, type ScheduleReminderInput, type ScheduleReminderResult, type ScheduledJobStatus, type ScheduledNotification, type SecurityAccessDeniedPayload, type SecurityEventType, type SendConversationMessageInput, type SendConversationMessageResult, type SendEmailArgs, type SendNotificationInput, type SendNotificationResult, type SendReplyArgs, type SendResult, type SendSmsParams, type SendSmsResponse, type SetConversationTaskStatusInput, TASK_EVENTS, TRANSLATION_EVENTS, type Task, type TaskAssignedPayload, type TaskCreatedPayload, type TaskEventType, type TaskStatus, type TaskStatusChangedPayload, TasksResource, type ThreadListFilter, type ThreadPage, type TrackOptions, Tracker, type TranslateBatchInput, type TranslateTextInput, type TranslationCompletedPayload, TranslationError, type TranslationEventType, type TranslationRequestedPayload, TranslationResource, type TranslationResult, TruthClient, type TruthClientConfig, type UnlinkEmailMessageInput, type UnlinkMessageArgs, type UnlinkedEmailPageView, type UnlinkedMessagePage, type UnregisterDeviceInput, type UpdateNotificationsInput, type UpdateNotificationsResult, type UpdatePreferencesInput, type UpdateTaskStatusInput, type UserSettings, UserSettingsResource, type VoicemailAuthResponse, type WebPushConfig, careInboxErrorInfo, careInboxRefs, createCareInboxSource, generateUuidV7, isCareInboxError, isWebPushSupported, onServiceWorkerMessage, registerServiceWorker, subscribeToPush, subscriptionToJSON, toCareInboxError, toEmailMailbox, toEmailMessage, toEmailThreadDetail, toEmailThreadSummary, toMailboxAccess, toMarkReadResult, toThreadPage, toUnlinkedMessagePage };