feat: bump to SDK 0.3 with canonical response shapes (breaking)

Author: simonbalfe

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.3.0
+
+**Breaking changes.**
+
+- Bumped `@creatorcrawl/sdk` to `^0.3.0`, which switches every endpoint to the new unified `{ data, page?, meta }` envelope.
+- All platforms (TikTok, Instagram, Twitter/X, YouTube, Reddit, LinkedIn) now return canonical `Creator` / `Post` / `Comment` shapes with snake_case fields and ISO 8601 dates.
+- CLI surface is unchanged: command names, arguments, and flags are identical to 0.2. Only the shape of the JSON printed to stdout has changed.
+- README examples updated to reflect the new envelope (e.g. `.data.handle` / `.data.follower_count` instead of `.user.uniqueId` / `.stats.followerCount`).
+
+See the [`@creatorcrawl/sdk` changelog](https://www.npmjs.com/package/@creatorcrawl/sdk) for the full type-level migration.
+
+## 0.2.0
+
+- Initial public release.

README.md

@@ -1,5 +1,7 @@
 # creatorcrawl CLI
 
+> **0.3 returns the new canonical response shape — see the SDK changelog for details.**
+
 Official command-line interface for [CreatorCrawl](https://creatorcrawl.com). Scrape **TikTok, Instagram, YouTube, LinkedIn, Twitter/X, and Reddit** from your terminal or shell scripts.
 
 ```bash
@@ -58,8 +60,26 @@ Run `creatorcrawl <platform> --help` for subcommand details.
 
 Default: compact JSON (greppable, pipeable).
 
+All responses use a unified envelope: `{ data, page?, meta }`. `data` holds the canonical record (`Creator`, `Post`, `Comment`, or a list of these). `meta` always includes `platform` and `fetched_at`.
+
 ```bash
-creatorcrawl tiktok profile khaby.lame | jq '.user.uniqueId, .stats.followerCount'
+creatorcrawl tiktok profile khaby.lame | jq '.data.handle, .data.follower_count'
+```
+
+Sample response:
+
+```json
+{
+  "data": {
+    "handle": "khaby.lame",
+    "follower_count": 162000000,
+    "platform": "tiktok"
+  },
+  "meta": {
+    "platform": "tiktok",
+    "fetched_at": "2026-05-15T10:00:00Z"
+  }
+}
 ```
 
 Pretty-print:
@@ -78,7 +98,7 @@ creatorcrawl tiktok profile stoolpresidente
 creatorcrawl youtube transcript https://youtu.be/dQw4w9WgXcQ > transcript.json
 
 # Search and extract top-5 channels
-creatorcrawl youtube search "ai tools" | jq '.items[:5]'
+creatorcrawl youtube search "ai tools" | jq '.data[:5]'
 
 # LinkedIn ad library lookup
 creatorcrawl linkedin ads stripe

package.json

@@ -1,6 +1,6 @@
 {
   "name": "creatorcrawl",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Official CLI for CreatorCrawl. Scrape TikTok, Instagram, YouTube, LinkedIn, Twitter/X, and Reddit profiles, posts, comments, transcripts, ads, and trending data from your terminal or shell scripts.",
   "license": "MIT",
   "author": "CreatorCrawl <support@creatorcrawl.com>",
@@ -45,7 +45,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@creatorcrawl/sdk": "^0.2.0",
+    "@creatorcrawl/sdk": "^0.3.0",
     "commander": "^12.1.0"
   },
   "devDependencies": {