Update readme, add uuid, update waitFor, fix minor issues (#7)

Author: Maks19

README.md

@@ -10,24 +10,17 @@ Welcome to the SaladCloud Transcription SDK documentation. This guide will help
 
 The Transcription REST API. Please refer to the [Transcription API Documentation](https://docs.salad.com/reference/transcribe/inference_endpoints/create-an-inference-endpoint-job) for more details.
 
-## Installation
-
-To get started with the SDK, we recommend installing using `npm` or `yarn`:
-
-```bash
-npm install @saladtechnologies-oss/salad-cloud-transcription-sdk
-```
-
-```bash
-yarn add @saladtechnologies-oss/salad-cloud-transcription-sdk
-```
-
 ## Table of Contents
 
+- [Getting Started](#getting-started)
+- [Installation](#installation)
 - [Authentication](#authentication)
-  - [Setting the API key](#transcribe)
-  - [Setting a Custom Timeout](#get)
+  - [Setting the API key](#setting-the-api-key)
+  - [Setting a Custom Timeout](#setting-a-custom-timeout)
+- [Environment Support](#environment-support)
 - [Sample Usage](#sample-usage)
+  - [Node.js Usage Example](#nodejs-usage-example)
+  - [Browser Usage Example](#browser-usage-example)
 - [Features and Methods](#features-and-methods)
   - [Transcribe](#transcribe)
   - [Transcribe and Get Updates via a Webhook](#transcribe-and-get-updates-via-a-webhook)
@@ -38,6 +31,26 @@ yarn add @saladtechnologies-oss/salad-cloud-transcription-sdk
 - [Error Handling](#error-handling)
 - [License](#license)
 
+## Getting Started
+
+To quickly integrate the SDK, follow these steps:
+
+1.  Install the SDK (see above).
+2.  Initialize the SDK with your API key.
+3.  Transcribe a File using a basic example provided below.
+
+## Installation
+
+To get started with the SDK, we recommend installing using `npm` or `yarn`:
+
+```bash
+npm install @saladtechnologies-oss/salad-cloud-transcription-sdk
+```
+
+```bash
+yarn add @saladtechnologies-oss/salad-cloud-transcription-sdk
+```
+
 ## Authentication
 
 ### API Key Authentication
@@ -60,15 +73,51 @@ You can set a custom timeout for the SDK's HTTP requests as follows:
 const sdk = new SaladCloudTranscriptionSdk({ timeout: 10000 })
 ```
 
+## Environment Support
+
+The SaladCloud Transcription SDK is built to work seamlessly in both Node.js and browser environments.
+
+- Node.js:
+  Full support for local file operations and heavy file I/O makes the SDK ideal for server-side applications and CLI tools.
+
+- Browser Limitations:
+  Browsers do not have access to the local file system like Node.js does. Therefore, any attempt to perform local file I/O in the browser will be explicitly rejected.
+
 ## Sample Usage
 
 Below is a comprehensive example demonstrating how to authenticate and transcribe:
 
+### Node.js Usage Example
+
+```ts
+const { SaladCloudTranscriptionSdk } = require('@saladtechnologies-oss/salad-cloud-transcription-sdk')
+
+const organizationName = 'organization_name'
+const file = 'file:///path/to/file.mp4'
+
+const sdk = new SaladCloudTranscriptionSdk({ apiKey: 'YOUR_API_KEY' })
+
+const transcribe = async (): Promise<string> => {
+  const { id } = await sdk.transcribe(organizationName, file)
+  return id
+}
+
+;(async () => {
+  try {
+    await transcribe()
+  } catch (error) {
+    console.error(error)
+  }
+})()
+```
+
+### Browser Usage Example
+
 ```ts
 import { SaladCloudTranscriptionSdk } from '@saladtechnologies-oss/salad-cloud-transcription-sdk'
 
 const organizationName = 'organization_name'
-const file = 'file_to_path_or_url'
+const file = 'https://example.com/video.mp4'
 
 const sdk = new SaladCloudTranscriptionSdk({ apiKey: 'YOUR_API_KEY' })
 
@@ -92,7 +141,8 @@ The SDK exposes several key methods:
 
 ### Transcribe
 
-Transcribes a file or remote source. If a local file is provided, it is uploaded before transcription.
+Transcribes either a local file or a remote source.
+If you provide a local file, it’s uploaded before transcription. Files larger than 100 MB are uploaded in chunks
 
 ```ts
 import { SaladCloudTranscriptionSdk } from '@saladtechnologies-oss/salad-cloud-transcription-sdk'
@@ -185,7 +235,14 @@ const sdk = new SaladCloudTranscriptionSdk({
   apiKey: 'YOUR_API_KEY',
 })
 
-const transcription = await sdk.get('organization_name', 'transcription_job_id')
+const controller = new AbortController()
+const signal = controller.signal
+
+const transcription = await sdk.get(
+  'organization_name', // organization name
+  'transcription_job_id', // transcription job ID
+  signal, // optional AbortSignal to cancel the operation
+)
 ```
 
 ### Stop
@@ -199,7 +256,10 @@ const sdk = new SaladCloudTranscriptionSdk({
   apiKey: 'YOUR_API_KEY',
 })
 
-await sdk.stop('organization_name', 'transcription_job_id')
+await sdk.stop(
+  'organization_name', // organization name
+  'transcription_job_id', // transcription job ID
+)
 ```
 
 ### List
@@ -213,12 +273,14 @@ const sdk = new SaladCloudTranscriptionSdk({
   apiKey: 'YOUR_API_KEY',
 })
 
-const transcriptionsList = await sdk.list('organization_name')
+const transcriptionsList = await sdk.list(
+  'organization_name', // organization name
+)
 ```
 
 ### WaitFor
 
-Polls the transcription status until the job reaches a final state ("succeeded" or "failed"), a timeout is reached, or the operation is aborted.
+Polls the transcription status every 5 seconds until one of the following occurs: the job reaches a final state (either "succeeded" or "failed"), it times out after 3 minutes, or the operation is aborted.
 
 ```ts
 import { SaladCloudTranscriptionSdk } from '@saladtechnologies-oss/salad-cloud-transcription-sdk'
@@ -228,7 +290,14 @@ const sdk = new SaladCloudTranscriptionSdk({
 })
 
 try {
-  const finalResult = await sdk.waitFor('organization_name', 'transcription_job_id')
+  const controller = new AbortController()
+  const signal = controller.signal
+
+  const finalResult = await sdk.get(
+    'organization_name', // organization name
+    'transcription_job_id', // transcription job ID
+    signal, // optional AbortSignal to cancel the operation
+  )
 } catch (error) {
   console.error('Error or timeout while waiting:', error)
 }

src/transcription/constants.ts

@@ -2,7 +2,8 @@ export const transcribeInferenceEndpointName = 'transcribe'
 
 export const oneSecondInMs = 1000
 export const oneMinuteInMs = 60000
+export const oneDayInSeconds = 86400
 
 export const oneMbInBytes = 1024 * 1024
 export const maxFileSizeBytesForStorage = oneMbInBytes * 100
-export const filePartSizeBytesForStorage = oneMbInBytes * 20
+export const filePartSizeBytesForStorage = oneMbInBytes * 80

src/transcription/node/utils.ts

@@ -1,10 +1,11 @@
 import { AxiosInstance } from 'axios'
+import { randomUUID } from 'crypto'
 import FormData from 'form-data'
 import fs from 'fs/promises'
 import { createReadStream, existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { filePartSizeBytesForStorage, maxFileSizeBytesForStorage } from '../constants'
+import { filePartSizeBytesForStorage, maxFileSizeBytesForStorage, oneDayInSeconds } from '../constants'
 import { SignFileError, UploadError } from '../errors'
 import { Semaphore } from './semaphore'
 
@@ -64,7 +65,6 @@ export const normalizeFilePath = (filePath: string): string => {
  * @returns A FormData instance containing the file.
  */
 export const createFormData = async (fileSource: string): Promise<FormData> => {
-  console.log(!existsSync(fileSource))
   if (!existsSync(fileSource)) {
     throw new UploadError(fileSource, 'File not found')
   }
@@ -125,7 +125,7 @@ export const signFile = async (
 ): Promise<UploadFileResponse> => {
   const requestBody = {
     method: 'GET',
-    exp: '3600',
+    exp: oneDayInSeconds,
   }
 
   try {
@@ -260,7 +260,7 @@ export const readFileInChunks = async (
  * 3. Completes the upload once all parts are processed.
  *
  * @param axiosInstance - The Axios instance for making HTTP requests.
- * @param fileName - The name of the file being uploaded.
+ * @param uniqueFileName - The name and uid of the file being uploaded.
  * @param filePath - The path of the file on the local filesystem.
  * @param fileSize - The total size of the file in bytes.
  * @param organizationName - The name of the organization (used in URL paths).
@@ -269,15 +269,15 @@ export const readFileInChunks = async (
  */
 export const uploadFileInParts = async (
   axiosInstance: AxiosInstance,
-  fileName: string,
+  uniqueFileName: string,
   filePath: string,
   fileSize: number,
   organizationName: string,
   partSizeBytes: number,
   signal?: AbortSignal,
 ): Promise<void> => {
-  const filesUploadUrl = `/organizations/${organizationName}/files/${fileName}`
-  const filePartsUploadUrl = `/organizations/${organizationName}/file_parts/${fileName}`
+  const filesUploadUrl = `/organizations/${organizationName}/files/${uniqueFileName}`
+  const filePartsUploadUrl = `/organizations/${organizationName}/file_parts/${uniqueFileName}`
 
   const createUploadUrl = `${filesUploadUrl}?action=mpu-create`
 
@@ -322,11 +322,14 @@ export const getTranscriptionLocalFileSource = async (
   organizationName: string,
   signal?: AbortSignal,
 ): Promise<string> => {
+  const uniqueId = randomUUID()
   const normalizedFilePath = normalizeFilePath(source)
   const fileName = path.basename(normalizedFilePath)
 
-  const uploadFileRequestUrl = `/organizations/${organizationName}/files/${fileName}`
-  const signFileRequestUrl = `/organizations/${organizationName}/file_tokens/${fileName}`
+  const uniqueFileName = `${uniqueId}-${fileName}`
+
+  const uploadFileRequestUrl = `/organizations/${organizationName}/files/${uniqueFileName}`
+  const signFileRequestUrl = `/organizations/${organizationName}/file_tokens/${uniqueFileName}`
 
   try {
     const stats = await fs.stat(normalizedFilePath)
@@ -335,7 +338,7 @@ export const getTranscriptionLocalFileSource = async (
     if (fileSize > maxFileSizeBytesForStorage) {
       await uploadFileInParts(
         axiosInstance,
-        fileName,
+        uniqueFileName,
         normalizedFilePath,
         fileSize,
         organizationName,

src/transcription/transcription.ts

@@ -258,7 +258,7 @@ export class SaladCloudTranscriptionSdk {
       if (signal?.aborted) {
         throw new Error('Operation aborted')
       }
-      if (Date.now() - startTime > oneMinuteInMs * 2) {
+      if (Date.now() - startTime > oneMinuteInMs * 3) {
         throw new Error('Timeout waiting for transcription')
       }
 
@@ -282,7 +282,7 @@ export class SaladCloudTranscriptionSdk {
       }
 
       // Otherwise, wait and poll again.
-      await new Promise((resolve) => setTimeout(resolve, oneSecondInMs * 3))
+      await new Promise((resolve) => setTimeout(resolve, oneSecondInMs * 5))
       return poll()
     }
 

tests/nodeUtils.test.ts

@@ -3,6 +3,7 @@ import fsPromises from 'fs/promises'
 import path from 'node:path'
 import { Readable } from 'node:stream'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { oneDayInSeconds } from '../src/transcription/constants'
 import * as utils from '../src/transcription/node'
 import {
   completeUpload,
@@ -110,7 +111,7 @@ describe('signFile', () => {
     const axiosInstance: any = createAxiosInstance('post', signResponse)
     const result = await signFile(axiosInstance as any, testUrl, testFileName)
     expect(result).toEqual(signResponse)
-    expect(axiosInstance.post).toHaveBeenCalledWith(testUrl, { method: 'GET', exp: '3600' })
+    expect(axiosInstance.post).toHaveBeenCalledWith(testUrl, { method: 'GET', exp: oneDayInSeconds })
   })
 
   it('should throw an error on failure', async () => {