first commit

docs/media/audio/voice-elevenlabs/src/models/models.md

@@ -0,0 +1,89 @@
+# `models`
+
+ElevenLabs model catalog. Lists every model the API key has access to,
+along with capability flags (TTS / voice conversion / fine-tuning) and
+the language matrix. Calls `GET /v1/models`.
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Most ElevenLabs adapters take an optional `modelId` parameter — but
+which model is appropriate depends on the operation, the language, the
+account tier, and whether the model serves Pro voices or requires Alpha
+access. This catalog gives application code a typed view of the
+account's available models so it can pick the right one at runtime
+instead of hard-coding strings, and degrade gracefully if a previously
+chosen model is no longer accessible.
+
+## Features
+
+- One method, `list()`, returning `readonly ElevenLabsModel[]`.
+- Each `ElevenLabsModel` carries the model id, display name, capability
+  flags (`canDoTextToSpeech`, `canDoVoiceConversion`, `canBeFinetuned`),
+  language matrix, and account-tier limits (`maxCharactersFree`,
+  `maxCharactersSubscribed`).
+- Optional metadata (`description`, `requiresAlphaAccess`,
+  `servesProVoices`, `tokenCostFactor`) is included only when present in
+  the upstream response.
+- Boolean capability flags default to `false` when missing, and the
+  language list defaults to `[]`.
+- Errors are remapped onto the `@suaveplan/voice` domain:
+  `ProviderNotConfiguredError`, `ProviderRateLimitedError`, and a
+  generic `VoiceError` for everything else.
+
+## Usage: Basic Example
+
+```ts
+import { createElevenLabsAdapters } from "@suaveplan/third-party-elevenlabs";
+
+const { models } = createElevenLabsAdapters({ apiKey: KEY });
+const all = await models.list();
+for (const m of all) console.log(m.modelId, m.name);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { createElevenLabsAdapters } from "@suaveplan/third-party-elevenlabs";
+
+const { models } = createElevenLabsAdapters({ apiKey: KEY });
+
+const all = await models.list();
+const ttsModelsForEnglish = all.filter(
+    (m) =>
+        m.canDoTextToSpeech &&
+        m.languages.some((l) => l.languageId === "en") &&
+        !m.requiresAlphaAccess
+);
+const cheapest = ttsModelsForEnglish.reduce((best, m) =>
+    (m.tokenCostFactor ?? 1) < (best.tokenCostFactor ?? 1) ? m : best
+);
+console.log("picked:", cheapest.modelId);
+```
+
+## API Reference
+
+- `interface ElevenLabsLanguage { languageId: string; name: string }`
+- `interface ElevenLabsModel { modelId, name, canDoTextToSpeech, canDoVoiceConversion, canBeFinetuned, languages, description?, maxCharactersFree?, maxCharactersSubscribed?, requiresAlphaAccess?, servesProVoices?, tokenCostFactor? }`
+- `class ElevenLabsModelCatalog`
+  - `providerName: "elevenlabs"`
+  - `list(): Promise<readonly ElevenLabsModel[]>`
+
+Throws: `ProviderNotConfiguredError`, `ProviderRateLimitedError`, and
+generic VoiceError-shaped failures.
+
+## Implementation Notes
+
+- The endpoint returns an array, not a paged envelope. There is no
+  `pageToken` to follow.
+- Language entries with missing `language_id` or `name` are still
+  emitted, but with empty strings — caller code should guard against
+  this rather than crash.
+- The catalog is not cached. Wrap it in an async-cache if you call it
+  frequently — model lists change rarely (days / weeks).
+- `tokenCostFactor` is ElevenLabs's relative pricing multiplier vs. the
+  base model. A value of `1` means 1× character billing; `0.5` means
+  half-cost (cheaper, often lower fidelity).