mastra-scavio 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +58 -9
  2. package/dist/index.cjs +1496 -177
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +240 -109
  5. package/dist/index.d.ts +240 -109
  6. package/dist/index.js +1404 -173
  7. package/dist/index.js.map +1 -1
  8. package/package.json +8 -3
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # mastra-scavio
2
2
 
3
- [Scavio](https://scavio.dev) real-time search tools for [Mastra](https://mastra.ai) agents — Google, YouTube, Amazon, Walmart, Reddit, TikTok, and Instagram, with one API key.
3
+ [Scavio](https://scavio.dev) real-time search tools for [Mastra](https://mastra.ai) agents — Google, YouTube, Amazon, Walmart, Reddit, TikTok, TikTok Shop, Instagram, X and LinkedIn, with one API key.
4
4
 
5
5
  > **Amazon changed (breaking).** The upstream provider moved in 2026-07:
6
6
  > `domain` is replaced by `country`, a two-letter marketplace code (`us`, `gb`
@@ -38,26 +38,75 @@ const agent = new Agent({
38
38
  Use a single tool instead of the full set:
39
39
 
40
40
  ```typescript
41
- import { createScavioGoogleSearchTool } from 'mastra-scavio';
41
+ import { createScavioGoogleSearchTool, createScavioLinkedinSearchJobsTool } from 'mastra-scavio';
42
42
 
43
43
  const agent = new Agent({
44
44
  id: 'search-agent',
45
45
  model: 'anthropic/claude-sonnet-4-6',
46
- instructions: 'Search Google with Scavio.',
47
- tools: { googleSearch: createScavioGoogleSearchTool({ apiKey: process.env.SCAVIO_API_KEY }) },
46
+ instructions: 'Search Google and LinkedIn jobs with Scavio.',
47
+ tools: {
48
+ googleSearch: createScavioGoogleSearchTool({ apiKey: process.env.SCAVIO_API_KEY }),
49
+ jobSearch: createScavioLinkedinSearchJobsTool({ apiKey: process.env.SCAVIO_API_KEY }),
50
+ },
48
51
  });
49
52
  ```
50
53
 
51
54
  ## Tools
52
55
 
53
- `createScavioTools()` returns: `scavioGoogleSearch`, `scavioAmazonSearch`, `scavioAmazonProduct`, `scavioAmazonOffers`, `scavioWalmartSearch`, `scavioWalmartProduct`, `scavioYoutubeSearch`, `scavioYoutubeVideo`, `scavioYoutubeMetadata`, `scavioYoutubeComments`, `scavioYoutubeChannel`, `scavioYoutubeTranscript`, `scavioYoutubeStreams`, `scavioRedditSearch`, `scavioRedditPost`, `scavioTiktokSearch`, `scavioTiktokProfile`, `scavioInstagramSearch`, `scavioInstagramProfile`.
56
+ `createScavioTools()` returns **97 tools** across ten platforms — one per billable Scavio endpoint.
54
57
 
55
- Each tool returns the structured Scavio JSON response: `{ data, response_time, credits_used, credits_remaining }`, with the payload under `data` on every platform except Google, whose body is flat.
58
+ | Platform | Tools | Names |
59
+ |---|---|---|
60
+ | Google | 14 | `scavioGoogleSearch`, `scavioGoogleAiMode`, `scavioGoogleMapsSearch`, `scavioGoogleMapsPlace`, `scavioGoogleMapsReviews`, `scavioGoogleShopping`, `scavioGoogleShoppingProduct`, `scavioGoogleShoppingStores`, `scavioGoogleFlights`, `scavioGoogleHotels`, `scavioGoogleHotelsDetail`, `scavioGoogleNews`, `scavioGoogleTrends`, `scavioGoogleTrending` |
61
+ | Amazon | 3 | `scavioAmazonSearch`, `scavioAmazonProduct`, `scavioAmazonOffers` |
62
+ | Walmart | 2 | `scavioWalmartSearch`, `scavioWalmartProduct` |
63
+ | YouTube | 15 | `scavioYoutubeSearch`, `scavioYoutubeShorts`, `scavioYoutubeSuggestions`, `scavioYoutubeVideo`, `scavioYoutubeComments`, `scavioYoutubeCommentReplies`, `scavioYoutubeTranscript`, `scavioYoutubeRelated`, `scavioYoutubeChannelSearch`, `scavioYoutubeChannel`, `scavioYoutubeChannelVideos`, `scavioYoutubeChannelShorts`, `scavioYoutubeChannelCommunity`, `scavioYoutubeChannelResolve`, `scavioYoutubeStreams` |
64
+ | Reddit | 12 | `scavioRedditSearch`, `scavioRedditSearchSuggestions`, `scavioRedditPost`, `scavioRedditPostComments`, `scavioRedditCommentReplies`, `scavioRedditSubreddit`, `scavioRedditSubredditPosts`, `scavioRedditUser`, `scavioRedditUserPosts`, `scavioRedditUserComments`, `scavioRedditPopular`, `scavioRedditTrending` |
65
+ | TikTok | 11 | `scavioTiktokProfile`, `scavioTiktokUserPosts`, `scavioTiktokVideo`, `scavioTiktokVideoComments`, `scavioTiktokCommentReplies`, `scavioTiktokSearchVideos`, `scavioTiktokSearchUsers`, `scavioTiktokHashtag`, `scavioTiktokHashtagVideos`, `scavioTiktokUserFollowers`, `scavioTiktokUserFollowings` |
66
+ | TikTok Shop | 8 | `scavioTiktokShopSearch`, `scavioTiktokShopSearchSuggestions`, `scavioTiktokShopProduct`, `scavioTiktokShopProductReviews`, `scavioTiktokShopCategories`, `scavioTiktokShopCategoryProducts`, `scavioTiktokShopShopProducts`, `scavioTiktokShopResolve` |
67
+ | Instagram | 12 | `scavioInstagramProfile`, `scavioInstagramUserPosts`, `scavioInstagramUserReels`, `scavioInstagramUserTagged`, `scavioInstagramUserStories`, `scavioInstagramPost`, `scavioInstagramPostComments`, `scavioInstagramCommentReplies`, `scavioInstagramSearchUsers`, `scavioInstagramSearchHashtags`, `scavioInstagramUserFollowers`, `scavioInstagramUserFollowings` |
68
+ | X (Twitter) | 11 | `scavioXSearch`, `scavioXTweet`, `scavioXTweetComments`, `scavioXTweetRetweeters`, `scavioXUser`, `scavioXUserTweets`, `scavioXUserReplies`, `scavioXUserMedia`, `scavioXUserFollowers`, `scavioXUserFollowings`, `scavioXTrending` |
69
+ | LinkedIn | 9 | `scavioLinkedinPerson`, `scavioLinkedinPersonAbout`, `scavioLinkedinPersonPosts`, `scavioLinkedinCompany`, `scavioLinkedinCompanyPosts`, `scavioLinkedinSearchJobs`, `scavioLinkedinJob`, `scavioLinkedinPost`, `scavioLinkedinPostComments` |
56
70
 
57
- `scavioYoutubeMetadata` is a deprecated alias of `scavioYoutubeVideo` and is kept only for older agents - use `scavioYoutubeVideo`.
71
+ Every tool is also exported individually as `createScavio<Name>Tool`.
58
72
 
59
- The full Scavio API - 98 endpoints across Google, YouTube, Amazon, Walmart, Reddit, TikTok, TikTok Shop, Instagram, X and LinkedIn - is also available directly via the [`scavio`](https://www.npmjs.com/package/scavio) SDK or the [MCP server](https://scavio.dev/docs).
73
+ Each tool returns the structured Scavio JSON response: `{ data, response_time, credits_used, credits_remaining }`, with the payload under `data` on every platform except Google, whose body is flat (read `organic_results` at the top level).
74
+
75
+ ### Endpoints deliberately not exposed
76
+
77
+ - `/api/v1/youtube/metadata` is a byte-identical deprecated alias of `/api/v1/youtube/video`. Only `scavioYoutubeVideo` ships, so an agent is not asked to pick between two tools that do the same thing. (`scavioYoutubeMetadata` was removed in 0.4.0.)
78
+ - LinkedIn `person/contact`, `company/people`, `company/jobs`, `search/people` and `search/posts` were retired upstream and answer HTTP 410 unbilled. `scavioLinkedinCompany` returns `featured_employees` (a 4-6 person sample) in place of `company/people`, and `scavioLinkedinSearchJobs` with the company name replaces `company/jobs`.
79
+ - `/api/v1/google` (Google v1) was retired on 2026-08-04 and answers 410. The Google tools speak v2 natively — `gl`, `hl`, `start`, `google_domain`, `device`. `start` is a 0-based result offset (0 is page 1, 10 is page 2), not a page number, so no `page` parameter is offered.
80
+
81
+ Everything else the Scavio API bills for has a tool here. The same endpoints are also available directly via the [`scavio`](https://www.npmjs.com/package/scavio) SDK or the [MCP server](https://scavio.dev/docs).
82
+
83
+ ### Renamed in 0.5.0
84
+
85
+ Reddit, TikTok and Instagram shipped two tools each before 0.5.0; the rest of their endpoints are new in this release. Two of the four old names were ambiguous once their siblings landed and were renamed:
86
+
87
+ | Before 0.5.0 | Now |
88
+ |---|---|
89
+ | `scavioTiktokSearch` / `createScavioTiktokSearchTool` | `scavioTiktokSearchVideos` / `createScavioTiktokSearchVideosTool` (there is now a `scavioTiktokSearchUsers` too) |
90
+ | `scavioInstagramSearch` / `createScavioInstagramSearchTool` | `scavioInstagramSearchUsers` / `createScavioInstagramSearchUsersTool` (there is now a `scavioInstagramSearchHashtags` too) |
91
+
92
+ `scavioRedditSearch`, `scavioRedditPost`, `scavioTiktokProfile` and `scavioInstagramProfile` are unchanged.
60
93
 
61
94
  ## Credits
62
95
 
63
- Most calls cost 1 credit, including Google and Reddit. YouTube search costs 2, YouTube streams 3, and YouTube transcript 8. The Instagram tools cost 10 each. See [scavio.dev/docs](https://scavio.dev/docs).
96
+ Most calls cost 1 credit. Every tool states its own cost in its description, so an agent can budget before it fans out.
97
+
98
+ | Tool | Credits |
99
+ |---|---|
100
+ | All Google, Amazon, Walmart, Reddit, TikTok, TikTok Shop and X tools | 1 |
101
+ | `scavioYoutubeSearch`, `scavioYoutubeShorts` | 2 |
102
+ | `scavioYoutubeStreams` | 3 |
103
+ | `scavioYoutubeTranscript` | 8 |
104
+ | All other YouTube tools | 1 |
105
+ | `scavioLinkedinPerson`, `scavioLinkedinPersonAbout`, `scavioLinkedinCompany`, `scavioLinkedinPost` | 1 |
106
+ | `scavioLinkedinPersonPosts`, `scavioLinkedinCompanyPosts`, `scavioLinkedinSearchJobs`, `scavioLinkedinPostComments` | 10 |
107
+ | `scavioLinkedinJob` | 30 |
108
+ | `scavioInstagramUserPosts` | 2 |
109
+ | `scavioInstagramPost`, `scavioInstagramCommentReplies` | 8 |
110
+ | All other Instagram tools | 10 |
111
+
112
+ 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).