assemblyai 2.0.0-beta → 2.0.1

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;
+  }
+}

package/src/services/transcripts/index.ts

@@ -1,55 +1,42 @@
 import BaseService from "@/services/base";
-import TranscriptSubtitleService from "./subtitles";
 import {
-  ParagraphsBody,
-  SegmentType,
-  SentencesBody,
+  ParagraphsResponse,
+  SentencesResponse,
   Transcript,
   TranscriptList,
-  TranscriptParams,
-  TranscriptPollingSettings,
+  CreateTranscriptParameters,
+  CreateTranscriptOptions,
   Createable,
   Deletable,
   Listable,
   Retrieveable,
-  TranscriptListInternal,
-  TranscriptListItemInternal,
-  TranscriptListItem,
+  SubtitleFormat,
+  RedactedAudioResponse,
 } from "@/types";
-import TranscriptRedactionService from "./redactions";
 import { AxiosInstance } from "axios";
 import FileService from "../files";
 
 export default class TranscriptService
   extends BaseService
   implements
-    Createable<Transcript, TranscriptParams, TranscriptPollingSettings>,
+    Createable<Transcript, CreateTranscriptParameters, CreateTranscriptOptions>,
     Retrieveable<Transcript>,
     Deletable<Transcript>,
     Listable<TranscriptList>
 {
-  /**
-   * The subtitles service.
-   */
-  public subtitles: TranscriptSubtitleService;
-
-  /**
-   * The redactions service.
-   */
-  public redactions: TranscriptRedactionService;
-
   constructor(client: AxiosInstance, private files: FileService) {
     super(client);
-    this.subtitles = new TranscriptSubtitleService(client);
-    this.redactions = new TranscriptRedactionService(client);
   }
 
+  /**
+   * 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 newly created transcript.
+   */
   async create(
-    params: TranscriptParams,
-    settings: TranscriptPollingSettings | null = {
-      pollingInterval: 3000,
-      pollingTimeout: 180000,
-    }
+    params: CreateTranscriptParameters,
+    options?: CreateTranscriptOptions
   ): Promise<Transcript> {
     const path = getPath(params.audio_url);
     if (path !== null) {
@@ -59,8 +46,8 @@ export default class TranscriptService
 
     const res = await this.client.post<Transcript>("/v2/transcript", params);
 
-    if (settings && settings.pollingInterval) {
-      return await this.poll(res.data.id, settings);
+    if (options?.poll ?? true) {
+      return await this.poll(res.data.id, options);
     }
 
     return res.data;
@@ -68,79 +55,114 @@ export default class TranscriptService
 
   private async poll(
     transcriptId: string,
-    settings: TranscriptPollingSettings
+    options?: CreateTranscriptOptions
   ): Promise<Transcript> {
-    const {
-      pollingInterval,
-      pollingTimeout,
-      resolver = (t) => t.status === "completed" || t.status === "error",
-    } = settings;
     const startTime = Date.now();
-
     while (true) {
-      const transcript = await this.retrieve(transcriptId);
-      if (resolver(transcript)) {
+      const transcript = await this.get(transcriptId);
+      if (transcript.status === "completed" || transcript.status === "error") {
         return transcript;
-      } else if (Date.now() - startTime < pollingTimeout) {
-        await new Promise((resolve) => setTimeout(resolve, pollingInterval));
+      } else if (
+        Date.now() - startTime <
+        (options?.pollingTimeout ?? 180_000)
+      ) {
+        await new Promise((resolve) =>
+          setTimeout(resolve, options?.pollingInterval ?? 3_000)
+        );
       } else {
         throw new Error("Polling timeout");
       }
     }
   }
 
-  async retrieve(id: string): Promise<Transcript> {
+  /**
+   * Retrieve a transcript.
+   * @param id The identifier of the transcript.
+   * @returns A promise that resolves to the transcript.
+   */
+  async get(id: string): Promise<Transcript> {
     const res = await this.client.get<Transcript>(`/v2/transcript/${id}`);
     return res.data;
   }
 
-  async list(nextUrl?: string): Promise<TranscriptList> {
-    const { data } = await this.client.get<TranscriptListInternal>(
-      nextUrl || "/v2/transcript"
+  // TODO: add options overload to support list querystring parameters
+  /**
+   * Retrieves a paged list of transcript listings.
+   * @param nextUrl The URL to retrieve the transcript list from. If not provided, the first page will be retrieved.
+   * @returns
+   */
+  async list(nextUrl?: string | null): Promise<TranscriptList> {
+    const { data } = await this.client.get<TranscriptList>(
+      nextUrl ?? "/v2/transcript"
     );
-    for (const transcriptListItem of data.transcripts as unknown as (
-      | TranscriptListItemInternal
-      | TranscriptListItem
-    )[]) {
+    for (const transcriptListItem of data.transcripts) {
       transcriptListItem.created = new Date(transcriptListItem.created);
-      transcriptListItem.completed = new Date(transcriptListItem.completed);
+      if (transcriptListItem.completed) {
+        transcriptListItem.completed = new Date(transcriptListItem.completed);
+      }
     }
 
     return data as unknown as TranscriptList;
   }
 
+  /**
+   * Delete a transcript
+   * @param id The identifier of the transcript.
+   * @returns A promise that resolves to the transcript.
+   */
   async delete(id: string): Promise<Transcript> {
     const res = await this.client.delete<Transcript>(`/v2/transcript/${id}`);
     return res.data;
   }
 
   /**
-   * Retrieve all segments of a transcript.
+   * Retrieve all sentences of a transcript.
+   * @param id The identifier of the transcript.
+   * @return A promise that resolves to the sentences.
+   */
+  async sentences(id: string): Promise<SentencesResponse> {
+    const { data } = await this.client.get<SentencesResponse>(
+      `/v2/transcript/${id}/sentences`
+    );
+    return data;
+  }
+
+  /**
+   * Retrieve all paragraphs of a transcript.
    * @param id The identifier of the transcript.
-   * @param type The type of segment to retrieve.
-   * @return A promise that resolves to the retrieved resource.
+   * @return A promise that resolves to the paragraphs.
    */
-  private async segments<T>(id: string, type: SegmentType): Promise<T> {
-    const { data } = await this.client.get<T>(`/v2/transcript/${id}/${type}`);
+  async paragraphs(id: string): Promise<ParagraphsResponse> {
+    const { data } = await this.client.get<ParagraphsResponse>(
+      `/v2/transcript/${id}/paragraphs`
+    );
     return data;
   }
 
   /**
-   * Retrieve all sentences of a transcript.
+   * Retrieve subtitles of a transcript.
    * @param id The identifier of the transcript.
-   * @return A promise that resolves to the sentences.
+   * @param format The format of the subtitles.
+   * @return A promise that resolves to the subtitles text.
    */
-  async sentences(id: string): Promise<SentencesBody> {
-    return this.segments<SentencesBody>(id, "sentences");
+  async subtitles(id: string, format: SubtitleFormat = "srt"): Promise<string> {
+    const { data } = await this.client.get<string>(
+      `/v2/transcript/${id}/${format}`
+    );
+
+    return data;
   }
 
   /**
-   * Retrieve all paragraphs of a transcript.
+   * Retrieve redactions of a transcript.
    * @param id The identifier of the transcript.
-   * @return A promise that resolves to the paragraphs.
+   * @return A promise that resolves to the subtitles text.
    */
-  async paragraphs(id: string): Promise<ParagraphsBody> {
-    return this.segments<ParagraphsBody>(id, "paragraphs");
+  async redactions(id: string): Promise<RedactedAudioResponse> {
+    const { data } = await this.client.get<RedactedAudioResponse>(
+      `/v2/transcript/${id}/redacted-audio`
+    );
+    return data;
   }
 }
 

package/src/types/asyncapi.generated.ts

@@ -0,0 +1,124 @@
+// this file is generated by typescript/scripts/generate-types.ts
+/* tslint:disable */
+/* eslint-disable */
+
+/** OneOf type helpers */
+type Without<T, U> = { [P in Exclude<keyof T, keyof U>]?: never };
+type XOR<T, U> = T | U extends object
+  ? (Without<T, U> & U) | (Without<U, T> & T)
+  : T | U;
+type OneOf<T extends any[]> = T extends [infer Only]
+  ? Only
+  : T extends [infer A, infer B, ...infer Rest]
+  ? OneOf<[XOR<A, B>, ...Rest]>
+  : never;
+
+export type AudioData = {
+  /** @description Raw audio data, base64 encoded. This can be the raw data recorded directly from a microphone or read from an audio file. */
+  audio_data: string;
+};
+
+export type FinalTranscript = RealtimeBaseTranscript & {
+  /**
+   * @description Describes the type of message.
+   * @constant
+   */
+  message_type: "FinalTranscript";
+  /** @description Whether the text has been punctuated and cased. */
+  punctuated: boolean;
+  /** @description Whether the text has been formatted (e.g. Dollar -> $) */
+  text_formatted: boolean;
+};
+
+/** @enum {string} */
+export type MessageType =
+  | "SessionBegins"
+  | "PartialTranscript"
+  | "FinalTranscript"
+  | "SessionTerminated";
+
+export type PartialTranscript = RealtimeBaseTranscript & {
+  /**
+   * @description Describes the type of message.
+   * @constant
+   */
+  message_type: "PartialTranscript";
+};
+
+export type RealtimeBaseMessage = {
+  /** @description Describes the type of the message. */
+  message_type: MessageType;
+};
+
+export type RealtimeBaseTranscript = {
+  /** @description End time of audio sample relative to session start, in milliseconds. */
+  audio_end: number;
+  /** @description Start time of audio sample relative to session start, in milliseconds. */
+  audio_start: number;
+  /**
+   * Format: double
+   * @description The confidence score of the entire transcription, between 0 and 1.
+   */
+  confidence: number;
+  /** @description The timestamp for the partial transcript. */
+  created: Date;
+  /** @description The partial transcript for your audio. */
+  text: string;
+  /** @description An array of objects, with the information for each word in the transcription text. Includes the start/end time (in milliseconds) of the word, the confidence score of the word, and the text (i.e. the word itself). */
+  words: Word[];
+};
+
+export type RealtimeError = {
+  error: string;
+};
+
+export type RealtimeMessage =
+  | SessionBegins
+  | PartialTranscript
+  | FinalTranscript
+  | SessionTerminated
+  | RealtimeError;
+
+export type RealtimeTranscript = PartialTranscript | FinalTranscript;
+
+/** @enum {string} */
+export type RealtimeTranscriptType = "PartialTranscript" | "FinalTranscript";
+
+export type SessionBegins = RealtimeBaseMessage & {
+  /** @description Timestamp when this session will expire. */
+  expires_at: Date;
+  /**
+   * @description Describes the type of the message.
+   * @constant
+   */
+  message_type: "SessionBegins";
+  /** @description Unique identifier for the established session. */
+  session_id: string;
+};
+
+export type SessionTerminated = RealtimeBaseMessage & {
+  /**
+   * @description Describes the type of the message.
+   * @constant
+   */
+  message_type: "SessionTerminated";
+};
+
+export type TerminateSession = RealtimeBaseMessage & {
+  /** @description A boolean value to communicate that you wish to end your real-time session forever. */
+  terminate_session: boolean;
+};
+
+export type Word = {
+  /**
+   * Format: double
+   * @description Confidence score of the word
+   */
+  confidence: number;
+  /** @description End time of the word in milliseconds */
+  end: number;
+  /** @description Start time of the word in milliseconds */
+  start: number;
+  /** @description The word itself */
+  text: string;
+};

package/src/types/index.ts

@@ -1,6 +1,5 @@
-export type * from "./core";
-export type * from "./lemur";
-export type * from "./models";
+export type * from "./transcripts";
 export type * from "./realtime";
 export type * from "./services";
-export type * from "./shared";
+export type * from "./asyncapi.generated";
+export type * from "./openapi.generated";