socialtap 1.453.20 → 1.484.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 +153 -93
- 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 +6514 -4775
- 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,18 +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
|
+
|
|
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.484.27). Docs: https://socialtap.dev/docs.
|
|
6
9
|
|
|
7
10
|
## Install
|
|
8
11
|
|
|
9
12
|
```sh
|
|
10
13
|
npm install socialtap
|
|
14
|
+
npm pkg set type=module # the examples are ES modules (or name your file .mjs or .mts)
|
|
11
15
|
```
|
|
12
16
|
|
|
13
|
-
Zero runtime dependencies (`fetch`); Node 20.3+, Deno, Bun and Cloudflare Workers (server-side: the API key is a secret).
|
|
14
|
-
|
|
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.
|
|
15
22
|
|
|
16
|
-
|
|
23
|
+
`null` means unknown. With `fields`, results are typed `PartialModel<T>` (every member may
|
|
17
24
|
be absent). A 2xx that is not the API's envelope (no `data`, not JSON) throws `APIDecodeError`; a `retry-after` longer than
|
|
18
25
|
`MAX_RETRY_AFTER_S` throws `RetryAfterExceededError` instead of retrying early. Results keep the API's objects as sent,
|
|
19
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`.
|
|
@@ -21,9 +28,9 @@ members this version doesn't model included. `Event` is a union narrowed by `typ
|
|
|
21
28
|
## Authenticate
|
|
22
29
|
|
|
23
30
|
The client reads your API key from `SOCIALTAP_API_KEY`, or takes it as an option. Requests send it in the
|
|
24
|
-
`x-api-key` header.
|
|
31
|
+
`x-api-key` header. Get a key at https://socialtap.dev/signup/: every account starts with 100 free credits.
|
|
25
32
|
|
|
26
|
-
## First call:
|
|
33
|
+
## First call: Exact follower and like counts, bio and country
|
|
27
34
|
|
|
28
35
|
```ts
|
|
29
36
|
import { SocialTap } from "socialtap";
|
|
@@ -90,10 +97,20 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
90
97
|
|
|
91
98
|
| endpoint | method | cost |
|
|
92
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 |
|
|
93
110
|
| `bluesky.comments` | `client.bluesky.comments.list()` | 1 credit |
|
|
94
111
|
| `bluesky.post` | `client.bluesky.post.get()` | 1 credit |
|
|
95
112
|
| `bluesky.posts` | `client.bluesky.posts.list()` | 1 credit |
|
|
96
|
-
| `bluesky.profile` | `client.bluesky.profile.get()` | 1 credit
|
|
113
|
+
| `bluesky.profile` | `client.bluesky.profile.get()` | 1 credit |
|
|
97
114
|
| `bluesky.search_posts` | `client.bluesky.searchPosts.list()` | 1 credit |
|
|
98
115
|
| `facebook.ad` | `client.facebook.ad.get()` | 1 credit |
|
|
99
116
|
| `facebook.ad_transcript` | `client.facebook.adTranscript.get()` | 2 credits + 2 per started minute of media |
|
|
@@ -104,7 +121,7 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
104
121
|
| `facebook.events` | `client.facebook.events.list()` | 1 credit |
|
|
105
122
|
| `facebook.group` | `client.facebook.group.get()` | 1 credit |
|
|
106
123
|
| `facebook.group_posts` | `client.facebook.groupPosts.list()` | 1 credit |
|
|
107
|
-
| `facebook.listing` | `client.facebook.listing.get()` | 1 credit
|
|
124
|
+
| `facebook.listing` | `client.facebook.listing.get()` | 1 credit |
|
|
108
125
|
| `facebook.photos` | `client.facebook.photos.list()` | 1 credit |
|
|
109
126
|
| `facebook.place_events` | `client.facebook.placeEvents.list()` | 1 credit |
|
|
110
127
|
| `facebook.post` | `client.facebook.post.get()` | 1 credit |
|
|
@@ -116,11 +133,11 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
116
133
|
| `facebook.search_advertisers` | `client.facebook.searchAdvertisers.list()` | 1 credit |
|
|
117
134
|
| `facebook.search_events` | `client.facebook.searchEvents.list()` | 1 credit |
|
|
118
135
|
| `facebook.search_groups` | `client.facebook.searchGroups.list()` | 1 credit + 1 per result filled in |
|
|
119
|
-
| `facebook.search_listings` | `client.facebook.searchListings.list()` | 1 credit
|
|
136
|
+
| `facebook.search_listings` | `client.facebook.searchListings.list()` | 1 credit |
|
|
120
137
|
| `facebook.search_places` | `client.facebook.searchPlaces.list()` | 1 credit |
|
|
121
138
|
| `facebook.search_posts` | `client.facebook.searchPosts.list()` | 1 credit + 1 per result filled in |
|
|
122
139
|
| `facebook.search_profiles` | `client.facebook.searchProfiles.list()` | 1 credit + 1 per result filled in |
|
|
123
|
-
| `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) |
|
|
124
141
|
| `google.ad` | `client.google.ad.get()` | 1 credit |
|
|
125
142
|
| `google.ads` | `client.google.ads.list()` | 1 credit |
|
|
126
143
|
| `google.advertiser` | `client.google.advertiser.get()` | 1 credit |
|
|
@@ -129,10 +146,10 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
129
146
|
| `google.search_suggestions` | `client.google.searchSuggestions.list()` | 1 credit |
|
|
130
147
|
| `instagram.comment` | `client.instagram.comment.get()` | 1 credit |
|
|
131
148
|
| `instagram.comments` | `client.instagram.comments.list()` | 1 credit |
|
|
132
|
-
| `instagram.embed` | `client.instagram.embed.get()` | 1 credit
|
|
149
|
+
| `instagram.embed` | `client.instagram.embed.get()` | 1 credit |
|
|
133
150
|
| `instagram.engagement` | `client.instagram.engagement.get()` | 1 credit |
|
|
134
151
|
| `instagram.hashtag` | `client.instagram.hashtag.get()` | 1 credit |
|
|
135
|
-
| `instagram.hashtag_posts` | `client.instagram.hashtagPosts.list()` | 1 credit
|
|
152
|
+
| `instagram.hashtag_posts` | `client.instagram.hashtagPosts.list()` | 1 credit |
|
|
136
153
|
| `instagram.highlights` | `client.instagram.highlights.list()` | 1 credit |
|
|
137
154
|
| `instagram.place` | `client.instagram.place.get()` | 1 credit |
|
|
138
155
|
| `instagram.place_posts` | `client.instagram.placePosts.list()` | 1 credit |
|
|
@@ -143,7 +160,7 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
143
160
|
| `instagram.reels` | `client.instagram.reels.list()` | 1 credit |
|
|
144
161
|
| `instagram.search_hashtags` | `client.instagram.searchHashtags.list()` | 1 credit |
|
|
145
162
|
| `instagram.search_places` | `client.instagram.searchPlaces.list()` | 1 credit + 1 per result filled in |
|
|
146
|
-
| `instagram.search_posts` | `client.instagram.searchPosts.list()` | 1 credit
|
|
163
|
+
| `instagram.search_posts` | `client.instagram.searchPosts.list()` | 1 credit |
|
|
147
164
|
| `instagram.search_profiles` | `client.instagram.searchProfiles.list()` | 1 credit + 1 per result filled in |
|
|
148
165
|
| `instagram.search_sounds` | `client.instagram.searchSounds.list()` | 1 credit + 1 per result filled in |
|
|
149
166
|
| `instagram.search_suggestions` | `client.instagram.searchSuggestions.list()` | 1 credit |
|
|
@@ -152,10 +169,10 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
152
169
|
| `instagram.sound_posts` | `client.instagram.soundPosts.list()` | 1 credit |
|
|
153
170
|
| `instagram.story` | `client.instagram.story.get()` | 1 credit |
|
|
154
171
|
| `instagram.topic` | `client.instagram.topic.get()` | 1 credit |
|
|
155
|
-
| `instagram.transcript` | `client.instagram.transcript.get()` | 1 credit
|
|
156
|
-
| `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 |
|
|
157
174
|
| `instagram.username` | `client.instagram.username.get()` | 1 credit |
|
|
158
|
-
| `kick.post` | `client.kick.post.get()` | 1 credit
|
|
175
|
+
| `kick.post` | `client.kick.post.get()` | 1 credit |
|
|
159
176
|
| `kick.transcript` | `client.kick.transcript.get()` | 2 credits + 2 per started minute of media |
|
|
160
177
|
| `komi.page` | `client.komi.page.get()` | 1 credit |
|
|
161
178
|
| `kwai.post` | `client.kwai.post.get()` | 1 credit |
|
|
@@ -164,11 +181,11 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
164
181
|
| `linkbio.profile` | `client.linkbio.profile.get()` | 1 credit |
|
|
165
182
|
| `linkedin.ad` | `client.linkedin.ad.get()` | 1 credit |
|
|
166
183
|
| `linkedin.post` | `client.linkedin.post.get()` | 1 credit |
|
|
167
|
-
| `linkedin.profile` | `client.linkedin.profile.get()` | 1 credit |
|
|
184
|
+
| `linkedin.profile` | `client.linkedin.profile.get()` | 1 credit (public page or web search) or 5 credits (data partner) |
|
|
168
185
|
| `linkedin.search_ads` | `client.linkedin.searchAds.list()` | 1 credit |
|
|
169
186
|
| `linkedin.search_posts` | `client.linkedin.searchPosts.list()` | 1 credit + 1 per result filled in |
|
|
170
187
|
| `linkedin.search_profiles` | `client.linkedin.searchProfiles.list()` | 1 credit + 1 per result filled in |
|
|
171
|
-
| `linkme.profile` | `client.linkme.profile.get()` | 1 credit
|
|
188
|
+
| `linkme.profile` | `client.linkme.profile.get()` | 1 credit |
|
|
172
189
|
| `linktree.profile` | `client.linktree.profile.get()` | 1 credit |
|
|
173
190
|
| `pillar.page` | `client.pillar.page.get()` | 1 credit |
|
|
174
191
|
| `reddit.comments` | `client.reddit.comments.list()` | 1 credit |
|
|
@@ -183,38 +200,53 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
183
200
|
| `reddit.search_subreddits` | `client.reddit.searchSubreddits.list()` | 1 credit |
|
|
184
201
|
| `reddit.subreddit` | `client.reddit.subreddit.get()` | 1 credit |
|
|
185
202
|
| `reddit.subreddit_posts` | `client.reddit.subredditPosts.list()` | 1 credit |
|
|
186
|
-
| `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) |
|
|
187
204
|
| `rumble.comments` | `client.rumble.comments.list()` | 1 credit |
|
|
188
205
|
| `rumble.engagement` | `client.rumble.engagement.get()` | 1 credit |
|
|
189
206
|
| `rumble.post` | `client.rumble.post.get()` | 1 credit |
|
|
190
207
|
| `rumble.posts` | `client.rumble.posts.list()` | 1 credit |
|
|
191
208
|
| `rumble.profile` | `client.rumble.profile.get()` | 1 credit |
|
|
192
209
|
| `rumble.search_posts` | `client.rumble.searchPosts.list()` | 1 credit |
|
|
193
|
-
| `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) |
|
|
194
211
|
| `snapchat.comments` | `client.snapchat.comments.list()` | 1 credit |
|
|
195
212
|
| `snapchat.profile` | `client.snapchat.profile.get()` | 1 credit |
|
|
196
213
|
| `snapchat.spotlight` | `client.snapchat.spotlight.get()` | 1 credit |
|
|
197
|
-
| `soundcloud.artist` | `client.soundcloud.artist.get()` | 1 credit
|
|
198
|
-
| `soundcloud.track` | `client.soundcloud.track.get()` | 1 credit
|
|
199
|
-
| `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 |
|
|
200
229
|
| `telegram.channel` | `client.telegram.channel.get()` | 1 credit |
|
|
201
230
|
| `telegram.channel_posts` | `client.telegram.channelPosts.list()` | 1 credit |
|
|
202
231
|
| `telegram.post` | `client.telegram.post.get()` | 1 credit |
|
|
203
232
|
| `telegram.search_channels` | `client.telegram.searchChannels.list()` | 1 credit + 1 per result filled in |
|
|
204
|
-
| `threads.comments` | `client.threads.comments.list()` | 1 credit
|
|
205
|
-
| `threads.post` | `client.threads.post.get()` | 1 credit
|
|
206
|
-
| `threads.posts` | `client.threads.posts.list()` | 1 credit
|
|
207
|
-
| `threads.profile` | `client.threads.profile.get()` | 1 credit
|
|
208
|
-
| `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 |
|
|
209
238
|
| `threads.search_profiles` | `client.threads.searchProfiles.list()` | 1 credit |
|
|
210
239
|
| `tiktok.ad` | `client.tiktok.ad.get()` | 1 credit |
|
|
211
240
|
| `tiktok.comment` | `client.tiktok.comment.get()` | 1 credit |
|
|
212
241
|
| `tiktok.comments` | `client.tiktok.comments.list()` | 1 credit |
|
|
213
|
-
| `tiktok.download` | `client.tiktok.download.get()` | 1 credit
|
|
242
|
+
| `tiktok.download` | `client.tiktok.download.get()` | 1 credit |
|
|
214
243
|
| `tiktok.effect` | `client.tiktok.effect.get()` | 1 credit |
|
|
215
244
|
| `tiktok.effect_posts` | `client.tiktok.effectPosts.list()` | 1 credit |
|
|
216
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 |
|
|
217
248
|
| `tiktok.hashtag` | `client.tiktok.hashtag.get()` | 1 credit |
|
|
249
|
+
| `tiktok.hashtag_posts` | `client.tiktok.hashtagPosts.list()` | 1 credit |
|
|
218
250
|
| `tiktok.liked_posts` | `client.tiktok.likedPosts.list()` | 1 credit |
|
|
219
251
|
| `tiktok.live` | `client.tiktok.live.get()` | 1 credit |
|
|
220
252
|
| `tiktok.place_posts` | `client.tiktok.placePosts.list()` | 1 credit |
|
|
@@ -234,13 +266,13 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
234
266
|
| `tiktok.sound_posts` | `client.tiktok.soundPosts.list()` | 1 credit |
|
|
235
267
|
| `tiktok.top_ads` | `client.tiktok.topAds.list()` | 1 credit |
|
|
236
268
|
| `tiktok.top_posts` | `client.tiktok.topPosts.list()` | 1 credit |
|
|
237
|
-
| `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) |
|
|
238
270
|
| `tiktok.trending_hashtags` | `client.tiktok.trendingHashtags.list()` | 1 credit |
|
|
239
271
|
| `tiktok.trending_posts` | `client.tiktok.trendingPosts.list()` | 1 credit |
|
|
240
272
|
| `tiktokshop.product` | `client.tiktokshop.product.get()` | 1 credit |
|
|
241
273
|
| `tiktokshop.products` | `client.tiktokshop.products.list()` | 1 credit |
|
|
242
274
|
| `tiktokshop.reviews` | `client.tiktokshop.reviews.list()` | 1 credit |
|
|
243
|
-
| `tiktokshop.search_products` | `client.tiktokshop.searchProducts.list()` | 1 credit
|
|
275
|
+
| `tiktokshop.search_products` | `client.tiktokshop.searchProducts.list()` | 1 credit |
|
|
244
276
|
| `truthsocial.post` | `client.truthsocial.post.get()` | 1 credit |
|
|
245
277
|
| `truthsocial.posts` | `client.truthsocial.posts.list()` | 1 credit |
|
|
246
278
|
| `truthsocial.profile` | `client.truthsocial.profile.get()` | 1 credit |
|
|
@@ -258,10 +290,22 @@ Every result also carries the envelope `meta` (request ID, source, cache status,
|
|
|
258
290
|
| `x.search_profiles` | `client.x.searchProfiles.list()` | 1 credit + 1 per result filled in |
|
|
259
291
|
| `youtube.comments` | `client.youtube.comments.list()` | 1 credit |
|
|
260
292
|
| `youtube.engagement` | `client.youtube.engagement.get()` | 1 credit |
|
|
261
|
-
| `youtube.post` | `client.youtube.post.get()` | 1 credit
|
|
293
|
+
| `youtube.post` | `client.youtube.post.get()` | 1 credit |
|
|
262
294
|
| `youtube.posts` | `client.youtube.posts.list()` | 1 credit |
|
|
263
295
|
| `youtube.profile` | `client.youtube.profile.get()` | 1 credit |
|
|
264
|
-
| `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
|
+
```
|
|
265
309
|
|
|
266
310
|
## Errors
|
|
267
311
|
|
|
@@ -276,7 +320,7 @@ try {
|
|
|
276
320
|
await client.tiktok.profile.get({ handle: "nasa" });
|
|
277
321
|
} catch (err) {
|
|
278
322
|
if (err instanceof NotFoundError) {
|
|
279
|
-
// Check the
|
|
323
|
+
// Check the link or ID. Do not retry.
|
|
280
324
|
} else if (err instanceof APIError) {
|
|
281
325
|
console.error(err.code, err.status, err.retryable, err.remediation, err.requestId);
|
|
282
326
|
} else throw err;
|
|
@@ -292,6 +336,7 @@ try {
|
|
|
292
336
|
| `insufficient_credits` | `InsufficientCreditsError` | 402 | no |
|
|
293
337
|
| `spend_limit_reached` | `SpendLimitReachedError` | 402 | no |
|
|
294
338
|
| `rate_limited` | `RateLimitedError` | 429 | yes |
|
|
339
|
+
| `request_too_large` | `RequestTooLargeError` | 413 | no |
|
|
295
340
|
| `method_not_allowed` | `MethodNotAllowedError` | 405 | no |
|
|
296
341
|
| `endpoint_retired` | `EndpointRetiredError` | 410 | no |
|
|
297
342
|
| `idempotency_key_reused` | `IdempotencyKeyReusedError` | 422 | no |
|
|
@@ -313,7 +358,9 @@ try {
|
|
|
313
358
|
Retryable failures (the codes above, connection errors, timeouts) are retried 2 times by default with
|
|
314
359
|
exponential backoff and jitter, honoring `retry-after`. A GET retry sends `max_age` set to the seconds since the first
|
|
315
360
|
attempt: if the first response was lost in transit, the retry is served free from the cache. Timeouts are per
|
|
316
|
-
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`.
|
|
317
364
|
|
|
318
365
|
## Pagination
|
|
319
366
|
|
|
@@ -323,7 +370,7 @@ stopped it) and `endReason` (the API's `page.end_reason`) say what happened.
|
|
|
323
370
|
Each page is checked against its catalog price before it is fetched, and an empty page with `has_more` is not the end.
|
|
324
371
|
|
|
325
372
|
```ts
|
|
326
|
-
const items = client.
|
|
373
|
+
const items = client.applemusic.searchAlbums.iterate({ query: "lover" }, { maxPages: 10, maxCredits: 100 });
|
|
327
374
|
for await (const item of items) {
|
|
328
375
|
console.log(item);
|
|
329
376
|
}
|
|
@@ -353,7 +400,10 @@ console.log(res.data, res.meta.request_id);
|
|
|
353
400
|
| `usage.rate.list` | `client.usage.rate.list(params)` | `account:read` |
|
|
354
401
|
| `credit_transactions.list` | `client.creditTransactions.list(params)` | `account:read` |
|
|
355
402
|
| `billing.checkout.get` | `client.billing.checkout.get(id)` | `account:read` |
|
|
403
|
+
| `billing.subscription.get` | `client.billing.subscription.get()` | `account:read` |
|
|
356
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` |
|
|
357
407
|
| `requests.list` | `client.requests.list(params)` | `account:read` |
|
|
358
408
|
| `requests.get` | `client.requests.get(id)` | `account:read` |
|
|
359
409
|
| `requests.get_response` | `client.requests.getResponse(id)` | `account:read` |
|
|
@@ -406,7 +456,8 @@ continue, and failures returned as the tool's output (`error` with `retryable` a
|
|
|
406
456
|
act on them. Transport failures raise as for any request, and tools that may be repeated are retried.
|
|
407
457
|
|
|
408
458
|
```ts
|
|
409
|
-
// 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" }).
|
|
410
461
|
import { generateText, stepCountIs } from "ai";
|
|
411
462
|
import { socialtapTools } from "socialtap/ai";
|
|
412
463
|
|
|
@@ -416,67 +467,77 @@ const { text } = await generateText({ model, tools: socialtapTools(), stopWhen:
|
|
|
416
467
|
// Any other tool-calling API: hand TOOLS (name, description, inputSchema) to the model, run its calls with callTool.
|
|
417
468
|
import { SocialTap, TOOLS, callTool } from "socialtap";
|
|
418
469
|
|
|
419
|
-
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" });
|
|
420
471
|
console.log(r.isError, r.output);
|
|
421
472
|
```
|
|
422
473
|
|
|
423
474
|
| tool | what it does |
|
|
424
475
|
|---|---|
|
|
425
|
-
| `get_ad` | Get an ad |
|
|
426
|
-
| `get_ad_transcript` | Get an ad transcript |
|
|
427
|
-
| `get_comment` | Get a comment |
|
|
428
|
-
| `get_community` | Get a community |
|
|
429
|
-
| `get_download` | Get a download |
|
|
430
|
-
| `get_effect` | Get an effect |
|
|
431
|
-
| `get_embed` | Get an embed |
|
|
432
|
-
| `get_engagement` | Get an engagement |
|
|
433
|
-
| `get_event` | Get an event |
|
|
434
|
-
| `get_hashtag` | Get a hashtag |
|
|
435
|
-
| `get_live` | Get a live |
|
|
436
|
-
| `get_place` | Get a place |
|
|
437
|
-
| `get_post` | Get a post |
|
|
438
|
-
| `get_product` | Get a product |
|
|
439
|
-
| `get_profile` | Get a profile |
|
|
440
|
-
| `get_sound` | Get a sound |
|
|
441
|
-
| `get_story` | Get a story |
|
|
442
|
-
| `get_topic` | Get a topic |
|
|
443
|
-
| `get_transcript` | Get a transcript |
|
|
444
|
-
| `get_username` | Get a username |
|
|
445
|
-
| `list_ads` | List ads |
|
|
446
|
-
| `list_channel_posts` | List channel posts |
|
|
447
|
-
| `list_comments` | List comments |
|
|
448
|
-
| `list_community_posts` | List community posts |
|
|
449
|
-
| `list_effect_posts` | List effect posts |
|
|
450
|
-
| `list_events` | List events |
|
|
451
|
-
| `list_hashtag_posts` | List hashtag posts |
|
|
452
|
-
| `list_highlights` | List highlights |
|
|
453
|
-
| `list_liked_posts` | List liked posts |
|
|
454
|
-
| `list_photos` | List photos |
|
|
455
|
-
| `list_place_events` | List place events |
|
|
456
|
-
| `list_place_posts` | List place posts |
|
|
457
|
-
| `list_playlist_posts` | List playlist posts |
|
|
458
|
-
| `list_playlist_stories` | List playlist stories |
|
|
459
|
-
| `list_playlists` | List playlists |
|
|
460
|
-
| `list_posts` | List posts |
|
|
461
|
-
| `list_products` | List products |
|
|
462
|
-
| `list_profile_comments` | List profile comments |
|
|
463
|
-
| `list_reels` | List reels |
|
|
464
|
-
| `list_replies` | List replies |
|
|
465
|
-
| `list_reviews` | List reviews |
|
|
466
|
-
| `list_schedule` | List schedule |
|
|
467
|
-
| `list_similar_profiles` | List similar profiles |
|
|
468
|
-
| `list_sound_posts` | List sound posts |
|
|
469
|
-
| `list_top_ads` | List top ads |
|
|
470
|
-
| `list_top_posts` | List top posts |
|
|
471
|
-
| `list_tracks` | List tracks |
|
|
472
|
-
| `list_trending_hashtags` | List trending hashtags |
|
|
473
|
-
| `list_trending_posts` | List trending posts |
|
|
474
|
-
| `list_videos` | List videos |
|
|
475
|
-
| `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 |
|
|
476
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 |
|
|
477
485
|
| `search_docs` | Search the docs |
|
|
478
486
|
| `read_doc` | Read a docs page |
|
|
479
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 |
|
|
480
541
|
| `create_job` | Create a background job |
|
|
481
542
|
| `get_job` | Get a background job |
|
|
482
543
|
| `list_job_results` | List a job's results |
|
|
@@ -489,7 +550,7 @@ line), the agent tools, and `init`, which sets up coding agents.
|
|
|
489
550
|
```sh
|
|
490
551
|
npx socialtap tiktok profile --handle nasa
|
|
491
552
|
npx socialtap endpoints # every command, its params and price
|
|
492
|
-
npx socialtap tool find_endpoint '{"query":"
|
|
553
|
+
npx socialtap tool find_endpoint '{"query":"Exact follower and like counts, bio and country"}'
|
|
493
554
|
npx socialtap init # Claude Code, Codex, Cursor, Gemini CLI: the Agent Skill + the MCP server
|
|
494
555
|
```
|
|
495
556
|
|
|
@@ -500,6 +561,5 @@ config: Claude Code through `claude mcp add-json`, Codex's `config.toml`, Cursor
|
|
|
500
561
|
|
|
501
562
|
## Versioning
|
|
502
563
|
|
|
503
|
-
The version is derived from the API contract: major = API version, minor = the
|
|
504
|
-
|
|
505
|
-
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. */
|