@healthcloudai/hc-sdk 0.4.0 → 0.6.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/README.md +225 -2
- package/dist/index.cjs +2913 -4
- package/dist/index.d.cts +5610 -2
- package/dist/index.d.ts +5610 -2
- package/dist/index.js +2879 -4
- package/package.json +6 -2
package/README.md
CHANGED
|
@@ -89,7 +89,7 @@ const patient = await sdk.patient.getProfile("patient-id");
|
|
|
89
89
|
```ts
|
|
90
90
|
const sdk = new HCSDK({
|
|
91
91
|
environment: "dev", // required
|
|
92
|
-
tenantId: "eclinicapi", // optional — injected
|
|
92
|
+
tenantId: "eclinicapi", // optional — injected into /auth/* request bodies only; never sent as a header
|
|
93
93
|
accessToken: "existing-token", // optional — skip login if you already have a token
|
|
94
94
|
});
|
|
95
95
|
```
|
|
@@ -143,6 +143,229 @@ All groups share one HTTP client, one token store, one error handler, the same U
|
|
|
143
143
|
|
|
144
144
|
---
|
|
145
145
|
|
|
146
|
+
## Vendor connectors (`sdk.vendors`)
|
|
147
|
+
|
|
148
|
+
The `sdk.vendors` namespace routes requests through the HealthCloud Connectors gateway at `*-api-connectors.health.cloud`. All 29 vendor clients share the same bearer token, error model, and URL resolution as the rest of the SDK. Every request body accepts an optional `mode` field (`"sandbox" | "live"`); the gateway defaults to `"sandbox"` when omitted.
|
|
149
|
+
|
|
150
|
+
### SDK creation with connectors
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
import { HCSDK, SDKError } from "@healthcloudai/hc-sdk";
|
|
154
|
+
|
|
155
|
+
// Create the SDK — a Cognito access token is required for all vendor calls.
|
|
156
|
+
const sdk = new HCSDK({
|
|
157
|
+
environment: "prod", // "dev" | "uat" | "prod"
|
|
158
|
+
accessToken: "eyJhbGci...", // Cognito bearer token
|
|
159
|
+
});
|
|
160
|
+
|
|
161
|
+
// The resolved base URL for the connectors service:
|
|
162
|
+
// dev → https://dev-api-connectors.health.cloud
|
|
163
|
+
// uat → https://uat-api-connectors.health.cloud
|
|
164
|
+
// prod → https://api-connectors.health.cloud
|
|
165
|
+
|
|
166
|
+
// Vendor credentials are connector-constructor fields in the request body.
|
|
167
|
+
// Keep them outside source control and spread them into each relevant call.
|
|
168
|
+
const whoopCredentials = { client_id: process.env.WHOOP_CLIENT_ID!, client_secret: process.env.WHOOP_CLIENT_SECRET! };
|
|
169
|
+
const ouraCredentials = { client_id: process.env.OURA_CLIENT_ID!, client_secret: process.env.OURA_CLIENT_SECRET! };
|
|
170
|
+
const athenaCredentials = { secret_key: process.env.ATHENA_SECRET_KEY!, practice_id: process.env.ATHENA_PRACTICE_ID! };
|
|
171
|
+
const stripeCredentials = { secret_key: process.env.STRIPE_SECRET_KEY! };
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### WHOOP — wearable health data
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
// OAuth flow
|
|
178
|
+
const url = await sdk.vendors.whoop.buildAuthorizationUrl({
|
|
179
|
+
redirect_uri: "https://myapp.com/callback",
|
|
180
|
+
scopes: ["read:profile", "read:cycles"],
|
|
181
|
+
mode: "sandbox",
|
|
182
|
+
...whoopCredentials,
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
// Exchange the code received in the callback
|
|
186
|
+
const tokens = await sdk.vendors.whoop.exchangeAuthorizationCode({
|
|
187
|
+
code: "auth-code-from-redirect",
|
|
188
|
+
redirect_uri: "https://myapp.com/callback",
|
|
189
|
+
mode: "sandbox",
|
|
190
|
+
...whoopCredentials,
|
|
191
|
+
});
|
|
192
|
+
|
|
193
|
+
// Retrieve a user's recent cycles (uses the user's access_token, not the SDK token)
|
|
194
|
+
const cycles = await sdk.vendors.whoop.getCycles({
|
|
195
|
+
access_token: "whoop-user-access-token",
|
|
196
|
+
start: "2025-01-01T00:00:00Z",
|
|
197
|
+
end: "2025-01-31T23:59:59Z",
|
|
198
|
+
mode: "sandbox",
|
|
199
|
+
...whoopCredentials,
|
|
200
|
+
});
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Oura Ring — wearable health data
|
|
204
|
+
|
|
205
|
+
```ts
|
|
206
|
+
// Build the Oura authorization URL
|
|
207
|
+
const url = await sdk.vendors.oura.buildAuthorizationUrl({
|
|
208
|
+
redirect_uri: "https://myapp.com/oura-callback",
|
|
209
|
+
scopes: ["daily", "personal"],
|
|
210
|
+
mode: "sandbox",
|
|
211
|
+
...ouraCredentials,
|
|
212
|
+
});
|
|
213
|
+
|
|
214
|
+
// Exchange code for tokens
|
|
215
|
+
const tokens = await sdk.vendors.oura.exchangeAuthorizationCode({
|
|
216
|
+
code: "oura-auth-code",
|
|
217
|
+
redirect_uri: "https://myapp.com/oura-callback",
|
|
218
|
+
mode: "sandbox",
|
|
219
|
+
...ouraCredentials,
|
|
220
|
+
});
|
|
221
|
+
|
|
222
|
+
// Fetch daily sleep data for a date range
|
|
223
|
+
const sleeps = await sdk.vendors.oura.getDailySleeps({
|
|
224
|
+
start_date: "2025-01-01",
|
|
225
|
+
end_date: "2025-01-07",
|
|
226
|
+
access_token: tokens.access_token,
|
|
227
|
+
mode: "sandbox",
|
|
228
|
+
...ouraCredentials,
|
|
229
|
+
});
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### Sandbox vs live mode
|
|
233
|
+
|
|
234
|
+
```ts
|
|
235
|
+
// Sandbox (default — omitting mode is equivalent to mode: "sandbox")
|
|
236
|
+
const sandboxResult = await sdk.vendors.stripe.createPaymentIntent({
|
|
237
|
+
amount: 5000,
|
|
238
|
+
currency: "usd",
|
|
239
|
+
...stripeCredentials,
|
|
240
|
+
});
|
|
241
|
+
|
|
242
|
+
// Live
|
|
243
|
+
const liveResult = await sdk.vendors.stripe.createPaymentIntent({
|
|
244
|
+
amount: 5000,
|
|
245
|
+
currency: "usd",
|
|
246
|
+
mode: "live",
|
|
247
|
+
...stripeCredentials,
|
|
248
|
+
});
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Athena Health EHR
|
|
252
|
+
|
|
253
|
+
```ts
|
|
254
|
+
// Search patients
|
|
255
|
+
const patients = await sdk.vendors.athena.searchPatients({
|
|
256
|
+
last_name: "Smith",
|
|
257
|
+
first_name: "Jane",
|
|
258
|
+
mode: "sandbox",
|
|
259
|
+
...athenaCredentials,
|
|
260
|
+
});
|
|
261
|
+
|
|
262
|
+
// Book an appointment into an existing open slot
|
|
263
|
+
const booking = await sdk.vendors.athena.bookAppointment({
|
|
264
|
+
appointment_id: "12345",
|
|
265
|
+
patient_id: "67890",
|
|
266
|
+
mode: "sandbox",
|
|
267
|
+
...athenaCredentials,
|
|
268
|
+
});
|
|
269
|
+
|
|
270
|
+
// Insurance packages
|
|
271
|
+
const packages = await sdk.vendors.athena.getInsurancePackages({
|
|
272
|
+
patient_id: "67890",
|
|
273
|
+
mode: "sandbox",
|
|
274
|
+
...athenaCredentials,
|
|
275
|
+
});
|
|
276
|
+
|
|
277
|
+
// Check a patient in
|
|
278
|
+
await sdk.vendors.athena.checkInPatient({
|
|
279
|
+
appointment_id: "12345",
|
|
280
|
+
mode: "sandbox",
|
|
281
|
+
...athenaCredentials,
|
|
282
|
+
});
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### Stripe payments
|
|
286
|
+
|
|
287
|
+
```ts
|
|
288
|
+
// Create a PaymentIntent
|
|
289
|
+
const intent = await sdk.vendors.stripe.createPaymentIntent({
|
|
290
|
+
amount: 5000,
|
|
291
|
+
currency: "usd",
|
|
292
|
+
mode: "sandbox",
|
|
293
|
+
...stripeCredentials,
|
|
294
|
+
});
|
|
295
|
+
// Use intent.client_secret for client-side confirmation
|
|
296
|
+
|
|
297
|
+
// Create a customer
|
|
298
|
+
const customer = await sdk.vendors.stripe.createCustomer({
|
|
299
|
+
email: "patient@example.com",
|
|
300
|
+
mode: "sandbox",
|
|
301
|
+
...stripeCredentials,
|
|
302
|
+
});
|
|
303
|
+
|
|
304
|
+
// List products
|
|
305
|
+
const products = await sdk.vendors.stripe.listProducts({ mode: "sandbox", ...stripeCredentials });
|
|
306
|
+
|
|
307
|
+
// Verify credentials
|
|
308
|
+
const status = await sdk.vendors.stripe.verifyConnection({ mode: "sandbox", ...stripeCredentials });
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### Error handling for vendor calls
|
|
312
|
+
|
|
313
|
+
```ts
|
|
314
|
+
import { SDKError } from "@healthcloudai/hc-sdk";
|
|
315
|
+
|
|
316
|
+
try {
|
|
317
|
+
const result = await sdk.vendors.stripe.createPaymentIntent({
|
|
318
|
+
amount: 5000,
|
|
319
|
+
currency: "usd",
|
|
320
|
+
mode: "sandbox",
|
|
321
|
+
...stripeCredentials,
|
|
322
|
+
});
|
|
323
|
+
} catch (error) {
|
|
324
|
+
if (error instanceof SDKError) {
|
|
325
|
+
console.log(error.statusCode); // 400 | 401 | 404 | 502 | 504 | 0 (network)
|
|
326
|
+
console.log(error.message); // parsed {"error": "..."} or HTTP status text
|
|
327
|
+
console.log(error.response); // full parsed response body, or undefined
|
|
328
|
+
console.log(error.cause); // underlying Error for network failures
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
### Available vendor clients
|
|
334
|
+
|
|
335
|
+
| Client | `sdk.vendors.<key>` | Gateway prefix |
|
|
336
|
+
|---|---|---|
|
|
337
|
+
| Athena Health EHR | `athena` | `/connectors/athena-health/` |
|
|
338
|
+
| Stripe | `stripe` | `/connectors/stripe/` |
|
|
339
|
+
| Twilio | `twilio` | `/connectors/twilio/` |
|
|
340
|
+
| Stedi (X12) | `stedi` | `/connectors/stedi/` |
|
|
341
|
+
| Salesforce | `salesforce` | `/connectors/salesforce/` |
|
|
342
|
+
| Quest Diagnostics | `quest` | `/connectors/quest/` |
|
|
343
|
+
| OpenAI | `openai` | `/connectors/openai/` |
|
|
344
|
+
| Anthropic | `anthropic` | `/connectors/anthropic/` |
|
|
345
|
+
| Google AI (Gemini) | `googleAI` | `/connectors/google-ai/` |
|
|
346
|
+
| Google Places | `googlePlaces` | `/connectors/google-places/` |
|
|
347
|
+
| SendGrid | `sendgrid` | `/connectors/sendgrid/` |
|
|
348
|
+
| ElevenLabs | `elevenlabs` | `/connectors/elevenlabs/` |
|
|
349
|
+
| NPPES | `nppes` | `/connectors/nppes/` |
|
|
350
|
+
| CMS Marketplace | `cms` | `/connectors/cms/` |
|
|
351
|
+
| FedEx | `fedex` | `/connectors/fedex/` |
|
|
352
|
+
| Connecture | `connecture` | `/connectors/connecture/` |
|
|
353
|
+
| SENAITE LIMS | `senaite` | `/connectors/senaite/` |
|
|
354
|
+
| Healthie | `healthie` | `/connectors/healthie/` |
|
|
355
|
+
| Grok (xAI) | `grok` | `/connectors/grok/` |
|
|
356
|
+
| Cal.com | `cal` | `/connectors/cal/` |
|
|
357
|
+
| CareQuality | `carequality` | `/connectors/carequality/` |
|
|
358
|
+
| Oura Ring | `oura` | `/connectors/oura/` |
|
|
359
|
+
| Plaid | `plaid` | `/connectors/plaid/identity-verification/` |
|
|
360
|
+
| Apple Auth | `appleAuth` | `/connectors/apple-auth/` |
|
|
361
|
+
| Zocdoc | `zocdoc` | `/connectors/zocdoc/` |
|
|
362
|
+
| WHOOP | `whoop` | `/connectors/whoop/` |
|
|
363
|
+
| Junction | `junction` | `/connectors/junction/` |
|
|
364
|
+
| SteadyMD | `steadymd` | `/connectors/steadymd/` |
|
|
365
|
+
| Impilo RPM | `impilo` | `/connectors/impilo/` |
|
|
366
|
+
|
|
367
|
+
---
|
|
368
|
+
|
|
146
369
|
## Auth
|
|
147
370
|
|
|
148
371
|
```ts
|
|
@@ -150,7 +373,7 @@ All groups share one HTTP client, one token store, one error handler, the same U
|
|
|
150
373
|
await sdk.auth.register({
|
|
151
374
|
email: "patient@example.com",
|
|
152
375
|
password: "SecurePassword123!",
|
|
153
|
-
tenant_id
|
|
376
|
+
// no tenant_id here — the SDK injects it from the `tenantId` passed to the HCSDK constructor
|
|
154
377
|
first_name: "Jane",
|
|
155
378
|
last_name: "Doe",
|
|
156
379
|
date_of_birth: "1990-06-15",
|