assemblyai 1.0.1 → 2.0.1-beta

package/dist/types/realtime/index.d.ts

@@ -0,0 +1,36 @@
+import { FinalTranscript, PartialTranscript, RealtimeTranscript, RealtimeTranscriptType } from "../asyncapi.generated";
+type CreateRealtimeServiceParams = {
+    realtimeUrl?: string;
+    sampleRate?: number;
+    wordBoost?: string[];
+} & ({
+    apiKey?: string;
+} | {
+    token: string;
+});
+type RealtimeServiceParams = {
+    realtimeUrl?: string;
+    sampleRate?: number;
+    wordBoost?: string[];
+} & ({
+    apiKey: string;
+} | {
+    token: string;
+});
+type RealtimeEvents = "open" | "close" | "transcript" | "transcript.partial" | "transcript.final" | "error";
+type SessionBeginsEventData = {
+    sessionId: string;
+    expiresAt: Date;
+};
+type RealtimeListeners = {
+    open?: (event: SessionBeginsEventData) => void;
+    close?: (code: number, reason: string) => void;
+    transcript?: (transcript: RealtimeTranscript) => void;
+    "transcript.partial"?: (transcript: PartialTranscript) => void;
+    "transcript.final"?: (transcript: FinalTranscript) => void;
+    error?: (error: Error) => void;
+};
+type RealtimeTokenParams = {
+    expires_in: number;
+};
+export type { CreateRealtimeServiceParams, RealtimeServiceParams, RealtimeEvents, RealtimeTranscriptType, SessionBeginsEventData, RealtimeListeners, RealtimeTokenParams, };

package/dist/types/services/abstractions.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Interface for classes that can create resources.
+ * @template T The type of the resource.
+ * @template Parameters The type of the parameters required to create the resource.
+ */
+interface Createable<T, Parameters, Options = Record<string, any>> {
+    /**
+     * Create a new resource.
+     * @param params The parameters of the new resource.
+     * @param options The options used for creating the new resource.
+     * @return A promise that resolves to the newly created resource.
+     */
+    create(params: Parameters, options?: Options): Promise<T>;
+}
+/**
+ * Interface for classes that can retrieve resources.
+ * @template T The type of the resource.
+ * @template Id The type of the resource's identifier. Defaults to string.
+ */
+interface Retrieveable<T, Id = string> {
+    /**
+     * Get a resource.
+     * @param id The identifier of the resource to retrieve.
+     * @return A promise that resolves to the retrieved resource.
+     */
+    get(id: Id): Promise<T>;
+}
+/**
+ * Interface for classes that can delete resources.
+ * @template T The type of the resource.
+ * @template Id The type of the resource's identifier. Defaults to string.
+ */
+interface Deletable<T, Id = string> {
+    /**
+     * Delete a resource.
+     * @param id The identifier of the resource to delete.
+     * @return A promise that resolves to a boolean indicating whether the deletion was successful.
+     */
+    delete(id: Id): Promise<T>;
+}
+/**
+ * Interface for classes that can list resources.
+ * @template T The type of the resource.
+ */
+interface Listable<T, Page = string> {
+    /**
+     * List all resources.
+     * @return A promise that resolves to an array of resources.
+     */
+    list(page?: Page): Promise<T>;
+}
+export type { Createable, Retrieveable, Deletable, Listable };

package/dist/types/services/index.d.ts

@@ -0,0 +1,6 @@
+type BaseServiceParams = {
+    apiKey: string;
+    baseUrl?: string;
+};
+export type * from "./abstractions";
+export type { BaseServiceParams };

package/dist/types/transcripts/index.d.ts

@@ -0,0 +1,5 @@
+export type CreateTranscriptOptions = {
+    poll?: boolean;
+    pollingInterval?: number;
+    pollingTimeout?: number;
+};

package/dist/utils/axios.d.ts

@@ -0,0 +1,3 @@
+import { BaseServiceParams } from "../.";
+export declare function createAxiosClient(params: BaseServiceParams): import("axios").AxiosInstance;
+export declare function throwApiError(error: unknown): Promise<never>;

package/dist/utils/errors/index.d.ts

@@ -0,0 +1 @@
+export { default as RealtimeError, RealtimeErrorType, RealtimeErrorMessages, } from "./realtime";

package/dist/utils/errors/realtime.d.ts

@@ -0,0 +1,23 @@
+declare enum RealtimeErrorType {
+    BadSampleRate = 4000,
+    AuthFailed = 4001,
+    InsufficientFundsOrFreeAccount = 4002,
+    NonexistentSessionId = 4004,
+    SessionExpired = 4008,
+    ClosedSession = 4010,
+    RateLimited = 4029,
+    UniqueSessionViolation = 4030,
+    SessionTimeout = 4031,
+    AudioTooShort = 4032,
+    AudioTooLong = 4033,
+    BadJson = 4100,
+    BadSchema = 4101,
+    TooManyStreams = 4102,
+    Reconnected = 4103,
+    ReconnectAttemptsExhausted = 1013
+}
+declare const RealtimeErrorMessages: Record<RealtimeErrorType, string>;
+declare class RealtimeError extends Error {
+}
+export { RealtimeErrorType, RealtimeErrorMessages };
+export default RealtimeError;

package/package.json

@@ -1,31 +1,68 @@
 {
   "name": "assemblyai",
-  "version": "1.0.1",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
+  "version": "2.0.1-beta",
+  "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.",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "typings": "dist/index.d.ts",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/AssemblyAI/assemblyai-node-sdk.git"
+    "url": "git+https://github.com/AssemblyAI/assemblyai-typescript-sdk.git"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "bugs": {
-    "url": "https://github.com/AssemblyAI/assemblyai-node-sdk/issues"
+  "publishConfig": {
+    "tag": "beta",
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
-  "homepage": "https://github.com/AssemblyAI/assemblyai-node-sdk#readme",
-  "dependencies": {
-    "request": "^2.88.0"
+  "scripts": {
+    "build": "pnpm clean && pnpm rollup -c",
+    "clean": "rimraf dist",
+    "lint": "tslint -p tsconfig.json",
+    "test": "pnpm lint && pnpm test:unit",
+    "test:unit": "jest --config jest.config.rollup.ts",
+    "prettier": "prettier --write 'src/**/*.ts'",
+    "generate-types": "tsx ./scripts/generate-types.ts && pnpm prettier"
   },
+  "keywords": [
+    "AssemblyAI",
+    "Speech-to-text"
+  ],
+  "author": "AssemblyAI (https://www.assemblyai.com)",
+  "license": "MIT",
+  "homepage": "https://www.assemblyai.com/docs",
+  "files": [
+    "dist",
+    "src",
+    "types"
+  ],
   "devDependencies": {
-    "eslint": "^5.4.0",
-    "eslint-config-standard": "^11.0.0",
-    "eslint-plugin-import": "^2.14.0",
-    "eslint-plugin-node": "^7.0.1",
-    "eslint-plugin-promise": "^4.0.0",
-    "eslint-plugin-standard": "^3.1.0"
+    "@types/jest": "^29.5.5",
+    "@types/node": "^20.5.7",
+    "@types/ws": "^8.5.5",
+    "dotenv": "^16.3.1",
+    "eslint": "^8.43.0",
+    "i": "^0.3.7",
+    "jest": "^29.5.0",
+    "jest-cli": "^29.5.0",
+    "jest-junit": "^16.0.0",
+    "jest-mock-extended": "^3.0.4",
+    "jest-websocket-mock": "^2.4.1",
+    "mock-socket": "^9.2.1",
+    "npm": "^9.7.1",
+    "openapi-typescript": "^6.6.1",
+    "prettier": "^2.8.8",
+    "rimraf": "^5.0.1",
+    "rollup": "^3.25.1",
+    "rollup-plugin-typescript2": "^0.34.1",
+    "ts-jest": "^29.1.0",
+    "ts-node": "^10.9.1",
+    "tslib": "^2.5.3",
+    "tslint": "^6.1.3",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "axios": "^1.4.0",
+    "ws": "^8.13.0"
   }
 }

package/src/index.ts

@@ -0,0 +1,5 @@
+import AssemblyAI from "./services";
+
+export * from "./services";
+export type * from "./types";
+export default AssemblyAI;

package/src/services/base.ts

@@ -0,0 +1,14 @@
+import { AxiosInstance } from "axios";
+
+/**
+ * Base class for services that communicate with the API.
+ */
+abstract class BaseService {
+  /**
+   * Create a new service.
+   * @param params The AxiosInstance to send HTTP requests to the API.
+   */
+  constructor(protected client: AxiosInstance) {}
+}
+
+export default BaseService;

package/src/services/files/index.ts

@@ -0,0 +1,22 @@
+import { readFile } from "fs/promises";
+import BaseService from "@/services/base";
+import { UploadedFile } from "@/types";
+
+export default class FileService extends BaseService {
+  /**
+   * Upload a local file to AssemblyAI.
+   * @param path The local file to upload.
+   * @return A promise that resolves to the uploaded file URL.
+   */
+  async upload(path: string): Promise<string> {
+    const file = await readFile(path);
+
+    const { data } = await this.client.post<UploadedFile>("/v2/upload", file, {
+      headers: {
+        "Content-Type": "application/octet-stream",
+      },
+    });
+
+    return data.upload_url;
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,49 @@
+import { createAxiosClient } from "@/utils/axios";
+import { BaseServiceParams } from "@/types";
+import LemurService from "./lemur";
+import { RealtimeService, RealtimeServiceFactory } from "./realtime";
+import TranscriptService from "./transcripts";
+import FileService from "./files";
+
+export default class AssemblyAI {
+  /**
+   * The files service.
+   */
+  public files: FileService;
+
+  /**
+   * The transcripts service.
+   */
+  public transcripts: TranscriptService;
+
+  /**
+   * The LeMUR service.
+   */
+  public lemur: LemurService;
+
+  /**
+   * The realtime service.
+   */
+  public realtime: RealtimeServiceFactory;
+
+  /**
+   * Create a new AssemblyAI client.
+   * @param params The parameters for the service, including the API key and base URL, if any.
+   */
+  constructor(params: BaseServiceParams) {
+    params.baseUrl = params.baseUrl || "https://api.assemblyai.com";
+    const client = createAxiosClient(params);
+    this.files = new FileService(client);
+    this.transcripts = new TranscriptService(client, this.files);
+    this.lemur = new LemurService(client);
+    this.realtime = new RealtimeServiceFactory(client, params);
+  }
+}
+
+export {
+  LemurService,
+  RealtimeServiceFactory,
+  RealtimeService,
+  TranscriptService,
+  FileService,
+};

package/src/services/lemur/index.ts

@@ -0,0 +1,49 @@
+import {
+  LemurSummaryParameters,
+  LemurActionItemsParameters,
+  LemurQuestionAnswerParameters,
+  LemurTaskParameters,
+  LemurSummaryResponse,
+  LemurQuestionAnswerResponse,
+  LemurActionItemsResponse,
+  LemurTaskResponse,
+} from "@/types";
+import BaseService from "@/services/base";
+
+export default class LemurService extends BaseService {
+  async summary(params: LemurSummaryParameters): Promise<LemurSummaryResponse> {
+    const { data } = await this.client.post<LemurSummaryResponse>(
+      "/lemur/v3/generate/summary",
+      params
+    );
+    return data;
+  }
+
+  async questionAnswer(
+    params: LemurQuestionAnswerParameters
+  ): Promise<LemurQuestionAnswerResponse> {
+    const { data } = await this.client.post<LemurQuestionAnswerResponse>(
+      "/lemur/v3/generate/question-answer",
+      params
+    );
+    return data;
+  }
+
+  async actionItems(
+    params: LemurActionItemsParameters
+  ): Promise<LemurActionItemsResponse> {
+    const { data } = await this.client.post<LemurActionItemsResponse>(
+      "/lemur/v3/generate/action-items",
+      params
+    );
+    return data;
+  }
+
+  async task(params: LemurTaskParameters): Promise<LemurTaskResponse> {
+    const { data } = await this.client.post<LemurTaskResponse>(
+      "/lemur/v3/generate/task",
+      params
+    );
+    return data;
+  }
+}

package/src/services/realtime/factory.ts

@@ -0,0 +1,32 @@
+import {
+  BaseServiceParams,
+  RealtimeTokenParams,
+  CreateRealtimeServiceParams,
+  RealtimeServiceParams,
+} from "@/types";
+import { AxiosInstance } from "axios";
+import { RealtimeService } from "./service";
+
+export class RealtimeServiceFactory {
+  constructor(
+    private client: AxiosInstance,
+    private params: BaseServiceParams
+  ) {}
+
+  createService(params?: CreateRealtimeServiceParams): RealtimeService {
+    if (!params) params = { apiKey: this.params.apiKey };
+    else if (!("token" in params) && !params.apiKey) {
+      params.apiKey = this.params.apiKey;
+    }
+
+    return new RealtimeService(params as RealtimeServiceParams);
+  }
+
+  async createTemporaryToken(params: RealtimeTokenParams) {
+    const response = await this.client.post<{ token: string }>(
+      "/v2/realtime/token",
+      params
+    );
+    return response.data.token;
+  }
+}

package/src/services/realtime/index.ts

@@ -0,0 +1,2 @@
+export * from "@/services/realtime/factory";
+export * from "@/services/realtime/service";

package/src/services/realtime/service.ts

@@ -0,0 +1,184 @@
+import WebSocket from "ws";
+import {
+  RealtimeEvents,
+  RealtimeListeners,
+  RealtimeServiceParams,
+  RealtimeMessage,
+  RealtimeTranscript,
+  PartialTranscript,
+  FinalTranscript,
+  SessionBeginsEventData,
+} from "@/types";
+import {
+  RealtimeError,
+  RealtimeErrorMessages,
+  RealtimeErrorType,
+} from "@/utils/errors";
+
+const defaultRealtimeUrl = "wss://api.assemblyai.com/v2/realtime/ws";
+
+export class RealtimeService {
+  private realtimeUrl: string;
+  private sampleRate: number;
+  private wordBoost?: string[];
+  private apiKey?: string;
+  private token?: string;
+  private socket?: WebSocket;
+  private listeners: RealtimeListeners = {};
+  private sessionTerminatedResolve?: () => void;
+
+  constructor(params: RealtimeServiceParams) {
+    this.realtimeUrl = params.realtimeUrl ?? defaultRealtimeUrl;
+    this.sampleRate = params.sampleRate ?? 16_000;
+    this.wordBoost = params.wordBoost;
+    this.realtimeUrl = params.realtimeUrl ?? defaultRealtimeUrl;
+    if ("apiKey" in params) this.apiKey = params.apiKey;
+    if ("token" in params) this.token = params.token;
+
+    if (!(this.apiKey || this.token)) {
+      throw new Error("API key or temporary token is required.");
+    }
+  }
+
+  private connectionUrl(): URL {
+    const url = new URL(this.realtimeUrl);
+
+    if (url.protocol !== "wss:") {
+      throw new Error("Invalid protocol, must be wss");
+    }
+
+    const searchParams = new URLSearchParams();
+    if (this.token) {
+      searchParams.set("token", this.token);
+    }
+    searchParams.set("sample_rate", this.sampleRate.toString());
+    if (this.wordBoost && this.wordBoost.length > 0) {
+      searchParams.set("word_boost", JSON.stringify(this.wordBoost));
+    }
+    url.search = searchParams.toString();
+
+    return url;
+  }
+
+  on(event: "open", listener: (event: SessionBeginsEventData) => void): void;
+  on(
+    event: "transcript",
+    listener: (transcript: RealtimeTranscript) => void
+  ): void;
+  on(
+    event: "transcript.partial",
+    listener: (transcript: PartialTranscript) => void
+  ): void;
+  on(
+    event: "transcript.final",
+    listener: (transcript: FinalTranscript) => void
+  ): void;
+  on(event: "error", listener: (error: Error) => void): void;
+  on(event: "close", listener: (code: number, reason: string) => void): void;
+  on(event: RealtimeEvents, listener: (...args: any[]) => void) {
+    this.listeners[event] = listener;
+  }
+
+  connect() {
+    return new Promise<SessionBeginsEventData>((resolve, _) => {
+      if (this.socket) {
+        throw new Error("Already connected");
+      }
+
+      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(), { headers });
+
+      this.socket.onclose = ({ code, reason }: WebSocket.CloseEvent) => {
+        if (!reason) {
+          if (code in RealtimeErrorType) {
+            reason = RealtimeErrorMessages[code as RealtimeErrorType];
+          }
+        }
+        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.onmessage = ({ data }: WebSocket.MessageEvent) => {
+        const message = JSON.parse(data.toString()) as RealtimeMessage;
+        if ("error" in message) {
+          this.listeners.error?.(new RealtimeError(message.error));
+          return;
+        }
+        switch (message.message_type) {
+          case "SessionBegins": {
+            const openObject: SessionBeginsEventData = {
+              sessionId: message.session_id,
+              expiresAt: new Date(message.expires_at),
+            };
+            resolve(openObject);
+            this.listeners.open?.(openObject);
+            break;
+          }
+          case "PartialTranscript": {
+            // message.created is actually a string when coming from the socket
+            message.created = new Date(message.created);
+            this.listeners.transcript?.(message);
+            this.listeners["transcript.partial"]?.(message);
+            break;
+          }
+          case "FinalTranscript": {
+            // message.created is actually a string when coming from the socket
+            message.created = new Date(message.created);
+            this.listeners.transcript?.(message);
+            this.listeners["transcript.final"]?.(message);
+            break;
+          }
+          case "SessionTerminated": {
+            this.sessionTerminatedResolve?.();
+            break;
+          }
+        }
+      };
+    });
+  }
+
+  sendAudio(audio: ArrayBuffer) {
+    if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+      throw new Error("Socket is not open for communication");
+    }
+
+    const payload = {
+      audio_data: Buffer.from(audio).toString("base64"),
+    };
+    this.socket.send(JSON.stringify(payload));
+  }
+
+  async close(waitForSessionTermination = true) {
+    if (this.socket) {
+      if (this.socket.readyState === WebSocket.OPEN) {
+        const terminateSessionMessage = `{"terminate_session": true}`;
+        if (waitForSessionTermination) {
+          const sessionTerminatedPromise = new Promise<void>((resolve, _) => {
+            this.sessionTerminatedResolve = resolve;
+          });
+          this.socket.send(terminateSessionMessage);
+          await sessionTerminatedPromise;
+        } else {
+          this.socket.send(terminateSessionMessage);
+        }
+      }
+      this.socket.removeAllListeners();
+      this.socket.close();
+    }
+
+    this.listeners = {};
+    this.socket = undefined;
+  }
+}