@healthcloudai/hc-sdk 0.6.0 → 0.7.2

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.
Files changed (6) hide show
  1. package/README.md +121 -159
  2. package/dist/index.cjs +1813 -1487
  3. package/dist/index.d.cts +8181 -1907
  4. package/dist/index.d.ts +8181 -1907
  5. package/dist/index.js +1809 -1485
  6. package/package.json +8 -5
package/README.md CHANGED
@@ -143,226 +143,188 @@ 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`)
146
+ ## Connectors (`sdk.connectors`)
147
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.
148
+ Connector clients are created in three explicit steps:
149
149
 
150
- ### SDK creation with connectors
150
+ 1. Configure HealthCloud once through `HCSDK`.
151
+ 2. Create an isolated connector client with that connector's credentials.
152
+ 3. Call operation methods with operation-specific parameters only.
151
153
 
152
154
  ```ts
153
- import { HCSDK, SDKError } from "@healthcloudai/hc-sdk";
155
+ import { HCSDK } from "@healthcloudai/hc-sdk";
154
156
 
155
- // Create the SDK — a Cognito access token is required for all vendor calls.
156
157
  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,
158
+ environment: "prod", // "dev" | "uat" | "prod"
159
+ tenantId: "<TENANT_ID>",
160
+ accessToken: "<HEALTHCLOUD_ACCESS_TOKEN>",
183
161
  });
184
162
 
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,
163
+ const cal = sdk.connectors.cal.createClient({
164
+ api_key: process.env.CAL_API_KEY!,
191
165
  });
192
166
 
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,
167
+ const bookings = await cal.getAllBookings({
168
+ status: "upcoming",
200
169
  });
201
170
  ```
202
171
 
203
- ### Oura Ring — wearable health data
172
+ The connector gateway URL is resolved internally from the HealthCloud environment. Applications never pass connector base URLs or the HealthCloud bearer token again when creating a connector client.
204
173
 
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
- });
174
+ ### Credentials and secrets
213
175
 
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,
176
+ Keep credentials in a server-side secret manager or environment variables. Do not hardcode them in source code and do not create connector clients in browser code.
177
+
178
+ ```ts
179
+ const stripe = sdk.connectors.stripe.createClient({
180
+ api_key: process.env.STRIPE_API_KEY!,
220
181
  });
221
182
 
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,
183
+ const intent = await stripe.createPaymentIntent({
184
+ amount: 5000,
185
+ currency: "usd",
229
186
  });
230
187
  ```
231
188
 
232
- ### Sandbox vs live mode
189
+ The SDK holds connector credentials only on that connector-client instance and forwards them to the HealthCloud Connectors gateway with every HTTPS request. Scoped secret fields cannot be replaced by operation input. Gateway errors are redacted before they are exposed as `SDKError` instances.
190
+
191
+ ### Sandbox and live modes
192
+
193
+ Mode is configured when the connector client is created. Connectors that support mode default to `sandbox`.
233
194
 
234
195
  ```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,
196
+ const fedexSandbox = sdk.connectors.fedex.createClient({
197
+ client_id: process.env.FEDEX_CLIENT_ID!,
198
+ client_secret: process.env.FEDEX_CLIENT_SECRET!,
199
+ account_number: process.env.FEDEX_ACCOUNT_NUMBER!,
240
200
  });
241
201
 
242
- // Live
243
- const liveResult = await sdk.vendors.stripe.createPaymentIntent({
244
- amount: 5000,
245
- currency: "usd",
202
+ const fedexLive = sdk.connectors.fedex.createClient({
203
+ client_id: process.env.FEDEX_CLIENT_ID!,
204
+ client_secret: process.env.FEDEX_CLIENT_SECRET!,
205
+ account_number: process.env.FEDEX_ACCOUNT_NUMBER!,
246
206
  mode: "live",
247
- ...stripeCredentials,
248
207
  });
249
208
  ```
250
209
 
251
- ### Athena Health EHR
210
+ ### Athena Health example
252
211
 
253
212
  ```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",
213
+ const athena = sdk.connectors.athena.createClient({
214
+ secret_key: process.env.ATHENA_SECRET_KEY!,
215
+ practice_id: process.env.ATHENA_PRACTICE_ID!,
216
+ department_id: process.env.ATHENA_DEPARTMENT_ID!,
217
+ provider_id: process.env.ATHENA_PROVIDER_ID!,
266
218
  mode: "sandbox",
267
- ...athenaCredentials,
268
219
  });
269
220
 
270
- // Insurance packages
271
- const packages = await sdk.vendors.athena.getInsurancePackages({
272
- patient_id: "67890",
273
- mode: "sandbox",
274
- ...athenaCredentials,
221
+ const patients = await athena.searchPatients({
222
+ last_name: "Smith",
223
+ first_name: "Jane",
275
224
  });
276
225
 
277
- // Check a patient in
278
- await sdk.vendors.athena.checkInPatient({
226
+ const booking = await athena.bookAppointment({
279
227
  appointment_id: "12345",
280
- mode: "sandbox",
281
- ...athenaCredentials,
228
+ patient_id: "67890",
282
229
  });
283
230
  ```
284
231
 
285
- ### Stripe payments
232
+ Non-secret connector context such as an Athena department or provider can be overridden by an operation when the backend contract supports it. Connector-scoped secrets cannot be overridden.
233
+
234
+ ### OAuth connector example
286
235
 
287
236
  ```ts
288
- // Create a PaymentIntent
289
- const intent = await sdk.vendors.stripe.createPaymentIntent({
290
- amount: 5000,
291
- currency: "usd",
237
+ const whoop = sdk.connectors.whoop.createClient({
238
+ client_id: process.env.WHOOP_CLIENT_ID!,
239
+ client_secret: process.env.WHOOP_CLIENT_SECRET!,
292
240
  mode: "sandbox",
293
- ...stripeCredentials,
294
241
  });
295
- // Use intent.client_secret for client-side confirmation
296
242
 
297
- // Create a customer
298
- const customer = await sdk.vendors.stripe.createCustomer({
299
- email: "patient@example.com",
300
- mode: "sandbox",
301
- ...stripeCredentials,
243
+ const url = await whoop.buildAuthorizationUrl({
244
+ redirect_uri: "https://myapp.example.com/whoop/callback",
245
+ scopes: ["read:profile", "read:cycles"],
302
246
  });
247
+ ```
248
+
249
+ ### Public connector without vendor credentials
303
250
 
304
- // List products
305
- const products = await sdk.vendors.stripe.listProducts({ mode: "sandbox", ...stripeCredentials });
251
+ NPPES uses the same factory pattern but does not require external credentials:
306
252
 
307
- // Verify credentials
308
- const status = await sdk.vendors.stripe.verifyConnection({ mode: "sandbox", ...stripeCredentials });
253
+ ```ts
254
+ const nppes = sdk.connectors.nppes.createClient();
255
+ const provider = await nppes.verifyProvider({ npi: "1234567890" });
309
256
  ```
310
257
 
311
- ### Error handling for vendor calls
258
+ ### Error handling
312
259
 
313
260
  ```ts
314
261
  import { SDKError } from "@healthcloudai/hc-sdk";
315
262
 
316
263
  try {
317
- const result = await sdk.vendors.stripe.createPaymentIntent({
318
- amount: 5000,
319
- currency: "usd",
320
- mode: "sandbox",
321
- ...stripeCredentials,
322
- });
264
+ await stripe.verifyConnection();
323
265
  } catch (error) {
324
266
  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
267
+ console.log(error.statusCode);
268
+ console.log(error.message); // connector secrets are redacted
269
+ console.log(error.response); // sensitive fields are redacted
329
270
  }
330
271
  }
331
272
  ```
332
273
 
333
- ### Available vendor clients
274
+ ### Available connectors
275
+
276
+ All 33 connectors follow the same pattern: `sdk.connectors.<name>.createClient({ ...credentials })` returns an isolated, credential-scoped client whose methods call `POST /connectors/<slug>/<operation>` on the HealthCloud Connectors gateway. The table lists each connector's required credential fields and the conventional `HC_*` environment variable names used by the live test suite (names only — never commit values). Fields marked `mode?` accept `"sandbox"` (default) or `"live"`.
277
+
278
+ | Connector | Purpose | `createClient` credentials | Suggested env vars | Called via |
279
+ |---|---|---|---|---|
280
+ | `anthropic` | Anthropic (Claude) LLM completions | `api_key`, `mode?` | `HC_ANTHROPIC_API_KEY` | `sdk.connectors.anthropic.createClient({...})` |
281
+ | `appleAuth` | Sign in with Apple token exchange | `team_id`, `client_id`, `key_id`, `redirect_uri`, `private_key` | `HC_APPLE_AUTH_TEAM_ID`, `HC_APPLE_AUTH_CLIENT_ID`, `HC_APPLE_AUTH_KEY_ID`, `HC_APPLE_AUTH_REDIRECT_URI`, `HC_APPLE_AUTH_PRIVATE_KEY` | `sdk.connectors.appleAuth.createClient({...})` |
282
+ | `athena` | athenahealth EHR (patients, appointments) | `secret_key`, `practice_id`, `department_id`, `provider_id`, `mode?` | `HC_ATHENA_SECRET_KEY`, `HC_ATHENA_PRACTICE_ID`, `HC_ATHENA_DEPARTMENT_ID`, `HC_ATHENA_PROVIDER_ID` | `sdk.connectors.athena.createClient({...})` |
283
+ | `cal` | Cal.com scheduling and bookings | `api_key` | `HC_CAL_API_KEY` | `sdk.connectors.cal.createClient({...})` |
284
+ | `carequality` | Carequality health information exchange | `api_key`, `initiator_url` | `HC_CAREQUALITY_API_KEY`, `HC_CAREQUALITY_INITIATOR_URL` | `sdk.connectors.carequality.createClient({...})` |
285
+ | `cms` | CMS (Centers for Medicare & Medicaid) data | `api_key` | `HC_CMS_API_KEY` | `sdk.connectors.cms.createClient({...})` |
286
+ | `connecture` | ConnectureDRX Medicare plan shopping | `basic_token`, `client_key`, `client_secret` | `HC_CONNECTURE_BASIC_TOKEN`, `HC_CONNECTURE_CLIENT_KEY`, `HC_CONNECTURE_CLIENT_SECRET` | `sdk.connectors.connecture.createClient({...})` |
287
+ | `elevenlabs` | ElevenLabs text-to-speech | `api_key` | `HC_ELEVENLABS_API_KEY` | `sdk.connectors.elevenlabs.createClient({...})` |
288
+ | `fedex` | FedEx shipping and tracking | `client_id`, `client_secret`, `account_number`, `mode?` | `HC_FEDEX_CLIENT_ID`, `HC_FEDEX_CLIENT_SECRET`, `HC_FEDEX_ACCOUNT_NUMBER` | `sdk.connectors.fedex.createClient({...})` |
289
+ | `googleAI` | Google AI (Gemini) LLM | `api_key` | `HC_GOOGLE_AI_API_KEY` | `sdk.connectors.googleAI.createClient({...})` |
290
+ | `googlePlaces` | Google Places search/geocoding | `api_key`, `mode?` | `HC_GOOGLE_PLACES_API_KEY` | `sdk.connectors.googlePlaces.createClient({...})` |
291
+ | `grok` | xAI Grok LLM | `api_key` | `HC_GROK_API_KEY` | `sdk.connectors.grok.createClient({...})` |
292
+ | `healthie` | Healthie EHR / practice management | `secret_key`, `mode?`, `shard_id?` | `HC_HEALTHIE_SECRET_KEY`, `HC_HEALTHIE_AUTHORIZATION_SHARD` | `sdk.connectors.healthie.createClient({...})` |
293
+ | `impilo` | Impilo remote patient monitoring logistics | `api_key` | `HC_IMPILO_API_KEY` | `sdk.connectors.impilo.createClient({...})` |
294
+ | `junction` | Junction (Vital) lab testing and wearables | `api_key` | `HC_JUNCTION_API_KEY` | `sdk.connectors.junction.createClient({...})` |
295
+ | `nppes` | NPPES NPI registry lookup (public, no credentials) | — | — | `sdk.connectors.nppes.createClient()` |
296
+ | `openai` | OpenAI LLM completions | `api_key` | `HC_OPENAI_API_KEY` | `sdk.connectors.openai.createClient({...})` |
297
+ | `oura` | Oura ring wearable data (OAuth) | `client_id`, `client_secret`, `mode?` | `HC_OURA_CLIENT_ID`, `HC_OURA_CLIENT_SECRET` | `sdk.connectors.oura.createClient({...})` |
298
+ | `plaid` | Plaid identity / financial verification | `client_id`, `secret`, `template_id`, `mode?` | `HC_PLAID_CLIENT_ID`, `HC_PLAID_SECRET`, `HC_PLAID_TEMPLATE_ID` | `sdk.connectors.plaid.createClient({...})` |
299
+ | `quest` | Quest Diagnostics lab orders/results — REST-style order/results/catalog operations plus HL7 orders, results, and compendium operations | `client_id`, `client_secret`, `mode?` | `HC_QUEST_CLIENT_ID`, `HC_QUEST_CLIENT_SECRET` | `sdk.connectors.quest.createClient({...})` |
300
+ | `salesforce` | Salesforce CRM records and queries | `client_id`, `client_secret`, `username`, `password`, `mode?` | `HC_SALESFORCE_CLIENT_ID`, `HC_SALESFORCE_CLIENT_SECRET`, `HC_SALESFORCE_USERNAME`, `HC_SALESFORCE_PASSWORD` | `sdk.connectors.salesforce.createClient({...})` |
301
+ | `scrapfly` | Scrapfly web scraping | `api_key` | `HC_SCRAPFLY_API_KEY` | `sdk.connectors.scrapfly.createClient({...})` |
302
+ | `senaite` | SENAITE LIMS (lab information management) | `base_url`, `username`, `password` | `HC_SENAITE_BASE_URL`, `HC_SENAITE_USERNAME`, `HC_SENAITE_PASSWORD` | `sdk.connectors.senaite.createClient({...})` |
303
+ | `sendgrid` | SendGrid transactional email | `api_key`, `mode?` | `HC_SENDGRID_API_KEY` | `sdk.connectors.sendgrid.createClient({...})` |
304
+ | `steadymd` | SteadyMD telehealth clinician network | `api_key` **or** `token` (exactly one), `mode?`, `api_url?` | `HC_STEADYMD_API_KEY` or `HC_STEADYMD_TOKEN`, `HC_STEADYMD_API_URL` | `sdk.connectors.steadymd.createClient({...})` |
305
+ | `stedi` | Stedi insurance eligibility (X12/EDI) | `api_key` | `HC_STEDI_API_KEY` | `sdk.connectors.stedi.createClient({...})` |
306
+ | `stripe` | Stripe payments and subscriptions | `api_key` | `HC_STRIPE_API_KEY` | `sdk.connectors.stripe.createClient({...})` |
307
+ | `twilio` | Twilio SMS / voice messaging | `account_sid`, `auth_token`, `from_number`, `mode?` | `HC_TWILIO_ACCOUNT_SID`, `HC_TWILIO_AUTH_TOKEN`, `HC_TWILIO_FROM_NUMBER` | `sdk.connectors.twilio.createClient({...})` |
308
+ | `uber` | Uber Direct / Health rides and deliveries | `client_id`, `client_secret`, `customer_id`, `mode?` | `HC_UBER_CLIENT_ID`, `HC_UBER_CLIENT_SECRET`, `HC_UBER_CUSTOMER_ID` | `sdk.connectors.uber.createClient({...})` |
309
+ | `whoop` | WHOOP wearable data (OAuth) | `client_id`, `client_secret`, `mode?` | `HC_WHOOP_CLIENT_ID`, `HC_WHOOP_CLIENT_SECRET` | `sdk.connectors.whoop.createClient({...})` |
310
+ | `zocdoc` | Zocdoc provider search and booking | `api_key` | `HC_ZOCDOC_API_KEY` | `sdk.connectors.zocdoc.createClient({...})` |
311
+ | `zus` | Zus Health aggregated patient data | `client_id`, `client_secret`, `mode?` | `HC_ZUS_CLIENT_ID`, `HC_ZUS_CLIENT_SECRET` | `sdk.connectors.zus.createClient({...})` |
312
+
313
+ > Note: the `quest` connector is a single client that exposes both the REST-style order/results/catalog operations and the HL7 message-based operations (orders, results, and compendium); all route to the gateway's `quest` slug and share the same credentials.
314
+
315
+ ### Sequential live integration tests
316
+
317
+ Each connector has its own opt-in sequential test under `tests/live/connectors/`. Tests load credentials from `.env`, create the connector client once, and call every public method one by one. Sandbox is the default. Live connector calls require an additional explicit opt-in.
334
318
 
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/` |
319
+ ```bash
320
+ HC_RUN_CONNECTOR_INTEGRATION=true npm run test:live:connectors
321
+
322
+ # Run one connector file
323
+ HC_RUN_CONNECTOR_INTEGRATION=true \
324
+ npm run test:live:connector -- tests/live/connectors/cal.sequential.live.ts
325
+ ```
326
+
327
+ Set `HC_CONNECTOR_STRICT=true` to require every method to return a successful response. Without strict mode, expected sandbox, OAuth-fixture, and resource-fixture failures are reported without hiding SDK contract or network failures. Reports are written to `reports/connectors/`.
366
328
 
367
329
  ---
368
330