first commit

plugins/library-navigator/skills/sp-third-party-elevenlabs/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sp-third-party-elevenlabs
+description: Typed thin client for ElevenLabs platform API — REST + WebSocket transport, retry, rate-limit parsing, OTel, Zod-validated DTOs. Domain adapters compose this client.
+---
+
+# sp-third-party-elevenlabs
+
+| Symbol | Kind | Responsibility |
+|---|---|---|
+| `ElevenLabsClient` | Class | Typed HTTP + WebSocket client for ElevenLabs API with retry and rate-limit handling |
+| `buildHeaders` | Function | Constructs authenticated request headers with API key |
+| `buildUrl` | Function | Builds endpoint URLs with path and query parameters |
+| `parseRetryAfter` | Function | Parses `Retry-After` header for rate-limit backoff |
+| `extractMetadata` | Function | Extracts response metadata (rate limits, request ID) |
+| `ElevenLabsApiError` | Class | Structured error hierarchy with 15+ specific error classes |
+| `ELEVENLABS_CODES` | Constant | Error-code registry via `@suaveplan/error` `defineCodes` |
+
+**File Structure:** `packages/media/audio/third-party-elevenlabs/src/{client,errors,types}/`
+
+**Sibling packages:**
+- `@suaveplan/voice-elevenlabs` — ElevenLabs domain adapter for voice operations
+- `@suaveplan/retry` — retry policy
+
+**Patterns:**
+
+*Quick Start:*
+```ts
+import { ElevenLabsClient } from "@suaveplan/third-party-elevenlabs/client/client";
+const client = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY });
+const voices = await client.get("/voices");
+```
+
+*WebSocket streaming:*
+```ts
+const ws = await client.connectWebSocket("/v1/text-to-speech", { voiceId: "abc" });
+ws.send(JSON.stringify({ text: "Hello world" }));
+```
+
+**Constraints:**
+- Subpath exports: `/client/client`, `/client/headers`, `/client/url`, `/errors/errors`, `/types/types`
+- `ElevenLabsClient` uses `@suaveplan/retry` for transient failures
+- Rate-limit headers parsed and surfaced as `RateLimitExceededError`
+- Zod-validated request/response DTOs
+- OTel instrumented for request count, latency, and errors
+
+**Checklist:**
+- [ ] `ElevenLabsClient` supports GET, POST, PUT, DELETE, and WebSocket
+- [ ] Rate-limit responses trigger `RateLimitExceededError` with retry-after
+- [ ] All response DTOs are Zod-validated
+- [ ] WebSocket connections handle protocol errors gracefully