socialtap 0.0.1 → 1.453.20

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Divergent Ventures LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,505 @@
1
- # socialtap
1
+ <!-- Code generated by engine/cmd/gensdk (make gen) from catalog/catalog.gen.json; DO NOT EDIT. -->
2
2
 
3
- Reserved for the [SocialTap](https://socialtap.dev) API client. The first release is on its way.
3
+ # SocialTap for TypeScript
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.
6
+
7
+ ## Install
8
+
9
+ ```sh
10
+ npm install socialtap
11
+ ```
12
+
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.
15
+
16
+ Nothing is invented (ADR 0007): `null` means unknown. With `fields`, results are typed `PartialModel<T>` (every member may
17
+ be absent). A 2xx that is not the API's envelope (no `data`, not JSON) throws `APIDecodeError`; a `retry-after` longer than
18
+ `MAX_RETRY_AFTER_S` throws `RetryAfterExceededError` instead of retrying early. Results keep the API's objects as sent,
19
+ members this version doesn't model included. `Event` is a union narrowed by `type`; a job item's `params` are typed by its `endpoint`.
20
+
21
+ ## Authenticate
22
+
23
+ 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.
25
+
26
+ ## First call: Public TikTok profile and follower counts
27
+
28
+ ```ts
29
+ import { SocialTap } from "socialtap";
30
+
31
+ const client = new SocialTap(); // apiKey defaults to process.env.SOCIALTAP_API_KEY
32
+
33
+ const res = await client.tiktok.profile.get({ handle: "nasa" });
34
+ console.log(res.data);
35
+ console.log(res.credits.charged, res.meta.request_id);
36
+ ```
37
+
38
+ `data` is a `Profile` (example response, truncated):
39
+
40
+ ```json
41
+ {
42
+ "approximate_fields": [],
43
+ "avatar_url": "https://p19-common-sign.tiktokcdn-us.com/tos-useast5-avt-0068-tx/e5143212a59c09a008bf50f487d54d1f~tplv-tiktokx-cropcenter:1080:1080.jpeg?dr=9640\u0026refresh_token=29840d4e\u0026x-expires=4070908800\u0026x-signature=SCRUBBED\u0026t=4d5b0474\u0026ps=13740610\u0026shp=a5d48078\u0026shcp=81f88b70\u0026idc=useast5",
44
+ "banner_url": null,
45
+ "bio": "Making the seemingly impossible, possible.✨",
46
+ "category": null,
47
+ "country_code": "US",
48
+ "created_at": "2026-07-20T15:55:49Z",
49
+ "display_name": "NASA",
50
+ "external_links": [
51
+ {
52
+ "title": null,
53
+ "url": "https://science.nasa.gov/feature/artemis-ii-preliminary-lunar-science-report"
54
+ }
55
+ ],
56
+ "id": "7664638705177150477",
57
+ "is_private": false,
58
+ "is_verified": true,
59
+ "location": null,
60
+ "metrics": {
61
+ "follower_count": 2152843,
62
+ "following_count": 23,
63
+ "post_count": 62,
64
+ "total_like_count": 11486661,
65
+ "total_view_count": null
66
+ },
67
+ "platform": "tiktok",
68
+ "platform_specific": {
69
+ "tiktok": {
70
+ "display_name_changed_at": "2026-07-20T15:58:00Z",
71
+ "friend_count": 17,
72
+ "is_business_account": false,
73
+ "is_shop_seller": false,
74
+ "language": "en",
75
+ "liked_post_count": null,
76
+ "sec_uid": "MS4wLjABAAAAU9BRVzC8oCaegVnia8IbqWhPb_-dbU7s00Y3wS1_Nx8g5RUaYvyXrpejgjdxTwd6"
77
+ }
78
+ },
79
+ "type": "organization",
80
+ "unknown_fields": [],
81
+ "url": "https://www.tiktok.com/@nasa",
82
+ "username": "nasa"
83
+ }
84
+ ```
85
+
86
+ Every result also carries the envelope `meta` (request ID, source, cache status, fetch time) and `credits`
87
+ (charged by this request, and the balance after it when the API reports it). Failed requests and cache hits are free.
88
+
89
+ ## Endpoints
90
+
91
+ | endpoint | method | cost |
92
+ |---|---|---|
93
+ | `bluesky.comments` | `client.bluesky.comments.list()` | 1 credit |
94
+ | `bluesky.post` | `client.bluesky.post.get()` | 1 credit |
95
+ | `bluesky.posts` | `client.bluesky.posts.list()` | 1 credit |
96
+ | `bluesky.profile` | `client.bluesky.profile.get()` | 1 credit; 1 credit |
97
+ | `bluesky.search_posts` | `client.bluesky.searchPosts.list()` | 1 credit |
98
+ | `facebook.ad` | `client.facebook.ad.get()` | 1 credit |
99
+ | `facebook.ad_transcript` | `client.facebook.adTranscript.get()` | 2 credits + 2 per started minute of media |
100
+ | `facebook.ads` | `client.facebook.ads.list()` | 1 credit |
101
+ | `facebook.comments` | `client.facebook.comments.list()` | 1 credit |
102
+ | `facebook.engagement` | `client.facebook.engagement.get()` | 1 credit |
103
+ | `facebook.event` | `client.facebook.event.get()` | 1 credit |
104
+ | `facebook.events` | `client.facebook.events.list()` | 1 credit |
105
+ | `facebook.group` | `client.facebook.group.get()` | 1 credit |
106
+ | `facebook.group_posts` | `client.facebook.groupPosts.list()` | 1 credit |
107
+ | `facebook.listing` | `client.facebook.listing.get()` | 1 credit; 1 credit |
108
+ | `facebook.photos` | `client.facebook.photos.list()` | 1 credit |
109
+ | `facebook.place_events` | `client.facebook.placeEvents.list()` | 1 credit |
110
+ | `facebook.post` | `client.facebook.post.get()` | 1 credit |
111
+ | `facebook.posts` | `client.facebook.posts.list()` | 1 credit |
112
+ | `facebook.profile` | `client.facebook.profile.get()` | 1 credit |
113
+ | `facebook.reels` | `client.facebook.reels.list()` | 1 credit |
114
+ | `facebook.replies` | `client.facebook.replies.list()` | 1 credit |
115
+ | `facebook.search_ads` | `client.facebook.searchAds.list()` | 1 credit |
116
+ | `facebook.search_advertisers` | `client.facebook.searchAdvertisers.list()` | 1 credit |
117
+ | `facebook.search_events` | `client.facebook.searchEvents.list()` | 1 credit |
118
+ | `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 |
120
+ | `facebook.search_places` | `client.facebook.searchPlaces.list()` | 1 credit |
121
+ | `facebook.search_posts` | `client.facebook.searchPosts.list()` | 1 credit + 1 per result filled in |
122
+ | `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 |
124
+ | `google.ad` | `client.google.ad.get()` | 1 credit |
125
+ | `google.ads` | `client.google.ads.list()` | 1 credit |
126
+ | `google.advertiser` | `client.google.advertiser.get()` | 1 credit |
127
+ | `google.search_ads` | `client.google.searchAds.list()` | 1 credit |
128
+ | `google.search_advertisers` | `client.google.searchAdvertisers.list()` | 1 credit |
129
+ | `google.search_suggestions` | `client.google.searchSuggestions.list()` | 1 credit |
130
+ | `instagram.comment` | `client.instagram.comment.get()` | 1 credit |
131
+ | `instagram.comments` | `client.instagram.comments.list()` | 1 credit |
132
+ | `instagram.embed` | `client.instagram.embed.get()` | 1 credit; 1 credit |
133
+ | `instagram.engagement` | `client.instagram.engagement.get()` | 1 credit |
134
+ | `instagram.hashtag` | `client.instagram.hashtag.get()` | 1 credit |
135
+ | `instagram.hashtag_posts` | `client.instagram.hashtagPosts.list()` | 1 credit; 1 credit |
136
+ | `instagram.highlights` | `client.instagram.highlights.list()` | 1 credit |
137
+ | `instagram.place` | `client.instagram.place.get()` | 1 credit |
138
+ | `instagram.place_posts` | `client.instagram.placePosts.list()` | 1 credit |
139
+ | `instagram.playlist_stories` | `client.instagram.playlistStories.list()` | 1 credit |
140
+ | `instagram.post` | `client.instagram.post.get()` | 1 credit |
141
+ | `instagram.posts` | `client.instagram.posts.list()` | 1 credit |
142
+ | `instagram.profile` | `client.instagram.profile.get()` | 1 credit |
143
+ | `instagram.reels` | `client.instagram.reels.list()` | 1 credit |
144
+ | `instagram.search_hashtags` | `client.instagram.searchHashtags.list()` | 1 credit |
145
+ | `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 |
147
+ | `instagram.search_profiles` | `client.instagram.searchProfiles.list()` | 1 credit + 1 per result filled in |
148
+ | `instagram.search_sounds` | `client.instagram.searchSounds.list()` | 1 credit + 1 per result filled in |
149
+ | `instagram.search_suggestions` | `client.instagram.searchSuggestions.list()` | 1 credit |
150
+ | `instagram.similar_profiles` | `client.instagram.similarProfiles.list()` | 1 credit |
151
+ | `instagram.sound` | `client.instagram.sound.get()` | 1 credit |
152
+ | `instagram.sound_posts` | `client.instagram.soundPosts.list()` | 1 credit |
153
+ | `instagram.story` | `client.instagram.story.get()` | 1 credit |
154
+ | `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 |
157
+ | `instagram.username` | `client.instagram.username.get()` | 1 credit |
158
+ | `kick.post` | `client.kick.post.get()` | 1 credit; 1 credit |
159
+ | `kick.transcript` | `client.kick.transcript.get()` | 2 credits + 2 per started minute of media |
160
+ | `komi.page` | `client.komi.page.get()` | 1 credit |
161
+ | `kwai.post` | `client.kwai.post.get()` | 1 credit |
162
+ | `kwai.posts` | `client.kwai.posts.list()` | 1 credit |
163
+ | `kwai.profile` | `client.kwai.profile.get()` | 1 credit |
164
+ | `linkbio.profile` | `client.linkbio.profile.get()` | 1 credit |
165
+ | `linkedin.ad` | `client.linkedin.ad.get()` | 1 credit |
166
+ | `linkedin.post` | `client.linkedin.post.get()` | 1 credit |
167
+ | `linkedin.profile` | `client.linkedin.profile.get()` | 1 credit |
168
+ | `linkedin.search_ads` | `client.linkedin.searchAds.list()` | 1 credit |
169
+ | `linkedin.search_posts` | `client.linkedin.searchPosts.list()` | 1 credit + 1 per result filled in |
170
+ | `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 |
172
+ | `linktree.profile` | `client.linktree.profile.get()` | 1 credit |
173
+ | `pillar.page` | `client.pillar.page.get()` | 1 credit |
174
+ | `reddit.comments` | `client.reddit.comments.list()` | 1 credit |
175
+ | `reddit.engagement` | `client.reddit.engagement.get()` | 1 credit |
176
+ | `reddit.post` | `client.reddit.post.get()` | 1 credit |
177
+ | `reddit.posts` | `client.reddit.posts.list()` | 1 credit |
178
+ | `reddit.profile` | `client.reddit.profile.get()` | 1 credit |
179
+ | `reddit.profile_comments` | `client.reddit.profileComments.list()` | 1 credit |
180
+ | `reddit.search_comments` | `client.reddit.searchComments.list()` | 1 credit |
181
+ | `reddit.search_posts` | `client.reddit.searchPosts.list()` | 1 credit |
182
+ | `reddit.search_profiles` | `client.reddit.searchProfiles.list()` | 1 credit |
183
+ | `reddit.search_subreddits` | `client.reddit.searchSubreddits.list()` | 1 credit |
184
+ | `reddit.subreddit` | `client.reddit.subreddit.get()` | 1 credit |
185
+ | `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 |
187
+ | `rumble.comments` | `client.rumble.comments.list()` | 1 credit |
188
+ | `rumble.engagement` | `client.rumble.engagement.get()` | 1 credit |
189
+ | `rumble.post` | `client.rumble.post.get()` | 1 credit |
190
+ | `rumble.posts` | `client.rumble.posts.list()` | 1 credit |
191
+ | `rumble.profile` | `client.rumble.profile.get()` | 1 credit |
192
+ | `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 |
194
+ | `snapchat.comments` | `client.snapchat.comments.list()` | 1 credit |
195
+ | `snapchat.profile` | `client.snapchat.profile.get()` | 1 credit |
196
+ | `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 |
200
+ | `telegram.channel` | `client.telegram.channel.get()` | 1 credit |
201
+ | `telegram.channel_posts` | `client.telegram.channelPosts.list()` | 1 credit |
202
+ | `telegram.post` | `client.telegram.post.get()` | 1 credit |
203
+ | `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 |
209
+ | `threads.search_profiles` | `client.threads.searchProfiles.list()` | 1 credit |
210
+ | `tiktok.ad` | `client.tiktok.ad.get()` | 1 credit |
211
+ | `tiktok.comment` | `client.tiktok.comment.get()` | 1 credit |
212
+ | `tiktok.comments` | `client.tiktok.comments.list()` | 1 credit |
213
+ | `tiktok.download` | `client.tiktok.download.get()` | 1 credit; 1 credit |
214
+ | `tiktok.effect` | `client.tiktok.effect.get()` | 1 credit |
215
+ | `tiktok.effect_posts` | `client.tiktok.effectPosts.list()` | 1 credit |
216
+ | `tiktok.engagement` | `client.tiktok.engagement.get()` | 1 credit |
217
+ | `tiktok.hashtag` | `client.tiktok.hashtag.get()` | 1 credit |
218
+ | `tiktok.liked_posts` | `client.tiktok.likedPosts.list()` | 1 credit |
219
+ | `tiktok.live` | `client.tiktok.live.get()` | 1 credit |
220
+ | `tiktok.place_posts` | `client.tiktok.placePosts.list()` | 1 credit |
221
+ | `tiktok.playlist_posts` | `client.tiktok.playlistPosts.list()` | 1 credit |
222
+ | `tiktok.playlists` | `client.tiktok.playlists.list()` | 1 credit |
223
+ | `tiktok.post` | `client.tiktok.post.get()` | 1 credit |
224
+ | `tiktok.posts` | `client.tiktok.posts.list()` | 1 credit |
225
+ | `tiktok.profile` | `client.tiktok.profile.get()` | 1 credit |
226
+ | `tiktok.replies` | `client.tiktok.replies.list()` | 1 credit |
227
+ | `tiktok.search_ads` | `client.tiktok.searchAds.list()` | 1 credit |
228
+ | `tiktok.search_hashtags` | `client.tiktok.searchHashtags.list()` | 1 credit + 1 per result filled in |
229
+ | `tiktok.search_posts` | `client.tiktok.searchPosts.list()` | 1 credit |
230
+ | `tiktok.search_profiles` | `client.tiktok.searchProfiles.list()` | 1 credit + 1 per result filled in |
231
+ | `tiktok.search_sounds` | `client.tiktok.searchSounds.list()` | 1 credit + 1 per result filled in |
232
+ | `tiktok.search_top` | `client.tiktok.searchTop.list()` | 1 credit + 1 per result filled in |
233
+ | `tiktok.sound` | `client.tiktok.sound.get()` | 1 credit |
234
+ | `tiktok.sound_posts` | `client.tiktok.soundPosts.list()` | 1 credit |
235
+ | `tiktok.top_ads` | `client.tiktok.topAds.list()` | 1 credit |
236
+ | `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 |
238
+ | `tiktok.trending_hashtags` | `client.tiktok.trendingHashtags.list()` | 1 credit |
239
+ | `tiktok.trending_posts` | `client.tiktok.trendingPosts.list()` | 1 credit |
240
+ | `tiktokshop.product` | `client.tiktokshop.product.get()` | 1 credit |
241
+ | `tiktokshop.products` | `client.tiktokshop.products.list()` | 1 credit |
242
+ | `tiktokshop.reviews` | `client.tiktokshop.reviews.list()` | 1 credit |
243
+ | `tiktokshop.search_products` | `client.tiktokshop.searchProducts.list()` | 1 credit; 1 credit |
244
+ | `truthsocial.post` | `client.truthsocial.post.get()` | 1 credit |
245
+ | `truthsocial.posts` | `client.truthsocial.posts.list()` | 1 credit |
246
+ | `truthsocial.profile` | `client.truthsocial.profile.get()` | 1 credit |
247
+ | `twitch.profile` | `client.twitch.profile.get()` | 1 credit |
248
+ | `twitch.schedule` | `client.twitch.schedule.list()` | 1 credit |
249
+ | `twitch.transcript` | `client.twitch.transcript.get()` | 2 credits + 2 per started minute of media |
250
+ | `twitch.video` | `client.twitch.video.get()` | 1 credit |
251
+ | `twitch.videos` | `client.twitch.videos.list()` | 1 credit |
252
+ | `x.community` | `client.x.community.get()` | 1 credit |
253
+ | `x.post` | `client.x.post.get()` | 1 credit |
254
+ | `x.profile` | `client.x.profile.get()` | 1 credit |
255
+ | `x.search_communities` | `client.x.searchCommunities.list()` | 1 credit + 1 per result filled in |
256
+ | `x.search_hashtags` | `client.x.searchHashtags.list()` | 1 credit |
257
+ | `x.search_posts` | `client.x.searchPosts.list()` | 1 credit + 1 per result filled in |
258
+ | `x.search_profiles` | `client.x.searchProfiles.list()` | 1 credit + 1 per result filled in |
259
+ | `youtube.comments` | `client.youtube.comments.list()` | 1 credit |
260
+ | `youtube.engagement` | `client.youtube.engagement.get()` | 1 credit |
261
+ | `youtube.post` | `client.youtube.post.get()` | 1 credit; 1 credit |
262
+ | `youtube.posts` | `client.youtube.posts.list()` | 1 credit |
263
+ | `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 |
265
+
266
+ ## Errors
267
+
268
+ Every API error is an `APIError` subclass named after its code, with `status`, `code`, `retryable`, `remediation`,
269
+ `requestId` and `creditsCharged` (0: errors are free). Codes this SDK version doesn't know arrive as a plain
270
+ `APIError` with their `code`; no response at all is an `APIConnectionError` (`APITimeoutError` for timeouts).
271
+
272
+ ```ts
273
+ import { APIError, NotFoundError } from "socialtap";
274
+
275
+ try {
276
+ await client.tiktok.profile.get({ handle: "nasa" });
277
+ } catch (err) {
278
+ if (err instanceof NotFoundError) {
279
+ // Check the URL or ID; do not retry.
280
+ } else if (err instanceof APIError) {
281
+ console.error(err.code, err.status, err.retryable, err.remediation, err.requestId);
282
+ } else throw err;
283
+ }
284
+ ```
285
+
286
+ | code | class | status | retried |
287
+ |---|---|---|---|
288
+ | `invalid_input` | `InvalidInputError` | 400 | no |
289
+ | `invalid_cursor` | `InvalidCursorError` | 400 | no |
290
+ | `unauthorized` | `UnauthorizedError` | 401 | no |
291
+ | `forbidden` | `ForbiddenError` | 403 | no |
292
+ | `insufficient_credits` | `InsufficientCreditsError` | 402 | no |
293
+ | `spend_limit_reached` | `SpendLimitReachedError` | 402 | no |
294
+ | `rate_limited` | `RateLimitedError` | 429 | yes |
295
+ | `method_not_allowed` | `MethodNotAllowedError` | 405 | no |
296
+ | `endpoint_retired` | `EndpointRetiredError` | 410 | no |
297
+ | `idempotency_key_reused` | `IdempotencyKeyReusedError` | 422 | no |
298
+ | `idempotency_key_in_progress` | `IdempotencyKeyInProgressError` | 409 | yes |
299
+ | `job_not_found` | `JobNotFoundError` | 404 | no |
300
+ | `unknown_endpoint` | `UnknownEndpointError` | 404 | no |
301
+ | `not_found` | `NotFoundError` | 404 | no |
302
+ | `private_or_unavailable` | `PrivateOrUnavailableError` | 403 | no |
303
+ | `no_transcript` | `NoTranscriptError` | 404 | no |
304
+ | `no_live` | `NoLiveError` | 404 | no |
305
+ | `no_media` | `NoMediaError` | 404 | no |
306
+ | `upstream_blocked` | `UpstreamBlockedError` | 503 | yes |
307
+ | `upstream_error` | `UpstreamError` | 502 | yes |
308
+ | `overloaded` | `OverloadedError` | 503 | yes |
309
+ | `internal` | `InternalError` | 500 | yes |
310
+
311
+ ## Retries and timeouts
312
+
313
+ Retryable failures (the codes above, connection errors, timeouts) are retried 2 times by default with
314
+ exponential backoff and jitter, honoring `retry-after`. A GET retry sends `max_age` set to the seconds since the first
315
+ 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.
317
+
318
+ ## Pagination
319
+
320
+ List endpoints return one page (`data`, `page.has_more`, `page.next_cursor`). `iterate()` returns a `Paginator` (`for await` over items, `.byPage()` for pages)
321
+ with two guards, `maxPages` and `maxCredits`; afterwards `pagesFetched`, `creditsCharged`, `stopReason` (`"end"`, or the guard that
322
+ stopped it) and `endReason` (the API's `page.end_reason`) say what happened.
323
+ Each page is checked against its catalog price before it is fetched, and an empty page with `has_more` is not the end.
324
+
325
+ ```ts
326
+ const items = client.bluesky.comments.iterate({ url: "https://bsky.app/profile/atproto.com/post/3moduzldxr22q" }, { maxPages: 10, maxCredits: 100 });
327
+ for await (const item of items) {
328
+ console.log(item);
329
+ }
330
+ console.log(items.pagesFetched, items.creditsCharged, items.stopReason, items.endReason);
331
+ ```
332
+
333
+ ## Account, API keys, jobs, webhooks and events
334
+
335
+ The gateway's own routes (account, usage, credit ledger, API keys, jobs, webhook endpoints, events) are free and
336
+ have methods too, named from their operation IDs (`<noun>.<verb>`, or `<noun>.<sub>.<verb>` for a sub-resource). They
337
+ answer the same envelope (`data`, `meta`, `credits`) with their own `meta`; cursor-paged list routes have `iterate` like
338
+ list endpoints. Every POST sends an `idempotency-key` header (yours, or a new UUID kept for the call's retries), so it is
339
+ retried like a GET and a retry never repeats the work; `replayed` says when the API answered from an earlier request
340
+ with the same key, and `status` is 202 when accepted work continues. Each route needs a key with the scope below (a key
341
+ never gets a scope its creator lacks).
342
+
343
+ ```ts
344
+ const res = await client.account.get();
345
+ console.log(res.data, res.meta.request_id);
346
+ ```
347
+
348
+ | operation | method | scope |
349
+ |---|---|---|
350
+ | `account.get` | `client.account.get()` | `account:read` |
351
+ | `account.update` | `client.account.update(body)` | `admin` |
352
+ | `usage.list` | `client.usage.list(params)` | `account:read` |
353
+ | `usage.rate.list` | `client.usage.rate.list(params)` | `account:read` |
354
+ | `credit_transactions.list` | `client.creditTransactions.list(params)` | `account:read` |
355
+ | `billing.checkout.get` | `client.billing.checkout.get(id)` | `account:read` |
356
+ | `billing.auto_topup.get` | `client.billing.autoTopup.get()` | `account:read` |
357
+ | `requests.list` | `client.requests.list(params)` | `account:read` |
358
+ | `requests.get` | `client.requests.get(id)` | `account:read` |
359
+ | `requests.get_response` | `client.requests.getResponse(id)` | `account:read` |
360
+ | `api_keys.create` | `client.apiKeys.create(body)` | `admin` |
361
+ | `api_keys.list` | `client.apiKeys.list(params)` | `account:read` |
362
+ | `api_keys.get` | `client.apiKeys.get(id)` | `account:read` |
363
+ | `api_keys.update` | `client.apiKeys.update(id, body)` | `admin` |
364
+ | `api_keys.rotate_secret` | `client.apiKeys.rotateSecret(id, body)` | `admin` |
365
+ | `api_keys.revoke` | `client.apiKeys.revoke(id)` | `admin` |
366
+ | `jobs.create` | `client.jobs.create(body, params)` | `jobs` |
367
+ | `jobs.list` | `client.jobs.list(params)` | `jobs:read` |
368
+ | `jobs.get` | `client.jobs.get(id, params)` | `jobs:read` |
369
+ | `jobs.results.list` | `client.jobs.results.list(id, params)` | `jobs:read` |
370
+ | `jobs.cancel` | `client.jobs.cancel(id)` | `jobs` |
371
+ | `webhook_endpoints.create` | `client.webhookEndpoints.create(body)` | `admin` |
372
+ | `webhook_endpoints.list` | `client.webhookEndpoints.list(params)` | `account:read` |
373
+ | `webhook_endpoints.get` | `client.webhookEndpoints.get(id)` | `account:read` |
374
+ | `webhook_endpoints.update` | `client.webhookEndpoints.update(id, body)` | `admin` |
375
+ | `webhook_endpoints.delete` | `client.webhookEndpoints.delete(id)` | `admin` |
376
+ | `webhook_endpoints.rotate_secret` | `client.webhookEndpoints.rotateSecret(id, body)` | `admin` |
377
+ | `webhook_endpoints.test` | `client.webhookEndpoints.test(id)` | `admin` |
378
+ | `webhook_endpoints.deliveries.list` | `client.webhookEndpoints.deliveries.list(id, params)` | `account:read` |
379
+ | `events.list` | `client.events.list(params)` | `account:read` |
380
+ | `events.get` | `client.events.get(id)` | `account:read` |
381
+ | `events.redeliver` | `client.events.redeliver(id, body)` | `admin` |
382
+ | `notification_preferences.get` | `client.notificationPreferences.get()` | `account:read` |
383
+ | `notification_preferences.update` | `client.notificationPreferences.update(body)` | `admin` |
384
+
385
+ ### Jobs and webhooks
386
+
387
+ Many requests (or one long list walk) run as a background job at the synchronous prices; failed items are
388
+ free. The create-and-wait helper creates one, long-polls it until it ends and returns every result; one Idempotency-Key
389
+ covers the create's retries, so a retry never runs a job twice. Webhook deliveries are signed per Standard Webhooks:
390
+ verify the raw body with your endpoint's secret before trusting it, and deduplicate on the event ID.
391
+
392
+ ```ts
393
+ const { job, results } = await client.jobs.createAndWait({ requests: [{ custom_id: "row-1", endpoint: "tiktok.profile", params: { handle: "nasa" } }] });
394
+ for (const r of results) console.log(r.custom_id, r.status, r.error?.code);
395
+
396
+ // A webhook delivery: the raw body, the request headers, your endpoint's secret.
397
+ const event = await client.webhooks.verify(rawBody, request.headers, process.env.SOCIALTAP_WEBHOOK_SECRET!);
398
+ ```
399
+
400
+ ## Tools for AI agents
401
+
402
+ The SDK hands the SocialTap MCP server's tools to a model: each tool's name, description (its price
403
+ and rules included) and input JSON Schema, and a call that sends one stateless MCP request with your key. A tool
404
+ behaves exactly as it does for an MCP client: concise results (`detail: "full"` for every field), `next_cursor` to
405
+ continue, and failures returned as the tool's output (`error` with `retryable` and `remediation`) so the model can
406
+ act on them. Transport failures raise as for any request, and tools that may be repeated are retried.
407
+
408
+ ```ts
409
+ // The Vercel AI SDK (ai is an optional peer dependency): every tool, or socialtapTools({ tools: [...] }).
410
+ import { generateText, stepCountIs } from "ai";
411
+ import { socialtapTools } from "socialtap/ai";
412
+
413
+ // model: any AI SDK model; prompt: the task. The model calls the tools, the SDK runs them with your key.
414
+ const { text } = await generateText({ model, tools: socialtapTools(), stopWhen: stepCountIs(5), prompt });
415
+
416
+ // Any other tool-calling API: hand TOOLS (name, description, inputSchema) to the model, run its calls with callTool.
417
+ import { SocialTap, TOOLS, callTool } from "socialtap";
418
+
419
+ const r = await callTool(new SocialTap(), "find_endpoint", { query: "Public TikTok profile and follower counts" });
420
+ console.log(r.isError, r.output);
421
+ ```
422
+
423
+ | tool | what it does |
424
+ |---|---|
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
+ | `find_endpoint` | Find an endpoint |
477
+ | `search_docs` | Search the docs |
478
+ | `read_doc` | Read a docs page |
479
+ | `get_account` | Get account balance |
480
+ | `create_job` | Create a background job |
481
+ | `get_job` | Get a background job |
482
+ | `list_job_results` | List a job's results |
483
+
484
+ ## CLI
485
+
486
+ The package's bin: every endpoint as a command (JSON on stdout; a list walk with `--all` prints one item per
487
+ line), the agent tools, and `init`, which sets up coding agents.
488
+
489
+ ```sh
490
+ npx socialtap tiktok profile --handle nasa
491
+ npx socialtap endpoints # every command, its params and price
492
+ npx socialtap tool find_endpoint '{"query":"Public TikTok profile and follower counts"}'
493
+ npx socialtap init # Claude Code, Codex, Cursor, Gemini CLI: the Agent Skill + the MCP server
494
+ ```
495
+
496
+ `init` installs the Agent Skill the site publishes (its discovery index, digest checked) into each agent's user
497
+ skills directory and registers the MCP server with your key (`--api-key`, or `SOCIALTAP_API_KEY`) in each agent's own user
498
+ config: Claude Code through `claude mcp add-json`, Codex's `config.toml`, Cursor's `mcp.json`, Gemini CLI's
499
+ `settings.json`. It sets up every agent it finds (`--agent <id>` to choose) and is safe to run again.
500
+
501
+ ## Versioning
502
+
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.
@@ -0,0 +1,55 @@
1
+ export type AgentId = "claude" | "codex" | "cursor" | "gemini";
2
+ /** What the installers touch: the user's home, their environment, subprocesses and the network. */
3
+ export interface SetupEnv {
4
+ home: string;
5
+ env: Record<string, string | undefined>;
6
+ /** Runs a program; rejects with code ENOENT when it isn't installed. */
7
+ run(cmd: string, args: readonly string[]): Promise<{
8
+ code: number;
9
+ stdout: string;
10
+ stderr: string;
11
+ }>;
12
+ fetch: typeof fetch;
13
+ }
14
+ /**
15
+ * The MCP server to register: its name in configs, its URL and the API key sent as a bearer token. Without a key, the
16
+ * agent signs its person in with their browser the first time a tool needs it (OAuth).
17
+ */
18
+ export interface McpServer {
19
+ name: string;
20
+ url: string;
21
+ key?: string;
22
+ }
23
+ export interface Skill {
24
+ name: string;
25
+ content: string;
26
+ }
27
+ export interface Agent {
28
+ id: AgentId;
29
+ name: string;
30
+ /** Whether the agent is set up for this user (its config directory exists). */
31
+ detect(env: SetupEnv): boolean;
32
+ /** The user-level skills directory it reads. */
33
+ skillsDir(env: SetupEnv): string;
34
+ /** Registers the server in its user config (replacing an earlier entry of that name); returns what changed. */
35
+ addMcp(env: SetupEnv, server: McpServer): Promise<string>;
36
+ }
37
+ export declare const AGENTS: readonly Agent[];
38
+ /**
39
+ * The skills the site publishes: its Agent Skills discovery index (agentskills.io, schema 0.2.0), each SKILL.md
40
+ * fetched and checked against the index's sha256 digest.
41
+ */
42
+ export declare function fetchSkills(env: SetupEnv, origin: string, indexPath: string): Promise<Skill[]>;
43
+ /** Writes each skill to <dir>/<name>/SKILL.md; returns the files written. */
44
+ export declare function writeSkills(dir: string, skills: readonly Skill[]): Promise<string[]>;
45
+ /**
46
+ * Replaces TOML table `name` (and its sub-tables `name.*`) with `lines`, or appends it. Line-based: a table runs from
47
+ * its header to the next table header, which is how config.toml is written.
48
+ */
49
+ export declare function setTomlTable(text: string, name: string, lines: readonly string[]): string;
50
+ /** Runs a program (the Claude Code CLI) and collects its output. */
51
+ export declare function runProgram(cmd: string, args: readonly string[]): Promise<{
52
+ code: number;
53
+ stdout: string;
54
+ stderr: string;
55
+ }>;