@healthcloudai/hc-ams 0.0.1 → 3.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/dist/index.d.cts CHANGED
@@ -25,6 +25,18 @@ declare const DEFAULT_TIMEOUT_MS = 30000;
25
25
  * services use — mirrors `resolveBaseUrl` in packages/npm/src/config/SDKConfig.ts.
26
26
  */
27
27
  declare function resolveBaseUrl(environment: Environment): string;
28
+ /**
29
+ * AMS mounts its tenant-admin auth routes (`/api/auth/*`) alongside, not
30
+ * under, `/api/ams` — so `AuthClient` resolves against this base instead of
31
+ * {@link resolveBaseUrl}.
32
+ */
33
+ declare function resolveAmsAuthBaseUrl(environment: Environment): string;
34
+ /**
35
+ * WSS mounts at the bare host (`/ws`, `/ws/agents/{id}/chat`) — no `/api/ams`
36
+ * suffix — and always uses the secure WebSocket scheme (`wss:`), never
37
+ * plaintext, mirroring `https:` vs `http:` for the REST hosts above.
38
+ */
39
+ declare function resolveWssBaseUrl(environment: Environment): string;
28
40
  declare function assertEnvironment(environment: Environment): void;
29
41
  declare function assertTimeout(timeout: number, label?: string): void;
30
42
 
@@ -72,6 +84,400 @@ type AmsApplicationAgentsResponse = Record<string, string[]> & {
72
84
  orchestrator?: string[];
73
85
  };
74
86
 
87
+ /** Audit fields common to every AMS entity (mirrors `AMSAuditableModel`). */
88
+ interface AmsAuditableFields {
89
+ id: string;
90
+ created_at: string;
91
+ updated_at: string;
92
+ tenant_id: string;
93
+ created_by_user_id: string;
94
+ created_date: string;
95
+ }
96
+
97
+ type AgentType = "Application" | "Phone" | "Utility";
98
+ type AgentPreferredModel = "gpt-4o" | "gpt-5" | "gpt-5-nano";
99
+ type AgentMode = "single" | "multi-agent";
100
+ type AgentStatus = "draft" | "active" | "disabled" | "archived";
101
+ type AgentTTSModel = "openai/alloy" | "openai/ash" | "openai/ballad" | "openai/coral" | "openai/echo" | "openai/fable" | "openai/nova" | "openai/onyx" | "openai/sage" | "openai/shimmer" | "openai/verse";
102
+ interface AIAgent extends AmsAuditableFields {
103
+ name: string;
104
+ status: AgentStatus;
105
+ active: boolean;
106
+ key?: string | null;
107
+ is_default: boolean;
108
+ is_orchestrator: boolean;
109
+ health_service_id?: string | null;
110
+ type: AgentType;
111
+ model?: string | null;
112
+ preferred_model: AgentPreferredModel;
113
+ mode: AgentMode;
114
+ description?: string | null;
115
+ temperature: number;
116
+ max_tokens: number;
117
+ voice?: string | null;
118
+ requires_auth: boolean;
119
+ language?: string | null;
120
+ supported_languages: string[];
121
+ allowed_roles: string[];
122
+ required_scopes: string[];
123
+ patient_context_required: boolean;
124
+ opening_card?: Record<string, unknown> | null;
125
+ opening_suggestions: boolean;
126
+ instructions: string;
127
+ greetings: Record<string, string>;
128
+ suggestion_instructions: string;
129
+ utility_instructions?: string | null;
130
+ utility_action_output_format?: string | null;
131
+ utility_execution_context?: string | null;
132
+ guardrails_input: string[];
133
+ guardrails_output: string[];
134
+ tools: string[];
135
+ data_sources: string[];
136
+ department_id?: string | null;
137
+ team_id?: string | null;
138
+ skill_ids: string[];
139
+ tool_ids: string[];
140
+ policy_ids: string[];
141
+ guardrail_ids: string[];
142
+ data_source_ids: string[];
143
+ tts_model?: AgentTTSModel | null;
144
+ artifact_kinds: Record<string, unknown>;
145
+ custom_tools: Record<string, unknown>;
146
+ workflow?: Record<string, unknown> | null;
147
+ config_version: number;
148
+ locked_until?: unknown;
149
+ }
150
+ interface AIAgentCreate {
151
+ name: string;
152
+ type?: AgentType;
153
+ key?: string | null;
154
+ is_default?: boolean;
155
+ is_orchestrator?: boolean;
156
+ health_service_id?: string | null;
157
+ model?: string | null;
158
+ preferred_model?: AgentPreferredModel;
159
+ mode?: AgentMode;
160
+ description?: string | null;
161
+ voice?: string | null;
162
+ requires_auth?: boolean;
163
+ opening_card?: Record<string, unknown> | null;
164
+ opening_suggestions?: boolean;
165
+ instructions?: string;
166
+ greetings?: Record<string, string>;
167
+ suggestion_instructions?: string;
168
+ supported_languages?: string[];
169
+ utility_instructions?: string | null;
170
+ utility_action_output_format?: string | null;
171
+ utility_execution_context?: string | null;
172
+ guardrails_input?: string[];
173
+ guardrails_output?: string[];
174
+ tools?: string[];
175
+ data_sources?: string[];
176
+ department_id?: string | null;
177
+ team_id?: string | null;
178
+ skill_ids?: string[];
179
+ tool_ids?: string[];
180
+ policy_ids?: string[];
181
+ guardrail_ids?: string[];
182
+ data_source_ids?: string[];
183
+ tts_model?: AgentTTSModel | null;
184
+ artifact_kinds?: Record<string, unknown>;
185
+ custom_tools?: Record<string, unknown>;
186
+ workflow?: Record<string, unknown> | null;
187
+ tenant_id?: string | null;
188
+ created_by_user_id?: string | null;
189
+ }
190
+ interface AIAgentUpdate {
191
+ name?: string;
192
+ status?: AgentStatus;
193
+ active?: boolean;
194
+ key?: string | null;
195
+ is_default?: boolean;
196
+ is_orchestrator?: boolean;
197
+ health_service_id?: string | null;
198
+ model?: string | null;
199
+ preferred_model?: AgentPreferredModel;
200
+ mode?: AgentMode;
201
+ description?: string | null;
202
+ voice?: string | null;
203
+ requires_auth?: boolean;
204
+ language?: string | null;
205
+ utility_instructions?: string | null;
206
+ utility_action_output_format?: string | null;
207
+ utility_execution_context?: string | null;
208
+ supported_languages?: string[];
209
+ allowed_roles?: string[];
210
+ required_scopes?: string[];
211
+ patient_context_required?: boolean;
212
+ opening_card?: Record<string, unknown> | null;
213
+ opening_suggestions?: boolean;
214
+ instructions?: string;
215
+ greetings?: Record<string, string>;
216
+ guardrails_input?: string[];
217
+ guardrails_output?: string[];
218
+ tools?: string[];
219
+ data_sources?: string[];
220
+ department_id?: string | null;
221
+ team_id?: string | null;
222
+ skill_ids?: string[];
223
+ tool_ids?: string[];
224
+ policy_ids?: string[];
225
+ guardrail_ids?: string[];
226
+ data_source_ids?: string[];
227
+ tts_model?: AgentTTSModel | null;
228
+ suggestion_instructions?: string;
229
+ artifact_kinds?: Record<string, unknown>;
230
+ custom_tools?: Record<string, unknown>;
231
+ workflow?: Record<string, unknown> | null;
232
+ }
233
+ /** GET /agents/candidates — non-orchestrator agents eligible as transfer targets. */
234
+ interface TransferCandidate {
235
+ id: string;
236
+ name?: string | null;
237
+ description?: string | null;
238
+ department_id?: string | null;
239
+ team_id?: string | null;
240
+ health_service_id?: string | null;
241
+ }
242
+
243
+ interface DepartmentTeamEvaluation {
244
+ required_eval_suite_ids: string[];
245
+ }
246
+ interface Department extends AmsAuditableFields {
247
+ name: string;
248
+ description?: string | null;
249
+ active: boolean;
250
+ parent_department_id?: string | null;
251
+ key?: string | null;
252
+ evaluation: DepartmentTeamEvaluation;
253
+ }
254
+ interface DepartmentCreate {
255
+ name: string;
256
+ description?: string | null;
257
+ parent_department_id?: string | null;
258
+ tenant_id?: string | null;
259
+ created_by_user_id: string;
260
+ key?: string | null;
261
+ evaluation?: DepartmentTeamEvaluation | null;
262
+ }
263
+ interface DepartmentUpdate {
264
+ name?: string;
265
+ description?: string | null;
266
+ parent_department_id?: string | null;
267
+ key?: string | null;
268
+ evaluation?: DepartmentTeamEvaluation | null;
269
+ }
270
+
271
+ interface Team extends AmsAuditableFields {
272
+ name: string;
273
+ department_id: string;
274
+ description?: string | null;
275
+ key?: string | null;
276
+ evaluation: DepartmentTeamEvaluation;
277
+ }
278
+ interface TeamCreate {
279
+ name: string;
280
+ department_id: string;
281
+ description?: string | null;
282
+ tenant_id?: string | null;
283
+ created_by_user_id: string;
284
+ key?: string | null;
285
+ evaluation?: DepartmentTeamEvaluation | null;
286
+ }
287
+ interface TeamUpdate {
288
+ name?: string;
289
+ description?: string | null;
290
+ key?: string | null;
291
+ evaluation?: DepartmentTeamEvaluation | null;
292
+ }
293
+
294
+ interface AISkill extends AmsAuditableFields {
295
+ name: string;
296
+ description?: string | null;
297
+ tool_ids: string[];
298
+ }
299
+ interface AISkillCreate {
300
+ name: string;
301
+ description?: string | null;
302
+ tool_ids?: string[];
303
+ tenant_id?: string | null;
304
+ created_by_user_id: string;
305
+ }
306
+ interface AISkillUpdate {
307
+ name?: string;
308
+ description?: string | null;
309
+ tool_ids?: string[];
310
+ }
311
+
312
+ interface Policy extends AmsAuditableFields {
313
+ name: string;
314
+ department_id: string;
315
+ description?: string | null;
316
+ content?: string | null;
317
+ guardrail_ids: string[];
318
+ active: boolean;
319
+ }
320
+ interface PolicyCreate {
321
+ name: string;
322
+ department_id: string;
323
+ description?: string | null;
324
+ content?: string | null;
325
+ guardrail_ids?: string[];
326
+ tenant_id?: string | null;
327
+ created_by_user_id: string;
328
+ }
329
+ interface PolicyUpdate {
330
+ name?: string;
331
+ description?: string | null;
332
+ content?: string | null;
333
+ guardrail_ids?: string[];
334
+ active?: boolean;
335
+ }
336
+
337
+ interface AIGuardrail extends AmsAuditableFields {
338
+ name: string;
339
+ description?: string | null;
340
+ rules: Record<string, unknown>;
341
+ }
342
+ interface AIGuardrailCreate {
343
+ name: string;
344
+ description?: string | null;
345
+ rules?: Record<string, unknown>;
346
+ tenant_id?: string | null;
347
+ created_by_user_id: string;
348
+ }
349
+ interface AIGuardrailUpdate {
350
+ name?: string;
351
+ description?: string | null;
352
+ rules?: Record<string, unknown>;
353
+ }
354
+
355
+ /** Read-only catalog entries — AMS exposes no create/update/delete for these. */
356
+ interface AIDataSource {
357
+ id: string;
358
+ name: string;
359
+ description: string;
360
+ }
361
+ interface AITool {
362
+ id: string;
363
+ name: string;
364
+ description: string;
365
+ parameters: string[];
366
+ input_schema?: Record<string, unknown> | null;
367
+ read_only: boolean;
368
+ pip_operation: string;
369
+ agent_type: string;
370
+ requires_confirmation: boolean;
371
+ required_scope: string;
372
+ audit_event: string;
373
+ activity_label: string;
374
+ }
375
+
376
+ /** `healthcloud_environment` — restricted to the HealthCloud env pattern `^(dev|uat|prod)$`. */
377
+ type TestPatientCredentialEnvironment = "dev" | "uat" | "prod";
378
+ interface TestPatientCredentialCreate {
379
+ name: string;
380
+ email: string;
381
+ /** Must be 8-512 chars with uppercase, lowercase, a digit, and a special character. */
382
+ password: string;
383
+ healthcloud_environment?: TestPatientCredentialEnvironment;
384
+ patient_id?: string | null;
385
+ enabled?: boolean;
386
+ description?: string | null;
387
+ }
388
+ interface TestPatientCredentialUpdate {
389
+ name?: string;
390
+ email?: string;
391
+ password?: string;
392
+ healthcloud_environment?: TestPatientCredentialEnvironment;
393
+ patient_id?: string | null;
394
+ enabled?: boolean;
395
+ description?: string | null;
396
+ }
397
+ interface TestPatientCredentialResponse {
398
+ id: string;
399
+ tenant_id: string;
400
+ name: string;
401
+ email_masked: string;
402
+ healthcloud_tenant_id: string;
403
+ healthcloud_environment: string;
404
+ patient_id?: string | null;
405
+ enabled: boolean;
406
+ description?: string | null;
407
+ last_login_at?: string | null;
408
+ last_login_status?: string | null;
409
+ created_at: string;
410
+ updated_at: string;
411
+ }
412
+ /** POST /test-patient-credentials/{id}/login — response used to open a WSS session as this persona. */
413
+ interface TestPatientLoginResponse {
414
+ credential_id: string;
415
+ healthcloud_tenant_id: string;
416
+ patient_id: string;
417
+ access_token: string;
418
+ expires_in: number;
419
+ }
420
+
421
+ interface ConversationHistoryEntry {
422
+ role: string;
423
+ content: string;
424
+ images: string[];
425
+ image_filenames: string[];
426
+ image_ids: string[];
427
+ }
428
+ /** GET /agents/{agent_id}/conversation?session_id={tenant_id}/{patient_id} */
429
+ interface ConversationHistory {
430
+ session_id: string;
431
+ agent_id: string;
432
+ messages: ConversationHistoryEntry[];
433
+ }
434
+
435
+ /** POST /api/auth/login */
436
+ interface LoginRequest {
437
+ username: string;
438
+ password: string;
439
+ tenant_id: string;
440
+ }
441
+ interface TokenResponse {
442
+ access_token: string;
443
+ token_type: string;
444
+ user_id: string;
445
+ tenant_id: string;
446
+ }
447
+ /** POST /api/auth/reset-password */
448
+ interface PasswordResetRequest {
449
+ email: string;
450
+ tenant_id: string;
451
+ }
452
+ /** POST /api/auth/confirm-reset-password */
453
+ interface PasswordResetConfirmRequest {
454
+ email: string;
455
+ tenant_id: string;
456
+ new_password: string;
457
+ confirmation_code: string;
458
+ }
459
+ interface AuthMessageResponse {
460
+ message: string;
461
+ }
462
+ /** POST /api/auth/register */
463
+ interface RegistrationRequest {
464
+ first_name: string;
465
+ last_name: string;
466
+ email: string;
467
+ password: string;
468
+ tenant_id: string;
469
+ phone?: string | null;
470
+ }
471
+ interface RegistrationResponse {
472
+ message: string;
473
+ email_verification_required: boolean;
474
+ }
475
+ /** GET /api/auth/me */
476
+ interface AuthenticatedUser {
477
+ user_id: string;
478
+ tenant_id: string;
479
+ }
480
+
75
481
  declare abstract class BaseServiceClient {
76
482
  protected readonly http: HttpClient;
77
483
  constructor(http: HttpClient);
@@ -92,12 +498,531 @@ declare class AmsClient extends BaseServiceClient {
92
498
  getAgentsForTenant<TResponse = AmsApplicationAgentsResponse>(tenantId: string): Promise<TResponse>;
93
499
  }
94
500
 
501
+ /**
502
+ * AgentsClient — full CRUD over AMS agents, plus transfer-candidate
503
+ * discovery and conversation-history access. All routes require a Tenant
504
+ * Admin Bearer token.
505
+ *
506
+ * Note: `create`/`update`/`delete` may respond 405 on tenants where AMS is
507
+ * configured with `disable_direct_agent_mutations` — in that mode, agent
508
+ * authoring happens exclusively through the Vibe Coder plan/apply flow,
509
+ * which is intentionally out of scope for this client.
510
+ */
511
+ declare class AgentsClient extends BaseServiceClient {
512
+ constructor(http: HttpClient);
513
+ /** GET /agents */
514
+ list<TResponse = AIAgent[]>(): Promise<TResponse>;
515
+ /** GET /agents/{agent_id} */
516
+ get<TResponse = AIAgent>(agentId: string): Promise<TResponse>;
517
+ /** POST /agents */
518
+ create<TResponse = AIAgent>(request: AIAgentCreate): Promise<TResponse>;
519
+ /** PUT /agents/{agent_id} */
520
+ update<TResponse = AIAgent>(agentId: string, request: AIAgentUpdate): Promise<TResponse>;
521
+ /** DELETE /agents/{agent_id} */
522
+ delete<TResponse = undefined>(agentId: string): Promise<TResponse>;
523
+ /** GET /agents/candidates — non-orchestrator agents eligible as transfer targets. */
524
+ listTransferCandidates<TResponse = TransferCandidate[]>(): Promise<TResponse>;
525
+ /**
526
+ * GET /agents/{agent_id}/conversation?session_id={tenant_id}/{patient_id}
527
+ *
528
+ * `sessionId` must be the literal `"{tenant_id}/{patient_id}"` string used
529
+ * to key the WSS session (see {@link "../wss/WssClient".WssClient}).
530
+ */
531
+ getConversation<TResponse = ConversationHistory>(agentId: string, sessionId: string): Promise<TResponse>;
532
+ /**
533
+ * DELETE /agents/{agent_id}/conversation?session_id={tenant_id}/{patient_id}
534
+ *
535
+ * Deletes both the persisted chat history and any live WSS session state
536
+ * for that session.
537
+ */
538
+ deleteConversation<TResponse = undefined>(agentId: string, sessionId: string): Promise<TResponse>;
539
+ }
540
+
541
+ /** DepartmentsClient — full CRUD over AMS departments. Requires a Tenant Admin Bearer token. */
542
+ declare class DepartmentsClient extends BaseServiceClient {
543
+ constructor(http: HttpClient);
544
+ /** GET /departments */
545
+ list<TResponse = Department[]>(): Promise<TResponse>;
546
+ /** GET /departments/{department_id} */
547
+ get<TResponse = Department>(departmentId: string): Promise<TResponse>;
548
+ /** POST /departments */
549
+ create<TResponse = Department>(request: DepartmentCreate): Promise<TResponse>;
550
+ /** PUT /departments/{department_id} */
551
+ update<TResponse = Department>(departmentId: string, request: DepartmentUpdate): Promise<TResponse>;
552
+ /** DELETE /departments/{department_id} */
553
+ delete<TResponse = undefined>(departmentId: string): Promise<TResponse>;
554
+ /** POST /departments/{department_id}/activate */
555
+ activate<TResponse = Department>(departmentId: string): Promise<TResponse>;
556
+ /** POST /departments/{department_id}/deactivate */
557
+ deactivate<TResponse = Department>(departmentId: string): Promise<TResponse>;
558
+ }
559
+
560
+ /** TeamsClient — full CRUD over AMS teams. Requires a Tenant Admin Bearer token. */
561
+ declare class TeamsClient extends BaseServiceClient {
562
+ constructor(http: HttpClient);
563
+ /** GET /teams */
564
+ list<TResponse = Team[]>(): Promise<TResponse>;
565
+ /** GET /teams/{team_id} */
566
+ get<TResponse = Team>(teamId: string): Promise<TResponse>;
567
+ /** POST /teams */
568
+ create<TResponse = Team>(request: TeamCreate): Promise<TResponse>;
569
+ /** PUT /teams/{team_id} */
570
+ update<TResponse = Team>(teamId: string, request: TeamUpdate): Promise<TResponse>;
571
+ /** DELETE /teams/{team_id} */
572
+ delete<TResponse = undefined>(teamId: string): Promise<TResponse>;
573
+ }
574
+
575
+ /** SkillsClient — full CRUD over AMS skills. Requires a Tenant Admin Bearer token. */
576
+ declare class SkillsClient extends BaseServiceClient {
577
+ constructor(http: HttpClient);
578
+ /** GET /skills */
579
+ list<TResponse = AISkill[]>(): Promise<TResponse>;
580
+ /** GET /skills/{skill_id} */
581
+ get<TResponse = AISkill>(skillId: string): Promise<TResponse>;
582
+ /** POST /skills */
583
+ create<TResponse = AISkill>(request: AISkillCreate): Promise<TResponse>;
584
+ /** PUT /skills/{skill_id} */
585
+ update<TResponse = AISkill>(skillId: string, request: AISkillUpdate): Promise<TResponse>;
586
+ /** DELETE /skills/{skill_id} */
587
+ delete<TResponse = undefined>(skillId: string): Promise<TResponse>;
588
+ }
589
+
590
+ /** PoliciesClient — full CRUD over AMS policies. Requires a Tenant Admin Bearer token. */
591
+ declare class PoliciesClient extends BaseServiceClient {
592
+ constructor(http: HttpClient);
593
+ /** GET /policies */
594
+ list<TResponse = Policy[]>(): Promise<TResponse>;
595
+ /** GET /policies/{policy_id} */
596
+ get<TResponse = Policy>(policyId: string): Promise<TResponse>;
597
+ /** POST /policies */
598
+ create<TResponse = Policy>(request: PolicyCreate): Promise<TResponse>;
599
+ /** PUT /policies/{policy_id} */
600
+ update<TResponse = Policy>(policyId: string, request: PolicyUpdate): Promise<TResponse>;
601
+ /** DELETE /policies/{policy_id} */
602
+ delete<TResponse = undefined>(policyId: string): Promise<TResponse>;
603
+ }
604
+
605
+ /** GuardrailsClient — full CRUD over AMS guardrails. Requires a Tenant Admin Bearer token. */
606
+ declare class GuardrailsClient extends BaseServiceClient {
607
+ constructor(http: HttpClient);
608
+ /** GET /guardrails */
609
+ list<TResponse = AIGuardrail[]>(): Promise<TResponse>;
610
+ /** GET /guardrails/{guardrail_id} */
611
+ get<TResponse = AIGuardrail>(guardrailId: string): Promise<TResponse>;
612
+ /** POST /guardrails */
613
+ create<TResponse = AIGuardrail>(request: AIGuardrailCreate): Promise<TResponse>;
614
+ /** PUT /guardrails/{guardrail_id} */
615
+ update<TResponse = AIGuardrail>(guardrailId: string, request: AIGuardrailUpdate): Promise<TResponse>;
616
+ /** DELETE /guardrails/{guardrail_id} */
617
+ delete<TResponse = undefined>(guardrailId: string): Promise<TResponse>;
618
+ }
619
+
620
+ /**
621
+ * DataSourcesClient — read-only catalog of AMS data sources. AMS exposes no
622
+ * create/update/delete for this resource. Requires a Tenant Admin Bearer token.
623
+ */
624
+ declare class DataSourcesClient extends BaseServiceClient {
625
+ constructor(http: HttpClient);
626
+ /** GET /data-sources */
627
+ list<TResponse = AIDataSource[]>(): Promise<TResponse>;
628
+ /** GET /data-sources/{data_source_id} */
629
+ get<TResponse = AIDataSource>(dataSourceId: string): Promise<TResponse>;
630
+ }
631
+
632
+ /**
633
+ * ToolsClient — read-only catalog of AMS tools. AMS exposes no
634
+ * create/update/delete for this resource. Requires a Tenant Admin Bearer token.
635
+ */
636
+ declare class ToolsClient extends BaseServiceClient {
637
+ constructor(http: HttpClient);
638
+ /** GET /tools */
639
+ list<TResponse = AITool[]>(): Promise<TResponse>;
640
+ /** GET /tools/{tool_id} */
641
+ get<TResponse = AITool>(toolId: string): Promise<TResponse>;
642
+ }
643
+
644
+ /**
645
+ * TestPersonasClient — CRUD over synthetic QA patient personas
646
+ * (`test-patient-credentials`), plus a `login` action that logs the persona
647
+ * into Health Cloud and returns a real patient access token. Requires a
648
+ * Tenant Admin Bearer token (the `login` call itself is tenant-admin
649
+ * authenticated even though it mints a *patient* token).
650
+ */
651
+ declare class TestPersonasClient extends BaseServiceClient {
652
+ constructor(http: HttpClient);
653
+ /** GET /test-patient-credentials */
654
+ list<TResponse = TestPatientCredentialResponse[]>(): Promise<TResponse>;
655
+ /** GET /test-patient-credentials/{credential_id} */
656
+ get<TResponse = TestPatientCredentialResponse>(credentialId: string): Promise<TResponse>;
657
+ /** POST /test-patient-credentials */
658
+ create<TResponse = TestPatientCredentialResponse>(request: TestPatientCredentialCreate): Promise<TResponse>;
659
+ /** PUT /test-patient-credentials/{credential_id} */
660
+ update<TResponse = TestPatientCredentialResponse>(credentialId: string, request: TestPatientCredentialUpdate): Promise<TResponse>;
661
+ /** DELETE /test-patient-credentials/{credential_id} */
662
+ delete<TResponse = undefined>(credentialId: string): Promise<TResponse>;
663
+ /**
664
+ * POST /test-patient-credentials/{credential_id}/login
665
+ *
666
+ * Logs this persona into Health Cloud and returns a real patient access
667
+ * token — feed `access_token`/`patient_id` into
668
+ * {@link "../wss/WssClient".WssClient} to open a chat session as this persona.
669
+ */
670
+ login<TResponse = TestPatientLoginResponse>(credentialId: string): Promise<TResponse>;
671
+ }
672
+
673
+ /**
674
+ * AuthClient — AMS's own Tenant Admin auth routes (`/api/auth/*`).
675
+ *
676
+ * AMS delegates identity verification to Health Cloud's Tenant Admin SDK on
677
+ * every request; this client just mirrors the thin proxy routes AMS exposes
678
+ * for that flow. It uses its own {@link HttpClient} resolved against
679
+ * `resolveAmsAuthBaseUrl` (see `SDKConfig.ts`), since `/api/auth/*` lives
680
+ * outside the `/api/ams` root every other client targets.
681
+ */
682
+ declare class AuthClient extends BaseServiceClient {
683
+ constructor(http: HttpClient);
684
+ /** POST /api/auth/login (public) */
685
+ login<TResponse = TokenResponse>(request: LoginRequest): Promise<TResponse>;
686
+ /** POST /api/auth/reset-password (public) */
687
+ resetPassword<TResponse = AuthMessageResponse>(request: PasswordResetRequest): Promise<TResponse>;
688
+ /** POST /api/auth/confirm-reset-password (public) */
689
+ confirmResetPassword<TResponse = AuthMessageResponse>(request: PasswordResetConfirmRequest): Promise<TResponse>;
690
+ /** POST /api/auth/register (public) */
691
+ register<TResponse = RegistrationResponse>(request: RegistrationRequest): Promise<TResponse>;
692
+ /** GET /api/auth/me (Bearer required) */
693
+ me<TResponse = AuthenticatedUser>(): Promise<TResponse>;
694
+ }
695
+
696
+ interface ChatFramePayload {
697
+ content: string;
698
+ image_base64?: string;
699
+ image_mime?: string;
700
+ suggestion_id?: string;
701
+ }
702
+ interface VoiceFramePayload {
703
+ active: boolean;
704
+ }
705
+ interface AudioInputFramePayload {
706
+ audio_b64: string;
707
+ mime?: string;
708
+ }
709
+ interface ToolConfirmationFramePayload {
710
+ confirmation_id: string;
711
+ confirmed: boolean;
712
+ }
713
+ interface HandoffFramePayload {
714
+ messages: Array<{
715
+ role: "user" | "assistant";
716
+ content: string;
717
+ }>;
718
+ }
719
+ type OutgoingFrameType = "chat" | "voice" | "audio_input" | "tool_confirmation" | "handoff" | "pong";
720
+ interface WssEnvelopeFields {
721
+ timestamp: string;
722
+ event_seq: number;
723
+ turn_id?: number;
724
+ }
725
+ interface ChatEvent extends WssEnvelopeFields {
726
+ content: string;
727
+ is_final: boolean;
728
+ replace?: boolean;
729
+ }
730
+ interface VoiceTranscriptEvent extends WssEnvelopeFields {
731
+ content: string;
732
+ }
733
+ interface HistoryEvent extends WssEnvelopeFields {
734
+ messages: Array<{
735
+ role: "user" | "assistant";
736
+ content: string;
737
+ }>;
738
+ }
739
+ interface EventReplayEvent extends WssEnvelopeFields {
740
+ events: Array<{
741
+ type: string;
742
+ payload: unknown;
743
+ }>;
744
+ complete: true;
745
+ }
746
+ interface ErrorEvent extends WssEnvelopeFields {
747
+ message: string;
748
+ code?: string;
749
+ }
750
+ interface PingEvent extends WssEnvelopeFields {
751
+ ts: number;
752
+ }
753
+ interface ActivityEvent extends WssEnvelopeFields {
754
+ label: string;
755
+ kind: "tool" | "thinking";
756
+ name?: string;
757
+ status?: "started" | "completed" | "failed" | "cancelled";
758
+ available?: boolean;
759
+ }
760
+ type TransferEvent = WssEnvelopeFields & ({
761
+ mode: "to_orchestrator";
762
+ from_agent_id: string;
763
+ to_agent_id: string;
764
+ agent_name: string;
765
+ task_name: string;
766
+ task_summary: string;
767
+ next_steps: string;
768
+ message: string;
769
+ } | {
770
+ mode: "agent_switched";
771
+ from_agent_id: string;
772
+ to_agent_id: string;
773
+ agent_name: string;
774
+ message: string;
775
+ });
776
+ interface ArtifactBlockEvent extends WssEnvelopeFields {
777
+ kind: string;
778
+ title: string;
779
+ content: string;
780
+ data?: Record<string, unknown>;
781
+ }
782
+ interface NotificationEvent extends WssEnvelopeFields {
783
+ title: string;
784
+ message: string;
785
+ level: "info" | "success" | "warning" | "error";
786
+ type: string;
787
+ }
788
+ interface ResponseSuggestionsEvent extends WssEnvelopeFields {
789
+ mode: "single" | "multi";
790
+ options: unknown[];
791
+ }
792
+ interface TurnStartedEvent extends WssEnvelopeFields {
793
+ turn_id: number;
794
+ }
795
+ interface TurnCompletedEvent extends WssEnvelopeFields {
796
+ turn_id: number;
797
+ blocked?: boolean;
798
+ }
799
+ interface TurnFailedEvent extends WssEnvelopeFields {
800
+ turn_id: number;
801
+ }
802
+ interface TurnCancelledEvent extends WssEnvelopeFields {
803
+ turn_id: number;
804
+ }
805
+ interface AudioChunkEvent extends WssEnvelopeFields {
806
+ seq: number;
807
+ audio_base64: string;
808
+ mime: string;
809
+ text: string;
810
+ is_last: boolean;
811
+ }
812
+ interface VadEvent extends WssEnvelopeFields {
813
+ speaking: boolean;
814
+ }
815
+ interface ToolResultEvent extends WssEnvelopeFields {
816
+ confirmation_id: string;
817
+ tool: string;
818
+ result: unknown;
819
+ }
820
+ /** Discriminated map of every known server → client event `type` string. */
821
+ interface WssEventMap {
822
+ chat: ChatEvent;
823
+ voice_transcript: VoiceTranscriptEvent;
824
+ history: HistoryEvent;
825
+ event_replay: EventReplayEvent;
826
+ error: ErrorEvent;
827
+ ping: PingEvent;
828
+ activity: ActivityEvent;
829
+ transfer: TransferEvent;
830
+ artifact_block: ArtifactBlockEvent;
831
+ notification: NotificationEvent;
832
+ response_suggestions: ResponseSuggestionsEvent;
833
+ turn_started: TurnStartedEvent;
834
+ turn_completed: TurnCompletedEvent;
835
+ turn_failed: TurnFailedEvent;
836
+ turn_cancelled: TurnCancelledEvent;
837
+ audio_chunk: AudioChunkEvent;
838
+ vad: VadEvent;
839
+ tool_result: ToolResultEvent;
840
+ }
841
+ type WssEventType = keyof WssEventMap;
842
+ /** Raw wire envelope for any server → client frame. */
843
+ interface WssServerFrame<T = unknown> {
844
+ type: string;
845
+ payload: T & WssEnvelopeFields;
846
+ }
847
+ /** Result of {@link "./WssClient".WssClient.sendAndAwaitTurn}. */
848
+ interface TurnResult {
849
+ message: string;
850
+ activity: ActivityEvent[];
851
+ transfers: TransferEvent[];
852
+ artifacts: ArtifactBlockEvent[];
853
+ notifications: NotificationEvent[];
854
+ suggestions?: ResponseSuggestionsEvent;
855
+ turnId?: number;
856
+ status: "completed" | "failed" | "cancelled";
857
+ }
858
+
859
+ /**
860
+ * Minimal structural subset of the DOM/`ws` `WebSocket` API this client
861
+ * relies on — lets callers inject any compatible implementation (e.g. the
862
+ * `ws` package on Node &lt; 21, where no global `WebSocket` exists).
863
+ */
864
+ interface WebSocketLikeEvent {
865
+ code?: number;
866
+ reason?: string;
867
+ data?: string;
868
+ }
869
+ interface WebSocketLike {
870
+ readonly readyState: number;
871
+ send(data: string): void;
872
+ close(code?: number, reason?: string): void;
873
+ addEventListener(type: "open" | "message" | "close" | "error", listener: (event: WebSocketLikeEvent) => void): void;
874
+ removeEventListener(type: "open" | "message" | "close" | "error", listener: (event: WebSocketLikeEvent) => void): void;
875
+ }
876
+ type WebSocketImpl = new (url: string) => WebSocketLike;
877
+ interface WssClientOptions {
878
+ environment: Environment;
879
+ tenantId: string;
880
+ patientId: string;
881
+ /**
882
+ * Health Cloud patient access token. Sent as the `token` field of the
883
+ * first WS frame (`{"type":"auth","token":"..."}`) immediately after the
884
+ * socket opens — never as part of the connect URL, a header, or a WS
885
+ * subprotocol entry, all of which a gateway/proxy/APM tool between the
886
+ * client and AMS commonly logs in full. `connect()` does not resolve
887
+ * until the server responds with `{"type":"auth_ok"}`; no other frame is
888
+ * sent or processed before that.
889
+ *
890
+ * Pass a plain string for a single connection, or {@link getAccessToken}
891
+ * to have the token resolved fresh on every `connect()` call (recommended
892
+ * whenever you reconnect the same logical session, so a refreshed token
893
+ * is sent instead of a captured, possibly-expired one). Exactly one of
894
+ * the two must be provided.
895
+ */
896
+ healthcloudToken?: string;
897
+ /**
898
+ * Resolves the access token fresh on every `connect()` call, including
899
+ * reconnects — wire this to the SDK's existing auth/refresh flow (or any
900
+ * token provider). Takes precedence over {@link healthcloudToken} when
901
+ * both are given.
902
+ */
903
+ getAccessToken?: () => string | Promise<string>;
904
+ /** Omit to connect via the tenant's default agent (`/ws`). */
905
+ agentId?: string;
906
+ /** Overrides the resolved WSS base URL (scheme + host, no path). */
907
+ baseUrlOverride?: string;
908
+ /** Defaults to `globalThis.WebSocket`. Required on Node &lt; 21. */
909
+ WebSocketImpl?: WebSocketImpl;
910
+ /** Default timeout (ms) for {@link WssClient.sendAndAwaitTurn}. Defaults to 60000. */
911
+ turnTimeoutMs?: number;
912
+ /** Timeout (ms) waiting for the server's `auth_ok` after the socket opens and the auth frame is sent. Defaults to 10000, matching the AMS server's own `WS_AUTH_TIMEOUT_SECONDS`. */
913
+ authTimeoutMs?: number;
914
+ /** Greeting language (server defaults to `"en"`). */
915
+ lang?: string;
916
+ /**
917
+ * Carries a prior, unauthenticated conversation's transcript into this
918
+ * (usually now-authenticated) connection, so the greeting can acknowledge
919
+ * it instead of it just silently appearing in history — e.g. a patient
920
+ * chatting with a public, `requires_auth: false` pre-login agent, who
921
+ * then logs in and reconnects to the real orchestrator. Sent once, as
922
+ * part of the connect URL (`?handoff=`), not as a post-open frame — the
923
+ * server reads it before generating the first greeting.
924
+ */
925
+ handoff?: HandoffFramePayload["messages"];
926
+ /** Starts the session in voice mode (server default: off). */
927
+ voice?: boolean;
928
+ /** Preferred TTS voice ID for the connect-time greeting and voice-mode replies, if voice streaming is enabled for this agent. */
929
+ voiceId?: string;
930
+ /** Audio format for voice replies (server default: `"mp3"`). */
931
+ audioFormat?: string;
932
+ /** Resume support: replays non-audio runtime events with `event_seq` greater than this value after reconnect. */
933
+ replaySince?: number;
934
+ }
935
+ type Listener<K extends WssEventType> = (payload: WssEventMap[K]) => void;
936
+ /**
937
+ * WssClient — a single WebSocket connection to AMS's agent-chat runtime
938
+ * (`/ws` or `/ws/agents/{agent_id}/chat`). The entire multi-agent
939
+ * conversation (orchestrator + any number of downstream specialists) lives
940
+ * on this one connection; agent switches arrive as `transfer` events, not
941
+ * reconnects.
942
+ */
943
+ declare class WssClient {
944
+ private readonly options;
945
+ private socket;
946
+ private authenticated;
947
+ private readonly listeners;
948
+ private readonly url;
949
+ private readonly WebSocketCtor;
950
+ private readonly turnTimeoutMs;
951
+ private readonly authTimeoutMs;
952
+ constructor(options: WssClientOptions);
953
+ private resolveToken;
954
+ /**
955
+ * Opens the socket and runs the auth handshake: sends
956
+ * `{"type":"auth","token":...}` as soon as the socket opens, and resolves
957
+ * only once the server replies `{"type":"auth_ok"}`. Rejects on a
958
+ * connect/auth error, an auth timeout, or a rejection frame — in every
959
+ * case before any chat frame can be sent (see {@link send}).
960
+ */
961
+ connect(): Promise<void>;
962
+ /** Subscribes to a typed server event. Returns an unsubscribe function. */
963
+ on<K extends WssEventType>(type: K, handler: Listener<K>): () => void;
964
+ /** Sends a raw outgoing frame: `{"type": type, "payload": payload}`. */
965
+ send(type: OutgoingFrameType | string, payload?: Record<string, unknown>): void;
966
+ sendChat(payload: ChatFramePayload): void;
967
+ sendVoice(active: boolean): void;
968
+ sendAudioInput(payload: AudioInputFramePayload): void;
969
+ sendToolConfirmation(payload: ToolConfirmationFramePayload): void;
970
+ sendHandoff(messages: HandoffFramePayload["messages"]): void;
971
+ /**
972
+ * Sends a `chat` frame and resolves once that turn completes, buffering
973
+ * every streamed `chat` delta into the final `message` and collecting
974
+ * `activity`/`transfer`/`artifact_block`/`notification`/`response_suggestions`
975
+ * events emitted during the turn.
976
+ *
977
+ * Resolves with `status: "failed"`/`"cancelled"` (rather than rejecting)
978
+ * on `turn_failed`/`turn_cancelled`, so callers can inspect whatever
979
+ * partial `message`/side-effects were collected before the turn ended.
980
+ * Rejects only if no terminal event arrives within `timeoutMs`.
981
+ */
982
+ sendAndAwaitTurn(content: string, opts?: Partial<Omit<ChatFramePayload, "content">> & {
983
+ timeoutMs?: number;
984
+ }): Promise<TurnResult>;
985
+ /** Closes the socket and clears all listeners. */
986
+ close(code?: number, reason?: string): void;
987
+ private dispatch;
988
+ }
989
+
95
990
  declare class HCAmsSDK {
96
991
  private readonly state;
97
992
  private readonly http;
98
- /** AMS application-agent discovery. */
993
+ private readonly authHttp;
994
+ /** AMS application-agent discovery (public). */
99
995
  readonly ams: AmsClient;
996
+ /** Agent CRUD, transfer candidates, conversation history. */
997
+ readonly agents: AgentsClient;
998
+ /** Department CRUD. */
999
+ readonly departments: DepartmentsClient;
1000
+ /** Team CRUD. */
1001
+ readonly teams: TeamsClient;
1002
+ /** Skill CRUD. */
1003
+ readonly skills: SkillsClient;
1004
+ /** Policy CRUD. */
1005
+ readonly policies: PoliciesClient;
1006
+ /** Guardrail CRUD. */
1007
+ readonly guardrails: GuardrailsClient;
1008
+ /** Data source catalog (read-only). */
1009
+ readonly dataSources: DataSourcesClient;
1010
+ /** Tool catalog (read-only). */
1011
+ readonly tools: ToolsClient;
1012
+ /** Synthetic QA patient persona CRUD + login. */
1013
+ readonly testPersonas: TestPersonasClient;
1014
+ /** AMS's own Tenant Admin auth routes (`/api/auth/*`). */
1015
+ readonly auth: AuthClient;
100
1016
  constructor(config: AmsSDKConfig);
1017
+ /**
1018
+ * Opens a WebSocket agent-chat session using this SDK's configured
1019
+ * environment (and `tenantId`, if set and not overridden here). See
1020
+ * {@link WssClient} for the full API (typed event subscription,
1021
+ * `sendAndAwaitTurn`, etc).
1022
+ */
1023
+ connectAgentChat(options: Omit<WssClientOptions, "environment" | "tenantId"> & {
1024
+ tenantId?: string;
1025
+ }): WssClient;
101
1026
  /** Get the current runtime environment. */
102
1027
  get environment(): string;
103
1028
  /** Get the configured tenant ID. */
@@ -121,4 +1046,4 @@ declare class SDKError extends Error {
121
1046
  toString(): string;
122
1047
  }
123
1048
 
124
- export { type AmsApplicationAgentsResponse, AmsClient, type AmsSDKConfig, type AmsServiceName, DEFAULT_TIMEOUT_MS, type Environment, HCAmsSDK, type HttpMethod, type HttpRequestBody, type HttpRequestOptions, type JsonObject, type JsonPrimitive, type JsonValue, type QueryParamPrimitive, type QueryParamValue, type QueryParams, SDKError, type SDKRuntimeState, SERVICE_NAME, assertEnvironment, assertTimeout, resolveBaseUrl };
1049
+ export { type AIAgent, type AIAgentCreate, type AIAgentUpdate, type AIDataSource, type AIGuardrail, type AIGuardrailCreate, type AIGuardrailUpdate, type AISkill, type AISkillCreate, type AISkillUpdate, type AITool, type ActivityEvent, type AgentMode, type AgentPreferredModel, type AgentStatus, type AgentTTSModel, type AgentType, AgentsClient, type AmsApplicationAgentsResponse, type AmsAuditableFields, AmsClient, type AmsSDKConfig, type AmsServiceName, type ArtifactBlockEvent, type AudioChunkEvent, type AudioInputFramePayload, AuthClient, type AuthMessageResponse, type AuthenticatedUser, type ChatEvent, type ChatFramePayload, type ConversationHistory, type ConversationHistoryEntry, DEFAULT_TIMEOUT_MS, DataSourcesClient, type Department, type DepartmentCreate, type DepartmentTeamEvaluation, type DepartmentUpdate, DepartmentsClient, type Environment, type ErrorEvent, type EventReplayEvent, GuardrailsClient, HCAmsSDK, type HandoffFramePayload, type HistoryEvent, type HttpMethod, type HttpRequestBody, type HttpRequestOptions, type JsonObject, type JsonPrimitive, type JsonValue, type LoginRequest, type NotificationEvent, type OutgoingFrameType, type PasswordResetConfirmRequest, type PasswordResetRequest, type PingEvent, PoliciesClient, type Policy, type PolicyCreate, type PolicyUpdate, type QueryParamPrimitive, type QueryParamValue, type QueryParams, type RegistrationRequest, type RegistrationResponse, type ResponseSuggestionsEvent, SDKError, type SDKRuntimeState, SERVICE_NAME, SkillsClient, type Team, type TeamCreate, type TeamUpdate, TeamsClient, type TestPatientCredentialCreate, type TestPatientCredentialEnvironment, type TestPatientCredentialResponse, type TestPatientCredentialUpdate, type TestPatientLoginResponse, TestPersonasClient, type TokenResponse, type ToolConfirmationFramePayload, type ToolResultEvent, ToolsClient, type TransferCandidate, type TransferEvent, type TurnCancelledEvent, type TurnCompletedEvent, type TurnFailedEvent, type TurnResult, type TurnStartedEvent, type VadEvent, type VoiceFramePayload, type VoiceTranscriptEvent, type WebSocketImpl, type WebSocketLike, WssClient, type WssClientOptions, type WssEnvelopeFields, type WssEventMap, type WssEventType, type WssServerFrame, assertEnvironment, assertTimeout, resolveAmsAuthBaseUrl, resolveBaseUrl, resolveWssBaseUrl };