assemblyai 4.3.1 → 4.3.2

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

@@ -2,5 +2,4 @@ type BaseServiceParams = {
     apiKey: string;
     baseUrl?: string;
 };
-export * from "./abstractions";
 export type { BaseServiceParams };

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

@@ -1,21 +1,27 @@
 import { FileUploadParams } from "../files";
 import { TranscriptParams } from "../openapi.generated";
+/**
+ * Options for polling.
+ */
 export type PollingOptions = {
     /**
      * The amount of time to wait between polling requests.
-     * @default 3000 or every 3 seconds
+     * @defaultValue 3000 or every 3 seconds
      */
     pollingInterval?: number;
     /**
      * The maximum amount of time to wait for the transcript to be ready.
-     * @default -1 which means wait forever
+     * @defaultValue -1 which means wait forever
      */
     pollingTimeout?: number;
 };
+/**
+ * @deprecated Use `TranscriptService.transcribe` with `TranscribeOptions`.
+ */
 export type CreateTranscriptOptions = {
     /**
      * Whether to poll the transcript until it is ready.
-     * @default true
+     * @defaultValue true
      */
     poll?: boolean;
 } & PollingOptions;
@@ -26,9 +32,12 @@ export type AudioToTranscribe = FileUploadParams;
 /**
  * The parameters to transcribe an audio file.
  */
-export type TranscribeParams = {
+export type TranscribeParams = ({
+    /**
+     * The audio to transcribe. This can be a public URL, a local file path, a readable file stream, or a file buffer.
+     */
     audio: AudioToTranscribe;
-} & Omit<TranscriptParams, "audio_url">;
+} & Omit<TranscriptParams, "audio_url">) | TranscriptParams;
 /**
  * The parameters to start the transcription of an audio file.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "assemblyai",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "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"
@@ -110,6 +110,7 @@
     "@typescript-eslint/eslint-plugin": "^6.7.5",
     "dotenv": "^16.3.1",
     "eslint": "^8.48.0",
+    "eslint-plugin-tsdoc": "^0.2.17",
     "jest": "^29.5.0",
     "jest-cli": "^29.5.0",
     "jest-fetch-mock": "^3.0.3",

package/src/services/base.ts

@@ -7,7 +7,7 @@ import { Error as JsonError } from "..";
 export abstract class BaseService {
   /**
    * Create a new service.
-   * @param params The parameters to use for the service.
+   * @param params - The parameters to use for the service.
    */
   constructor(private params: BaseServiceParams) {}
   protected async fetch(

package/src/services/files/index.ts

@@ -5,8 +5,8 @@ import { UploadedFile, FileUploadParams, FileUploadData } from "../..";
 export 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.
+   * @param input - The local file path to upload, or a stream or buffer of the file to upload.
+   * @returns A promise that resolves to the uploaded file URL.
    */
   async upload(input: FileUploadParams): Promise<string> {
     let fileData: FileUploadData;

package/src/services/index.ts

@@ -34,7 +34,7 @@ class AssemblyAI {
 
   /**
    * Create a new AssemblyAI client.
-   * @param params The parameters for the service, including the API key and base URL, if any.
+   * @param params - The parameters for the service, including the API key and base URL, if any.
    */
   constructor(params: BaseServiceParams) {
     params.baseUrl = params.baseUrl || defaultBaseUrl;

package/src/services/lemur/index.ts

@@ -52,7 +52,7 @@ export class LemurService extends BaseService {
 
   /**
    * Delete the data for a previously submitted LeMUR request.
-   * @param id ID of the LeMUR request
+   * @param id - ID of the LeMUR request
    */
   purgeRequestData(id: string): Promise<PurgeLemurRequestDataResponse> {
     return this.fetchJson<PurgeLemurRequestDataResponse>(`/lemur/v3/${id}`, {

package/src/services/realtime/service.ts

@@ -58,8 +58,7 @@ export class RealtimeTranscriber {
     this.sampleRate = params.sampleRate ?? 16_000;
     this.wordBoost = params.wordBoost;
     this.encoding = params.encoding;
-    this.endUtteranceSilenceThreshold =
-      params.endUtteranceSilenceThreshold;
+    this.endUtteranceSilenceThreshold = params.endUtteranceSilenceThreshold;
     if ("token" in params && params.token) this.token = params.token;
     if ("apiKey" in params && params.apiKey) this.apiKey = params.apiKey;
 
@@ -214,8 +213,8 @@ export class RealtimeTranscriber {
 
   /**
    * Configure the threshold for how long to wait before ending an utterance. Default is 700ms.
-   * @param threshold The duration of the end utterance silence threshold in milliseconds
-   * @format integer
+   * @param threshold - The duration of the end utterance silence threshold in milliseconds.
+   * This value must be an integer between 0 and 20_000.
    */
   configureEndUtteranceSilenceThreshold(threshold: number) {
     this.send(`{"end_utterance_silence_threshold":${threshold}}`);

package/src/services/transcripts/index.ts

@@ -6,10 +6,6 @@ import {
   TranscriptList,
   TranscriptParams,
   CreateTranscriptOptions,
-  Createable,
-  Deletable,
-  Listable,
-  Retrieveable,
   SubtitleFormat,
   RedactedAudioResponse,
   ListTranscriptParams,
@@ -23,22 +19,15 @@ import {
 import { FileService } from "../files";
 import { getPath } from "../../utils/path";
 
-export class TranscriptService
-  extends BaseService
-  implements
-    Createable<Transcript, TranscriptParams, CreateTranscriptOptions>,
-    Retrieveable<Transcript>,
-    Deletable<Transcript>,
-    Listable<TranscriptList>
-{
+export class TranscriptService extends BaseService {
   constructor(params: BaseServiceParams, private files: FileService) {
     super(params);
   }
 
   /**
    * 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.
+   * @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(
@@ -51,37 +40,43 @@ export class TranscriptService
 
   /**
    * 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.
+   * @param params - The parameters to start the transcription of an audio file.
    * @returns A promise that resolves to the queued transcript.
    */
   async submit(params: SubmitParams): Promise<Transcript> {
-    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);
+    let transcriptParams: TranscriptParams | undefined = undefined;
+    if ("audio" in params) {
+      const { audio, ...audioTranscriptParams } = params;
+      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 not a local path, assume it's a URL
-        audioUrl = audio;
+        // audio is of uploadable type
+        audioUrl = await this.files.upload(audio);
       }
+      transcriptParams = { ...audioTranscriptParams, audio_url: audioUrl };
     } else {
-      // audio is of uploadable type
-      audioUrl = await this.files.upload(audio);
+      transcriptParams = params;
     }
 
     const data = await this.fetchJson<Transcript>("/v2/transcript", {
       method: "POST",
-      body: JSON.stringify({ ...createParams, audio_url: audioUrl }),
+      body: JSON.stringify(transcriptParams),
     });
     return data;
   }
 
   /**
    * Create a transcript.
-   * @param params The parameters to create a transcript.
-   * @param options The options used for creating the new 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.
    */
@@ -109,8 +104,8 @@ export class TranscriptService
 
   /**
    * 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.
+   * @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(
@@ -138,7 +133,7 @@ export class TranscriptService
 
   /**
    * Retrieve a transcript.
-   * @param id The identifier of the transcript.
+   * @param id - The identifier of the transcript.
    * @returns A promise that resolves to the transcript.
    */
   get(id: string): Promise<Transcript> {
@@ -147,19 +142,17 @@ export class TranscriptService
 
   /**
    * 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.
+   * @param params - The parameters to filter the transcript list by, or the URL to retrieve the transcript list from.
    */
-  async list(
-    parameters?: ListTranscriptParams | string
-  ): Promise<TranscriptList> {
+  async list(params?: ListTranscriptParams | string): Promise<TranscriptList> {
     let url = "/v2/transcript";
-    if (typeof parameters === "string") {
-      url = parameters;
-    } else if (parameters) {
+    if (typeof params === "string") {
+      url = params;
+    } else if (params) {
       url = `${url}?${new URLSearchParams(
-        Object.keys(parameters).map((key) => [
+        Object.keys(params).map((key) => [
           key,
-          parameters[key as keyof ListTranscriptParams]?.toString() || "",
+          params[key as keyof ListTranscriptParams]?.toString() || "",
         ])
       )}`;
     }
@@ -176,7 +169,7 @@ export class TranscriptService
 
   /**
    * Delete a transcript
-   * @param id The identifier of the transcript.
+   * @param id - The identifier of the transcript.
    * @returns A promise that resolves to the transcript.
    */
   delete(id: string): Promise<Transcript> {
@@ -186,9 +179,9 @@ export class TranscriptService
   /**
    * 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.
+   * @param id - The identifier of the transcript.
+   * @param words - Keywords to search for.
+   * @returns A promise that resolves to the sentences.
    */
   wordSearch(id: string, words: string[]): Promise<WordSearchResponse> {
     const params = new URLSearchParams({ words: words.join(",") });
@@ -199,8 +192,8 @@ export class TranscriptService
 
   /**
    * Retrieve all sentences of a transcript.
-   * @param id The identifier of the transcript.
-   * @return A promise that resolves to the sentences.
+   * @param id - The identifier of the transcript.
+   * @returns A promise that resolves to the sentences.
    */
   sentences(id: string): Promise<SentencesResponse> {
     return this.fetchJson<SentencesResponse>(`/v2/transcript/${id}/sentences`);
@@ -208,8 +201,8 @@ export class TranscriptService
 
   /**
    * Retrieve all paragraphs of a transcript.
-   * @param id The identifier of the transcript.
-   * @return A promise that resolves to the paragraphs.
+   * @param id - The identifier of the transcript.
+   * @returns A promise that resolves to the paragraphs.
    */
   paragraphs(id: string): Promise<ParagraphsResponse> {
     return this.fetchJson<ParagraphsResponse>(
@@ -219,10 +212,10 @@ export class TranscriptService
 
   /**
    * 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.
+   * @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.
+   * @returns A promise that resolves to the subtitles text.
    */
   async subtitles(
     id: string,
@@ -241,8 +234,8 @@ export class TranscriptService
 
   /**
    * Retrieve redactions of a transcript.
-   * @param id The identifier of the transcript.
-   * @return A promise that resolves to the subtitles text.
+   * @param id - The identifier of the transcript.
+   * @returns A promise that resolves to the subtitles text.
    */
   redactions(id: string): Promise<RedactedAudioResponse> {
     return this.fetchJson<RedactedAudioResponse>(

package/src/types/asyncapi.generated.ts

@@ -1,7 +1,6 @@
 // this file is generated by typescript/scripts/generate-types.ts
 /* tslint:disable */
 /* eslint-disable */
-
 import { LiteralUnion } from "./helpers";
 
 /** OneOf type helpers */
@@ -15,44 +14,54 @@ type OneOf<T extends any[]> = T extends [infer Only]
   ? OneOf<[XOR<A, B>, ...Rest]>
   : never;
 
+/* eslint-enable */
+
 /**
- * Format: binary
- * @description Binary audio data
+ * Binary audio data
  */
 export type AudioData = ArrayBufferLike;
 
 /**
- * @description The encoding of the audio data
- * @default pcm_s16le
- * @enum {string}
+ * The encoding of the audio data
+ * @defaultValue "pcm_s16"le
  */
 export type AudioEncoding = "pcm_s16le" | "pcm_mulaw";
 
-/** @description Configure the threshold for how long to wait before ending an utterance. Default is 700ms. */
+/**
+ * Configure the threshold for how long to wait before ending an utterance. Default is 700ms.
+ */
 export type ConfigureEndUtteranceSilenceThreshold = {
-  /** @description The duration threshold in milliseconds */
+  /**
+   * The duration threshold in milliseconds
+   */
   end_utterance_silence_threshold: number;
 };
 
 export type FinalTranscript = RealtimeBaseTranscript & {
   /**
-   * @description Describes the type of message
-   * @constant
+   * Describes the type of message
    */
   message_type: "FinalTranscript";
-  /** @description Whether the text is punctuated and cased */
+  /**
+   * Whether the text is punctuated and cased
+   */
   punctuated: boolean;
-  /** @description Whether the text is formatted, for example Dollar -> $ */
+  /**
+   * Whether the text is formatted, for example Dollar -&gt; $
+   */
   text_formatted: boolean;
 };
 
-/** @description Manually end an utterance */
+/**
+ * Manually end an utterance
+ */
 export type ForceEndUtterance = {
-  /** @description A boolean value to communicate that you wish to force the end of the utterance */
+  /**
+   * A boolean value to communicate that you wish to force the end of the utterance
+   */
   force_end_utterance: boolean;
 };
 
-/** @enum {string} */
 export type MessageType =
   | "SessionBegins"
   | "PartialTranscript"
@@ -61,33 +70,41 @@ export type MessageType =
 
 export type PartialTranscript = RealtimeBaseTranscript & {
   /**
-   * @description Describes the type of message
-   * @constant
+   * Describes the type of message
    */
   message_type: "PartialTranscript";
 };
 
 export type RealtimeBaseMessage = {
-  /** @description Describes the type of the message */
+  /**
+   * Describes the type of the message
+   */
   message_type: MessageType;
 };
 
 export type RealtimeBaseTranscript = {
-  /** @description End time of audio sample relative to session start, in milliseconds */
+  /**
+   * 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 */
+  /**
+   * 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
+   * The confidence score of the entire transcription, between 0 and 1
    */
   confidence: number;
-  /** @description The timestamp for the partial transcript */
+  /**
+   * The timestamp for the partial transcript
+   */
   created: Date;
-  /** @description The partial transcript for your audio */
+  /**
+   * The partial transcript for your audio
+   */
   text: string;
   /**
-   * @description An array of objects, with the information for each word in the transcription text.
+   * An array of objects, with the information for each word in the transcription text.
    * Includes the start and end time of the word in milliseconds, the confidence score of the word, and the text, which is the word itself.
    */
   words: Word[];
@@ -106,47 +123,52 @@ export type RealtimeMessage =
 
 export type RealtimeTranscript = PartialTranscript | FinalTranscript;
 
-/** @enum {string} */
 export type RealtimeTranscriptType = "PartialTranscript" | "FinalTranscript";
 
 export type SessionBegins = RealtimeBaseMessage & {
-  /** @description Timestamp when this session will expire */
+  /**
+   * Timestamp when this session will expire
+   */
   expires_at: Date;
   /**
-   * @description Describes the type of the message
-   * @constant
+   * Describes the type of the message
    */
   message_type: "SessionBegins";
   /**
-   * Format: uuid
-   * @description Unique identifier for the established session
+   * Unique identifier for the established session
    */
   session_id: string;
 };
 
 export type SessionTerminated = RealtimeBaseMessage & {
   /**
-   * @description Describes the type of the message
-   * @constant
+   * Describes the type of the message
    */
   message_type: "SessionTerminated";
 };
 
-export type TerminateSession = RealtimeBaseMessage & {
-  /** @description Set to true to end your real-time session forever */
+export type TerminateSession = {
+  /**
+   * Set to true to end your real-time session forever
+   */
   terminate_session: boolean;
 };
 
 export type Word = {
   /**
-   * Format: double
-   * @description Confidence score of the word
+   * Confidence score of the word
    */
   confidence: number;
-  /** @description End time of the word in milliseconds */
+  /**
+   * End time of the word in milliseconds
+   */
   end: number;
-  /** @description Start time of the word in milliseconds */
+  /**
+   * Start time of the word in milliseconds
+   */
   start: number;
-  /** @description The word itself */
+  /**
+   * The word itself
+   */
   text: string;
 };