socialtap 1.453.19 → 1.483.27
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.
- package/README.md +154 -98
- package/dist/agents.d.ts +3 -1
- package/dist/agents.js +27 -4
- package/dist/ai.d.ts +6 -3
- package/dist/ai.js +4 -3
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +96 -41
- package/dist/client.d.ts +19 -14
- package/dist/client.js +21 -14
- package/dist/commands.d.ts +0 -2
- package/dist/commands.js +652 -218
- package/dist/constants.d.ts +32 -23
- package/dist/constants.js +28 -23
- package/dist/core.d.ts +10 -2
- package/dist/core.js +52 -4
- package/dist/errors.d.ts +74 -60
- package/dist/errors.js +74 -60
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/models.d.ts +1264 -127
- package/dist/models.js +1 -1
- package/dist/resources.d.ts +6414 -4676
- package/dist/resources.js +951 -468
- package/dist/tooldefs.d.ts +6 -1
- package/dist/tooldefs.js +2052 -1467
- package/dist/tools.js +1 -1
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -2,22 +2,25 @@
|
|
|
2
2
|
|
|
3
3
|
# SocialTap for TypeScript
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
SocialTap is the social media scraper API for developers and AI agents. Send a public link, a handle or a search and get live data back in one schema. Failed requests are free.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The TypeScript SDK for the SocialTap API: a method for every endpoint, typed models and errors, retries and pagination.
|
|
8
|
+
Generated from the SocialTap catalog (version 1.483.27). Docs: https://socialtap.dev/docs.
|
|
8
9
|
|
|
9
|
-
|
|
10
|
-
`sdk/typescript`).
|
|
10
|
+
## Install
|
|
11
11
|
|
|
12
12
|
```sh
|
|
13
|
-
|
|
14
|
-
npm
|
|
13
|
+
npm install socialtap
|
|
14
|
+
npm pkg set type=module # the examples are ES modules (or name your file .mjs or .mts)
|
|
15
15
|
```
|
|
16
16
|
|
|
17
|
-
Zero runtime dependencies (`fetch`); Node 20.3+, Deno, Bun and Cloudflare Workers (server-side: the API key is a secret).
|
|
18
|
-
|
|
17
|
+
Zero runtime dependencies (`fetch`); Node 20.3+, Deno, Bun and Cloudflare Workers (server-side: the API key is a secret).
|
|
18
|
+
ESM only: in Node, your project needs `"type": "module"` in its package.json (the second command above) or a
|
|
19
|
+
`.mjs`/`.mts` file, else Node stops at the first `import` ("Cannot use import statement outside a module"). Run
|
|
20
|
+
TypeScript directly with Node 22.18+ (`node app.ts`) or `npx tsx app.ts`. Params and models use the API's snake_case
|
|
21
|
+
names; SDK objects (options, `credits`, errors) are camelCase.
|
|
19
22
|
|
|
20
|
-
|
|
23
|
+
`null` means unknown. With `fields`, results are typed `PartialModel<T>` (every member may
|
|
21
24
|
be absent). A 2xx that is not the API's envelope (no `data`, not JSON) throws `APIDecodeError`; a `retry-after` longer than
|
|
22
25
|
`MAX_RETRY_AFTER_S` throws `RetryAfterExceededError` instead of retrying early. Results keep the API's objects as sent,
|
|
23
26
|
members this version doesn't model included. `Event` is a union narrowed by `type`; a job item's `params` are typed by its `endpoint`.
|
|
@@ -25,9 +28,9 @@ members this version doesn't model included. `Event` is a union narrowed by `typ
|
|
|
25
28
|
## Authenticate
|
|
26
29
|
|
|
27
30
|
The client reads your API key from `SOCIALTAP_API_KEY`, or takes it as an option. Requests send it in the
|
|
28
|
-
`x-api-key` header.
|
|
31
|
+
`x-api-key` header. Get a key at https://socialtap.dev/signup/: every account starts with 100 free credits.
|
|
29
32
|
|
|
30
|
-
## First call:
|
|
33
|
+
## First call: Exact follower and like counts, bio and country
|
|
31
34
|
|
|
32
35
|
```ts
|
|
33
36
|
import { SocialTap } from "socialtap";
|
|
@@ -94,10 +97,20 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
94
97
|
|
|
95
98
|
| endpoint | method | cost |
|
|
96
99
|
|---|---|---|
|
|
100
|
+
| `applemusic.album` | `client.applemusic.album.get()` | 1 credit |
|
|
101
|
+
| `applemusic.artist` | `client.applemusic.artist.get()` | 1 credit |
|
|
102
|
+
| `applemusic.search_albums` | `client.applemusic.searchAlbums.list()` | 1 credit |
|
|
103
|
+
| `applemusic.search_artists` | `client.applemusic.searchArtists.list()` | 1 credit |
|
|
104
|
+
| `applemusic.search_playlists` | `client.applemusic.searchPlaylists.list()` | 1 credit |
|
|
105
|
+
| `applemusic.search_tracks` | `client.applemusic.searchTracks.list()` | 1 credit |
|
|
106
|
+
| `applemusic.top_albums` | `client.applemusic.topAlbums.list()` | 1 credit |
|
|
107
|
+
| `applemusic.top_playlists` | `client.applemusic.topPlaylists.list()` | 1 credit |
|
|
108
|
+
| `applemusic.top_tracks` | `client.applemusic.topTracks.list()` | 1 credit |
|
|
109
|
+
| `applemusic.track` | `client.applemusic.track.get()` | 1 credit |
|
|
97
110
|
| `bluesky.comments` | `client.bluesky.comments.list()` | 1 credit |
|
|
98
111
|
| `bluesky.post` | `client.bluesky.post.get()` | 1 credit |
|
|
99
112
|
| `bluesky.posts` | `client.bluesky.posts.list()` | 1 credit |
|
|
100
|
-
| `bluesky.profile` | `client.bluesky.profile.get()` | 1 credit
|
|
113
|
+
| `bluesky.profile` | `client.bluesky.profile.get()` | 1 credit |
|
|
101
114
|
| `bluesky.search_posts` | `client.bluesky.searchPosts.list()` | 1 credit |
|
|
102
115
|
| `facebook.ad` | `client.facebook.ad.get()` | 1 credit |
|
|
103
116
|
| `facebook.ad_transcript` | `client.facebook.adTranscript.get()` | 2 credits + 2 per started minute of media |
|
|
@@ -108,7 +121,7 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
108
121
|
| `facebook.events` | `client.facebook.events.list()` | 1 credit |
|
|
109
122
|
| `facebook.group` | `client.facebook.group.get()` | 1 credit |
|
|
110
123
|
| `facebook.group_posts` | `client.facebook.groupPosts.list()` | 1 credit |
|
|
111
|
-
| `facebook.listing` | `client.facebook.listing.get()` | 1 credit
|
|
124
|
+
| `facebook.listing` | `client.facebook.listing.get()` | 1 credit |
|
|
112
125
|
| `facebook.photos` | `client.facebook.photos.list()` | 1 credit |
|
|
113
126
|
| `facebook.place_events` | `client.facebook.placeEvents.list()` | 1 credit |
|
|
114
127
|
| `facebook.post` | `client.facebook.post.get()` | 1 credit |
|
|
@@ -120,11 +133,11 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
120
133
|
| `facebook.search_advertisers` | `client.facebook.searchAdvertisers.list()` | 1 credit |
|
|
121
134
|
| `facebook.search_events` | `client.facebook.searchEvents.list()` | 1 credit |
|
|
122
135
|
| `facebook.search_groups` | `client.facebook.searchGroups.list()` | 1 credit + 1 per result filled in |
|
|
123
|
-
| `facebook.search_listings` | `client.facebook.searchListings.list()` | 1 credit
|
|
136
|
+
| `facebook.search_listings` | `client.facebook.searchListings.list()` | 1 credit |
|
|
124
137
|
| `facebook.search_places` | `client.facebook.searchPlaces.list()` | 1 credit |
|
|
125
138
|
| `facebook.search_posts` | `client.facebook.searchPosts.list()` | 1 credit + 1 per result filled in |
|
|
126
139
|
| `facebook.search_profiles` | `client.facebook.searchProfiles.list()` | 1 credit + 1 per result filled in |
|
|
127
|
-
| `facebook.transcript` | `client.facebook.transcript.get()` | 1 credit
|
|
140
|
+
| `facebook.transcript` | `client.facebook.transcript.get()` | 1 credit (captions) or 2 credits + 2 per started minute of media (speech-to-text) |
|
|
128
141
|
| `google.ad` | `client.google.ad.get()` | 1 credit |
|
|
129
142
|
| `google.ads` | `client.google.ads.list()` | 1 credit |
|
|
130
143
|
| `google.advertiser` | `client.google.advertiser.get()` | 1 credit |
|
|
@@ -133,10 +146,10 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
133
146
|
| `google.search_suggestions` | `client.google.searchSuggestions.list()` | 1 credit |
|
|
134
147
|
| `instagram.comment` | `client.instagram.comment.get()` | 1 credit |
|
|
135
148
|
| `instagram.comments` | `client.instagram.comments.list()` | 1 credit |
|
|
136
|
-
| `instagram.embed` | `client.instagram.embed.get()` | 1 credit
|
|
149
|
+
| `instagram.embed` | `client.instagram.embed.get()` | 1 credit |
|
|
137
150
|
| `instagram.engagement` | `client.instagram.engagement.get()` | 1 credit |
|
|
138
151
|
| `instagram.hashtag` | `client.instagram.hashtag.get()` | 1 credit |
|
|
139
|
-
| `instagram.hashtag_posts` | `client.instagram.hashtagPosts.list()` | 1 credit
|
|
152
|
+
| `instagram.hashtag_posts` | `client.instagram.hashtagPosts.list()` | 1 credit |
|
|
140
153
|
| `instagram.highlights` | `client.instagram.highlights.list()` | 1 credit |
|
|
141
154
|
| `instagram.place` | `client.instagram.place.get()` | 1 credit |
|
|
142
155
|
| `instagram.place_posts` | `client.instagram.placePosts.list()` | 1 credit |
|
|
@@ -147,7 +160,7 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
147
160
|
| `instagram.reels` | `client.instagram.reels.list()` | 1 credit |
|
|
148
161
|
| `instagram.search_hashtags` | `client.instagram.searchHashtags.list()` | 1 credit |
|
|
149
162
|
| `instagram.search_places` | `client.instagram.searchPlaces.list()` | 1 credit + 1 per result filled in |
|
|
150
|
-
| `instagram.search_posts` | `client.instagram.searchPosts.list()` | 1 credit
|
|
163
|
+
| `instagram.search_posts` | `client.instagram.searchPosts.list()` | 1 credit |
|
|
151
164
|
| `instagram.search_profiles` | `client.instagram.searchProfiles.list()` | 1 credit + 1 per result filled in |
|
|
152
165
|
| `instagram.search_sounds` | `client.instagram.searchSounds.list()` | 1 credit + 1 per result filled in |
|
|
153
166
|
| `instagram.search_suggestions` | `client.instagram.searchSuggestions.list()` | 1 credit |
|
|
@@ -156,10 +169,10 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
156
169
|
| `instagram.sound_posts` | `client.instagram.soundPosts.list()` | 1 credit |
|
|
157
170
|
| `instagram.story` | `client.instagram.story.get()` | 1 credit |
|
|
158
171
|
| `instagram.topic` | `client.instagram.topic.get()` | 1 credit |
|
|
159
|
-
| `instagram.transcript` | `client.instagram.transcript.get()` | 1 credit
|
|
160
|
-
| `instagram.trending_posts` | `client.instagram.trendingPosts.list()` | 1 credit
|
|
172
|
+
| `instagram.transcript` | `client.instagram.transcript.get()` | 1 credit (captions) or 2 credits + 2 per started minute of media (speech-to-text) |
|
|
173
|
+
| `instagram.trending_posts` | `client.instagram.trendingPosts.list()` | 1 credit |
|
|
161
174
|
| `instagram.username` | `client.instagram.username.get()` | 1 credit |
|
|
162
|
-
| `kick.post` | `client.kick.post.get()` | 1 credit
|
|
175
|
+
| `kick.post` | `client.kick.post.get()` | 1 credit |
|
|
163
176
|
| `kick.transcript` | `client.kick.transcript.get()` | 2 credits + 2 per started minute of media |
|
|
164
177
|
| `komi.page` | `client.komi.page.get()` | 1 credit |
|
|
165
178
|
| `kwai.post` | `client.kwai.post.get()` | 1 credit |
|
|
@@ -168,11 +181,11 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
168
181
|
| `linkbio.profile` | `client.linkbio.profile.get()` | 1 credit |
|
|
169
182
|
| `linkedin.ad` | `client.linkedin.ad.get()` | 1 credit |
|
|
170
183
|
| `linkedin.post` | `client.linkedin.post.get()` | 1 credit |
|
|
171
|
-
| `linkedin.profile` | `client.linkedin.profile.get()` | 1 credit |
|
|
184
|
+
| `linkedin.profile` | `client.linkedin.profile.get()` | 1 credit (public page) or 5 credits (data partner) |
|
|
172
185
|
| `linkedin.search_ads` | `client.linkedin.searchAds.list()` | 1 credit |
|
|
173
186
|
| `linkedin.search_posts` | `client.linkedin.searchPosts.list()` | 1 credit + 1 per result filled in |
|
|
174
187
|
| `linkedin.search_profiles` | `client.linkedin.searchProfiles.list()` | 1 credit + 1 per result filled in |
|
|
175
|
-
| `linkme.profile` | `client.linkme.profile.get()` | 1 credit
|
|
188
|
+
| `linkme.profile` | `client.linkme.profile.get()` | 1 credit |
|
|
176
189
|
| `linktree.profile` | `client.linktree.profile.get()` | 1 credit |
|
|
177
190
|
| `pillar.page` | `client.pillar.page.get()` | 1 credit |
|
|
178
191
|
| `reddit.comments` | `client.reddit.comments.list()` | 1 credit |
|
|
@@ -187,38 +200,53 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
187
200
|
| `reddit.search_subreddits` | `client.reddit.searchSubreddits.list()` | 1 credit |
|
|
188
201
|
| `reddit.subreddit` | `client.reddit.subreddit.get()` | 1 credit |
|
|
189
202
|
| `reddit.subreddit_posts` | `client.reddit.subredditPosts.list()` | 1 credit |
|
|
190
|
-
| `reddit.transcript` | `client.reddit.transcript.get()` | 1 credit
|
|
203
|
+
| `reddit.transcript` | `client.reddit.transcript.get()` | 1 credit (captions) or 2 credits + 2 per started minute of media (speech-to-text) |
|
|
191
204
|
| `rumble.comments` | `client.rumble.comments.list()` | 1 credit |
|
|
192
205
|
| `rumble.engagement` | `client.rumble.engagement.get()` | 1 credit |
|
|
193
206
|
| `rumble.post` | `client.rumble.post.get()` | 1 credit |
|
|
194
207
|
| `rumble.posts` | `client.rumble.posts.list()` | 1 credit |
|
|
195
208
|
| `rumble.profile` | `client.rumble.profile.get()` | 1 credit |
|
|
196
209
|
| `rumble.search_posts` | `client.rumble.searchPosts.list()` | 1 credit |
|
|
197
|
-
| `rumble.transcript` | `client.rumble.transcript.get()` | 1 credit
|
|
210
|
+
| `rumble.transcript` | `client.rumble.transcript.get()` | 1 credit (captions) or 2 credits + 2 per started minute of media (speech-to-text) |
|
|
198
211
|
| `snapchat.comments` | `client.snapchat.comments.list()` | 1 credit |
|
|
199
212
|
| `snapchat.profile` | `client.snapchat.profile.get()` | 1 credit |
|
|
200
213
|
| `snapchat.spotlight` | `client.snapchat.spotlight.get()` | 1 credit |
|
|
201
|
-
| `soundcloud.artist` | `client.soundcloud.artist.get()` | 1 credit
|
|
202
|
-
| `soundcloud.track` | `client.soundcloud.track.get()` | 1 credit
|
|
203
|
-
| `soundcloud.tracks` | `client.soundcloud.tracks.list()` | 1 credit
|
|
214
|
+
| `soundcloud.artist` | `client.soundcloud.artist.get()` | 1 credit |
|
|
215
|
+
| `soundcloud.track` | `client.soundcloud.track.get()` | 1 credit |
|
|
216
|
+
| `soundcloud.tracks` | `client.soundcloud.tracks.list()` | 1 credit |
|
|
217
|
+
| `spotify.album` | `client.spotify.album.get()` | 1 credit |
|
|
218
|
+
| `spotify.artist` | `client.spotify.artist.get()` | 1 credit |
|
|
219
|
+
| `spotify.playlist` | `client.spotify.playlist.get()` | 1 credit |
|
|
220
|
+
| `spotify.playlist_tracks` | `client.spotify.playlistTracks.list()` | 1 credit |
|
|
221
|
+
| `spotify.podcast` | `client.spotify.podcast.get()` | 1 credit |
|
|
222
|
+
| `spotify.podcast_episodes` | `client.spotify.podcastEpisodes.list()` | 1 credit |
|
|
223
|
+
| `spotify.search_albums` | `client.spotify.searchAlbums.list()` | 1 credit |
|
|
224
|
+
| `spotify.search_artists` | `client.spotify.searchArtists.list()` | 1 credit |
|
|
225
|
+
| `spotify.search_playlists` | `client.spotify.searchPlaylists.list()` | 1 credit |
|
|
226
|
+
| `spotify.search_podcasts` | `client.spotify.searchPodcasts.list()` | 1 credit |
|
|
227
|
+
| `spotify.search_tracks` | `client.spotify.searchTracks.list()` | 1 credit |
|
|
228
|
+
| `spotify.track` | `client.spotify.track.get()` | 1 credit |
|
|
204
229
|
| `telegram.channel` | `client.telegram.channel.get()` | 1 credit |
|
|
205
230
|
| `telegram.channel_posts` | `client.telegram.channelPosts.list()` | 1 credit |
|
|
206
231
|
| `telegram.post` | `client.telegram.post.get()` | 1 credit |
|
|
207
232
|
| `telegram.search_channels` | `client.telegram.searchChannels.list()` | 1 credit + 1 per result filled in |
|
|
208
|
-
| `threads.comments` | `client.threads.comments.list()` | 1 credit
|
|
209
|
-
| `threads.post` | `client.threads.post.get()` | 1 credit
|
|
210
|
-
| `threads.posts` | `client.threads.posts.list()` | 1 credit
|
|
211
|
-
| `threads.profile` | `client.threads.profile.get()` | 1 credit
|
|
212
|
-
| `threads.search_posts` | `client.threads.searchPosts.list()` | 1 credit
|
|
233
|
+
| `threads.comments` | `client.threads.comments.list()` | 1 credit |
|
|
234
|
+
| `threads.post` | `client.threads.post.get()` | 1 credit |
|
|
235
|
+
| `threads.posts` | `client.threads.posts.list()` | 1 credit |
|
|
236
|
+
| `threads.profile` | `client.threads.profile.get()` | 1 credit |
|
|
237
|
+
| `threads.search_posts` | `client.threads.searchPosts.list()` | 1 credit |
|
|
213
238
|
| `threads.search_profiles` | `client.threads.searchProfiles.list()` | 1 credit |
|
|
214
239
|
| `tiktok.ad` | `client.tiktok.ad.get()` | 1 credit |
|
|
215
240
|
| `tiktok.comment` | `client.tiktok.comment.get()` | 1 credit |
|
|
216
241
|
| `tiktok.comments` | `client.tiktok.comments.list()` | 1 credit |
|
|
217
|
-
| `tiktok.download` | `client.tiktok.download.get()` | 1 credit
|
|
242
|
+
| `tiktok.download` | `client.tiktok.download.get()` | 1 credit |
|
|
218
243
|
| `tiktok.effect` | `client.tiktok.effect.get()` | 1 credit |
|
|
219
244
|
| `tiktok.effect_posts` | `client.tiktok.effectPosts.list()` | 1 credit |
|
|
220
245
|
| `tiktok.engagement` | `client.tiktok.engagement.get()` | 1 credit |
|
|
246
|
+
| `tiktok.followers` | `client.tiktok.followers.list()` | 1 credit |
|
|
247
|
+
| `tiktok.following` | `client.tiktok.following.list()` | 1 credit |
|
|
221
248
|
| `tiktok.hashtag` | `client.tiktok.hashtag.get()` | 1 credit |
|
|
249
|
+
| `tiktok.hashtag_posts` | `client.tiktok.hashtagPosts.list()` | 1 credit |
|
|
222
250
|
| `tiktok.liked_posts` | `client.tiktok.likedPosts.list()` | 1 credit |
|
|
223
251
|
| `tiktok.live` | `client.tiktok.live.get()` | 1 credit |
|
|
224
252
|
| `tiktok.place_posts` | `client.tiktok.placePosts.list()` | 1 credit |
|
|
@@ -238,13 +266,13 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
238
266
|
| `tiktok.sound_posts` | `client.tiktok.soundPosts.list()` | 1 credit |
|
|
239
267
|
| `tiktok.top_ads` | `client.tiktok.topAds.list()` | 1 credit |
|
|
240
268
|
| `tiktok.top_posts` | `client.tiktok.topPosts.list()` | 1 credit |
|
|
241
|
-
| `tiktok.transcript` | `client.tiktok.transcript.get()` | 1 credit
|
|
269
|
+
| `tiktok.transcript` | `client.tiktok.transcript.get()` | 1 credit (captions) or 2 credits + 2 per started minute of media (speech-to-text) |
|
|
242
270
|
| `tiktok.trending_hashtags` | `client.tiktok.trendingHashtags.list()` | 1 credit |
|
|
243
271
|
| `tiktok.trending_posts` | `client.tiktok.trendingPosts.list()` | 1 credit |
|
|
244
272
|
| `tiktokshop.product` | `client.tiktokshop.product.get()` | 1 credit |
|
|
245
273
|
| `tiktokshop.products` | `client.tiktokshop.products.list()` | 1 credit |
|
|
246
274
|
| `tiktokshop.reviews` | `client.tiktokshop.reviews.list()` | 1 credit |
|
|
247
|
-
| `tiktokshop.search_products` | `client.tiktokshop.searchProducts.list()` | 1 credit
|
|
275
|
+
| `tiktokshop.search_products` | `client.tiktokshop.searchProducts.list()` | 1 credit |
|
|
248
276
|
| `truthsocial.post` | `client.truthsocial.post.get()` | 1 credit |
|
|
249
277
|
| `truthsocial.posts` | `client.truthsocial.posts.list()` | 1 credit |
|
|
250
278
|
| `truthsocial.profile` | `client.truthsocial.profile.get()` | 1 credit |
|
|
@@ -262,10 +290,22 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
262
290
|
| `x.search_profiles` | `client.x.searchProfiles.list()` | 1 credit + 1 per result filled in |
|
|
263
291
|
| `youtube.comments` | `client.youtube.comments.list()` | 1 credit |
|
|
264
292
|
| `youtube.engagement` | `client.youtube.engagement.get()` | 1 credit |
|
|
265
|
-
| `youtube.post` | `client.youtube.post.get()` | 1 credit
|
|
293
|
+
| `youtube.post` | `client.youtube.post.get()` | 1 credit |
|
|
266
294
|
| `youtube.posts` | `client.youtube.posts.list()` | 1 credit |
|
|
267
295
|
| `youtube.profile` | `client.youtube.profile.get()` | 1 credit |
|
|
268
|
-
| `youtube.transcript` | `client.youtube.transcript.get()` | 1 credit
|
|
296
|
+
| `youtube.transcript` | `client.youtube.transcript.get()` | 1 credit (captions) or 2 credits + 2 per started minute of media (speech-to-text) |
|
|
297
|
+
|
|
298
|
+
### Endpoints newer than this package
|
|
299
|
+
|
|
300
|
+
A version has a method for every endpoint the API had when it was released. For a newer one, update the
|
|
301
|
+
package, or send the request yourself: the raw request adds your key and retries and raises errors like a method,
|
|
302
|
+
and returns the status, headers and body (the envelope, `data` and `meta`). Each endpoint's docs page has its path
|
|
303
|
+
and params.
|
|
304
|
+
|
|
305
|
+
```ts
|
|
306
|
+
const res = await client.request({ method: "GET", path: "/v1/tiktok/profile", query: { handle: "nasa" } });
|
|
307
|
+
console.log(res.status, res.body);
|
|
308
|
+
```
|
|
269
309
|
|
|
270
310
|
## Errors
|
|
271
311
|
|
|
@@ -280,7 +320,7 @@ try {
|
|
|
280
320
|
await client.tiktok.profile.get({ handle: "nasa" });
|
|
281
321
|
} catch (err) {
|
|
282
322
|
if (err instanceof NotFoundError) {
|
|
283
|
-
// Check the
|
|
323
|
+
// Check the link or ID. Do not retry.
|
|
284
324
|
} else if (err instanceof APIError) {
|
|
285
325
|
console.error(err.code, err.status, err.retryable, err.remediation, err.requestId);
|
|
286
326
|
} else throw err;
|
|
@@ -296,6 +336,7 @@ try {
|
|
|
296
336
|
| `insufficient_credits` | `InsufficientCreditsError` | 402 | no |
|
|
297
337
|
| `spend_limit_reached` | `SpendLimitReachedError` | 402 | no |
|
|
298
338
|
| `rate_limited` | `RateLimitedError` | 429 | yes |
|
|
339
|
+
| `request_too_large` | `RequestTooLargeError` | 413 | no |
|
|
299
340
|
| `method_not_allowed` | `MethodNotAllowedError` | 405 | no |
|
|
300
341
|
| `endpoint_retired` | `EndpointRetiredError` | 410 | no |
|
|
301
342
|
| `idempotency_key_reused` | `IdempotencyKeyReusedError` | 422 | no |
|
|
@@ -317,7 +358,9 @@ try {
|
|
|
317
358
|
Retryable failures (the codes above, connection errors, timeouts) are retried 2 times by default with
|
|
318
359
|
exponential backoff and jitter, honoring `retry-after`. A GET retry sends `max_age` set to the seconds since the first
|
|
319
360
|
attempt: if the first response was lost in transit, the retry is served free from the cache. Timeouts are per
|
|
320
|
-
attempt
|
|
361
|
+
attempt: 60 s by default, and 300 s for endpoints that may transcribe audio (`facebook.ad_transcript`, `facebook.transcript`, `instagram.transcript`, `kick.transcript`, `reddit.transcript`, `rumble.transcript`, `tiktok.transcript`, `twitch.transcript`, `youtube.transcript`), because speech-to-text on long
|
|
362
|
+
media takes minutes, and for create-and-wait's long-polls. Most requests answer in a few seconds. A timeout you set, on the client or on one request,
|
|
363
|
+
applies to every endpoint, and so does `maxRetries`.
|
|
321
364
|
|
|
322
365
|
## Pagination
|
|
323
366
|
|
|
@@ -327,7 +370,7 @@ stopped it) and `endReason` (the API's `page.end_reason`) say what happened.
|
|
|
327
370
|
Each page is checked against its catalog price before it is fetched, and an empty page with `has_more` is not the end.
|
|
328
371
|
|
|
329
372
|
```ts
|
|
330
|
-
const items = client.
|
|
373
|
+
const items = client.applemusic.searchAlbums.iterate({ query: "lover" }, { maxPages: 10, maxCredits: 100 });
|
|
331
374
|
for await (const item of items) {
|
|
332
375
|
console.log(item);
|
|
333
376
|
}
|
|
@@ -357,7 +400,10 @@ console.log(res.data, res.meta.request_id);
|
|
|
357
400
|
| `usage.rate.list` | `client.usage.rate.list(params)` | `account:read` |
|
|
358
401
|
| `credit_transactions.list` | `client.creditTransactions.list(params)` | `account:read` |
|
|
359
402
|
| `billing.checkout.get` | `client.billing.checkout.get(id)` | `account:read` |
|
|
403
|
+
| `billing.subscription.get` | `client.billing.subscription.get()` | `account:read` |
|
|
360
404
|
| `billing.auto_topup.get` | `client.billing.autoTopup.get()` | `account:read` |
|
|
405
|
+
| `billing.purchases.list` | `client.billing.purchases.list(params)` | `account:read` |
|
|
406
|
+
| `billing.purchases.receipt` | `client.billing.purchases.receipt(id)` | `account:read` |
|
|
361
407
|
| `requests.list` | `client.requests.list(params)` | `account:read` |
|
|
362
408
|
| `requests.get` | `client.requests.get(id)` | `account:read` |
|
|
363
409
|
| `requests.get_response` | `client.requests.getResponse(id)` | `account:read` |
|
|
@@ -410,7 +456,8 @@ continue, and failures returned as the tool's output (`error` with `retryable` a
|
|
|
410
456
|
act on them. Transport failures raise as for any request, and tools that may be repeated are retried.
|
|
411
457
|
|
|
412
458
|
```ts
|
|
413
|
-
// The Vercel AI SDK (ai is an optional peer dependency):
|
|
459
|
+
// The Vercel AI SDK (ai is an optional peer dependency): the default tools (call_endpoint reaches every endpoint),
|
|
460
|
+
// or socialtapTools({ tools: [...] }) / socialtapTools({ tools: "all" }).
|
|
414
461
|
import { generateText, stepCountIs } from "ai";
|
|
415
462
|
import { socialtapTools } from "socialtap/ai";
|
|
416
463
|
|
|
@@ -420,67 +467,77 @@ const { text } = await generateText({ model, tools: socialtapTools(), stopWhen:
|
|
|
420
467
|
// Any other tool-calling API: hand TOOLS (name, description, inputSchema) to the model, run its calls with callTool.
|
|
421
468
|
import { SocialTap, TOOLS, callTool } from "socialtap";
|
|
422
469
|
|
|
423
|
-
const r = await callTool(new SocialTap(), "find_endpoint", { query: "
|
|
470
|
+
const r = await callTool(new SocialTap(), "find_endpoint", { query: "Exact follower and like counts, bio and country" });
|
|
424
471
|
console.log(r.isError, r.output);
|
|
425
472
|
```
|
|
426
473
|
|
|
427
474
|
| tool | what it does |
|
|
428
475
|
|---|---|
|
|
429
|
-
| `get_ad` | Get an ad |
|
|
430
|
-
| `get_ad_transcript` | Get an ad transcript |
|
|
431
|
-
| `get_comment` | Get a comment |
|
|
432
|
-
| `get_community` | Get a community |
|
|
433
|
-
| `get_download` | Get a download |
|
|
434
|
-
| `get_effect` | Get an effect |
|
|
435
|
-
| `get_embed` | Get an embed |
|
|
436
|
-
| `get_engagement` | Get an engagement |
|
|
437
|
-
| `get_event` | Get an event |
|
|
438
|
-
| `get_hashtag` | Get a hashtag |
|
|
439
|
-
| `get_live` | Get a live |
|
|
440
|
-
| `get_place` | Get a place |
|
|
441
|
-
| `get_post` | Get a post |
|
|
442
|
-
| `get_product` | Get a product |
|
|
443
|
-
| `get_profile` | Get a profile |
|
|
444
|
-
| `get_sound` | Get a sound |
|
|
445
|
-
| `get_story` | Get a story |
|
|
446
|
-
| `get_topic` | Get a topic |
|
|
447
|
-
| `get_transcript` | Get a transcript |
|
|
448
|
-
| `get_username` | Get a username |
|
|
449
|
-
| `list_ads` | List ads |
|
|
450
|
-
| `list_channel_posts` | List channel posts |
|
|
451
|
-
| `list_comments` | List comments |
|
|
452
|
-
| `list_community_posts` | List community posts |
|
|
453
|
-
| `list_effect_posts` | List effect posts |
|
|
454
|
-
| `list_events` | List events |
|
|
455
|
-
| `list_hashtag_posts` | List hashtag posts |
|
|
456
|
-
| `list_highlights` | List highlights |
|
|
457
|
-
| `list_liked_posts` | List liked posts |
|
|
458
|
-
| `list_photos` | List photos |
|
|
459
|
-
| `list_place_events` | List place events |
|
|
460
|
-
| `list_place_posts` | List place posts |
|
|
461
|
-
| `list_playlist_posts` | List playlist posts |
|
|
462
|
-
| `list_playlist_stories` | List playlist stories |
|
|
463
|
-
| `list_playlists` | List playlists |
|
|
464
|
-
| `list_posts` | List posts |
|
|
465
|
-
| `list_products` | List products |
|
|
466
|
-
| `list_profile_comments` | List profile comments |
|
|
467
|
-
| `list_reels` | List reels |
|
|
468
|
-
| `list_replies` | List replies |
|
|
469
|
-
| `list_reviews` | List reviews |
|
|
470
|
-
| `list_schedule` | List schedule |
|
|
471
|
-
| `list_similar_profiles` | List similar profiles |
|
|
472
|
-
| `list_sound_posts` | List sound posts |
|
|
473
|
-
| `list_top_ads` | List top ads |
|
|
474
|
-
| `list_top_posts` | List top posts |
|
|
475
|
-
| `list_tracks` | List tracks |
|
|
476
|
-
| `list_trending_hashtags` | List trending hashtags |
|
|
477
|
-
| `list_trending_posts` | List trending posts |
|
|
478
|
-
| `list_videos` | List videos |
|
|
479
|
-
| `search` | Search ads and advertisers and channels and comments and communities and events and groups and hashtags and places and posts and products and profiles and sounds and suggestions and top |
|
|
480
476
|
| `find_endpoint` | Find an endpoint |
|
|
477
|
+
| `get_post` | Post by link |
|
|
478
|
+
| `list_posts` | Posts of a profile |
|
|
479
|
+
| `get_profile` | Profile by handle |
|
|
480
|
+
| `list_comments` | Comments of a post |
|
|
481
|
+
| `get_transcript` | Transcript by link |
|
|
482
|
+
| `get_engagement` | Engagement by handle |
|
|
483
|
+
| `search` | Search by query |
|
|
484
|
+
| `call_endpoint` | Call any endpoint |
|
|
481
485
|
| `search_docs` | Search the docs |
|
|
482
486
|
| `read_doc` | Read a docs page |
|
|
483
487
|
| `get_account` | Get account balance |
|
|
488
|
+
| `get_story` | Story by link |
|
|
489
|
+
| `list_community_posts` | Community posts |
|
|
490
|
+
| `list_hashtag_posts` | Hashtag posts |
|
|
491
|
+
| `list_place_posts` | Place posts |
|
|
492
|
+
| `list_reels` | Reels of a profile |
|
|
493
|
+
| `list_sound_posts` | Sound posts |
|
|
494
|
+
| `list_top_posts` | Top posts |
|
|
495
|
+
| `list_trending_posts` | Trending posts |
|
|
496
|
+
| `list_channel_posts` | Channel posts of a profile |
|
|
497
|
+
| `list_effect_posts` | Effect posts |
|
|
498
|
+
| `list_liked_posts` | Liked posts of a profile |
|
|
499
|
+
| `list_photos` | Photos of a profile |
|
|
500
|
+
| `list_playlist_posts` | Playlist posts |
|
|
501
|
+
| `list_playlist_stories` | Playlist stories |
|
|
502
|
+
| `list_playlist_tracks` | Playlist tracks |
|
|
503
|
+
| `list_podcast_episodes` | Podcast episodes |
|
|
504
|
+
| `list_tracks` | Tracks of a profile |
|
|
505
|
+
| `list_videos` | Videos of a profile |
|
|
506
|
+
| `list_followers` | Followers of a profile |
|
|
507
|
+
| `list_following` | Following of a profile |
|
|
508
|
+
| `list_similar_profiles` | Similar profiles of a profile |
|
|
509
|
+
| `get_comment` | Comment by link |
|
|
510
|
+
| `list_replies` | Replies of a post |
|
|
511
|
+
| `list_profile_comments` | Profile comments |
|
|
512
|
+
| `get_ad_transcript` | Ad transcript by link |
|
|
513
|
+
| `get_ad` | Ad by link |
|
|
514
|
+
| `list_ads` | Ads of a profile |
|
|
515
|
+
| `list_top_ads` | Top ads |
|
|
516
|
+
| `get_hashtag` | Hashtag by link |
|
|
517
|
+
| `list_trending_hashtags` | Trending hashtags |
|
|
518
|
+
| `get_community` | Community by link |
|
|
519
|
+
| `get_album` | Album by link |
|
|
520
|
+
| `get_product` | Product by link |
|
|
521
|
+
| `get_sound` | Sound by link |
|
|
522
|
+
| `get_download` | Download by link |
|
|
523
|
+
| `get_effect` | Effect by link |
|
|
524
|
+
| `get_embed` | Embed by link |
|
|
525
|
+
| `get_event` | Event by link |
|
|
526
|
+
| `get_live` | Live by handle |
|
|
527
|
+
| `get_place` | Place by link |
|
|
528
|
+
| `get_playlist` | Playlist by link |
|
|
529
|
+
| `get_podcast` | Podcast by link |
|
|
530
|
+
| `get_topic` | Topic by link |
|
|
531
|
+
| `get_username` | Username by handle |
|
|
532
|
+
| `list_events` | Events of a profile |
|
|
533
|
+
| `list_highlights` | Highlights of a profile |
|
|
534
|
+
| `list_place_events` | Place events |
|
|
535
|
+
| `list_playlists` | Playlists of a profile |
|
|
536
|
+
| `list_products` | Products of a profile |
|
|
537
|
+
| `list_reviews` | Reviews of a product |
|
|
538
|
+
| `list_schedule` | Schedule of a profile |
|
|
539
|
+
| `list_top_albums` | Top albums |
|
|
540
|
+
| `list_top_playlists` | Top playlists |
|
|
484
541
|
| `create_job` | Create a background job |
|
|
485
542
|
| `get_job` | Get a background job |
|
|
486
543
|
| `list_job_results` | List a job's results |
|
|
@@ -493,7 +550,7 @@ line), the agent tools, and `init`, which sets up coding agents.
|
|
|
493
550
|
```sh
|
|
494
551
|
npx socialtap tiktok profile --handle nasa
|
|
495
552
|
npx socialtap endpoints # every command, its params and price
|
|
496
|
-
npx socialtap tool find_endpoint '{"query":"
|
|
553
|
+
npx socialtap tool find_endpoint '{"query":"Exact follower and like counts, bio and country"}'
|
|
497
554
|
npx socialtap init # Claude Code, Codex, Cursor, Gemini CLI: the Agent Skill + the MCP server
|
|
498
555
|
```
|
|
499
556
|
|
|
@@ -504,6 +561,5 @@ config: Claude Code through `claude mcp add-json`, Codex's `config.toml`, Cursor
|
|
|
504
561
|
|
|
505
562
|
## Versioning
|
|
506
563
|
|
|
507
|
-
The version is derived from the API contract: major = API version, minor = the
|
|
508
|
-
|
|
509
|
-
edit it.
|
|
564
|
+
The version is derived from the API contract: major = API version, minor = the contract's revision (it grows
|
|
565
|
+
with every additive change, a new endpoint included), patch = the SDK generator's revision. Questions and bug reports: support@socialtap.dev.
|
package/dist/agents.d.ts
CHANGED
|
@@ -31,10 +31,12 @@ export interface Agent {
|
|
|
31
31
|
detect(env: SetupEnv): boolean;
|
|
32
32
|
/** The user-level skills directory it reads. */
|
|
33
33
|
skillsDir(env: SetupEnv): string;
|
|
34
|
-
/** Registers the server in its user config (replacing an earlier entry of that name); returns
|
|
34
|
+
/** Registers the server in its user config (replacing an earlier entry of that name); returns the file that holds it. */
|
|
35
35
|
addMcp(env: SetupEnv, server: McpServer): Promise<string>;
|
|
36
36
|
}
|
|
37
37
|
export declare const AGENTS: readonly Agent[];
|
|
38
|
+
/** Whether Claude Code's entry for this server sends a key today: `init` replacing it with a browser sign-in loses that. */
|
|
39
|
+
export declare function claudeHoldsKey(env: SetupEnv, name: string): Promise<boolean>;
|
|
38
40
|
/**
|
|
39
41
|
* The skills the site publishes: its Agent Skills discovery index (agentskills.io, schema 0.2.0), each SKILL.md
|
|
40
42
|
* fetched and checked against the index's sha256 digest.
|
package/dist/agents.js
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
import { execFile } from "node:child_process";
|
|
9
9
|
import { createHash } from "node:crypto";
|
|
10
10
|
import { existsSync } from "node:fs";
|
|
11
|
-
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
11
|
+
import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
|
|
12
12
|
import { join } from "node:path";
|
|
13
13
|
const bearer = (s) => (s.key ? { headers: { Authorization: `Bearer ${s.key}` } } : {});
|
|
14
14
|
/** The shared user skills directory (agentskills.io): Codex, Cursor and Gemini CLI read it. */
|
|
@@ -26,7 +26,11 @@ export const AGENTS = [
|
|
|
26
26
|
const r = await env.run("claude", ["mcp", "add-json", "--scope", "user", s.name, config]);
|
|
27
27
|
if (r.code !== 0)
|
|
28
28
|
throw new Error(`claude mcp add-json failed: ${(r.stderr || r.stdout).trim()}`);
|
|
29
|
-
|
|
29
|
+
// Its CLI wrote the file, and owns where it goes: a key in it is readable by the user only, where we find it.
|
|
30
|
+
const path = claudeConfig(env);
|
|
31
|
+
if (s.key)
|
|
32
|
+
await chmod(path, 0o600).catch(() => undefined);
|
|
33
|
+
return path;
|
|
30
34
|
},
|
|
31
35
|
},
|
|
32
36
|
{
|
|
@@ -68,6 +72,20 @@ export const AGENTS = [
|
|
|
68
72
|
},
|
|
69
73
|
},
|
|
70
74
|
];
|
|
75
|
+
/** Where Claude Code keeps its user-scoped MCP servers. */
|
|
76
|
+
function claudeConfig(env) {
|
|
77
|
+
return join(env.env.CLAUDE_CONFIG_DIR || env.home, ".claude.json");
|
|
78
|
+
}
|
|
79
|
+
/** Whether Claude Code's entry for this server sends a key today: `init` replacing it with a browser sign-in loses that. */
|
|
80
|
+
export async function claudeHoldsKey(env, name) {
|
|
81
|
+
try {
|
|
82
|
+
const config = JSON.parse(await readText(claudeConfig(env)));
|
|
83
|
+
return config.mcpServers?.[name]?.headers !== undefined;
|
|
84
|
+
}
|
|
85
|
+
catch {
|
|
86
|
+
return false;
|
|
87
|
+
}
|
|
88
|
+
}
|
|
71
89
|
function codexHome(env) {
|
|
72
90
|
return env.env.CODEX_HOME || join(env.home, ".codex");
|
|
73
91
|
}
|
|
@@ -122,10 +140,15 @@ async function readText(path) {
|
|
|
122
140
|
throw e;
|
|
123
141
|
}
|
|
124
142
|
}
|
|
125
|
-
/**
|
|
143
|
+
/**
|
|
144
|
+
* Writes a config file that can hold a secret, readable by the user only: an existing file's mode is tightened before the
|
|
145
|
+
* secret goes in (writeFile's mode applies only to a new file). In place, so a symlinked config stays one.
|
|
146
|
+
*/
|
|
126
147
|
async function writePrivate(path, text) {
|
|
127
148
|
await mkdir(join(path, ".."), { recursive: true });
|
|
128
|
-
await writeFile(path,
|
|
149
|
+
await writeFile(path, "", { mode: 0o600, flag: "a" });
|
|
150
|
+
await chmod(path, 0o600);
|
|
151
|
+
await writeFile(path, text);
|
|
129
152
|
}
|
|
130
153
|
/** Sets mcpServers[name] in a JSON config, keeping everything else; refuses a file that isn't plain JSON. */
|
|
131
154
|
async function setJsonServer(path, name, server) {
|
package/dist/ai.d.ts
CHANGED
|
@@ -3,11 +3,14 @@ import type { ClientOptions, Core } from "./core.ts";
|
|
|
3
3
|
export interface SocialtapToolsOptions extends ClientOptions {
|
|
4
4
|
/** The client whose key and settings the tools use (default: a new one from the other options). */
|
|
5
5
|
client?: Core;
|
|
6
|
-
/**
|
|
7
|
-
|
|
6
|
+
/**
|
|
7
|
+
* Which tools: these names, or "all" (default: DEFAULT_TOOLS, a small set whose call_endpoint reaches every
|
|
8
|
+
* endpoint, so the model's context isn't spent on tools it won't call).
|
|
9
|
+
*/
|
|
10
|
+
tools?: readonly string[] | "all";
|
|
8
11
|
}
|
|
9
12
|
/**
|
|
10
|
-
*
|
|
13
|
+
* The tools as AI SDK tools, keyed by name: `generateText({ model, tools: socialtapTools(), prompt })`. A tool's
|
|
11
14
|
* failure (an API error, a bad argument) is its output (`error` with `retryable` and `remediation`), so the model
|
|
12
15
|
* reads it; transport failures throw.
|
|
13
16
|
*/
|
package/dist/ai.js
CHANGED
|
@@ -3,16 +3,17 @@
|
|
|
3
3
|
// entry point imports it.
|
|
4
4
|
import { jsonSchema, tool } from "ai";
|
|
5
5
|
import { SocialTap } from "./client.js";
|
|
6
|
-
import { TOOLS } from "./tooldefs.js";
|
|
6
|
+
import { DEFAULT_TOOLS, TOOLS } from "./tooldefs.js";
|
|
7
7
|
import { callTool } from "./tools.js";
|
|
8
8
|
/**
|
|
9
|
-
*
|
|
9
|
+
* The tools as AI SDK tools, keyed by name: `generateText({ model, tools: socialtapTools(), prompt })`. A tool's
|
|
10
10
|
* failure (an API error, a bad argument) is its output (`error` with `retryable` and `remediation`), so the model
|
|
11
11
|
* reads it; transport failures throw.
|
|
12
12
|
*/
|
|
13
13
|
export function socialtapTools(options = {}) {
|
|
14
|
-
const { client: given, tools:
|
|
14
|
+
const { client: given, tools: chosen, ...clientOptions } = options;
|
|
15
15
|
const client = given ?? new SocialTap(clientOptions);
|
|
16
|
+
const only = chosen === "all" ? null : (chosen ?? DEFAULT_TOOLS);
|
|
16
17
|
const out = {};
|
|
17
18
|
for (const def of TOOLS) {
|
|
18
19
|
if (only && !only.includes(def.name))
|
package/dist/cli.d.ts
CHANGED
|
@@ -3,6 +3,8 @@ import { type SetupEnv } from "./agents.ts";
|
|
|
3
3
|
export interface IO extends SetupEnv {
|
|
4
4
|
out(text: string): void;
|
|
5
5
|
err(text: string): void;
|
|
6
|
+
/** Whether a person is at this terminal (who can finish a browser sign-in). */
|
|
7
|
+
interactive?: boolean;
|
|
6
8
|
}
|
|
7
9
|
export declare function processIO(): IO;
|
|
8
10
|
/** Runs the CLI; returns the exit code. */
|