@transcribe-api/sdk 0.1.6 → 0.1.8

package/README.md

@@ -68,6 +68,10 @@ const client = new TranscribeAPI({
   apiKey: "YOUR_API_KEY",
   baseUrl: "https://api.transcribeapi.com/v1",
   uploadConcurrency: 4,
+  autoReload: {
+    amount: 10,
+    ifBalanceBelow: 20,
+  },
   showLogs: true,
   logger: console,
   polling: {
@@ -82,6 +86,7 @@ const client = new TranscribeAPI({
 | `apiKey` | Required. Your Transcribe API key. |
 | `baseUrl` | Optional. Defaults to `https://api.transcribeapi.com/v1`. |
 | `uploadConcurrency` | Optional. Number of in-flight upload PUTs. Defaults to `1` and is capped at `32`. |
+| `autoReload` | Optional. Automatically calls `POST /v1/add-funds` after a transcription result when `remaining_balance` is below `ifBalanceBelow`. |
 | `showLogs` | Optional. Prints upload progress, upload completion, polling status, and final result info. |
 | `logger` | Optional. Logger object with a `log` method. Defaults to `console`. |
 | `polling` | Optional. `{ interval, timeout }` in seconds. `interval` must be at least `10`. Omit or set to `null`/`false` to disable automatic polling. |
@@ -185,7 +190,53 @@ You can also pass a comma-separated string:
 exclude: "metadata,billing"
 ```
 
-If `exclude` leaves only one transcript field and removes metadata, billing, and detected language, the API returns that remaining value directly instead of a JSON object. For example, text-only responses return a plain string, VTT-only responses return a plain string, and segments-only responses return an array.
+For single-file outputs, if `exclude` leaves only one transcript field and removes metadata, billing, and detected language, the API returns that remaining value directly instead of a JSON object. Text-only responses return a plain string, VTT-only responses return a plain string, and segments-only responses return an array. Multi-file outputs still return JSON so each result stays associated with its `reference_id`.
+
+If `autoReload` is enabled, the SDK always keeps billing in the request even if you included `billing` in `exclude`. It needs `remaining_balance` to decide whether to call `POST /v1/add-funds`.
+
+## Auto reload
+
+```js
+const client = new TranscribeAPI({
+  apiKey: process.env.TRANSCRIBE_API_KEY,
+  autoReload: {
+    amount: 10,
+    ifBalanceBelow: 20,
+  },
+});
+```
+
+When `autoReload` is enabled, the SDK:
+
+- checks `remaining_balance` after a transcription result
+- only calls `POST /v1/add-funds` when the balance is below `ifBalanceBelow`
+- sends `{ amount, if_balance_below }` to the API for backend-side protection too
+- ignores `billing` inside `exclude` so the SDK can always read `remaining_balance`
+
+Auto reload only runs when the transcription result returned to the SDK includes `remaining_balance`. If you disable polling for async jobs, immediate non-terminal async responses do not have enough billing data for the SDK to auto reload yet.
+
+### Manual addFunds for webhooks
+
+When using webhooks with batch jobs, the transcription result goes to your webhook URL instead of the SDK. The `autoReload` config won't fire because the SDK never sees the result. Call `client.addFunds()` inside your webhook handler instead:
+
+```js
+// Webhook handler (Express example)
+app.post("/webhook", async (req, res) => {
+  const { remaining_balance } = req.body;
+
+  if (remaining_balance < 20) {
+    const client = new TranscribeAPI({ apiKey: process.env.TRANSCRIBE_API_KEY });
+    await client.addFunds(10, { ifBalanceBelow: 20 });
+  }
+
+  res.sendStatus(200);
+});
+```
+
+`addFunds(amount, { ifBalanceBelow })` calls `POST /v1/add-funds`:
+
+- `amount` — whole dollar amount from 5 to 100.
+- `ifBalanceBelow` — server-side guard. The API only charges if your current balance is actually below this threshold, making it safe against duplicate webhook deliveries.
 
 ## Webhooks
 

package/index.js

@@ -143,6 +143,54 @@ function normalizePollingConfig(polling) {
   };
 }
 
+function normalizeAutoReloadConfig(autoReload) {
+  if (autoReload === undefined || autoReload === null || autoReload === false) {
+    return null;
+  }
+  if (typeof autoReload !== "object" || Array.isArray(autoReload)) {
+    throw new TranscribeAPIError("`autoReload` must be an object with `amount` and `ifBalanceBelow`.", {
+      code: "invalid_auto_reload_config",
+    });
+  }
+
+  const amount = Number.parseInt(String(autoReload.amount ?? ""), 10);
+  if (!Number.isInteger(amount) || amount < 5 || amount > 100) {
+    throw new TranscribeAPIError("`autoReload.amount` must be a whole dollar value from 5 to 100.", {
+      code: "invalid_auto_reload_amount",
+    });
+  }
+
+  const rawIfBalanceBelow = autoReload.ifBalanceBelow ?? autoReload.if_balance_below;
+  const ifBalanceBelow = Number(rawIfBalanceBelow);
+  if (!Number.isFinite(ifBalanceBelow) || ifBalanceBelow < 0) {
+    throw new TranscribeAPIError("`autoReload.ifBalanceBelow` must be a number >= 0.", {
+      code: "invalid_auto_reload_if_balance_below",
+    });
+  }
+
+  return {
+    amount,
+    ifBalanceBelow,
+  };
+}
+
+function normalizeExcludeList(exclude) {
+  if (exclude === undefined || exclude === null || exclude === "") {
+    return [];
+  }
+  if (Array.isArray(exclude)) {
+    return exclude.map((item) => String(item || "").trim()).filter(Boolean);
+  }
+  return String(exclude)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function stringifyExclude(excludeList) {
+  return excludeList.length ? excludeList.join(",") : null;
+}
+
 function contentTypeFromName(name = "") {
   const lower = String(name).toLowerCase();
   if (lower.endsWith(".mp3")) return "audio/mpeg";
@@ -1229,6 +1277,7 @@ export class TranscribeAPI {
     showLogs = false,
     logger = console,
     polling = null,
+    autoReload = null,
   } = {}) {
     if (!apiKey) {
       throw new Error("Missing API key");
@@ -1240,6 +1289,7 @@ export class TranscribeAPI {
     this.showLogs = Boolean(showLogs);
     this.logger = logger || console;
     this.polling = normalizePollingConfig(polling);
+    this.autoReload = normalizeAutoReloadConfig(autoReload);
     this.jobs = {
       createBigFile: (options) => this.createBigFileJob(options),
       createBatch: (options) => this.createBatchJob(options),
@@ -1265,6 +1315,54 @@ export class TranscribeAPI {
     return retryable ? retry(run) : run();
   }
 
+  getEffectiveExclude(exclude) {
+    const excludeList = normalizeExcludeList(exclude);
+    if (!this.autoReload) {
+      return excludeList;
+    }
+    return excludeList.filter((field) => field !== "billing");
+  }
+
+  async addFunds(amount, { ifBalanceBelow } = {}) {
+    const body = { amount };
+    if (ifBalanceBelow !== undefined && ifBalanceBelow !== null) {
+      body.if_balance_below = ifBalanceBelow;
+    }
+    return this.requestJson("/add-funds", {
+      method: "POST",
+      body,
+      retryable: true,
+    });
+  }
+
+  async maybeAutoReload(result, { showLogs = this.showLogs, logger = this.logger } = {}) {
+    if (!this.autoReload || !result || typeof result !== "object" || Array.isArray(result)) {
+      return result;
+    }
+
+    const remainingBalance = Number(result.remaining_balance);
+    if (!Number.isFinite(remainingBalance) || remainingBalance >= this.autoReload.ifBalanceBelow) {
+      return result;
+    }
+
+    try {
+      const autoReloadResult = await this.addFunds(this.autoReload.amount, {
+        ifBalanceBelow: this.autoReload.ifBalanceBelow,
+      });
+      if (showLogs && typeof logger?.log === "function") {
+        logger.log(JSON.stringify(autoReloadResult, null, 2));
+      }
+    } catch (error) {
+      if (showLogs && typeof logger?.log === "function") {
+        logger.log(JSON.stringify({
+          auto_reload_error: extractErrorInfo(error),
+        }, null, 2));
+      }
+    }
+
+    return result;
+  }
+
   async waitForJobCompletion(jobId, {
     polling = this.polling,
     showLogs = this.showLogs,
@@ -1325,6 +1423,7 @@ export class TranscribeAPI {
     exclude,
     uploadConcurrency,
   } = {}) {
+    const effectiveExclude = this.getEffectiveExclude(exclude);
     const progress = composeProgressHandler({
       onProgress,
       showLogs: showLogs ?? this.showLogs,
@@ -1353,7 +1452,7 @@ export class TranscribeAPI {
           logger: logger ?? this.logger,
           uploadConcurrency,
           language,
-          exclude,
+          exclude: effectiveExclude,
         });
       }
 
@@ -1364,8 +1463,6 @@ export class TranscribeAPI {
         : (normalizedItem.durationEstimateSec || await estimateDurationFromFile(normalizedSingleFile));
       const effectiveLanguage = normalizedItem.hasLanguage ? normalizedItem.language : normalizeLanguageCode(language);
       const isAsync = files.length > 1
-        || Boolean(normalizedItem.url)
-        || Boolean(webhookUrl)
         || (
           normalizedSingleFile
           && (
@@ -1383,7 +1480,19 @@ export class TranscribeAPI {
           logger: logger ?? this.logger,
           uploadConcurrency,
           language,
-          exclude,
+          exclude: effectiveExclude,
+        });
+      }
+
+      if (normalizedItem.url) {
+        return this.transcribeUrlDirect({
+          url: normalizedItem.url,
+          referenceId: normalizedItem.referenceId,
+          language: effectiveLanguage,
+          exclude: effectiveExclude,
+          webhookUrl,
+          showLogs: showLogs ?? this.showLogs,
+          logger: logger ?? this.logger,
         });
       }
 
@@ -1391,7 +1500,7 @@ export class TranscribeAPI {
         file: normalizedSingleFile,
         referenceId: normalizedItem.referenceId,
         language: effectiveLanguage,
-        exclude,
+        exclude: effectiveExclude,
         webhookUrl,
         showLogs: showLogs ?? this.showLogs,
         logger: logger ?? this.logger,
@@ -1440,7 +1549,10 @@ export class TranscribeAPI {
     if ((showLogs ?? this.showLogs) && TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
       logTerminalAsyncResult(result, logger ?? this.logger);
     }
-    return result;
+    return this.maybeAutoReload(result, {
+      showLogs: showLogs ?? this.showLogs,
+      logger: logger ?? this.logger,
+    });
   }
 
   async transcribeDirect({
@@ -1460,7 +1572,8 @@ export class TranscribeAPI {
     if (String(referenceId || "").trim()) form.set("reference_id", String(referenceId).trim());
     form.set("file", directFile, directFile.name);
     if (language) form.set("language", language);
-    if (exclude) form.set("exclude", Array.isArray(exclude) ? exclude.join(",") : exclude);
+    const excludeValue = stringifyExclude(this.getEffectiveExclude(exclude));
+    if (excludeValue) form.set("exclude", excludeValue);
     if (webhookUrl) form.set("webhook_url", webhookUrl);
 
     const response = await fetch(`${this.baseUrl}/transcribe`, {
@@ -1479,10 +1592,51 @@ export class TranscribeAPI {
         initialJob: result,
       });
     }
+    const finalResult = await this.maybeAutoReload(result, { showLogs, logger });
     if (showLogs && typeof logger?.log === "function") {
-      logger.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+      logger.log(typeof finalResult === "string" ? finalResult : JSON.stringify(finalResult, null, 2));
     }
-    return result;
+    return finalResult;
+  }
+
+  async transcribeUrlDirect({
+    url,
+    referenceId,
+    language,
+    exclude,
+    webhookUrl,
+    showLogs = false,
+    logger = console,
+  } = {}) {
+    const form = new FormData();
+    form.set("url", String(url || "").trim());
+    if (String(referenceId || "").trim()) form.set("reference_id", String(referenceId).trim());
+    if (language) form.set("language", language);
+    const excludeValue = stringifyExclude(this.getEffectiveExclude(exclude));
+    if (excludeValue) form.set("exclude", excludeValue);
+    if (webhookUrl) form.set("webhook_url", webhookUrl);
+
+    const response = await fetch(`${this.baseUrl}/transcribe`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: form,
+    });
+    const result = await parseApiResponse(response);
+    if (this.polling && result && typeof result === "object" && result.job_status && !TERMINAL_JOB_STATUSES.has(String(result.job_status))) {
+      return this.waitForJobCompletion(result.job_id, {
+        polling: this.polling,
+        showLogs,
+        logger,
+        initialJob: result,
+      });
+    }
+    const finalResult = await this.maybeAutoReload(result, { showLogs, logger });
+    if (showLogs && typeof logger?.log === "function") {
+      logger.log(typeof finalResult === "string" ? finalResult : JSON.stringify(finalResult, null, 2));
+    }
+    return finalResult;
   }
 
   async transcribeMany({
@@ -1602,7 +1756,7 @@ export class TranscribeAPI {
         )),
         ...(normalizedLanguage ? { language: normalizedLanguage } : {}),
         ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
-        ...(exclude ? { exclude: Array.isArray(exclude) ? exclude.join(",") : exclude } : {}),
+        ...(stringifyExclude(this.getEffectiveExclude(exclude)) ? { exclude: stringifyExclude(this.getEffectiveExclude(exclude)) } : {}),
       },
       retryable: true,
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transcribe-api/sdk",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Official JavaScript SDK for Transcribe API.",
   "type": "module",
   "main": "index.js",

package/worker.js

@@ -143,6 +143,54 @@ function normalizePollingConfig(polling) {
   };
 }
 
+function normalizeAutoReloadConfig(autoReload) {
+  if (autoReload === undefined || autoReload === null || autoReload === false) {
+    return null;
+  }
+  if (typeof autoReload !== "object" || Array.isArray(autoReload)) {
+    throw new TranscribeAPIError("`autoReload` must be an object with `amount` and `ifBalanceBelow`.", {
+      code: "invalid_auto_reload_config",
+    });
+  }
+
+  const amount = Number.parseInt(String(autoReload.amount ?? ""), 10);
+  if (!Number.isInteger(amount) || amount < 5 || amount > 100) {
+    throw new TranscribeAPIError("`autoReload.amount` must be a whole dollar value from 5 to 100.", {
+      code: "invalid_auto_reload_amount",
+    });
+  }
+
+  const rawIfBalanceBelow = autoReload.ifBalanceBelow ?? autoReload.if_balance_below;
+  const ifBalanceBelow = Number(rawIfBalanceBelow);
+  if (!Number.isFinite(ifBalanceBelow) || ifBalanceBelow < 0) {
+    throw new TranscribeAPIError("`autoReload.ifBalanceBelow` must be a number >= 0.", {
+      code: "invalid_auto_reload_if_balance_below",
+    });
+  }
+
+  return {
+    amount,
+    ifBalanceBelow,
+  };
+}
+
+function normalizeExcludeList(exclude) {
+  if (exclude === undefined || exclude === null || exclude === "") {
+    return [];
+  }
+  if (Array.isArray(exclude)) {
+    return exclude.map((item) => String(item || "").trim()).filter(Boolean);
+  }
+  return String(exclude)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function stringifyExclude(excludeList) {
+  return excludeList.length ? excludeList.join(",") : null;
+}
+
 function contentTypeFromName(name = "") {
   const lower = String(name).toLowerCase();
   if (lower.endsWith(".mp3")) return "audio/mpeg";
@@ -1229,6 +1277,7 @@ export class TranscribeAPI {
     showLogs = false,
     logger = console,
     polling = null,
+    autoReload = null,
   } = {}) {
     if (!apiKey) {
       throw new Error("Missing API key");
@@ -1240,6 +1289,7 @@ export class TranscribeAPI {
     this.showLogs = Boolean(showLogs);
     this.logger = logger || console;
     this.polling = normalizePollingConfig(polling);
+    this.autoReload = normalizeAutoReloadConfig(autoReload);
     this.jobs = {
       createBigFile: (options) => this.createBigFileJob(options),
       createBatch: (options) => this.createBatchJob(options),
@@ -1265,6 +1315,54 @@ export class TranscribeAPI {
     return retryable ? retry(run) : run();
   }
 
+  getEffectiveExclude(exclude) {
+    const excludeList = normalizeExcludeList(exclude);
+    if (!this.autoReload) {
+      return excludeList;
+    }
+    return excludeList.filter((field) => field !== "billing");
+  }
+
+  async addFunds(amount, { ifBalanceBelow } = {}) {
+    const body = { amount };
+    if (ifBalanceBelow !== undefined && ifBalanceBelow !== null) {
+      body.if_balance_below = ifBalanceBelow;
+    }
+    return this.requestJson("/add-funds", {
+      method: "POST",
+      body,
+      retryable: true,
+    });
+  }
+
+  async maybeAutoReload(result, { showLogs = this.showLogs, logger = this.logger } = {}) {
+    if (!this.autoReload || !result || typeof result !== "object" || Array.isArray(result)) {
+      return result;
+    }
+
+    const remainingBalance = Number(result.remaining_balance);
+    if (!Number.isFinite(remainingBalance) || remainingBalance >= this.autoReload.ifBalanceBelow) {
+      return result;
+    }
+
+    try {
+      const autoReloadResult = await this.addFunds(this.autoReload.amount, {
+        ifBalanceBelow: this.autoReload.ifBalanceBelow,
+      });
+      if (showLogs && typeof logger?.log === "function") {
+        logger.log(JSON.stringify(autoReloadResult, null, 2));
+      }
+    } catch (error) {
+      if (showLogs && typeof logger?.log === "function") {
+        logger.log(JSON.stringify({
+          auto_reload_error: extractErrorInfo(error),
+        }, null, 2));
+      }
+    }
+
+    return result;
+  }
+
   async waitForJobCompletion(jobId, {
     polling = this.polling,
     showLogs = this.showLogs,
@@ -1325,6 +1423,7 @@ export class TranscribeAPI {
     exclude,
     uploadConcurrency,
   } = {}) {
+    const effectiveExclude = this.getEffectiveExclude(exclude);
     const progress = composeProgressHandler({
       onProgress,
       showLogs: showLogs ?? this.showLogs,
@@ -1353,7 +1452,7 @@ export class TranscribeAPI {
           logger: logger ?? this.logger,
           uploadConcurrency,
           language,
-          exclude,
+          exclude: effectiveExclude,
         });
       }
 
@@ -1364,8 +1463,6 @@ export class TranscribeAPI {
         : (normalizedItem.durationEstimateSec || await estimateDurationFromFile(normalizedSingleFile));
       const effectiveLanguage = normalizedItem.hasLanguage ? normalizedItem.language : normalizeLanguageCode(language);
       const isAsync = files.length > 1
-        || Boolean(normalizedItem.url)
-        || Boolean(webhookUrl)
         || (
           normalizedSingleFile
           && (
@@ -1383,7 +1480,19 @@ export class TranscribeAPI {
           logger: logger ?? this.logger,
           uploadConcurrency,
           language,
-          exclude,
+          exclude: effectiveExclude,
+        });
+      }
+
+      if (normalizedItem.url) {
+        return this.transcribeUrlDirect({
+          url: normalizedItem.url,
+          referenceId: normalizedItem.referenceId,
+          language: effectiveLanguage,
+          exclude: effectiveExclude,
+          webhookUrl,
+          showLogs: showLogs ?? this.showLogs,
+          logger: logger ?? this.logger,
         });
       }
 
@@ -1391,7 +1500,7 @@ export class TranscribeAPI {
         file: normalizedSingleFile,
         referenceId: normalizedItem.referenceId,
         language: effectiveLanguage,
-        exclude,
+        exclude: effectiveExclude,
         webhookUrl,
         showLogs: showLogs ?? this.showLogs,
         logger: logger ?? this.logger,
@@ -1440,7 +1549,10 @@ export class TranscribeAPI {
     if ((showLogs ?? this.showLogs) && TERMINAL_JOB_STATUSES.has(String(result?.job_status || ""))) {
       logTerminalAsyncResult(result, logger ?? this.logger);
     }
-    return result;
+    return this.maybeAutoReload(result, {
+      showLogs: showLogs ?? this.showLogs,
+      logger: logger ?? this.logger,
+    });
   }
 
   async transcribeDirect({
@@ -1460,7 +1572,8 @@ export class TranscribeAPI {
     if (String(referenceId || "").trim()) form.set("reference_id", String(referenceId).trim());
     form.set("file", directFile, directFile.name);
     if (language) form.set("language", language);
-    if (exclude) form.set("exclude", Array.isArray(exclude) ? exclude.join(",") : exclude);
+    const excludeValue = stringifyExclude(this.getEffectiveExclude(exclude));
+    if (excludeValue) form.set("exclude", excludeValue);
     if (webhookUrl) form.set("webhook_url", webhookUrl);
 
     const response = await fetch(`${this.baseUrl}/transcribe`, {
@@ -1479,10 +1592,51 @@ export class TranscribeAPI {
         initialJob: result,
       });
     }
+    const finalResult = await this.maybeAutoReload(result, { showLogs, logger });
     if (showLogs && typeof logger?.log === "function") {
-      logger.log(typeof result === "string" ? result : JSON.stringify(result, null, 2));
+      logger.log(typeof finalResult === "string" ? finalResult : JSON.stringify(finalResult, null, 2));
     }
-    return result;
+    return finalResult;
+  }
+
+  async transcribeUrlDirect({
+    url,
+    referenceId,
+    language,
+    exclude,
+    webhookUrl,
+    showLogs = false,
+    logger = console,
+  } = {}) {
+    const form = new FormData();
+    form.set("url", String(url || "").trim());
+    if (String(referenceId || "").trim()) form.set("reference_id", String(referenceId).trim());
+    if (language) form.set("language", language);
+    const excludeValue = stringifyExclude(this.getEffectiveExclude(exclude));
+    if (excludeValue) form.set("exclude", excludeValue);
+    if (webhookUrl) form.set("webhook_url", webhookUrl);
+
+    const response = await fetch(`${this.baseUrl}/transcribe`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: form,
+    });
+    const result = await parseApiResponse(response);
+    if (this.polling && result && typeof result === "object" && result.job_status && !TERMINAL_JOB_STATUSES.has(String(result.job_status))) {
+      return this.waitForJobCompletion(result.job_id, {
+        polling: this.polling,
+        showLogs,
+        logger,
+        initialJob: result,
+      });
+    }
+    const finalResult = await this.maybeAutoReload(result, { showLogs, logger });
+    if (showLogs && typeof logger?.log === "function") {
+      logger.log(typeof finalResult === "string" ? finalResult : JSON.stringify(finalResult, null, 2));
+    }
+    return finalResult;
   }
 
   async transcribeMany({
@@ -1602,7 +1756,7 @@ export class TranscribeAPI {
         )),
         ...(normalizedLanguage ? { language: normalizedLanguage } : {}),
         ...(webhookUrl ? { webhook_url: webhookUrl } : {}),
-        ...(exclude ? { exclude: Array.isArray(exclude) ? exclude.join(",") : exclude } : {}),
+        ...(stringifyExclude(this.getEffectiveExclude(exclude)) ? { exclude: stringifyExclude(this.getEffectiveExclude(exclude)) } : {}),
       },
       retryable: true,
     });