naijalingo 0.1.0

package/dist/index.cjs

@@ -0,0 +1,707 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AudioResponse: () => AudioResponse,
+  AudioStream: () => AudioStream,
+  AuthenticationError: () => AuthenticationError,
+  ConnectionError: () => ConnectionError,
+  NaijaLingo: () => NaijaLingo,
+  NaijaLingoError: () => NaijaLingoError,
+  NotFoundError: () => NotFoundError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError,
+  TTS: () => TTS,
+  VERSION: () => VERSION
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var NaijaLingoError = class extends Error {
+  statusCode;
+  response;
+  constructor(message, statusCode, response) {
+    super(message);
+    this.name = "NaijaLingoError";
+    this.statusCode = statusCode;
+    this.response = response;
+  }
+};
+var AuthenticationError = class extends NaijaLingoError {
+  constructor(message, statusCode, response) {
+    super(message, statusCode, response);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends NaijaLingoError {
+  constructor(message, statusCode, response) {
+    super(message, statusCode, response);
+    this.name = "RateLimitError";
+  }
+};
+var NotFoundError = class extends NaijaLingoError {
+  constructor(message, statusCode, response) {
+    super(message, statusCode, response);
+    this.name = "NotFoundError";
+  }
+};
+var ServerError = class extends NaijaLingoError {
+  constructor(message, statusCode, response) {
+    super(message, statusCode, response);
+    this.name = "ServerError";
+  }
+};
+var ConnectionError = class extends NaijaLingoError {
+  constructor(message, statusCode, response) {
+    super(message, statusCode, response);
+    this.name = "ConnectionError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.9jalingo.org";
+var DEFAULT_TIMEOUT_MS = 3e5;
+var BaseClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  defaultHeaders;
+  constructor(options = {}) {
+    this.apiKey = options.apiKey ?? process.env.NAIJALINGO_API_KEY ?? "";
+    const base = options.baseUrl ?? process.env.NAIJALINGO_BASE_URL ?? DEFAULT_BASE_URL;
+    this.baseUrl = base.replace(/\/+$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.defaultHeaders = {
+      "User-Agent": "naijalingo-js/0.1.0"
+    };
+    if (this.apiKey) {
+      this.defaultHeaders["X-API-Key"] = this.apiKey;
+    }
+  }
+  async request(method, path, init = {}) {
+    const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    const timeoutMs = init.timeoutMs ?? this.timeout;
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetch(url, {
+          ...init,
+          method,
+          headers: {
+            ...this.defaultHeaders,
+            ...init.headers
+          },
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (response.ok) {
+          return response;
+        }
+        await this.raiseForStatus(response);
+        return response;
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof NaijaLingoError) {
+          throw err;
+        }
+        lastError = err;
+        const isAbort = err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+        if (isAbort) {
+          throw new ConnectionError(
+            `Request timed out after ${timeoutMs}ms: ${String(err)}`
+          );
+        }
+        if (attempt < 2) {
+          await sleep(1500);
+          continue;
+        }
+      }
+    }
+    throw new ConnectionError(
+      `Unable to connect to ${this.baseUrl}: ${String(lastError)}`
+    );
+  }
+  async raiseForStatus(response) {
+    const status = response.status;
+    let detail;
+    let body;
+    try {
+      body = await response.json();
+      detail = typeof body === "object" && body !== null && "detail" in body ? String(body.detail) : JSON.stringify(body);
+    } catch {
+      detail = await response.text();
+    }
+    if (status === 401 || status === 403) {
+      throw new AuthenticationError(detail, status, body);
+    }
+    if (status === 404) {
+      throw new NotFoundError(detail, status, body);
+    }
+    if (status === 429) {
+      throw new RateLimitError(detail, status, body);
+    }
+    if (status >= 500) {
+      throw new ServerError(detail, status, body);
+    }
+    throw new NaijaLingoError(detail, status, body);
+  }
+  async getJson(path, params) {
+    let url = path;
+    if (params) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(params)) {
+        if (v != null) qs.set(k, v);
+      }
+      const s = qs.toString();
+      if (s) url = `${path}?${s}`;
+    }
+    const resp = await this.request("GET", url);
+    return await resp.json();
+  }
+  async postBytes(path, body) {
+    const resp = await this.request("POST", path, {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+    return new Uint8Array(await resp.arrayBuffer());
+  }
+  async *postStream(path, body) {
+    let lastError;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const response = await fetch(
+          `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`,
+          {
+            method: "POST",
+            headers: {
+              ...this.defaultHeaders,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal
+          }
+        );
+        clearTimeout(timer);
+        if (!response.ok) {
+          await this.raiseForStatus(response);
+        }
+        if (!response.body) {
+          throw new ConnectionError("No response body for stream");
+        }
+        const reader = response.body.getReader();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            if (value && value.length > 0) {
+              yield value;
+            }
+          }
+        } finally {
+          reader.releaseLock();
+        }
+        return;
+      } catch (err) {
+        clearTimeout(timer);
+        if (err instanceof NaijaLingoError) throw err;
+        lastError = err;
+        const isAbort = err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+        if (isAbort) {
+          throw new ConnectionError(`Request timed out: ${String(err)}`);
+        }
+        if (attempt < 2) {
+          await sleep(1500);
+          continue;
+        }
+      }
+    }
+    throw new ConnectionError(
+      `Unable to connect to ${this.baseUrl}: ${String(lastError)}`
+    );
+  }
+  async postMultipart(path, form, timeoutMs) {
+    const resp = await this.request("POST", path, {
+      body: form,
+      timeoutMs: timeoutMs ?? Math.max(this.timeout, 6e5)
+      // Let fetch set multipart boundary — do not set Content-Type
+    });
+    return new Uint8Array(await resp.arrayBuffer());
+  }
+};
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/tts.ts
+var import_promises = require("fs/promises");
+var import_node_path = require("path");
+var import_node_fs = require("fs");
+
+// src/types.ts
+function speakerFromDict(data) {
+  return {
+    id: String(data.id ?? data.speaker_id ?? ""),
+    name: String(data.name ?? data.id ?? ""),
+    language: String(data.language ?? ""),
+    gender: data.gender ?? null,
+    domain: data.domain ?? null
+  };
+}
+function speakerListFromDict(data) {
+  const raw = data.speakers ?? [];
+  const speakers = raw.map(speakerFromDict);
+  const total = typeof data.total === "number" ? data.total : speakers.length;
+  const byLanguage = data.by_language ?? {};
+  return {
+    speakers,
+    total,
+    byLanguage,
+    get length() {
+      return total;
+    },
+    [Symbol.iterator]() {
+      return speakers[Symbol.iterator]();
+    }
+  };
+}
+function languageFromDict(data) {
+  return {
+    code: String(data.code ?? ""),
+    name: String(data.name ?? ""),
+    speakerCount: Number(data.speaker_count ?? 0)
+  };
+}
+function languageListFromDict(data) {
+  const rawLangs = data.languages;
+  let languages;
+  if (rawLangs && typeof rawLangs === "object" && !Array.isArray(rawLangs)) {
+    languages = Object.entries(rawLangs).map(
+      ([code, value]) => {
+        if (value && typeof value === "object") {
+          const v = value;
+          return {
+            code,
+            name: String(v.name ?? code),
+            speakerCount: Number(v.speaker_count ?? 0)
+          };
+        }
+        return { code, name: String(value), speakerCount: 0 };
+      }
+    );
+  } else {
+    const arr = rawLangs ?? [];
+    languages = arr.map(languageFromDict);
+  }
+  return {
+    languages,
+    domains: data.domains ?? []
+  };
+}
+function healthStatusFromDict(data) {
+  const supported = data.supported_languages;
+  let languages = [];
+  if (Array.isArray(data.languages)) {
+    languages = data.languages;
+  } else if (supported && typeof supported === "object") {
+    languages = Object.keys(supported);
+  }
+  return {
+    status: String(data.status ?? "unknown"),
+    engineReady: Boolean(data.engine_ready ?? data.tts_initialized ?? false),
+    codecReady: Boolean(data.codec_ready ?? false),
+    totalSpeakers: Number(data.total_speakers ?? data.speakers_loaded ?? 0),
+    languages,
+    voiceCloningAvailable: Boolean(data.voice_cloning_available ?? false),
+    speakerProjectionLoaded: Boolean(data.speaker_projection_loaded ?? false)
+  };
+}
+function modelFromDict(data) {
+  return {
+    id: String(data.id ?? ""),
+    object: String(data.object ?? "model"),
+    ownedBy: String(data.owned_by ?? "9jalingo")
+  };
+}
+function modelListFromDict(data) {
+  const raw = data.data ?? [];
+  const models = raw.map(modelFromDict);
+  return {
+    models,
+    object: String(data.object ?? "list"),
+    get length() {
+      return models.length;
+    },
+    [Symbol.iterator]() {
+      return models[Symbol.iterator]();
+    }
+  };
+}
+function apiInfoFromDict(data) {
+  return {
+    name: String(data.name ?? ""),
+    version: String(data.version ?? ""),
+    description: String(data.description ?? ""),
+    endpoints: data.endpoints ?? {}
+  };
+}
+function serviceInfoFromDict(data) {
+  return {
+    object: String(data.object ?? "service"),
+    name: String(data.name ?? ""),
+    modelsUrl: String(data.models_url ?? ""),
+    speechUrl: String(data.speech_url ?? ""),
+    speechStreamUrl: String(data.speech_stream_url ?? "")
+  };
+}
+
+// src/voice.ts
+var LANG_ALIASES = {
+  yo: "yo",
+  yor: "yo",
+  yoruba: "yo",
+  ig: "ig",
+  ibo: "ig",
+  igbo: "ig",
+  ha: "ha",
+  hau: "ha",
+  hausa: "ha",
+  pcm: "pcm",
+  pidgin: "pcm"
+};
+function normalizeLang(code) {
+  return LANG_ALIASES[code.trim().toLowerCase()] ?? null;
+}
+function resolveTtsVoiceAndLang(options) {
+  let resolvedLang = null;
+  if (options.lang != null) {
+    resolvedLang = normalizeLang(options.lang);
+    if (resolvedLang == null) {
+      throw new Error(
+        `Unsupported language '${options.lang}'. Use ha, ig, yo, or pcm.`
+      );
+    }
+  } else if (options.language != null) {
+    resolvedLang = normalizeLang(options.language);
+    if (resolvedLang == null) {
+      throw new Error(
+        `Unsupported language '${options.language}'. Use ha, ig, yo, or pcm.`
+      );
+    }
+  }
+  const candidate = options.speaker != null ? options.speaker : options.voice;
+  if (candidate == null || !String(candidate).trim()) {
+    return [null, resolvedLang];
+  }
+  const resolved = String(candidate).trim();
+  const normalized = resolved.toLowerCase();
+  if (normalized in LANG_ALIASES) {
+    const langCode = LANG_ALIASES[normalized];
+    throw new Error(
+      `'${resolved}' is a language code, not a speaker ID. Pass speaker/voice='ada_pcm' (or another speaker ID) and lang='${langCode}' for the language. Browse speakers with: client.tts.listSpeakers({ language: '${langCode}' })`
+    );
+  }
+  if (resolvedLang == null && resolved.includes("_")) {
+    const suffix = resolved.split("_").pop();
+    resolvedLang = normalizeLang(suffix);
+  }
+  return [resolved, resolvedLang];
+}
+function resolveCloneLangAndSpeaker(voice, options = {}) {
+  let resolvedLang = options.lang != null ? normalizeLang(options.lang) : null;
+  let resolvedSpeaker = options.speaker?.trim() || null;
+  const voiceStr = (voice || "").trim();
+  const voiceNorm = voiceStr.toLowerCase();
+  if (voiceNorm in LANG_ALIASES) {
+    if (resolvedLang == null) {
+      resolvedLang = LANG_ALIASES[voiceNorm];
+    }
+  } else if (voiceStr.includes("_")) {
+    if (resolvedSpeaker == null) {
+      resolvedSpeaker = voiceStr;
+    }
+    if (resolvedLang == null) {
+      const suffix = voiceStr.split("_").pop();
+      resolvedLang = normalizeLang(suffix);
+    }
+  } else if (voiceStr && resolvedLang == null) {
+    throw new Error(
+      `'${voice}' is not a language code (ha/ig/yo/pcm) or a speaker ID with a language suffix (e.g. 'daniel_pcm'). Pass voice='pcm' or lang='pcm'.`
+    );
+  }
+  if (!resolvedLang) {
+    throw new Error(
+      "Clone requires a language. Pass voice='pcm' (or 'ha'/'ig'/'yo'), lang='pcm', or a speaker ID ending in _pcm/_ha/_ig/_yo."
+    );
+  }
+  return [resolvedLang, resolvedSpeaker];
+}
+
+// src/tts.ts
+var DEFAULT_MODEL_NAME = "9jalingo-tts-1";
+var AudioResponse = class {
+  content;
+  mediaType;
+  constructor(content, mediaType = "audio/wav") {
+    this.content = content;
+    this.mediaType = mediaType;
+  }
+  /** Write the audio to a file. */
+  async save(path) {
+    await (0, import_promises.mkdir)((0, import_node_path.dirname)(path), { recursive: true });
+    await (0, import_promises.writeFile)(path, this.content);
+    return path;
+  }
+  get length() {
+    return this.content.length;
+  }
+  toString() {
+    return `AudioResponse(${this.content.length} bytes, ${this.mediaType})`;
+  }
+};
+var AudioStream = class {
+  chunks;
+  collected = null;
+  constructor(chunks) {
+    this.chunks = chunks;
+  }
+  async *[Symbol.asyncIterator]() {
+    for await (const chunk of this.chunks) {
+      yield chunk;
+    }
+  }
+  /** Consume the entire stream and return an AudioResponse. */
+  async collect() {
+    if (this.collected == null) {
+      const parts = [];
+      let total = 0;
+      for await (const chunk of this.chunks) {
+        parts.push(chunk);
+        total += chunk.length;
+      }
+      const out = new Uint8Array(total);
+      let offset = 0;
+      for (const part of parts) {
+        out.set(part, offset);
+        offset += part.length;
+      }
+      this.collected = out;
+    }
+    return new AudioResponse(this.collected, "audio/wav");
+  }
+};
+var TTS = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  /** Generate speech from text. */
+  async generate(text, options = {}) {
+    let [resolvedVoice, resolvedLang] = resolveTtsVoiceAndLang(options);
+    if (resolvedVoice == null && options.speakerEmbedding == null) {
+      resolvedVoice = "blessing_pcm";
+    }
+    const responseFormat = options.responseFormat ?? "wav";
+    const body = buildBody({
+      input: text,
+      voice: resolvedVoice,
+      lang: resolvedLang,
+      model: options.modelName ?? DEFAULT_MODEL_NAME,
+      speaker_embedding: options.speakerEmbedding,
+      response_format: responseFormat,
+      temperature: options.temperature,
+      top_p: options.topP,
+      repetition_penalty: options.repetitionPenalty,
+      enable_long_form: options.enableLongForm ?? true,
+      max_chunk_duration: options.maxChunkDuration,
+      silence_duration: options.silenceDuration
+    });
+    const content = await this.client.postBytes("/v1/audio/speech", body);
+    const mediaType = MEDIA_TYPES[responseFormat] ?? "application/octet-stream";
+    return new AudioResponse(content, mediaType);
+  }
+  /** Stream speech generation — audio arrives as it's produced. */
+  stream(text, options = {}) {
+    let [resolvedVoice, resolvedLang] = resolveTtsVoiceAndLang(options);
+    if (resolvedVoice == null && options.speakerEmbedding == null) {
+      resolvedVoice = "blessing_pcm";
+    }
+    const body = buildBody({
+      input: text,
+      voice: resolvedVoice,
+      lang: resolvedLang,
+      speaker_embedding: options.speakerEmbedding,
+      response_format: "wav",
+      temperature: options.temperature,
+      top_p: options.topP,
+      repetition_penalty: options.repetitionPenalty,
+      enable_long_form: options.enableLongForm ?? true,
+      max_chunk_duration: options.maxChunkDuration,
+      silence_duration: options.silenceDuration
+    });
+    return new AudioStream(this.client.postStream("/v1/audio/speech/stream", body));
+  }
+  /**
+   * Generate speech using a cloned voice from a reference audio file.
+   * `audioFile` may be a filesystem path, Buffer, Uint8Array, Blob, or File.
+   */
+  async clone(text, audioFile, options = {}) {
+    const voice = options.voice ?? "pcm";
+    const [resolvedLang, resolvedSpeaker] = resolveCloneLangAndSpeaker(
+      voice,
+      { lang: options.lang, speaker: options.speaker }
+    );
+    const responseFormat = options.responseFormat ?? "wav";
+    const form = new FormData();
+    form.append("text", text);
+    form.append("lang", resolvedLang);
+    form.append("model_name", options.modelName ?? DEFAULT_MODEL_NAME);
+    form.append("response_format", responseFormat);
+    if (resolvedSpeaker) {
+      form.append("voice", resolvedSpeaker);
+    }
+    if (options.temperature != null) {
+      form.append("temperature", String(options.temperature));
+    }
+    if (options.topP != null) {
+      form.append("top_p", String(options.topP));
+    }
+    if (options.repetitionPenalty != null) {
+      form.append("repetition_penalty", String(options.repetitionPenalty));
+    }
+    const { blob, filename } = await toAudioBlob(audioFile);
+    form.append("audio", blob, filename);
+    const content = await this.client.postMultipart("/v1/audio/clone", form);
+    const mediaType = MEDIA_TYPES[responseFormat] ?? "application/octet-stream";
+    return new AudioResponse(content, mediaType);
+  }
+  async listSpeakers(options = {}) {
+    const data = await this.client.getJson("/v1/speakers", {
+      language: options.language,
+      gender: options.gender,
+      domain: options.domain
+    });
+    return speakerListFromDict(data);
+  }
+  async getSpeaker(speakerId) {
+    const data = await this.client.getJson(`/v1/speakers/${speakerId}`);
+    return speakerFromDict(data);
+  }
+  async listLanguages() {
+    const data = await this.client.getJson("/v1/languages");
+    return languageListFromDict(data);
+  }
+  async health() {
+    const data = await this.client.getJson("/v1/health");
+    return healthStatusFromDict(data);
+  }
+};
+var MEDIA_TYPES = {
+  wav: "audio/wav",
+  pcm: "application/octet-stream",
+  flac: "audio/flac",
+  aac: "audio/aac",
+  ogg: "audio/ogg",
+  mp3: "audio/mpeg",
+  alac: "audio/alac"
+};
+function buildBody(kwargs) {
+  const out = {};
+  for (const [k, v] of Object.entries(kwargs)) {
+    if (v !== void 0 && v !== null) out[k] = v;
+  }
+  return out;
+}
+async function toAudioBlob(audioFile) {
+  if (typeof audioFile === "string") {
+    const bytes2 = (0, import_node_fs.readFileSync)(audioFile);
+    const filename = (0, import_node_path.basename)(audioFile);
+    const mime = guessMime(filename);
+    return {
+      blob: new Blob([bytes2], { type: mime }),
+      filename
+    };
+  }
+  if (audioFile instanceof Blob) {
+    return {
+      blob: audioFile,
+      filename: "audio.wav"
+    };
+  }
+  const bytes = audioFile instanceof Uint8Array ? audioFile : new Uint8Array(audioFile);
+  return {
+    blob: new Blob([bytes], { type: "application/octet-stream" }),
+    filename: "audio.wav"
+  };
+}
+function guessMime(filename) {
+  const lower = filename.toLowerCase();
+  if (lower.endsWith(".wav")) return "audio/wav";
+  if (lower.endsWith(".mp3")) return "audio/mpeg";
+  if (lower.endsWith(".flac")) return "audio/flac";
+  if (lower.endsWith(".ogg")) return "audio/ogg";
+  if (lower.endsWith(".aac") || lower.endsWith(".m4a")) return "audio/aac";
+  return "application/octet-stream";
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+var NaijaLingo = class {
+  _client;
+  tts;
+  constructor(options = {}) {
+    this._client = new BaseClient(options);
+    this.tts = new TTS(this._client);
+  }
+  /** List available TTS models. GET /v1/models */
+  async listModels() {
+    const data = await this._client.getJson("/v1/models");
+    return modelListFromDict(data);
+  }
+  /** Root API information. GET / */
+  async apiInfo() {
+    const data = await this._client.getJson("/");
+    return apiInfoFromDict(data);
+  }
+  /** v1 service metadata. GET /v1 */
+  async serviceInfo() {
+    const data = await this._client.getJson("/v1");
+    return serviceInfoFromDict(data);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AudioResponse,
+  AudioStream,
+  AuthenticationError,
+  ConnectionError,
+  NaijaLingo,
+  NaijaLingoError,
+  NotFoundError,
+  RateLimitError,
+  ServerError,
+  TTS,
+  VERSION
+});
+//# sourceMappingURL=index.cjs.map