@captapi/sdk 0.2.0 → 0.3.0

package/README.md

@@ -1,73 +1,73 @@
-# @captapi/sdk
-
-Official typed TypeScript SDK for the [Captapi](https://captapi.com) social media API — 178 endpoints across 32 platforms (YouTube, TikTok, Instagram, Facebook, X/Twitter, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Twitch, Spotify, SoundCloud, GitHub, and more).
-
-- Zero dependencies — built on native `fetch` (Node 18+, Deno, Bun, edge runtimes)
-- Full type definitions for every endpoint and parameter — great autocomplete for humans and AI coding agents
-- Errors always throw a `CaptapiError` with status, code, and detail — no silent failures
-- One bounded retry on 502/503 (skipped when the API says the failure is persistent or already cached)
-
-## Install
-
-```bash
-npm install @captapi/sdk
-```
-
-## Quick start
-
-```ts
-import { Captapi } from "@captapi/sdk";
-
-const client = new Captapi({ apiKey: "YOUR_KEY" }); // or set CAPTAPI_API_KEY
-
-const transcript = await client.youtube.transcript({
-  url: "https://youtube.com/watch?v=dQw4w9WgXcQ",
-});
-console.log(transcript.data);
-
-const profile = await client.tiktok.channelDetails({ url: "https://tiktok.com/@nba" });
-const posts = await client.reddit.subredditPosts({ url: "https://reddit.com/r/programming", limit: 25 });
-const ads = await client.googleAdLibrary.companyAds({ advertiser: "nike.com" });
-```
-
-## Error handling
-
-Every failed request throws — nothing fails silently:
-
-```ts
-import { Captapi, CaptapiError } from "@captapi/sdk";
-
-try {
-  await client.instagram.channelDetails({ url: "https://instagram.com/whoever" });
-} catch (err) {
-  if (err instanceof CaptapiError) {
-    console.error(err.status, err.code, err.detail);
-  }
-}
-```
-
-## Options
-
-```ts
-new Captapi({
-  apiKey: "...",              // default: process.env.CAPTAPI_API_KEY
-  baseUrl: "https://api.captapi.com", // default
-  timeoutMs: 120_000,          // default
-});
-```
-
-## Responses
-
-All methods resolve to the standard Captapi envelope:
-
-```json
-{ "success": true, "data": { ... } }
-```
-
-## Links
-
-- [Documentation](https://captapi.com/docs)
-- [Get an API key (100 free credits)](https://captapi.com/dashboard/api-keys)
-- Python SDK: [`pip install captapi`](https://pypi.org/project/captapi/)
-- MCP server for AI agents: [`@captapi/mcp`](https://www.npmjs.com/package/@captapi/mcp)
-- CLI: [`@captapi/cli`](https://www.npmjs.com/package/@captapi/cli)
+# @captapi/sdk
+
+Official typed TypeScript SDK for the [Captapi](https://captapi.com) social media API — 178 endpoints across 32 platforms (YouTube, TikTok, Instagram, Facebook, X/Twitter, Reddit, Threads, Bluesky, Pinterest, LinkedIn, Twitch, Spotify, SoundCloud, GitHub, and more).
+
+- Zero dependencies — built on native `fetch` (Node 18+, Deno, Bun, edge runtimes)
+- Full type definitions for every endpoint and parameter — great autocomplete for humans and AI coding agents
+- Errors always throw a `CaptapiError` with status, code, and detail — no silent failures
+- One bounded retry on 502/503 (skipped when the API says the failure is persistent or already cached)
+
+## Install
+
+```bash
+npm install @captapi/sdk
+```
+
+## Quick start
+
+```ts
+import { Captapi } from "@captapi/sdk";
+
+const client = new Captapi({ apiKey: "YOUR_KEY" }); // or set CAPTAPI_API_KEY
+
+const transcript = await client.youtube.transcript({
+  url: "https://youtube.com/watch?v=dQw4w9WgXcQ",
+});
+console.log(transcript.data);
+
+const profile = await client.tiktok.channelDetails({ url: "https://tiktok.com/@nba" });
+const posts = await client.reddit.subredditPosts({ url: "https://reddit.com/r/programming", limit: 25 });
+const ads = await client.googleAdLibrary.companyAds({ advertiser: "nike.com" });
+```
+
+## Error handling
+
+Every failed request throws — nothing fails silently:
+
+```ts
+import { Captapi, CaptapiError } from "@captapi/sdk";
+
+try {
+  await client.instagram.channelDetails({ url: "https://instagram.com/whoever" });
+} catch (err) {
+  if (err instanceof CaptapiError) {
+    console.error(err.status, err.code, err.detail);
+  }
+}
+```
+
+## Options
+
+```ts
+new Captapi({
+  apiKey: "...",              // default: process.env.CAPTAPI_API_KEY
+  baseUrl: "https://api.captapi.com", // default
+  timeoutMs: 120_000,          // default
+});
+```
+
+## Responses
+
+All methods resolve to the standard Captapi envelope:
+
+```json
+{ "success": true, "data": { ... } }
+```
+
+## Links
+
+- [Documentation](https://captapi.com/docs)
+- [Get an API key (100 free credits)](https://captapi.com/dashboard/api-keys)
+- Python SDK: [`pip install captapi`](https://pypi.org/project/captapi/)
+- MCP server for AI agents: [`@captapi/mcp`](https://www.npmjs.com/package/@captapi/mcp)
+- CLI: [`@captapi/cli`](https://www.npmjs.com/package/@captapi/cli)

package/dist/core.js

@@ -15,18 +15,24 @@ export class CaptapiError extends Error {
 }
 const RETRY_STATUSES = new Set([502, 503]);
 const RETRY_DELAY_MS = 500;
+function errorBag(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const root = body;
+    if (root.error && typeof root.error === "object") {
+        return root.error;
+    }
+    if (root.detail && typeof root.detail === "object") {
+        return root.detail;
+    }
+    return root;
+}
 function shouldRetry(status, body) {
-    if (!RETRY_STATUSES.has(status))
-        return false;
-    const bag = body && typeof body === "object" && "detail" in body
-        ? body.detail
-        : body;
-    if (bag && typeof bag === "object") {
-        const flags = bag;
-        if (flags.persistent === true || flags.replayed === true)
-            return false;
+    const bag = errorBag(body);
+    if (bag && typeof bag.retryable === "boolean") {
+        return bag.retryable === true;
     }
-    return true;
+    return RETRY_STATUSES.has(status);
 }
 export class HttpCore {
     apiKey;
@@ -45,13 +51,19 @@ export class HttpCore {
         this.fetchImpl = options.fetch ?? globalThis.fetch;
     }
     fail(path, status, body) {
-        const detail = body?.detail ?? body?.error ?? body;
-        const code = typeof body?.detail === "object" && body?.detail?.error
-            ? String(body.detail.error)
+        const bag = errorBag(body);
+        const detail = bag ?? body?.detail ?? body?.error ?? body;
+        const code = typeof bag?.code === "string"
+            ? bag.code
             : typeof body?.error === "string"
                 ? body.error
                 : undefined;
-        return new CaptapiError(`Captapi ${path} returned ${status}: ${typeof detail === "string" ? detail : JSON.stringify(detail ?? "unknown error")}`, status, code, detail);
+        const message = typeof bag?.message === "string"
+            ? bag.message
+            : typeof detail === "string"
+                ? detail
+                : JSON.stringify(detail ?? "unknown error");
+        return new CaptapiError(`Captapi ${path} returned ${status}: ${message}`, status, code, detail);
     }
     async parseBody(res) {
         try {