unified-live

unified-live

A TypeScript SDK providing a unified interface for live streaming platform APIs.

Documentation   |   Getting Started   |   API Reference   |   Contributing

---

Pass a URL and the SDK auto-detects the platform, normalizes the response, and handles auth, rate limits, and retries.

Features

• Unified API — One interface for YouTube, Twitch, and TwitCasting. Content, Channel, Broadcast, Archive types work across all platforms.
• Plugin Architecture — Install only the platforms you need. Each platform is a separate package with its own auth, rate limiting, and URL resolution.
• OpenTelemetry Compatible — Built-in tracing with zero overhead when OTel SDK is not configured. Every API call emits spans with platform, HTTP, rate limit, and quota attributes.
• Automatic Rate Limiting — Token bucket (Twitch, TwitCasting) and quota-based (YouTube) strategies handled transparently with exponential backoff retries.
• Zero Required Dependencies — The core package has no runtime dependencies. OpenTelemetry tracing is supported via an optional peer dependency. Plain TypeScript types with discriminated unions — no schema libraries, no bloat.
• Type-Safe — Content.isBroadcast() / Content.isArchive() companion object type guards for safe narrowing across all content types.
• Runtime Agnostic — Works on Node.js 18+, Deno, Bun, Cloudflare Workers — any runtime with native fetch.

Quick Start

# npm
npm install @unified-live/core @unified-live/youtube @unified-live/twitch

# pnpm
pnpm add @unified-live/core @unified-live/youtube @unified-live/twitch

import { UnifiedClient, Content } from "@unified-live/core";
import { createYouTubePlugin } from "@unified-live/youtube";
import { createTwitchPlugin } from "@unified-live/twitch";

const client = UnifiedClient.create({
  plugins: [
    createYouTubePlugin({ apiKey: process.env.YOUTUBE_API_KEY! }),
    createTwitchPlugin({
      clientId: process.env.TWITCH_CLIENT_ID!,
      clientSecret: process.env.TWITCH_CLIENT_SECRET!,
    }),
  ],
});

// Auto-detects platform from URL
const content = await client.resolve("https://www.youtube.com/watch?v=dQw4w9WgXcQ");

console.log(content.title);
console.log(content.platform); // "youtube"
console.log(content.type); // "broadcast", "scheduled", "archive", or "clip"

// Type-safe narrowing with companion object guards
if (Content.isBroadcast(content)) {
  console.log(content.startedAt); // only available on Broadcast
}

Error Handling

All SDK errors extend UnifiedLiveError with a typed code field:

import { UnifiedLiveError, ErrorCode } from "@unified-live/core";

try {
  const content = await client.resolve(url);
} catch (error) {
  if (error instanceof UnifiedLiveError) {
    if (ErrorCode.isNetwork(error.code)) {
      // NETWORK_TIMEOUT, NETWORK_CONNECTION, etc.
    }
    if (ErrorCode.isRateLimit(error.code)) {
      // RATE_LIMIT_EXCEEDED — automatic retries already attempted
    }
  }
}

Packages