@healthcloudai/hc-ams 3.8.0 → 3.9.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
@@ -23,6 +23,44 @@ const agents = await sdk.ams.getAgentsForTenant("<TENANT_ID>");
23
23
 
24
24
  ## Authentication
25
25
 
26
+ ### Native or custom HTTP transport
27
+
28
+ `HCAmsSDK` accepts an optional `fetch` adapter per instance. API, native V2 HTTP
29
+ and tenant-admin auth calls use that adapter; other SDK instances and global
30
+ fetch are unaffected. Without an adapter, the SDK uses global fetch at request
31
+ time as before. WebSocket construction remains the separate `WebSocketImpl` option.
32
+
33
+ An adapter accepts a resolved URL string and `RequestInit`, returning a standard
34
+ `Response`. It is a trusted transport: it must honor `AbortSignal` during headers
35
+ and body reads, and `redirect: "error"` before following redirects. The SDK also
36
+ rejects returned redirects, but that check cannot undo authority already sent by
37
+ an adapter that ignored redirect mode. Adapter errors never cause fallback or
38
+ automatic retries. Retain original V2 binding terms after uncertain outcomes.
39
+
40
+ For later Expo native host integration, use a named implementation rather than
41
+ replacing global networking:
42
+
43
+ ```ts
44
+ import { fetch as expoFetch } from "expo/fetch";
45
+ import { HCAmsSDK, type AmsFetch } from "@healthcloudai/hc-ams";
46
+
47
+ const nativeFetch: AmsFetch = (url, init) => expoFetch(url, {
48
+ method: init.method,
49
+ headers: init.headers,
50
+ body: init.body ?? undefined,
51
+ signal: init.signal ?? undefined,
52
+ redirect: "error",
53
+ credentials: "omit",
54
+ });
55
+ const sdk = new HCAmsSDK({ environment: "dev", fetch: nativeFetch });
56
+ ```
57
+
58
+ This hook alone does not qualify native Patient chat. The host still owns its
59
+ reviewed V2 endpoint, native HTTP/WSS Origin, ordinary Patient identity, UUID
60
+ generation, rendering, lifecycle and actual iOS/Android verification.
61
+
62
+ ### Patient and admin authority
63
+
26
64
  `ams.getAgentsForTenant` and native V2's `v2.listPublicAgents` / `v2.createRun`
27
65
  are public and require no access token. V2 public admission also requires an
28
66
  allowed browser Origin configured by the server.
@@ -357,3 +395,28 @@ is fixed. Callers intentionally overriding authentication must now explicitly
357
395
  set `authBaseUrlOverride`; selecting another API server leaves the environment's
358
396
  auth target unchanged. An API override now also selects the WebSocket origin
359
397
  unless an SDK/per-chat WS override is provided. UAT/PROD defaults are unchanged.
398
+
399
+ ### Reception-only V2 connections
400
+
401
+ Use `capabilities: { read_only: true, supported_actions: [] }` for an owned-run
402
+ connection that only receives history/events and responds to keepalive pings.
403
+ This is reception only: `sendChat`, `bindPatient`, `sendActionResult` and explicit
404
+ `sendCommand` retries reject before sending. Omitted or `false` preserves ordinary
405
+ command behavior. The capability is copied when the client is constructed.
406
+
407
+ ```ts
408
+ const receiver = sdk.connectV2AgentChat({
409
+ agentId, run, identity,
410
+ capabilities: { platform: "web", read_only: true, supported_actions: [] },
411
+ WebSocketImpl,
412
+ });
413
+ receiver.on("history", renderHistory);
414
+ await receiver.connect();
415
+ // Reconnect this same instance after closing; no new run is created implicitly.
416
+ ```
417
+
418
+ Tenant, Patient-token and owned-run claim authorization remain enforced by the
419
+ server. Ordinary app sign-in still uses the separate Patient HTTP binding API
420
+ after closing the socket and observing its actual closure. Reception-only support
421
+ does not establish Patient chat/action parity, deployed Origin acceptance or a
422
+ registry release; verify the installed published version before using this option.
package/dist/index.cjs CHANGED
@@ -193,7 +193,8 @@ var HttpClient = class {
193
193
  let response;
194
194
  let payload;
195
195
  try {
196
- response = await fetch(url, init);
196
+ const adapter = this.state.fetch;
197
+ response = adapter ? await adapter(url, init) : await globalThis.fetch(url, init);
197
198
  if (response.redirected || response.status >= 300 && response.status < 400 || response.type === "opaqueredirect") {
198
199
  throw new SDKError({ message: "Service redirects are not allowed", statusCode: response.status });
199
200
  }
@@ -1044,6 +1045,7 @@ function capabilities(value) {
1044
1045
  if (!record(value) || !onlyKeys(value, [
1045
1046
  "platform",
1046
1047
  "supported_actions",
1048
+ "read_only",
1047
1049
  "patient_flags_confirmation",
1048
1050
  "intake_confirmation",
1049
1051
  "encounter_confirmation",
@@ -1052,7 +1054,7 @@ function capabilities(value) {
1052
1054
  ])) return false;
1053
1055
  if (value.platform !== void 0 && !["web", "ios", "android", "terminal", "unknown"].includes(value.platform)) return false;
1054
1056
  if (value.supported_actions !== void 0 && (!Array.isArray(value.supported_actions) || value.supported_actions.length > 16 || !value.supported_actions.every((action) => ["confirm", "insurance_scan", "vitals_import", "slot_picker", "login", "symptom_save", "telehealth_join"].includes(action)))) return false;
1055
- for (const key of ["patient_flags_confirmation", "intake_confirmation", "encounter_confirmation"]) {
1057
+ for (const key of ["read_only", "patient_flags_confirmation", "intake_confirmation", "encounter_confirmation"]) {
1056
1058
  if (value[key] !== void 0 && typeof value[key] !== "boolean") return false;
1057
1059
  }
1058
1060
  return ["locale", "time_zone"].every((key) => value[key] === void 0 || typeof value[key] === "string" && value[key].length > 0 && value[key].length <= 128);
@@ -1367,8 +1369,11 @@ var NativeV2WssClient = class {
1367
1369
  }
1368
1370
  /** Explicit retries resend the caller's original command identity and terms. */
1369
1371
  sendCommand(command) {
1370
- var _a, _b, _c, _d, _e, _f;
1372
+ var _a, _b, _c, _d, _e, _f, _g;
1371
1373
  __privateMethod(this, _NativeV2WssClient_instances, requireConnected_fn).call(this);
1374
+ if (((_a = __privateGet(this, _options).capabilities) == null ? void 0 : _a.read_only) === true) {
1375
+ throw invalid("Read-only V2 connections cannot send commands.");
1376
+ }
1372
1377
  if (!record(command) || !onlyKeys(command, ["type", "payload"]) || !record(command.payload)) {
1373
1378
  throw invalid("Invalid V2 command.");
1374
1379
  }
@@ -1385,15 +1390,15 @@ var NativeV2WssClient = class {
1385
1390
  if (__privateGet(this, _options).run.protocol !== "dbos_signin_cta_v1" || payload.previous_turn_id === null || !record(choice) || !onlyKeys(choice, ["offer_id", "action", "option_id"]) || typeof choice.offer_id !== "string" || !/^[0-9a-f]{32}$/.test(choice.offer_id) || typeof choice.action !== "string" || !/^[a-z0-9_-]{1,128}$/.test(choice.action) || ![`${choice.offer_id}:yes`, `${choice.offer_id}:no`].includes(choice.option_id)) throw invalid("Invalid V2 CTA confirmation.");
1386
1391
  }
1387
1392
  } else if (command.type === "bind_patient") {
1388
- if (!((_b = (_a = __privateGet(this, _options).capabilities) == null ? void 0 : _a.supported_actions) == null ? void 0 : _b.includes("login"))) throw invalid("V2 login was not advertised.");
1393
+ if (!((_c = (_b = __privateGet(this, _options).capabilities) == null ? void 0 : _b.supported_actions) == null ? void 0 : _c.includes("login"))) throw invalid("V2 login was not advertised.");
1389
1394
  if (!onlyKeys(payload, ["action_id", "tenant_id", "patient_id", "token", "run_secret", "identity_proof", "turn_id", "previous_turn_id"]) || !uuid(payload.action_id) || payload.previous_turn_id === null || payload.tenant_id !== __privateGet(this, _options).tenantId || !identity(payload.patient_id) || payload.run_secret !== __privateGet(this, _options).run.run_secret || typeof payload.token !== "string" || !payload.token || payload.token.length > 4096 || typeof payload.identity_proof !== "string" || !payload.identity_proof || payload.identity_proof.length > 2048) throw invalid("Invalid V2 binding command.");
1390
1395
  } else if (command.type === "action_result") {
1391
1396
  if (!onlyKeys(payload, ["action_id", "status", "data", "operation", "turn_id", "previous_turn_id"]) || !uuid(payload.action_id) || payload.previous_turn_id === null || !["completed", "cancelled", "failed"].includes(payload.status) || !record(payload.data)) throw invalid("Invalid V2 action command.");
1392
1397
  const data = payload.data;
1393
1398
  if ("proposal_id" in data) {
1394
- if (!((_d = (_c = __privateGet(this, _options).capabilities) == null ? void 0 : _c.supported_actions) == null ? void 0 : _d.includes("confirm"))) throw invalid("V2 confirmation was not advertised.");
1399
+ if (!((_e = (_d = __privateGet(this, _options).capabilities) == null ? void 0 : _d.supported_actions) == null ? void 0 : _e.includes("confirm"))) throw invalid("V2 confirmation was not advertised.");
1395
1400
  if (__privateGet(this, _options).run.protocol !== "dbos_signin_booking_v1" || !onlyKeys(data, ["proposal_id", "approved"]) || !uuid(data.proposal_id) || ![void 0, "confirm", "status"].includes(payload.operation) || (payload.operation === "status" ? payload.status !== "completed" || data.approved !== null : typeof data.approved !== "boolean" || payload.status !== "completed" && data.approved)) throw invalid("Invalid V2 booking result.");
1396
- } else if (!((_f = (_e = __privateGet(this, _options).capabilities) == null ? void 0 : _e.supported_actions) == null ? void 0 : _f.includes("slot_picker")) || !["dbos_signin_actions_v1", "dbos_signin_booking_v1", "dbos_signin_cta_v1"].includes(__privateGet(this, _options).run.protocol) || payload.operation !== void 0 || (payload.status === "completed" ? !onlyKeys(data, ["slot_id"]) || typeof data.slot_id !== "string" || !data.slot_id.length || data.slot_id.length > 256 : Object.keys(data).length > 0)) {
1401
+ } else if (!((_g = (_f = __privateGet(this, _options).capabilities) == null ? void 0 : _f.supported_actions) == null ? void 0 : _g.includes("slot_picker")) || !["dbos_signin_actions_v1", "dbos_signin_booking_v1", "dbos_signin_cta_v1"].includes(__privateGet(this, _options).run.protocol) || payload.operation !== void 0 || (payload.status === "completed" ? !onlyKeys(data, ["slot_id"]) || typeof data.slot_id !== "string" || !data.slot_id.length || data.slot_id.length > 256 : Object.keys(data).length > 0)) {
1397
1402
  throw invalid("Invalid V2 slot result.");
1398
1403
  }
1399
1404
  } else throw invalid("Unsupported V2 command.");
@@ -1481,6 +1486,10 @@ var HCAmsSDK = class {
1481
1486
  var _a, _b;
1482
1487
  assertEnvironment(config.environment);
1483
1488
  assertTimeout((_a = config.timeout) != null ? _a : DEFAULT_TIMEOUT_MS);
1489
+ const adapter = config.fetch;
1490
+ if (adapter !== void 0 && typeof adapter !== "function") {
1491
+ throw new Error("Invalid HealthCloud SDK fetch adapter: expected a function.");
1492
+ }
1484
1493
  const apiBase = normalizeBaseUrl(
1485
1494
  config.baseUrlOverride === void 0 ? resolveBaseUrl(config.environment) : config.baseUrlOverride
1486
1495
  );
@@ -1495,7 +1504,8 @@ var HCAmsSDK = class {
1495
1504
  tenantId: config.tenantId,
1496
1505
  accessToken: config.accessToken,
1497
1506
  baseUrlOverride: apiBase,
1498
- timeout: (_b = config.timeout) != null ? _b : DEFAULT_TIMEOUT_MS
1507
+ timeout: (_b = config.timeout) != null ? _b : DEFAULT_TIMEOUT_MS,
1508
+ fetch: adapter
1499
1509
  };
1500
1510
  this.http = new HttpClient(this.state);
1501
1511
  const state = this.state;
@@ -1517,6 +1527,9 @@ var HCAmsSDK = class {
1517
1527
  },
1518
1528
  get timeout() {
1519
1529
  return state.timeout;
1530
+ },
1531
+ get fetch() {
1532
+ return state.fetch;
1520
1533
  }
1521
1534
  };
1522
1535
  this.authHttp = new HttpClient(authState);
package/dist/index.d.cts CHANGED
@@ -1,3 +1,25 @@
1
+ type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
2
+ /** Per-instance HTTP transport. Honor AbortSignal and refuse redirects before following them. */
3
+ type AmsFetch = (url: string, init: RequestInit) => Promise<Response>;
4
+ type QueryParamPrimitive = string | number | boolean | null | undefined;
5
+ type QueryParamValue = QueryParamPrimitive | QueryParamPrimitive[];
6
+ type QueryParams = Record<string, QueryParamValue>;
7
+ type JsonPrimitive = string | number | boolean | null;
8
+ type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
9
+ interface JsonObject {
10
+ [key: string]: JsonValue;
11
+ }
12
+ type HttpRequestBody = JsonPrimitive | object | FormData | Blob | ArrayBuffer | URLSearchParams;
13
+ interface HttpRequestOptions {
14
+ pathParams?: Record<string, string | number>;
15
+ query?: QueryParams;
16
+ body?: HttpRequestBody;
17
+ headers?: Record<string, string>;
18
+ auth?: boolean;
19
+ /** Overrides the SDK-configured timeout for this request. */
20
+ timeoutMs?: number;
21
+ }
22
+
1
23
  type Environment = "dev" | "uat" | "prod";
2
24
  /** The AMS service name used for URL resolution. */
3
25
  declare const SERVICE_NAME: "ams";
@@ -14,6 +36,8 @@ interface AmsSDKConfig {
14
36
  wssBaseUrlOverride?: string;
15
37
  /** Request timeout in milliseconds. Defaults to 30000 (30s). */
16
38
  timeout?: number;
39
+ /** Optional HTTP implementation for this instance; never replaces global fetch. */
40
+ fetch?: AmsFetch;
17
41
  }
18
42
  interface SDKRuntimeState {
19
43
  environment: Environment;
@@ -21,6 +45,7 @@ interface SDKRuntimeState {
21
45
  accessToken?: string;
22
46
  baseUrlOverride?: string;
23
47
  timeout: number;
48
+ fetch?: AmsFetch;
24
49
  }
25
50
  declare const DEFAULT_TIMEOUT_MS = 30000;
26
51
  /**
@@ -45,26 +70,6 @@ declare function resolveWssBaseUrl(environment: Environment): string;
45
70
  declare function assertEnvironment(environment: Environment): void;
46
71
  declare function assertTimeout(timeout: number, label?: string): void;
47
72
 
48
- type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
49
- type QueryParamPrimitive = string | number | boolean | null | undefined;
50
- type QueryParamValue = QueryParamPrimitive | QueryParamPrimitive[];
51
- type QueryParams = Record<string, QueryParamValue>;
52
- type JsonPrimitive = string | number | boolean | null;
53
- type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
54
- interface JsonObject {
55
- [key: string]: JsonValue;
56
- }
57
- type HttpRequestBody = JsonPrimitive | object | FormData | Blob | ArrayBuffer | URLSearchParams;
58
- interface HttpRequestOptions {
59
- pathParams?: Record<string, string | number>;
60
- query?: QueryParams;
61
- body?: HttpRequestBody;
62
- headers?: Record<string, string>;
63
- auth?: boolean;
64
- /** Overrides the SDK-configured timeout for this request. */
65
- timeoutMs?: number;
66
- }
67
-
68
73
  declare class HttpClient {
69
74
  private readonly state;
70
75
  private readonly baseUrl;
@@ -1024,6 +1029,8 @@ interface V2PatientBindingResult {
1024
1029
  last_turn_id: string | null;
1025
1030
  }
1026
1031
  interface V2ClientCapabilities {
1032
+ /** Reception only: permits admission without action handlers; sends no commands. */
1033
+ read_only?: boolean;
1027
1034
  platform?: "web" | "ios" | "android" | "terminal" | "unknown";
1028
1035
  supported_actions?: Array<"confirm" | "insurance_scan" | "vitals_import" | "slot_picker" | "login" | "symptom_save" | "telehealth_join">;
1029
1036
  patient_flags_confirmation?: boolean;
@@ -1366,4 +1373,4 @@ declare class SDKError extends Error {
1366
1373
  toString(): string;
1367
1374
  }
1368
1375
 
1369
- 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, NativeV2Client, NativeV2WssClient, type NativeV2WssClientOptions, 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 V2Action, type V2ActionResult, type V2AdmissionOptions, type V2AuthOk, type V2BindPayload, type V2BookingAction, type V2BookingOutcome, type V2BookingResult, type V2CTAConfirmation, type V2ChatPayload, type V2ClientCapabilities, type V2Command, type V2Envelope, type V2EventMap, type V2EventType, type V2HistoryMessage, type V2Identity, type V2LoginAction, type V2OwnedRun, type V2PatientBindingOptions, type V2PatientBindingRequest, type V2PatientBindingResult, type V2Protocol, type V2PublicAgent, type V2PublicAgents, type V2ReplayFrame, type V2SignInOutcome, type V2SlotAction, type V2SlotResult, type V2Suggestions, type VadEvent, type VoiceFramePayload, type VoiceTranscriptEvent, type WebSocketImpl, type WebSocketLike, WssClient, type WssClientOptions, type WssEnvelopeFields, type WssEventMap, type WssEventType, type WssServerFrame, assertEnvironment, assertTimeout, resolveAmsAuthBaseUrl, resolveAmsOrigin, resolveBaseUrl, resolveWssBaseUrl };
1376
+ 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 AmsFetch, 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, NativeV2Client, NativeV2WssClient, type NativeV2WssClientOptions, 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 V2Action, type V2ActionResult, type V2AdmissionOptions, type V2AuthOk, type V2BindPayload, type V2BookingAction, type V2BookingOutcome, type V2BookingResult, type V2CTAConfirmation, type V2ChatPayload, type V2ClientCapabilities, type V2Command, type V2Envelope, type V2EventMap, type V2EventType, type V2HistoryMessage, type V2Identity, type V2LoginAction, type V2OwnedRun, type V2PatientBindingOptions, type V2PatientBindingRequest, type V2PatientBindingResult, type V2Protocol, type V2PublicAgent, type V2PublicAgents, type V2ReplayFrame, type V2SignInOutcome, type V2SlotAction, type V2SlotResult, type V2Suggestions, type VadEvent, type VoiceFramePayload, type VoiceTranscriptEvent, type WebSocketImpl, type WebSocketLike, WssClient, type WssClientOptions, type WssEnvelopeFields, type WssEventMap, type WssEventType, type WssServerFrame, assertEnvironment, assertTimeout, resolveAmsAuthBaseUrl, resolveAmsOrigin, resolveBaseUrl, resolveWssBaseUrl };
package/dist/index.d.ts CHANGED
@@ -1,3 +1,25 @@
1
+ type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
2
+ /** Per-instance HTTP transport. Honor AbortSignal and refuse redirects before following them. */
3
+ type AmsFetch = (url: string, init: RequestInit) => Promise<Response>;
4
+ type QueryParamPrimitive = string | number | boolean | null | undefined;
5
+ type QueryParamValue = QueryParamPrimitive | QueryParamPrimitive[];
6
+ type QueryParams = Record<string, QueryParamValue>;
7
+ type JsonPrimitive = string | number | boolean | null;
8
+ type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
9
+ interface JsonObject {
10
+ [key: string]: JsonValue;
11
+ }
12
+ type HttpRequestBody = JsonPrimitive | object | FormData | Blob | ArrayBuffer | URLSearchParams;
13
+ interface HttpRequestOptions {
14
+ pathParams?: Record<string, string | number>;
15
+ query?: QueryParams;
16
+ body?: HttpRequestBody;
17
+ headers?: Record<string, string>;
18
+ auth?: boolean;
19
+ /** Overrides the SDK-configured timeout for this request. */
20
+ timeoutMs?: number;
21
+ }
22
+
1
23
  type Environment = "dev" | "uat" | "prod";
2
24
  /** The AMS service name used for URL resolution. */
3
25
  declare const SERVICE_NAME: "ams";
@@ -14,6 +36,8 @@ interface AmsSDKConfig {
14
36
  wssBaseUrlOverride?: string;
15
37
  /** Request timeout in milliseconds. Defaults to 30000 (30s). */
16
38
  timeout?: number;
39
+ /** Optional HTTP implementation for this instance; never replaces global fetch. */
40
+ fetch?: AmsFetch;
17
41
  }
18
42
  interface SDKRuntimeState {
19
43
  environment: Environment;
@@ -21,6 +45,7 @@ interface SDKRuntimeState {
21
45
  accessToken?: string;
22
46
  baseUrlOverride?: string;
23
47
  timeout: number;
48
+ fetch?: AmsFetch;
24
49
  }
25
50
  declare const DEFAULT_TIMEOUT_MS = 30000;
26
51
  /**
@@ -45,26 +70,6 @@ declare function resolveWssBaseUrl(environment: Environment): string;
45
70
  declare function assertEnvironment(environment: Environment): void;
46
71
  declare function assertTimeout(timeout: number, label?: string): void;
47
72
 
48
- type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
49
- type QueryParamPrimitive = string | number | boolean | null | undefined;
50
- type QueryParamValue = QueryParamPrimitive | QueryParamPrimitive[];
51
- type QueryParams = Record<string, QueryParamValue>;
52
- type JsonPrimitive = string | number | boolean | null;
53
- type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
54
- interface JsonObject {
55
- [key: string]: JsonValue;
56
- }
57
- type HttpRequestBody = JsonPrimitive | object | FormData | Blob | ArrayBuffer | URLSearchParams;
58
- interface HttpRequestOptions {
59
- pathParams?: Record<string, string | number>;
60
- query?: QueryParams;
61
- body?: HttpRequestBody;
62
- headers?: Record<string, string>;
63
- auth?: boolean;
64
- /** Overrides the SDK-configured timeout for this request. */
65
- timeoutMs?: number;
66
- }
67
-
68
73
  declare class HttpClient {
69
74
  private readonly state;
70
75
  private readonly baseUrl;
@@ -1024,6 +1029,8 @@ interface V2PatientBindingResult {
1024
1029
  last_turn_id: string | null;
1025
1030
  }
1026
1031
  interface V2ClientCapabilities {
1032
+ /** Reception only: permits admission without action handlers; sends no commands. */
1033
+ read_only?: boolean;
1027
1034
  platform?: "web" | "ios" | "android" | "terminal" | "unknown";
1028
1035
  supported_actions?: Array<"confirm" | "insurance_scan" | "vitals_import" | "slot_picker" | "login" | "symptom_save" | "telehealth_join">;
1029
1036
  patient_flags_confirmation?: boolean;
@@ -1366,4 +1373,4 @@ declare class SDKError extends Error {
1366
1373
  toString(): string;
1367
1374
  }
1368
1375
 
1369
- 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, NativeV2Client, NativeV2WssClient, type NativeV2WssClientOptions, 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 V2Action, type V2ActionResult, type V2AdmissionOptions, type V2AuthOk, type V2BindPayload, type V2BookingAction, type V2BookingOutcome, type V2BookingResult, type V2CTAConfirmation, type V2ChatPayload, type V2ClientCapabilities, type V2Command, type V2Envelope, type V2EventMap, type V2EventType, type V2HistoryMessage, type V2Identity, type V2LoginAction, type V2OwnedRun, type V2PatientBindingOptions, type V2PatientBindingRequest, type V2PatientBindingResult, type V2Protocol, type V2PublicAgent, type V2PublicAgents, type V2ReplayFrame, type V2SignInOutcome, type V2SlotAction, type V2SlotResult, type V2Suggestions, type VadEvent, type VoiceFramePayload, type VoiceTranscriptEvent, type WebSocketImpl, type WebSocketLike, WssClient, type WssClientOptions, type WssEnvelopeFields, type WssEventMap, type WssEventType, type WssServerFrame, assertEnvironment, assertTimeout, resolveAmsAuthBaseUrl, resolveAmsOrigin, resolveBaseUrl, resolveWssBaseUrl };
1376
+ 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 AmsFetch, 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, NativeV2Client, NativeV2WssClient, type NativeV2WssClientOptions, 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 V2Action, type V2ActionResult, type V2AdmissionOptions, type V2AuthOk, type V2BindPayload, type V2BookingAction, type V2BookingOutcome, type V2BookingResult, type V2CTAConfirmation, type V2ChatPayload, type V2ClientCapabilities, type V2Command, type V2Envelope, type V2EventMap, type V2EventType, type V2HistoryMessage, type V2Identity, type V2LoginAction, type V2OwnedRun, type V2PatientBindingOptions, type V2PatientBindingRequest, type V2PatientBindingResult, type V2Protocol, type V2PublicAgent, type V2PublicAgents, type V2ReplayFrame, type V2SignInOutcome, type V2SlotAction, type V2SlotResult, type V2Suggestions, type VadEvent, type VoiceFramePayload, type VoiceTranscriptEvent, type WebSocketImpl, type WebSocketLike, WssClient, type WssClientOptions, type WssEnvelopeFields, type WssEventMap, type WssEventType, type WssServerFrame, assertEnvironment, assertTimeout, resolveAmsAuthBaseUrl, resolveAmsOrigin, resolveBaseUrl, resolveWssBaseUrl };
package/dist/index.js CHANGED
@@ -145,7 +145,8 @@ var HttpClient = class {
145
145
  let response;
146
146
  let payload;
147
147
  try {
148
- response = await fetch(url, init);
148
+ const adapter = this.state.fetch;
149
+ response = adapter ? await adapter(url, init) : await globalThis.fetch(url, init);
149
150
  if (response.redirected || response.status >= 300 && response.status < 400 || response.type === "opaqueredirect") {
150
151
  throw new SDKError({ message: "Service redirects are not allowed", statusCode: response.status });
151
152
  }
@@ -996,6 +997,7 @@ function capabilities(value) {
996
997
  if (!record(value) || !onlyKeys(value, [
997
998
  "platform",
998
999
  "supported_actions",
1000
+ "read_only",
999
1001
  "patient_flags_confirmation",
1000
1002
  "intake_confirmation",
1001
1003
  "encounter_confirmation",
@@ -1004,7 +1006,7 @@ function capabilities(value) {
1004
1006
  ])) return false;
1005
1007
  if (value.platform !== void 0 && !["web", "ios", "android", "terminal", "unknown"].includes(value.platform)) return false;
1006
1008
  if (value.supported_actions !== void 0 && (!Array.isArray(value.supported_actions) || value.supported_actions.length > 16 || !value.supported_actions.every((action) => ["confirm", "insurance_scan", "vitals_import", "slot_picker", "login", "symptom_save", "telehealth_join"].includes(action)))) return false;
1007
- for (const key of ["patient_flags_confirmation", "intake_confirmation", "encounter_confirmation"]) {
1009
+ for (const key of ["read_only", "patient_flags_confirmation", "intake_confirmation", "encounter_confirmation"]) {
1008
1010
  if (value[key] !== void 0 && typeof value[key] !== "boolean") return false;
1009
1011
  }
1010
1012
  return ["locale", "time_zone"].every((key) => value[key] === void 0 || typeof value[key] === "string" && value[key].length > 0 && value[key].length <= 128);
@@ -1319,8 +1321,11 @@ var NativeV2WssClient = class {
1319
1321
  }
1320
1322
  /** Explicit retries resend the caller's original command identity and terms. */
1321
1323
  sendCommand(command) {
1322
- var _a, _b, _c, _d, _e, _f;
1324
+ var _a, _b, _c, _d, _e, _f, _g;
1323
1325
  __privateMethod(this, _NativeV2WssClient_instances, requireConnected_fn).call(this);
1326
+ if (((_a = __privateGet(this, _options).capabilities) == null ? void 0 : _a.read_only) === true) {
1327
+ throw invalid("Read-only V2 connections cannot send commands.");
1328
+ }
1324
1329
  if (!record(command) || !onlyKeys(command, ["type", "payload"]) || !record(command.payload)) {
1325
1330
  throw invalid("Invalid V2 command.");
1326
1331
  }
@@ -1337,15 +1342,15 @@ var NativeV2WssClient = class {
1337
1342
  if (__privateGet(this, _options).run.protocol !== "dbos_signin_cta_v1" || payload.previous_turn_id === null || !record(choice) || !onlyKeys(choice, ["offer_id", "action", "option_id"]) || typeof choice.offer_id !== "string" || !/^[0-9a-f]{32}$/.test(choice.offer_id) || typeof choice.action !== "string" || !/^[a-z0-9_-]{1,128}$/.test(choice.action) || ![`${choice.offer_id}:yes`, `${choice.offer_id}:no`].includes(choice.option_id)) throw invalid("Invalid V2 CTA confirmation.");
1338
1343
  }
1339
1344
  } else if (command.type === "bind_patient") {
1340
- if (!((_b = (_a = __privateGet(this, _options).capabilities) == null ? void 0 : _a.supported_actions) == null ? void 0 : _b.includes("login"))) throw invalid("V2 login was not advertised.");
1345
+ if (!((_c = (_b = __privateGet(this, _options).capabilities) == null ? void 0 : _b.supported_actions) == null ? void 0 : _c.includes("login"))) throw invalid("V2 login was not advertised.");
1341
1346
  if (!onlyKeys(payload, ["action_id", "tenant_id", "patient_id", "token", "run_secret", "identity_proof", "turn_id", "previous_turn_id"]) || !uuid(payload.action_id) || payload.previous_turn_id === null || payload.tenant_id !== __privateGet(this, _options).tenantId || !identity(payload.patient_id) || payload.run_secret !== __privateGet(this, _options).run.run_secret || typeof payload.token !== "string" || !payload.token || payload.token.length > 4096 || typeof payload.identity_proof !== "string" || !payload.identity_proof || payload.identity_proof.length > 2048) throw invalid("Invalid V2 binding command.");
1342
1347
  } else if (command.type === "action_result") {
1343
1348
  if (!onlyKeys(payload, ["action_id", "status", "data", "operation", "turn_id", "previous_turn_id"]) || !uuid(payload.action_id) || payload.previous_turn_id === null || !["completed", "cancelled", "failed"].includes(payload.status) || !record(payload.data)) throw invalid("Invalid V2 action command.");
1344
1349
  const data = payload.data;
1345
1350
  if ("proposal_id" in data) {
1346
- if (!((_d = (_c = __privateGet(this, _options).capabilities) == null ? void 0 : _c.supported_actions) == null ? void 0 : _d.includes("confirm"))) throw invalid("V2 confirmation was not advertised.");
1351
+ if (!((_e = (_d = __privateGet(this, _options).capabilities) == null ? void 0 : _d.supported_actions) == null ? void 0 : _e.includes("confirm"))) throw invalid("V2 confirmation was not advertised.");
1347
1352
  if (__privateGet(this, _options).run.protocol !== "dbos_signin_booking_v1" || !onlyKeys(data, ["proposal_id", "approved"]) || !uuid(data.proposal_id) || ![void 0, "confirm", "status"].includes(payload.operation) || (payload.operation === "status" ? payload.status !== "completed" || data.approved !== null : typeof data.approved !== "boolean" || payload.status !== "completed" && data.approved)) throw invalid("Invalid V2 booking result.");
1348
- } else if (!((_f = (_e = __privateGet(this, _options).capabilities) == null ? void 0 : _e.supported_actions) == null ? void 0 : _f.includes("slot_picker")) || !["dbos_signin_actions_v1", "dbos_signin_booking_v1", "dbos_signin_cta_v1"].includes(__privateGet(this, _options).run.protocol) || payload.operation !== void 0 || (payload.status === "completed" ? !onlyKeys(data, ["slot_id"]) || typeof data.slot_id !== "string" || !data.slot_id.length || data.slot_id.length > 256 : Object.keys(data).length > 0)) {
1353
+ } else if (!((_g = (_f = __privateGet(this, _options).capabilities) == null ? void 0 : _f.supported_actions) == null ? void 0 : _g.includes("slot_picker")) || !["dbos_signin_actions_v1", "dbos_signin_booking_v1", "dbos_signin_cta_v1"].includes(__privateGet(this, _options).run.protocol) || payload.operation !== void 0 || (payload.status === "completed" ? !onlyKeys(data, ["slot_id"]) || typeof data.slot_id !== "string" || !data.slot_id.length || data.slot_id.length > 256 : Object.keys(data).length > 0)) {
1349
1354
  throw invalid("Invalid V2 slot result.");
1350
1355
  }
1351
1356
  } else throw invalid("Unsupported V2 command.");
@@ -1433,6 +1438,10 @@ var HCAmsSDK = class {
1433
1438
  var _a, _b;
1434
1439
  assertEnvironment(config.environment);
1435
1440
  assertTimeout((_a = config.timeout) != null ? _a : DEFAULT_TIMEOUT_MS);
1441
+ const adapter = config.fetch;
1442
+ if (adapter !== void 0 && typeof adapter !== "function") {
1443
+ throw new Error("Invalid HealthCloud SDK fetch adapter: expected a function.");
1444
+ }
1436
1445
  const apiBase = normalizeBaseUrl(
1437
1446
  config.baseUrlOverride === void 0 ? resolveBaseUrl(config.environment) : config.baseUrlOverride
1438
1447
  );
@@ -1447,7 +1456,8 @@ var HCAmsSDK = class {
1447
1456
  tenantId: config.tenantId,
1448
1457
  accessToken: config.accessToken,
1449
1458
  baseUrlOverride: apiBase,
1450
- timeout: (_b = config.timeout) != null ? _b : DEFAULT_TIMEOUT_MS
1459
+ timeout: (_b = config.timeout) != null ? _b : DEFAULT_TIMEOUT_MS,
1460
+ fetch: adapter
1451
1461
  };
1452
1462
  this.http = new HttpClient(this.state);
1453
1463
  const state = this.state;
@@ -1469,6 +1479,9 @@ var HCAmsSDK = class {
1469
1479
  },
1470
1480
  get timeout() {
1471
1481
  return state.timeout;
1482
+ },
1483
+ get fetch() {
1484
+ return state.fetch;
1472
1485
  }
1473
1486
  };
1474
1487
  this.authHttp = new HttpClient(authState);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@healthcloudai/hc-ams",
3
- "version": "3.8.0",
3
+ "version": "3.9.1",
4
4
  "description": "HealthCloud AMS SDK \u2014 application-agent discovery for AMS Services.",
5
5
  "author": "Healthcheck Systems Inc",
6
6
  "license": "MIT",