speechrevolutions 0.2.0

package/dist/esm/types.d.ts

@@ -0,0 +1,73 @@
+export type OutputType = "txt" | "json" | "srt" | "vtt" | "docx" | "pdf";
+export type ProcessingTier = "standard" | "economy";
+export interface TranscribeOptions {
+    outputType?: OutputType;
+    wordTimestamps?: boolean;
+    speakerLabels?: boolean;
+    /** Alias for speakerLabels (ElevenLabs / Deepgram). */
+    diarize?: boolean;
+    nltk?: boolean;
+    /** Processing / pricing tier. Default: standard. */
+    tier?: ProcessingTier;
+    customVocabulary?: string[];
+    /** Webhook URL POSTed a signed completion/failure notification. */
+    callbackUrl?: string;
+    /** Callback fired for every transcription progress event (read `event.percent`). */
+    onProgress?: ProgressCallback;
+    /** Callback fired for byte-level upload progress (`event.step === "upload"`). */
+    onUploadProgress?: ProgressCallback;
+    /** Render live `Uploading` + `Transcribing` bars to stderr. Default: false. */
+    progress?: boolean;
+}
+export interface UploadJob {
+    jobId: string;
+    uploadUrl: string;
+    downloadUrl: string;
+    contentType: string;
+    expiresIn: number;
+}
+export interface JobStatus {
+    jobId: string;
+    status: "processing" | "completed" | "failed" | string;
+    downloadUrl?: string;
+    failedStage?: string;
+    reason?: string;
+}
+export interface ProgressEvent {
+    completed?: number;
+    total?: number;
+    step?: string;
+    elapsedSeconds?: number;
+    raw?: Record<string, unknown>;
+    /** Completion as a 0–100 number, or `undefined` when the total is unknown. */
+    percent?: number;
+}
+export type ProgressCallback = (event: ProgressEvent) => void;
+/** Completion as a 0–100 number clamped to [0, 100], or `undefined` if unknown. */
+export declare function computePercent(completed?: number, total?: number): number | undefined;
+/** Build a {@link ProgressEvent} with its `percent` derived from completed/total. */
+export declare function makeProgressEvent(event: Omit<ProgressEvent, "percent">): ProgressEvent;
+export interface STTClientOptions {
+    /** Defaults to SPEECHREVOLUTIONS_API_KEY or STT_API_KEY. */
+    apiKey?: string;
+    baseUrl?: string;
+    /** Total seconds to wait for a job (default 600). */
+    timeout?: number;
+    fetch?: typeof fetch;
+    /** Retry attempts for transient JSON API failures (429/5xx/network). Default 3. */
+    maxRetries?: number;
+    /** Base backoff in ms; exponential and capped at 30s. Default 500. */
+    retryBackoffMs?: number;
+    /**
+     * Extra `fetch` init merged into every request — the idiomatic proxy hook in
+     * Node: pass `{ dispatcher: new ProxyAgent(url) }` (from `undici`).
+     */
+    requestInit?: RequestInit;
+    /**
+     * Prefer S3 multipart uploads and fall back to a single presigned PUT if the
+     * server has multipart disabled or a multipart upload fails mid-flight.
+     * Default true.
+     */
+    multipart?: boolean;
+}
+export declare function resolveOptions(options?: TranscribeOptions): Required<Pick<TranscribeOptions, "outputType" | "wordTimestamps" | "speakerLabels" | "nltk" | "tier">> & Pick<TranscribeOptions, "customVocabulary" | "callbackUrl">;

package/dist/esm/types.js

@@ -0,0 +1,26 @@
+/** Completion as a 0–100 number clamped to [0, 100], or `undefined` if unknown. */
+export function computePercent(completed, total) {
+    if (completed === undefined || completed === null || !total)
+        return undefined;
+    return Math.max(0, Math.min(100, (completed / total) * 100));
+}
+/** Build a {@link ProgressEvent} with its `percent` derived from completed/total. */
+export function makeProgressEvent(event) {
+    return { ...event, percent: computePercent(event.completed, event.total) };
+}
+export function resolveOptions(options = {}) {
+    const speakerLabels = options.diarize !== undefined
+        ? options.diarize
+        : options.speakerLabels !== undefined
+            ? options.speakerLabels
+            : true;
+    return {
+        outputType: options.outputType ?? "json",
+        wordTimestamps: options.wordTimestamps ?? true,
+        speakerLabels,
+        nltk: options.nltk ?? true,
+        tier: options.tier ?? "standard",
+        customVocabulary: options.customVocabulary,
+        callbackUrl: options.callbackUrl,
+    };
+}

package/dist/esm/upload.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Upload-body helpers that report byte-level progress.
+ *
+ * The HTTP client can only observe upload progress if it reads the body through
+ * something we control. For a presigned S3 PUT that's a byte-chunk async
+ * generator (`iterWithProgress`) paired with an explicit `Content-Length`
+ * header, which keeps S3 happy — undici (Node's fetch) would otherwise switch a
+ * streamed body to `Transfer-Encoding: chunked`, which presigned PUTs reject.
+ */
+import { type ProgressCallback } from "./types.js";
+/** Callback receives (bytesSent, totalBytes). */
+export type ByteProgressFn = (sent: number, total: number) => void;
+export declare const UPLOAD_CHUNK_SIZE: number;
+/**
+ * Adapt a {@link ProgressCallback} to a `(sent, total)` byte callback.
+ *
+ * Upload events are reported as `ProgressEvent(step="upload")` so they share the
+ * same shape (and `.percent`) as transcription progress.
+ */
+export declare function byteProgressAdapter(onProgress?: ProgressCallback): ByteProgressFn | undefined;
+/**
+ * Yield `data` in chunks, reporting progress after each — used as the streamed
+ * PUT body. A fresh generator is created per upload attempt, so a retry simply
+ * restarts progress from 0.
+ */
+export declare function iterWithProgress(data: Uint8Array, callback?: ByteProgressFn): AsyncGenerator<Uint8Array>;

package/dist/esm/upload.js

@@ -0,0 +1,39 @@
+/**
+ * Upload-body helpers that report byte-level progress.
+ *
+ * The HTTP client can only observe upload progress if it reads the body through
+ * something we control. For a presigned S3 PUT that's a byte-chunk async
+ * generator (`iterWithProgress`) paired with an explicit `Content-Length`
+ * header, which keeps S3 happy — undici (Node's fetch) would otherwise switch a
+ * streamed body to `Transfer-Encoding: chunked`, which presigned PUTs reject.
+ */
+import { makeProgressEvent } from "./types.js";
+export const UPLOAD_CHUNK_SIZE = 64 * 1024;
+/**
+ * Adapt a {@link ProgressCallback} to a `(sent, total)` byte callback.
+ *
+ * Upload events are reported as `ProgressEvent(step="upload")` so they share the
+ * same shape (and `.percent`) as transcription progress.
+ */
+export function byteProgressAdapter(onProgress) {
+    if (!onProgress)
+        return undefined;
+    return (sent, total) => {
+        onProgress(makeProgressEvent({ completed: sent, total, step: "upload" }));
+    };
+}
+/**
+ * Yield `data` in chunks, reporting progress after each — used as the streamed
+ * PUT body. A fresh generator is created per upload attempt, so a retry simply
+ * restarts progress from 0.
+ */
+export async function* iterWithProgress(data, callback) {
+    const total = data.byteLength;
+    let sent = 0;
+    for (let start = 0; start < total; start += UPLOAD_CHUNK_SIZE) {
+        const chunk = data.subarray(start, Math.min(start + UPLOAD_CHUNK_SIZE, total));
+        sent += chunk.byteLength;
+        yield chunk;
+        callback?.(sent, total);
+    }
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "speechrevolutions",
+  "version": "0.2.0",
+  "description": "Official JavaScript/TypeScript SDK for the Speech Revolutions speech-to-text API",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && npm run build:esm && npm run build:cjs && node scripts/fixup-dist.mjs",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "test:only": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "speech-to-text",
+    "stt",
+    "transcription",
+    "whisper",
+    "asr"
+  ],
+  "author": "Speech Revolutions",
+  "homepage": "https://speechrevolutions.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SpeechRevolutions/node-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/SpeechRevolutions/node-sdk/issues"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.0"
+  }
+}