med-scribe-alliance-ts-sdk 2.0.18 → 2.0.20

package/dist/index.d.ts

@@ -120,14 +120,31 @@ export interface ErrorResponse {
 /**
  * Result type for all public SDK methods.
  * Expected errors (API failures, auth, validation) are returned — not thrown.
+ *
+ * `httpStatus` is set when the result was produced by an HTTP call (success or error).
+ * It will be undefined for purely local operations (e.g. cached discovery, no-op init).
  */
 export type SDKResult<T = void> = {
 	success: true;
 	data: T;
+	httpStatus?: number;
 } | {
 	success: false;
 	error: ScribeError;
 };
+/**
+ * Internal return shape for manager methods that wrap an HTTP call.
+ * Carries the HTTP status alongside the parsed response data so the
+ * ScribeClient boundary can surface it on SDKResult.
+ *
+ * For composed operations (e.g. recording start = createSession + recorder init),
+ * httpStatus reflects the most relevant HTTP call. It is optional because some
+ * code paths (cache hits, no-op flows) don't make a request.
+ */
+export type ApiCallResult<T> = {
+	data: T;
+	httpStatus?: number;
+};
 /**
  * Transport layer types
  */
@@ -752,8 +769,11 @@ export declare class ScribeClient {
 	 */
 	reset(): Promise<void>;
 	/**
-	 * Wraps an async operation into SDKResult.
-	 * Internal layers throw — this converts to { success, data/error }.
+	 * Wraps an async manager operation into SDKResult.
+	 * Internal manager methods always return `ApiCallResult<T>` so the HTTP
+	 * status from the underlying call (when present) is propagated to the
+	 * SDKResult success variant. On error, status is preserved via
+	 * `error.httpStatus`.
 	 */
 	private wrapResult;
 	/**
@@ -851,7 +871,7 @@ export declare class DiscoveryManager {
 	 * Fetch and validate the discovery document from the well-known endpoint.
 	 * Caches the result for 1 hour (configurable).
 	 */
-	fetchDiscovery(baseUrl: string, forceRefresh?: boolean): Promise<ResolvedConfig>;
+	fetchDiscovery(baseUrl: string, forceRefresh?: boolean): Promise<ApiCallResult<ResolvedConfig>>;
 	/**
 	 * Get the resolved runtime config. Throws if discovery hasn't been fetched.
 	 */
@@ -882,32 +902,32 @@ export declare class SessionManager {
 	 * Create a new scribe session.
 	 * Validates the request structure, sends to server, validates response.
 	 */
-	createSession(baseUrl: string, request: CreateSessionRequest): Promise<CreateSessionResponse>;
+	createSession(baseUrl: string, request: CreateSessionRequest): Promise<ApiCallResult<CreateSessionResponse>>;
 	/**
 	 * End an active session.
 	 * If no sessionId is provided, ends the current session.
 	 */
-	endSession(baseUrl: string, request: EndSessionRequest, sessionId?: string): Promise<EndSessionResponse>;
+	endSession(baseUrl: string, request: EndSessionRequest, sessionId?: string): Promise<ApiCallResult<EndSessionResponse>>;
 	/**
 	 * Get the status of a session.
 	 * If no sessionId is provided, queries the current session.
 	 * Pass templateId to filter status for a specific template.
 	 */
-	getSessionStatus(baseUrl: string, sessionId?: string, templateId?: string): Promise<GetSessionStatusResponse>;
+	getSessionStatus(baseUrl: string, sessionId?: string, templateId?: string): Promise<ApiCallResult<GetSessionStatusResponse>>;
 	/**
 	 * Patch an existing session (e.g., update user_status or processing_status).
 	 */
-	patchSession(baseUrl: string, request: PatchSessionRequest, sessionId?: string): Promise<PatchSessionResponse>;
+	patchSession(baseUrl: string, request: PatchSessionRequest, sessionId?: string): Promise<ApiCallResult<PatchSessionResponse>>;
 	/**
 	 * Trigger processing for a specific template in a session.
 	 */
-	processTemplate(baseUrl: string, templateId: string, sessionId?: string): Promise<ProcessTemplateResponse>;
+	processTemplate(baseUrl: string, templateId: string, sessionId?: string): Promise<ApiCallResult<ProcessTemplateResponse>>;
 	/**
 	 * Poll for session completion.
 	 * Keeps checking getSessionStatus until the session reaches a terminal state
 	 * (completed, partial, or failed) or the max attempts are exhausted.
 	 */
-	pollForCompletion(baseUrl: string, sessionId?: string, options?: PollOptions): Promise<GetSessionStatusResponse>;
+	pollForCompletion(baseUrl: string, sessionId?: string, options?: PollOptions): Promise<ApiCallResult<GetSessionStatusResponse>>;
 	/**
 	 * Get the current active session, if any.
 	 */
@@ -963,7 +983,7 @@ export declare class RecordingManager {
 	 * @param accessToken - Current Bearer token for upload auth headers
 	 * @returns The created session response
 	 */
-	start(baseUrl: string, options: RecordingOptions, accessToken?: string): Promise<CreateSessionResponse>;
+	start(baseUrl: string, options: RecordingOptions, accessToken?: string): Promise<ApiCallResult<CreateSessionResponse>>;
 	/**
 	 * Start recording for an already-created session.
 	 * Use this when the session was created externally (e.g. via createSession())
@@ -977,7 +997,7 @@ export declare class RecordingManager {
 	startWithExistingSession(baseUrl: string, session: CreateSessionResponse, options?: {
 		uploadType?: string;
 		deviceId?: string;
-	}, accessToken?: string): Promise<void>;
+	}, accessToken?: string): Promise<ApiCallResult<void>>;
 	/**
 	 * Pause the active recording.
 	 */
@@ -986,7 +1006,7 @@ export declare class RecordingManager {
 	 * Resume a paused recording.
 	 */
 	resume(): void;
-	stop(): Promise<EndRecordingResult>;
+	stop(): Promise<ApiCallResult<EndRecordingResult>>;
 	/**
 	 * End the session, dispatch onSessionEvent, and return the response.
 	 * Called from stop() (auto-finalize) and finalizeAfterExternalEndSession()
@@ -1031,7 +1051,7 @@ export declare class RecordingManager {
 	 * Each file is re-uploaded via transport.request() with retry logic.
 	 * Successfully retried files are removed from the retry context.
 	 */
-	retryFailedUploads(): Promise<RetryUploadResult>;
+	retryFailedUploads(): Promise<ApiCallResult<RetryUploadResult>>;
 	/**
 	 * Create the appropriate recorder based on upload type.
 	 */

package/dist/index.mjs

@@ -159,7 +159,7 @@ var r = "/.well-known/medscribealliance", i = 3600 * 1e3, a = /* @__PURE__ */ fu
 	upload_type: e.string().min(1, "upload_type is required"),
 	communication_protocol: e.string().min(1, "communication_protocol is required"),
 	model: e.string().optional(),
-	language_hint: e.array(e.string().max(2, "language_hint items must be at most 2 characters")).optional(),
+	language_hint: e.array(e.string()).optional(),
 	transcript_language: e.string().optional(),
 	additional_data: e.record(e.string(), e.any()).optional(),
 	session_mode: e.string().optional(),
@@ -250,7 +250,7 @@ var r = "/.well-known/medscribealliance", i = 3600 * 1e3, a = /* @__PURE__ */ fu
 	uploadType: e.string().optional(),
 	communicationProtocol: e.string().optional(),
 	model: e.string().optional(),
-	languageHint: e.array(e.string().max(2, "languageHint items must be at most 2 characters")).optional(),
+	languageHint: e.array(e.string()).optional(),
 	transcriptLanguage: e.string().optional(),
 	deviceId: e.string().optional(),
 	additionalData: e.record(e.string(), e.any()).optional(),
@@ -652,7 +652,10 @@ var V = class {
 	}
 	async fetchDiscovery(e, t = !1) {
 		try {
-			if (!t && this.resolvedConfig && this.isCacheValid()) return this.debug && console.log("[ScribeSDK] Using cached discovery document"), this.resolvedConfig;
+			if (!t && this.resolvedConfig && this.isCacheValid()) return this.debug && console.log("[ScribeSDK] Using cached discovery document"), {
+				data: this.resolvedConfig,
+				httpStatus: void 0
+			};
 			let n = e + r;
 			this.debug && console.log("[ScribeSDK] Fetching discovery from:", n);
 			let i = await this.transport.request({
@@ -661,7 +664,10 @@ var V = class {
 			});
 			this.validator.validateDiscoveryResponse(i.data);
 			let a = i.data, o = B(a);
-			return this.cachedDocument = a, this.resolvedConfig = o, this.cacheTimestamp = Date.now(), this.debug && console.log("[ScribeSDK] Discovery complete:", a.service?.name ?? a.protocol), o;
+			return this.cachedDocument = a, this.resolvedConfig = o, this.cacheTimestamp = Date.now(), this.debug && console.log("[ScribeSDK] Discovery complete:", a.service?.name ?? a.protocol), {
+				data: o,
+				httpStatus: i.status
+			};
 		} catch (t) {
 			throw t instanceof h ? t : new h(`Failed to fetch discovery document: ${t instanceof Error ? t.message : "Unknown error"}`, { baseUrl: e });
 		}
@@ -724,7 +730,10 @@ var V = class {
 				url: n,
 				body: t
 			});
-			return this.validator.validateCreateSessionResponse(r.data), this.currentSession = r.data, this.debug && console.log("[ScribeSDK] Session created:", r.data.session_id), r.data;
+			return this.validator.validateCreateSessionResponse(r.data), this.currentSession = r.data, this.debug && console.log("[ScribeSDK] Session created:", r.data.session_id), {
+				data: r.data,
+				httpStatus: r.status
+			};
 		} catch (e) {
 			throw e instanceof p ? e : new p(`Failed to create session: ${e instanceof Error ? e.message : "Unknown error"}`);
 		}
@@ -741,7 +750,10 @@ var V = class {
 				url: i,
 				body: t
 			});
-			return this.validator.validateEndSessionResponse(a.data), this.currentSession?.session_id === r && (this.currentSession = null), this.debug && console.log("[ScribeSDK] Session ended:", r, a.data.status), a.data;
+			return this.validator.validateEndSessionResponse(a.data), this.currentSession?.session_id === r && (this.currentSession = null), this.debug && console.log("[ScribeSDK] Session ended:", r, a.data.status), {
+				data: a.data,
+				httpStatus: a.status
+			};
 		} catch (e) {
 			throw e instanceof p ? e : new p(`Failed to end session: ${e instanceof Error ? e.message : "Unknown error"}`);
 		}
@@ -758,7 +770,10 @@ var V = class {
 				url: i,
 				acceptStatuses: [410]
 			});
-			return this.validator.validateGetSessionStatusResponse(a.data), this.debug && console.log("[ScribeSDK] Session status:", r, a.data.status), a.data;
+			return this.validator.validateGetSessionStatusResponse(a.data), this.debug && console.log("[ScribeSDK] Session status:", r, a.data.status), {
+				data: a.data,
+				httpStatus: a.status
+			};
 		} catch (e) {
 			throw e instanceof p ? e : new p(`Failed to get session status: ${e instanceof Error ? e.message : "Unknown error"}`);
 		}
@@ -775,7 +790,10 @@ var V = class {
 				url: i,
 				body: t
 			});
-			return this.validator.validatePatchSessionResponse(a.data), this.debug && console.log("[ScribeSDK] Session patched:", r, a.data.status), a.data;
+			return this.validator.validatePatchSessionResponse(a.data), this.debug && console.log("[ScribeSDK] Session patched:", r, a.data.status), {
+				data: a.data,
+				httpStatus: a.status
+			};
 		} catch (e) {
 			throw e instanceof p ? e : new p(`Failed to patch session: ${e instanceof Error ? e.message : "Unknown error"}`);
 		}
@@ -791,7 +809,10 @@ var V = class {
 				method: "POST",
 				url: i
 			});
-			return this.validator.validateProcessTemplateResponse(a.data), this.debug && console.log("[ScribeSDK] Template processing triggered:", t, a.data.status), a.data;
+			return this.validator.validateProcessTemplateResponse(a.data), this.debug && console.log("[ScribeSDK] Template processing triggered:", t, a.data.status), {
+				data: a.data,
+				httpStatus: a.status
+			};
 		} catch (e) {
 			throw e instanceof p ? e : new p(`Failed to process template: ${e instanceof Error ? e.message : "Unknown error"}`);
 		}
@@ -807,13 +828,13 @@ var V = class {
 			});
 			for (let t = 1; t <= i; t++) {
 				if (n?.signal?.aborted) throw new p("Polling was aborted", "polling_aborted", void 0, { session_id: r });
-				let o = await this.getSessionStatus(e, r);
+				let o = await this.getSessionStatus(e, r), s = o.data;
 				if (n?.onProgress) try {
-					n.onProgress(o);
+					n.onProgress(s);
 				} catch (e) {
 					console.error("[ScribeSDK] Error in poll onProgress callback:", e);
 				}
-				if (this.isTerminalStatus(o.status)) return this.debug && console.log("[ScribeSDK] Poll complete:", r, o.status, `(attempt ${t})`), o;
+				if (this.isTerminalStatus(s.status)) return this.debug && console.log("[ScribeSDK] Poll complete:", r, s.status, `(attempt ${t})`), o;
 				t < i && await this.sleepWithAbort(a, n?.signal);
 			}
 			throw new p(`Polling timed out after ${i} attempts for session '${r}'`, "polling_timeout", void 0, {
@@ -1554,9 +1575,10 @@ var ie = class {
 			session_id: t.sessionId
 		};
 		try {
-			let i;
+			let i, o;
 			try {
-				i = await this.sessionManager.createSession(e, a);
+				let t = await this.sessionManager.createSession(e, a);
+				i = t.data, o = t.httpStatus;
 			} catch (e) {
 				throw this.dispatchStartError("transport_error", "session_creation_failed", e), e;
 			}
@@ -1565,14 +1587,14 @@ var ie = class {
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
 				data: i
 			}), this.recorder = this.createRecorder(r);
-			let o = {
+			let s = {
 				accessToken: n,
 				uploadUrl: i.upload_url,
 				uploadHeaders: this.buildUploadHeaders(n),
 				sessionId: i.session_id
 			};
 			try {
-				this.recorder.initialize(i, o);
+				this.recorder.initialize(i, s);
 			} catch (e) {
 				throw this.cleanupRecordingState(), this.dispatchStartError("validation_error", "recorder_init_failed", e), e;
 			}
@@ -1585,7 +1607,10 @@ var ie = class {
 			return this._isRecording = !0, this.callbackRegistry.dispatch("onRecordingStateChange", {
 				type: "started",
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
-			}), this.config.debug && console.log("[ScribeSDK] Recording started:", i.session_id), i;
+			}), this.config.debug && console.log("[ScribeSDK] Recording started:", i.session_id), {
+				data: i,
+				httpStatus: o
+			};
 		} finally {
 			this._isStarting = !1;
 		}
@@ -1614,10 +1639,13 @@ var ie = class {
 			} catch (e) {
 				throw this.cleanupRecordingState(), this.dispatchStartError("vad_error", "vad_start_failed", e), e;
 			}
-			this._isRecording = !0, this.callbackRegistry.dispatch("onRecordingStateChange", {
+			return this._isRecording = !0, this.callbackRegistry.dispatch("onRecordingStateChange", {
 				type: "started",
 				timestamp: (/* @__PURE__ */ new Date()).toISOString()
-			}), this.config.debug && console.log("[ScribeSDK] Recording started with existing session:", t.session_id);
+			}), this.config.debug && console.log("[ScribeSDK] Recording started with existing session:", t.session_id), {
+				data: void 0,
+				httpStatus: void 0
+			};
 		} finally {
 			this._isStarting = !1;
 		}
@@ -1636,17 +1664,20 @@ var ie = class {
 	}
 	async stop() {
 		if (!this.recorder || !this._isRecording) return {
-			failedUploads: [],
-			totalFiles: 0,
-			sessionEnded: !1
+			data: {
+				failedUploads: [],
+				totalFiles: 0,
+				sessionEnded: !1
+			},
+			httpStatus: void 0
 		};
-		let e = !1;
+		let e = !1, t;
 		try {
-			let t = await this.recorder.stop();
+			let n = await this.recorder.stop();
 			this.preserveRetryContext(), this._isRecording = !1;
-			let n = t.failedUploads;
-			if (n.length > 0) try {
-				n = (await this.retryFailedUploads()).stillFailed;
+			let r = n.failedUploads;
+			if (r.length > 0) try {
+				r = (await this.retryFailedUploads()).data.stillFailed;
 			} catch (e) {
 				console.error("[ScribeSDK] Internal retry pass failed:", e), this.callbackRegistry.dispatch("onError", {
 					type: "transport_error",
@@ -1657,24 +1688,27 @@ var ie = class {
 					}
 				});
 			}
-			let r = {
-				failedUploads: n,
-				totalFiles: t.totalFiles,
+			let i = {
+				failedUploads: r,
+				totalFiles: n.totalFiles,
 				sessionEnded: !1
 			};
-			if (n.length === 0 && this.activeSession) {
-				let n = await this.finalizeSession(t.totalFiles, t.totalFiles);
-				n && (r.sessionEnded = !0, r.endSessionResponse = n, e = !0);
+			if (r.length === 0 && this.activeSession) {
+				let r = await this.finalizeSession(n.totalFiles, n.totalFiles);
+				r && (i.sessionEnded = !0, i.endSessionResponse = r.data, t = r.httpStatus, e = !0);
 			}
 			return this.callbackRegistry.dispatch("onRecordingStateChange", {
 				type: "ended",
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-				data: r
+				data: i
 			}), this.config.debug && console.log("[ScribeSDK] Recording stopped:", {
-				totalFiles: r.totalFiles,
-				failedUploads: r.failedUploads.length,
-				sessionEnded: r.sessionEnded
-			}), r;
+				totalFiles: i.totalFiles,
+				failedUploads: i.failedUploads.length,
+				sessionEnded: i.sessionEnded
+			}), {
+				data: i,
+				httpStatus: t
+			};
 		} catch (e) {
 			return console.error("[ScribeSDK] Error stopping recording:", e), this.callbackRegistry.dispatch("onError", {
 				type: "transport_error",
@@ -1684,9 +1718,12 @@ var ie = class {
 					message: e instanceof Error ? e.message : "Failed to stop recording"
 				}
 			}), {
-				failedUploads: [],
-				totalFiles: 0,
-				sessionEnded: !1
+				data: {
+					failedUploads: [],
+					totalFiles: 0,
+					sessionEnded: !1
+				},
+				httpStatus: void 0
 			};
 		} finally {
 			e ? this.cleanupRecordingState() : this.partialCleanupAfterFailedFinalize();
@@ -1701,7 +1738,7 @@ var ie = class {
 			return this.callbackRegistry.dispatch("onSessionEvent", {
 				type: "ended",
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-				data: n
+				data: n.data
 			}), n;
 		} catch (e) {
 			console.error("[ScribeSDK] Failed to end session:", e), this.callbackRegistry.dispatch("onError", {
@@ -1753,9 +1790,12 @@ var ie = class {
 	async retryFailedUploads() {
 		if (this._isRecording) throw new p("Cannot retry uploads while recording is active.");
 		if (!this.retryContext || this.retryContext.failedChunks.length === 0) return {
-			retried: 0,
-			succeeded: 0,
-			stillFailed: []
+			data: {
+				retried: 0,
+				succeeded: 0,
+				stillFailed: []
+			},
+			httpStatus: void 0
 		};
 		let { uploadUrl: e, failedChunks: t } = this.retryContext, n = t.length, r = [], i = 0;
 		this.config.debug && console.log(`[ScribeSDK] Retrying ${n} failed uploads`);
@@ -1785,9 +1825,12 @@ var ie = class {
 			}), this.config.debug && console.log(`[ScribeSDK] Retry failed: ${a.fileName}`, e);
 		}
 		return r.length === 0 ? this.retryContext = null : this.retryContext.failedChunks = t.filter((e) => r.includes(e.fileName)), this.config.debug && console.log(`[ScribeSDK] Retry complete: ${i}/${n} succeeded`), {
-			retried: n,
-			succeeded: i,
-			stillFailed: r
+			data: {
+				retried: n,
+				succeeded: i,
+				stillFailed: r
+			},
+			httpStatus: void 0
 		};
 	}
 	createRecorder(e) {
@@ -1854,7 +1897,11 @@ var ie = class {
 			success: !0,
 			data: void 0
 		} : this.wrapResult(async () => {
-			this.config.autoDiscovery !== !1 && await this.discoveryManager.fetchDiscovery(this.config.baseUrl), this.isInitialized = !0;
+			let e;
+			return this.config.autoDiscovery !== !1 && (e = (await this.discoveryManager.fetchDiscovery(this.config.baseUrl)).httpStatus), this.isInitialized = !0, {
+				data: void 0,
+				httpStatus: e
+			};
 		});
 	}
 	async startRecording(e) {
@@ -1913,7 +1960,7 @@ var ie = class {
 			return r && this.recordingManager.finalizeAfterExternalEndSession(r), this.callbackRegistry.dispatch("onSessionEvent", {
 				type: "ended",
 				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-				data: i
+				data: i.data
 			}), i;
 		});
 	}
@@ -1975,9 +2022,11 @@ var ie = class {
 	}
 	async wrapResult(e) {
 		try {
+			let t = await e();
 			return {
 				success: !0,
-				data: await e()
+				data: t.data,
+				httpStatus: t.httpStatus
 			};
 		} catch (e) {
 			return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "med-scribe-alliance-ts-sdk",
-  "version": "2.0.18",
+  "version": "2.0.20",
   "description": "TypeScript SDK for the MedScribe Alliance Protocol",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",