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 CHANGED
@@ -2,18 +2,25 @@
2
2
 
3
3
  # SocialTap for TypeScript
4
4
 
5
- Social media scraper API. Any link in. Clean JSON out. Generated from the SocialTap catalog (version 1.453.20); docs: https://socialtap.dev/docs.
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). ESM only. Params and
14
- models use the API's snake_case names; SDK objects (options, `credits`, errors) are camelCase.
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
- Nothing is invented (ADR 0007): `null` means unknown. With `fields`, results are typed `PartialModel<T>` (every member may
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: Public TikTok profile and follower counts
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; 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; 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; 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; 2 credits + 2 per started minute of media |
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; 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; 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; 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; 2 credits + 2 per started minute of media |
156
- | `instagram.trending_posts` | `client.instagram.trendingPosts.list()` | 1 credit; 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; 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; 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; 2 credits + 2 per started minute of media |
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; 2 credits + 2 per started minute of media |
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; 1 credit |
198
- | `soundcloud.track` | `client.soundcloud.track.get()` | 1 credit; 1 credit |
199
- | `soundcloud.tracks` | `client.soundcloud.tracks.list()` | 1 credit; 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; 1 credit |
205
- | `threads.post` | `client.threads.post.get()` | 1 credit; 1 credit |
206
- | `threads.posts` | `client.threads.posts.list()` | 1 credit; 1 credit |
207
- | `threads.profile` | `client.threads.profile.get()` | 1 credit; 1 credit |
208
- | `threads.search_posts` | `client.threads.searchPosts.list()` | 1 credit; 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; 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; 2 credits + 2 per started minute of media |
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; 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; 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; 2 credits + 2 per started minute of media |
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 URL or ID; do not retry.
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 (default 300 s). Both are client and per-request options.
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.bluesky.comments.iterate({ url: "https://bsky.app/profile/atproto.com/post/3moduzldxr22q" }, { maxPages: 10, maxCredits: 100 });
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): every tool, or socialtapTools({ tools: [...] }).
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: "Public TikTok profile and follower counts" });
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":"Public TikTok profile and follower counts"}'
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 number of public contract facts
504
- (it grows with every additive change), patch = generator revision. This package is generated: report issues, don't
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 what changed. */
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
- return "claude mcp add-json --scope user (~/.claude.json)";
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
- /** Writes a config file that holds a secret: a new file is readable by the user only (an existing one keeps its mode). */
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, text, { mode: 0o600 });
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
- /** Only these tools (default: every tool). */
7
- tools?: readonly string[];
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
- * Every tool as an AI SDK tool, keyed by name: `generateText({ model, tools: socialtapTools(), prompt })`. A tool's
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
- * Every tool as an AI SDK tool, keyed by name: `generateText({ model, tools: socialtapTools(), prompt })`. A tool's
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: only, ...clientOptions } = options;
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. */