@rawcast/sdk 0.1.0 → 0.1.1

package/README.md

@@ -15,6 +15,7 @@ Resolves high-speed adaptive HLS/DASH video streams, multi-language WebVTT subti
 
 - **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()`.
+- **High Availability & Auto-Failover**: Seamlessly fails over to backup mirrors or queries an out-of-band remote discovery manifest (GitHub Gist) if the primary domain is unreachable, ensuring uninterrupted playback even during domain migrations or DNS outages.
 - **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`.
@@ -64,6 +65,35 @@ console.log('Remaining Monthly Quota:', rawcast.quota.remaining);
 
 ---
 
+## 🌐 High Availability & Out-of-Band Discovery
+
+The Rawcast SDK features a **self-healing transport layer**. If the primary API domain suffers a DNS outage, the client automatically:
+1. Retries the request against warm standby mirrors (`fallbackUrls`).
+2. If all local mirrors are unreachable, it automatically queries an out-of-band remote discovery manifest hosted on GitHub Gist to discover active mirrors.
+3. Automatically updates its internal base URL so subsequent calls go straight to the working mirror without application restarts or code updates.
+
+```typescript
+const rawcast = new Rawcast({
+  apiKey: 'rc_live_your_api_key',
+  // Primary endpoint:
+  baseUrl: 'https://api.rawcast.space/v1',
+  // Standby mirrors:
+  fallbackUrls: ['https://zeroms.space/v1'],
+  // Auto-failover enabled by default:
+  autoFailover: true,
+});
+
+// Check which endpoint is currently answering requests:
+console.log(rawcast.baseUrl);
+
+// Proactively inspect the remote discovery manifest:
+const manifest = await rawcast.discoverEndpoints();
+console.log('Active primary:', manifest?.primary);
+console.log('Active mirrors:', manifest?.mirrors);
+```
+
+---
+
 ## 📖 Usage Guide
 
 ### 1. Resolving Movie Streams
@@ -258,19 +288,28 @@ try {
 ---
 
 ## ⚙️ Client Options
-
+ 
 ```typescript
 interface RawcastOptions {
   /** Your Rawcast API key (starts with rc_live_) */
   apiKey: string;
 
-  /** API Base URL (defaults to https://zeroms.space/v1) */
+  /** API Base URL (defaults to https://api.rawcast.space/v1) */
   baseUrl?: string;
 
+  /** Standby mirror base URLs to try on connection failure (defaults to ["https://zeroms.space/v1"]) */
+  fallbackUrls?: string[];
+
+  /** Out-of-band remote discovery endpoint URL (defaults to official Rawcast GitHub Gist) */
+  discoveryUrl?: string;
+
+  /** Whether to automatically failover to fallback mirrors or query discovery (defaults to true) */
+  autoFailover?: boolean;
+
   /** Request timeout in milliseconds (defaults to 25000) */
   timeoutMs?: number;
 
-  /** Maximum retries on 429 or 502/503/504 errors (defaults to 2) */
+  /** Maximum retries on 429 or 502/503/504 errors per endpoint (defaults to 2) */
   maxRetries?: number;
 
   /** Custom fetch implementation for proxies or test mocks */

package/dist/client.d.ts

@@ -4,7 +4,7 @@ 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';
+import type { QuotaState, RawcastEndpointsManifest, RawcastOptions } from './types';
 /**
  * Main Rawcast SDK client entry point.
  *
@@ -36,6 +36,19 @@ export declare class Rawcast {
     readonly resolve: ResolveResource;
     readonly health: HealthResource;
     constructor(optionsOrApiKey?: string | RawcastOptions);
+    /**
+     * The currently active API base URL (updates dynamically on failover).
+     */
+    get baseUrl(): string;
+    /**
+     * Manually override the active API base URL at runtime.
+     */
+    setBaseUrl(url: string): void;
+    /**
+     * Proactively queries the out-of-band remote discovery manifest (GitHub Gist)
+     * to check current endpoint statuses and mirrors.
+     */
+    discoverEndpoints(): Promise<RawcastEndpointsManifest | null>;
     /**
      * Current rate-limit and monthly credit quota snapshot,
      * updated automatically after every API response.

package/dist/client.d.ts.map

@@ -1 +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"}
+{"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,wBAAwB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEpF;;;;;;;;;;;;;;;;;;;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;;OAEG;IACH,IAAW,OAAO,IAAI,MAAM,CAE3B;IAED;;OAEG;IACI,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIpC;;;OAGG;IACU,iBAAiB,IAAI,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC;IAI1E;;;OAGG;IACH,IAAW,KAAK,IAAI,QAAQ,CAAC,UAAU,CAAC,CAEvC;CACF"}

package/dist/index.cjs

@@ -464,12 +464,21 @@ class TvResource {
 }
 
 // src/transport.ts
+var DEFAULT_BASE_URL = "https://api.rawcast.space/v1";
+var DEFAULT_FALLBACK_URLS = ["https://zeroms.space/v1"];
+var DEFAULT_DISCOVERY_URL = "https://gist.githubusercontent.com/c1ph3rhunt3r/8e11bc9b749378b140616d89157a5a6c/raw/rawcast-endpoints.json";
+
 class HttpTransport {
-  baseUrl;
+  currentBaseUrl;
+  fallbackUrls;
+  discoveryUrl;
+  autoFailover;
   apiKey;
   timeoutMs;
   maxRetries;
   fetchFn;
+  discoveredManifest = null;
+  discoveryPromise = null;
   quota = {
     limit: null,
     remaining: null,
@@ -481,7 +490,16 @@ class HttpTransport {
       throw new RawcastAuthenticationError("Rawcast API key is required. Pass apiKey or set process.env.RAWCAST_API_KEY.");
     }
     this.apiKey = options.apiKey.trim();
-    this.baseUrl = (options.baseUrl || "https://zeroms.space/v1").replace(/\/+$/, "");
+    this.currentBaseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    if (options.fallbackUrls) {
+      this.fallbackUrls = options.fallbackUrls.map((u) => u.replace(/\/+$/, ""));
+    } else if (options.baseUrl) {
+      this.fallbackUrls = [];
+    } else {
+      this.fallbackUrls = [...DEFAULT_FALLBACK_URLS];
+    }
+    this.discoveryUrl = options.discoveryUrl || DEFAULT_DISCOVERY_URL;
+    this.autoFailover = options.autoFailover ?? true;
     this.timeoutMs = options.timeoutMs ?? 25000;
     this.maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.fetchFn = options.fetch ?? globalThis.fetch;
@@ -489,6 +507,75 @@ class HttpTransport {
       throw new RawcastError("Global fetch is not available. Please provide a custom fetch implementation or upgrade Node/runtime.");
     }
   }
+  get baseUrl() {
+    return this.currentBaseUrl;
+  }
+  getBaseUrl() {
+    return this.currentBaseUrl;
+  }
+  setBaseUrl(url) {
+    this.currentBaseUrl = url.replace(/\/+$/, "");
+  }
+  getApiKey() {
+    return this.apiKey;
+  }
+  getFetch() {
+    return this.fetchFn;
+  }
+  async discoverEndpoints() {
+    if (this.discoveredManifest)
+      return this.discoveredManifest;
+    if (this.discoveryPromise)
+      return this.discoveryPromise;
+    this.discoveryPromise = (async () => {
+      try {
+        const controller = new AbortController;
+        const timer = setTimeout(() => controller.abort(), 6000);
+        const res = await this.fetchFn(this.discoveryUrl, {
+          method: "GET",
+          headers: { Accept: "application/json, text/plain, */*" },
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (res.ok) {
+          const data = await res.json();
+          if (data && typeof data === "object" && typeof data.primary === "string") {
+            this.discoveredManifest = data;
+            return data;
+          }
+        }
+      } catch {} finally {
+        this.discoveryPromise = null;
+      }
+      return null;
+    })();
+    return this.discoveryPromise;
+  }
+  getNextCandidate(triedUrls) {
+    for (const url of this.fallbackUrls) {
+      const clean = url.replace(/\/+$/, "");
+      if (!triedUrls.has(clean)) {
+        return clean;
+      }
+    }
+    if (this.discoveredManifest) {
+      if (this.discoveredManifest.primary) {
+        const clean = this.discoveredManifest.primary.replace(/\/+$/, "");
+        if (!triedUrls.has(clean)) {
+          return clean;
+        }
+      }
+      if (Array.isArray(this.discoveredManifest.mirrors)) {
+        for (const mirror of this.discoveredManifest.mirrors) {
+          const clean = mirror.replace(/\/+$/, "");
+          if (!triedUrls.has(clean)) {
+            return clean;
+          }
+        }
+      }
+    }
+    return null;
+  }
   updateQuotaHeaders(headers) {
     const limit = headers.get("x-ratelimit-limit");
     const remaining = headers.get("x-ratelimit-remaining");
@@ -503,17 +590,8 @@ class HttpTransport {
   async sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
-  getBaseUrl() {
-    return this.baseUrl;
-  }
-  getApiKey() {
-    return this.apiKey;
-  }
-  getFetch() {
-    return this.fetchFn;
-  }
   async rawFetch(endpoint, options = {}) {
-    const url = endpoint.startsWith("http") ? endpoint : `${this.baseUrl}/${endpoint.replace(/^\/+/, "")}`;
+    const url = endpoint.startsWith("http") ? endpoint : `${this.currentBaseUrl}/${endpoint.replace(/^\/+/, "")}`;
     const headers = new Headers(options.headers || {});
     if (!options.skipAuth) {
       headers.set("X-API-Key", this.apiKey);
@@ -523,8 +601,8 @@ class HttpTransport {
       headers
     });
   }
-  async request(endpoint, options = {}) {
-    const url = endpoint.startsWith("http") ? endpoint : `${this.baseUrl}/${endpoint.replace(/^\/+/, "")}`;
+  async executeSingle(baseUrl, endpoint, options = {}) {
+    const url = endpoint.startsWith("http") ? endpoint : `${baseUrl}/${endpoint.replace(/^\/+/, "")}`;
     const timeout = options.timeoutMs ?? this.timeoutMs;
     let attempt = 0;
     while (attempt <= this.maxRetries) {
@@ -615,6 +693,33 @@ class HttpTransport {
     }
     throw new RawcastError("Request failed after maximum retries exceeded.");
   }
+  async request(endpoint, options = {}) {
+    if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+      return this.executeSingle("", endpoint, options);
+    }
+    const triedUrls = new Set;
+    while (true) {
+      const activeUrl = this.currentBaseUrl;
+      triedUrls.add(activeUrl);
+      try {
+        return await this.executeSingle(activeUrl, endpoint, options);
+      } catch (err) {
+        const isEligibleForFailover = err instanceof RawcastError && (err.code === "RC_NETWORK_ERROR" || err.code === "RC_TIMEOUT") || err instanceof RawcastTimeoutError || err instanceof RawcastUpstreamError;
+        if (!this.autoFailover || !isEligibleForFailover) {
+          throw err;
+        }
+        let nextCandidate = this.getNextCandidate(triedUrls);
+        if (!nextCandidate) {
+          await this.discoverEndpoints();
+          nextCandidate = this.getNextCandidate(triedUrls);
+        }
+        if (!nextCandidate) {
+          throw err;
+        }
+        this.currentBaseUrl = nextCandidate;
+      }
+    }
+  }
 }
 
 // src/client.ts
@@ -646,6 +751,15 @@ class Rawcast {
     this.resolve = new ResolveResource(this.transport);
     this.health = new HealthResource(this.transport);
   }
+  get baseUrl() {
+    return this.transport.getBaseUrl();
+  }
+  setBaseUrl(url) {
+    this.transport.setBaseUrl(url);
+  }
+  async discoverEndpoints() {
+    return this.transport.discoverEndpoints();
+  }
   get quota() {
     return this.transport.quota;
   }

package/dist/index.mjs

@@ -403,12 +403,21 @@ class TvResource {
 }
 
 // src/transport.ts
+var DEFAULT_BASE_URL = "https://api.rawcast.space/v1";
+var DEFAULT_FALLBACK_URLS = ["https://zeroms.space/v1"];
+var DEFAULT_DISCOVERY_URL = "https://gist.githubusercontent.com/c1ph3rhunt3r/8e11bc9b749378b140616d89157a5a6c/raw/rawcast-endpoints.json";
+
 class HttpTransport {
-  baseUrl;
+  currentBaseUrl;
+  fallbackUrls;
+  discoveryUrl;
+  autoFailover;
   apiKey;
   timeoutMs;
   maxRetries;
   fetchFn;
+  discoveredManifest = null;
+  discoveryPromise = null;
   quota = {
     limit: null,
     remaining: null,
@@ -420,7 +429,16 @@ class HttpTransport {
       throw new RawcastAuthenticationError("Rawcast API key is required. Pass apiKey or set process.env.RAWCAST_API_KEY.");
     }
     this.apiKey = options.apiKey.trim();
-    this.baseUrl = (options.baseUrl || "https://zeroms.space/v1").replace(/\/+$/, "");
+    this.currentBaseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    if (options.fallbackUrls) {
+      this.fallbackUrls = options.fallbackUrls.map((u) => u.replace(/\/+$/, ""));
+    } else if (options.baseUrl) {
+      this.fallbackUrls = [];
+    } else {
+      this.fallbackUrls = [...DEFAULT_FALLBACK_URLS];
+    }
+    this.discoveryUrl = options.discoveryUrl || DEFAULT_DISCOVERY_URL;
+    this.autoFailover = options.autoFailover ?? true;
     this.timeoutMs = options.timeoutMs ?? 25000;
     this.maxRetries = Math.max(0, options.maxRetries ?? 2);
     this.fetchFn = options.fetch ?? globalThis.fetch;
@@ -428,6 +446,75 @@ class HttpTransport {
       throw new RawcastError("Global fetch is not available. Please provide a custom fetch implementation or upgrade Node/runtime.");
     }
   }
+  get baseUrl() {
+    return this.currentBaseUrl;
+  }
+  getBaseUrl() {
+    return this.currentBaseUrl;
+  }
+  setBaseUrl(url) {
+    this.currentBaseUrl = url.replace(/\/+$/, "");
+  }
+  getApiKey() {
+    return this.apiKey;
+  }
+  getFetch() {
+    return this.fetchFn;
+  }
+  async discoverEndpoints() {
+    if (this.discoveredManifest)
+      return this.discoveredManifest;
+    if (this.discoveryPromise)
+      return this.discoveryPromise;
+    this.discoveryPromise = (async () => {
+      try {
+        const controller = new AbortController;
+        const timer = setTimeout(() => controller.abort(), 6000);
+        const res = await this.fetchFn(this.discoveryUrl, {
+          method: "GET",
+          headers: { Accept: "application/json, text/plain, */*" },
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (res.ok) {
+          const data = await res.json();
+          if (data && typeof data === "object" && typeof data.primary === "string") {
+            this.discoveredManifest = data;
+            return data;
+          }
+        }
+      } catch {} finally {
+        this.discoveryPromise = null;
+      }
+      return null;
+    })();
+    return this.discoveryPromise;
+  }
+  getNextCandidate(triedUrls) {
+    for (const url of this.fallbackUrls) {
+      const clean = url.replace(/\/+$/, "");
+      if (!triedUrls.has(clean)) {
+        return clean;
+      }
+    }
+    if (this.discoveredManifest) {
+      if (this.discoveredManifest.primary) {
+        const clean = this.discoveredManifest.primary.replace(/\/+$/, "");
+        if (!triedUrls.has(clean)) {
+          return clean;
+        }
+      }
+      if (Array.isArray(this.discoveredManifest.mirrors)) {
+        for (const mirror of this.discoveredManifest.mirrors) {
+          const clean = mirror.replace(/\/+$/, "");
+          if (!triedUrls.has(clean)) {
+            return clean;
+          }
+        }
+      }
+    }
+    return null;
+  }
   updateQuotaHeaders(headers) {
     const limit = headers.get("x-ratelimit-limit");
     const remaining = headers.get("x-ratelimit-remaining");
@@ -442,17 +529,8 @@ class HttpTransport {
   async sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
-  getBaseUrl() {
-    return this.baseUrl;
-  }
-  getApiKey() {
-    return this.apiKey;
-  }
-  getFetch() {
-    return this.fetchFn;
-  }
   async rawFetch(endpoint, options = {}) {
-    const url = endpoint.startsWith("http") ? endpoint : `${this.baseUrl}/${endpoint.replace(/^\/+/, "")}`;
+    const url = endpoint.startsWith("http") ? endpoint : `${this.currentBaseUrl}/${endpoint.replace(/^\/+/, "")}`;
     const headers = new Headers(options.headers || {});
     if (!options.skipAuth) {
       headers.set("X-API-Key", this.apiKey);
@@ -462,8 +540,8 @@ class HttpTransport {
       headers
     });
   }
-  async request(endpoint, options = {}) {
-    const url = endpoint.startsWith("http") ? endpoint : `${this.baseUrl}/${endpoint.replace(/^\/+/, "")}`;
+  async executeSingle(baseUrl, endpoint, options = {}) {
+    const url = endpoint.startsWith("http") ? endpoint : `${baseUrl}/${endpoint.replace(/^\/+/, "")}`;
     const timeout = options.timeoutMs ?? this.timeoutMs;
     let attempt = 0;
     while (attempt <= this.maxRetries) {
@@ -554,6 +632,33 @@ class HttpTransport {
     }
     throw new RawcastError("Request failed after maximum retries exceeded.");
   }
+  async request(endpoint, options = {}) {
+    if (endpoint.startsWith("http://") || endpoint.startsWith("https://")) {
+      return this.executeSingle("", endpoint, options);
+    }
+    const triedUrls = new Set;
+    while (true) {
+      const activeUrl = this.currentBaseUrl;
+      triedUrls.add(activeUrl);
+      try {
+        return await this.executeSingle(activeUrl, endpoint, options);
+      } catch (err) {
+        const isEligibleForFailover = err instanceof RawcastError && (err.code === "RC_NETWORK_ERROR" || err.code === "RC_TIMEOUT") || err instanceof RawcastTimeoutError || err instanceof RawcastUpstreamError;
+        if (!this.autoFailover || !isEligibleForFailover) {
+          throw err;
+        }
+        let nextCandidate = this.getNextCandidate(triedUrls);
+        if (!nextCandidate) {
+          await this.discoverEndpoints();
+          nextCandidate = this.getNextCandidate(triedUrls);
+        }
+        if (!nextCandidate) {
+          throw err;
+        }
+        this.currentBaseUrl = nextCandidate;
+      }
+    }
+  }
 }
 
 // src/client.ts
@@ -585,6 +690,15 @@ class Rawcast {
     this.resolve = new ResolveResource(this.transport);
     this.health = new HealthResource(this.transport);
   }
+  get baseUrl() {
+    return this.transport.getBaseUrl();
+  }
+  setBaseUrl(url) {
+    this.transport.setBaseUrl(url);
+  }
+  async discoverEndpoints() {
+    return this.transport.discoverEndpoints();
+  }
   get quota() {
     return this.transport.quota;
   }

package/dist/transport.d.ts

@@ -1,20 +1,33 @@
-import type { QuotaState, RawcastOptions } from './types';
+import type { QuotaState, RawcastEndpointsManifest, RawcastOptions } from './types';
+export declare const DEFAULT_BASE_URL = "https://api.rawcast.space/v1";
+export declare const DEFAULT_FALLBACK_URLS: string[];
+export declare const DEFAULT_DISCOVERY_URL = "https://gist.githubusercontent.com/c1ph3rhunt3r/8e11bc9b749378b140616d89157a5a6c/raw/rawcast-endpoints.json";
 export declare class HttpTransport {
-    readonly baseUrl: string;
+    private currentBaseUrl;
+    private readonly fallbackUrls;
+    private readonly discoveryUrl;
+    private readonly autoFailover;
     private readonly apiKey;
     private readonly timeoutMs;
     private readonly maxRetries;
     private readonly fetchFn;
+    private discoveredManifest;
+    private discoveryPromise;
     readonly quota: QuotaState;
     constructor(options: RawcastOptions);
-    private updateQuotaHeaders;
-    private sleep;
+    get baseUrl(): string;
     getBaseUrl(): string;
+    setBaseUrl(url: string): void;
     getApiKey(): string;
     getFetch(): typeof fetch;
+    discoverEndpoints(): Promise<RawcastEndpointsManifest | null>;
+    private getNextCandidate;
+    private updateQuotaHeaders;
+    private sleep;
     rawFetch(endpoint: string, options?: RequestInit & {
         skipAuth?: boolean;
     }): Promise<Response>;
+    private executeSingle;
     request<T>(endpoint: string, options?: RequestInit & {
         timeoutMs?: number;
         skipAuth?: boolean;

package/dist/transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1D,qBAAa,aAAa;IACxB,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,SAAgB,KAAK,EAAE,UAAU,CAK/B;gBAEU,OAAO,EAAE,cAAc;IAoBnC,OAAO,CAAC,kBAAkB;YAcZ,KAAK;IAIZ,UAAU,IAAI,MAAM;IAIpB,SAAS,IAAI,MAAM;IAInB,QAAQ,IAAI,OAAO,KAAK;IAIlB,QAAQ,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAW,GAAG;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GACjD,OAAO,CAAC,QAAQ,CAAC;IAgBP,OAAO,CAAC,CAAC,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAW,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GACrE,OAAO,CAAC,CAAC,CAAC;CAmId"}
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,wBAAwB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEpF,eAAO,MAAM,gBAAgB,iCAAiC,CAAC;AAC/D,eAAO,MAAM,qBAAqB,UAA8B,CAAC;AACjE,eAAO,MAAM,qBAAqB,gHAC6E,CAAC;AAEhH,qBAAa,aAAa;IACxB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAW;IACxC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IAEvC,OAAO,CAAC,kBAAkB,CAAyC;IACnE,OAAO,CAAC,gBAAgB,CAAyD;IAEjF,SAAgB,KAAK,EAAE,UAAU,CAK/B;gBAEU,OAAO,EAAE,cAAc;IAgCnC,IAAW,OAAO,IAAI,MAAM,CAE3B;IAEM,UAAU,IAAI,MAAM;IAIpB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI7B,SAAS,IAAI,MAAM;IAInB,QAAQ,IAAI,OAAO,KAAK;IAIlB,iBAAiB,IAAI,OAAO,CAAC,wBAAwB,GAAG,IAAI,CAAC;IAmC1E,OAAO,CAAC,gBAAgB;IA8BxB,OAAO,CAAC,kBAAkB;YAcZ,KAAK;IAIN,QAAQ,CACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAW,GAAG;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GACjD,OAAO,CAAC,QAAQ,CAAC;YAgBN,aAAa;IAsId,OAAO,CAAC,CAAC,EACpB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,WAAW,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GACrE,OAAO,CAAC,CAAC,CAAC;CAwCd"}

package/dist/types.d.ts

@@ -15,6 +15,18 @@ export interface ProviderHealthDashboard {
     timestamp: string;
     servers: Record<string, string>;
 }
+/**
+ * Out-of-band remote endpoints manifest structure.
+ */
+export interface RawcastEndpointsManifest {
+    version: number;
+    updated_at?: string;
+    status?: string;
+    primary: string;
+    portal?: string;
+    mirrors?: string[];
+    notice?: string;
+}
 /**
  * Configuration options for the Rawcast SDK client.
  */
@@ -25,16 +37,31 @@ export interface RawcastOptions {
     apiKey: string;
     /**
      * Base URL of the Rawcast API.
-     * @default "https://zeroms.space/v1"
+     * @default "https://api.rawcast.space/v1"
      */
     baseUrl?: string;
+    /**
+     * List of fallback mirror base URLs to try if the primary endpoint is unreachable.
+     * @default ["https://zeroms.space/v1"]
+     */
+    fallbackUrls?: string[];
+    /**
+     * Out-of-band remote discovery endpoint URL for finding live mirrors if primary and hardcoded fallbacks fail.
+     * @default "https://gist.githubusercontent.com/c1ph3rhunt3r/8e11bc9b749378b140616d89157a5a6c/raw/rawcast-endpoints.json"
+     */
+    discoveryUrl?: string;
+    /**
+     * Whether to automatically failover to fallback mirrors or query the remote discovery endpoint on network / DNS failures.
+     * @default true
+     */
+    autoFailover?: boolean;
     /**
      * Request timeout in milliseconds.
      * @default 25000
      */
     timeoutMs?: number;
     /**
-     * Maximum number of automatic retries on rate limits (HTTP 429) or transient 5xx errors.
+     * Maximum number of automatic retries on rate limits (HTTP 429) or transient 5xx errors per endpoint.
      * @default 2
      */
     maxRetries?: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@rawcast/sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Official TypeScript/JavaScript SDK for Rawcast Media Resolution API",
   "author": "Rawcast Team",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",