@audicle/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,492 @@
+// src/client.ts
+import createClient from "openapi-fetch";
+
+// src/resources/health.ts
+function createHealthResource(api) {
+  return async () => {
+    const result = await api.GET("/v1/health");
+    return result.data ?? result.error;
+  };
+}
+
+// src/errors.ts
+var AudicleError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AudicleError";
+  }
+};
+var AudicleApiError = class extends AudicleError {
+  status;
+  code;
+  requestId;
+  details;
+  constructor(status, code, message, requestId, details) {
+    super(message);
+    this.name = "AudicleApiError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+    this.details = details;
+  }
+};
+var AudicleAuthError = class extends AudicleApiError {
+  constructor(code, message, requestId, details) {
+    super(401, code, message, requestId, details);
+    this.name = "AudicleAuthError";
+  }
+};
+var AudicleNotFoundError = class extends AudicleApiError {
+  constructor(code, message, requestId, details) {
+    super(404, code, message, requestId, details);
+    this.name = "AudicleNotFoundError";
+  }
+};
+var AudicleRateLimitError = class extends AudicleApiError {
+  constructor(code, message, requestId, details) {
+    super(429, code, message, requestId, details);
+    this.name = "AudicleRateLimitError";
+  }
+};
+var AudicleTimeoutError = class extends AudicleError {
+  constructor(message) {
+    super(message);
+    this.name = "AudicleTimeoutError";
+  }
+};
+function throwApiError(status, body) {
+  const { code, message, request_id, details } = body.error;
+  switch (status) {
+    case 401:
+      throw new AudicleAuthError(code, message, request_id, details);
+    case 404:
+      throw new AudicleNotFoundError(code, message, request_id, details);
+    case 429:
+      throw new AudicleRateLimitError(code, message, request_id, details);
+    default:
+      throw new AudicleApiError(status, code, message, request_id, details);
+  }
+}
+function unwrapResponse(result) {
+  if (result.data !== void 0) return result.data;
+  if (result.error && isErrorResponseBody(result.error)) {
+    throwApiError(result.response.status, result.error);
+  }
+  throw new AudicleApiError(
+    result.response.status,
+    "unknown_error",
+    `Unexpected ${result.response.status} response`,
+    ""
+  );
+}
+function isErrorResponseBody(value) {
+  return typeof value === "object" && value !== null && "error" in value && typeof value.error?.code === "string";
+}
+
+// src/resources/transcripts.ts
+var TranscriptsResource = class {
+  #api;
+  #baseUrl;
+  #apiKey;
+  constructor(api, baseUrl, apiKey) {
+    this.#api = api;
+    this.#baseUrl = baseUrl;
+    this.#apiKey = apiKey;
+  }
+  async get(id) {
+    const result = await this.#api.GET("/v1/transcripts/{id}", {
+      params: { path: { id } }
+    });
+    return unwrapResponse(result);
+  }
+  async getText(id) {
+    return this.getFormatted(id, "text");
+  }
+  async getSrt(id) {
+    return this.getFormatted(id, "srt");
+  }
+  async getVtt(id) {
+    return this.getFormatted(id, "vtt");
+  }
+  async list(params = {}) {
+    const result = await this.#api.GET("/v1/transcripts", {
+      params: {
+        query: {
+          cursor: params.cursor,
+          limit: params.limit,
+          status: params.status,
+          created_after: params.createdAfter,
+          created_before: params.createdBefore
+        }
+      }
+    });
+    return unwrapResponse(result);
+  }
+  async *listAll(params = {}) {
+    let cursor;
+    do {
+      const page = await this.list({ ...params, cursor });
+      for (const item of page.data) {
+        yield item;
+      }
+      cursor = page.has_more && page.next_cursor ? page.next_cursor : void 0;
+    } while (cursor);
+  }
+  async delete(id) {
+    const result = await this.#api.DELETE("/v1/transcripts/{id}", {
+      params: { path: { id } }
+    });
+    if (result.error) throwApiError(result.response.status, result.error);
+  }
+  async wait(id, options = {}) {
+    const interval = Math.max(options.interval ?? 3e3, 500);
+    const timeout = options.timeout ?? 3e5;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const txn = await this.get(id);
+      if (txn.status === "completed" || txn.status === "error") return txn;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0) break;
+      await sleep(Math.min(interval, remaining));
+    }
+    throw new AudicleTimeoutError(
+      `Transcription ${id} did not complete within ${timeout}ms`
+    );
+  }
+  async getFormatted(id, format) {
+    const url = `${this.#baseUrl}/v1/transcripts/${encodeURIComponent(id)}?format=${format}`;
+    const resp = await fetch(url, {
+      headers: { Authorization: `Bearer ${this.#apiKey}` }
+    });
+    if (!resp.ok) {
+      const body = await resp.json();
+      throwApiError(resp.status, body);
+    }
+    return resp.text();
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/resources/usage.ts
+var UsageResource = class {
+  #api;
+  constructor(api) {
+    this.#api = api;
+  }
+  async get(params) {
+    const result = await this.#api.GET("/v1/usage", {
+      params: {
+        query: {
+          start_date: params.startDate,
+          end_date: params.endDate,
+          granularity: params.granularity
+        }
+      }
+    });
+    return unwrapResponse(result);
+  }
+};
+
+// src/resources/transcribe.ts
+var TranscribeResource = class {
+  #baseUrl;
+  #apiKey;
+  constructor(baseUrl, apiKey) {
+    this.#baseUrl = baseUrl;
+    this.#apiKey = apiKey;
+  }
+  async transcribe(input, options = {}) {
+    const url = `${this.#baseUrl}/v1/transcribe`;
+    const headers = {
+      Authorization: `Bearer ${this.#apiKey}`
+    };
+    if (options.idempotencyKey) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+    const preferParts = [];
+    if (options.async) preferParts.push("respond-async");
+    if (options.wait !== void 0) preferParts.push(`wait=${options.wait}`);
+    if (preferParts.length > 0) headers["Prefer"] = preferParts.join(", ");
+    let body;
+    if (input.audioUrl) {
+      const form = new FormData();
+      form.append("audio_url", input.audioUrl);
+      appendFormOptions(form, options);
+      body = form;
+    } else if (input.file) {
+      const blob = toBlob(input.file);
+      const form = new FormData();
+      form.append("file", blob);
+      appendFormOptions(form, options);
+      body = form;
+    } else {
+      throw new Error("Either file or audioUrl must be provided");
+    }
+    const resp = await fetch(url, { method: "POST", headers, body });
+    if (!resp.ok) {
+      const errBody = await resp.json();
+      throwApiError(resp.status, errBody);
+    }
+    return await resp.json();
+  }
+};
+function toBlob(input) {
+  if (input instanceof Blob) return input;
+  if (input instanceof ArrayBuffer) return new Blob([input]);
+  return new Blob([new Uint8Array(input).buffer]);
+}
+function appendFormOptions(form, options) {
+  if (options.model) form.append("model", options.model);
+  if (options.language) form.append("language", options.language);
+  if (options.speakerLabels !== void 0)
+    form.append("speaker_labels", String(options.speakerLabels));
+  if (options.wordTimestamps !== void 0)
+    form.append("word_timestamps", String(options.wordTimestamps));
+  if (options.webhookUrl) form.append("webhook_url", options.webhookUrl);
+  if (options.metadata) form.append("metadata", JSON.stringify(options.metadata));
+}
+
+// src/streaming/emitter.ts
+var TypedEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  on(event, fn) {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(fn);
+    return this;
+  }
+  off(event, fn) {
+    this.listeners.get(event)?.delete(fn);
+    return this;
+  }
+  once(event, fn) {
+    const wrapped = ((data) => {
+      this.off(event, wrapped);
+      fn(data);
+    });
+    return this.on(event, wrapped);
+  }
+  emit(event, data) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const fn of set) {
+      fn(data);
+    }
+  }
+  removeAllListeners() {
+    this.listeners.clear();
+  }
+};
+
+// src/streaming/stream.ts
+var TranscriptionStream = class extends TypedEmitter {
+  #ws = null;
+  #closed = false;
+  #baseUrl;
+  #apiKey;
+  #options;
+  constructor(baseUrl, apiKey, options = {}) {
+    super();
+    this.#baseUrl = baseUrl;
+    this.#apiKey = apiKey;
+    this.#options = options;
+    this.#connect();
+  }
+  sendAudio(data) {
+    if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) {
+      throw new Error("WebSocket is not open");
+    }
+    this.#ws.send(data);
+  }
+  finalize() {
+    this.#send({ type: "finalize" });
+  }
+  stop() {
+    this.#send({ type: "stop" });
+  }
+  configure(config) {
+    const { type: _, ...rest } = config;
+    this.#send({ ...rest, type: "configure" });
+  }
+  close() {
+    this.#closed = true;
+    this.#ws?.close();
+  }
+  get readyState() {
+    return this.#ws?.readyState ?? WebSocket.CLOSED;
+  }
+  #connect() {
+    const wsUrl = this.#buildUrl();
+    this.#ws = new WebSocket(wsUrl);
+    this.#ws.binaryType = "arraybuffer";
+    this.#ws.addEventListener("open", () => {
+      this.emit("open", void 0);
+    });
+    this.#ws.addEventListener("message", (event) => {
+      if (typeof event.data !== "string") return;
+      try {
+        const msg = JSON.parse(event.data);
+        switch (msg.type) {
+          case "session.begin":
+            this.emit("session.begin", msg);
+            break;
+          case "transcript":
+            this.emit("transcript", msg);
+            break;
+          case "vad":
+            this.emit("vad", msg);
+            break;
+          case "error":
+            this.emit("error", msg);
+            break;
+          case "session.end":
+            this.emit("session.end", msg);
+            break;
+        }
+      } catch {
+        this.emit("error", { type: "error", code: "parse_error", message: "Invalid JSON from server" });
+      }
+    });
+    this.#ws.addEventListener("close", (event) => {
+      this.emit("close", { code: event.code, reason: event.reason });
+    });
+  }
+  /** @internal WebSocket auth requires token in query string (standard WebSocket limitation) */
+  #buildUrl() {
+    const base = this.#baseUrl.replace(/^https?/, (m) => m === "https" ? "wss" : "ws");
+    const params = new URLSearchParams();
+    params.set("token", this.#apiKey);
+    if (this.#options.model) params.set("model", this.#options.model);
+    if (this.#options.language) params.set("language", this.#options.language);
+    if (this.#options.sample_rate !== void 0)
+      params.set("sample_rate", String(this.#options.sample_rate));
+    if (this.#options.encoding) params.set("encoding", this.#options.encoding);
+    if (this.#options.interim_results !== void 0)
+      params.set("interim_results", String(this.#options.interim_results));
+    return `${base}/v1/transcribe?${params.toString()}`;
+  }
+  #send(msg) {
+    if (!this.#ws || this.#ws.readyState !== WebSocket.OPEN) {
+      throw new Error("WebSocket is not open");
+    }
+    this.#ws.send(JSON.stringify(msg));
+  }
+};
+
+// src/streaming/observer.ts
+var ObserverStream = class extends TypedEmitter {
+  #ws = null;
+  #baseUrl;
+  #apiKey;
+  #sessionId;
+  constructor(baseUrl, apiKey, sessionId) {
+    super();
+    this.#baseUrl = baseUrl;
+    this.#apiKey = apiKey;
+    this.#sessionId = sessionId;
+    this.#connect();
+  }
+  close() {
+    this.#ws?.close();
+  }
+  get readyState() {
+    return this.#ws?.readyState ?? WebSocket.CLOSED;
+  }
+  #connect() {
+    const base = this.#baseUrl.replace(/^https?/, (m) => m === "https" ? "wss" : "ws");
+    const params = new URLSearchParams({ token: this.#apiKey });
+    const url = `${base}/v1/transcribe/${encodeURIComponent(this.#sessionId)}/observe?${params.toString()}`;
+    this.#ws = new WebSocket(url);
+    this.#ws.addEventListener("open", () => {
+      this.emit("open", void 0);
+    });
+    this.#ws.addEventListener("message", (event) => {
+      if (typeof event.data !== "string") return;
+      try {
+        const msg = JSON.parse(event.data);
+        switch (msg.type) {
+          case "session.begin":
+            this.emit("session.begin", msg);
+            break;
+          case "transcript":
+            this.emit("transcript", msg);
+            break;
+          case "vad":
+            this.emit("vad", msg);
+            break;
+          case "error":
+            this.emit("error", msg);
+            break;
+          case "session.end":
+            this.emit("session.end", msg);
+            break;
+        }
+      } catch {
+        this.emit("error", { type: "error", code: "parse_error", message: "Invalid JSON from server" });
+      }
+    });
+    this.#ws.addEventListener("close", (event) => {
+      this.emit("close", { code: event.code, reason: event.reason });
+    });
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.audicle.ai";
+var Audicle = class {
+  transcripts;
+  usage;
+  streaming;
+  #transcribeResource;
+  #healthFn;
+  constructor(options) {
+    const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const apiKey = options.apiKey;
+    const api = createClient({
+      baseUrl,
+      headers: { Authorization: `Bearer ${apiKey}` }
+    });
+    this.#healthFn = createHealthResource(api);
+    this.transcripts = new TranscriptsResource(api, baseUrl, apiKey);
+    this.usage = new UsageResource(api);
+    this.#transcribeResource = new TranscribeResource(baseUrl, apiKey);
+    this.streaming = new StreamingNamespace(baseUrl, apiKey);
+  }
+  health() {
+    return this.#healthFn();
+  }
+  transcribe(input, options) {
+    return this.#transcribeResource.transcribe(input, options);
+  }
+};
+var StreamingNamespace = class {
+  #baseUrl;
+  #apiKey;
+  constructor(baseUrl, apiKey) {
+    this.#baseUrl = baseUrl;
+    this.#apiKey = apiKey;
+  }
+  transcribe(options) {
+    return new TranscriptionStream(this.#baseUrl, this.#apiKey, options);
+  }
+  observe(sessionId) {
+    return new ObserverStream(this.#baseUrl, this.#apiKey, sessionId);
+  }
+};
+export {
+  Audicle,
+  AudicleApiError,
+  AudicleAuthError,
+  AudicleError,
+  AudicleNotFoundError,
+  AudicleRateLimitError,
+  AudicleTimeoutError,
+  ObserverStream,
+  TranscriptionStream,
+  TypedEmitter
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@audicle/sdk",
+	"version": "0.1.0",
+	"type": "module",
+	"description": "Official Node.js/TypeScript SDK for the Audicle transcription API",
+	"license": "MIT",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "tsup && dts-bundle-generator -o dist/index.d.ts src/index.ts --project tsconfig.json --no-banner && cp dist/index.d.ts dist/index.d.cts",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"openapi-fetch": "^0.13.5"
+	},
+	"devDependencies": {
+		"@audicle/shared": "workspace:*",
+		"dts-bundle-generator": "^9.5.1",
+		"msw": "^2.7.3",
+		"tsup": "^8.4.0",
+		"typescript": "^5.7.2",
+		"vitest": "~2.1.8"
+	},
+	"keywords": [
+		"audicle",
+		"transcription",
+		"speech-to-text",
+		"audio",
+		"api",
+		"sdk"
+	]
+}