@healthcloudai/hc-ams 3.7.0 → 3.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -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.
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
  }
@@ -1059,6 +1060,7 @@ function capabilities(value) {
1059
1060
  }
1060
1061
 
1061
1062
  // src/v2/NativeV2Client.ts
1063
+ var BINDING_UNKNOWN = "V2 patient binding outcome unknown; reconcile the original operation.";
1062
1064
  var NativeV2Client = class {
1063
1065
  constructor(http) {
1064
1066
  this.http = http;
@@ -1077,6 +1079,65 @@ var NativeV2Client = class {
1077
1079
  ownedRun(result);
1078
1080
  return { run_id: result.run_id, run_secret: result.run_secret, protocol: result.protocol };
1079
1081
  }
1082
+ /**
1083
+ * Ordinary app sign-in. Close the socket after committed delivery first.
1084
+ * Sends once; callers retain the original UUID, claim and predecessor for retry.
1085
+ */
1086
+ async bindPatient(tenantId, agentId, runId, request, options) {
1087
+ let body;
1088
+ let headers;
1089
+ try {
1090
+ if (!record(request) || Object.keys(request).length !== 3 || !onlyKeys(request, ["operation_id", "run_secret", "expected_last_turn_id"]) || !record(options) || !onlyKeys(options, ["origin", "patientAccessToken"]) || !Object.prototype.hasOwnProperty.call(options, "patientAccessToken")) {
1091
+ throw invalid("Invalid V2 patient binding input.");
1092
+ }
1093
+ body = {
1094
+ operation_id: request.operation_id,
1095
+ run_secret: request.run_secret,
1096
+ expected_last_turn_id: request.expected_last_turn_id
1097
+ };
1098
+ const token = options.patientAccessToken;
1099
+ const origin = options.origin;
1100
+ if (!identity(tenantId) || !identity(agentId) || !uuid(runId) || !uuid(body.operation_id) || typeof body.run_secret !== "string" || !/^[A-Za-z0-9_-]{32,128}$/.test(body.run_secret) || !(body.expected_last_turn_id === null || uuid(body.expected_last_turn_id)) || typeof token !== "string" || !/^[!-~]{1,4096}$/.test(token)) {
1101
+ throw invalid("Invalid V2 patient binding input.");
1102
+ }
1103
+ headers = { Authorization: `Bearer ${token}` };
1104
+ if (origin !== void 0) {
1105
+ const parsed = new URL(origin);
1106
+ if (!["https:", "http:"].includes(parsed.protocol) || parsed.origin !== origin) {
1107
+ throw invalid("Invalid V2 patient binding input.");
1108
+ }
1109
+ headers.Origin = origin;
1110
+ }
1111
+ } catch {
1112
+ throw invalid("Invalid V2 patient binding input.");
1113
+ }
1114
+ let result;
1115
+ try {
1116
+ result = await this.http.request("POST", "/tenants/{tenant_id}/agents/{agent_id}/runs/{run_id}/patient-binding", {
1117
+ pathParams: { tenant_id: tenantId, agent_id: agentId, run_id: runId },
1118
+ auth: false,
1119
+ headers,
1120
+ body,
1121
+ timeoutMs: 1e4
1122
+ });
1123
+ } catch (error) {
1124
+ const code = error instanceof SDKError ? error.statusCode : 0;
1125
+ throw new SDKError({
1126
+ message: BINDING_UNKNOWN,
1127
+ statusCode: typeof code === "number" && Number.isInteger(code) && code >= 0 && code <= 599 ? code : 0
1128
+ });
1129
+ }
1130
+ if (!record(result) || result.status !== "bound" || !uuid(result.run_id) || result.run_id !== runId || !uuid(result.operation_id) || result.operation_id !== body.operation_id || typeof result.patient_id !== "string" || !/^[A-Za-z0-9_-]{1,160}$/.test(result.patient_id) || !(result.last_turn_id === null || uuid(result.last_turn_id)) || result.last_turn_id !== body.expected_last_turn_id) {
1131
+ throw new SDKError({ message: BINDING_UNKNOWN, statusCode: 0 });
1132
+ }
1133
+ return {
1134
+ status: "bound",
1135
+ run_id: result.run_id,
1136
+ operation_id: result.operation_id,
1137
+ patient_id: result.patient_id,
1138
+ last_turn_id: result.last_turn_id
1139
+ };
1140
+ }
1080
1141
  async request(method, path, tenantId, options, agentId) {
1081
1142
  if (options.origin !== void 0) {
1082
1143
  try {
@@ -1421,6 +1482,10 @@ var HCAmsSDK = class {
1421
1482
  var _a, _b;
1422
1483
  assertEnvironment(config.environment);
1423
1484
  assertTimeout((_a = config.timeout) != null ? _a : DEFAULT_TIMEOUT_MS);
1485
+ const adapter = config.fetch;
1486
+ if (adapter !== void 0 && typeof adapter !== "function") {
1487
+ throw new Error("Invalid HealthCloud SDK fetch adapter: expected a function.");
1488
+ }
1424
1489
  const apiBase = normalizeBaseUrl(
1425
1490
  config.baseUrlOverride === void 0 ? resolveBaseUrl(config.environment) : config.baseUrlOverride
1426
1491
  );
@@ -1435,7 +1500,8 @@ var HCAmsSDK = class {
1435
1500
  tenantId: config.tenantId,
1436
1501
  accessToken: config.accessToken,
1437
1502
  baseUrlOverride: apiBase,
1438
- timeout: (_b = config.timeout) != null ? _b : DEFAULT_TIMEOUT_MS
1503
+ timeout: (_b = config.timeout) != null ? _b : DEFAULT_TIMEOUT_MS,
1504
+ fetch: adapter
1439
1505
  };
1440
1506
  this.http = new HttpClient(this.state);
1441
1507
  const state = this.state;
@@ -1457,6 +1523,9 @@ var HCAmsSDK = class {
1457
1523
  },
1458
1524
  get timeout() {
1459
1525
  return state.timeout;
1526
+ },
1527
+ get fetch() {
1528
+ return state.fetch;
1460
1529
  }
1461
1530
  };
1462
1531
  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;
@@ -1009,6 +1014,20 @@ interface V2OwnedRun {
1009
1014
  run_secret: string;
1010
1015
  protocol: V2Protocol;
1011
1016
  }
1017
+ /** Original HTTP binding terms; retain privately and reuse unchanged after uncertainty. */
1018
+ interface V2PatientBindingRequest {
1019
+ operation_id: string;
1020
+ run_secret: string;
1021
+ expected_last_turn_id: string | null;
1022
+ }
1023
+ /** Patient identity is derived and verified by the server, never supplied by the host. */
1024
+ interface V2PatientBindingResult {
1025
+ status: "bound";
1026
+ run_id: string;
1027
+ operation_id: string;
1028
+ patient_id: string;
1029
+ last_turn_id: string | null;
1030
+ }
1012
1031
  interface V2ClientCapabilities {
1013
1032
  platform?: "web" | "ios" | "android" | "terminal" | "unknown";
1014
1033
  supported_actions?: Array<"confirm" | "insurance_scan" | "vitals_import" | "slot_picker" | "login" | "symptom_save" | "telehealth_join">;
@@ -1222,12 +1241,21 @@ interface V2AdmissionOptions {
1222
1241
  /** Allowed application origin for Node/native callers; browsers supply their own Origin. */
1223
1242
  origin?: string;
1224
1243
  }
1225
- /** Public Patient admission. Uses the SDK's selected AMS HTTP transport. */
1244
+ interface V2PatientBindingOptions extends V2AdmissionOptions {
1245
+ /** Explicit ordinary Patient authority; never the SDK's tenant-admin token. */
1246
+ patientAccessToken: string;
1247
+ }
1248
+ /** Native Patient admission and ordinary app binding through the selected AMS transport. */
1226
1249
  declare class NativeV2Client {
1227
1250
  private readonly http;
1228
1251
  constructor(http: HttpClient);
1229
1252
  listPublicAgents(tenantId: string, options?: V2AdmissionOptions): Promise<V2PublicAgents>;
1230
1253
  createRun(tenantId: string, agentId: string, options?: V2AdmissionOptions): Promise<V2OwnedRun>;
1254
+ /**
1255
+ * Ordinary app sign-in. Close the socket after committed delivery first.
1256
+ * Sends once; callers retain the original UUID, claim and predecessor for retry.
1257
+ */
1258
+ bindPatient(tenantId: string, agentId: string, runId: string, request: V2PatientBindingRequest, options: V2PatientBindingOptions): Promise<V2PatientBindingResult>;
1231
1259
  private request;
1232
1260
  }
1233
1261
 
@@ -1343,4 +1371,4 @@ declare class SDKError extends Error {
1343
1371
  toString(): string;
1344
1372
  }
1345
1373
 
1346
- 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 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 };
1374
+ 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;
@@ -1009,6 +1014,20 @@ interface V2OwnedRun {
1009
1014
  run_secret: string;
1010
1015
  protocol: V2Protocol;
1011
1016
  }
1017
+ /** Original HTTP binding terms; retain privately and reuse unchanged after uncertainty. */
1018
+ interface V2PatientBindingRequest {
1019
+ operation_id: string;
1020
+ run_secret: string;
1021
+ expected_last_turn_id: string | null;
1022
+ }
1023
+ /** Patient identity is derived and verified by the server, never supplied by the host. */
1024
+ interface V2PatientBindingResult {
1025
+ status: "bound";
1026
+ run_id: string;
1027
+ operation_id: string;
1028
+ patient_id: string;
1029
+ last_turn_id: string | null;
1030
+ }
1012
1031
  interface V2ClientCapabilities {
1013
1032
  platform?: "web" | "ios" | "android" | "terminal" | "unknown";
1014
1033
  supported_actions?: Array<"confirm" | "insurance_scan" | "vitals_import" | "slot_picker" | "login" | "symptom_save" | "telehealth_join">;
@@ -1222,12 +1241,21 @@ interface V2AdmissionOptions {
1222
1241
  /** Allowed application origin for Node/native callers; browsers supply their own Origin. */
1223
1242
  origin?: string;
1224
1243
  }
1225
- /** Public Patient admission. Uses the SDK's selected AMS HTTP transport. */
1244
+ interface V2PatientBindingOptions extends V2AdmissionOptions {
1245
+ /** Explicit ordinary Patient authority; never the SDK's tenant-admin token. */
1246
+ patientAccessToken: string;
1247
+ }
1248
+ /** Native Patient admission and ordinary app binding through the selected AMS transport. */
1226
1249
  declare class NativeV2Client {
1227
1250
  private readonly http;
1228
1251
  constructor(http: HttpClient);
1229
1252
  listPublicAgents(tenantId: string, options?: V2AdmissionOptions): Promise<V2PublicAgents>;
1230
1253
  createRun(tenantId: string, agentId: string, options?: V2AdmissionOptions): Promise<V2OwnedRun>;
1254
+ /**
1255
+ * Ordinary app sign-in. Close the socket after committed delivery first.
1256
+ * Sends once; callers retain the original UUID, claim and predecessor for retry.
1257
+ */
1258
+ bindPatient(tenantId: string, agentId: string, runId: string, request: V2PatientBindingRequest, options: V2PatientBindingOptions): Promise<V2PatientBindingResult>;
1231
1259
  private request;
1232
1260
  }
1233
1261
 
@@ -1343,4 +1371,4 @@ declare class SDKError extends Error {
1343
1371
  toString(): string;
1344
1372
  }
1345
1373
 
1346
- 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 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 };
1374
+ 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
  }
@@ -1011,6 +1012,7 @@ function capabilities(value) {
1011
1012
  }
1012
1013
 
1013
1014
  // src/v2/NativeV2Client.ts
1015
+ var BINDING_UNKNOWN = "V2 patient binding outcome unknown; reconcile the original operation.";
1014
1016
  var NativeV2Client = class {
1015
1017
  constructor(http) {
1016
1018
  this.http = http;
@@ -1029,6 +1031,65 @@ var NativeV2Client = class {
1029
1031
  ownedRun(result);
1030
1032
  return { run_id: result.run_id, run_secret: result.run_secret, protocol: result.protocol };
1031
1033
  }
1034
+ /**
1035
+ * Ordinary app sign-in. Close the socket after committed delivery first.
1036
+ * Sends once; callers retain the original UUID, claim and predecessor for retry.
1037
+ */
1038
+ async bindPatient(tenantId, agentId, runId, request, options) {
1039
+ let body;
1040
+ let headers;
1041
+ try {
1042
+ if (!record(request) || Object.keys(request).length !== 3 || !onlyKeys(request, ["operation_id", "run_secret", "expected_last_turn_id"]) || !record(options) || !onlyKeys(options, ["origin", "patientAccessToken"]) || !Object.prototype.hasOwnProperty.call(options, "patientAccessToken")) {
1043
+ throw invalid("Invalid V2 patient binding input.");
1044
+ }
1045
+ body = {
1046
+ operation_id: request.operation_id,
1047
+ run_secret: request.run_secret,
1048
+ expected_last_turn_id: request.expected_last_turn_id
1049
+ };
1050
+ const token = options.patientAccessToken;
1051
+ const origin = options.origin;
1052
+ if (!identity(tenantId) || !identity(agentId) || !uuid(runId) || !uuid(body.operation_id) || typeof body.run_secret !== "string" || !/^[A-Za-z0-9_-]{32,128}$/.test(body.run_secret) || !(body.expected_last_turn_id === null || uuid(body.expected_last_turn_id)) || typeof token !== "string" || !/^[!-~]{1,4096}$/.test(token)) {
1053
+ throw invalid("Invalid V2 patient binding input.");
1054
+ }
1055
+ headers = { Authorization: `Bearer ${token}` };
1056
+ if (origin !== void 0) {
1057
+ const parsed = new URL(origin);
1058
+ if (!["https:", "http:"].includes(parsed.protocol) || parsed.origin !== origin) {
1059
+ throw invalid("Invalid V2 patient binding input.");
1060
+ }
1061
+ headers.Origin = origin;
1062
+ }
1063
+ } catch {
1064
+ throw invalid("Invalid V2 patient binding input.");
1065
+ }
1066
+ let result;
1067
+ try {
1068
+ result = await this.http.request("POST", "/tenants/{tenant_id}/agents/{agent_id}/runs/{run_id}/patient-binding", {
1069
+ pathParams: { tenant_id: tenantId, agent_id: agentId, run_id: runId },
1070
+ auth: false,
1071
+ headers,
1072
+ body,
1073
+ timeoutMs: 1e4
1074
+ });
1075
+ } catch (error) {
1076
+ const code = error instanceof SDKError ? error.statusCode : 0;
1077
+ throw new SDKError({
1078
+ message: BINDING_UNKNOWN,
1079
+ statusCode: typeof code === "number" && Number.isInteger(code) && code >= 0 && code <= 599 ? code : 0
1080
+ });
1081
+ }
1082
+ if (!record(result) || result.status !== "bound" || !uuid(result.run_id) || result.run_id !== runId || !uuid(result.operation_id) || result.operation_id !== body.operation_id || typeof result.patient_id !== "string" || !/^[A-Za-z0-9_-]{1,160}$/.test(result.patient_id) || !(result.last_turn_id === null || uuid(result.last_turn_id)) || result.last_turn_id !== body.expected_last_turn_id) {
1083
+ throw new SDKError({ message: BINDING_UNKNOWN, statusCode: 0 });
1084
+ }
1085
+ return {
1086
+ status: "bound",
1087
+ run_id: result.run_id,
1088
+ operation_id: result.operation_id,
1089
+ patient_id: result.patient_id,
1090
+ last_turn_id: result.last_turn_id
1091
+ };
1092
+ }
1032
1093
  async request(method, path, tenantId, options, agentId) {
1033
1094
  if (options.origin !== void 0) {
1034
1095
  try {
@@ -1373,6 +1434,10 @@ var HCAmsSDK = class {
1373
1434
  var _a, _b;
1374
1435
  assertEnvironment(config.environment);
1375
1436
  assertTimeout((_a = config.timeout) != null ? _a : DEFAULT_TIMEOUT_MS);
1437
+ const adapter = config.fetch;
1438
+ if (adapter !== void 0 && typeof adapter !== "function") {
1439
+ throw new Error("Invalid HealthCloud SDK fetch adapter: expected a function.");
1440
+ }
1376
1441
  const apiBase = normalizeBaseUrl(
1377
1442
  config.baseUrlOverride === void 0 ? resolveBaseUrl(config.environment) : config.baseUrlOverride
1378
1443
  );
@@ -1387,7 +1452,8 @@ var HCAmsSDK = class {
1387
1452
  tenantId: config.tenantId,
1388
1453
  accessToken: config.accessToken,
1389
1454
  baseUrlOverride: apiBase,
1390
- timeout: (_b = config.timeout) != null ? _b : DEFAULT_TIMEOUT_MS
1455
+ timeout: (_b = config.timeout) != null ? _b : DEFAULT_TIMEOUT_MS,
1456
+ fetch: adapter
1391
1457
  };
1392
1458
  this.http = new HttpClient(this.state);
1393
1459
  const state = this.state;
@@ -1409,6 +1475,9 @@ var HCAmsSDK = class {
1409
1475
  },
1410
1476
  get timeout() {
1411
1477
  return state.timeout;
1478
+ },
1479
+ get fetch() {
1480
+ return state.fetch;
1412
1481
  }
1413
1482
  };
1414
1483
  this.authHttp = new HttpClient(authState);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@healthcloudai/hc-ams",
3
- "version": "3.7.0",
3
+ "version": "3.9.0",
4
4
  "description": "HealthCloud AMS SDK \u2014 application-agent discovery for AMS Services.",
5
5
  "author": "Healthcheck Systems Inc",
6
6
  "license": "MIT",