assemblyai 3.0.1 → 3.1.1

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

@@ -1,16 +1,16 @@
 /**
  * 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.
+ * @template Params The type of the parameters required to create the resource.
  */
-interface Createable<T, Parameters, Options = Record<string, unknown>> {
+interface Createable<T, Params, Options = Record<string, unknown>> {
     /**
      * 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>;
+    create(params: Params, options?: Options): Promise<T>;
 }
 /**
  * Interface for classes that can retrieve resources.

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

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

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

@@ -1,5 +1,39 @@
-export type CreateTranscriptOptions = {
-    poll?: boolean;
+import { FileUploadParams } from "../files";
+import { TranscriptParams } from "../openapi.generated";
+export type PollingOptions = {
+    /**
+     * The amount of time to wait between polling requests.
+     * @default 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
+     */
     pollingTimeout?: number;
 };
+export type CreateTranscriptOptions = {
+    /**
+     * Whether to poll the transcript until it is ready.
+     * @default true
+     */
+    poll?: boolean;
+} & PollingOptions;
+/**
+ * The audio to transcribe. This can be a public URL, a local file path, a readable file stream, or a file buffer.
+ */
+export type AudioToTranscribe = FileUploadParams;
+/**
+ * The parameters to transcribe an audio file.
+ */
+export type TranscribeParams = {
+    audio: AudioToTranscribe;
+} & Omit<TranscriptParams, "audio_url">;
+/**
+ * The parameters to start the transcription of an audio file.
+ */
+export type SubmitParams = TranscribeParams;
+/**
+ * The options to transcribe an audio file, including polling options.
+ */
+export type TranscribeOptions = PollingOptions;

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "assemblyai",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "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",
+  "exports": {
+    "default": "./dist/index.js",
+    "require": "./dist/index.js",
+    "import": "./dist/index.esm.js",
+    "node": "./dist/index.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AssemblyAI/assemblyai-node-sdk.git"
@@ -18,10 +24,10 @@
   "scripts": {
     "build": "pnpm clean && pnpm rollup -c",
     "clean": "rimraf dist",
-    "lint": "eslint -c .eslintrc.json 'src/**/*'",
+    "lint": "eslint -c .eslintrc.json '{src,tests}/**/*.{js,ts}'",
     "test": "pnpm lint && pnpm test:unit",
     "test:unit": "jest --config jest.config.rollup.ts",
-    "format": "prettier --write 'src/**/*.ts'",
+    "format": "prettier '**/*' --write",
     "generate-types": "tsx ./scripts/generate-types.ts && pnpm format",
     "copybara:dry-run": "./copybara.sh dry_run --init-history",
     "copybara:pr": "./copybara.sh sync_out --init-history"
@@ -38,8 +44,7 @@
   "homepage": "https://www.assemblyai.com/docs",
   "files": [
     "dist",
-    "src",
-    "types"
+    "src"
   ],
   "devDependencies": {
     "@types/jest": "^29.5.5",

package/src/index.ts

@@ -1,2 +1,2 @@
-export type * from "./types";
+export * from "./types";
 export * from "./services";

package/src/services/files/index.ts

@@ -2,7 +2,7 @@
 // to keep the assemblyai module more compatible. Some fs polyfills don't include `createReadStream`.
 import fs from "fs";
 import { BaseService } from "../base";
-import { UploadedFile, FileUploadParameters, FileUploadData } from "../..";
+import { UploadedFile, FileUploadParams, FileUploadData } from "../..";
 
 export class FileService extends BaseService {
   /**
@@ -10,7 +10,7 @@ export class FileService extends BaseService {
    * @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: FileUploadParameters): Promise<string> {
+  async upload(input: FileUploadParams): Promise<string> {
     let fileData: FileUploadData;
     if (typeof input === "string") fileData = fs.createReadStream(input);
     else fileData = input;

package/src/services/lemur/index.ts

@@ -1,8 +1,8 @@
 import {
-  LemurSummaryParameters,
-  LemurActionItemsParameters,
-  LemurQuestionAnswerParameters,
-  LemurTaskParameters,
+  LemurSummaryParams,
+  LemurActionItemsParams,
+  LemurQuestionAnswerParams,
+  LemurTaskParams,
   LemurSummaryResponse,
   LemurQuestionAnswerResponse,
   LemurActionItemsResponse,
@@ -12,7 +12,7 @@ import {
 import { BaseService } from "../base";
 
 export class LemurService extends BaseService {
-  summary(params: LemurSummaryParameters): Promise<LemurSummaryResponse> {
+  summary(params: LemurSummaryParams): Promise<LemurSummaryResponse> {
     return this.fetchJson<LemurSummaryResponse>("/lemur/v3/generate/summary", {
       method: "POST",
       body: JSON.stringify(params),
@@ -20,7 +20,7 @@ export class LemurService extends BaseService {
   }
 
   questionAnswer(
-    params: LemurQuestionAnswerParameters
+    params: LemurQuestionAnswerParams
   ): Promise<LemurQuestionAnswerResponse> {
     return this.fetchJson<LemurQuestionAnswerResponse>(
       "/lemur/v3/generate/question-answer",
@@ -32,7 +32,7 @@ export class LemurService extends BaseService {
   }
 
   actionItems(
-    params: LemurActionItemsParameters
+    params: LemurActionItemsParams
   ): Promise<LemurActionItemsResponse> {
     return this.fetchJson<LemurActionItemsResponse>(
       "/lemur/v3/generate/action-items",
@@ -43,7 +43,7 @@ export class LemurService extends BaseService {
     );
   }
 
-  task(params: LemurTaskParameters): Promise<LemurTaskResponse> {
+  task(params: LemurTaskParams): Promise<LemurTaskResponse> {
     return this.fetchJson<LemurTaskResponse>("/lemur/v3/generate/task", {
       method: "POST",
       body: JSON.stringify(params),

package/src/services/transcripts/index.ts

@@ -4,7 +4,7 @@ import {
   SentencesResponse,
   Transcript,
   TranscriptList,
-  CreateTranscriptParameters,
+  TranscriptParams,
   CreateTranscriptOptions,
   Createable,
   Deletable,
@@ -12,16 +12,20 @@ import {
   Retrieveable,
   SubtitleFormat,
   RedactedAudioResponse,
-  TranscriptListParameters,
+  ListTranscriptParams,
   WordSearchResponse,
   BaseServiceParams,
+  PollingOptions,
+  TranscribeParams,
+  TranscribeOptions,
+  SubmitParams,
 } from "../..";
 import { FileService } from "../files";
 
 export class TranscriptService
   extends BaseService
   implements
-    Createable<Transcript, CreateTranscriptParameters, CreateTranscriptOptions>,
+    Createable<Transcript, TranscriptParams, CreateTranscriptOptions>,
     Retrieveable<Transcript>,
     Deletable<Transcript>,
     Listable<TranscriptList>
@@ -30,14 +34,58 @@ export class TranscriptService
     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.
+   * @returns A promise that resolves to the transcript. The transcript status is "completed" or "error".
+   */
+  async transcribe(
+    params: TranscribeParams,
+    options?: TranscribeOptions
+  ): Promise<Transcript> {
+    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: 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);
+      } 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<Transcript>("/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 newly created 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: CreateTranscriptParameters,
+    params: TranscriptParams,
     options?: CreateTranscriptOptions
   ): Promise<Transcript> {
     const path = getPath(params.audio_url);
@@ -52,16 +100,24 @@ export class TranscriptService
     });
 
     if (options?.poll ?? true) {
-      return await this.poll(data.id, options);
+      return await this.waitUntilReady(data.id, options);
     }
 
     return data;
   }
 
-  private async poll(
+  /**
+   * 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: string,
-    options?: CreateTranscriptOptions
+    options?: PollingOptions
   ): Promise<Transcript> {
+    const pollingInterval = options?.pollingInterval ?? 3_000;
+    const pollingTimeout = options?.pollingTimeout ?? -1;
     const startTime = Date.now();
     // eslint-disable-next-line no-constant-condition
     while (true) {
@@ -69,14 +125,12 @@ export class TranscriptService
       if (transcript.status === "completed" || transcript.status === "error") {
         return transcript;
       } else if (
-        Date.now() - startTime <
-        (options?.pollingTimeout ?? 180_000)
+        pollingTimeout > 0 &&
+        Date.now() - startTime > pollingTimeout
       ) {
-        await new Promise((resolve) =>
-          setTimeout(resolve, options?.pollingInterval ?? 3_000)
-        );
-      } else {
         throw new Error("Polling timeout");
+      } else {
+        await new Promise((resolve) => setTimeout(resolve, pollingInterval));
       }
     }
   }
@@ -95,7 +149,7 @@ export class TranscriptService
    * @param parameters The parameters to filter the transcript list by, or the URL to retrieve the transcript list from.
    */
   async list(
-    parameters?: TranscriptListParameters | string
+    parameters?: ListTranscriptParams | string
   ): Promise<TranscriptList> {
     let url = "/v2/transcript";
     if (typeof parameters === "string") {
@@ -104,7 +158,7 @@ export class TranscriptService
       url = `${url}?${new URLSearchParams(
         Object.keys(parameters).map((key) => [
           key,
-          parameters[key as keyof TranscriptListParameters]?.toString() || "",
+          parameters[key as keyof ListTranscriptParams]?.toString() || "",
         ])
       )}`;
     }
@@ -136,8 +190,9 @@ export class TranscriptService
    * @return A promise that resolves to the sentences.
    */
   wordSearch(id: string, words: string[]): Promise<WordSearchResponse> {
+    const params = new URLSearchParams({ words: words.join(",") });
     return this.fetchJson<WordSearchResponse>(
-      `/v2/transcript/${id}/word-search?words=${JSON.stringify(words)}`
+      `/v2/transcript/${id}/word-search?${params.toString()}`
     );
   }
 
@@ -165,10 +220,21 @@ 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.
    */
-  async subtitles(id: string, format: SubtitleFormat = "srt"): Promise<string> {
-    const response = await this.fetch(`/v2/transcript/${id}/${format}`);
+  async subtitles(
+    id: string,
+    format: SubtitleFormat = "srt",
+    chars_per_caption?: number
+  ): Promise<string> {
+    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();
   }
 

package/src/types/asyncapi.generated.ts

@@ -14,19 +14,19 @@ type OneOf<T extends any[]> = T extends [infer Only]
   : 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. */
+  /** @description Base64 encoded raw audio data */
   audio_data: string;
 };
 
 export type FinalTranscript = RealtimeBaseTranscript & {
   /**
-   * @description Describes the type of message.
+   * @description Describes the type of message
    * @constant
    */
   message_type: "FinalTranscript";
-  /** @description Whether the text has been punctuated and cased. */
+  /** @description Whether the text is punctuated and cased */
   punctuated: boolean;
-  /** @description Whether the text has been formatted (e.g. Dollar -> $) */
+  /** @description Whether the text is formatted, for example Dollar -> $ */
   text_formatted: boolean;
 };
 
@@ -39,32 +39,35 @@ export type MessageType =
 
 export type PartialTranscript = RealtimeBaseTranscript & {
   /**
-   * @description Describes the type of message.
+   * @description Describes the type of message
    * @constant
    */
   message_type: "PartialTranscript";
 };
 
 export type RealtimeBaseMessage = {
-  /** @description Describes the type of the message. */
+  /** @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. */
+  /** @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. */
+  /** @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.
+   * @description The confidence score of the entire transcription, between 0 and 1
    */
   confidence: number;
-  /** @description The timestamp for the partial transcript. */
+  /** @description The timestamp for the partial transcript */
   created: Date;
-  /** @description The partial transcript for your audio. */
+  /** @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). */
+  /**
+   * @description 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[];
 };
 
@@ -85,27 +88,27 @@ export type RealtimeTranscript = PartialTranscript | FinalTranscript;
 export type RealtimeTranscriptType = "PartialTranscript" | "FinalTranscript";
 
 export type SessionBegins = RealtimeBaseMessage & {
-  /** @description Timestamp when this session will expire. */
+  /** @description Timestamp when this session will expire */
   expires_at: Date;
   /**
-   * @description Describes the type of the message.
+   * @description Describes the type of the message
    * @constant
    */
   message_type: "SessionBegins";
-  /** @description Unique identifier for the established session. */
+  /** @description Unique identifier for the established session */
   session_id: string;
 };
 
 export type SessionTerminated = RealtimeBaseMessage & {
   /**
-   * @description Describes the type of the message.
+   * @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. */
+  /** @description Set to true to end your real-time session forever */
   terminate_session: boolean;
 };
 

package/src/types/deprecated.ts

@@ -0,0 +1,78 @@
+import { FileUploadParams } from "./files";
+import {
+  CreateRealtimeTemporaryTokenParams,
+  LemurActionItemsParams,
+  LemurBaseParams,
+  LemurQuestionAnswerParams,
+  LemurSummaryParams,
+  LemurTaskParams,
+  ListTranscriptParams,
+  TranscriptOptionalParams,
+  TranscriptParams,
+} from "./openapi.generated";
+import { SubmitParams, TranscribeParams } from "./transcripts";
+
+/**
+ * @deprecated
+ * Use`FileUploadParams` instead.
+ */
+export type FileUploadParameters = FileUploadParams;
+
+/**
+ * @deprecated
+ * Use`TranscribeParams` instead.
+ */
+export type TranscribeParameters = TranscribeParams;
+
+/**
+ * @deprecated
+ * Use`SubmitParams` instead.
+ */
+export type SubmitParameters = SubmitParams;
+
+/**
+ * @deprecated
+ * Use`CreateRealtimeTemporaryTokenParams` instead.
+ */
+export type CreateRealtimeTemporaryTokenParameters =
+  CreateRealtimeTemporaryTokenParams;
+/**
+ * @deprecated
+ * Use`LemurActionItemsParams` instead.
+ */
+export type LemurActionItemsParameters = LemurActionItemsParams;
+/**
+ * @deprecated
+ * Use`LemurBaseParams` instead.
+ */
+export type LemurBaseParameters = LemurBaseParams;
+/**
+ * @deprecated
+ * Use`LemurQuestionAnswerParams` instead.
+ */
+export type LemurQuestionAnswerParameters = LemurQuestionAnswerParams;
+/**
+ * @deprecated
+ * Use`LemurSummaryParams` instead.
+ */
+export type LemurSummaryParameters = LemurSummaryParams;
+/**
+ * @deprecated
+ * Use`LemurTaskParams` instead.
+ */
+export type LemurTaskParameters = LemurTaskParams;
+/**
+ * @deprecated
+ * Use`ListTranscriptParams` instead.
+ */
+export type TranscriptListParameters = ListTranscriptParams;
+/**
+ * @deprecated
+ * Use`TranscriptOptionalParams` instead.
+ */
+export type CreateTranscriptOptionalParameters = TranscriptOptionalParams;
+/**
+ * @deprecated
+ * Use`TranscriptParams` instead.
+ */
+export type CreateTranscriptParameters = TranscriptParams;

package/src/types/files/index.ts

@@ -1,4 +1,4 @@
-type FileUploadParameters = string | FileUploadData;
+type FileUploadParams = string | FileUploadData;
 type FileUploadData =
   | NodeJS.ReadableStream
   | ReadableStream
@@ -8,4 +8,4 @@ type FileUploadData =
   | ArrayBufferLike
   | Uint8Array;
 
-export type { FileUploadParameters, FileUploadData };
+export type { FileUploadParams, FileUploadData };

package/src/types/index.ts

@@ -1,6 +1,7 @@
-export type * from "./files";
-export type * from "./transcripts";
-export type * from "./realtime";
-export type * from "./services";
-export type * from "./asyncapi.generated";
-export type * from "./openapi.generated";
+export * from "./files";
+export * from "./transcripts";
+export * from "./realtime";
+export * from "./services";
+export * from "./asyncapi.generated";
+export * from "./openapi.generated";
+export * from "./deprecated";