@speechweave/node 1.0.0

package/dist/index.js

@@ -0,0 +1,830 @@
+// src/client.ts
+import { createReadStream } from "fs";
+import { stat } from "fs/promises";
+
+// src/errors.ts
+var SpeechWeaveError = class extends Error {
+  status;
+  code;
+  body;
+  retry_after;
+  constructor(message, status = 500, code, body, retry_after) {
+    super(message);
+    this.name = "SpeechWeaveError";
+    this.status = status;
+    this.code = code;
+    this.body = body;
+    this.retry_after = retry_after;
+  }
+};
+
+// src/polling.ts
+var TERMINAL = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "cancelled"
+]);
+async function waitForJob(client, job_id, opts = {}) {
+  const timeout_ms = opts.timeout_ms ?? 36e5;
+  const poll_ms = opts.poll_ms ?? 2e3;
+  const deadline = Date.now() + timeout_ms;
+  while (Date.now() < deadline) {
+    const job = await client.getJob(job_id);
+    if (TERMINAL.has(String(job.status))) {
+      return job;
+    }
+    await new Promise((r) => setTimeout(r, poll_ms));
+  }
+  throw new SpeechWeaveError(
+    "Timed out waiting for job",
+    504,
+    "JOB_WAIT_TIMEOUT",
+    { job_id }
+  );
+}
+
+// src/version.ts
+var VERSION = "1.0.0";
+
+// src/client.ts
+function normalizeBaseURL(url) {
+  const s = String(url || "").trim().replace(/\/+$/, "");
+  return s || "https://api.speechweave.com/v1";
+}
+async function readErrorMessage(response) {
+  const content_type = response.headers.get("content-type") || "";
+  try {
+    if (content_type.includes("application/json")) {
+      const json = await response.json();
+      return String(json?.error || json?.message || response.statusText);
+    }
+    const text = await response.text();
+    return text.slice(0, 500) || response.statusText;
+  } catch {
+    return response.statusText;
+  }
+}
+async function getBodyLength(body, file_size) {
+  if (file_size != null && Number.isFinite(file_size) && file_size >= 0) {
+    return file_size;
+  }
+  if (Buffer.isBuffer(body)) {
+    return body.byteLength;
+  }
+  if (body instanceof Blob) {
+    return body.size;
+  }
+  const path_like = body.path;
+  if (typeof path_like === "string" || Buffer.isBuffer(path_like) || path_like instanceof URL) {
+    try {
+      return (await stat(path_like)).size;
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+var SpeechWeaveClient = class {
+  api_key;
+  base_url;
+  fetch_func;
+  /**
+   * @param options.api_key - Falls back to SPEECHWEAVE_API_KEY. Throws if neither is set.
+   * @param options.base_url - Defaults to https://api.speechweave.com/v1.
+   */
+  constructor(options = {}) {
+    this.api_key = options.api_key || typeof process !== "undefined" && process.env?.SPEECHWEAVE_API_KEY || "";
+    this.base_url = normalizeBaseURL(
+      options.base_url || "https://api.speechweave.com/v1"
+    );
+    this.fetch_func = options.fetch_func || fetch;
+    if (!this.api_key) {
+      throw new Error("SpeechWeave API key is required (api_key, or SPEECHWEAVE_API_KEY)");
+    }
+  }
+  /**
+   * Authenticated fetch against base_url.
+   * Adds Bearer and User-Agent when missing. Path is relative (leading `/` optional).
+   */
+  async rawFetch(path, init = {}) {
+    const formatted_path = path.startsWith("/") ? path : `/${path}`;
+    const url = `${this.base_url}${formatted_path}`;
+    const h = new Headers(init.headers);
+    if (!h.has("Authorization")) {
+      h.set("Authorization", `Bearer ${this.api_key}`);
+    }
+    if (!h.has("User-Agent")) {
+      h.set("User-Agent", `speechweave-node/${VERSION}`);
+    }
+    return this.fetch_func(url, {
+      ...init,
+      headers: h
+    });
+  }
+  async requestJson(method, path, json, params) {
+    let request_path = path;
+    if (params) {
+      const search = new URLSearchParams();
+      for (const [
+        key,
+        value
+      ] of Object.entries(params)) {
+        if (value === void 0 || value === null) {
+          continue;
+        }
+        search.set(key, String(value));
+      }
+      const qs = search.toString();
+      if (qs) {
+        request_path = `${path}${path.includes("?") ? "&" : "?"}${qs}`;
+      }
+    }
+    const headers = { Accept: "application/json" };
+    let body;
+    if (json !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(json);
+    }
+    const response = await this.rawFetch(request_path, {
+      method,
+      headers,
+      body
+    });
+    if (!response.ok) {
+      const ct = response.headers.get("content-type") || "";
+      let err_body;
+      let message;
+      let code = String(response.status);
+      let retry_after;
+      const header_retry = response.headers.get("Retry-After");
+      if (header_retry) {
+        const n = parseInt(header_retry, 10);
+        if (Number.isFinite(n)) {
+          retry_after = n;
+        }
+      }
+      try {
+        if (ct.includes("application/json")) {
+          err_body = await response.json();
+          const j = err_body;
+          message = String(j?.error || j?.message || response.statusText);
+          if (j?.code) {
+            code = j.code;
+          }
+          if (typeof j?.retry_after === "number") {
+            retry_after = j.retry_after;
+          }
+        } else {
+          const t = await response.text();
+          message = t.slice(0, 500) || response.statusText;
+        }
+      } catch {
+        message = response.statusText;
+      }
+      throw new SpeechWeaveError(
+        message,
+        response.status,
+        code,
+        err_body,
+        retry_after
+      );
+    }
+    return await response.json();
+  }
+  /**
+   * Request a short-lived PUT URL and object_key for direct upload to storage.
+   *
+   * @param params.filename - Original name (used in the storage key).
+   * @param params.content_type - MIME type that must match the subsequent PUT.
+   */
+  async presignUpload(params) {
+    return this.requestJson(
+      "POST",
+      "/uploads",
+      {
+        filename: params.filename,
+        content_type: params.content_type
+      }
+    );
+  }
+  /**
+   * PUT audio bytes to a presigned upload_url.
+   * Sets Content-Length when the body can be measured; pass file_size for pipes/live streams.
+   *
+   * @param uploadUrl - upload_url from presignUpload.
+   */
+  async putToPresignedUrl(uploadUrl, body, contentType, options = {}) {
+    const headers = new Headers({ "Content-Type": contentType });
+    const content_length = await getBodyLength(body, options.file_size);
+    if (content_length != null) {
+      headers.set("Content-Length", String(content_length));
+    }
+    const init = {
+      method: "PUT",
+      headers,
+      body
+    };
+    const is_node_stream = body && typeof body.pipe === "function";
+    if (is_node_stream) {
+      init.duplex = "half";
+    }
+    const response = await this.fetch_func(uploadUrl, init);
+    if (!response.ok) {
+      const message = await readErrorMessage(response);
+      throw new SpeechWeaveError(
+        `R2 upload failed: ${message}`,
+        response.status,
+        "UPLOAD_FAILED"
+      );
+    }
+  }
+  /**
+   * Presign → PUT → create job. Returns the create ack (no transcript); poll getJob or waitForJob.
+   * Omitting service_mode leaves the API default (deferred). Synchronous rejects files over the sync size cap (default 512 MiB).
+   *
+   * @param options.filename - Defaults to audio.bin.
+   * @param options.content_type - Defaults to application/octet-stream.
+   * @param options.language - Two-letter ISO code (e.g. 'en', 'es').
+   * @param options.file_size - Content-Length when the body cannot be measured (pipes, live streams).
+   */
+  async transcribeFile(file, options = {}) {
+    const filename = options.filename || "audio.bin";
+    const content_type = options.content_type || "application/octet-stream";
+    const presign = await this.presignUpload({
+      filename,
+      content_type
+    });
+    const put_opts = { file_size: options.file_size };
+    if (Buffer.isBuffer(file) || file instanceof Blob) {
+      await this.putToPresignedUrl(presign.upload_url, file, content_type, put_opts);
+    } else {
+      await this.putToPresignedUrl(
+        presign.upload_url,
+        file,
+        content_type,
+        put_opts
+      );
+    }
+    return this.createJob({
+      object_key: presign.object_key,
+      model: options.model,
+      service_mode: options.service_mode,
+      language: options.language,
+      metadata: options.metadata
+    });
+  }
+  /**
+   * Same as {@link transcribeFile}, then poll until completed, failed, or cancelled.
+   *
+   * @param options.wait_timeout_ms - Defaults to SPEECHWEAVE_JOB_WAIT_MS or 300_000.
+   * @param options.poll_ms - Poll interval; defaults to 1500.
+   */
+  async transcribeFileBlocking(file, options = {}) {
+    const created = await this.transcribeFile(file, options);
+    return waitForJob(
+      this,
+      created.id,
+      {
+        timeout_ms: options.wait_timeout_ms ?? Number(process.env?.SPEECHWEAVE_JOB_WAIT_MS || 3e5),
+        poll_ms: options.poll_ms ?? 1500
+      }
+    );
+  }
+  /**
+   * Create a transcription job from an already-uploaded object or a remote URL.
+   * Provide exactly one of object_key, input_url, or audio_url. type defaults to transcription.
+   * Omitting service_mode leaves the API default (deferred).
+   *
+   * @param params.object_key - From PresignResponse after a successful PUT.
+   * @param params.input_url - Publicly reachable audio URL.
+   * @param params.audio_url - Alias for input_url.
+   * @param params.language - Two-letter ISO code (e.g. 'en', 'es').
+   */
+  async createJob(params) {
+    const payload = {
+      type: params.type || "transcription"
+    };
+    if (params.object_key != null) {
+      payload.object_key = params.object_key;
+    }
+    if (params.input_url != null) {
+      payload.input_url = params.input_url;
+    }
+    if (params.audio_url != null) {
+      payload.audio_url = params.audio_url;
+    }
+    if (params.model != null) {
+      payload.model = params.model;
+    }
+    if (params.service_mode != null) {
+      payload.service_mode = params.service_mode;
+    }
+    if (params.language != null) {
+      payload.language = params.language;
+    }
+    if (params.metadata != null) {
+      payload.metadata = params.metadata;
+    }
+    return this.requestJson("POST", "/jobs", payload);
+  }
+  /**
+   * Fetch the current job record (status, transcript when completed, error when failed).
+   *
+   * @param job_id - Id from createJob / transcribeFile.
+   */
+  async getJob(job_id) {
+    return this.requestJson(
+      "GET",
+      `/jobs/${encodeURIComponent(job_id)}`
+    );
+  }
+  /**
+   * List jobs for the authenticated account.
+   *
+   * @param params.status - Filter by PublicJobStatus value.
+   * @param params.page - 1-based page; API default if omitted.
+   * @param params.limit - Page size; API default if omitted.
+   */
+  async listJobs(params = {}) {
+    return this.requestJson(
+      "GET",
+      "/jobs",
+      void 0,
+      {
+        page: params.page,
+        limit: params.limit,
+        status: params.status
+      }
+    );
+  }
+  /**
+   * Cancel a pending or processing job.
+   * Fails if the job is already completed, failed, or cancelled.
+   *
+   * @param job_id - Id from createJob / transcribeFile.
+   */
+  async cancelJob(job_id) {
+    return this.requestJson(
+      "POST",
+      `/jobs/${encodeURIComponent(job_id)}/cancel`,
+      {}
+    );
+  }
+  /**
+   * Open a disk path and run {@link transcribeFile}.
+   * filename is taken from the path basename.
+   *
+   * @param file_path - Absolute or relative path on the local filesystem.
+   */
+  async transcribeFilePath(file_path, options = {}) {
+    const stream = createReadStream(file_path);
+    const base = file_path.split(/[/\\]/).pop() || "audio.bin";
+    return this.transcribeFile(
+      stream,
+      {
+        filename: base,
+        content_type: options.content_type,
+        model: options.model,
+        service_mode: options.service_mode,
+        language: options.language,
+        metadata: options.metadata,
+        file_size: options.file_size
+      }
+    );
+  }
+};
+
+// src/compat_shapes.ts
+function jobText(job) {
+  const text = job.transcript;
+  return typeof text === "string" ? text : "";
+}
+function jobDuration(job) {
+  const duration = job.duration;
+  if (duration == null) {
+    return void 0;
+  }
+  const value = Number(duration);
+  if (!Number.isFinite(value) || value < 0) {
+    return void 0;
+  }
+  return value;
+}
+function jobLanguage(job) {
+  const language = job.language;
+  if (language == null) {
+    return void 0;
+  }
+  const text = String(language).trim().toLowerCase();
+  return text || void 0;
+}
+function shapeOpenAiResponse(job) {
+  const response = {
+    text: jobText(job),
+    task: "transcribe"
+  };
+  const duration = jobDuration(job);
+  if (duration !== void 0) {
+    response.duration = duration;
+  }
+  const language = jobLanguage(job);
+  if (language !== void 0) {
+    response.language = language;
+  }
+  return response;
+}
+function shapeDeepgramResponse(job, options = {}) {
+  const job_id = String(job.id || "");
+  const model_name = options.model || String(job.model || "core");
+  const text = jobText(job);
+  const language = jobLanguage(job);
+  const alternative = {
+    transcript: text,
+    confidence: 1,
+    words: []
+  };
+  if (language !== void 0) {
+    alternative.language = language;
+  }
+  return {
+    metadata: {
+      request_id: job_id,
+      model_info: {
+        name: model_name,
+        version: "1",
+        arch: "speechweave"
+      }
+    },
+    results: {
+      channels: [
+        {
+          alternatives: [
+            alternative
+          ]
+        }
+      ]
+    }
+  };
+}
+function shapeAssemblyResponse(job) {
+  const status = String(job.status || "unknown");
+  const pub_status = status === "completed" ? "completed" : status;
+  const duration = jobDuration(job);
+  const language = jobLanguage(job);
+  const error = job.error;
+  const response = {
+    id: String(job.id || ""),
+    status: pub_status,
+    text: jobText(job)
+  };
+  if (duration !== void 0) {
+    response.audio_duration = duration;
+  }
+  if (language !== void 0) {
+    response.language = language;
+  }
+  if (error != null && pub_status === "failed") {
+    response.error = String(error);
+  } else {
+    response.error = null;
+  }
+  return response;
+}
+async function toUploadBody(data) {
+  if (data instanceof Blob) {
+    return {
+      body: data,
+      content_type: data.type || "application/octet-stream"
+    };
+  }
+  if (Buffer.isBuffer(data) || data instanceof Uint8Array) {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data);
+    return {
+      body: buf,
+      content_type: "application/octet-stream"
+    };
+  }
+  return {
+    body: data,
+    content_type: "application/octet-stream"
+  };
+}
+async function uploadAndCreateJob(client, params) {
+  const prepared = await toUploadBody(params.data);
+  const content_type = params.content_type || prepared.content_type;
+  const body = prepared.body;
+  const presign = await client.presignUpload({
+    filename: params.filename,
+    content_type
+  });
+  await client.putToPresignedUrl(
+    presign.upload_url,
+    body,
+    content_type,
+    { file_size: params.file_size }
+  );
+  return client.createJob({
+    object_key: presign.object_key,
+    model: params.model,
+    language: params.language,
+    service_mode: params.service_mode ?? "synchronous",
+    metadata: params.metadata
+  });
+}
+async function createJobFromUrl(client, params) {
+  return client.createJob({
+    input_url: params.url,
+    model: params.model,
+    language: params.language,
+    service_mode: params.service_mode ?? "synchronous",
+    metadata: params.metadata
+  });
+}
+async function finishCompatJob(client, job, options) {
+  if (!options.wait) {
+    return job;
+  }
+  const finished = await waitForJob(
+    client,
+    String(job.id || ""),
+    {
+      timeout_ms: options.timeout_ms ?? 3e5,
+      poll_ms: options.poll_ms ?? 1500
+    }
+  );
+  if (String(finished.status) === "failed") {
+    throw new SpeechWeaveError(
+      String(finished.error || "Transcription failed"),
+      500,
+      options.error_code,
+      finished
+    );
+  }
+  return finished;
+}
+
+// src/webhooks.ts
+import crypto from "crypto";
+function timingSafeEqual(a, b) {
+  const ab = Buffer.from(a, "utf8");
+  const bb = Buffer.from(b, "utf8");
+  if (ab.length !== bb.length) {
+    return false;
+  }
+  return crypto.timingSafeEqual(ab, bb);
+}
+function verifyWebhook(secret, raw_body, signature_header, tolerance_seconds = 300) {
+  const secrets = (Array.isArray(secret) ? secret : [
+    secret
+  ]).map((s) => String(s || "").trim()).filter(Boolean);
+  if (!secrets.length) {
+    return {
+      ok: false,
+      reason: "no_secrets"
+    };
+  }
+  const header = String(signature_header || "").trim();
+  const parts = header.split(",").map((p) => p.trim());
+  let t = null;
+  const v1_list = [];
+  for (const part of parts) {
+    if (part.startsWith("t=")) {
+      t = part.slice(2);
+    }
+    if (part.startsWith("v1=")) {
+      v1_list.push(part.slice(3));
+    }
+  }
+  if (!t || !v1_list.length) {
+    return {
+      ok: false,
+      reason: "missing_t_or_v1"
+    };
+  }
+  const ts = Number(t);
+  if (!Number.isFinite(ts)) {
+    return {
+      ok: false,
+      reason: "bad_timestamp"
+    };
+  }
+  const now = Math.floor(Date.now() / 1e3);
+  if (Math.abs(now - ts) > tolerance_seconds) {
+    return {
+      ok: false,
+      reason: "timestamp_skew"
+    };
+  }
+  for (const secret2 of secrets) {
+    const expected = crypto.createHmac("sha256", secret2).update(`${t}.${raw_body}`).digest("hex");
+    for (const v1 of v1_list) {
+      if (timingSafeEqual(expected, v1)) {
+        return {
+          ok: true
+        };
+      }
+    }
+  }
+  return {
+    ok: false,
+    reason: "bad_signature"
+  };
+}
+
+// src/openai/openai_compat.ts
+function createOpenAiAudioNamespace(client) {
+  return {
+    transcriptions: {
+      /** OpenAI-shaped transcription create — drop-in compatibility wrapper. */
+      create: async (opts) => {
+        const name = opts.filename || "audio.bin";
+        const job = await uploadAndCreateJob(client, {
+          data: opts.file,
+          filename: name,
+          model: opts.model,
+          language: opts.language,
+          file_size: opts.file_size
+        });
+        const finished = await finishCompatJob(client, job, {
+          wait: opts.wait ?? true,
+          error_code: "OPENAI_PROXY"
+        });
+        if (opts.wait === false) {
+          return finished;
+        }
+        return shapeOpenAiResponse(finished);
+      }
+    }
+  };
+}
+
+// src/deepgram/deepgram_compat.ts
+function createDeepgramListenNamespace(client) {
+  return {
+    prerecorded: {
+      /** Deepgram-shaped prerecorded file transcription — drop-in compatibility wrapper. */
+      transcribeFile: async (stream, options = {}) => {
+        const job = await uploadAndCreateJob(client, {
+          data: stream,
+          filename: options.filename || "audio.bin",
+          model: options.model,
+          language: options.language,
+          file_size: options.file_size
+        });
+        const finished = await finishCompatJob(client, job, {
+          wait: options.wait ?? true,
+          error_code: "DEEPGRAM_PROXY"
+        });
+        if (options.wait === false) {
+          return finished;
+        }
+        return shapeDeepgramResponse(
+          finished,
+          { model: options.model }
+        );
+      },
+      /** Deepgram-shaped prerecorded URL transcription — drop-in compatibility wrapper. */
+      transcribeUrl: async (url, options = {}) => {
+        const job = await createJobFromUrl(client, {
+          url,
+          model: options.model,
+          language: options.language
+        });
+        const finished = await finishCompatJob(client, job, {
+          wait: options.wait ?? true,
+          error_code: "DEEPGRAM_PROXY"
+        });
+        if (options.wait === false) {
+          return finished;
+        }
+        return shapeDeepgramResponse(
+          finished,
+          { model: options.model }
+        );
+      }
+    }
+  };
+}
+
+// src/assembly/assembly_compat.ts
+function createAssemblyTranscriptsNamespace(client) {
+  return {
+    /** AssemblyAI-shaped transcription — drop-in compatibility wrapper. Pass a URL string or binary/file body. */
+    transcribe: async (audio, config, options = {}) => {
+      const cfg = config || {};
+      const wait = options.wait ?? true;
+      let job;
+      if (typeof audio === "string") {
+        job = await createJobFromUrl(client, {
+          url: audio,
+          model: cfg.model,
+          language: cfg.language
+        });
+      } else {
+        job = await uploadAndCreateJob(client, {
+          data: audio,
+          filename: "audio.bin",
+          model: cfg.model,
+          language: cfg.language,
+          file_size: cfg.file_size
+        });
+      }
+      const finished = await finishCompatJob(client, job, {
+        wait,
+        error_code: "ASSEMBLY_PROXY"
+      });
+      if (!wait) {
+        return finished;
+      }
+      return shapeAssemblyResponse(finished);
+    }
+  };
+}
+
+// src/index.ts
+function createJobsNamespace(client) {
+  return {
+    /**
+     * Create a job from a local file or a remote URL / object_key.
+     * Pass `file` (path, Buffer, Blob, or stream) to presign-upload then create.
+     * Otherwise pass one of `object_key`, `input_url`, or `audio_url` (no upload).
+     * Omitting service_mode leaves the API default (deferred).
+     */
+    create: async (params) => {
+      if (params.file != null) {
+        if (typeof params.file === "string") {
+          return client.transcribeFilePath(
+            params.file,
+            {
+              model: params.model,
+              service_mode: params.service_mode,
+              language: params.language,
+              content_type: params.content_type,
+              metadata: params.metadata,
+              file_size: params.file_size
+            }
+          );
+        }
+        return client.transcribeFile(
+          params.file,
+          {
+            filename: params.filename,
+            content_type: params.content_type,
+            model: params.model,
+            service_mode: params.service_mode,
+            language: params.language,
+            metadata: params.metadata,
+            file_size: params.file_size
+          }
+        );
+      }
+      return client.createJob({
+        object_key: params.object_key,
+        input_url: params.input_url,
+        audio_url: params.audio_url,
+        model: params.model,
+        service_mode: params.service_mode,
+        language: params.language,
+        type: params.type,
+        metadata: params.metadata
+      });
+    },
+    /** Fetch the current job record. */
+    get: client.getJob.bind(client),
+    /** List jobs for the authenticated account. */
+    list: client.listJobs.bind(client),
+    /**
+     * Cancel a pending or processing job.
+     * Fails if the job is already completed, failed, or cancelled.
+     */
+    cancel: client.cancelJob.bind(client)
+  };
+}
+var SpeechWeave = class extends SpeechWeaveClient {
+  audio;
+  listen;
+  transcripts;
+  jobs;
+  constructor(options = {}) {
+    super(options);
+    this.audio = createOpenAiAudioNamespace(this);
+    this.listen = createDeepgramListenNamespace(this);
+    this.transcripts = createAssemblyTranscriptsNamespace(this);
+    this.jobs = createJobsNamespace(this);
+  }
+};
+export {
+  SpeechWeave,
+  SpeechWeaveClient,
+  SpeechWeaveError,
+  VERSION,
+  createJobFromUrl,
+  finishCompatJob,
+  shapeAssemblyResponse,
+  shapeDeepgramResponse,
+  shapeOpenAiResponse,
+  uploadAndCreateJob,
+  verifyWebhook,
+  waitForJob
+};
+//# sourceMappingURL=index.js.map