feat: typed canonical response shapes (breaking)

Every endpoint now returns a single canonical envelope
({ data, page?, meta }) across all six platforms, replacing the
raw upstream-platform shapes (TikTok's user.uniqueId, Twitter's
legacy.screen_name, Instagram's data.user.edge_followed_by.count,
etc.).

- Response field names are snake_case and consistent cross-platform
- Dates are ISO 8601
- Pagination unified as page.cursor + page.has_more on list endpoints
- New exported types: Envelope, Creator, MiniCreator, Post, Comment,
  Transcript, Hashtag, Song, Subreddit, Company, Media, Platform
- Method names and parameters unchanged

Bumps to 0.3.0. See CHANGELOG.md for migration notes.

Author: simonbalfe

CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## 0.3.0
+
+### Breaking changes
+
+All endpoints now return a single canonical response envelope across every platform, replacing the raw upstream-platform shapes returned by 0.2.x and earlier.
+
+Every response now has the shape:
+
+```ts
+type Envelope<T> = {
+  data: T
+  page?: { cursor: string | null; has_more: boolean; total?: number }
+  meta: { platform: Platform; fetched_at: string }
+}
+```
+
+What this means in practice:
+
+- TikTok profiles return `data.handle` / `data.follower_count` instead of `user.uniqueId` / `stats.followerCount`.
+- Twitter profiles return `data.handle` / `data.verified_tier` instead of `legacy.screen_name` / `is_blue_verified`.
+- Instagram profiles return `data.follower_count` instead of `data.user.edge_followed_by.count`.
+- YouTube channels return `data.handle` / `data.subscriber_count` mapped into `data.follower_count` for cross-platform consistency.
+- Reddit, LinkedIn (profile + company), and all post / comment / transcript endpoints follow the same envelope.
+- All dates are ISO 8601 strings.
+- All field names are `snake_case`.
+- Pagination is now consistent: `page.cursor` + `page.has_more` on list endpoints.
+
+### Migration
+
+Method names and parameters are unchanged. Only the response shape changed.
+
+Before (0.2.x):
+
+```ts
+const res = await cc.twitter.profile({ handle: 'elonmusk' })
+console.log(res.legacy.screen_name, res.legacy.followers_count)
+```
+
+After (0.3.0):
+
+```ts
+const res = await cc.twitter.profile({ handle: 'elonmusk' })
+console.log(res.data.handle, res.data.follower_count)
+```
+
+### Added
+
+- Canonical exported types: `Envelope`, `Creator`, `MiniCreator`, `Post`, `Comment`, `Transcript`, `Hashtag`, `Song`, `Subreddit`, `Company`, `Media`, `Platform`, `PageInfo`, plus enums for `PostType`.
+- `CreatorWithPosts` and `SubredditWithPosts` helpers for endpoints that return a primary entity plus recent posts.
+
+## 0.2.0
+
+Initial public release.

README.md

@@ -9,6 +9,20 @@ One typed client, six platforms: **TikTok, Instagram, YouTube, LinkedIn, Twitter
 - Works in Node 18+, Bun, Deno, Cloudflare Workers, and browsers
 - Same endpoints are also available as a native MCP server for Claude, Cursor, Windsurf, and Zed
 
+## Breaking changes in 0.3
+
+0.3.0 unifies every response under a single canonical envelope. Field names are now `snake_case` and identical across platforms, so a `Creator` from TikTok and one from YouTube share the same shape.
+
+```ts
+type Envelope<T> = {
+  data: T
+  page?: { cursor: string | null; has_more: boolean; total?: number }
+  meta: { platform: Platform; fetched_at: string }
+}
+```
+
+If you were reading raw upstream fields (`legacy.screen_name`, `stats.followerCount`, `data.user.edge_followed_by.count`, etc.), you will need to update your call sites. Method names and parameters are unchanged. See `CHANGELOG.md` for migration notes.
+
 ## Install
 
 ```bash
@@ -33,6 +47,76 @@ const transcript = await cc.youtube.transcript({ url: 'https://youtu.be/...' })
 const company = await cc.linkedin.company({ url: 'https://www.linkedin.com/company/openai' })
 ```
 
+## Response shape
+
+Every endpoint returns the same envelope:
+
+```ts
+{
+  data: T,                    // Creator | Post | Post[] | Comment[] | Transcript | ...
+  page?: {                    // present on list endpoints
+    cursor: string | null,
+    has_more: boolean,
+    total?: number
+  },
+  meta: {
+    platform: 'tiktok' | 'instagram' | 'twitter' | 'youtube' | 'reddit' | 'linkedin',
+    fetched_at: string        // ISO 8601
+  }
+}
+```
+
+A Twitter profile call:
+
+```ts
+const res = await cc.twitter.profile({ handle: 'elonmusk' })
+// {
+//   data: {
+//     id: '44196397',
+//     handle: 'elonmusk',
+//     name: 'Elon Musk',
+//     bio: '...',
+//     url: 'https://twitter.com/elonmusk',
+//     avatar_url: 'https://...',
+//     verified: true,
+//     verified_tier: 'blue',
+//     follower_count: 200000000,
+//     following_count: 800,
+//     post_count: 50000,
+//     created_at: '2009-06-02T20:12:29.000Z',
+//     platform: 'twitter',
+//     recent_posts: [ /* Post[] */ ]
+//   },
+//   meta: { platform: 'twitter', fetched_at: '2025-01-15T12:00:00.000Z' }
+// }
+```
+
+A TikTok video list:
+
+```ts
+const res = await cc.tiktok.profileVideos({ handle: 'khaby.lame' })
+// {
+//   data: [
+//     {
+//       id: '7234567890',
+//       url: 'https://www.tiktok.com/@khaby.lame/video/7234567890',
+//       type: 'video',
+//       created_at: '2024-12-01T15:30:00.000Z',
+//       text: 'Caption here #fyp',
+//       view_count: 12000000,
+//       like_count: 1200000,
+//       comment_count: 8000,
+//       share_count: 50000,
+//       author: { id: '...', handle: 'khaby.lame', name: 'Khaby Lame', url: '...', platform: 'tiktok' },
+//       hashtags: ['fyp'],
+//       platform: 'tiktok'
+//     }
+//   ],
+//   page: { cursor: '1701436200', has_more: true },
+//   meta: { platform: 'tiktok', fetched_at: '2025-01-15T12:00:00.000Z' }
+// }
+```
+
 ## Resources
 
 ```ts

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creatorcrawl/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "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.",
   "license": "MIT",
   "author": "CreatorCrawl <support@creatorcrawl.com>",

src/index.ts

@@ -6,7 +6,29 @@ export {
   RateLimitError,
   UpstreamError,
 } from './errors'
-export type { CreatorCrawlOptions, JsonRecord, RequestOptions } from './types'
+export type {
+  Comment,
+  Company,
+  Creator,
+  CreatorCrawlOptions,
+  CreatorWithPosts,
+  Envelope,
+  Hashtag,
+  JsonRecord,
+  Media,
+  MiniCreator,
+  PageInfo,
+  Platform,
+  Post,
+  PostMusic,
+  PostType,
+  RequestOptions,
+  Song,
+  Subreddit,
+  SubredditWithPosts,
+  Transcript,
+  TranscriptSegment,
+} from './types'
 export type {
   TikTokCommentsParams,
   TikTokCreatorTranscriptsParams,

src/resources/instagram.ts

@@ -1,5 +1,14 @@
 import type { CreatorCrawl } from '../client'
-import type { JsonRecord, RequestOptions } from '../types'
+import type {
+  Comment,
+  Creator,
+  CreatorWithPosts,
+  Envelope,
+  JsonRecord,
+  Post,
+  RequestOptions,
+  Transcript,
+} from '../types'
 
 export type InstagramProfileParams = { handle: string }
 export type InstagramBasicProfileParams = { userId: string }
@@ -17,46 +26,46 @@ export class Instagram {
   constructor(private readonly client: CreatorCrawl) {}
 
   profile(params: InstagramProfileParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/profile', params, options)
+    return this.client.get<Envelope<CreatorWithPosts>>('/instagram/profile', params, options)
   }
 
   basicProfile(params: InstagramBasicProfileParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/basic-profile', params, options)
+    return this.client.get<Envelope<Creator>>('/instagram/basic-profile', params, options)
   }
 
   posts(params: InstagramPostsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/user/posts', params, options)
+    return this.client.get<Envelope<Post[]>>('/instagram/user/posts', params, options)
   }
 
   reels(params: InstagramReelsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/user/reels', params, options)
+    return this.client.get<Envelope<Post[]>>('/instagram/user/reels', params, options)
   }
 
   postInfo(params: InstagramPostInfoParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/post', params, options)
+    return this.client.get<Envelope<Post>>('/instagram/post', params, options)
   }
 
   comments(params: InstagramCommentsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/post/comments', params, options)
+    return this.client.get<Envelope<Comment[]>>('/instagram/post/comments', params, options)
   }
 
   transcript(params: InstagramTranscriptParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/media/transcript', params, options)
+    return this.client.get<Envelope<Transcript>>('/instagram/media/transcript', params, options)
   }
 
   storyHighlights(params: InstagramStoryHighlightsParams = {}, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/user/highlights', params, options)
+    return this.client.get<Envelope<JsonRecord[]>>('/instagram/user/highlights', params, options)
   }
 
   highlightsDetails(params: InstagramHighlightsDetailsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/user/highlight/detail', params, options)
+    return this.client.get<Envelope<JsonRecord>>('/instagram/user/highlight/detail', params, options)
   }
 
   searchReels(params: InstagramSearchReelsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/reels/search', params, options)
+    return this.client.get<Envelope<Post[]>>('/instagram/reels/search', params, options)
   }
 
   embed(params: InstagramEmbedParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/instagram/user/embed', params, options)
+    return this.client.get<Envelope<JsonRecord>>('/instagram/user/embed', params, options)
   }
 }

src/resources/linkedin.ts

@@ -1,5 +1,12 @@
 import type { CreatorCrawl } from '../client'
-import type { JsonRecord, RequestOptions } from '../types'
+import type {
+  Company,
+  Creator,
+  Envelope,
+  JsonRecord,
+  Post,
+  RequestOptions,
+} from '../types'
 
 export type LinkedInProfileParams = { url: string }
 export type LinkedInCompanyParams = { url: string }
@@ -20,26 +27,26 @@ export class LinkedIn {
   constructor(private readonly client: CreatorCrawl) {}
 
   profile(params: LinkedInProfileParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/linkedin/profile', params, options)
+    return this.client.get<Envelope<Creator>>('/linkedin/profile', params, options)
   }
 
   company(params: LinkedInCompanyParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/linkedin/company', params, options)
+    return this.client.get<Envelope<Company>>('/linkedin/company', params, options)
   }
 
   companyPosts(params: LinkedInCompanyPostsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/linkedin/company/posts', params, options)
+    return this.client.get<Envelope<Post[]>>('/linkedin/company/posts', params, options)
   }
 
   post(params: LinkedInPostParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/linkedin/post', params, options)
+    return this.client.get<Envelope<Post>>('/linkedin/post', params, options)
   }
 
   adsSearch(params: LinkedInAdsSearchParams = {}, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/linkedin/ads/search', params, options)
+    return this.client.get<Envelope<JsonRecord[]>>('/linkedin/ads/search', params, options)
   }
 
   ad(params: LinkedInAdParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/linkedin/ad', params, options)
+    return this.client.get<Envelope<JsonRecord>>('/linkedin/ad', params, options)
   }
 }

src/resources/reddit.ts

@@ -1,5 +1,12 @@
 import type { CreatorCrawl } from '../client'
-import type { JsonRecord, RequestOptions } from '../types'
+import type {
+  Comment,
+  Envelope,
+  Post,
+  RequestOptions,
+  Subreddit,
+  SubredditWithPosts,
+} from '../types'
 
 export type RedditSearchParams = {
   query: string
@@ -33,22 +40,26 @@ export class Reddit {
   constructor(private readonly client: CreatorCrawl) {}
 
   search(params: RedditSearchParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/reddit/search', params, options)
+    return this.client.get<Envelope<Post[]>>('/reddit/search', params, options)
   }
 
   subredditDetails(params: RedditSubredditDetailsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/reddit/subreddit/details', params, options)
+    return this.client.get<Envelope<Subreddit | SubredditWithPosts>>(
+      '/reddit/subreddit/details',
+      params,
+      options,
+    )
   }
 
   subredditPosts(params: RedditSubredditPostsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/reddit/subreddit/posts', params, options)
+    return this.client.get<Envelope<Post[]>>('/reddit/subreddit/posts', params, options)
   }
 
   subredditSearch(params: RedditSubredditSearchParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/reddit/subreddit/search', params, options)
+    return this.client.get<Envelope<Post[]>>('/reddit/subreddit/search', params, options)
   }
 
   postComments(params: RedditPostCommentsParams, options?: RequestOptions) {
-    return this.client.get<JsonRecord>('/reddit/post/comments', params, options)
+    return this.client.get<Envelope<Comment[]>>('/reddit/post/comments', params, options)
   }
 }