@rawcast/sdk 0.1.0

package/README.md

@@ -0,0 +1,285 @@
+# @rawcast/sdk
+
+The official, zero-dependency TypeScript & JavaScript SDK for the **Rawcast Media Resolution API**.
+
+Resolves high-speed adaptive HLS/DASH video streams, multi-language WebVTT subtitles, comprehensive TMDB metadata, and 4-quality direct MP4 download links (1080p, 720p, 480p, 360p) with sub-second latency.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)]()
+[![Types: Included](https://img.shields.io/badge/types-TypeScript%20Strict-blue.svg)]()
+[![Runtimes](https://img.shields.io/badge/runtimes-Node%2018%2B%20%7C%20Bun%20%7C%20Deno%20%7C%20CF%20Workers-orange.svg)]()
+
+---
+
+## ⚡ Features
+
+- **Zero Runtime Dependencies**: Powered entirely by the standard Web Fetch API (`fetch`, `Headers`, `AbortController`). Runs anywhere (Node 18+, Bun, Deno, Cloudflare Workers, Next.js, Fastly Compute).
+- **Dual ESM & CommonJS**: Full first-class support for `import` and `require()`.
+- **Smart Stream Selection**: Built-in `.bestStream()` ranking engine automatically picks optimal CDN manifests based on format (HLS/DASH/MP4), resolution, and audio track.
+- **Direct MP4 Downloads**: 1-click download links with RFC 6266 `Content-Disposition` attachment headers across 4 video qualities.
+- **Live Quota Tracking**: Real-time snapshot of remaining monthly developer quota and rate-limit reset windows via `client.quota`.
+- **Built-in Resilience**: Automatic exponential backoff with jitter on HTTP 429 (`Retry-After`) and transient upstream gateway errors (502/503/504).
+- **TypeScript First**: 100% strict type definitions with rich JSDoc documentation and autocomplete.
+
+---
+
+## 📦 Installation
+
+```bash
+# npm
+npm install @rawcast/sdk
+
+# bun
+bun add @rawcast/sdk
+
+# pnpm
+pnpm add @rawcast/sdk
+
+# yarn
+yarn add @rawcast/sdk
+```
+
+---
+
+## 🚀 Quickstart
+
+```typescript
+import { Rawcast } from '@rawcast/sdk';
+
+// Initialize with your API key (or set RAWCAST_API_KEY environment variable)
+const rawcast = new Rawcast({
+  apiKey: 'rc_live_your_api_key_here',
+});
+
+// Resolve movie streaming servers & subtitles
+const sources = await rawcast.movies.getSources(550); // 550 = Fight Club
+
+// Automatically pick the highest quality HLS stream
+const stream = sources.bestStream({ preferFormat: 'hls' });
+
+console.log('Stream Manifest:', stream.manifestUrl);
+console.log('Available Subtitles:', sources.subtitles.length);
+console.log('Remaining Monthly Quota:', rawcast.quota.remaining);
+```
+
+---
+
+## 📖 Usage Guide
+
+### 1. Resolving Movie Streams
+
+```typescript
+const sources = await rawcast.movies.getSources(550, {
+  lang: 'en', // Preferred audio language
+  title: 'Fight Club', // Optional title override
+});
+
+// Pick best stream
+const stream = sources.bestStream({
+  preferFormat: 'hls',     // 'hls' | 'dash' | 'mp4'
+  maxQuality: '1080p',     // '1080p' | '720p' | '480p' | '360p'
+  preferredAudio: 'English',
+});
+
+// Access server groups directly
+for (const server of sources.servers) {
+  console.log(`Server: ${server.name} (${server.format})`);
+  for (const s of server.streams) {
+    console.log(`  - Quality: ${s.quality}, Audio: ${s.audio}, URL: ${s.url}`);
+  }
+}
+```
+
+### 2. Resolving TV Show Episodes
+
+```typescript
+// Resolve Game of Thrones Season 1, Episode 1 (TMDB: 1399)
+const sources = await rawcast.tv.getSources(1399, 1, 1, { lang: 'en' });
+
+// Or pass an options object:
+const sourcesAlt = await rawcast.tv.getSources({
+  tmdbId: 1399,
+  season: 1,
+  episode: 1,
+});
+
+const bestStream = sources.bestStream({ preferFormat: 'hls' });
+console.log('HLS Manifest:', bestStream?.manifestUrl);
+```
+
+### 3. Subtitles & On-The-Fly WebVTT Conversion
+
+Rawcast provides CORS-ready WebVTT conversion on the fly for any remote SRT or VTT subtitle track:
+
+```typescript
+// 1. Fetch available subtitle tracks for a title
+const { subtitles } = await rawcast.subtitles.getMovie(550, { lang: 'en' });
+
+for (const track of subtitles) {
+  console.log(`[${track.language}] ${track.label} -> ${track.url}`);
+}
+
+// 2. Or convert any remote SRT URL to a CORS-friendly WebVTT proxy URL
+const webVttUrl = rawcast.subtitles.getVttUrl('https://example.com/subs.srt');
+// Pass directly to <track src={webVttUrl} kind="subtitles" srcLang="en" />
+```
+
+### 4. Direct 4-Quality MP4 Downloads
+
+Fetch direct download URLs with filename attachments:
+
+```typescript
+// Fetch a specific quality
+const download = await rawcast.movies.getDownload(550, { quality: '1080p' });
+console.log('Download URL:', download.downloadUrl);
+console.log('Filename:', download.filename);
+
+// Or fetch all available qualities (1080p, 720p, 480p, 360p):
+const allDownloads = await rawcast.movies.getDownload(550);
+for (const dl of allDownloads.downloads) {
+  console.log(`${dl.quality}: ${dl.downloadUrl} (${dl.filename})`);
+}
+
+// TV Downloads:
+const tvDownload = await rawcast.tv.getDownload(1399, 1, 1, { quality: '720p' });
+console.log('TV Download:', tvDownload.downloadUrl);
+```
+
+### 5. TMDB Metadata with CDN Posters & Backdrops
+
+```typescript
+// Fetch Movie Metadata
+const movie = await rawcast.metadata.getMovie(550);
+console.log(movie.title, movie.runtime, movie.rating.voteAverage);
+console.log('Poster:', movie.poster?.original);
+console.log('Cast:', movie.cast.slice(0, 5).map(c => c.name).join(', '));
+
+// Fetch TV Show Metadata
+const series = await rawcast.metadata.getTv(1399);
+console.log(series.name, series.numberOfSeasons, series.seasons);
+
+// Fetch Season breakdown with episodes:
+const season1 = await rawcast.metadata.getTv(1399, { season: 1 });
+for (const ep of season1.episodes ?? []) {
+  console.log(`Episode ${ep.episodeNumber}: ${ep.name} (Rating: ${ep.voteAverage})`);
+}
+```
+
+### 6. Live Quota & Rate Limit Inspection
+
+The client automatically captures quota headers from every API call:
+
+```typescript
+await rawcast.movies.getSources(550);
+
+console.log('Monthly Limit:', rawcast.quota.limit);
+console.log('Requests Remaining:', rawcast.quota.remaining);
+console.log('Reset Timestamp:', new Date((rawcast.quota.reset ?? 0) * 1000));
+console.log('Last Sync:', new Date(rawcast.quota.lastUpdated ?? 0));
+```
+
+### 7. Stream Resolution & Direct Player URLs
+
+```typescript
+// Construct a direct streaming URL from a stream token
+const playerUrl = rawcast.resolve.getStreamUrl(stream.token);
+
+// Construct an HLS master playlist URL
+const hlsUrl = rawcast.resolve.getHlsManifestUrl(stream.token);
+
+// Or resolve the upstream CDN destination URL directly
+const directCdnUrl = await rawcast.resolve.resolveDirect(stream.token);
+```
+
+---
+
+## 📺 Video Player Integration Examples
+
+### HTML5 / Hls.js
+
+```html
+<video id="video" controls style="width: 100%; max-width: 800px;"></video>
+<script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
+<script type="module">
+  import { Rawcast } from '@rawcast/sdk';
+
+  const rawcast = new Rawcast('rc_live_...');
+  const sources = await rawcast.movies.getSources(550);
+  const stream = sources.bestStream({ preferFormat: 'hls' });
+
+  const video = document.getElementById('video');
+  if (Hls.isSupported() && stream.manifestUrl) {
+    const hls = new Hls();
+    hls.loadSource(stream.manifestUrl);
+    hls.attachMedia(video);
+  } else {
+    video.src = stream.url;
+  }
+</script>
+```
+
+---
+
+## 🛡️ Error Handling
+
+The SDK exposes granular error classes for all failure modes:
+
+```typescript
+import {
+  Rawcast,
+  RawcastAuthenticationError,
+  RawcastForbiddenError,
+  RawcastNotFoundError,
+  RawcastRateLimitError,
+  RawcastTimeoutError,
+  RawcastUpstreamError,
+} from '@rawcast/sdk';
+
+try {
+  const sources = await rawcast.movies.getSources(550);
+} catch (err) {
+  if (err instanceof RawcastAuthenticationError) {
+    console.error('Invalid or missing API key.');
+  } else if (err instanceof RawcastRateLimitError) {
+    console.error(`Rate limited! Retry in ${err.retryAfterSeconds}s.`);
+    console.error(`Quota Remaining: ${err.remaining}/${err.limit}`);
+  } else if (err instanceof RawcastNotFoundError) {
+    console.error('Media title or token not found.');
+  } else if (err instanceof RawcastUpstreamError) {
+    console.error('Upstream scraper temporary failure. HTTP status:', err.statusCode);
+  } else if (err instanceof RawcastTimeoutError) {
+    console.error(`Request timed out after ${err.timeoutMs}ms.`);
+  } else {
+    console.error('Unexpected error:', err);
+  }
+}
+```
+
+---
+
+## ⚙️ Client Options
+
+```typescript
+interface RawcastOptions {
+  /** Your Rawcast API key (starts with rc_live_) */
+  apiKey: string;
+
+  /** API Base URL (defaults to https://zeroms.space/v1) */
+  baseUrl?: string;
+
+  /** Request timeout in milliseconds (defaults to 25000) */
+  timeoutMs?: number;
+
+  /** Maximum retries on 429 or 502/503/504 errors (defaults to 2) */
+  maxRetries?: number;
+
+  /** Custom fetch implementation for proxies or test mocks */
+  fetch?: typeof fetch;
+}
+```
+
+---
+
+## 📄 License
+
+MIT © Rawcast Team.

package/dist/client.d.ts

@@ -0,0 +1,45 @@
+import { HealthResource } from './resources/health';
+import { MetadataResource } from './resources/metadata';
+import { MoviesResource } from './resources/movies';
+import { ResolveResource } from './resources/resolve';
+import { SubtitlesResource } from './resources/subtitles';
+import { TvResource } from './resources/tv';
+import type { QuotaState, RawcastOptions } from './types';
+/**
+ * Main Rawcast SDK client entry point.
+ *
+ * @example
+ * ```typescript
+ * import { Rawcast } from '@rawcast/sdk';
+ *
+ * const rawcast = new Rawcast({ apiKey: 'rc_live_...' });
+ *
+ * // Resolve movie streams:
+ * const sources = await rawcast.movies.getSources(550);
+ * const stream = sources.bestStream({ preferFormat: 'hls' });
+ *
+ * // TV streams:
+ * const tvSources = await rawcast.tv.getSources(1399, 1, 1);
+ *
+ * // Check remaining monthly quota:
+ * console.log(rawcast.quota.remaining);
+ * ```
+ */
+export declare class Rawcast {
+    private readonly transport;
+    readonly movies: MoviesResource;
+    readonly tv: TvResource;
+    readonly subtitles: SubtitlesResource;
+    readonly metadata: MetadataResource;
+    /** Short alias for metadata */
+    readonly meta: MetadataResource;
+    readonly resolve: ResolveResource;
+    readonly health: HealthResource;
+    constructor(optionsOrApiKey?: string | RawcastOptions);
+    /**
+     * Current rate-limit and monthly credit quota snapshot,
+     * updated automatically after every API response.
+     */
+    get quota(): Readonly<QuotaState>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5C,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAE1C,SAAgB,MAAM,EAAE,cAAc,CAAC;IACvC,SAAgB,EAAE,EAAE,UAAU,CAAC;IAC/B,SAAgB,SAAS,EAAE,iBAAiB,CAAC;IAC7C,SAAgB,QAAQ,EAAE,gBAAgB,CAAC;IAC3C,+BAA+B;IAC/B,SAAgB,IAAI,EAAE,gBAAgB,CAAC;IACvC,SAAgB,OAAO,EAAE,eAAe,CAAC;IACzC,SAAgB,MAAM,EAAE,cAAc,CAAC;gBAE3B,eAAe,CAAC,EAAE,MAAM,GAAG,cAAc;IAwBrD;;;OAGG;IACH,IAAW,KAAK,IAAI,QAAQ,CAAC,UAAU,CAAC,CAEvC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Base error class for all Rawcast SDK errors.
+ */
+export declare class RawcastError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly responseBody?: unknown;
+    constructor(message: string, code?: string, statusCode?: number, responseBody?: unknown);
+}
+/**
+ * Thrown when an invalid or missing API key is supplied (HTTP 401).
+ */
+export declare class RawcastAuthenticationError extends RawcastError {
+    constructor(message?: string, responseBody?: unknown);
+}
+/**
+ * Thrown when account permission or email verification fails (HTTP 403).
+ */
+export declare class RawcastForbiddenError extends RawcastError {
+    constructor(message?: string, code?: string, responseBody?: unknown);
+}
+/**
+ * Thrown when a requested resource, title, or stream token is not found (HTTP 404).
+ */
+export declare class RawcastNotFoundError extends RawcastError {
+    constructor(message?: string, code?: string, responseBody?: unknown);
+}
+/**
+ * Thrown when requests exceed plan quotas or burst rate limits (HTTP 429).
+ */
+export declare class RawcastRateLimitError extends RawcastError {
+    readonly retryAfterSeconds?: number;
+    readonly limit?: number;
+    readonly remaining?: number;
+    readonly reset?: number;
+    constructor(message?: string, options?: {
+        retryAfterSeconds?: number;
+        limit?: number;
+        remaining?: number;
+        reset?: number;
+        responseBody?: unknown;
+    });
+}
+/**
+ * Thrown when upstream scrapers fail or timeout (HTTP 502 / 504).
+ */
+export declare class RawcastUpstreamError extends RawcastError {
+    constructor(message?: string, statusCode?: number, responseBody?: unknown);
+}
+/**
+ * Thrown when an SDK request exceeds the configured client timeout.
+ */
+export declare class RawcastTimeoutError extends RawcastError {
+    constructor(timeoutMs: number);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpC,SAAgB,YAAY,CAAC,EAAE,OAAO,CAAC;gBAGrC,OAAO,EAAE,MAAM,EACf,IAAI,SAAqB,EACzB,UAAU,CAAC,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,OAAO;CASzB;AAED;;GAEG;AACH,qBAAa,0BAA2B,SAAQ,YAAY;gBAC9C,OAAO,SAAmC,EAAE,YAAY,CAAC,EAAE,OAAO;CAI/E;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;gBAEnD,OAAO,SAAuD,EAC9D,IAAI,SAAiB,EACrB,YAAY,CAAC,EAAE,OAAO;CAKzB;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBAElD,OAAO,SAAyC,EAChD,IAAI,SAAiB,EACrB,YAAY,CAAC,EAAE,OAAO;CAKzB;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,YAAY;IACrD,SAAgB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3C,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAC;IAC/B,SAAgB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnC,SAAgB,KAAK,CAAC,EAAE,MAAM,CAAC;gBAG7B,OAAO,SAA0C,EACjD,OAAO,CAAC,EAAE;QACR,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB;CASJ;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;gBAElD,OAAO,SAAwC,EAC/C,UAAU,SAAM,EAChB,YAAY,CAAC,EAAE,OAAO;CAKzB;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;gBACvC,SAAS,EAAE,MAAM;CAI9B"}