@healthcloudai/hc-sdk 0.11.0 → 2.0.1

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/README.md CHANGED
@@ -78,8 +78,10 @@ await sdk.auth.login({
78
78
  ```
79
79
 
80
80
  ```ts
81
- // 4. All subsequent calls use the token automatically
82
- const patient = await sdk.patient.getProfile("patient-id");
81
+ // 4. All subsequent calls use the token automatically. getProfile() is
82
+ // self-service — it always returns the authenticated patient, resolved
83
+ // server-side from the token, so no id is passed here.
84
+ const patient = await sdk.patient.getProfile();
83
85
  ```
84
86
 
85
87
  ---
@@ -599,10 +601,19 @@ const authResponse = await sdk.auth.login({
599
601
 
600
602
  ## Patient
601
603
 
604
+ All methods below are **self-service**: the authenticated patient is
605
+ resolved server-side from the caller's PATIENT-pool Bearer token, so none of
606
+ them take a patient id argument — the SDK never lets a client supply one.
607
+ (`sdk.diagnostics`, documented separately, is different: every method there
608
+ still takes an explicit `patientId` since providers and field agents
609
+ legitimately act on patients other than themselves; when the caller holds a
610
+ PATIENT-pool token, the backend now enforces server-side that `patientId`
611
+ must be their own, 403 otherwise.)
612
+
602
613
  ### Profile, phone, address, race, demographics
603
614
 
604
615
  ```ts
605
- const profile = await sdk.patient.getProfile("patient-id");
616
+ const profile = await sdk.patient.getProfile();
606
617
  ```
607
618
 
608
619
  ```json
@@ -625,7 +636,7 @@ const profile = await sdk.patient.getProfile("patient-id");
625
636
 
626
637
  ```ts
627
638
  // Dashboard snapshot
628
- const dashboard = await sdk.patient.getDashboard("patient-id");
639
+ const dashboard = await sdk.patient.getDashboard();
629
640
  ```
630
641
 
631
642
  ```json
@@ -642,7 +653,7 @@ const dashboard = await sdk.patient.getDashboard("patient-id");
642
653
 
643
654
  ```ts
644
655
  // Update phone (triggers SMS OTP)
645
- await sdk.patient.updatePhone("patient-id", { phone: "+15550001234" });
656
+ await sdk.patient.updatePhone({ phone: "+15550001234" });
646
657
  ```
647
658
 
648
659
  ```json
@@ -651,7 +662,7 @@ await sdk.patient.updatePhone("patient-id", { phone: "+15550001234" });
651
662
 
652
663
  ```ts
653
664
  // Verify SMS OTP
654
- await sdk.patient.verifySms("patient-id", { otp: "654321" });
665
+ await sdk.patient.verifySms({ otp: "654321" });
655
666
  ```
656
667
 
657
668
  ```json
@@ -660,7 +671,7 @@ await sdk.patient.verifySms("patient-id", { otp: "654321" });
660
671
 
661
672
  ```ts
662
673
  // Update address
663
- await sdk.patient.updateAddress("patient-id", {
674
+ await sdk.patient.updateAddress({
664
675
  street: "123 Main St",
665
676
  city: "San Francisco",
666
677
  state: "CA",
@@ -674,7 +685,7 @@ await sdk.patient.updateAddress("patient-id", {
674
685
 
675
686
  ```ts
676
687
  // Update race
677
- await sdk.patient.updateRace("patient-id", { races: ["white"] });
688
+ await sdk.patient.updateRace({ races: ["white"] });
678
689
  ```
679
690
 
680
691
  ```json
@@ -682,8 +693,8 @@ await sdk.patient.updateRace("patient-id", { races: ["white"] });
682
693
  ```
683
694
 
684
695
  ```ts
685
- // Get a patient's boolean feature/state flags — {} if none are set
686
- const flags = await sdk.patient.getFlags("patient-id");
696
+ // Get the authenticated patient's boolean feature/state flags — {} if none are set
697
+ const flags = await sdk.patient.getFlags();
687
698
  ```
688
699
 
689
700
  ```json
@@ -694,7 +705,7 @@ const flags = await sdk.patient.getFlags("patient-id");
694
705
  // Update flags — a partial merge, not a replace: only the flags named here
695
706
  // change, every other existing flag is left unchanged. Idempotent. Returns
696
707
  // the complete flags dictionary after the merge.
697
- await sdk.patient.updateFlags("patient-id", { onboarding_completed: true });
708
+ await sdk.patient.updateFlags({ onboarding_completed: true });
698
709
  ```
699
710
 
700
711
  ```json
@@ -703,7 +714,7 @@ await sdk.patient.updateFlags("patient-id", { onboarding_completed: true });
703
714
 
704
715
  ```ts
705
716
  // Update demographics — partial update, all fields optional
706
- await sdk.patient.updateDemographics("patient-id", {
717
+ await sdk.patient.updateDemographics({
707
718
  date_of_birth: "1990-06-15",
708
719
  sex_at_birth: "female", // 'male' | 'female' | 'intersex' | 'unknown'
709
720
  gender_identity: "woman",
@@ -722,7 +733,7 @@ await sdk.patient.updateDemographics("patient-id", {
722
733
  ### Photo, face match, ID document OCR
723
734
 
724
735
  ```ts
725
- const uploadUrl = await sdk.patient.getPhotoUploadUrl("patient-id");
736
+ const uploadUrl = await sdk.patient.getPhotoUploadUrl();
726
737
  ```
727
738
 
728
739
  ```json
@@ -730,7 +741,7 @@ const uploadUrl = await sdk.patient.getPhotoUploadUrl("patient-id");
730
741
  ```
731
742
 
732
743
  ```ts
733
- await sdk.patient.uploadPhoto("patient-id", {
744
+ await sdk.patient.uploadPhoto({
734
745
  data: "base64-image-data",
735
746
  content_type: "image/jpeg",
736
747
  });
@@ -741,10 +752,10 @@ await sdk.patient.uploadPhoto("patient-id", {
741
752
  ```
742
753
 
743
754
  ```ts
744
- const photo = await sdk.patient.getPhoto("patient-id", { binary_id: "binary-id" });
755
+ const photo = await sdk.patient.getPhoto({ binary_id: "binary-id" });
745
756
 
746
757
  // Face match (Rekognition CompareFaces against a stored FHIR Binary)
747
- await sdk.patient.compareFaceMatch("patient-id", {
758
+ await sdk.patient.compareFaceMatch({
748
759
  selfie_data: "base64-selfie-data",
749
760
  reference_binary_id: "binary-id",
750
761
  similarity_threshold: 80.0, // optional, defaults to 80.0
@@ -762,7 +773,7 @@ await sdk.patient.compareFaceMatch("patient-id", {
762
773
 
763
774
  ```ts
764
775
  // OCR identity document (Textract AnalyzeID)
765
- await sdk.patient.scanIdentityDocument("patient-id", {
776
+ await sdk.patient.scanIdentityDocument({
766
777
  document_data: "base64-document-data",
767
778
  verify_against_demographics: true, // compares extracted name+DOB to the patient's FHIR record
768
779
  });
@@ -781,7 +792,7 @@ await sdk.patient.scanIdentityDocument("patient-id", {
781
792
  ### Insurance
782
793
 
783
794
  ```ts
784
- await sdk.patient.createInsurance("patient-id", {
795
+ await sdk.patient.createInsurance({
785
796
  priority: "primary", // 'primary' | 'secondary' | 'tertiary'
786
797
  payer_name: "Blue Cross Blue Shield",
787
798
  member_id: "M001",
@@ -810,7 +821,7 @@ response, so it's typed as `InsuranceEligibilityResponse` (`JsonValue`).
810
821
 
811
822
  ```ts
812
823
  // List the patient's stored insurances
813
- const insurances = await sdk.patient.listPatientInsurances("patient-id");
824
+ const insurances = await sdk.patient.listPatientInsurances();
814
825
  ```
815
826
 
816
827
  ### Records, import, pharmacy, dependents, notifications
@@ -821,11 +832,11 @@ stabilized, so responses are not yet generated models. The methods are:
821
832
 
822
833
  | Area | Methods | Routes |
823
834
  |---|---|---|
824
- | Health-record / CCDA import | `importHealthRecord`, `importCCDA` | `POST /patients/{id}/health-record/import` |
825
- | Vitals / activity import | `importVitals`, `importActivity`, `listActivity`, `deleteActivity` | `/patients/{id}/vitals/import`, `/patients/{id}/activity*` |
826
- | Preferred pharmacy | `getPreferredPharmacy`, `setPreferredPharmacy` | `GET|PUT /patients/{id}/preferred-pharmacy` |
827
- | Dependents | `listDependents`, `saveDependent`, `deleteDependent` | `/patients/{id}/dependents*` |
828
- | Notifications | `listNotifications`, `saveNotification`, `deleteNotification` | `/patients/{id}/notifications*` |
835
+ | Health-record / CCDA import | `importHealthRecord`, `importCCDA` | `POST /patients/health-record/import` |
836
+ | Vitals / activity import | `importVitals`, `importActivity`, `listActivity`, `deleteActivity` | `/patients/vitals/import`, `/patients/activity*` |
837
+ | Preferred pharmacy | `getPreferredPharmacy`, `setPreferredPharmacy` | `GET|PUT /patients/preferred-pharmacy` |
838
+ | Dependents | `listDependents`, `saveDependent`, `deleteDependent` | `/patients/dependents*` |
839
+ | Notifications | `listNotifications`, `saveNotification`, `deleteNotification` | `/patients/notifications*` |
829
840
  | Agent configuration | `getAgentConfiguration`, `getAgent` | `GET /agentconfiguration`, `GET /agent` |
830
841
  | Care session / check-in / sidebar | `getCheckin`, `getCurrentCareSession`, `getPatientSidebar` | `GET /checkin`, `GET /care-sessions/current`, `GET /patient/sidebar` |
831
842
  | Current screening symptoms | `createCurrentScreeningSymptoms` | `POST /screenings/current/symptoms` |
@@ -847,7 +858,7 @@ every_8_hours, every_12_hours, every_48_hours, weekly, biweekly, monthly,
847
858
  as_needed, other`.
848
859
 
849
860
  ```ts
850
- await sdk.patient.createMedication("patient-id", {
861
+ await sdk.patient.createMedication({
851
862
  name: "Amoxicillin",
852
863
  route: "oral",
853
864
  dosage: { value: 500, unit: "mg", frequency: "twice_daily" },
@@ -869,7 +880,7 @@ await sdk.patient.createMedication("patient-id", {
869
880
  ```
870
881
 
871
882
  ```ts
872
- const meds = await sdk.patient.listMedications("patient-id");
883
+ const meds = await sdk.patient.listMedications();
873
884
  // optional: { resource_type: "MedicationRequest" | "MedicationStatement" }
874
885
  ```
875
886
 
@@ -878,10 +889,10 @@ const meds = await sdk.patient.listMedications("patient-id");
878
889
  ```
879
890
 
880
891
  ```ts
881
- const med = await sdk.patient.getMedication("patient-id", "med-id");
892
+ const med = await sdk.patient.getMedication("med-id");
882
893
  // → a single MedicationResponse
883
894
 
884
- await sdk.patient.updateMedicationStatus("patient-id", "med-id", {
895
+ await sdk.patient.updateMedicationStatus("med-id", {
885
896
  status: "completed",
886
897
  notes: "course finished",
887
898
  });
@@ -1389,6 +1400,15 @@ const vitals = await sdk.vitals.list("patient-id");
1389
1400
 
1390
1401
  ## Diagnostics
1391
1402
 
1403
+ Every method takes an explicit `patientId` — unlike `sdk.patient`, this
1404
+ group is not self-service, since providers and field agents legitimately
1405
+ look up or record diagnostics for a patient other than themselves (e.g.
1406
+ `createRapidTest`, used to record a test performed for a patient). When the
1407
+ caller holds a PATIENT-pool token, the backend enforces server-side that
1408
+ `patientId` must be their own FHIR id — passing another patient's id returns
1409
+ `403`, so patient A can never read or write patient B's diagnostics.
1410
+ Provider/field-agent callers are unrestricted.
1411
+
1392
1412
  ```ts
1393
1413
  // Create rapid test result
1394
1414
  await sdk.diagnostics.createRapidTest("patient-id", {
@@ -1541,11 +1561,13 @@ const handshake = await sdk.mcp.patient<Record<string, never>, McpInitializeResu
1541
1561
  ```
1542
1562
 
1543
1563
  ```ts
1564
+ // get_patient is self-service — no patient_id argument; the patient is
1565
+ // resolved server-side from whichever Bearer token this SDK instance holds.
1544
1566
  const result = await sdk.mcp.patient<{ name: string; arguments: Record<string, unknown> }, McpToolCallResult>({
1545
1567
  jsonrpc: "2.0",
1546
1568
  id: 3,
1547
1569
  method: "tools/call",
1548
- params: { name: "get_patient", arguments: { patient_id: fhirPatientId } },
1570
+ params: { name: "get_patient", arguments: {} },
1549
1571
  });
1550
1572
  ```
1551
1573
 
@@ -1625,7 +1647,7 @@ All non-2xx responses and network failures are normalized into `SDKError`:
1625
1647
  import { SDKError } from "@healthcloudai/hc-sdk";
1626
1648
 
1627
1649
  try {
1628
- await sdk.patient.getProfile("patient-id");
1650
+ await sdk.patient.getProfile();
1629
1651
  } catch (error) {
1630
1652
  if (error instanceof SDKError) {
1631
1653
  console.log(error.statusCode); // HTTP status; 0 for network errors
@@ -1657,25 +1679,27 @@ import { HCSDK, SDKError, type PatientResponse } from "@healthcloudai/hc-sdk";
1657
1679
 
1658
1680
  const sdk = new HCSDK({ environment: "dev", tenantId: "eclinicapi" });
1659
1681
 
1660
- export function usePatientProfile(patientId: string) {
1682
+ export function useOwnPatientProfile() {
1661
1683
  const [data, setData] = useState<PatientResponse | null>(null);
1662
1684
  const [loading, setLoading] = useState(true);
1663
1685
  const [error, setError] = useState<SDKError | null>(null);
1664
1686
 
1665
1687
  useEffect(() => {
1666
- sdk.patient.getProfile(patientId)
1688
+ // Self-service: getProfile() always resolves the currently authenticated
1689
+ // patient (from the SDK's Bearer token) — there is no patient id to pass.
1690
+ sdk.patient.getProfile()
1667
1691
  .then(setData)
1668
1692
  .catch((err: unknown) => {
1669
1693
  if (err instanceof SDKError) setError(err);
1670
1694
  })
1671
1695
  .finally(() => setLoading(false));
1672
- }, [patientId]);
1696
+ }, []);
1673
1697
 
1674
1698
  return { data, loading, error };
1675
1699
  }
1676
1700
 
1677
- export function PatientProfile({ patientId }: { patientId: string }) {
1678
- const { data, loading, error } = usePatientProfile(patientId);
1701
+ export function PatientProfile() {
1702
+ const { data, loading, error } = useOwnPatientProfile();
1679
1703
  if (loading) return <ActivityIndicator />;
1680
1704
  if (error) return <Text>Error {error.statusCode}: {error.message}</Text>;
1681
1705
  return <View><Text>{JSON.stringify(data)}</Text></View>;