@healthcloudai/hc-sdk 0.5.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 CHANGED
@@ -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