scavio 0.4.0 → 0.6.0

package/README.md

@@ -104,15 +104,45 @@ await client.walmart.product({
 // Search videos
 await client.youtube.search({
   query: "typescript tutorial",
-  upload_date: "week",     // optional
-  sort_by: "relevance",   // optional
-  hd: true,                // optional
+  upload_date: "this_week",       // optional
+  sort_by: "relevance",           // optional
+  features: ["hd", "4k"],         // optional
+  cursor: "...",                  // optional (pagination)
 });
 
-// Get video metadata
-await client.youtube.metadata({
+// Search Shorts
+await client.youtube.shorts({ query: "cooking" });
+
+// Search-as-you-type suggestions
+await client.youtube.suggestions({ query: "how to" });
+
+// Get video details (accepts an id or a full watch URL)
+await client.youtube.video({ video_id: "dQw4w9WgXcQ" });
+// youtube.metadata() is a deprecated alias of youtube.video()
+
+// Video comments and threaded replies
+await client.youtube.comments({ video_id: "dQw4w9WgXcQ" });
+await client.youtube.commentReplies({
   video_id: "dQw4w9WgXcQ",
+  reply_cursor: "...",            // from a comment's reply_cursor
 });
+
+// Transcript / subtitles (format: 'text' or 'srt')
+await client.youtube.transcript({ video_id: "dQw4w9WgXcQ", format: "srt" });
+
+// Related videos
+await client.youtube.related({ video_id: "dQw4w9WgXcQ" });
+
+// Playable / downloadable stream URLs
+await client.youtube.streams({ video_id: "dQw4w9WgXcQ" });
+
+// Channels
+await client.youtube.channelSearch({ query: "mkbhd" });
+await client.youtube.channel({ channel_id: "@mkbhd" }); // id, @handle, or URL
+await client.youtube.channelVideos({ channel_id: "UC..." });
+await client.youtube.channelShorts({ channel_id: "UC..." });
+await client.youtube.channelCommunity({ channel_id: "UC..." });
+await client.youtube.channelResolve({ channel: "@mkbhd" }); // handle/URL -> id
 ```
 
 ### Reddit
@@ -246,11 +276,13 @@ MIT
 
 ## About Scavio
 
-[Scavio](https://scavio.dev) is a unified [search API](https://scavio.dev/docs/search-api) built for AI agents — one API key, structured JSON, no scraping or proxies. A real-time [Tavily alternative](https://scavio.dev) and [SerpAPI alternative](https://scavio.dev) with data from:
+[Scavio](https://scavio.dev) is a unified [search API for AI agents](https://scavio.dev/search-api-for-ai-agents) — one API key, structured JSON, no scraping or proxies. A real-time [Tavily alternative](https://scavio.dev/alternatives/tavily) and [SerpAPI alternative](https://scavio.dev/alternatives/serpapi) with data from:
+
+- [Google Search API](https://scavio.dev/google-search-api) — SERP results, news, images, maps, and knowledge graph
+- [Amazon Product API](https://scavio.dev/amazon-product-api) and [Walmart Product API](https://scavio.dev/walmart-product-api) — product search and details
+- [YouTube API](https://scavio.dev/youtube-transcript-api), [TikTok API](https://scavio.dev/tiktok-api), and [Instagram API](https://scavio.dev/instagram-api) — video and social media data
+- [Reddit API](https://scavio.dev/reddit-api) — posts and threaded comments
 
-- [Google Search API](https://scavio.dev/docs/search-api) — SERP results, news, images, maps, and knowledge graph
-- [Amazon Product API](https://scavio.dev/docs/amazon-api) and [Walmart API](https://scavio.dev/docs/walmart-api) — product search and details
-- [YouTube API](https://scavio.dev/docs/youtube-api), [TikTok API](https://scavio.dev/docs/tiktok-api), and [Instagram API](https://scavio.dev/docs/instagram-api) — video and social media data
-- [Reddit API](https://scavio.dev/docs/reddit-api) — posts and threaded comments
+Teams choosing between providers can [compare Scavio vs alternatives](https://scavio.dev/compare) side by side.
 
 Get a free [API key](https://dashboard.scavio.dev) and explore the [documentation](https://scavio.dev/docs/introduction).

package/dist/index.cjs

@@ -24,10 +24,13 @@ __export(index_exports, {
   InsufficientCreditsError: () => InsufficientCreditsError,
   InvalidAPIKeyError: () => InvalidAPIKeyError,
   MissingAPIKeyError: () => MissingAPIKeyError,
+  NotFoundError: () => NotFoundError,
   RateLimitError: () => RateLimitError,
   Scavio: () => Scavio,
   ScavioAPIError: () => ScavioAPIError,
-  ScavioError: () => ScavioError
+  ScavioConnectionError: () => ScavioConnectionError,
+  ScavioError: () => ScavioError,
+  ScavioTimeoutError: () => ScavioTimeoutError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -46,42 +49,121 @@ var MissingAPIKeyError = class extends ScavioError {
     this.name = "MissingAPIKeyError";
   }
 };
+var ScavioConnectionError = class extends ScavioError {
+  constructor(message = "Connection error") {
+    super(message);
+    this.name = "ScavioConnectionError";
+  }
+};
+var ScavioTimeoutError = class extends ScavioError {
+  constructor(message = "Request timed out") {
+    super(message);
+    this.name = "ScavioTimeoutError";
+  }
+};
 var InvalidAPIKeyError = class extends ScavioError {
-  constructor(message = "Invalid API key") {
+  statusCode = 401;
+  responseBody;
+  constructor(message = "Invalid API key", responseBody) {
     super(message);
     this.name = "InvalidAPIKeyError";
+    this.responseBody = responseBody;
   }
 };
 var InsufficientCreditsError = class extends ScavioError {
-  constructor(message = "Insufficient credits") {
+  statusCode = 402;
+  responseBody;
+  constructor(message = "Insufficient credits", responseBody) {
     super(message);
     this.name = "InsufficientCreditsError";
+    this.responseBody = responseBody;
   }
 };
 var BadRequestError = class extends ScavioError {
-  constructor(message = "Bad request") {
+  statusCode = 400;
+  responseBody;
+  constructor(message = "Bad request", responseBody) {
     super(message);
     this.name = "BadRequestError";
+    this.responseBody = responseBody;
+  }
+};
+var NotFoundError = class extends ScavioError {
+  statusCode = 404;
+  responseBody;
+  constructor(message = "Not found", responseBody) {
+    super(message);
+    this.name = "NotFoundError";
+    this.responseBody = responseBody;
   }
 };
 var RateLimitError = class extends ScavioError {
-  constructor(message = "Rate limit exceeded") {
+  statusCode = 429;
+  responseBody;
+  constructor(message = "Rate limit exceeded", responseBody) {
     super(message);
     this.name = "RateLimitError";
+    this.responseBody = responseBody;
   }
 };
 var ScavioAPIError = class extends ScavioError {
   statusCode;
-  constructor(statusCode, message) {
+  responseBody;
+  constructor(statusCode, message, responseBody) {
     super(`API error ${statusCode}: ${message}`);
     this.name = "ScavioAPIError";
     this.statusCode = statusCode;
+    this.responseBody = responseBody;
   }
 };
 
+// src/retry.ts
+var DEFAULT_RETRY_STATUSES = /* @__PURE__ */ new Set([
+  429,
+  500,
+  502,
+  503,
+  504
+]);
+function makeRetryConfig(maxRetries) {
+  return {
+    maxRetries,
+    baseDelay: 0.5,
+    maxDelay: 8,
+    retryStatuses: DEFAULT_RETRY_STATUSES
+  };
+}
+function shouldRetryStatus(config, statusCode, attempt) {
+  return attempt < config.maxRetries && config.retryStatuses.has(statusCode);
+}
+function shouldRetryException(config, attempt) {
+  return attempt < config.maxRetries;
+}
+function backoff(config, attempt, retryAfter) {
+  if (retryAfter !== void 0) {
+    return Math.min(Math.max(retryAfter, 0), config.maxDelay);
+  }
+  const capped = Math.min(config.maxDelay, config.baseDelay * 2 ** attempt);
+  return Math.random() * capped;
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const trimmed = header.trim();
+  const asNumber = Number(trimmed);
+  if (!Number.isNaN(asNumber) && trimmed !== "") {
+    return asNumber;
+  }
+  const asDate = Date.parse(trimmed);
+  if (!Number.isNaN(asDate)) {
+    return Math.max((asDate - Date.now()) / 1e3, 0);
+  }
+  return void 0;
+}
+
 // src/http.ts
 var BASE_URL = "https://api.scavio.dev";
 var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 2;
 function buildHeaders(apiKey) {
   return {
     Authorization: `Bearer ${apiKey}`,
@@ -104,39 +186,80 @@ function handleError(statusCode, body) {
     error = error.message;
   }
   const msg = String(error);
-  if (statusCode === 400) throw new BadRequestError(msg);
-  if (statusCode === 401) throw new InvalidAPIKeyError(msg);
-  if (statusCode === 402) throw new InsufficientCreditsError(msg);
-  if (statusCode === 429) throw new RateLimitError(msg);
-  throw new ScavioAPIError(statusCode, msg);
+  const responseBody = Object.keys(body).length > 0 ? body : void 0;
+  if (statusCode === 400) throw new BadRequestError(msg, responseBody);
+  if (statusCode === 401) throw new InvalidAPIKeyError(msg, responseBody);
+  if (statusCode === 402) throw new InsufficientCreditsError(msg, responseBody);
+  if (statusCode === 404) throw new NotFoundError(msg, responseBody);
+  if (statusCode === 429) throw new RateLimitError(msg, responseBody);
+  throw new ScavioAPIError(statusCode, msg, responseBody);
+}
+function sleep(seconds) {
+  return new Promise((resolve) => setTimeout(resolve, seconds * 1e3));
+}
+function isAbortError(err) {
+  return err instanceof Error && (err.name === "AbortError" || err.name === "TimeoutError");
+}
+function getHeader(response, name) {
+  const headers = response.headers;
+  if (headers && typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  return null;
 }
 async function request(options) {
-  await options.rateLimiter.wait();
   const url = `${options.baseUrl}${options.path}`;
   const headers = buildHeaders(options.apiKey);
-  const controller = new AbortController();
-  const timeoutId = setTimeout(() => controller.abort(), options.timeout);
-  try {
-    const fetchOptions = {
-      method: options.method,
-      headers,
-      signal: controller.signal
-    };
-    if (options.method === "POST" && options.body) {
-      fetchOptions.body = JSON.stringify(stripUndefined(options.body));
-    }
-    const response = await fetch(url, fetchOptions);
-    if (!response.ok) {
-      let body = {};
-      try {
-        body = await response.json();
-      } catch {
+  const retry = makeRetryConfig(
+    options.maxRetries ?? DEFAULT_MAX_RETRIES
+  );
+  let attempt = 0;
+  for (; ; ) {
+    await options.rateLimiter.wait();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), options.timeout);
+    let response;
+    try {
+      const fetchOptions = {
+        method: options.method,
+        headers,
+        signal: controller.signal
+      };
+      if (options.method === "POST" && options.body) {
+        fetchOptions.body = JSON.stringify(stripUndefined(options.body));
+      }
+      response = await fetch(url, fetchOptions);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      const timedOut = isAbortError(err);
+      if (shouldRetryException(retry, attempt)) {
+        await sleep(backoff(retry, attempt));
+        attempt += 1;
+        continue;
+      }
+      const msg = err instanceof Error ? err.message : String(err);
+      if (timedOut) {
+        throw new ScavioTimeoutError(msg);
       }
-      handleError(response.status, body);
+      throw new ScavioConnectionError(msg);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    if (response.ok) {
+      return await response.json();
+    }
+    if (shouldRetryStatus(retry, response.status, attempt)) {
+      const retryAfter = parseRetryAfter(getHeader(response, "Retry-After"));
+      await sleep(backoff(retry, attempt, retryAfter));
+      attempt += 1;
+      continue;
+    }
+    let body = {};
+    try {
+      body = await response.json();
+    } catch {
     }
-    return await response.json();
-  } finally {
-    clearTimeout(timeoutId);
+    handleError(response.status, body);
   }
 }
 
@@ -188,6 +311,10 @@ var AmazonNamespace = class {
       ...rest
     });
   }
+  /** Supported Amazon domains, languages, currencies, and countries. */
+  async options() {
+    return this.client._get("/api/v1/amazon/options");
+  }
 };
 
 // src/namespaces/google.ts
@@ -374,14 +501,73 @@ var YouTubeNamespace = class {
   }
   client;
   async search(options) {
+    const { query, fourK, video_360, video_3d, ...rest } = options;
+    const body = {
+      search: query,
+      ...rest
+    };
+    if (fourK !== void 0) body["4k"] = fourK;
+    if (video_360 !== void 0) body["360"] = video_360;
+    if (video_3d !== void 0) body["3d"] = video_3d;
+    return this.client._post("/api/v1/youtube/search", body);
+  }
+  async shorts(options) {
+    const { query, ...rest } = options;
+    return this.client._post("/api/v1/youtube/shorts", {
+      search: query,
+      ...rest
+    });
+  }
+  async suggestions(options) {
     const { query, ...rest } = options;
-    return this.client._post("/api/v1/youtube/search", {
+    return this.client._post("/api/v1/youtube/suggestions", {
       search: query,
       ...rest
     });
   }
+  async video(options) {
+    return this.client._post("/api/v1/youtube/video", options);
+  }
+  /** @deprecated Use youtube.video(). Alias kept for backward compatibility. */
   async metadata(options) {
-    return this.client._post("/api/v1/youtube/metadata", options);
+    return this.video(options);
+  }
+  async comments(options) {
+    return this.client._post("/api/v1/youtube/comments", options);
+  }
+  async commentReplies(options) {
+    return this.client._post("/api/v1/youtube/comments/replies", options);
+  }
+  async transcript(options) {
+    return this.client._post("/api/v1/youtube/transcript", options);
+  }
+  async related(options) {
+    return this.client._post("/api/v1/youtube/related", options);
+  }
+  async channelSearch(options) {
+    const { query, ...rest } = options;
+    return this.client._post("/api/v1/youtube/channel/search", {
+      search: query,
+      ...rest
+    });
+  }
+  async channel(options) {
+    return this.client._post("/api/v1/youtube/channel", options);
+  }
+  async channelVideos(options) {
+    return this.client._post("/api/v1/youtube/channel/videos", options);
+  }
+  async channelShorts(options) {
+    return this.client._post("/api/v1/youtube/channel/shorts", options);
+  }
+  async channelCommunity(options) {
+    return this.client._post("/api/v1/youtube/channel/community", options);
+  }
+  async channelResolve(options) {
+    return this.client._post("/api/v1/youtube/channel/resolve", options);
+  }
+  async streams(options) {
+    return this.client._post("/api/v1/youtube/streams", options);
   }
 };
 
@@ -397,6 +583,7 @@ var Scavio = class {
   apiKey;
   baseUrl;
   timeout;
+  maxRetries;
   rateLimiter;
   constructor(config) {
     this.apiKey = config?.apiKey ?? process.env.SCAVIO_API_KEY ?? "";
@@ -405,6 +592,7 @@ var Scavio = class {
     }
     this.baseUrl = (config?.baseUrl ?? BASE_URL).replace(/\/+$/, "");
     this.timeout = config?.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = config?.maxRetries ?? DEFAULT_MAX_RETRIES;
     const rps = config?.maxRequestsPerSecond ?? 1;
     if (rps < 1 || rps > 10) {
       throw new ScavioError("maxRequestsPerSecond must be between 1 and 10");
@@ -426,6 +614,7 @@ var Scavio = class {
       apiKey: this.apiKey,
       baseUrl: this.baseUrl,
       timeout: this.timeout,
+      maxRetries: this.maxRetries,
       rateLimiter: this.rateLimiter,
       body
     });
@@ -438,6 +627,7 @@ var Scavio = class {
       apiKey: this.apiKey,
       baseUrl: this.baseUrl,
       timeout: this.timeout,
+      maxRetries: this.maxRetries,
       rateLimiter: this.rateLimiter
     });
   }
@@ -454,9 +644,12 @@ var Scavio = class {
   InsufficientCreditsError,
   InvalidAPIKeyError,
   MissingAPIKeyError,
+  NotFoundError,
   RateLimitError,
   Scavio,
   ScavioAPIError,
-  ScavioError
+  ScavioConnectionError,
+  ScavioError,
+  ScavioTimeoutError
 });
 //# sourceMappingURL=index.cjs.map