assemblyai 3.1.3 → 4.0.0-beta.1

package/docs/compat.md

@@ -0,0 +1,59 @@
+# SDK Compatibility
+
+The JavaScript SDK is developed for Node.js but is also compatible with other runtimes
+such as the browser, Deno, Bun, Cloudflare Workers, etc.
+
+## Browser compatibility
+
+To make the SDK compatible with the browser, the SDK aims to use web standards as much as possible.
+However, there are still incompatibilities between Node.js and the browser.
+
+- `RealtimeService` doesn't support the AssemblyAI API key in the browser.
+  Instead, you have to generate a temporary auth token using `client.realtime.createTemporaryToken`, and pass in the resulting token to the real-time transcriber.
+
+  Generate a temporary auth token on the server.
+
+  ```js
+  import { AssemblyAI } from "assemblyai"
+  // Ideally, to avoid embedding your API key client side,
+  // you generate this token on the server, and pass it to the client via an API.
+  const client = new AssemblyAI({ apiKey: "YOUR_API_KEY" });
+  const token = await client.realtime.createTemporaryToken({ expires_in = 480 });
+  ```
+
+  > [!NOTE]
+  > We recommend generating the token on the server, so you don't embed your AssemblyAI API key in your client app.
+  > If you embed the API key on the client, everyone can see it and use it for themselves.
+
+  Then pass the token via an API to the client.
+  On the client, create an instance of `RealtimeService` using the token.
+
+  ```js
+  import { RealtimeService } from "assemblyai";
+  // or the following if you're using UMD
+  // const { RealtimeService } = assemblyai;
+
+  const token = getToken(); // getToken is a function for you to implement
+
+  const rt = new RealtimeService({
+    token: token,
+  });
+  ```
+
+- You can't pass local audio file paths to `client.files.upload`, `client.transcripts.transcribe`, and `client.transcripts.submit`. If you do, you'll get the following error: "'fs' is not supported in this environment.".
+  If you want to transcribe audio files, you must use a public URL, a stream, or a buffer.
+
+> [!WARNING]
+> The SDK is usable from the browser, but we strongly recommend you don't embed the AssemblyAI API key into your client apps.
+> If you embed the API key on the client, everyone can see it and use it for themselves.
+> Instead, create use the SDK on the server and provide APIs for your client to call.
+
+## Deno, Bun, Cloudflare Workers, etc.
+
+Most server-side JavaScript runtimes include a compatibility layer with Node.js.
+Our SDK is developed for Node.js, which makes it compatible with other runtimes through their compatibility layer.
+The bugs in these compatibility layers may introduce issues in our SDK.
+
+## Report issues
+
+If you find any (undocumented) bugs when using the SDK, [submit a GitHub issue](https://github.com/AssemblyAI/assemblyai-node-sdk). We'll try to fix it or at least document the compatibility issue.

package/package.json

@@ -1,10 +1,27 @@
 {
   "name": "assemblyai",
-  "version": "3.1.3",
-  "description": "The AssemblyAI Node.js 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.",
+  "version": "4.0.0-beta.1",
+  "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.",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
+      "node": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.node.mjs",
+        "require": "./dist/index.node.cjs"
+      },
+      "bun": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.node.mjs",
+        "require": "./dist/index.node.cjs"
+      },
+      "deno": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.node.mjs",
+        "require": "./dist/index.node.cjs"
+      },
+      "workerd": "./dist/index.mjs",
+      "browser": "./dist/index.mjs",
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs",
       "default": "./dist/index.cjs"
@@ -12,10 +29,11 @@
     "./package.json": "./package.json"
   },
   "type": "commonjs",
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "typings": "dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "require": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "typings": "./dist/index.d.ts",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AssemblyAI/assemblyai-node-sdk.git"
@@ -29,8 +47,7 @@
     "build": "pnpm clean && pnpm rollup -c",
     "clean": "rimraf dist",
     "lint": "eslint -c .eslintrc.json '{src,tests}/**/*.{js,ts}' && publint",
-    "test": "pnpm lint && pnpm test:unit",
-    "test:unit": "jest --config jest.config.rollup.ts",
+    "test": "jest --config jest.config.rollup.ts",
     "format": "prettier '**/*' --write",
     "generate-types": "tsx ./scripts/generate-types.ts && pnpm format",
     "copybara:dry-run": "./copybara.sh dry_run --init-history",
@@ -48,11 +65,19 @@
   "homepage": "https://www.assemblyai.com/docs",
   "files": [
     "dist",
-    "src"
+    "src",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md",
+    "docs"
   ],
   "devDependencies": {
+    "@rollup/plugin-alias": "^5.0.1",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
     "@types/jest": "^29.5.5",
     "@types/node": "^20.5.7",
+    "@types/websocket": "^1.0.8",
     "@types/ws": "^8.5.5",
     "@typescript-eslint/eslint-plugin": "^6.7.5",
     "dotenv": "^16.3.1",
@@ -78,6 +103,8 @@
     "typescript": "^5.2.2"
   },
   "dependencies": {
+    "@swimburger/isomorphic-streams": "^1.1.1",
+    "isomorphic-ws": "^5.0.0",
     "ws": "^8.13.0"
   }
-}
+}

package/src/polyfills/no-fs.ts

@@ -0,0 +1,8 @@
+function throwError() {
+  throw new Error("'fs' is not supported in this environment.");
+}
+
+export const createReadStream = throwError;
+export default {
+  createReadStream,
+};

package/src/services/files/index.ts

@@ -1,5 +1,3 @@
-// import the fs module instead if specific named exports
-// to keep the assemblyai module more compatible. Some fs polyfills don't include `createReadStream`.
 import fs from "fs";
 import { BaseService } from "../base";
 import { UploadedFile, FileUploadParams, FileUploadData } from "../..";

package/src/services/realtime/service.ts

@@ -1,4 +1,6 @@
-import WebSocket from "ws";
+import { WritableStream } from "@swimburger/isomorphic-streams";
+import WebSocket from "isomorphic-ws";
+import { ErrorEvent, MessageEvent, CloseEvent } from "ws";
 import {
   RealtimeEvents,
   RealtimeListeners,
@@ -14,7 +16,6 @@ import {
   RealtimeErrorMessages,
   RealtimeErrorType,
 } from "../../utils/errors";
-import Stream from "stream";
 
 const defaultRealtimeUrl = "wss://api.assemblyai.com/v2/realtime/ws";
 
@@ -32,8 +33,8 @@ export class RealtimeService {
     this.realtimeUrl = params.realtimeUrl ?? defaultRealtimeUrl;
     this.sampleRate = params.sampleRate ?? 16_000;
     this.wordBoost = params.wordBoost;
-    if ("apiKey" in params) this.apiKey = params.apiKey;
-    if ("token" in params) this.token = params.token;
+    if ("apiKey" in params && params.apiKey) this.apiKey = params.apiKey;
+    if ("token" in params && params.token) this.token = params.token;
 
     if (!(this.apiKey || this.token)) {
       throw new Error("API key or temporary token is required.");
@@ -88,16 +89,15 @@ export class RealtimeService {
 
       const url = this.connectionUrl();
 
-      let headers;
       if (this.token) {
-        headers = undefined;
-      } else if (this.apiKey) {
-        headers = { Authorization: this.apiKey };
+        this.socket = new WebSocket(url.toString());
+      } else {
+        this.socket = new WebSocket(url.toString(), {
+          headers: { Authorization: this.apiKey },
+        });
       }
 
-      this.socket = new WebSocket(url.toString(), { headers });
-
-      this.socket.onclose = ({ code, reason }: WebSocket.CloseEvent) => {
+      this.socket.onclose = ({ code, reason }: CloseEvent) => {
         if (!reason) {
           if (code in RealtimeErrorType) {
             reason = RealtimeErrorMessages[code as RealtimeErrorType];
@@ -106,12 +106,12 @@ export class RealtimeService {
         this.listeners.close?.(code, reason);
       };
 
-      this.socket.onerror = (errorEvent: WebSocket.ErrorEvent) => {
-        if (errorEvent.error) this.listeners.error?.(errorEvent.error as Error);
-        else this.listeners.error?.(new Error(errorEvent.message));
+      this.socket.onerror = (event: ErrorEvent) => {
+        if (event.error) this.listeners.error?.(event.error as Error);
+        else this.listeners.error?.(new Error(event.message));
       };
 
-      this.socket.onmessage = ({ data }: WebSocket.MessageEvent) => {
+      this.socket.onmessage = ({ data }: MessageEvent) => {
         const message = JSON.parse(data.toString()) as RealtimeMessage;
         if ("error" in message) {
           this.listeners.error?.(new RealtimeError(message.error));
@@ -150,25 +150,35 @@ export class RealtimeService {
     });
   }
 
-  sendAudio(audio: ArrayBuffer) {
+  sendAudio(audio: ArrayBufferLike) {
     if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
       throw new Error("Socket is not open for communication");
     }
-
+    let audioData;
+    if (typeof Buffer !== "undefined") {
+      audioData = Buffer.from(audio).toString("base64");
+    } else {
+      // Buffer is not available in the browser by default
+      // https://stackoverflow.com/a/42334410/2919731
+      audioData = btoa(
+        new Uint8Array(audio).reduce(
+          (data, byte) => data + String.fromCharCode(byte),
+          ""
+        )
+      );
+    }
     const payload = {
-      audio_data: Buffer.from(audio).toString("base64"),
+      audio_data: audioData,
     };
     this.socket.send(JSON.stringify(payload));
   }
 
-  stream(): NodeJS.WritableStream {
-    const stream = new Stream.Writable({
-      write: (chunk: Buffer, encoding, next) => {
+  stream(): WritableStream<ArrayBufferLike> {
+    return new WritableStream<ArrayBufferLike>({
+      write: (chunk: ArrayBufferLike) => {
         this.sendAudio(chunk);
-        next();
       },
     });
-    return stream;
   }
 
   async close(waitForSessionTermination = true) {
@@ -185,7 +195,7 @@ export class RealtimeService {
           this.socket.send(terminateSessionMessage);
         }
       }
-      this.socket.removeAllListeners();
+      if ("removeAllListeners" in this.socket) this.socket.removeAllListeners();
       this.socket.close();
     }