Skip to content

Commit 9bc0f0d

Browse files
simonbalfeclaude
simonbalfe
and
claude
committed
initial release: v0.1.0
Typed TypeScript SDK covering all six CreatorCrawl platforms: TikTok, Instagram, YouTube, LinkedIn, Twitter/X, Reddit. Ships ~9 KB ESM + CJS with zero runtime deps. Publishes to npm on tag v* via GitHub Actions. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
0 parents  commit 9bc0f0d

21 files changed

Lines changed: 1829 additions & 0 deletions

‎.github/workflows/ci.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
test:
11+
name: Type-check and build
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
- uses: pnpm/action-setup@v4
16+
with:
17+
version: 9.15.0
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: 20
21+
cache: pnpm
22+
- run: pnpm install --frozen-lockfile
23+
- run: pnpm type-check
24+
- run: pnpm build

‎.github/workflows/publish.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
name: Publish to npm
2+
3+
on:
4+
push:
5+
tags:
6+
- 'v*'
7+
8+
permissions:
9+
contents: read
10+
id-token: write
11+
12+
jobs:
13+
publish:
14+
runs-on: ubuntu-latest
15+
steps:
16+
- uses: actions/checkout@v4
17+
- uses: pnpm/action-setup@v4
18+
with:
19+
version: 9.15.0
20+
- uses: actions/setup-node@v4
21+
with:
22+
node-version: 20
23+
cache: pnpm
24+
registry-url: https://registry.npmjs.org
25+
- run: pnpm install --frozen-lockfile
26+
- run: pnpm type-check
27+
- run: pnpm build
28+
- run: npm publish --access public --provenance
29+
env:
30+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules
2+
dist
3+
.turbo
4+
*.log
5+
.DS_Store
6+
tsconfig.tsbuildinfo

‎.npmignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
src
2+
tsconfig.json
3+
tsup.config.ts
4+
biome.json
5+
node_modules
6+
.turbo
7+
*.log

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 CreatorCrawl
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.

‎README.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# @creatorcrawl/sdk
2+
3+
Official TypeScript / JavaScript SDK for the [CreatorCrawl](https://creatorcrawl.com) social media data API.
4+
5+
One typed client, six platforms: **TikTok, Instagram, YouTube, LinkedIn, Twitter/X, and Reddit**. Profiles, posts, comments, transcripts, ads, search, and trending data as structured JSON.
6+
7+
- 60+ endpoints across six platforms
8+
- Fully typed, ESM + CJS, zero runtime dependencies
9+
- Works in Node 18+, Bun, Deno, Cloudflare Workers, and browsers
10+
- Same endpoints are also available as a native MCP server for Claude, Cursor, Windsurf, and Zed
11+
12+
## Install
13+
14+
```bash
15+
npm install @creatorcrawl/sdk
16+
# or
17+
pnpm add @creatorcrawl/sdk
18+
# or
19+
yarn add @creatorcrawl/sdk
20+
```
21+
22+
## Quick start
23+
24+
Get a key at [creatorcrawl.com](https://creatorcrawl.com). 250 credits are free on signup, no card required.
25+
26+
```ts
27+
import { CreatorCrawl } from '@creatorcrawl/sdk'
28+
29+
const cc = new CreatorCrawl({ apiKey: process.env.CREATORCRAWL_API_KEY! })
30+
31+
const profile = await cc.tiktok.profile({ handle: 'khaby.lame' })
32+
const transcript = await cc.youtube.transcript({ url: 'https://youtu.be/...' })
33+
const company = await cc.linkedin.company({ url: 'https://www.linkedin.com/company/openai' })
34+
```
35+
36+
## Resources
37+
38+
```ts
39+
cc.tiktok.profile({ handle })
40+
cc.tiktok.profileVideos({ handle })
41+
cc.tiktok.videoInfo({ url })
42+
cc.tiktok.transcript({ url })
43+
cc.tiktok.searchKeyword({ query })
44+
cc.tiktok.searchUsers({ query })
45+
cc.tiktok.comments({ url })
46+
47+
cc.instagram.profile({ handle })
48+
cc.instagram.posts({ handle })
49+
cc.instagram.postInfo({ url })
50+
cc.instagram.reels({ handle })
51+
cc.instagram.comments({ url })
52+
cc.instagram.transcript({ url })
53+
54+
cc.youtube.channel({ handle })
55+
cc.youtube.channelVideos({ handle })
56+
cc.youtube.channelShorts({ handle })
57+
cc.youtube.video({ url })
58+
cc.youtube.search({ query })
59+
cc.youtube.transcript({ url })
60+
cc.youtube.comments({ url })
61+
cc.youtube.playlist({ url })
62+
63+
cc.linkedin.profile({ url })
64+
cc.linkedin.company({ url })
65+
cc.linkedin.companyPosts({ url })
66+
cc.linkedin.post({ url })
67+
cc.linkedin.adsSearch({ query })
68+
cc.linkedin.ad({ url })
69+
70+
cc.twitter.profile({ handle })
71+
cc.twitter.tweet({ url })
72+
cc.twitter.userTweets({ handle })
73+
cc.twitter.transcript({ url })
74+
cc.twitter.community({ url })
75+
cc.twitter.communityTweets({ url })
76+
77+
cc.reddit.search({ query })
78+
cc.reddit.subredditDetails({ subreddit })
79+
cc.reddit.subredditPosts({ subreddit })
80+
cc.reddit.subredditSearch({ subreddit, query })
81+
cc.reddit.postComments({ url })
82+
```
83+
84+
## Configuration
85+
86+
```ts
87+
const cc = new CreatorCrawl({
88+
apiKey: 'cc_...',
89+
baseUrl: 'https://app.creatorcrawl.com/api', // optional
90+
timeout: 30_000, // optional, ms
91+
fetch: customFetch, // optional
92+
})
93+
```
94+
95+
## Error handling
96+
97+
Failed requests throw a typed `CreatorCrawlError`:
98+
99+
```ts
100+
import {
101+
AuthenticationError,
102+
CreatorCrawlError,
103+
InsufficientCreditsError,
104+
RateLimitError,
105+
UpstreamError,
106+
} from '@creatorcrawl/sdk'
107+
108+
try {
109+
await cc.tiktok.profile({ handle: 'khaby.lame' })
110+
} catch (err) {
111+
if (err instanceof InsufficientCreditsError) {
112+
// top up credits
113+
} else if (err instanceof RateLimitError) {
114+
// back off
115+
} else if (err instanceof CreatorCrawlError) {
116+
console.error(err.status, err.message)
117+
}
118+
}
119+
```
120+
121+
## Cancellation
122+
123+
Every method accepts a `RequestOptions` argument with an `AbortSignal`:
124+
125+
```ts
126+
const controller = new AbortController()
127+
setTimeout(() => controller.abort(), 5_000)
128+
129+
await cc.tiktok.profile({ handle: 'khaby.lame' }, { signal: controller.signal })
130+
```
131+
132+
## Links
133+
134+
- API docs: [creatorcrawl.com/mcp-docs](https://creatorcrawl.com/mcp-docs)
135+
- Pricing: [creatorcrawl.com/#pricing](https://creatorcrawl.com/#pricing)
136+
- MCP server: native MCP at `app.creatorcrawl.com/api/mcp` for AI agents
137+
- Status / issues: [github.com/simonbalfe/creator-crawl/issues](https://github.com/simonbalfe/creator-crawl/issues)
138+
139+
## License
140+
141+
MIT

‎biome.json‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
{
2+
"$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
3+
"vcs": {
4+
"enabled": true,
5+
"clientKind": "git",
6+
"useIgnoreFile": true
7+
},
8+
"organizeImports": {
9+
"enabled": true
10+
},
11+
"formatter": {
12+
"enabled": true,
13+
"indentStyle": "space",
14+
"indentWidth": 2,
15+
"lineWidth": 100
16+
},
17+
"javascript": {
18+
"formatter": {
19+
"quoteStyle": "single",
20+
"semicolons": "asNeeded",
21+
"trailingCommas": "all",
22+
"arrowParentheses": "always"
23+
}
24+
},
25+
"linter": {
26+
"enabled": true,
27+
"rules": {
28+
"recommended": true,
29+
"correctness": {
30+
"noUnusedVariables": "warn",
31+
"noUnusedImports": "error"
32+
},
33+
"style": {
34+
"useImportType": "error"
35+
},
36+
"suspicious": {
37+
"noExplicitAny": "warn"
38+
}
39+
}
40+
},
41+
"files": {
42+
"ignore": ["node_modules", "dist"]
43+
}
44+
}

‎package.json‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
{
2+
"name": "@creatorcrawl/sdk",
3+
"version": "0.1.0",
4+
"description": "Official TypeScript SDK for the CreatorCrawl social media data API. Scrape TikTok, Instagram, YouTube, LinkedIn, Twitter/X, and Reddit profiles, posts, comments, transcripts, and ads.",
5+
"license": "MIT",
6+
"author": "CreatorCrawl <support@creatorcrawl.com>",
7+
"homepage": "https://creatorcrawl.com",
8+
"repository": {
9+
"type": "git",
10+
"url": "git+https://github.com/simonbalfe/creatorcrawl-sdk-typescript.git"
11+
},
12+
"bugs": {
13+
"url": "https://github.com/simonbalfe/creatorcrawl-sdk-typescript/issues"
14+
},
15+
"keywords": [
16+
"creatorcrawl",
17+
"social-media-api",
18+
"tiktok-api",
19+
"instagram-api",
20+
"youtube-api",
21+
"linkedin-api",
22+
"twitter-api",
23+
"reddit-api",
24+
"scraper",
25+
"sdk",
26+
"mcp"
27+
],
28+
"type": "module",
29+
"main": "./dist/index.cjs",
30+
"module": "./dist/index.js",
31+
"types": "./dist/index.d.ts",
32+
"exports": {
33+
".": {
34+
"types": "./dist/index.d.ts",
35+
"import": "./dist/index.js",
36+
"require": "./dist/index.cjs"
37+
}
38+
},
39+
"files": ["dist", "README.md", "LICENSE"],
40+
"scripts": {
41+
"build": "tsup",
42+
"type-check": "tsc --noEmit",
43+
"lint": "biome check .",
44+
"prepublishOnly": "pnpm build"
45+
},
46+
"engines": {
47+
"node": ">=18"
48+
},
49+
"devDependencies": {
50+
"@biomejs/biome": "^1.9.4",
51+
"tsup": "^8.3.5",
52+
"typescript": "^5.9.3"
53+
},
54+
"publishConfig": {
55+
"access": "public"
56+
}
57+
}

0 commit comments

Comments
 (0)