med-scribe-alliance-ts-sdk 2.0.32 → 2.0.34

package/README.md

@@ -198,6 +198,8 @@ await client.reset(); // stops recording if active, clears all state and caches
 - **`cancelSession()` does NOT trigger processing.** It stops the recorder locally, cleans up state, and tells the server the session is cancelled. No `endSession` call is made to the backend.
 - **All async methods return `SDKResult<T>`, never throw.** Always check `result.success` before accessing `result.data`. Errors are in `result.error`.
 - **The SDK validates inputs against the discovery document.** If the server doesn't support an upload type, language, or model you requested, you'll get a `ValidationError` before the API call is made.
+- **Audio uploads go to a server-selected storage backend.** Discovery's `capabilities.storage_provider` (default `aws`) decides the backend; uploads go directly to it (e.g. S3 presigned POST). 
+
 - **SharedWorker is optional.** If you provide `workerScriptUrl`, the SDK offloads MP3 compression and upload to a SharedWorker. If the worker fails to load, it silently falls back to main-thread processing.
 - **Microphone permission is requested on `startRecording()`.** The browser will prompt the user for mic access. If denied, you'll get an error via `onError` callback.
 - **`reset()` is a full teardown.** It destroys the transport, clears discovery cache, removes all callbacks, and sets the client back to uninitialized state. You'll need to call `init()` (or `startRecording()`) again after reset.
@@ -273,6 +275,42 @@ if (client.hasFailedUploads()) {
 }
 ```
 
+### Upload a Pre-recorded Audio File
+
+For processing an already-recorded file (no mic/VAD). Create a session, then upload the file using the session's `upload_url`, then end the session and poll.
+
+```ts
+// 1. Create a session (gives you upload_url)
+const session = await client.createSession({
+  templates: ['soap'],
+  upload_type: 'single',
+  communication_protocol: 'http',
+});
+if (!session.success) return;
+
+// 2. Upload the file to storage using the session's upload_url
+const upload = await client.uploadAudioFile(
+  myAudioFile,
+  'audio_0.mp3',            // storage object name
+  session.data.upload_url
+);
+if (!upload.success) {
+  console.error('Upload failed:', upload.error.message);
+  return;
+}
+console.log(upload.data.status, upload.data.headers); // full storage response
+
+// 3. End the session to trigger processing, then poll getSessionStatus()
+await client.endSession(
+  { audio_files_sent: 1, audio_files_uploaded: 1 },
+  session.data.session_id
+);
+```
+
+- `file` is a `File`/`Blob`; `fileName` is the storage object name; `upload` is the `upload_url` object from the create-session response.
+- Returns `UploadAudioFileResult` — `{ fileName, status, headers, response }` (the full storage response; the body is usually empty for an S3 presigned POST).
+- Failures (network, malformed `upload_url`) come back as `UploadError` in `result.error`; an unknown provider as `UnsupportedStorageProviderError`.
+
 ### Update Auth Token
 
 ```ts
@@ -351,6 +389,7 @@ interface RecordingOptions {
 | `isRecordingPaused()` | `boolean` | Whether the active recording is paused. |
 | `retryFailedUploads()` | `SDKResult<RetryUploadResult>` | Retry uploads that failed during the last recording. |
 | `hasFailedUploads()` | `boolean` | Whether there are retryable failed uploads. |
+| `uploadAudioFile(file, fileName, upload)` | `SDKResult<UploadAudioFileResult>` | Upload one pre-recorded audio file to storage using a session's `upload_url`. No mic/recorder. |
 
 ### Session
 
@@ -457,10 +496,12 @@ interface CreateSessionResponse {
   status: SessionStatus;
   created_at: string;
   expires_at: string;
-  upload_url: string;
+  upload_url: SessionUploadInfo;
   patient_details?: PatientDetails;
 }
 
+type SessionUploadInfo = Record<string, unknown>;
+
 interface PatchSessionRequest {
   user_status?: string;
   processing_status?: string;
@@ -585,7 +626,8 @@ console.log(result.data.session_id);
 | `DiscoveryError` | — | Discovery fetch/parse failed |
 | `TransportError` | — | Network / IPC failure |
 | `WorkerError` | — | SharedWorker failure |
-| `UploadError` | — | Audio upload failure |
+| `UploadError` | — | Audio upload failure (failed transfer, or malformed `upload_url` payload). Has `failedFiles: string[]`. |
+| `UnsupportedStorageProviderError` | — | Discovery advertised a `storage_provider` this SDK build has no wrapper for. Thrown at `startRecording`. Has `provider: string`. |
 
 ## SharedWorker Support
 
@@ -648,6 +690,8 @@ const client = new ScribeClient({
 
 IPC mode always uses main-thread compression (SharedWorker can't access the IPC bridge).
 
+> **Presigned uploads over IPC need host support.** The SDK forwards `uploadFormFields` + base64 file (`blobData`) in the `IpcRequest`; your host must build the `multipart/form-data` POST (no `Authorization` header). Browser/HTTP mode works out of the box.
+
 ## Building from Source
 
 ```bash

package/dist/index.d.ts

@@ -98,7 +98,8 @@ export declare enum ErrorCode {
 	VAD_START_FAILED = "vad_start_failed",
 	STOP_FAILED = "stop_failed",
 	INTERNAL_RETRY_FAILED = "internal_retry_failed",
-	SESSION_END_FAILED = "session_end_failed"
+	SESSION_END_FAILED = "session_end_failed",
+	UNSUPPORTED_STORAGE_PROVIDER = "unsupported_storage_provider"
 }
 export declare enum HttpStatus {
 	OK = 200,
@@ -155,6 +156,11 @@ export declare class UploadError extends ScribeError {
 	constructor(message: string, failedFiles: string[], details?: Record<string, any>);
 	toJSON(): Record<string, any>;
 }
+/** Thrown when discovery advertises a storage provider the SDK has no wrapper for. */
+export declare class UnsupportedStorageProviderError extends ScribeError {
+	readonly provider: string;
+	constructor(provider: string);
+}
 export interface ApiError {
 	code: ErrorCode | string;
 	message: string;
@@ -201,6 +207,13 @@ export interface TransportRequest {
 	body?: any;
 	isUpload?: boolean;
 	uploadBlob?: Blob;
+	uploadFileName?: string;
+	/** Multipart form fields; when set, the request is multipart/form-data with uploadBlob as the file. */
+	uploadFormFields?: Record<string, string>;
+	/** Multipart field name for the file part. Defaults to 'file'. */
+	uploadFileFieldName?: string;
+	/** Attach the service Bearer + flavour header. Defaults to true; false for presigned uploads. */
+	attachAuth?: boolean;
 	/** Additional HTTP status codes to treat as success (not throw). */
 	acceptStatuses?: number[];
 	maxRetries?: number;
@@ -229,8 +242,14 @@ export interface IpcRequest {
 	url: string;
 	headers?: Record<string, string>;
 	body?: any;
-	/** Base64-encoded blob data for uploads */
+	/** Base64-encoded file bytes for uploads. */
 	blobData?: string;
+	/** Multipart fields for presigned uploads — host builds multipart from these + blobData (no auth header). */
+	uploadFormFields?: Record<string, string>;
+	/** Multipart field name for the file part. Defaults to 'file'. */
+	uploadFileFieldName?: string;
+	/** File name for the multipart file part. */
+	uploadFileName?: string;
 }
 export interface IpcResponse {
 	correlationId: string;
@@ -304,6 +323,7 @@ export interface CapabilitiesInfo {
 	upload_methods?: string[];
 	webhook_delivery?: boolean;
 	client_sdk_delivery?: boolean;
+	storage_provider?: string;
 }
 export interface ModelConfig {
 	id: string;
@@ -332,6 +352,7 @@ export interface ResolvedConfig {
 	autoDetectLanguage: boolean;
 	supportedAudioFormats: string[];
 	supportedUploadMethods: string[];
+	storageProvider: string;
 	maxChunkDurationSeconds: number;
 	/** modelId -> max session duration in seconds */
 	maxSessionDurationSeconds: Map<string, number>;
@@ -360,12 +381,14 @@ export interface CreateSessionRequest {
 	patient_details?: PatientDetails;
 	session_id?: string;
 }
+/** Provider-specific upload payload; validated/interpreted by the StorageProvider, not the session schema. */
+export type SessionUploadInfo = Record<string, unknown>;
 export interface CreateSessionResponse {
 	session_id: string;
 	status: SessionStatus;
 	created_at: string;
 	expires_at: string;
-	upload_url: string;
+	upload_url: SessionUploadInfo;
 	patient_details?: PatientDetails;
 }
 export interface EndSessionRequest {
@@ -472,7 +495,9 @@ export interface RecordingOptions {
 }
 export interface RecorderConfig {
 	accessToken?: string;
-	uploadUrl: string;
+	/** Provider-specific upload payload from the create-session response. */
+	upload: SessionUploadInfo;
+	storageProvider: string;
 	uploadHeaders: Record<string, string>;
 	sessionId: string;
 }
@@ -527,6 +552,17 @@ export interface RetryUploadResult {
 	/** File names that still failed after retry */
 	stillFailed: string[];
 }
+/** Result of ScribeClient.uploadAudioFile() — the storage backend's full response. */
+export interface UploadAudioFileResult {
+	/** The storage object name used. */
+	fileName: string;
+	/** HTTP status from the storage backend (e.g. 204 for an S3 presigned POST). */
+	status: number;
+	/** Response headers from the storage backend (e.g. ETag). */
+	headers: Record<string, string>;
+	/** Raw response body from the storage backend (often empty for S3). */
+	response: unknown;
+}
 export interface RecordingStateChangeEvent {
 	type: RecordingState$1;
 	timestamp: string;
@@ -648,7 +684,9 @@ export interface WorkerCompressAndUploadMessage {
 	type: "compress_and_upload";
 	audioFrames: Float32Array;
 	fileName: string;
-	uploadUrl: string;
+	storageProvider: string;
+	/** Provider-specific upload payload from the create-session response. */
+	upload: unknown;
 	headers: Record<string, string>;
 }
 export interface WorkerWaitForUploadsMessage {
@@ -758,6 +796,14 @@ export declare class ScribeClient {
 	 * Call this after receiving a 'chunk_limit_reached' error to resume chunk uploads.
 	 */
 	forceAllowMoreChunks(): void;
+	/**
+	 * Upload a single pre-recorded audio file to storage.
+	 * @param file - The audio file/blob to upload.
+	 * @param upload - The `upload_url` payload from the create-session response.
+	 * @param options.fileName - Storage object name. Defaults to the File's name,
+	 *   else `audio_0.<ext>` derived from the MIME type.
+	 */
+	uploadAudioFile(file: Blob, fileName: string, upload: SessionUploadInfo): Promise<SDKResult<UploadAudioFileResult>>;
 	/**
 	 * Create a session directly (without starting a recording).
 	 */
@@ -871,12 +917,49 @@ export declare class ScribeClient {
 	 */
 	private createTransport;
 	private resolveWorkerConfig;
+	/** Storage provider name from discovery; defaults to 'aws'. */
+	private getStorageProviderName;
 	/**
 	 * Get the effective base URL — prefer discovery's base_url, fall back to config.
 	 */
 	private getEffectiveBaseUrl;
 	private validateConfig;
 }
+/**
+ * Storage provider abstraction — the only part of the upload flow that varies
+ * between backends (AWS S3, GCP, ...). A provider is a pure, DOM-free request
+ * builder so it runs on the main thread, in the SharedWorker, and over IPC.
+ *
+ * To add a provider: implement StorageProvider in `<name>-provider.ts` and
+ * register it in `storage-provider-factory.ts`. No other changes needed.
+ */
+export interface UploadContext {
+	fileName: string;
+	blob: Blob;
+	upload: unknown;
+}
+export interface PreparedUpload {
+	url: string;
+	method: "POST" | "PUT";
+	bodyMode: "multipart" | "binary";
+	formFields?: Record<string, string>;
+	fileFieldName?: string;
+	headers: Record<string, string>;
+	attachAuth: boolean;
+}
+export interface StorageProvider {
+	/** Matches discovery's `capabilities.storage_provider`. */
+	readonly name: string;
+	/** @throws UploadError if the upload payload is malformed. */
+	prepareUpload(ctx: UploadContext): PreparedUpload;
+}
+export declare class AwsS3StorageProvider implements StorageProvider {
+	readonly name = "aws";
+	prepareUpload({ fileName, blob, upload }: UploadContext): PreparedUpload;
+}
+export declare function isStorageProviderSupported(name: string): boolean;
+/** @throws UnsupportedStorageProviderError if no wrapper is registered. */
+export declare function getStorageProvider(name: string): StorageProvider;
 export declare class CallbackRegistry {
 	private handlers;
 	/**
@@ -1132,7 +1215,7 @@ export declare class RecordingManager {
 	finalizeAfterExternalEndSession(sessionId: string): void;
 	/**
 	 * Retry uploading audio files that failed during the last recording.
-	 * Uses the stored MP3 blobs and the original upload URL.
+	 * Uses the stored MP3 blobs and the same storage provider as the recording.
 	 *
 	 * Each file is re-uploaded via transport.request() with retry logic.
 	 * Successfully retried files are removed from the retry context.
@@ -1142,6 +1225,10 @@ export declare class RecordingManager {
 	 * Create the appropriate recorder based on upload type.
 	 */
 	private createRecorder;
+	/** Storage provider name from discovery; defaults to 'aws'. */
+	private getStorageProviderName;
+	/** Validate the provider has a wrapper (throws UnsupportedStorageProviderError) and return its name. */
+	private resolveStorageProviderName;
 	/**
 	 * Build upload headers from the current auth state.
 	 */