@transcribe-api/sdk 0.1.0 → 0.1.2

package/index.js

@@ -1,16 +1,1816 @@
+const DEFAULT_BASE_URL = "https://api.transcribeapi.com/v1";
+const MAX_BATCH_FILES = 10000;
+const MAX_BATCH_TOTAL_SIZE_BYTES = 10 * 1024 * 1024 * 1024;
+const MAX_SYNC_AUDIO_BYTES = 30 * 1024 * 1024;
+const MAX_SYNC_AUDIO_SECONDS = 10 * 60;
+const MULTIPART_UPLOAD_THRESHOLD_BYTES = 100 * 1024 * 1024;
+const DEFAULT_MULTIPART_CONCURRENCY = 8;
+const MAX_MULTIPART_CONCURRENCY = 32;
+const MAX_MULTIPART_ADAPTIVE_ATTEMPTS = 12;
+const MULTIPART_IDLE_WAIT_MS = 50;
+const MULTIPART_RESUME_STATE_VERSION = 1;
+const MIN_POLLING_INTERVAL_SECONDS = 10;
+const DEFAULT_POLLING_SPINNER_INTERVAL_MS = 150;
+const TERMINAL_JOB_STATUSES = new Set(["completed", "failed", "insufficient_funds"]);
+const BATCH_MP4_UNSUPPORTED_MESSAGE = "Batch uploads do not support .mp4 for MVP. Supported batch audio formats: mp3, mpeg, mpga, m4a, wav, webm.";
+const BATCH_UNSUPPORTED_MESSAGE = "Unsupported batch audio format. Supported batch audio formats: mp3, mpeg, mpga, m4a, wav, webm.";
+
+export class TranscribeAPIError extends Error {
+  constructor(error, { status = null, code = null, extra = null, response = null } = {}) {
+    super(error);
+    this.name = "TranscribeAPIError";
+    this.status = status;
+    this.code = code;
+    this.error = error;
+    this.response = response;
+    if (extra && typeof extra === "object") {
+      for (const [key, value] of Object.entries(extra)) {
+        if (key === "status" || key === "stack" || key === "name") {
+          continue;
+        }
+        this[key] = value;
+      }
+    }
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function extractErrorInfo(error) {
+  return {
+    name: error?.name || null,
+    message: error?.message || String(error),
+    code: error?.code || error?.cause?.code || null,
+    status: error?.status || null,
+    cause_message: error?.cause?.message || null,
+  };
+}
+
+function isRetryableError(error) {
+  const code = String(error?.code || error?.cause?.code || "");
+  if (
+    code === "ECONNRESET"
+    || code === "ETIMEDOUT"
+    || code === "ECONNREFUSED"
+    || code === "EPIPE"
+    || code === "UND_ERR_SOCKET"
+    || code === "UND_ERR_CONNECT_TIMEOUT"
+    || code === "ERR_SSL_SSLV3_ALERT_BAD_RECORD_MAC"
+  ) {
+    return true;
+  }
+  if (String(error?.message || "").includes("fetch failed")) {
+    return true;
+  }
+  return !error?.status || error.status === 429 || error.status >= 500;
+}
+
+async function retry(operation, { attempts = 3, baseDelayMs = 250 } = {}) {
+  let lastError;
+  for (let index = 0; index < attempts; index += 1) {
+    try {
+      return await operation(index);
+    } catch (error) {
+      lastError = error;
+      const retryable = isRetryableError(error);
+      if (!retryable || index === attempts - 1) {
+        throw error;
+      }
+      await sleep(baseDelayMs * (2 ** index));
+    }
+  }
+  throw lastError;
+}
+
+function normalizeMultipartConcurrency(value) {
+  if (value === undefined || value === null || value === "") {
+    return DEFAULT_MULTIPART_CONCURRENCY;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new TranscribeAPIError("`multipartConcurrency` must be an integer >= 1.", {
+      code: "invalid_multipart_concurrency",
+    });
+  }
+  return Math.min(parsed, MAX_MULTIPART_CONCURRENCY);
+}
+
+function normalizePollingConfig(polling) {
+  if (polling === undefined || polling === null || polling === false) {
+    return null;
+  }
+  if (typeof polling !== "object" || Array.isArray(polling)) {
+    throw new TranscribeAPIError("`polling` must be an object with `interval` in seconds.", {
+      code: "invalid_polling_config",
+    });
+  }
+
+  const interval = Number.parseInt(String(polling.interval ?? ""), 10);
+  if (!Number.isInteger(interval) || interval < MIN_POLLING_INTERVAL_SECONDS) {
+    throw new TranscribeAPIError(`\`polling.interval\` must be an integer >= ${MIN_POLLING_INTERVAL_SECONDS} seconds.`, {
+      code: "invalid_polling_interval",
+    });
+  }
+
+  if (polling.timeout === undefined || polling.timeout === null || polling.timeout === "") {
+    return {
+      interval,
+      timeout: null,
+    };
+  }
+
+  const timeout = Number.parseInt(String(polling.timeout), 10);
+  if (!Number.isInteger(timeout) || timeout < interval) {
+    throw new TranscribeAPIError("`polling.timeout` must be an integer >= `polling.interval` in seconds.", {
+      code: "invalid_polling_timeout",
+    });
+  }
+
+  return {
+    interval,
+    timeout,
+  };
+}
+
+function isNodePathFile(file) {
+  return Boolean(file?.path && typeof file.path === "string");
+}
+
+function multipartResumeStatePath(filePath) {
+  return `${filePath}.transcribe-upload.json`;
+}
+
+function normalizeCompletedParts(parts) {
+  if (!Array.isArray(parts)) {
+    return [];
+  }
+  const deduped = new Map();
+  for (const part of parts) {
+    const partNumber = Number(part?.part_number ?? part?.partNumber);
+    const etag = String(part?.etag || "").trim();
+    if (!Number.isInteger(partNumber) || partNumber < 1 || !etag) {
+      continue;
+    }
+    deduped.set(partNumber, {
+      part_number: partNumber,
+      etag,
+    });
+  }
+  return Array.from(deduped.values()).sort((a, b) => a.part_number - b.part_number);
+}
+
+function serializeUploadForResume(upload) {
+  if (!upload || typeof upload !== "object") {
+    return null;
+  }
+  if (upload.type === "multipart") {
+    return {
+      type: "multipart",
+      key: upload.key || null,
+      upload_id: upload.upload_id || null,
+      part_size: Number(upload.part_size || 0),
+    };
+  }
+  if (upload.type === "put") {
+    return {
+      type: "put",
+      key: upload.key || null,
+      headers: upload.headers || {},
+    };
+  }
+  return null;
+}
+
+async function readMultipartResumeState(file, { baseUrl } = {}) {
+  if (!isNodePathFile(file)) {
+    return null;
+  }
+  try {
+    const fs = await import("node:fs/promises");
+    const raw = await fs.readFile(multipartResumeStatePath(file.path), "utf8");
+    const parsed = JSON.parse(raw);
+    if (
+      Number(parsed?.version) !== MULTIPART_RESUME_STATE_VERSION
+      || String(parsed?.file_path || "") !== String(file.path)
+      || Number(parsed?.file_size || 0) !== Number(file.size || 0)
+      || String(parsed?.file_name || "") !== String(file.name || "")
+    ) {
+      return null;
+    }
+    if (baseUrl && String(parsed?.api_base_url || "") !== String(baseUrl)) {
+      return null;
+    }
+    const upload = serializeUploadForResume(parsed.upload);
+    if (!upload) {
+      return null;
+    }
+    return {
+      version: MULTIPART_RESUME_STATE_VERSION,
+      api_base_url: String(parsed.api_base_url || ""),
+      job_id: String(parsed.job_id || ""),
+      model: parsed.model || null,
+      file_path: String(parsed.file_path || ""),
+      file_name: String(parsed.file_name || ""),
+      file_size: Number(parsed.file_size || 0),
+      upload,
+      completed_parts: normalizeCompletedParts(parsed.completed_parts),
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function writeMultipartResumeState(file, state) {
+  if (!isNodePathFile(file) || !state) {
+    return;
+  }
+  const fs = await import("node:fs/promises");
+  await fs.writeFile(
+    multipartResumeStatePath(file.path),
+    JSON.stringify(state, null, 2),
+    "utf8",
+  );
+}
+
+async function deleteMultipartResumeState(file) {
+  if (!isNodePathFile(file)) {
+    return;
+  }
+  try {
+    const fs = await import("node:fs/promises");
+    await fs.unlink(multipartResumeStatePath(file.path));
+  } catch {
+    // Ignore missing or inaccessible state files.
+  }
+}
+
+function buildMultipartResumeState({ baseUrl, jobId, model, file, upload, completedParts }) {
+  return {
+    version: MULTIPART_RESUME_STATE_VERSION,
+    api_base_url: baseUrl,
+    job_id: jobId,
+    model: model || null,
+    file_path: file.path,
+    file_name: file.name,
+    file_size: file.size,
+    upload: serializeUploadForResume(upload),
+    completed_parts: normalizeCompletedParts(completedParts),
+  };
+}
+
+function contentTypeFromName(name = "") {
+  const lower = String(name).toLowerCase();
+  if (lower.endsWith(".mp3")) return "audio/mpeg";
+  if (lower.endsWith(".mpeg")) return "audio/mpeg";
+  if (lower.endsWith(".mpga")) return "audio/mpeg";
+  if (lower.endsWith(".wav")) return "audio/wav";
+  if (lower.endsWith(".m4a")) return "audio/mp4";
+  if (lower.endsWith(".webm")) return "audio/webm";
+  return "application/octet-stream";
+}
+
+function isRemoteFileInput(input) {
+  return Boolean(input && typeof input === "object" && typeof input.url === "string");
+}
+
+function isRemoteBatchItem(input) {
+  return Boolean(input && typeof input === "object" && typeof input.url === "string");
+}
+
+function defaultReferenceId(index) {
+  return `file_${String(index + 1).padStart(6, "0")}`;
+}
+
+function normalizeBatchInputItem(item, index) {
+  if (!item || typeof item !== "object" || Array.isArray(item)) {
+    throw new TranscribeAPIError("Each batch item must be an object with `reference_id` and either `file` or `url`.", {
+      code: "invalid_batch_item",
+    });
+  }
+
+  const referenceId = String(item.reference_id || "").trim();
+  if (!referenceId) {
+    throw new TranscribeAPIError(`files[${index}].reference_id is required.`, {
+      code: "missing_reference_id",
+    });
+  }
+
+  const hasFile = Object.prototype.hasOwnProperty.call(item, "file");
+  const hasUrl = typeof item.url === "string" && item.url.trim();
+  if (hasFile && hasUrl) {
+    throw new TranscribeAPIError(`files[${index}] must include either \`file\` or \`url\`, not both.`, {
+      code: "invalid_batch_item",
+    });
+  }
+  if (!hasFile && !hasUrl) {
+    throw new TranscribeAPIError(`files[${index}] must include either \`file\` or \`url\`.`, {
+      code: "invalid_batch_item",
+    });
+  }
+
+  return {
+    referenceId,
+    file: hasFile ? item.file : null,
+    url: hasUrl ? item.url.trim() : null,
+    durationEstimateSec: item.durationEstimateSec || item.duration_estimate_sec || null,
+  };
+}
+
+function uploadDescriptorForFile(referenceId, file) {
+  const descriptor = { reference_id: referenceId };
+  if (Number(file?.size || 0) >= MULTIPART_UPLOAD_THRESHOLD_BYTES) {
+    descriptor.size_bytes = Number(file.size || 0);
+  }
+  return descriptor;
+}
+
+function normalizeResponseUploads(response) {
+  if (Array.isArray(response?.uploads)) {
+    return response.uploads;
+  }
+  if (response?.upload) {
+    return [{
+      reference_id: response.reference_id || defaultReferenceId(0),
+      upload: response.upload,
+    }];
+  }
+  return [];
+}
+
+function uploadFromResponse(response, referenceId) {
+  if (response?.upload) {
+    return response.upload;
+  }
+  const entry = normalizeResponseUploads(response)
+    .find((candidate) => candidate.reference_id === referenceId);
+  return entry?.upload || null;
+}
+
+function emitProgress(handler, event) {
+  if (typeof handler !== "function") {
+    return;
+  }
+  handler(event);
+}
+
+function renderProgressBar(loaded, total, width = 30) {
+  if (!total) {
+    return `[${".".repeat(width)}]`;
+  }
+  const ratio = Math.max(0, Math.min(1, Number(loaded || 0) / Number(total || 1)));
+  const filled = Math.round(ratio * width);
+  return `[${"|".repeat(filled)}${".".repeat(Math.max(0, width - filled))}]`;
+}
+
+function formatBytes(bytes) {
+  const value = Number(bytes || 0);
+  if (value < 1024) return `${value} B`;
+  if (value < 1024 ** 2) return `${(value / 1024).toFixed(1)} KB`;
+  if (value < 1024 ** 3) return `${(value / 1024 ** 2).toFixed(1)} MB`;
+  return `${(value / 1024 ** 3).toFixed(2)} GB`;
+}
+
+function createSdkLoggerProgressHandler(logger = console) {
+  let activeProgressLine = false;
+
+  const writeLine = (line) => {
+    if (activeProgressLine && typeof process !== "undefined" && process?.stdout?.write) {
+      process.stdout.write("\n");
+      activeProgressLine = false;
+    }
+    if (typeof logger?.log === "function") {
+      logger.log(line);
+    }
+  };
+
+  const writeProgress = (line) => {
+    if (typeof process !== "undefined" && process?.stdout?.write) {
+      process.stdout.write(`\r${line}`);
+      activeProgressLine = true;
+      return;
+    }
+    if (typeof logger?.log === "function") {
+      logger.log(line);
+    }
+  };
+
+  return (event) => {
+    if (!event || typeof event !== "object") {
+      return;
+    }
+    if (event.event === "upload_started") {
+      writeLine(`Uploading ${event.uploadFiles}/${event.totalFiles} local file(s) for ${event.jobId}, ${formatBytes(event.totalBytes)} total`);
+      return;
+    }
+    if (event.event === "upload_progress") {
+      const loaded = Number(event.batchLoaded ?? event.loaded ?? 0);
+      const total = Number(event.batchTotal ?? event.total ?? 0);
+      const percent = total ? ((loaded / total) * 100).toFixed(1) : "0.0";
+      writeProgress(`Uploading ${renderProgressBar(loaded, total)} ${percent}% (${formatBytes(loaded)} / ${formatBytes(total)})`);
+      if (total && loaded >= total && activeProgressLine && typeof process !== "undefined" && process?.stdout?.write) {
+        process.stdout.write("\n");
+        activeProgressLine = false;
+      }
+      return;
+    }
+    if (event.event === "upload_completed") {
+      if (event.suppressLog) {
+        return;
+      }
+      writeLine(`Uploaded completed: ${JSON.stringify(event.response, null, 2)}`);
+    }
+  };
+}
+
+function createSdkPollingLogger(logger = console) {
+  let spinnerTimer = null;
+  let activeLine = false;
+  let currentFrameIndex = 0;
+  let currentStatus = "waiting";
+  let currentJobId = "unknown_job";
+  let lastRenderedLength = 0;
+  const frames = ["|", "/", "-", "\\"];
+
+  const stopSpinnerLine = () => {
+    if (spinnerTimer) {
+      clearInterval(spinnerTimer);
+      spinnerTimer = null;
+    }
+    if (activeLine && typeof process !== "undefined" && process?.stdout?.write) {
+      process.stdout.write("\n");
+      activeLine = false;
+    }
+  };
+
+  const renderLine = () => {
+    const frame = frames[currentFrameIndex % frames.length];
+    currentFrameIndex += 1;
+    const rawLine = `${frame} Polling ${currentJobId} (${currentStatus})`;
+    const paddedLine = rawLine.padEnd(lastRenderedLength, " ");
+    lastRenderedLength = paddedLine.length;
+    if (typeof process !== "undefined" && process?.stdout?.write) {
+      process.stdout.write(`\r${paddedLine}`);
+      activeLine = true;
+      return;
+    }
+    if (typeof logger?.log === "function") {
+      logger.log(rawLine);
+    }
+  };
+
+  const writeLine = (line) => {
+    stopSpinnerLine();
+    if (typeof logger?.log === "function") {
+      logger.log(line);
+    }
+  };
+
+  return {
+    start({ jobId, jobStatus }) {
+      currentJobId = jobId || currentJobId;
+      currentStatus = jobStatus || currentStatus;
+      currentFrameIndex = 0;
+      if (typeof process !== "undefined" && process?.stdout?.write) {
+        renderLine();
+        spinnerTimer = setInterval(renderLine, DEFAULT_POLLING_SPINNER_INTERVAL_MS);
+        return;
+      }
+      writeLine(`Polling ${currentJobId} (${currentStatus})`);
+    },
+    update({ jobStatus }) {
+      currentStatus = jobStatus || currentStatus;
+      if (!spinnerTimer && !(typeof process !== "undefined" && process?.stdout?.write)) {
+        writeLine(`Polling ${currentJobId} (${currentStatus})`);
+      }
+    },
+    finish({ jobStatus, resultUrl }) {
+      currentStatus = jobStatus || currentStatus;
+      writeLine(resultUrl
+        ? `Polling complete: ${currentStatus} - ${resultUrl}`
+        : `Polling complete: ${currentStatus}`);
+    },
+    timeout({ timeoutSeconds, jobStatus }) {
+      currentStatus = jobStatus || currentStatus;
+      writeLine(`Polling stopped: timeout after ${timeoutSeconds}s (${currentStatus})`);
+    },
+  };
+}
+
+function composeProgressHandler({ onProgress, showLogs = false, logger = console } = {}) {
+  const logHandler = showLogs ? createSdkLoggerProgressHandler(logger) : null;
+  if (!logHandler) {
+    return typeof onProgress === "function" ? onProgress : null;
+  }
+  return (event) => {
+    emitProgress(logHandler, event);
+    emitProgress(onProgress, event);
+  };
+}
+
+function assertSupportedBatchFormat(file) {
+  const lowerName = String(file?.name || "").toLowerCase();
+  const lowerType = String(file?.type || contentTypeFromName(file?.name)).toLowerCase();
+
+  if (lowerName.endsWith(".mp4") || lowerType === "video/mp4") {
+    throw new TranscribeAPIError(BATCH_MP4_UNSUPPORTED_MESSAGE, { code: "unsupported_batch_format" });
+  }
+
+  if (
+    lowerName.endsWith(".mp3")
+    || lowerName.endsWith(".mpeg")
+    || lowerName.endsWith(".mpga")
+    || lowerName.endsWith(".m4a")
+    || lowerName.endsWith(".wav")
+    || lowerName.endsWith(".webm")
+    || lowerType.includes("audio/mpeg")
+    || lowerType.includes("mpga")
+    || lowerType.includes("audio/mp4")
+    || lowerType.includes("audio/x-m4a")
+    || lowerType.includes("audio/wav")
+    || lowerType.includes("audio/wave")
+    || lowerType.includes("audio/webm")
+    || lowerType.includes("video/webm")
+  ) {
+    return;
+  }
+
+  throw new TranscribeAPIError(BATCH_UNSUPPORTED_MESSAGE, { code: "unsupported_batch_format" });
+}
+
+function estimateDurationFromSize(sizeBytes) {
+  return Math.max(1, Math.ceil(Number(sizeBytes || 0) / 16000));
+}
+
+function ascii(bytes, offset, length) {
+  return Array.from(bytes.slice(offset, offset + length), (byte) => String.fromCharCode(byte)).join("");
+}
+
+function readUint32(bytes, offset, littleEndian = false) {
+  return new DataView(bytes.buffer, bytes.byteOffset + offset, 4).getUint32(0, littleEndian);
+}
+
+function readUint64(bytes, offset) {
+  const high = readUint32(bytes, offset);
+  const low = readUint32(bytes, offset + 4);
+  return high * 2 ** 32 + low;
+}
+
+function syncSafeInteger(bytes, offset) {
+  return ((bytes[offset] & 0x7f) << 21)
+    | ((bytes[offset + 1] & 0x7f) << 14)
+    | ((bytes[offset + 2] & 0x7f) << 7)
+    | (bytes[offset + 3] & 0x7f);
+}
+
+function id3Offset(bytes) {
+  if (bytes.length >= 10 && ascii(bytes, 0, 3) === "ID3") {
+    return 10 + syncSafeInteger(bytes, 6);
+  }
+  return 0;
+}
+
+const MP3_BITRATES = {
+  V1L3: [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320],
+  V2L3: [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160],
+};
+
+const MP3_SAMPLE_RATES = {
+  3: [44100, 48000, 32000],
+  2: [22050, 24000, 16000],
+  0: [11025, 12000, 8000],
+};
+
+function mp3FrameInfoAt(bytes, offset) {
+  if (offset + 4 > bytes.length || bytes[offset] !== 0xff || (bytes[offset + 1] & 0xe0) !== 0xe0) {
+    return null;
+  }
+
+  const versionBits = (bytes[offset + 1] >> 3) & 0x03;
+  const layerBits = (bytes[offset + 1] >> 1) & 0x03;
+  const bitrateIndex = (bytes[offset + 2] >> 4) & 0x0f;
+  const sampleRateIndex = (bytes[offset + 2] >> 2) & 0x03;
+  const padding = (bytes[offset + 2] >> 1) & 0x01;
+  if (versionBits === 1 || layerBits !== 1 || bitrateIndex === 0 || bitrateIndex === 15 || sampleRateIndex === 3) {
+    return null;
+  }
+
+  const sampleRate = MP3_SAMPLE_RATES[versionBits]?.[sampleRateIndex];
+  const bitrateKbps = versionBits === 3
+    ? MP3_BITRATES.V1L3[bitrateIndex]
+    : MP3_BITRATES.V2L3[bitrateIndex];
+  if (!sampleRate || !bitrateKbps) {
+    return null;
+  }
+
+  const bitrate = bitrateKbps * 1000;
+  const frameLength = Math.floor(((versionBits === 3 ? 144 : 72) * bitrate) / sampleRate + padding);
+  if (frameLength <= 0) {
+    return null;
+  }
+
+  return {
+    bitrate,
+    sampleRate,
+    frameLength,
+  };
+}
+
+function findMp3Frame(bytes, startOffset = 0) {
+  for (let offset = Math.max(0, startOffset); offset < bytes.length - 4; offset += 1) {
+    const info = mp3FrameInfoAt(bytes, offset);
+    if (info) {
+      return { offset, ...info };
+    }
+  }
+  return null;
+}
+
+function parseMp3Duration(bytes, objectSize) {
+  const offset = id3Offset(bytes);
+  const firstFrame = findMp3Frame(bytes, offset);
+  if (!firstFrame) {
+    return null;
+  }
+  const audioBytes = Math.max(0, Number(objectSize || bytes.length) - firstFrame.offset);
+  const duration = (audioBytes * 8) / firstFrame.bitrate;
+  return Number.isFinite(duration) && duration > 0 ? duration : null;
+}
+
+function parseWavDuration(bytes) {
+  if (bytes.length < 44 || ascii(bytes, 0, 4) !== "RIFF" || ascii(bytes, 8, 4) !== "WAVE") {
+    return null;
+  }
+
+  let offset = 12;
+  let byteRate = 0;
+  let dataSize = 0;
+  while (offset + 8 <= bytes.length) {
+    const chunkId = ascii(bytes, offset, 4);
+    const chunkSize = readUint32(bytes, offset + 4, true);
+    if (chunkId === "fmt " && offset + 20 <= bytes.length) {
+      byteRate = readUint32(bytes, offset + 16, true);
+    } else if (chunkId === "data") {
+      dataSize = chunkSize;
+      break;
+    }
+    offset += 8 + chunkSize + (chunkSize % 2);
+  }
+
+  if (!byteRate || !dataSize) {
+    return null;
+  }
+  return dataSize / byteRate;
+}
+
+function parseMp4Duration(bytes) {
+  for (let offset = 0; offset + 32 < bytes.length; offset += 1) {
+    if (ascii(bytes, offset + 4, 4) !== "mvhd") {
+      continue;
+    }
+    const size = readUint32(bytes, offset);
+    if (size < 32 || offset + size > bytes.length + 8) {
+      continue;
+    }
+    const version = bytes[offset + 8];
+    if (version === 0 && offset + 28 <= bytes.length) {
+      const timescale = readUint32(bytes, offset + 20);
+      const duration = readUint32(bytes, offset + 24);
+      return timescale > 0 ? duration / timescale : null;
+    }
+    if (version === 1 && offset + 40 <= bytes.length) {
+      const timescale = readUint32(bytes, offset + 28);
+      const duration = readUint64(bytes, offset + 32);
+      return timescale > 0 ? duration / timescale : null;
+    }
+  }
+  return null;
+}
+
+function typeFromNameOrContentType(name = "", contentType = "") {
+  const lowerName = String(name || "").toLowerCase();
+  const lowerType = String(contentType || "").toLowerCase();
+  if (lowerType.includes("wav") || lowerName.endsWith(".wav")) {
+    return "wav";
+  }
+  if (
+    lowerType.includes("mp4")
+    || lowerType.includes("m4a")
+    || lowerType.includes("audio/x-m4a")
+    || lowerName.endsWith(".m4a")
+  ) {
+    return "m4a";
+  }
+  return "mp3";
+}
+
+async function estimateDurationFromFile(file) {
+  const headerLength = Math.min(Number(file?.size || 0), 2 * 1024 * 1024);
+  if (!headerLength) {
+    return estimateDurationFromSize(file?.size);
+  }
+
+  try {
+    let bytes;
+    if (typeof file?.readSlice === "function") {
+      bytes = new Uint8Array(await file.readSlice(0, headerLength));
+    } else if (typeof file?.slice === "function") {
+      bytes = new Uint8Array(await file.slice(0, headerLength).arrayBuffer());
+    } else {
+      return estimateDurationFromSize(file?.size);
+    }
+    const type = typeFromNameOrContentType(file?.name, file?.type || contentTypeFromName(file?.name));
+    const duration = type === "wav"
+      ? parseWavDuration(bytes)
+      : type === "m4a"
+        ? parseMp4Duration(bytes)
+        : parseMp3Duration(bytes, file.size);
+    if (Number.isFinite(duration) && duration > 0) {
+      return Math.max(1, Math.ceil(duration));
+    }
+  } catch {
+    // Fall back to the coarse size heuristic when metadata parsing fails.
+  }
+
+  return estimateDurationFromSize(file?.size);
+}
+
+async function fileFromPath(pathValue) {
+  const fs = await import("node:fs/promises");
+  const path = await import("node:path");
+  const stats = await fs.stat(pathValue);
+  const name = path.basename(pathValue);
+  return {
+    name,
+    size: stats.size,
+    type: contentTypeFromName(name),
+    path: pathValue,
+    async readSlice(start, end) {
+      const handle = await fs.open(pathValue, "r");
+      try {
+        const length = Math.max(0, end - start);
+        const buffer = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buffer, 0, length, start);
+        return buffer.subarray(0, bytesRead);
+      } finally {
+        await handle.close();
+      }
+    },
+  };
+}
+
+function makeFile(parts, name, type) {
+  if (typeof File !== "undefined") {
+    return new File(parts, name, { type });
+  }
+  const blob = new Blob(parts, { type });
+  Object.defineProperty(blob, "name", { value: name });
+  return blob;
+}
+
+async function normalizeFile(input, fallbackName = "audio.mp3") {
+  if (
+    input
+    && typeof input === "object"
+    && typeof input.name === "string"
+    && Number.isFinite(Number(input.size))
+    && typeof input.type === "string"
+    && (typeof input.readSlice === "function" || typeof input.slice === "function")
+  ) {
+    return input;
+  }
+  if (typeof input === "string") {
+    return fileFromPath(input);
+  }
+  if (typeof File !== "undefined" && input instanceof File) {
+    return input;
+  }
+  if (input instanceof Blob) {
+    return input.name ? input : makeFile([input], fallbackName, input.type || contentTypeFromName(fallbackName));
+  }
+  if (input?.data instanceof Uint8Array || input?.data instanceof ArrayBuffer) {
+    return makeFile([input.data], input.name || fallbackName, input.type || contentTypeFromName(input.name || fallbackName));
+  }
+  throw new TranscribeAPIError("Invalid file. Provide a path, File, Blob, or { data, name, type }.");
+}
+
+async function parseApiResponse(response) {
+  const text = await response.text();
+  let data = {};
+  try {
+    data = text ? JSON.parse(text) : {};
+  } catch {
+    data = { raw: text };
+  }
+  if (!response.ok) {
+    throw new TranscribeAPIError(data.error || text || `HTTP ${response.status}`, {
+      status: response.status,
+      code: data.code || null,
+      extra: data,
+      response: data,
+    });
+  }
+  return data;
+}
+
+function normalizeHeaders(headers = {}) {
+  return Object.fromEntries(
+    Object.entries(headers)
+      .filter(([, value]) => value !== undefined && value !== null)
+      .map(([key, value]) => [key, String(value)]),
+  );
+}
+
+function isNodeStreamBody(body) {
+  return Boolean(body && typeof body === "object" && typeof body.pipe === "function");
+}
+
+async function putNodeStream(upload, streamBody, headers) {
+  const http = await import("node:http");
+  const https = await import("node:https");
+  const { pipeline } = await import("node:stream/promises");
+  const target = new URL(upload.url || upload);
+  const transport = target.protocol === "https:" ? https : http;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finishResolve = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(value);
+    };
+    const finishReject = (error) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      reject(error);
+    };
+    const request = transport.request(target, {
+      method: "PUT",
+      headers,
+      agent: false,
+    }, (response) => {
+      response.resume();
+      response.on("error", finishReject);
+      response.on("end", () => {
+        finishResolve({
+          ok: response.statusCode >= 200 && response.statusCode < 300,
+          status: response.statusCode || 0,
+          headers: {
+            get(name) {
+              const value = response.headers[String(name || "").toLowerCase()];
+              return Array.isArray(value) ? value[0] : value || null;
+            },
+          },
+        });
+      });
+    });
+
+    request.on("error", finishReject);
+    request.on("socket", (socket) => {
+      socket.on("error", finishReject);
+    });
+    request.setTimeout(120000, () => {
+      request.destroy(new Error("stream_upload_timeout"));
+    });
+    if (typeof streamBody.on === "function") {
+      streamBody.on("error", finishReject);
+    }
+    pipeline(streamBody, request).catch(finishReject);
+  });
+}
+
+async function putObjectWithRetry(upload, body, {
+  onProgress,
+  loadedOffset = 0,
+  totalBytes = 0,
+  contentLength = null,
+  progressMeta = null,
+  debugContext = null,
+} = {}) {
+  const response = await retry(async (attemptIndex) => {
+    const resolvedBody = typeof body === "function" ? await body() : body;
+    const headers = normalizeHeaders({
+      ...(upload.headers || {}),
+      ...(contentLength !== null ? { "Content-Length": contentLength } : {}),
+      ...(typeof body === "function" ? { Connection: "close" } : {}),
+    });
+    const putResponse = isNodeStreamBody(resolvedBody)
+      ? await putNodeStream(upload, resolvedBody, headers)
+      : await fetch(upload.url || upload, {
+        method: "PUT",
+        headers,
+        body: resolvedBody,
+      });
+    if (!putResponse.ok) {
+      throw new TranscribeAPIError(`R2 upload failed with HTTP ${putResponse.status}.`, {
+        status: putResponse.status,
+        code: "upload_failed",
+        extra: {
+          ...(progressMeta || {}),
+          ...(debugContext || {}),
+          content_length: contentLength,
+        },
+      });
+    }
+    return putResponse;
+  }, {
+    attempts: 5,
+    baseDelayMs: 1000,
+  });
+  const transferredBytes = Number(
+    contentLength
+    ?? body?.size
+    ?? body?.byteLength
+    ?? 0,
+  );
+  const loaded = loadedOffset + transferredBytes;
+  if (onProgress) {
+    onProgress({
+      loaded,
+      total: totalBytes || loaded,
+      ...(progressMeta || {}),
+    });
+  }
+  return response;
+}
+
+async function openFileBody(file, start = 0, end = null) {
+  if (!file?.path) {
+    return file;
+  }
+  const fs = await import("node:fs");
+  return fs.createReadStream(file.path, end === null ? { start } : { start, end: end - 1 });
+}
+
+async function runWithConcurrency(items, concurrency, worker) {
+  let index = 0;
+  const workerCount = Math.max(1, Math.min(items.length || 1, concurrency));
+  const workers = Array.from({ length: workerCount }, async () => {
+    while (true) {
+      const current = index;
+      index += 1;
+      if (current >= items.length) {
+        return;
+      }
+      await worker(items[current], current);
+    }
+  });
+  await Promise.all(workers);
+}
+
+function multipartCompleteXml(parts) {
+  const rows = parts
+    .sort((a, b) => a.partNumber - b.partNumber)
+    .map((part) => `<Part><PartNumber>${part.partNumber}</PartNumber><ETag>${part.etag}</ETag></Part>`)
+    .join("");
+  return `<CompleteMultipartUpload>${rows}</CompleteMultipartUpload>`;
+}
+
+async function uploadMultipart(upload, file, {
+  onProgress,
+  multipartConcurrency = DEFAULT_MULTIPART_CONCURRENCY,
+  resumeState = null,
+  onPartComplete = null,
+  onConcurrencyChange = null,
+} = {}) {
+  const completed = normalizeCompletedParts(resumeState?.completed_parts).map((part) => ({
+    partNumber: part.part_number,
+    etag: part.etag,
+  }));
+  const totalParts = upload.parts.length;
+  const completedPartNumbers = new Set(completed.map((part) => part.partNumber));
+  let completedBytes = completed.reduce((total, part) => {
+    const start = (part.partNumber - 1) * upload.part_size;
+    const end = Math.min(file.size, start + upload.part_size);
+    return total + Math.max(0, end - start);
+  }, 0);
+  const concurrency = normalizeMultipartConcurrency(multipartConcurrency);
+  let targetConcurrency = concurrency;
+  let activeWorkers = 0;
+  let fatalError = null;
+  const pendingParts = upload.parts.filter((part) => !completedPartNumbers.has(part.part_number));
+  const partAttempts = new Map();
+
+  if (onProgress && completedBytes > 0) {
+    onProgress({
+      loaded: completedBytes,
+      total: file.size,
+      uploadType: "multipart",
+      totalParts,
+      multipartConcurrency: targetConcurrency,
+      resumed: true,
+    });
+  }
+
+  const workers = Array.from({ length: concurrency }, async (_, workerIndex) => {
+    while (true) {
+      if (fatalError) {
+        return;
+      }
+      if (completedPartNumbers.size >= totalParts) {
+        return;
+      }
+      if (workerIndex >= targetConcurrency) {
+        await sleep(MULTIPART_IDLE_WAIT_MS);
+        continue;
+      }
+      const part = pendingParts.shift();
+      if (!part) {
+        if (!activeWorkers) {
+          return;
+        }
+        await sleep(MULTIPART_IDLE_WAIT_MS);
+        continue;
+      }
+
+      activeWorkers += 1;
+      const start = (part.part_number - 1) * upload.part_size;
+      const end = Math.min(file.size, start + upload.part_size);
+      const chunkSize = end - start;
+      try {
+        const response = await putObjectWithRetry(
+          { url: part.url },
+          file.path ? (() => openFileBody(file, start, end)) : file.slice(start, end),
+          {
+            onProgress: null,
+            loadedOffset: 0,
+            totalBytes: file.size,
+            contentLength: chunkSize,
+            progressMeta: {
+              uploadType: "multipart",
+              partNumber: part.part_number,
+              totalParts,
+              chunkBytes: chunkSize,
+            },
+            debugContext: {
+              file_name: file?.name || null,
+              file_size: file?.size || null,
+              range_start: start,
+              range_end_exclusive: end,
+            },
+          },
+        );
+        const etag = response.headers.get("ETag") || response.headers.get("etag");
+        completed.push({
+          partNumber: part.part_number,
+          etag,
+        });
+        completedPartNumbers.add(part.part_number);
+        completedBytes += chunkSize;
+        if (onPartComplete) {
+          try {
+            await onPartComplete({
+              partNumber: part.part_number,
+              etag,
+              completedParts: completed,
+            });
+          } catch {
+            // Resume-state persistence is best-effort.
+          }
+        }
+        if (onProgress) {
+          onProgress({
+            loaded: completedBytes,
+            total: file.size,
+            uploadType: "multipart",
+            partNumber: part.part_number,
+            totalParts,
+            chunkBytes: chunkSize,
+            multipartConcurrency: targetConcurrency,
+          });
+        }
+      } catch (error) {
+        const attempts = (partAttempts.get(part.part_number) || 0) + 1;
+        partAttempts.set(part.part_number, attempts);
+        const retryable = isRetryableError(error);
+        if (retryable && attempts < MAX_MULTIPART_ADAPTIVE_ATTEMPTS) {
+          const previousConcurrency = targetConcurrency;
+          targetConcurrency = Math.max(1, Math.floor(targetConcurrency / 2));
+          pendingParts.push(part);
+          if (onConcurrencyChange && targetConcurrency !== previousConcurrency) {
+            try {
+              onConcurrencyChange({
+                previousConcurrency,
+                nextConcurrency: targetConcurrency,
+                partNumber: part.part_number,
+                attempts,
+                error: extractErrorInfo(error),
+              });
+            } catch {
+              // Ignore observer failures.
+            }
+          }
+          activeWorkers -= 1;
+          await sleep(Math.min(10000, 1000 * (2 ** Math.min(attempts - 1, 3))));
+          continue;
+        }
+        fatalError = new TranscribeAPIError(
+          `Multipart upload failed for part ${part.part_number}/${totalParts}.`,
+          {
+            status: error?.status || null,
+            code: error?.code || "multipart_part_upload_failed",
+            extra: {
+              cause_error: error?.error || error?.message || String(error),
+              cause_code: error?.code || error?.cause?.code || null,
+              cause_status: error?.status || null,
+              upload_type: "multipart",
+              part_number: part.part_number,
+              total_parts: totalParts,
+              chunk_bytes: chunkSize,
+              completed_bytes_before_failure: completedBytes,
+              multipart_concurrency: targetConcurrency,
+              file_name: file?.name || null,
+              file_size: file?.size || null,
+              range_start: start,
+              range_end_exclusive: end,
+              attempts,
+            },
+          },
+        );
+        activeWorkers -= 1;
+        return;
+      }
+      activeWorkers -= 1;
+    }
+  });
+
+  await Promise.all(workers);
+  if (fatalError) {
+    throw fatalError;
+  }
+
+  const completeResponse = await retry(async () => {
+    const response = await fetch(upload.complete_url, {
+      method: "POST",
+      headers: { "Content-Type": "application/xml" },
+      body: multipartCompleteXml(completed),
+    });
+    if (!response.ok) {
+      throw new TranscribeAPIError(`R2 multipart complete failed with HTTP ${response.status}.`, {
+        status: response.status,
+        code: "multipart_complete_failed",
+      });
+    }
+    return response;
+  });
+  return completeResponse;
+}
+
+async function uploadUsingInstructions(upload, file, options = {}) {
+  if (upload.type === "multipart") {
+    return uploadMultipart(upload, file, options);
+  }
+  const body = file.path ? (() => openFileBody(file)) : file;
+  return putObjectWithRetry(upload, body, {
+    onProgress: options.onProgress,
+    loadedOffset: 0,
+    totalBytes: file.size,
+    contentLength: file.size,
+    progressMeta: {
+      uploadType: "single_put",
+      chunkBytes: file.size,
+    },
+    debugContext: {
+      file_name: file?.name || null,
+      file_size: file?.size || null,
+    },
+  });
+}
+
+function assertBatchLimits(totalFiles, totalSizeBytes) {
+  if (totalFiles > MAX_BATCH_FILES) {
+    throw new TranscribeAPIError(`Batch jobs support up to ${MAX_BATCH_FILES} files.`, {
+      code: "too_many_files",
+    });
+  }
+  if (totalSizeBytes > MAX_BATCH_TOTAL_SIZE_BYTES) {
+    throw new TranscribeAPIError("Batch jobs support up to 10GB total.", {
+      code: "batch_too_large",
+    });
+  }
+}
+
+class BigFileJob {
+  constructor(client, file, createResponse, options) {
+    this.client = client;
+    this.file = file;
+    this.createResponse = createResponse;
+    this.referenceId = options.referenceId || defaultReferenceId(0);
+    this.jobId = createResponse.job_id;
+    this.jobStatus = createResponse.job_status;
+    this.model = createResponse.model || options.model || null;
+    this.uploadInfo = uploadFromResponse(createResponse, this.referenceId);
+    this.options = options;
+    this.resumeState = options.resumeState || null;
+    this.resumeWriteChain = Promise.resolve();
+  }
+
+  async persistResumeState(completedParts = this.resumeState?.completed_parts || []) {
+    if (!isNodePathFile(this.file) || this.uploadInfo?.type !== "multipart") {
+      return;
+    }
+    const state = buildMultipartResumeState({
+      baseUrl: this.client.baseUrl,
+      jobId: this.jobId,
+      model: this.model,
+      file: this.file,
+      upload: this.uploadInfo,
+      completedParts,
+    });
+    this.resumeState = state;
+    this.resumeWriteChain = this.resumeWriteChain
+      .catch(() => {})
+      .then(() => writeMultipartResumeState(this.file, state))
+      .catch(() => {});
+    await this.resumeWriteChain;
+  }
+
+  async clearResumeState() {
+    await this.resumeWriteChain.catch(() => {});
+    await deleteMultipartResumeState(this.file);
+    this.resumeState = null;
+  }
+
+  async upload({ onProgress } = {}) {
+    const progress = onProgress || this.options.onProgress;
+    if (!this.uploadInfo) {
+      return this.createResponse;
+    }
+    if (this.uploadInfo.type === "multipart" && isNodePathFile(this.file)) {
+      const persisted = this.resumeState || await readMultipartResumeState(this.file, {
+        baseUrl: this.client.baseUrl,
+      });
+      if (persisted?.job_id === this.jobId && persisted.upload?.type === "multipart") {
+        this.resumeState = persisted;
+        try {
+          const refreshed = await this.client.refreshBigFileUpload(this.jobId, {
+            upload: persisted.upload,
+          });
+          this.uploadInfo = refreshed;
+        } catch (error) {
+          if (error?.status === 404 || error?.code === "not_found") {
+            await this.clearResumeState();
+          }
+          if (error?.status === 409) {
+            const currentJob = await this.client.jobs.get(this.jobId);
+            this.jobStatus = currentJob?.job_status || this.jobStatus;
+            this.uploadInfo = null;
+            await this.clearResumeState();
+            return currentJob;
+          }
+          if (!(error?.status === 404 || error?.code === "not_found")) {
+            throw error;
+          }
+        }
+      }
+      await this.persistResumeState(this.resumeState?.completed_parts || []);
+    }
+    await uploadUsingInstructions(this.uploadInfo, this.file, {
+      onProgress: progress,
+      multipartConcurrency: this.options.multipartConcurrency,
+      resumeState: this.resumeState,
+      onPartComplete: async ({ completedParts }) => {
+        if (!isNodePathFile(this.file) || this.uploadInfo?.type !== "multipart") {
+          return;
+        }
+        await this.persistResumeState(completedParts.map((part) => ({
+          part_number: part.partNumber,
+          etag: part.etag,
+        })));
+      },
+      onConcurrencyChange: (event) => {
+        if (typeof onProgress === "function" || typeof this.options.onProgress === "function") {
+          (onProgress || this.options.onProgress)({
+            uploadType: "multipart",
+            event: "adaptive_concurrency",
+            previousConcurrency: event.previousConcurrency,
+            multipartConcurrency: event.nextConcurrency,
+            partNumber: event.partNumber,
+            attempts: event.attempts,
+            error: event.error,
+          });
+        }
+      },
+    });
+    await this.clearResumeState();
+    const completion = await this.client.jobs.complete(this.jobId);
+    emitProgress(progress, {
+      event: "upload_completed",
+      jobId: this.jobId,
+      response: completion,
+      suppressLog: Boolean(this.client.polling),
+    });
+    return completion;
+  }
+}
+
+class RemoteBigFileJob {
+  constructor(client, createResponse, options) {
+    this.client = client;
+    this.createResponse = createResponse;
+    this.jobId = createResponse.job_id;
+    this.jobStatus = createResponse.job_status;
+    this.model = createResponse.model || options.model || null;
+    this.options = options;
+  }
+
+  async upload() {
+    return this.createResponse;
+  }
+}
+
+class BatchJob {
+  constructor(client, files, createResponse, options) {
+    this.client = client;
+    this.files = files;
+    this.createResponse = createResponse;
+    this.jobId = createResponse.job_id;
+    this.jobStatus = createResponse.job_status;
+    this.model = createResponse.model || options.model || null;
+    this.uploadsByReferenceId = new Map(
+      normalizeResponseUploads(createResponse).map((entry) => [entry.reference_id, entry.upload]),
+    );
+    this.options = options;
+  }
+
+  async upload({ onProgress } = {}) {
+    if (!this.uploadsByReferenceId.size) {
+      return this.createResponse;
+    }
+
+    const progress = onProgress || this.options.onProgress;
+    const totalBytes = this.files.reduce((sum, item) => sum + Number(item?.file?.size || 0), 0);
+    const loadedByReferenceId = new Map();
+    const uploadableFiles = this.files.filter((item) => item.file);
+
+    emitProgress(progress, {
+      event: "upload_started",
+      jobId: this.jobId,
+      totalFiles: this.files.length,
+      uploadFiles: uploadableFiles.length,
+      totalBytes,
+    });
+
+    for (const item of this.files) {
+      if (!item.file) {
+        continue;
+      }
+      const upload = this.uploadsByReferenceId.get(item.referenceId);
+      if (!upload) {
+        throw new TranscribeAPIError(`Missing upload instructions for \`${item.referenceId}\`.`, {
+          code: "missing_upload_instructions",
+        });
+      }
+      await uploadUsingInstructions(upload, item.file, {
+        onProgress: (event) => {
+          const fileLoaded = Math.max(0, Math.min(Number(event?.loaded || 0), Number(item.file.size || 0)));
+          loadedByReferenceId.set(item.referenceId, fileLoaded);
+          const batchLoaded = Array.from(loadedByReferenceId.values())
+            .reduce((sum, value) => sum + Number(value || 0), 0);
+          emitProgress(progress, {
+            ...event,
+            event: event?.event || "upload_progress",
+            referenceId: item.referenceId,
+            fileLoaded,
+            fileTotal: Number(item.file.size || 0),
+            batchLoaded,
+            batchTotal: totalBytes,
+            totalFiles: this.files.length,
+            uploadFiles: uploadableFiles.length,
+          });
+        },
+      });
+    }
+    const completion = await this.client.jobs.complete(this.jobId);
+    emitProgress(progress, {
+      event: "upload_completed",
+      jobId: this.jobId,
+      response: completion,
+      batchLoaded: totalBytes,
+      batchTotal: totalBytes,
+      totalFiles: this.files.length,
+      uploadFiles: uploadableFiles.length,
+      suppressLog: Boolean(this.client.polling),
+    });
+    return completion;
+  }
+}
+
 export class TranscribeAPI {
-  constructor({ apiKey, baseUrl = "https://api.transcribeapi.com/v1" }) {
+  constructor({
+    apiKey,
+    baseUrl = DEFAULT_BASE_URL,
+    multipartConcurrency = DEFAULT_MULTIPART_CONCURRENCY,
+    showLogs = false,
+    logger = console,
+    polling = null,
+  } = {}) {
     if (!apiKey) {
       throw new Error("Missing API key");
     }
 
     this.apiKey = apiKey;
     this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.multipartConcurrency = normalizeMultipartConcurrency(multipartConcurrency);
+    this.showLogs = Boolean(showLogs);
+    this.logger = logger || console;
+    this.polling = normalizePollingConfig(polling);
+    this.batch = {
+      transcribe: (options) => this.transcribeMany(options),
+    };
+    this.jobs = {
+      createBigFile: (options) => this.createBigFileJob(options),
+      createBatch: (options) => this.createBatchJob(options),
+      uploadCompleted: (jobId) => this.requestJson(`/transcribe/${jobId}/upload-completed`, { method: "POST", retryable: true }),
+      complete: (jobId) => this.requestJson(`/transcribe/${jobId}/upload-completed`, { method: "POST", retryable: true }),
+      get: (jobId) => this.requestJson(`/transcribe/${jobId}`),
+      result: (jobId) => this.requestJson(`/transcribe/${jobId}`),
+    };
+  }
+
+  async requestJson(path, { method = "GET", body = null, retryable = false } = {}) {
+    const run = async () => {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        method,
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : null,
+      });
+      return parseApiResponse(response);
+    };
+    return retryable ? retry(run) : run();
+  }
+
+  async refreshBigFileUpload(jobId, { upload } = {}) {
+    const response = await this.requestJson(`/jobs/${jobId}/resume-upload`, {
+      method: "POST",
+      body: { upload },
+      retryable: true,
+    });
+    return response.upload;
   }
 
-  async transcribe() {
-    throw new Error(
-      "The Transcribe API JavaScript SDK is coming soon. For now, use the REST API docs at https://transcribeapi.com."
-    );
+  async waitForJobCompletion(jobId, {
+    polling = this.polling,
+    showLogs = this.showLogs,
+    logger = this.logger,
+    initialJob = null,
+  } = {}) {
+    const effectivePolling = normalizePollingConfig(polling);
+    if (!effectivePolling) {
+      return this.jobs.get(jobId);
+    }
+
+    const startedAt = Date.now();
+    const spinner = showLogs ? createSdkPollingLogger(logger) : null;
+    let lastJob = initialJob || null;
+    spinner?.start({
+      jobId,
+      jobStatus: lastJob?.job_status || "waiting",
+    });
+
+    while (!TERMINAL_JOB_STATUSES.has(String(lastJob?.job_status || ""))) {
+      if (effectivePolling.timeout !== null && (Date.now() - startedAt) >= effectivePolling.timeout * 1000) {
+        spinner?.timeout({
+          timeoutSeconds: effectivePolling.timeout,
+          jobStatus: lastJob?.job_status || "unknown",
+        });
+        throw new TranscribeAPIError(`Polling timed out after ${effectivePolling.timeout} seconds.`, {
+          code: "polling_timeout",
+          extra: {
+            job_id: jobId,
+            job_status: lastJob?.job_status || null,
+            last_job: lastJob,
+          },
+          response: lastJob,
+        });
+      }
+
+      await sleep(effectivePolling.interval * 1000);
+      lastJob = await this.jobs.get(jobId);
+      spinner?.update({
+        jobStatus: lastJob?.job_status || "unknown",
+      });
+    }
+
+    spinner?.finish({
+      jobStatus: lastJob?.job_status || "unknown",
+      resultUrl: lastJob?.result_url || null,
+    });
+    return lastJob;
   }
-}
+
+  async transcribe({
+    file,
+    webhookUrl,
+    onProgress,
+    showLogs,
+    logger,
+    language,
+    task,
+    vadFilter,
+    initialPrompt,
+    vttGranularity,
+    exclude,
+    multipartConcurrency,
+  } = {}) {
+    const progress = composeProgressHandler({
+      onProgress,
+      showLogs: showLogs ?? this.showLogs,
+      logger: logger ?? this.logger,
+    });
+    if (isRemoteFileInput(file)) {
+      const job = await this.createBigFileJob({
+        file,
+        webhookUrl,
+        onProgress: progress,
+        showLogs: false,
+        multipartConcurrency,
+      });
+      const result = await job.upload({ onProgress: progress });
+      if (this.polling && !TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
+        return this.waitForJobCompletion(result.job_id, {
+          polling: this.polling,
+          showLogs: showLogs ?? this.showLogs,
+          logger: logger ?? this.logger,
+          initialJob: result,
+        });
+      }
+      return result;
+    }
+
+    const normalizedFile = await normalizeFile(file);
+    const estimatedDurationSec = await estimateDurationFromFile(normalizedFile);
+    if (normalizedFile.size > MAX_SYNC_AUDIO_BYTES || estimatedDurationSec > MAX_SYNC_AUDIO_SECONDS) {
+      const job = await this.createBigFileJob({
+        file: normalizedFile,
+        webhookUrl,
+        durationEstimateSec: estimatedDurationSec,
+        onProgress: progress,
+        showLogs: false,
+        multipartConcurrency,
+      });
+      const result = await job.upload({ onProgress: progress });
+      if (this.polling && !TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
+        return this.waitForJobCompletion(result.job_id, {
+          polling: this.polling,
+          showLogs: showLogs ?? this.showLogs,
+          logger: logger ?? this.logger,
+          initialJob: result,
+        });
+      }
+      return result;
+    }
+
+    return this.transcribeDirect({
+      file: normalizedFile,
+      language,
+      task,
+      vadFilter,
+      initialPrompt,
+      vttGranularity,
+      exclude,
+    });
+  }
+
+  async transcribeDirect({
+    file,
+    language,
+    task,
+    vadFilter,
+    initialPrompt,
+    vttGranularity,
+    exclude,
+  } = {}) {
+    const normalizedFile = await normalizeFile(file);
+    const directFile = normalizedFile.path
+      ? makeFile([await normalizedFile.readSlice(0, normalizedFile.size)], normalizedFile.name, normalizedFile.type)
+      : normalizedFile;
+    const form = new FormData();
+    form.set("file", directFile, directFile.name);
+    if (language) form.set("language", language);
+    if (task) form.set("task", task);
+    if (vadFilter !== undefined) form.set("vad_filter", String(Boolean(vadFilter)));
+    if (initialPrompt) form.set("initial_prompt", initialPrompt);
+    if (vttGranularity) form.set("vtt_granularity", vttGranularity);
+    if (exclude) form.set("exclude", Array.isArray(exclude) ? exclude.join(",") : exclude);
+
+    const response = await fetch(`${this.baseUrl}/transcribe`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: form,
+    });
+    return parseApiResponse(response);
+  }
+
+  async transcribeMany({
+    files,
+    webhookUrl,
+    durationEstimateSec,
+    onProgress,
+    showLogs,
+    logger,
+    multipartConcurrency,
+  } = {}) {
+    const progress = composeProgressHandler({
+      onProgress,
+      showLogs: showLogs ?? this.showLogs,
+      logger: logger ?? this.logger,
+    });
+    const job = await this.createBatchJob({
+      files,
+      webhookUrl,
+      durationEstimateSec,
+      onProgress: progress,
+      showLogs: false,
+      multipartConcurrency,
+    });
+    const result = await job.upload({ onProgress: progress });
+    if (this.polling && !TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
+      return this.waitForJobCompletion(result.job_id, {
+        polling: this.polling,
+        showLogs: showLogs ?? this.showLogs,
+        logger: logger ?? this.logger,
+        initialJob: result,
+      });
+    }
+    return result;
+  }
+
+  async createBigFileJob({
+    file,
+    webhookUrl,
+    durationEstimateSec,
+    onProgress,
+    showLogs,
+    logger,
+    multipartConcurrency,
+  } = {}) {
+    const progress = composeProgressHandler({
+      onProgress,
+      showLogs: showLogs ?? this.showLogs,
+      logger: logger ?? this.logger,
+    });
+    const normalizedConcurrency = normalizeMultipartConcurrency(multipartConcurrency ?? this.multipartConcurrency);
+    if (isRemoteFileInput(file)) {
+      const response = await this.requestJson("/transcribe", {
+        method: "POST",
+        body: {
+          files: [{
+            reference_id: defaultReferenceId(0),
+            url: file.url,
+          }],
+          ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
+        },
+        retryable: true,
+      });
+      return new RemoteBigFileJob(this, response, {
+        onProgress: progress,
+        multipartConcurrency: normalizedConcurrency,
+      });
+    }
+
+    const normalizedFile = await normalizeFile(file);
+    const resumeState = await readMultipartResumeState(normalizedFile, { baseUrl: this.baseUrl });
+    if (resumeState?.job_id && resumeState.upload?.type === "multipart") {
+      try {
+        const refreshedUpload = await this.refreshBigFileUpload(resumeState.job_id, {
+          upload: resumeState.upload,
+        });
+        const existingJob = await this.requestJson(`/transcribe/${resumeState.job_id}`, { retryable: true });
+        const currentStatus = existingJob?.job_status || "uploading";
+        return new BigFileJob(this, normalizedFile, {
+          job_id: resumeState.job_id,
+          job_status: currentStatus,
+          model: existingJob?.model || resumeState.model || null,
+          upload: currentStatus === "uploading" ? refreshedUpload : null,
+        }, {
+          onProgress: progress,
+          multipartConcurrency: normalizedConcurrency,
+          referenceId: defaultReferenceId(0),
+          resumeState,
+        });
+      } catch (error) {
+        if (error?.status === 404 || error?.code === "not_found") {
+          await deleteMultipartResumeState(normalizedFile);
+        } else {
+          throw error;
+        }
+      }
+    }
+    const estimate = durationEstimateSec || await estimateDurationFromFile(normalizedFile);
+    const response = await this.requestJson("/transcribe", {
+      method: "POST",
+      body: {
+        files: [
+          estimate > MAX_SYNC_AUDIO_SECONDS || normalizedFile.size > MAX_SYNC_AUDIO_BYTES
+            ? uploadDescriptorForFile(defaultReferenceId(0), normalizedFile)
+            : { reference_id: defaultReferenceId(0) },
+        ],
+        ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
+      },
+      retryable: true,
+    });
+    emitProgress(progress, {
+      event: "upload_urls_received",
+      jobId: response.job_id,
+      jobStatus: response.job_status,
+      uploadCount: normalizeResponseUploads(response).length,
+      totalFiles: 1,
+    });
+    const job = new BigFileJob(this, normalizedFile, response, {
+      onProgress: progress,
+      multipartConcurrency: normalizedConcurrency,
+      referenceId: defaultReferenceId(0),
+    });
+    if (uploadFromResponse(response, defaultReferenceId(0))?.type === "multipart" && isNodePathFile(normalizedFile)) {
+      await job.persistResumeState([]);
+    }
+    return job;
+  }
+
+  async createBatchJob({
+    files,
+    webhookUrl,
+    durationEstimateSec,
+    onProgress,
+    showLogs,
+    logger,
+    multipartConcurrency,
+  } = {}) {
+    const progress = composeProgressHandler({
+      onProgress,
+      showLogs: showLogs ?? this.showLogs,
+      logger: logger ?? this.logger,
+    });
+    if (!Array.isArray(files) || files.length === 0) {
+      throw new TranscribeAPIError("Batch upload requires at least one file.", { code: "invalid_files" });
+    }
+    assertBatchLimits(files.length, 0);
+    const normalizedItems = files.map((item, index) => normalizeBatchInputItem(item, index));
+
+    const normalizedBatchItems = [];
+    for (let index = 0; index < normalizedItems.length; index += 1) {
+      const item = normalizedItems[index];
+      if (isRemoteBatchItem(item)) {
+        normalizedBatchItems.push({
+          file: null,
+          referenceId: item.referenceId,
+          url: item.url,
+          durationEstimateSec: item.durationEstimateSec || durationEstimateSec || null,
+        });
+        continue;
+      }
+
+      const file = await normalizeFile(item.file, `file_${String(index + 1).padStart(6, "0")}.mp3`);
+      assertSupportedBatchFormat(file);
+      normalizedBatchItems.push({
+        file,
+        referenceId: item.referenceId,
+        url: null,
+        durationEstimateSec: item.durationEstimateSec || await estimateDurationFromFile(file),
+      });
+    }
+
+    const totalSizeBytes = normalizedBatchItems.reduce((total, item) => total + Number(item.file?.size || 0), 0);
+    assertBatchLimits(normalizedBatchItems.length, totalSizeBytes);
+    const response = await this.requestJson("/transcribe", {
+      method: "POST",
+      body: {
+        files: normalizedBatchItems.map((item) => (
+          item.url
+            ? {
+              reference_id: item.referenceId,
+              url: item.url,
+            }
+            : uploadDescriptorForFile(item.referenceId, item.file)
+        )),
+        ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
+      },
+      retryable: true,
+    });
+    emitProgress(progress, {
+      event: "upload_urls_received",
+      jobId: response.job_id,
+      jobStatus: response.job_status,
+      uploadCount: normalizeResponseUploads(response).length,
+      totalFiles: normalizedBatchItems.length,
+    });
+    return new BatchJob(this, normalizedBatchItems, response, {
+      onProgress: progress,
+      webhookUrl,
+      multipartConcurrency: normalizeMultipartConcurrency(multipartConcurrency ?? this.multipartConcurrency),
+    });
+  }
+}
+
+export default TranscribeAPI;