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 CHANGED
@@ -2,22 +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.19); 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
6
 
7
- ## Install
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
- Not published to npm yet: install it from source, a checkout of the SocialTap repository (this directory is
10
- `sdk/typescript`).
10
+ ## Install
11
11
 
12
12
  ```sh
13
- (cd sdk/typescript && npm ci && npm run build)
14
- npm install ./sdk/typescript # from your project, with the path to the checkout
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). ESM only. Params and
18
- 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.
19
22
 
20
- 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
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: Public TikTok profile and follower counts
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; 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; 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; 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; 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) |
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; 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; 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; 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; 2 credits + 2 per started minute of media |
160
- | `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 |
161
174
  | `instagram.username` | `client.instagram.username.get()` | 1 credit |
162
- | `kick.post` | `client.kick.post.get()` | 1 credit; 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; 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; 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) |
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; 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) |
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; 1 credit |
202
- | `soundcloud.track` | `client.soundcloud.track.get()` | 1 credit; 1 credit |
203
- | `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 |
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; 1 credit |
209
- | `threads.post` | `client.threads.post.get()` | 1 credit; 1 credit |
210
- | `threads.posts` | `client.threads.posts.list()` | 1 credit; 1 credit |
211
- | `threads.profile` | `client.threads.profile.get()` | 1 credit; 1 credit |
212
- | `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 |
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; 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; 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) |
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; 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; 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; 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
+ ```
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 URL or ID; do not retry.
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 (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`.
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.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 });
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): 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" }).
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: "Public TikTok profile and follower counts" });
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":"Public TikTok profile and follower counts"}'
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 number of public contract facts
508
- (it grows with every additive change), patch = generator revision. This package is generated: report issues, don't
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 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. */