mastra-scavio 0.7.1 → 0.7.3

package/README.md

@@ -2,7 +2,7 @@
 
 [Scavio](https://scavio.dev) real-time data tools for [Mastra](https://mastra.ai) agents — **188 tools across 31 platforms** on one API key. Retail (Amazon, Walmart, eBay, Target, Home Depot), real estate (Zillow, Redfin), travel (Booking.com, Airbnb, Tripadvisor), local (Yelp, Google Maps), jobs (Indeed, Glassdoor, LinkedIn), software reviews (G2, Capterra), app stores (App Store, Google Play), company filings (SEC EDGAR, Companies House), ad libraries (Google Ads Transparency, Meta Ad Library), search (Google) and social (YouTube, TikTok, Instagram, X, Reddit, Threads, Kuaishou) — plus `scavioExtract`, which reads any URL as clean Markdown, and five opt-in tools that map a site's URLs, crawl a whole site or batch-extract a URL list.
 
-> **Amazon changed (breaking).** The upstream provider moved in 2026-07:
+> **Amazon changed (breaking).** The Amazon endpoint changed in 2026-07:
 > `domain` is replaced by `country`, a two-letter marketplace code (`us`, `gb`
 > -- the UK is `gb`, not `uk` -- `de`, `jp`, ...), and `sort_by`, `pages`,
 > `category_id`, `merchant_id`, `language`, `currency`, `device`, `zip_code`
@@ -204,11 +204,10 @@ Most calls cost 1 credit. Every tool states its own cost in its description, so
 | `scavioLinkedinPerson`, `scavioLinkedinPersonAbout`, `scavioLinkedinCompany`, `scavioLinkedinPost` | 1 |
 | `scavioLinkedinPersonPosts`, `scavioLinkedinCompanyPosts`, `scavioLinkedinSearchJobs`, `scavioLinkedinPostComments` | 10 |
 | `scavioLinkedinJob` | 30 |
-| `scavioInstagramUserPosts` | 2 |
-| `scavioInstagramPost`, `scavioInstagramCommentReplies` | 8 |
-| All other Instagram tools | 10 |
+| `scavioInstagramProfile`, `scavioInstagramUserReels`, `scavioInstagramUserTagged` | 1 |
+| All other Instagram tools | 2 |
 
-Instagram is priced per endpoint rather than flat, on three tiers: 10 where both upstream legs are billed, 8 for the two calls with no fallback leg to hedge (`scavioInstagramPost`, `scavioInstagramCommentReplies`), and 2 for `scavioInstagramUserPosts`, whose cheap leg is the primary one. Prefer `scavioInstagramUserPosts` over `scavioInstagramUserReels` when the timeline will do — same shape of data, one fifth of the cost. Paginated tools bill per page. See [scavio.dev/docs](https://scavio.dev/docs).
+Instagram is priced per endpoint rather than flat: profile, reels and tagged 1 credit (reels and tagged 2 the first time a username is looked up), every other Instagram tool 2, and the user and hashtag searches 8 when called with a `cursor`. Any Instagram request can cost up to 10 when it needs extra work; `credits_used` in the response is the exact charge. Paginated tools bill per page. See [scavio.dev/docs](https://scavio.dev/docs).
 
 ### These surfaces are priced by the request body
 
@@ -217,7 +216,7 @@ No single number is true for these, so each tool states its own price and none o
 | Surface | Price |
 |---|---|
 | `scavioWalmartSearch`, `scavioWalmartCategory` | 1 credit on `domain` `com` or `ca`, **2 on `com.mx`**. The other five Walmart tools take no `domain` and are always 1. |
-| `scavioThreadsProfile`, `scavioThreadsUserPosts`, `scavioThreadsUserReplies` | **2 credits addressed by `user_id`, 4 by `username`** — a handle buys a second upstream call, because the upstream handle lookup is dead. Pass `user_id` whenever you have it. The other three Threads tools have no username form and are always 2. |
+| `scavioThreadsProfile`, `scavioThreadsUserPosts`, `scavioThreadsUserReplies` | **2 credits addressed by `user_id`, 4 by `username`** — a handle buys a second lookup. Pass `user_id` whenever you have it. The other three Threads tools have no username form and are always 2. |
 | Kuaishou | **Per endpoint, 1 to 40.** See the table above; one platform-wide figure would be wrong by up to 40x. |
 | `scavioExtract` | 1 credit on `mode` `normal` or `advanced`, **2 on `ultra`**. Only a successful extraction is billed — a dead link, bot wall or timeout costs nothing. |
 | `scavioMapWebsite` | 1 credit on `mode` `normal`; up to 2 on `advanced`, up to 10 on `ultra`, priced by what the call needed. |

package/dist/index.cjs

@@ -1461,8 +1461,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-profile",
     platform: "instagram",
     endpoint: "/api/v1/instagram/profile",
-    credits: 10,
-    description: "Fetch an Instagram profile via Scavio (10 credits). The profile is inlined at the root of data - pk, username, full_name, biography, follower_count, following_count, is_private, is_verified, profile_pic_url - with no data.user wrapper. Provide username or user_id.",
+    credits: 1,
+    description: "Fetch an Instagram profile via Scavio (1 credit). The profile is inlined at the root of data - pk, username, full_name, biography, follower_count, following_count, is_private, is_verified, profile_pic_url - with no data.user wrapper. Provide username or user_id.",
     inputSchema: import_zod8.z.object({ username: username2, user_id: userId }),
     call: (client, input) => client.instagram.profile(input)
   }),
@@ -1472,7 +1472,7 @@ var instagramToolSpecs = [
     platform: "instagram",
     endpoint: "/api/v1/instagram/user/posts",
     credits: 2,
-    description: "Fetch an account's Instagram timeline posts via Scavio (2 credits - the cheapest Instagram tool by 5x, because its primary upstream leg is the cheap one). Items usually arrive at data.data with data.pagination_token; a fallback leg answers with data.items and next_max_id instead, so read both. Prefer this over the reels and tagged tools when you just need recent media.",
+    description: "Fetch an account's Instagram timeline posts via Scavio (2 credits per page). Items arrive at data.data; pass data.pagination_token as cursor for the next page. Use it when you need the whole timeline; the reels tool is cheaper (1 credit) when reels alone will do.",
     inputSchema: import_zod8.z.object({ username: username2, user_id: userId, count: feedCount, cursor: cursor5 }),
     call: (client, input) => client.instagram.userPosts(input)
   }),
@@ -1481,8 +1481,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-user-reels",
     platform: "instagram",
     endpoint: "/api/v1/instagram/user/reels",
-    credits: 10,
-    description: "Fetch an account's Instagram reels via Scavio (10 credits). Returns data.items with data.next_max_id. Five times the price of scavio-instagram-user-posts, so use it only when you specifically need reels rather than the timeline.",
+    credits: 1,
+    description: "Fetch an account's Instagram reels via Scavio (1 credit; 2 the first time a username is looked up). Returns data.items with data.next_max_id.",
     inputSchema: import_zod8.z.object({ username: username2, user_id: userId, count: feedCount, cursor: cursor5 }),
     call: (client, input) => client.instagram.userReels(input)
   }),
@@ -1491,8 +1491,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-user-tagged",
     platform: "instagram",
     endpoint: "/api/v1/instagram/user/tagged",
-    credits: 10,
-    description: "Fetch the posts an Instagram account is tagged in via Scavio (10 credits). Returns data.items with data.more_available and data.next_max_id. This is other accounts posting about them - use it for brand mentions and creator collaborations, not for their own feed.",
+    credits: 1,
+    description: "Fetch the posts an Instagram account is tagged in via Scavio (1 credit; 2 the first time a username is looked up). Returns data.items with data.next_max_id. Video items carry video_url null - fetch the video with scavio-instagram-post. This is other accounts posting about them - use it for brand mentions and creator collaborations, not for their own feed.",
     inputSchema: import_zod8.z.object({ username: username2, user_id: userId, count: feedCount, cursor: cursor5 }),
     call: (client, input) => client.instagram.userTagged(input)
   }),
@@ -1501,8 +1501,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-user-stories",
     platform: "instagram",
     endpoint: "/api/v1/instagram/user/stories",
-    credits: 10,
-    description: "Fetch an Instagram account's currently active stories via Scavio (10 credits). Returns data.items and data.reels. Stories expire after 24 hours and there is no pagination here - no count, no cursor. Provide username or user_id.",
+    credits: 2,
+    description: "Fetch an Instagram account's currently active stories via Scavio (2 credits). Returns data.items and data.reels. Stories expire after 24 hours and there is no pagination here - no count, no cursor. Provide username or user_id.",
     inputSchema: import_zod8.z.object({ username: username2, user_id: userId }),
     call: (client, input) => client.instagram.userStories(input)
   }),
@@ -1511,8 +1511,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-post",
     platform: "instagram",
     endpoint: "/api/v1/instagram/post",
-    credits: 8,
-    description: "Fetch one Instagram post via Scavio (8 credits - cheaper than most Instagram tools because there is no fallback leg to hedge). The post is data.items[0]: caption, like_count, comment_count, media_type (1 image, 2 video, 8 carousel), video_versions[].url for video and image_versions2.candidates for the cover. It also carries the media_id that scavio-instagram-comment-replies requires. Provide url, media_id or shortcode.",
+    credits: 2,
+    description: "Fetch one Instagram post via Scavio (2 credits). The post is data.items[0]: caption, like_count, comment_count, media_type (1 image, 2 video, 8 carousel), video_versions[].url for video and image_versions2.candidates for the cover. It also carries the media_id that scavio-instagram-comment-replies requires. Provide url, media_id or shortcode.",
     inputSchema: import_zod8.z.object({
       url: import_zod8.z.string().optional().describe("Full Instagram post URL."),
       media_id: import_zod8.z.string().optional().describe("Instagram media id. Highest precedence - url and shortcode are ignored with it."),
@@ -1525,13 +1525,13 @@ var instagramToolSpecs = [
     id: "scavio-instagram-post-comments",
     platform: "instagram",
     endpoint: "/api/v1/instagram/post/comments",
-    credits: 10,
-    description: "Fetch the comments on an Instagram post via Scavio (10 credits). Returns data.comments with data.comment_count, data.has_more_comments and data.next_min_id. Identify the post by shortcode or url ONLY - media_id is not accepted here, unlike the post and replies tools.",
+    credits: 2,
+    description: "Fetch the comments on an Instagram post via Scavio (2 credits per page). Returns data.comments with data.comment_count, data.has_more_comments and data.next_min_id. Identify the post by shortcode or url ONLY - media_id is not accepted here, unlike the post and replies tools.",
     inputSchema: import_zod8.z.object({
       shortcode: import_zod8.z.string().optional().describe("Shortcode from the post URL, e.g. 'DUajw4YkorV'."),
       url: import_zod8.z.string().optional().describe("Full Instagram post URL. It is parsed down to the shortcode, so /p/, /reel/ and /tv/ links work and others fail."),
       cursor: cursor5,
-      sort_order: import_zod8.z.enum(["popular", "newest"]).optional().describe("popular (default) or newest. A fallback leg can silently ignore it.")
+      sort_order: import_zod8.z.enum(["popular", "newest"]).optional().describe("popular (default) or newest.")
     }),
     call: (client, input) => client.instagram.postComments(input)
   }),
@@ -1540,8 +1540,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-comment-replies",
     platform: "instagram",
     endpoint: "/api/v1/instagram/post/comments/replies",
-    credits: 8,
-    description: "Fetch the replies to one Instagram comment via Scavio (8 credits - no fallback leg to hedge). Returns data.child_comments with data.next_min_child_id. Requires media_id plus comment_id: the comments tool does not return a media_id, so resolve it with scavio-instagram-post first. A shortcode or url will not work here.",
+    credits: 2,
+    description: "Fetch the replies to one Instagram comment via Scavio (2 credits). Returns data.child_comments; when data.has_more_tail_child_comments is true, pass data.next_min_child_cursor as cursor. Requires media_id plus comment_id: the comments tool does not return a media_id, so resolve it with scavio-instagram-post first. A shortcode or url will not work here.",
     inputSchema: import_zod8.z.object({
       media_id: import_zod8.z.string().describe("Instagram media id, from scavio-instagram-post."),
       comment_id: import_zod8.z.string().describe("Parent comment id, from scavio-instagram-post-comments."),
@@ -1554,8 +1554,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-search-users",
     platform: "instagram",
     endpoint: "/api/v1/instagram/search/users",
-    credits: 10,
-    description: "Search Instagram accounts by keyword via Scavio (10 credits). Returns data.users with data.rank_token. Page size is not controllable - there is no count - and a fallback leg can reset paging to page 1, so treat deep paging as unreliable.",
+    credits: 2,
+    description: "Search Instagram accounts by keyword via Scavio (2 credits; a request with a cursor costs 8). Returns data.users with data.rank_token. Page size is not controllable - there is no count - so the first page is usually the one to use.",
     inputSchema: import_zod8.z.object({ keyword: keyword2, cursor: cursor5 }),
     call: (client, input) => client.instagram.searchUsers(input)
   }),
@@ -1564,8 +1564,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-search-hashtags",
     platform: "instagram",
     endpoint: "/api/v1/instagram/search/hashtags",
-    credits: 10,
-    description: "Search Instagram hashtags by keyword via Scavio (10 credits). Returns data.hashtags with media counts and data.rank_token. Same no-count, unreliable-deep-paging caveat as the user search.",
+    credits: 2,
+    description: "Search Instagram hashtags by keyword via Scavio (2 credits; a request with a cursor costs 8). Returns data.hashtags with media counts and data.rank_token. No count parameter, same as the user search.",
     inputSchema: import_zod8.z.object({ keyword: keyword2, cursor: cursor5 }),
     call: (client, input) => client.instagram.searchHashtags(input)
   }),
@@ -1574,8 +1574,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-user-followers",
     platform: "instagram",
     endpoint: "/api/v1/instagram/user/followers",
-    credits: 10,
-    description: "List an Instagram account's followers via Scavio (10 credits). Returns data.users with data.has_more; the followers response often carries no continuation id, so paging can end earlier than followings. Each page costs another 10 credits - cap how deep you walk.",
+    credits: 2,
+    description: "List an Instagram account's followers via Scavio (2 credits per page). Returns data.users with data.has_more, and data.next_max_id when there is a next page. Each page costs another 2 credits - cap how deep you walk.",
     inputSchema: import_zod8.z.object({ username: username2, user_id: userId, count: followCount, cursor: cursor5 }),
     call: (client, input) => client.instagram.userFollowers(input)
   }),
@@ -1584,8 +1584,8 @@ var instagramToolSpecs = [
     id: "scavio-instagram-user-followings",
     platform: "instagram",
     endpoint: "/api/v1/instagram/user/followings",
-    credits: 10,
-    description: "List the accounts an Instagram user follows via Scavio (10 credits). Returns data.users with data.next_max_id and data.has_more. The public name is followings (plural), matching TikTok.",
+    credits: 2,
+    description: "List the accounts an Instagram user follows via Scavio (2 credits per page). Returns data.users with data.next_max_id and data.has_more. The public name is followings (plural), matching TikTok.",
     inputSchema: import_zod8.z.object({ username: username2, user_id: userId, count: followCount, cursor: cursor5 }),
     call: (client, input) => client.instagram.userFollowings(input)
   })
@@ -2544,7 +2544,7 @@ var ebayToolSpecs = [
         "price_low",
         "price_high"
       ]).optional().describe(
-        "Result sort order. Defaults to 'best_match'. eBay's 'Distance: nearest first' is deliberately unsupported (it ranks against our proxy exit, not the caller)."
+        "Result sort order. Defaults to 'best_match'. eBay's 'Distance: nearest first' is deliberately unsupported (it would not rank by the location of the caller)."
       ),
       min_price: import_zod15.z.number().optional().describe("Minimum price, inclusive. Must be 0 or greater."),
       max_price: import_zod15.z.number().optional().describe("Maximum price, inclusive. Must be 0 or greater."),
@@ -2994,7 +2994,7 @@ var bookingToolSpecs = [
       ),
       rooms: import_zod19.z.number().int().optional().describe("Rooms required, >= 1 (default 1)."),
       currency: import_zod19.z.string().optional().describe(
-        "ISO 4217 currency for prices, 3 letters (default 'USD'). Without it Booking prices off the proxy exit and identical requests disagree."
+        "ISO 4217 currency for prices, 3 letters (default 'USD'). Without it Booking picks a currency itself and identical requests can disagree."
       )
     }),
     call: (client, input) => client.booking.search(input)
@@ -3025,7 +3025,7 @@ var bookingToolSpecs = [
       ),
       rooms: import_zod19.z.number().int().optional().describe("Rooms required, >= 1 (default 1)."),
       currency: import_zod19.z.string().optional().describe(
-        "ISO 4217 currency for prices, 3 letters (default 'USD'). Without it Booking prices off the proxy exit and identical requests disagree."
+        "ISO 4217 currency for prices, 3 letters (default 'USD'). Without it Booking picks a currency itself and identical requests can disagree."
       )
     }),
     call: (client, input) => client.booking.hotel(input)
@@ -3315,7 +3315,7 @@ var airbnbToolSpecs = [
         "Comma-separated amenities (1-200 characters): wifi, air_conditioning, pool, kitchen, free_parking, washer, self_check_in, tv, or raw numeric Airbnb amenity ids. An unrecognised NAME is rejected before the scrape."
       ),
       currency: import_zod22.z.string().optional().describe(
-        "ISO 4217 currency for prices, 3 letters (default 'USD'). Without it Airbnb prices off the proxy exit and identical requests disagree."
+        "ISO 4217 currency for prices, 3 letters (default 'USD'). Without it Airbnb picks a currency itself and identical requests can disagree."
       ),
       page: import_zod22.z.number().int().optional().describe(
         "Results page, 1-based. 18 listings per page. Cannot be combined with cursor."
@@ -3421,7 +3421,7 @@ var glassdoorToolSpecs = [
     description: "Up to THREE full Glassdoor reviews - the cap is Glassdoor's login wall - with per-axis scores, pros, cons, advice, job title, location, employment status and employer response, plus complete rating statistics, star distribution, aggregate pro/con highlight terms and per-job-title review counts. There is no page param: move the window with category and employment_status. Provide employer_id or url. Costs 1 credit.",
     inputSchema: import_zod23.z.object({
       employer_id: import_zod23.z.string().optional().describe(
-        "Glassdoor employer id (1-50 characters): '1699', 'E1699' or 'IE1699'. Must be a STRING - a JSON number is rejected. Addressing by id costs two upstream fetches; the customer price is unchanged."
+        "Glassdoor employer id (1-50 characters): '1699', 'E1699' or 'IE1699'. Must be a STRING - a JSON number is rejected. Addressing by id takes an extra lookup; the customer price is unchanged."
       ),
       company: import_zod23.z.string().optional().describe(
         "Employer name as it appears in a Glassdoor slug (1-200 characters). COSMETIC: ignored when url is set, and it does not satisfy the employer_id-or-url requirement."
@@ -3454,7 +3454,7 @@ var glassdoorToolSpecs = [
     description: "Glassdoor salaries by job title, 10 titles per page: base-pay and total-pay percentiles P10-P90 with medians called out, sample counts, currency, pay period and last-reported date. The figures are Glassdoor's ESTIMATES for the title, not individual reported salaries. Provide employer_id or url. Costs 1 credit.",
     inputSchema: import_zod23.z.object({
       employer_id: import_zod23.z.string().optional().describe(
-        "Glassdoor employer id (1-50 characters): '1699', 'E1699' or 'IE1699'. Must be a STRING - a JSON number is rejected. Addressing by id costs two upstream fetches; the customer price is unchanged."
+        "Glassdoor employer id (1-50 characters): '1699', 'E1699' or 'IE1699'. Must be a STRING - a JSON number is rejected. Addressing by id takes an extra lookup; the customer price is unchanged."
       ),
       company: import_zod23.z.string().optional().describe(
         "Employer name as it appears in a Glassdoor slug (1-200 characters). COSMETIC: ignored when url is set, and it does not satisfy the employer_id-or-url requirement."
@@ -3501,7 +3501,7 @@ var yelpToolSpecs = [
         "What to look for (1-200 characters): a category ('plumbers'), a dish, or a business name. Required together with location unless url is given."
       ),
       location: import_zod24.z.string().optional().describe(
-        "Where to look (1-200 characters): city and region, a full address, or a postcode. Effectively required - Yelp geolocates a location-less search off the proxy exit, so the same request answers about a different metro run to run."
+        "Where to look (1-200 characters): city and region, a full address, or a postcode. Effectively required - without it Yelp picks a location itself, so the same request can answer about a different metro run to run."
       ),
       page: import_zod24.z.number().int().optional().describe(
         "Results page, 1-based. Yelp fixes the page size at 10."