assemblyai 4.5.0-beta.0 → 4.6.0

package/docs/reference-types-from-js.md

@@ -0,0 +1,27 @@
+# Reference types from JavaScript
+
+Types are automatically configured in most IDEs when you import the `assemblyai` module using `require` or `import`.
+However, if you're using the _assemblyai.umd.js_ or _assemblyai.umd.min.js_ script,
+you need to manually reference the types.
+
+1. Install the `assemblyai` module locally.
+2. Create an _assemblyai.d.ts_ file with the following content.
+   ```typescript
+   import AssemblyAIModule from "assemblyai";
+   declare global {
+     const assemblyai: typeof AssemblyAIModule;
+   }
+   ```
+   This will import the TypeScript types from the `assemblyai` module,
+   and configure them as the global `assemblyai` variable.
+3. Reference the _assemblyai.d.ts_ file at the top of your script file.
+
+   ```js
+   /// <reference path="assemblyai.d.ts" />
+   const { RealtimeTranscriber } = assemblyai;
+   ...
+   ```
+
+   Your IDE will load the types specified in the `<reference />` tag.
+
+   > [!INFO] > `/// <reference />` tags only work in script files, not script-blocks, and should be at the top of the file.

package/package.json

@@ -1,25 +1,26 @@
 {
   "name": "assemblyai",
-  "version": "4.5.0-beta.0",
+  "version": "4.6.0",
   "description": "The AssemblyAI JavaScript SDK provides an easy-to-use interface for interacting with the AssemblyAI API, which supports async and real-time transcription, as well as the latest LeMUR models.",
   "engines": {
     "node": ">=18"
   },
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
+      "types": "./dist/exports/index.d.ts",
       "bun": {
-        "types": "./dist/index.d.ts",
+        "types": "./dist/exports/index.d.ts",
         "default": "./dist/bun.mjs"
       },
       "deno": {
-        "types": "./dist/index.d.ts",
+        "types": "./dist/exports/index.d.ts",
         "default": "./dist/deno.mjs"
       },
-      "workerd": "./dist/index.mjs",
+      "workerd": "./dist/workerd.mjs",
       "browser": "./dist/browser.mjs",
+      "react-native": "./dist/browser.mjs",
       "node": {
-        "types": "./dist/index.d.ts",
+        "types": "./dist/exports/index.d.ts",
         "import": "./dist/node.mjs",
         "require": "./dist/node.cjs"
       },
@@ -27,9 +28,20 @@
       "require": "./dist/index.cjs",
       "default": "./dist/index.cjs"
     },
+    "./streaming": {
+      "types": "./dist/exports/streaming.d.ts",
+      "browser": "./dist/streaming.browser.mjs",
+      "import": "./dist/streaming.mjs",
+      "require": "./dist/streaming.cjs",
+      "default": "./dist/streaming.cjs"
+    },
     "./package.json": "./package.json"
   },
   "imports": {
+    "#fetch": {
+      "workerd": "./src/polyfills/fetch/workerd.ts",
+      "default": "./src/polyfills/fetch/default.ts"
+    },
     "#fs": {
       "node": "./src/polyfills/fs/node.ts",
       "bun": "./src/polyfills/fs/bun.ts",
@@ -47,6 +59,8 @@
     }
   },
   "type": "commonjs",
+  "react-native": "./dist/browser.mjs",
+  "browser": "./dist/browser.mjs",
   "main": "./dist/index.cjs",
   "require": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -57,18 +71,22 @@
     "url": "git+https://github.com/AssemblyAI/assemblyai-node-sdk.git"
   },
   "publishConfig": {
-    "tag": "beta",
+    "tag": "latest",
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
     "build": "pnpm clean && pnpm rollup -c",
     "clean": "rimraf dist/* && rimraf temp/* && rimraf temp-docs/*",
-    "lint": "eslint -c .eslintrc.json '{src,tests}/**/*.{js,ts}' && publint && tsc --noEmit -p tsconfig.json",
-    "test": "pnpm run test:unit && pnpm run test:integration",
+    "lint": "pnpm lint:eslint && pnpm lint:tsc && pnpm lint:format && pnpm lint:publint",
+    "lint:eslint": "eslint -c .eslintrc.json '{src,tests}/**/*.{js,ts}'",
+    "lint:tsc": "tsc --noEmit -p tsconfig.json",
+    "lint:format": "prettier  --check --no-error-on-unmatched-pattern {*,**/*}",
+    "lint:publint": "publint",
+    "test": "pnpm test:unit && pnpm test:integration",
     "test:unit": "jest --config jest.unit.config.js --testTimeout 1000",
     "test:integration": "jest --config jest.integration.config.js --testTimeout 360000",
-    "format": "prettier '**/*' --write",
+    "format": "prettier --write --no-error-on-unmatched-pattern {*,**/*}",
     "generate:types": "tsx ./scripts/generate-types.ts && prettier 'src/types/*.generated.ts' --write",
     "generate:reference": "typedoc",
     "copybara:dry-run": "./copybara.sh dry_run --init-history",
@@ -97,19 +115,20 @@
     "docs"
   ],
   "devDependencies": {
-    "@babel/preset-env": "^7.24.0",
-    "@babel/preset-typescript": "^7.23.3",
+    "@babel/preset-env": "^7.24.7",
+    "@babel/preset-typescript": "^7.24.7",
     "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-replace": "^5.0.7",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^11.1.6",
     "@types/jest": "^29.5.12",
-    "@types/node": "^18.11.9",
+    "@types/node": "^18.19.38",
     "@types/websocket": "^1.0.10",
     "@types/ws": "^8.5.10",
-    "@typescript-eslint/eslint-plugin": "^7.2.0",
+    "@typescript-eslint/eslint-plugin": "^7.13.1",
     "dotenv": "^16.4.5",
     "eslint": "^8.57.0",
-    "eslint-plugin-tsdoc": "^0.2.17",
+    "eslint-plugin-tsdoc": "^0.3.0",
     "jest": "^29.7.0",
     "jest-cli": "^29.7.0",
     "jest-fetch-mock": "^3.0.3",
@@ -117,17 +136,30 @@
     "jest-websocket-mock": "^2.5.0",
     "mock-socket": "^9.3.1",
     "openapi-typescript": "^6.7.5",
-    "prettier": "^3.2.5",
-    "publint": "^0.2.7",
-    "rimraf": "^5.0.5",
-    "rollup": "^4.13.0",
-    "ts-jest": "^29.1.2",
-    "tslib": "^2.5.3",
-    "typescript": "^5.4.2",
-    "typedoc": "^0.25.12",
-    "typedoc-plugin-extras": "^3.0.0"
+    "prettier": "^3.3.2",
+    "publint": "^0.2.8",
+    "rimraf": "^5.0.7",
+    "rollup": "^4.18.0",
+    "ts-jest": "^29.1.5",
+    "tslib": "^2.6.3",
+    "typedoc": "^0.25.13",
+    "typedoc-plugin-extras": "^3.0.0",
+    "typescript": "^5.4.5"
   },
   "dependencies": {
-    "ws": "^8.16.0"
+    "ws": "^8.17.1"
+  },
+  "pnpm": {
+    "packageExtensions": {
+      "ws": {
+        "peerDependencies": {
+          "@types/ws": "^8.5.10"
+        }
+      }
+    },
+    "overrides": {
+      "undici@<5.28.4": ">=5.28.4",
+      "braces@<3.0.3": ">=3.0.3"
+    }
   }
 }

package/src/exports/index.ts

@@ -0,0 +1,2 @@
+export * from "../types";
+export * from "../services";

package/src/exports/streaming.ts

@@ -0,0 +1,4 @@
+export * from "../types/asyncapi.generated";
+export * from "../types/realtime";
+export * from "../types/helpers";
+export * from "../services/realtime/service";

package/src/polyfills/fetch/default.ts

@@ -0,0 +1,3 @@
+export const DEFAULT_FETCH_INIT: Record<string, unknown> = {
+  cache: "no-store",
+};

package/src/polyfills/fetch/workerd.ts

@@ -0,0 +1 @@
+export const DEFAULT_FETCH_INIT: Record<string, unknown> = {};

package/src/services/base.ts

@@ -1,26 +1,46 @@
-import { BaseServiceParams } from "..";
-import { Error as JsonError } from "..";
+import { DEFAULT_FETCH_INIT } from "#fetch";
+import { BaseServiceParams, Error as JsonError } from "..";
+import { buildUserAgent } from "../utils/userAgent";
 
 /**
  * Base class for services that communicate with the API.
  */
 export abstract class BaseService {
+  private userAgent: string | undefined;
   /**
    * Create a new service.
    * @param params - The parameters to use for the service.
    */
-  constructor(private params: BaseServiceParams) {}
+  constructor(private params: BaseServiceParams) {
+    if (params.userAgent === false) {
+      this.userAgent = undefined;
+    } else {
+      this.userAgent = buildUserAgent(params.userAgent || {});
+    }
+  }
   protected async fetch(
     input: string,
     init?: RequestInit | undefined,
   ): Promise<Response> {
-    init = init ?? {};
-    init.headers = init.headers ?? {};
-    init.headers = {
+    init = { ...DEFAULT_FETCH_INIT, ...init };
+    let headers = {
       Authorization: this.params.apiKey,
       "Content-Type": "application/json",
-      ...init.headers,
     };
+    if (DEFAULT_FETCH_INIT?.headers)
+      headers = { ...headers, ...DEFAULT_FETCH_INIT.headers };
+    if (init?.headers) headers = { ...headers, ...init.headers };
+
+    if (this.userAgent) {
+      (headers as Record<string, string>)["User-Agent"] = this.userAgent;
+      // chromium browsers have a bug where the user agent can't be modified
+      if (typeof window !== "undefined" && "chrome" in window) {
+        (headers as Record<string, string>)["AssemblyAI-Agent"] =
+          this.userAgent;
+      }
+    }
+    init.headers = headers;
+
     if (!input.startsWith("http")) input = this.params.baseUrl + input;
 
     const response = await fetch(input, init);

package/src/services/files/index.ts

@@ -10,8 +10,13 @@ export class FileService extends BaseService {
    */
   async upload(input: FileUploadParams): Promise<string> {
     let fileData: FileUploadData;
-    if (typeof input === "string") fileData = await readFile(input);
-    else fileData = input;
+    if (typeof input === "string") {
+      if (input.startsWith("data:")) {
+        fileData = dataUrlToBlob(input);
+      } else {
+        fileData = await readFile(input);
+      }
+    } else fileData = input;
 
     const data = await this.fetchJson<UploadedFile>("/v2/upload", {
       method: "POST",
@@ -24,3 +29,15 @@ export class FileService extends BaseService {
     return data.upload_url;
   }
 }
+
+function dataUrlToBlob(dataUrl: string) {
+  const arr = dataUrl.split(",");
+  const mime = arr[0].match(/:(.*?);/)![1];
+  const bstr = atob(arr[1]);
+  let n = bstr.length;
+  const u8arr = new Uint8Array(n);
+  while (n--) {
+    u8arr[n] = bstr.charCodeAt(n);
+  }
+  return new Blob([u8arr], { type: mime });
+}

package/src/services/index.ts

@@ -38,8 +38,9 @@ class AssemblyAI {
    */
   constructor(params: BaseServiceParams) {
     params.baseUrl = params.baseUrl || defaultBaseUrl;
-    if (params.baseUrl && params.baseUrl.endsWith("/"))
+    if (params.baseUrl && params.baseUrl.endsWith("/")) {
       params.baseUrl = params.baseUrl.slice(0, -1);
+    }
     this.files = new FileService(params);
     this.transcripts = new TranscriptService(params, this.files);
     this.lemur = new LemurService(params);

package/src/services/lemur/index.ts

@@ -8,6 +8,7 @@ import {
   LemurActionItemsResponse,
   LemurTaskResponse,
   PurgeLemurRequestDataResponse,
+  LemurResponse,
 } from "../..";
 import { BaseService } from "../base";
 
@@ -50,6 +51,17 @@ export class LemurService extends BaseService {
     });
   }
 
+  /**
+   * Retrieve a LeMUR response that was previously generated.
+   * @param id - The ID of the LeMUR request you previously made. This would be found in the response of the original request.
+   * @returns The LeMUR response.
+   */
+  getResponse<T extends LemurResponse>(id: string): Promise<T>;
+  getResponse(id: string): Promise<LemurResponse>;
+  getResponse(id: string): Promise<LemurResponse> {
+    return this.fetchJson<LemurResponse>(`/lemur/v3/${id}`);
+  }
+
   /**
    * Delete the data for a previously submitted LeMUR request.
    * @param id - ID of the LeMUR request

package/src/services/realtime/service.ts

@@ -45,6 +45,9 @@ type BufferLike =
   | { valueOf(): string }
   | { [Symbol.toPrimitive](hint: string): string };
 
+/**
+ * RealtimeTranscriber connects to the Streaming Speech-to-Text API and lets you transcribe audio in real-time.
+ */
 export class RealtimeTranscriber {
   private realtimeUrl: string;
   private sampleRate: number;
@@ -59,6 +62,10 @@ export class RealtimeTranscriber {
   private listeners: RealtimeListeners = {};
   private sessionTerminatedResolve?: () => void;
 
+  /**
+   * Create a new RealtimeTranscriber.
+   * @param params - Parameters to configure the RealtimeTranscriber
+   */
   constructor(params: RealtimeTranscriberParams) {
     this.realtimeUrl = params.realtimeUrl ?? defaultRealtimeUrl;
     this.sampleRate = params.sampleRate ?? 16_000;
@@ -106,30 +113,75 @@ export class RealtimeTranscriber {
     return url;
   }
 
+  /**
+   * Listen for the open event which is emitted when the connection is established and the session begins.
+   * @param event - The open event.
+   * @param listener - The function to call when the event is emitted.
+   */
   on(event: "open", listener: (event: SessionBeginsEventData) => void): void;
+  /**
+   * Listen for the transcript event which is emitted when a partian or final transcript is received.
+   * @param event - The transcript event.
+   * @param listener - The function to call when the event is emitted.
+   */
   on(
     event: "transcript",
     listener: (transcript: RealtimeTranscript) => void,
   ): void;
+  /**
+   * Listen for the partial transcript event which is emitted when a partial transcript is received.
+   * @param event - The partial transcript event.
+   * @param listener - The function to call when the event is emitted.
+   */
   on(
     event: "transcript.partial",
     listener: (transcript: PartialTranscript) => void,
   ): void;
+  /**
+   * Listen for the final transcript event which is emitted when a final transcript is received.
+   * @param event - The final transcript event.
+   * @param listener - The function to call when the event is emitted.
+   */
   on(
     event: "transcript.final",
     listener: (transcript: FinalTranscript) => void,
   ): void;
+  /**
+   * Listen for the session information event which is emitted when session information is received.
+   * The session information is sent right before the session is terminated.
+   * @param event - The session information event.
+   * @param listener - The function to call when the event is emitted.
+   */
   on(
     event: "session_information",
     listener: (info: SessionInformation) => void,
   ): void;
+  /**
+   * Listen for the error event which is emitted when an error occurs.
+   * @param event - The error event.
+   * @param listener - The function to call when the event is emitted.
+   */
   on(event: "error", listener: (error: Error) => void): void;
+  /**
+   * Listen for the close event which is emitted when the connection is closed.
+   * @param event - The close event.
+   * @param listener - The function to call when the event is emitted.
+   */
   on(event: "close", listener: (code: number, reason: string) => void): void;
+  /**
+   * Add a listener for an event.
+   * @param event - The event to listen for.
+   * @param listener - The function to call when the event is emitted.
+   */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   on(event: RealtimeEvents, listener: (...args: any[]) => void) {
     this.listeners[event] = listener;
   }
 
+  /**
+   * Connect to the server and begin a new session.
+   * @returns A promise that resolves when the connection is established and the session begins.
+   */
   connect() {
     return new Promise<SessionBeginsEventData>((resolve) => {
       if (this.socket) {
@@ -216,10 +268,18 @@ export class RealtimeTranscriber {
     });
   }
 
+  /**
+   * Send audio data to the server.
+   * @param audio - The audio data to send to the server.
+   */
   sendAudio(audio: AudioData) {
     this.send(audio);
   }
 
+  /**
+   * Create a writable stream that can be used to send audio data to the server.
+   * @returns A writable stream that can be used to send audio data to the server.
+   */
   stream(): WritableStream<AudioData> {
     return new WritableStream<AudioData>({
       write: (chunk: AudioData) => {
@@ -251,6 +311,11 @@ export class RealtimeTranscriber {
     this.socket.send(data);
   }
 
+  /**
+   * Close the connection to the server.
+   * @param waitForSessionTermination - If true, the method will wait for the session to be terminated before closing the connection.
+   * While waiting for the session to be terminated, you will receive the final transcript and session information.
+   */
   async close(waitForSessionTermination = true) {
     if (this.socket) {
       if (this.socket.readyState === this.socket.OPEN) {

package/src/services/transcripts/index.ts

@@ -16,6 +16,7 @@ import {
   TranscribeOptions,
   SubmitParams,
   SpeechModel,
+  RedactedAudioFile,
 } from "../..";
 import { FileService } from "../files";
 import { getPath } from "../../utils/path";
@@ -60,8 +61,12 @@ export class TranscriptService extends BaseService {
           // audio is local path, upload local file
           audioUrl = await this.files.upload(path);
         } else {
-          // audio is not a local path, assume it's a URL
-          audioUrl = audio;
+          if (audio.startsWith("data:")) {
+            audioUrl = await this.files.upload(audio);
+          } else {
+            // audio is not a local path, and not a data-URI, assume it's a normal URL
+            audioUrl = audio;
+          }
         }
       } else {
         // audio is of uploadable type
@@ -240,15 +245,47 @@ export class TranscriptService extends BaseService {
   }
 
   /**
-   * Retrieve redactions of a transcript.
+   * Retrieve the redacted audio URL of a transcript.
    * @param id - The identifier of the transcript.
-   * @returns A promise that resolves to the subtitles text.
+   * @returns A promise that resolves to the details of the redacted audio.
+   * @deprecated Use `redactedAudio` instead.
    */
   redactions(id: string): Promise<RedactedAudioResponse> {
+    return this.redactedAudio(id);
+  }
+
+  /**
+   * Retrieve the redacted audio URL of a transcript.
+   * @param id - The identifier of the transcript.
+   * @returns A promise that resolves to the details of the redacted audio.
+   */
+  redactedAudio(id: string): Promise<RedactedAudioResponse> {
     return this.fetchJson<RedactedAudioResponse>(
       `/v2/transcript/${id}/redacted-audio`,
     );
   }
+
+  /**
+   * Retrieve the redacted audio file of a transcript.
+   * @param id - The identifier of the transcript.
+   * @returns A promise that resolves to the fetch HTTP response of the redacted audio file.
+   */
+  async redactedAudioFile(id: string): Promise<RedactedAudioFile> {
+    const { redacted_audio_url, status } = await this.redactedAudio(id);
+    if (status !== "redacted_audio_ready") {
+      throw new Error(`Redacted audio status is ${status}`);
+    }
+    const response = await fetch(redacted_audio_url);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch redacted audio: ${response.statusText}`);
+    }
+    return {
+      arrayBuffer: response.arrayBuffer.bind(response),
+      blob: response.blob.bind(response),
+      body: response.body,
+      bodyUsed: response.bodyUsed,
+    };
+  }
 }
 
 function deprecateConformer2(params: { speech_model?: SpeechModel | null }) {

package/src/types/index.ts

@@ -5,3 +5,12 @@ export * from "./services";
 export * from "./asyncapi.generated";
 export * from "./openapi.generated";
 export * from "./deprecated";
+
+export type UserAgentItem = {
+  name: string;
+  version: string;
+};
+
+export type UserAgent = {
+  [component: string]: UserAgentItem | undefined | null | false;
+};