@healthcloudai/hc-sdk 0.5.0 → 0.7.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
@@ -143,6 +143,191 @@ All groups share one HTTP client, one token store, one error handler, the same U
143
143
 
144
144
  ---
145
145
 
146
+ ## Connectors (`sdk.connectors`)
147
+
148
+ Connector clients are created in three explicit steps:
149
+
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.
153
+
154
+ ```ts
155
+ import { HCSDK } from "@healthcloudai/hc-sdk";
156
+
157
+ const sdk = new HCSDK({
158
+ environment: "prod", // "dev" | "uat" | "prod"
159
+ tenantId: "<TENANT_ID>",
160
+ accessToken: "<HEALTHCLOUD_ACCESS_TOKEN>",
161
+ });
162
+
163
+ const cal = sdk.connectors.cal.createClient({
164
+ api_key: process.env.CAL_API_KEY!,
165
+ });
166
+
167
+ const bookings = await cal.getAllBookings({
168
+ status: "upcoming",
169
+ });
170
+ ```
171
+
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.
173
+
174
+ ### Credentials and secrets
175
+
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!,
181
+ });
182
+
183
+ const intent = await stripe.createPaymentIntent({
184
+ amount: 5000,
185
+ currency: "usd",
186
+ });
187
+ ```
188
+
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`.
194
+
195
+ ```ts
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!,
200
+ });
201
+
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!,
206
+ mode: "live",
207
+ });
208
+ ```
209
+
210
+ ### Athena Health example
211
+
212
+ ```ts
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!,
218
+ mode: "sandbox",
219
+ });
220
+
221
+ const patients = await athena.searchPatients({
222
+ last_name: "Smith",
223
+ first_name: "Jane",
224
+ });
225
+
226
+ const booking = await athena.bookAppointment({
227
+ appointment_id: "12345",
228
+ patient_id: "67890",
229
+ });
230
+ ```
231
+
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
235
+
236
+ ```ts
237
+ const whoop = sdk.connectors.whoop.createClient({
238
+ client_id: process.env.WHOOP_CLIENT_ID!,
239
+ client_secret: process.env.WHOOP_CLIENT_SECRET!,
240
+ mode: "sandbox",
241
+ });
242
+
243
+ const url = await whoop.buildAuthorizationUrl({
244
+ redirect_uri: "https://myapp.example.com/whoop/callback",
245
+ scopes: ["read:profile", "read:cycles"],
246
+ });
247
+ ```
248
+
249
+ ### Public connector without vendor credentials
250
+
251
+ NPPES uses the same factory pattern but does not require external credentials:
252
+
253
+ ```ts
254
+ const nppes = sdk.connectors.nppes.createClient();
255
+ const provider = await nppes.verifyProvider({ npi: "1234567890" });
256
+ ```
257
+
258
+ ### Error handling
259
+
260
+ ```ts
261
+ import { SDKError } from "@healthcloudai/hc-sdk";
262
+
263
+ try {
264
+ await stripe.verifyConnection();
265
+ } catch (error) {
266
+ if (error instanceof SDKError) {
267
+ console.log(error.statusCode);
268
+ console.log(error.message); // connector secrets are redacted
269
+ console.log(error.response); // sensitive fields are redacted
270
+ }
271
+ }
272
+ ```
273
+
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.
318
+
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/`.
328
+
329
+ ---
330
+
146
331
  ## Auth
147
332
 
148
333
  ```ts