assemblyai 4.0.0-beta.0 → 4.0.0-beta.2

package/dist/node.mjs

@@ -0,0 +1,542 @@
+import { WritableStream } from '@swimburger/isomorphic-streams';
+import WebSocket from 'isomorphic-ws';
+import { createReadStream } from 'fs';
+import { Readable } from 'stream';
+
+/**
+ * Base class for services that communicate with the API.
+ */
+class BaseService {
+    /**
+     * Create a new service.
+     * @param params The parameters to use for the service.
+     */
+    constructor(params) {
+        this.params = params;
+    }
+    async fetch(input, init) {
+        init = init ?? {};
+        init.headers = init.headers ?? {};
+        init.headers = {
+            Authorization: this.params.apiKey,
+            "Content-Type": "application/json",
+            ...init.headers,
+        };
+        if (!input.startsWith("http"))
+            input = this.params.baseUrl + input;
+        const response = await fetch(input, init);
+        if (response.status >= 400) {
+            let json;
+            const text = await response.text();
+            if (text) {
+                try {
+                    json = JSON.parse(text);
+                }
+                catch {
+                    /* empty */
+                }
+                if (json?.error)
+                    throw new Error(json.error);
+                throw new Error(text);
+            }
+            throw new Error(`HTTP Error: ${response.status} ${response.statusText}`);
+        }
+        return response;
+    }
+    async fetchJson(input, init) {
+        const response = await this.fetch(input, init);
+        return response.json();
+    }
+}
+
+class LemurService extends BaseService {
+    summary(params) {
+        return this.fetchJson("/lemur/v3/generate/summary", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    questionAnswer(params) {
+        return this.fetchJson("/lemur/v3/generate/question-answer", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    actionItems(params) {
+        return this.fetchJson("/lemur/v3/generate/action-items", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    task(params) {
+        return this.fetchJson("/lemur/v3/generate/task", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+    }
+    /**
+     * Delete the data for a previously submitted LeMUR request.
+     * @param id ID of the LeMUR request
+     */
+    purgeRequestData(id) {
+        return this.fetchJson(`/lemur/v3/${id}`, {
+            method: "DELETE",
+        });
+    }
+}
+
+var RealtimeErrorType;
+(function (RealtimeErrorType) {
+    RealtimeErrorType[RealtimeErrorType["BadSampleRate"] = 4000] = "BadSampleRate";
+    RealtimeErrorType[RealtimeErrorType["AuthFailed"] = 4001] = "AuthFailed";
+    // Both InsufficientFunds and FreeAccount error use 4002
+    RealtimeErrorType[RealtimeErrorType["InsufficientFundsOrFreeAccount"] = 4002] = "InsufficientFundsOrFreeAccount";
+    RealtimeErrorType[RealtimeErrorType["NonexistentSessionId"] = 4004] = "NonexistentSessionId";
+    RealtimeErrorType[RealtimeErrorType["SessionExpired"] = 4008] = "SessionExpired";
+    RealtimeErrorType[RealtimeErrorType["ClosedSession"] = 4010] = "ClosedSession";
+    RealtimeErrorType[RealtimeErrorType["RateLimited"] = 4029] = "RateLimited";
+    RealtimeErrorType[RealtimeErrorType["UniqueSessionViolation"] = 4030] = "UniqueSessionViolation";
+    RealtimeErrorType[RealtimeErrorType["SessionTimeout"] = 4031] = "SessionTimeout";
+    RealtimeErrorType[RealtimeErrorType["AudioTooShort"] = 4032] = "AudioTooShort";
+    RealtimeErrorType[RealtimeErrorType["AudioTooLong"] = 4033] = "AudioTooLong";
+    RealtimeErrorType[RealtimeErrorType["BadJson"] = 4100] = "BadJson";
+    RealtimeErrorType[RealtimeErrorType["BadSchema"] = 4101] = "BadSchema";
+    RealtimeErrorType[RealtimeErrorType["TooManyStreams"] = 4102] = "TooManyStreams";
+    RealtimeErrorType[RealtimeErrorType["Reconnected"] = 4103] = "Reconnected";
+    RealtimeErrorType[RealtimeErrorType["ReconnectAttemptsExhausted"] = 1013] = "ReconnectAttemptsExhausted";
+})(RealtimeErrorType || (RealtimeErrorType = {}));
+const RealtimeErrorMessages = {
+    [RealtimeErrorType.BadSampleRate]: "Sample rate must be a positive integer",
+    [RealtimeErrorType.AuthFailed]: "Not Authorized",
+    [RealtimeErrorType.InsufficientFundsOrFreeAccount]: "Insufficient funds or you are using a free account. This feature is paid-only and requires you to add a credit card. Please visit https://assemblyai.com/dashboard/ to add a credit card to your account.",
+    [RealtimeErrorType.NonexistentSessionId]: "Session ID does not exist",
+    [RealtimeErrorType.SessionExpired]: "Session has expired",
+    [RealtimeErrorType.ClosedSession]: "Session is closed",
+    [RealtimeErrorType.RateLimited]: "Rate limited",
+    [RealtimeErrorType.UniqueSessionViolation]: "Unique session violation",
+    [RealtimeErrorType.SessionTimeout]: "Session Timeout",
+    [RealtimeErrorType.AudioTooShort]: "Audio too short",
+    [RealtimeErrorType.AudioTooLong]: "Audio too long",
+    [RealtimeErrorType.BadJson]: "Bad JSON",
+    [RealtimeErrorType.BadSchema]: "Bad schema",
+    [RealtimeErrorType.TooManyStreams]: "Too many streams",
+    [RealtimeErrorType.Reconnected]: "Reconnected",
+    [RealtimeErrorType.ReconnectAttemptsExhausted]: "Reconnect attempts exhausted",
+};
+class RealtimeError extends Error {
+}
+
+const defaultRealtimeUrl = "wss://api.assemblyai.com/v2/realtime/ws";
+class RealtimeService {
+    constructor(params) {
+        this.listeners = {};
+        this.realtimeUrl = params.realtimeUrl ?? defaultRealtimeUrl;
+        this.sampleRate = params.sampleRate ?? 16000;
+        this.wordBoost = params.wordBoost;
+        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.");
+        }
+    }
+    connectionUrl() {
+        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;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    on(event, listener) {
+        this.listeners[event] = listener;
+    }
+    connect() {
+        return new Promise((resolve) => {
+            if (this.socket) {
+                throw new Error("Already connected");
+            }
+            const url = this.connectionUrl();
+            if (this.token) {
+                this.socket = new WebSocket(url.toString());
+            }
+            else {
+                this.socket = new WebSocket(url.toString(), {
+                    headers: { Authorization: this.apiKey },
+                });
+            }
+            this.socket.onclose = ({ code, reason }) => {
+                if (!reason) {
+                    if (code in RealtimeErrorType) {
+                        reason = RealtimeErrorMessages[code];
+                    }
+                }
+                this.listeners.close?.(code, reason);
+            };
+            this.socket.onerror = (event) => {
+                if (event.error)
+                    this.listeners.error?.(event.error);
+                else
+                    this.listeners.error?.(new Error(event.message));
+            };
+            this.socket.onmessage = ({ data }) => {
+                const message = JSON.parse(data.toString());
+                if ("error" in message) {
+                    this.listeners.error?.(new RealtimeError(message.error));
+                    return;
+                }
+                switch (message.message_type) {
+                    case "SessionBegins": {
+                        const openObject = {
+                            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) {
+        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: audioData,
+        };
+        this.socket.send(JSON.stringify(payload));
+    }
+    stream() {
+        return new WritableStream({
+            write: (chunk) => {
+                this.sendAudio(chunk);
+            },
+        });
+    }
+    async close(waitForSessionTermination = true) {
+        if (this.socket) {
+            if (this.socket.readyState === WebSocket.OPEN) {
+                const terminateSessionMessage = `{"terminate_session": true}`;
+                if (waitForSessionTermination) {
+                    const sessionTerminatedPromise = new Promise((resolve) => {
+                        this.sessionTerminatedResolve = resolve;
+                    });
+                    this.socket.send(terminateSessionMessage);
+                    await sessionTerminatedPromise;
+                }
+                else {
+                    this.socket.send(terminateSessionMessage);
+                }
+            }
+            if ("removeAllListeners" in this.socket)
+                this.socket.removeAllListeners();
+            this.socket.close();
+        }
+        this.listeners = {};
+        this.socket = undefined;
+    }
+}
+
+class RealtimeServiceFactory extends BaseService {
+    constructor(params) {
+        super(params);
+        this.rtFactoryParams = params;
+    }
+    createService(params) {
+        if (!params)
+            params = { apiKey: this.rtFactoryParams.apiKey };
+        else if (!("token" in params) && !params.apiKey) {
+            params.apiKey = this.rtFactoryParams.apiKey;
+        }
+        return new RealtimeService(params);
+    }
+    async createTemporaryToken(params) {
+        const data = await this.fetchJson("/v2/realtime/token", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+        return data.token;
+    }
+}
+
+class TranscriptService extends BaseService {
+    constructor(params, files) {
+        super(params);
+        this.files = files;
+    }
+    /**
+     * Transcribe an audio file. This will create a transcript and wait until the transcript status is "completed" or "error".
+     * @param params The parameters to transcribe an audio file.
+     * @param options The options to transcribe an audio file.
+     * @returns A promise that resolves to the transcript. The transcript status is "completed" or "error".
+     */
+    async transcribe(params, options) {
+        const transcript = await this.submit(params);
+        return await this.waitUntilReady(transcript.id, options);
+    }
+    /**
+     * Submits a transcription job for an audio file. This will not wait until the transcript status is "completed" or "error".
+     * @param params The parameters to start the transcription of an audio file.
+     * @returns A promise that resolves to the queued transcript.
+     */
+    async submit(params) {
+        const { audio, ...createParams } = params;
+        let audioUrl;
+        if (typeof audio === "string") {
+            const path = getPath(audio);
+            if (path !== null) {
+                // 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;
+            }
+        }
+        else {
+            // audio is of uploadable type
+            audioUrl = await this.files.upload(audio);
+        }
+        const data = await this.fetchJson("/v2/transcript", {
+            method: "POST",
+            body: JSON.stringify({ ...createParams, audio_url: audioUrl }),
+        });
+        return data;
+    }
+    /**
+     * Create a transcript.
+     * @param params The parameters to create a transcript.
+     * @param options The options used for creating the new transcript.
+     * @returns A promise that resolves to the transcript.
+     * @deprecated Use `transcribe` instead to transcribe a audio file that includes polling, or `submit` to transcribe a audio file without polling.
+     */
+    async create(params, options) {
+        const path = getPath(params.audio_url);
+        if (path !== null) {
+            const uploadUrl = await this.files.upload(path);
+            params.audio_url = uploadUrl;
+        }
+        const data = await this.fetchJson("/v2/transcript", {
+            method: "POST",
+            body: JSON.stringify(params),
+        });
+        if (options?.poll ?? true) {
+            return await this.waitUntilReady(data.id, options);
+        }
+        return data;
+    }
+    /**
+     * Wait until the transcript ready, either the status is "completed" or "error".
+     * @param transcriptId The ID of the transcript.
+     * @param options The options to wait until the transcript is ready.
+     * @returns A promise that resolves to the transcript. The transcript status is "completed" or "error".
+     */
+    async waitUntilReady(transcriptId, options) {
+        const pollingInterval = options?.pollingInterval ?? 3000;
+        const pollingTimeout = options?.pollingTimeout ?? -1;
+        const startTime = Date.now();
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            const transcript = await this.get(transcriptId);
+            if (transcript.status === "completed" || transcript.status === "error") {
+                return transcript;
+            }
+            else if (pollingTimeout > 0 &&
+                Date.now() - startTime > pollingTimeout) {
+                throw new Error("Polling timeout");
+            }
+            else {
+                await new Promise((resolve) => setTimeout(resolve, pollingInterval));
+            }
+        }
+    }
+    /**
+     * Retrieve a transcript.
+     * @param id The identifier of the transcript.
+     * @returns A promise that resolves to the transcript.
+     */
+    get(id) {
+        return this.fetchJson(`/v2/transcript/${id}`);
+    }
+    /**
+     * Retrieves a page of transcript listings.
+     * @param parameters The parameters to filter the transcript list by, or the URL to retrieve the transcript list from.
+     */
+    async list(parameters) {
+        let url = "/v2/transcript";
+        if (typeof parameters === "string") {
+            url = parameters;
+        }
+        else if (parameters) {
+            url = `${url}?${new URLSearchParams(Object.keys(parameters).map((key) => [
+                key,
+                parameters[key]?.toString() || "",
+            ]))}`;
+        }
+        const data = await this.fetchJson(url);
+        for (const transcriptListItem of data.transcripts) {
+            transcriptListItem.created = new Date(transcriptListItem.created);
+            if (transcriptListItem.completed) {
+                transcriptListItem.completed = new Date(transcriptListItem.completed);
+            }
+        }
+        return data;
+    }
+    /**
+     * Delete a transcript
+     * @param id The identifier of the transcript.
+     * @returns A promise that resolves to the transcript.
+     */
+    delete(id) {
+        return this.fetchJson(`/v2/transcript/${id}`, { method: "DELETE" });
+    }
+    /**
+     * Search through the transcript for a specific set of keywords.
+     * You can search for individual words, numbers, or phrases containing up to five words or numbers.
+     * @param id The identifier of the transcript.
+     * @param words Keywords to search for.
+     * @return A promise that resolves to the sentences.
+     */
+    wordSearch(id, words) {
+        const params = new URLSearchParams({ words: words.join(",") });
+        return this.fetchJson(`/v2/transcript/${id}/word-search?${params.toString()}`);
+    }
+    /**
+     * Retrieve all sentences of a transcript.
+     * @param id The identifier of the transcript.
+     * @return A promise that resolves to the sentences.
+     */
+    sentences(id) {
+        return this.fetchJson(`/v2/transcript/${id}/sentences`);
+    }
+    /**
+     * Retrieve all paragraphs of a transcript.
+     * @param id The identifier of the transcript.
+     * @return A promise that resolves to the paragraphs.
+     */
+    paragraphs(id) {
+        return this.fetchJson(`/v2/transcript/${id}/paragraphs`);
+    }
+    /**
+     * Retrieve subtitles of a transcript.
+     * @param id The identifier of the transcript.
+     * @param format The format of the subtitles.
+     * @param chars_per_caption The maximum number of characters per caption.
+     * @return A promise that resolves to the subtitles text.
+     */
+    async subtitles(id, format = "srt", chars_per_caption) {
+        let url = `/v2/transcript/${id}/${format}`;
+        if (chars_per_caption) {
+            const params = new URLSearchParams();
+            params.set("chars_per_caption", chars_per_caption.toString());
+            url += `?${params.toString()}`;
+        }
+        const response = await this.fetch(url);
+        return await response.text();
+    }
+    /**
+     * Retrieve redactions of a transcript.
+     * @param id The identifier of the transcript.
+     * @return A promise that resolves to the subtitles text.
+     */
+    redactions(id) {
+        return this.fetchJson(`/v2/transcript/${id}/redacted-audio`);
+    }
+}
+function getPath(path) {
+    let url;
+    try {
+        url = new URL(path);
+        if (url.protocol === "file:")
+            return url.pathname;
+        else
+            return null;
+    }
+    catch {
+        return path;
+    }
+}
+
+const readFile = async (path) => Readable.toWeb(createReadStream(path));
+
+class FileService extends BaseService {
+    /**
+     * Upload a local file to AssemblyAI.
+     * @param input The local file path to upload, or a stream or buffer of the file to upload.
+     * @return A promise that resolves to the uploaded file URL.
+     */
+    async upload(input) {
+        let fileData;
+        if (typeof input === "string")
+            fileData = await readFile(input);
+        else
+            fileData = input;
+        const data = await this.fetchJson("/v2/upload", {
+            method: "POST",
+            body: fileData,
+            headers: {
+                "Content-Type": "application/octet-stream",
+            },
+            duplex: "half",
+        });
+        return data.upload_url;
+    }
+}
+
+const defaultBaseUrl = "https://api.assemblyai.com";
+class AssemblyAI {
+    /**
+     * Create a new AssemblyAI client.
+     * @param params The parameters for the service, including the API key and base URL, if any.
+     */
+    constructor(params) {
+        params.baseUrl = params.baseUrl || defaultBaseUrl;
+        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);
+        this.realtime = new RealtimeServiceFactory(params);
+    }
+}
+
+export { AssemblyAI, FileService, LemurService, RealtimeService, RealtimeServiceFactory, TranscriptService };

package/dist/services/realtime/service.d.ts

@@ -1,5 +1,3 @@
-/// <reference types="node" />
-import { WritableStream } from "@swimburger/isomorphic-streams";
 import { RealtimeServiceParams, RealtimeTranscript, PartialTranscript, FinalTranscript, SessionBeginsEventData } from "../..";
 export declare class RealtimeService {
     private realtimeUrl;

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.