scavio 0.21.1 → 0.22.0

package/README.md

@@ -356,7 +356,7 @@ nickname, or a listing with no public questions, is a billed 404.
 
 ### YouTube
 
-Credit cost varies by endpoint: `transcript` costs 8; `streams` costs 3;
+Credit cost varies by endpoint: `transcript` costs 5; `streams` costs 3;
 `search` and `shorts` cost 2; every other YouTube endpoint costs 1.
 
 ```typescript
@@ -402,6 +402,10 @@ 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
+
+// One community post (text, author, likes, images, comments_cursor) and its comments
+await client.youtube.communityPost({ post_id: "Ugkx_PqHZYEoCCP7e8WIOrh-1HCvtKoFMzVp" });
+await client.youtube.communityPostComments({ post_id: "Ugkx_PqHZYEoCCP7e8WIOrh-1HCvtKoFMzVp" });
 ```
 
 ### Reddit
@@ -409,7 +413,8 @@ await client.youtube.channelResolve({ channel: "@mkbhd" }); // handle/URL -> id
 Every Reddit endpoint costs 1 credit.
 
 `search()` takes only `query` and `cursor` — there is no result-type or sort
-filter, so anything else is dropped server-side. It returns
+filter, so anything else is dropped server-side. `searchComments()` does sort
+(`RELEVANCE`, `HOT`, `TOP` or `NEW`). It returns
 `data.results` with `next_cursor` and `has_more`. `post()` returns a flat post
 object under `data` and carries no comments; use `postComments()` for those.
 The subreddit and user feeds return `data.posts`.
@@ -444,6 +449,10 @@ await client.reddit.userComments({ username: "spez" });
 // Site-wide popular feed and trending searches
 await client.reddit.popular();
 await client.reddit.trending();
+
+// Comment search (each result carries its post and subreddit) and subreddit search
+await client.reddit.searchComments({ query: "web scraping api", sort: "NEW" });
+await client.reddit.searchSubreddits({ query: "web scraping" });
 ```
 
 ### X
@@ -467,8 +476,15 @@ await client.x.userFollowings({ screen_name: "elonmusk" });
 
 // Trending topics
 await client.x.trending({ country: "UnitedStates" });
+
+// Communities: search, details (rules, member count), and posts
+await client.x.searchCommunities({ keyword: "crypto" });
+await client.x.community({ community_id: "1508567430188126209" });
+await client.x.communityTweets({ community_id: "1508567430188126209", ranking: "Recency" });
 ```
 
+Every X endpoint costs 1 credit.
+
 ### LinkedIn
 
 ```typescript
@@ -541,8 +557,39 @@ await client.tiktok.userFollowers({ sec_user_id: "abc123" });
 
 // User followings
 await client.tiktok.userFollowings({ sec_user_id: "abc123" });
+
+// Trending searches and a sample of trending videos (about 6 per call)
+await client.tiktok.trendingSearches();
+await client.tiktok.trendingVideos();
+
+// Search autocomplete
+await client.tiktok.searchSuggestions({ keyword: "cooking" });
+
+// Sounds: detail, videos using a sound, search, Top 50 / Viral 50 chart
+await client.tiktok.music({ music_id: "7364498342501435408" });
+await client.tiktok.musicVideos({ music_id: "7364498342501435408" });
+await client.tiktok.searchMusic({ keyword: "espresso" });
+await client.tiktok.musicChart({ chart: "viral" });
+
+// Similar creators, playlists and the videos in one
+await client.tiktok.userSimilar({ sec_user_id: "abc123" });
+await client.tiktok.userPlaylists({ sec_user_id: "abc123" });
+await client.tiktok.playlistVideos({ playlist_id: "7596415294902389534" });
+
+// Live status and account region (region also returns sec_user_id)
+await client.tiktok.userLive({ username: "mrbeast" });
+await client.tiktok.userRegion({ username: "mrbeast" });
 ```
 
+Every TikTok endpoint costs 1 credit. The trending, sound, similar, playlist,
+live and region endpoints return TikTok's raw payload: large numeric ids can
+lose precision when parsed as JSON numbers, so use the string forms (`id_str`,
+`sec_uid`, `sec_user_id`). `trendingVideos()` returns about 6 videos per call
+whatever `count` is set to, and `musicVideos()` ignores `count` (about 14 per
+page). Search suggestions can be empty for long-tail keywords and still bill.
+An unknown username is a billed 404 on `userLive()` and an unbilled 404 on
+`userRegion()`.
+
 ### TikTok Shop
 
 Every TikTok Shop endpoint costs 1 credit. Two limits to design around:

package/dist/index.cjs

@@ -203,7 +203,7 @@ function parseRetryAfter(header) {
 var BASE_URL = "https://api.scavio.dev";
 var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 2;
-var SDK_VERSION = true ? "0.21.1" : "0.0.0";
+var SDK_VERSION = true ? "0.22.0" : "0.0.0";
 var USER_AGENT = `scavio-js/${SDK_VERSION}`;
 function isServerRuntime() {
   const g = globalThis;
@@ -493,6 +493,21 @@ var RedditNamespace = class {
   async trending() {
     return this.client._post("/api/v1/reddit/trending", {});
   }
+  /**
+   * Search Reddit comments by keyword. Each result carries the comment text,
+   * author, score and date, plus the post and subreddit it was left on.
+   * Costs 1 credit.
+   */
+  async searchComments(options) {
+    return this.client._post("/api/v1/reddit/search/comments", options);
+  }
+  /**
+   * Find subreddits by keyword, with subscriber counts, descriptions and NSFW
+   * flags. Costs 1 credit.
+   */
+  async searchSubreddits(options) {
+    return this.client._post("/api/v1/reddit/search/subreddits", options);
+  }
 };
 
 // src/namespaces/tiktok.ts
@@ -534,6 +549,107 @@ var TikTokNamespace = class {
   async userFollowings(options) {
     return this.client._post("/api/v1/tiktok/user/followings", options);
   }
+  /**
+   * Search terms trending on TikTok now (about 90 per call, US-weighted, no
+   * region filter). Costs 1 credit.
+   */
+  async trendingSearches() {
+    return this.client._post("/api/v1/tiktok/trending/searches", {});
+  }
+  /**
+   * A sample of videos trending on TikTok now, with author, stats, sound and
+   * hashtags. Each call returns about 6 videos whatever `count` is set to;
+   * call again for a fresh sample. No region filter. Costs 1 credit.
+   * Returns TikTok's raw payload: large numeric ids can lose precision as JSON
+   * numbers, so use the string forms (`id_str`, `sec_uid`).
+   */
+  async trendingVideos(options = {}) {
+    return this.client._post("/api/v1/tiktok/trending/videos", options);
+  }
+  /**
+   * TikTok search autocomplete suggestions for a keyword. Long-tail keywords
+   * can return none, which is still a billed answer. Costs 1 credit.
+   */
+  async searchSuggestions(options) {
+    return this.client._post("/api/v1/tiktok/search/suggestions", options);
+  }
+  /**
+   * A TikTok sound by id: title, artist, album, duration, how many videos use
+   * it, original vs commercial, play URL, cover, and chart rank when charting.
+   * Costs 1 credit.
+   * Returns TikTok's raw payload: large numeric ids can lose precision as JSON
+   * numbers, so use the string forms (`id_str`, `sec_uid`).
+   */
+  async music(options) {
+    return this.client._post("/api/v1/tiktok/music", options);
+  }
+  /**
+   * Videos that use a TikTok sound, about 14 per page (`count` is ignored
+   * upstream). Costs 1 credit.
+   * Returns TikTok's raw payload: large numeric ids can lose precision as JSON
+   * numbers, so use the string forms (`id_str`, `sec_uid`).
+   */
+  async musicVideos(options) {
+    return this.client._post("/api/v1/tiktok/music/videos", options);
+  }
+  /**
+   * Search TikTok sounds by keyword: id, title, artist, duration, usage count
+   * and play URL. Costs 1 credit.
+   * Returns TikTok's raw payload: large numeric ids can lose precision as JSON
+   * numbers, so use the string forms (`id_str`, `sec_uid`).
+   */
+  async searchMusic(options) {
+    return this.client._post("/api/v1/tiktok/search/music", options);
+  }
+  /**
+   * TikTok's Top 50 or Viral 50 sound chart, with each sound's details and
+   * trend. One global chart, no region filter. Costs 1 credit.
+   * Returns TikTok's raw payload: large numeric ids can lose precision as JSON
+   * numbers, so use the string forms (`id_str`, `sec_uid`).
+   */
+  async musicChart(options = {}) {
+    return this.client._post("/api/v1/tiktok/music/chart", options);
+  }
+  /**
+   * Creators similar to a TikTok user (about 30 per page), with follower,
+   * following, video and like counts, bio and verification. Costs 1 credit.
+   * Returns TikTok's raw payload: large numeric ids can lose precision as JSON
+   * numbers, so use the string forms (`id_str`, `sec_uid`).
+   */
+  async userSimilar(options) {
+    return this.client._post("/api/v1/tiktok/user/similar", options);
+  }
+  /**
+   * A TikTok user's playlists (series): id, name, video count and cover.
+   * Accounts without playlists return an empty list. Costs 1 credit.
+   */
+  async userPlaylists(options) {
+    return this.client._post("/api/v1/tiktok/user/playlists", options);
+  }
+  /**
+   * Videos in a TikTok playlist, with pagination. Costs 1 credit.
+   * Returns TikTok's raw payload: large numeric ids can lose precision as JSON
+   * numbers, so use the string forms (`id_str`, `sec_uid`).
+   */
+  async playlistVideos(options) {
+    return this.client._post("/api/v1/tiktok/playlist/videos", options);
+  }
+  /**
+   * Whether a TikTok user is live now: the user, live room status (2 = live,
+   * 4 = not live), title, start time and viewer counts. An unknown username is
+   * a billed 404. Costs 1 credit.
+   */
+  async userLive(options) {
+    return this.client._post("/api/v1/tiktok/user/live", options);
+  }
+  /**
+   * The region a TikTok account is registered in (ISO country code, not the
+   * creator's nationality), plus its user id and sec_user_id. An unknown
+   * username is a 404 and is not billed. Costs 1 credit.
+   */
+  async userRegion(options) {
+    return this.client._post("/api/v1/tiktok/user/region", options);
+  }
 };
 
 // src/namespaces/tiktok-shop.ts
@@ -826,6 +942,7 @@ var YouTubeNamespace = class {
   async commentReplies(options) {
     return this.client._post("/api/v1/youtube/comments/replies", options);
   }
+  /** Transcript / captions for a YouTube video. Costs 5 credits. */
   async transcript(options) {
     return this.client._post("/api/v1/youtube/transcript", options);
   }
@@ -857,6 +974,21 @@ var YouTubeNamespace = class {
   async streams(options) {
     return this.client._post("/api/v1/youtube/streams", options);
   }
+  /**
+   * A single YouTube community post: text, author, likes, comment count,
+   * attached images, and a comments_cursor for communityPostComments.
+   * Costs 1 credit.
+   */
+  async communityPost(options) {
+    return this.client._post("/api/v1/youtube/community/post", options);
+  }
+  /**
+   * Comments on a YouTube community post, with likes, reply counts and
+   * pagination. Costs 1 credit.
+   */
+  async communityPostComments(options) {
+    return this.client._post("/api/v1/youtube/community/post/comments", options);
+  }
 };
 
 // src/namespaces/x.ts
@@ -898,6 +1030,27 @@ var XNamespace = class {
   async trending(options = {}) {
     return this.client._post("/api/v1/x/trending", options);
   }
+  /**
+   * Find X Communities by keyword, with member counts, topic and NSFW flag.
+   * Costs 1 credit.
+   */
+  async searchCommunities(options) {
+    return this.client._post("/api/v1/x/search/communities", options);
+  }
+  /**
+   * An X Community: name, description, creation date, member count, topic and
+   * rules. Costs 1 credit.
+   */
+  async community(options) {
+    return this.client._post("/api/v1/x/community", options);
+  }
+  /**
+   * Posts in an X Community, by relevance or recency, with pagination.
+   * Costs 1 credit.
+   */
+  async communityTweets(options) {
+    return this.client._post("/api/v1/x/community/tweets", options);
+  }
 };
 
 // src/namespaces/linkedin.ts