socialcrawl-mcp 1.1.0 → 1.2.0

package/README.md

@@ -211,21 +211,26 @@ Every response follows a unified envelope format:
 
 ## Available Tools
 
-The MCP server exposes 4 tools:
+The MCP server exposes 5 tools:
 
 | Tool | Description | Needs API key? |
 |------|-------------|----------------|
 | `socialcrawl_list_platforms` | Discover all 21 platforms with their endpoints and capabilities | No |
 | `socialcrawl_list_endpoints` | See all endpoints, required parameters, and credit costs for a platform | No |
-| `socialcrawl_request` | Make any SocialCrawl API call — profiles, posts, comments, search, analytics | Yes |
+| `socialcrawl_request` | Make any SocialCrawl API call — profiles, posts, comments, search, analytics. Supports an optional `idempotencyKey` for retry-safe calls. | Yes |
+| `socialcrawl_check_balance` | Check remaining credits and recent deduction summary. Calls `/v1/credits/balance` — costs 0 credits. | Yes |
 | `socialcrawl_get_docs` | Access detailed API documentation by topic or platform | No |
 
-Three of the four tools work without an API key — they query local bundled data. Only `socialcrawl_request` (which makes actual API calls) requires a key.
+Three of the five tools work without an API key — they query local bundled data. `socialcrawl_request` and `socialcrawl_check_balance` require a key.
 
 ### Smart validation
 
 Before making any API call, `socialcrawl_request` validates locally that the platform exists, the endpoint exists, and all required parameters are present. If something is wrong, it tells the agent exactly how to fix it — without consuming any credits.
 
+### Retry-safe requests
+
+Pass an `idempotencyKey` to `socialcrawl_request` (UUIDv4 recommended) to make the call retry-safe. If the request is replayed within 24h, the server returns the original response and deducts **0 credits** (`X-Idempotent-Replay: true`).
+
 ## Supported Platforms
 
 | Platform | Endpoints | Data Available |
@@ -265,7 +270,13 @@ The MCP server handles errors gracefully and gives the agent actionable guidance
 | Insufficient credits | Shows balance and links to billing page |
 | Bad platform/resource | Suggests using discovery tools to find the right endpoint |
 | Missing parameters | Lists exactly what's missing with examples |
-| Platform unavailable | Reports the outage; credits are refunded automatically |
+| Resource not found (404) | Reports the upstream resource doesn't exist; credits auto-refunded (BIL-01) |
+| Idempotency-Key conflict (409) | Tells the agent the key was used by another account — generate a fresh one |
+| Idempotency-Key payload mismatch (422) | Tells the agent the same key was reused with different params |
+| Method not allowed (405) | Reminds the caller that `/v1/*` is GET-only |
+| Concurrency limit (429) | Asks the caller to back off (50 concurrent/key max) |
+| Upstream error (502) | Reports the failure; credits refunded automatically |
+| Platform unavailable (503) | Circuit breaker open; credits refunded; retry in 30s |
 
 ## Links
 

package/dist/__tests__/check-balance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/check-balance.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { checkBalance } from "../tools/check-balance.js";
+describe("socialcrawl_check_balance tool", () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        process.env = { ...originalEnv, SOCIALCRAWL_API_KEY: "sc_test_key" };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+        vi.restoreAllMocks();
+    });
+    it("calls /v1/credits/balance with no platform prefix and no query string", async () => {
+        let capturedUrl = "";
+        vi.stubGlobal("fetch", async (url) => {
+            capturedUrl = url;
+            return new Response(JSON.stringify({
+                success: true,
+                platform: "meta",
+                endpoint: "/v1/credits/balance",
+                data: { balance: 8432, recent_deductions: { last_24h: 128, last_7d: 1043 } },
+                credits_used: 0,
+                credits_remaining: 8432,
+            }), { status: 200 });
+        });
+        const result = await checkBalance();
+        expect(capturedUrl).toContain("/v1/credits/balance");
+        expect(capturedUrl).not.toContain("/v1/meta/");
+        expect(capturedUrl).not.toContain("?");
+        expect(result).toContain("8432");
+    });
+    it("returns the No-API-key error when SOCIALCRAWL_API_KEY is missing", async () => {
+        delete process.env.SOCIALCRAWL_API_KEY;
+        const result = await checkBalance();
+        expect(result).toContain("No API key configured");
+    });
+    it("formats the balance response with a header noting 0-credit cost", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({
+            success: true,
+            platform: "meta",
+            endpoint: "/v1/credits/balance",
+            data: { balance: 100, recent_deductions: { last_24h: 0, last_7d: 0 } },
+            credits_used: 0,
+            credits_remaining: 100,
+        }), { status: 200 }));
+        const result = await checkBalance();
+        expect(result).toContain("/v1/credits/balance");
+        expect(result).toContain("0 credits");
+    });
+    it("propagates 401 errors with the Invalid API key message", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({ success: false, error: { type: "INVALID_API_KEY", message: "bad key" } }), { status: 401 }));
+        const result = await checkBalance();
+        expect(result).toContain("Invalid API key");
+    });
+});
+//# sourceMappingURL=check-balance.test.js.map

package/dist/__tests__/check-balance.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-balance.test.js","sourceRoot":"","sources":["../../src/__tests__/check-balance.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/client.test.js

@@ -68,5 +68,98 @@ describe("API client", () => {
         expect(result).toContain("Upstream error");
         expect(result).toContain("auto-refunded");
     });
+    it("maps 404 RESOURCE_NOT_FOUND to a refund-aware message", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({
+            success: false,
+            error: { type: "RESOURCE_NOT_FOUND", message: "Resource does not exist" },
+        }), { status: 404 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "ghost" } });
+        expect(result).toContain("Resource not found");
+        expect(result).toContain("refunded");
+        expect(result).not.toContain("socialcrawl_list_endpoints");
+    });
+    it("maps 405 METHOD_NOT_ALLOWED with the Allow header hint", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({
+            success: false,
+            error: { type: "METHOD_NOT_ALLOWED", message: "Only GET is allowed" },
+        }), { status: 405 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("Method not allowed");
+        expect(result).toContain("GET");
+    });
+    it("maps 409 IDEMPOTENCY_KEY_CONFLICT", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({
+            success: false,
+            error: { type: "IDEMPOTENCY_KEY_CONFLICT", message: "Key already used by another account" },
+        }), { status: 409 }));
+        const result = await makeRequest({
+            platform: "tiktok",
+            resource: "profile",
+            params: { handle: "test" },
+            idempotencyKey: "shared-key",
+        });
+        expect(result).toContain("Idempotency-Key");
+        expect(result).toContain("conflict");
+    });
+    it("maps 422 IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({
+            success: false,
+            error: { type: "IDEMPOTENCY_KEY_PAYLOAD_MISMATCH", message: "Key reused with different payload" },
+        }), { status: 422 }));
+        const result = await makeRequest({
+            platform: "tiktok",
+            resource: "profile",
+            params: { handle: "test" },
+            idempotencyKey: "reused-key",
+        });
+        expect(result).toContain("Idempotency-Key");
+        expect(result).toContain("different");
+    });
+    it("includes doc_url in default error formatting when present", async () => {
+        vi.stubGlobal("fetch", async () => new Response(JSON.stringify({
+            success: false,
+            error: {
+                type: "INTERNAL_ERROR",
+                message: "Something went wrong",
+                doc_url: "https://www.socialcrawl.dev/docs/errors/internal-error",
+            },
+        }), { status: 500 }));
+        const result = await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "test" } });
+        expect(result).toContain("INTERNAL_ERROR");
+        expect(result).toContain("https://www.socialcrawl.dev/docs/errors/internal-error");
+    });
+    it("forwards idempotencyKey as Idempotency-Key header", async () => {
+        let capturedHeaders = {};
+        vi.stubGlobal("fetch", async (_url, init) => {
+            capturedHeaders = init.headers;
+            return new Response(JSON.stringify({ success: true, data: {} }), { status: 200 });
+        });
+        await makeRequest({
+            platform: "tiktok",
+            resource: "profile",
+            params: { handle: "charlidamelio" },
+            idempotencyKey: "abc-123",
+        });
+        expect(capturedHeaders["Idempotency-Key"]).toBe("abc-123");
+    });
+    it("does not send Idempotency-Key header when not provided", async () => {
+        let capturedHeaders = {};
+        vi.stubGlobal("fetch", async (_url, init) => {
+            capturedHeaders = init.headers;
+            return new Response(JSON.stringify({ success: true, data: {} }), { status: 200 });
+        });
+        await makeRequest({ platform: "tiktok", resource: "profile", params: { handle: "charlidamelio" } });
+        expect(capturedHeaders["Idempotency-Key"]).toBeUndefined();
+    });
+    it("supports the meta platform for /v1/credits/balance", async () => {
+        let capturedUrl = "";
+        vi.stubGlobal("fetch", async (url) => {
+            capturedUrl = url;
+            return new Response(JSON.stringify({ success: true, data: { balance: 42 } }), { status: 200 });
+        });
+        await makeRequest({ platform: "meta", resource: "credits/balance" });
+        expect(capturedUrl).toContain("/v1/credits/balance");
+        expect(capturedUrl).not.toContain("?");
+    });
 });
 //# sourceMappingURL=client.test.js.map

package/dist/__tests__/client.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../src/__tests__/client.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.test.js","sourceRoot":"","sources":["../../src/__tests__/client.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/data-integrity.test.js

@@ -139,5 +139,61 @@ describe("Documentation data integrity", () => {
     it("getAvailableTopics returns at least 26 topics", () => {
         expect(getAvailableTopics().length).toBeGreaterThanOrEqual(26);
     });
+    it("getAvailableTopics includes the new idempotency topic", () => {
+        expect(getAvailableTopics()).toContain("idempotency");
+    });
+});
+describe("Errors documentation reflects 2026-04-17 backend", () => {
+    it("documents METHOD_NOT_ALLOWED (405)", () => {
+        const errors = getDoc("errors");
+        expect(errors).toContain("METHOD_NOT_ALLOWED");
+        expect(errors).toContain("405");
+    });
+    it("documents IDEMPOTENCY_KEY_CONFLICT (409)", () => {
+        const errors = getDoc("errors");
+        expect(errors).toContain("IDEMPOTENCY_KEY_CONFLICT");
+        expect(errors).toContain("409");
+    });
+    it("documents IDEMPOTENCY_KEY_PAYLOAD_MISMATCH (422)", () => {
+        const errors = getDoc("errors");
+        expect(errors).toContain("IDEMPOTENCY_KEY_PAYLOAD_MISMATCH");
+        expect(errors).toContain("422");
+    });
+    it("notes that RESOURCE_NOT_FOUND auto-refunds credits (BIL-01)", () => {
+        const errors = getDoc("errors");
+        // The RESOURCE_NOT_FOUND row should mention refund / auto-refund.
+        expect(errors).toMatch(/RESOURCE_NOT_FOUND[\s\S]*?refund/i);
+    });
+    it("uses the path-style doc_url format (no anchor fragment)", () => {
+        const errors = getDoc("errors");
+        expect(errors).not.toContain("docs/errors#");
+        expect(errors).toMatch(/docs\/errors\/[a-z-]+/);
+    });
+});
+describe("Credits documentation reflects 2026-04-17 backend", () => {
+    it("mentions the optional data._warnings advisory channel (ENV-03)", () => {
+        const credits = getDoc("credits");
+        expect(credits).toContain("_warnings");
+    });
+});
+describe("Idempotency documentation (BIL-02)", () => {
+    it("has an idempotency topic", () => {
+        expect(getDoc("idempotency")).toBeTruthy();
+    });
+    it("documents the Idempotency-Key header", () => {
+        const doc = getDoc("idempotency");
+        expect(doc).toContain("Idempotency-Key");
+    });
+    it("explains the 24h TTL and zero-credit replay", () => {
+        const doc = getDoc("idempotency");
+        expect(doc).toMatch(/24\s*h/i);
+        expect(doc).toContain("0 credit");
+    });
+});
+describe("Meta endpoint documentation (SEC-02)", () => {
+    it("overview mentions /v1/credits/balance", () => {
+        const overview = getDoc("overview");
+        expect(overview).toContain("/v1/credits/balance");
+    });
 });
 //# sourceMappingURL=data-integrity.test.js.map

package/dist/__tests__/data-integrity.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"data-integrity.test.js","sourceRoot":"","sources":["../../src/__tests__/data-integrity.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"data-integrity.test.js","sourceRoot":"","sources":["../../src/__tests__/data-integrity.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACvF,OAAO,EAAQ,MAAM,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEnE,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,SAAS,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;YACnC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;YACnC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,UAAU,EAAE,CAAC;YAC1C,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACpD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;QAC7B,MAAM,CAAC,MAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,mBAAmB,EAAE,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,UAAU,EAAE,CAAC;YACvC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,UAAU,EAAE,CAAC;YACvC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpC,MAAM,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YAC3E,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YAClD,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,CAAC;YACxC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;QACxC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,SAAS,GAA2B,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACpF,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC;QACnE,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC;QAC7C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAClE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,SAAS,GAAG,sBAAsB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACxD,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;QACxD,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;gBACpC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;gBAChC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,UAAU,EAAE,CAAC;gBACvC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,CAAC;YACrC,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,EAAE,GAAG,YAAY,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC7C,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QACzB,MAAM,CAAC,EAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACrC,MAAM,CAAC,EAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,CAAC,EAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IAChE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,QAAQ,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAChD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC1E,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;gBACzC,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;oBAC3B,MAAM,CACJ,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EACzB,GAAG,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,mBAAmB,MAAM,yBAAyB,CAC5F,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACf,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,IAAI,QAAQ,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC;gBAAE,SAAS;YAChD,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAClE,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;gBACzC,KAAK,MAAM,MAAM,IAAI,KAAK,EAAE,CAAC;oBAC3B,MAAM,CACJ,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,EACzB,GAAG,QAAQ,CAAC,QAAQ,IAAI,QAAQ,CAAC,QAAQ,mBAAmB,MAAM,8BAA8B,CACjG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAChB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,cAAc,EAAE,CAAC;gBAC1C,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;gBAC9B,MAAM,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACrE,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;oBACxB,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,CAAC;oBACrC,MAAM,CAAC,GAAG,CAAC,UAAW,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;gBACpD,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,gEAAgE,EAAE,GAAG,EAAE;QACxE,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;QACpC,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;QAC9C,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;QACvC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,CAAC,GAAG,EAAE,8BAA8B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC;QAC1E,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,aAAa,EAAE,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+CAA+C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,kBAAkB,EAAE,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uDAAuD,EAAE,GAAG,EAAE;QAC/D,MAAM,CAAC,kBAAkB,EAAE,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,kDAAkD,EAAE,GAAG,EAAE;IAChE,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAE,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,oBAAoB,CAAC,CAAC;QAC/C,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAE,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,0BAA0B,CAAC,CAAC;QACrD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAE,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,kCAAkC,CAAC,CAAC;QAC7D,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACrE,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAE,CAAC;QACjC,kEAAkE;QAClE,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,mCAAmC,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAE,CAAC;QACjC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,mDAAmD,EAAE,GAAG,EAAE;IACjE,EAAE,CAAC,gEAAgE,EAAE,GAAG,EAAE;QACxE,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAE,CAAC;QACnC,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,oCAAoC,EAAE,GAAG,EAAE;IAClD,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,aAAa,CAAE,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,GAAG,GAAG,MAAM,CAAC,aAAa,CAAE,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAC/B,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,sCAAsC,EAAE,GAAG,EAAE;IACpD,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAE,CAAC;QACrC,MAAM,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/preflight.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import { request } from "../tools/request.js";
 describe("Pre-flight validation", () => {
     it("rejects unknown platform", async () => {
@@ -45,4 +45,28 @@ describe("Pre-flight validation", () => {
         expect(result).toContain("No API key configured");
     });
 });
+describe("request tool — idempotency forwarding", () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        process.env = { ...originalEnv, SOCIALCRAWL_API_KEY: "sc_test_key" };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+        vi.restoreAllMocks();
+    });
+    it("forwards idempotencyKey to the API client as Idempotency-Key header", async () => {
+        let capturedHeaders = {};
+        vi.stubGlobal("fetch", async (_url, init) => {
+            capturedHeaders = init.headers;
+            return new Response(JSON.stringify({ success: true, data: {} }), { status: 200 });
+        });
+        await request({
+            platform: "tiktok",
+            resource: "profile",
+            params: { handle: "charlidamelio" },
+            idempotencyKey: "tool-key-xyz",
+        });
+        expect(capturedHeaders["Idempotency-Key"]).toBe("tool-key-xyz");
+    });
+});
 //# sourceMappingURL=preflight.test.js.map

package/dist/__tests__/preflight.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"preflight.test.js","sourceRoot":"","sources":["../../src/__tests__/preflight.test.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"preflight.test.js","sourceRoot":"","sources":["../../src/__tests__/preflight.test.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -2,6 +2,13 @@ interface RequestOptions {
     platform: string;
     resource: string;
     params?: Record<string, string>;
+    /**
+     * Optional `Idempotency-Key` header value (BIL-02). Pass an opaque, client-generated
+     * string (UUIDv4 recommended) to enable safe retries. The first response is stored
+     * server-side for 24h; replays return the original body, status, and credits_used
+     * (with a `X-Idempotent-Replay: true` header), and deduct 0 new credits.
+     */
+    idempotencyKey?: string;
 }
 export declare function makeRequest(options: RequestOptions): Promise<string>;
 export {};

package/dist/client.js

@@ -13,12 +13,14 @@ export async function makeRequest(options) {
     const url = buildUrl(options);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    const headers = { "x-api-key": apiKey };
+    if (options.idempotencyKey) {
+        headers["Idempotency-Key"] = options.idempotencyKey;
+    }
     try {
         const response = await fetch(url, {
             method: "GET",
-            headers: {
-                "x-api-key": apiKey,
-            },
+            headers,
             signal: controller.signal,
         });
         const body = await response.text();
@@ -41,7 +43,10 @@ export async function makeRequest(options) {
     }
 }
 function buildUrl(options) {
-    const base = `${getBaseUrl()}/v1/${options.platform}/${options.resource}`;
+    const path = options.platform === "meta"
+        ? `/v1/${options.resource}`
+        : `/v1/${options.platform}/${options.resource}`;
+    const base = `${getBaseUrl()}${path}`;
     if (!options.params || Object.keys(options.params).length === 0) {
         return base;
     }
@@ -58,6 +63,7 @@ function formatHttpError(status, body, options) {
     }
     const errorType = parsed?.error?.type ?? "UNKNOWN_ERROR";
     const errorMessage = parsed?.error?.message ?? body;
+    const docUrl = parsed?.error?.doc_url;
     switch (status) {
         case 401:
             return "Error: Invalid API key. Check your SOCIALCRAWL_API_KEY configuration.";
@@ -66,15 +72,26 @@ function formatHttpError(status, body, options) {
         case 400:
             return `Error: ${errorMessage}`;
         case 404:
+            if (errorType === "RESOURCE_NOT_FOUND") {
+                return `Error: Resource not found upstream. The requested ${options.platform} resource doesn't exist. Credits have been refunded automatically.`;
+            }
             return `Error: Endpoint /v1/${options.platform}/${options.resource} not found. Use socialcrawl_list_endpoints to see available endpoints for ${options.platform}.`;
-        case 503:
-            return `Error: Platform ${options.platform} is temporarily unavailable. Try again shortly.`;
+        case 405:
+            return "Error: Method not allowed. SocialCrawl /v1/* endpoints accept GET requests only.";
+        case 409:
+            return "Error: Idempotency-Key conflict. The key you supplied was already used by another account. Generate a fresh key (UUIDv4 recommended).";
+        case 422:
+            return "Error: Idempotency-Key payload mismatch. You reused the same key with different parameters. Either use a different key, or repeat the original request exactly.";
+        case 429:
+            return "Error: Too many concurrent requests on this API key (50 max). Wait a moment and try again.";
         case 502:
             return "Error: Upstream error fetching data. Credits have been auto-refunded.";
-        case 429:
-            return "Error: Too many concurrent requests. Wait a moment and try again.";
-        default:
-            return `Error (${status}): ${errorType} — ${errorMessage}`;
+        case 503:
+            return `Error: Platform ${options.platform} is temporarily unavailable. Credits have been auto-refunded — retry in 30 seconds.`;
+        default: {
+            const docHint = docUrl ? ` See ${docUrl}` : "";
+            return `Error (${status}): ${errorType} — ${errorMessage}${docHint}`;
+        }
     }
 }
 function truncateResponse(body) {

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/data/docs.js

@@ -12,7 +12,7 @@ Unified social media data API. One API key, one response format, 21 platforms, 1
 
 ## Base URL
 
-https://socialcrawl.dev/v1
+https://www.socialcrawl.dev/v1
 
 ## Authentication
 
@@ -30,26 +30,32 @@ ${PLATFORMS.map((p) => `- ${p.slug} (${p.endpointCount} endpoint${p.endpointCoun
 
 Most endpoints cost 1 credit (standard tier). Heavier endpoints (trending feeds, audience analytics, ad transparency, AI-powered utilities) cost 5 or 10.
 
+## Meta Endpoints
+
+API-key-authed endpoints that return account metadata at 0 credit cost:
+
+- \`GET /v1/credits/balance\` — current credit balance and recent deduction summary. Use the \`socialcrawl_check_balance\` tool to call it.
+
 ## Full Reference
 
 For complete endpoint documentation with parameters, examples, and response schemas:
-https://socialcrawl.dev/llms-full.txt
+https://www.socialcrawl.dev/llms-full.txt
 
 ## OpenAPI Spec
 
-https://socialcrawl.dev/v1/openapi.json`,
+https://www.socialcrawl.dev/v1/openapi.json`,
     authentication: `# SocialCrawl API — Authentication
 
 Every request requires an \`x-api-key\` header with your API key. Keys start with \`sc_\`.
 
 \`\`\`
-curl https://socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio \\
+curl https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio \\
   -H "x-api-key: sc_your_api_key_here"
 \`\`\`
 
 ## Where to get a key
 
-Sign up at https://socialcrawl.dev — every account starts with 100 free credits, no credit card required.
+Sign up at https://www.socialcrawl.dev — every account starts with 100 free credits, no credit card required.
 
 ## Key management
 
@@ -74,7 +80,23 @@ Every request costs credits. The MCP server pre-calculates cost from the endpoin
 
 ## Caching
 
-Cached responses are free — the envelope includes \`"cached": true\` and no credits are deducted. Cache TTLs range from 2 minutes (search) to 30 minutes (analytics).
+Cached responses are free (BIL-03) — the envelope includes \`"cached": true\` and no credits are deducted. Cache TTLs range from 2 minutes (search) to 30 minutes (analytics).
+
+## Empty upstream auto-refund (BIL-01)
+
+When the upstream returns 200 with an empty body for a nonexistent profile/post (e.g. an Instagram handle that does not exist), the API auto-refunds the credit and returns a 404 \`RESOURCE_NOT_FOUND\` envelope. You are never billed for missing resources.
+
+## Idempotent retries (BIL-02)
+
+Pass an \`Idempotency-Key\` header to make a request safely retryable. Replays return the original response, deduct 0 new credits, and include \`X-Idempotent-Replay: true\`. The \`socialcrawl_request\` tool accepts an \`idempotencyKey\` parameter for this.
+
+## Check balance (SEC-02)
+
+Use the \`socialcrawl_check_balance\` tool — it calls \`GET /v1/credits/balance\` and costs 0 credits.
+
+## Advisory warnings (ENV-03)
+
+Successful responses may include an optional \`data._warnings\` string array — non-fatal notices from the transform pipeline (e.g. an engagement-rate clamp). Treat as observability hints, not as failures.
 
 ## Insufficient credits
 
@@ -90,7 +112,7 @@ All errors follow the same envelope:
     "type": "INVALID_REQUEST",
     "message": "Missing required parameter: handle",
     "status": 400,
-    "doc_url": "https://socialcrawl.dev/docs/errors#invalid-request"
+    "doc_url": "https://www.socialcrawl.dev/docs/errors/invalid-request"
   },
   "credits_remaining": 99,
   "request_id": "req-XXXXX"
@@ -104,17 +126,56 @@ All errors follow the same envelope:
 | \`MISSING_API_KEY\` | 401 | No \`x-api-key\` header supplied |
 | \`INVALID_API_KEY\` | 401 | Key does not exist or has been revoked |
 | \`INSUFFICIENT_CREDITS\` | 402 | Account balance too low for this endpoint |
-| \`INVALID_REQUEST\` | 400 | Missing/invalid parameter, bad platform, bad resource |
+| \`INVALID_REQUEST\` | 400 | Missing/invalid parameter, bad platform/handle/URL format (ERR-01) |
+| \`METHOD_NOT_ALLOWED\` | 405 | Non-GET request against \`/v1/*\` (ERR-02). Response includes \`Allow: GET\` |
 | \`ENDPOINT_NOT_FOUND\` | 404 | Unknown platform+resource combination |
-| \`RESOURCE_NOT_FOUND\` | 404 | Upstream resource (profile, post, etc.) does not exist |
-| \`CONCURRENCY_LIMIT\` | 429 | Too many simultaneous requests on the same API key |
+| \`RESOURCE_NOT_FOUND\` | 404 | Upstream resource does not exist or empty body (BIL-01) — credits auto-refunded |
+| \`IDEMPOTENCY_KEY_CONFLICT\` | 409 | \`Idempotency-Key\` already used by another account (BIL-02) |
+| \`IDEMPOTENCY_KEY_PAYLOAD_MISMATCH\` | 422 | Same \`Idempotency-Key\` reused with different parameters (BIL-02) |
+| \`CONCURRENCY_LIMIT\` | 429 | Too many simultaneous requests on the same API key (50 max) |
 | \`UPSTREAM_ERROR\` | 502 | ScrapeCreators upstream failed — credits are refunded automatically |
-| \`SERVICE_UNAVAILABLE\` | 503 | Temporary outage — retry with exponential backoff |
-| \`INTERNAL_ERROR\` | 500 | Bug on our side — the request ID in the response is the fastest way to report it |
+| \`SERVICE_UNAVAILABLE\` | 503 | Circuit breaker open — credits refunded, response includes \`Retry-After: 30\` |
+| \`INTERNAL_ERROR\` | 500 | Bug on our side — credits refunded; the request ID in the response is the fastest way to report it |
+
+## Auto-refund matrix
+
+Credits are refunded automatically on: 404 \`RESOURCE_NOT_FOUND\` (empty upstream — BIL-01), 502 \`UPSTREAM_ERROR\`, 503 \`SERVICE_UNAVAILABLE\`, 500 \`INTERNAL_ERROR\`. Cache hits, 405, 409, and 422 never deduct credits in the first place.
 
 ## Client-side validation
 
 Before making any request, the MCP server validates locally that the platform exists, the resource exists, and all required parameters (including \`oneOf\` groups) are present. This avoids burning credits on malformed calls.`,
+    idempotency: `# SocialCrawl API — Idempotent Requests (BIL-02)
+
+Any \`/v1/*\` request can be made retry-safe by supplying an \`Idempotency-Key\` header. Network blips, agent retries, and redelivery from a queue stop being a billing risk.
+
+## How to use it
+
+The \`socialcrawl_request\` tool accepts an optional \`idempotencyKey\` parameter:
+
+- Use a UUIDv4 (or any opaque 16+ character string) the agent can regenerate on retry.
+- Reuse the same key across retries of the same logical operation.
+- Generate a fresh key for each new logical operation.
+
+## What the server does
+
+\`lookupIdempotency(userId, key, requestHash)\` returns one of four verdicts:
+
+| Outcome | HTTP | Body | Credits |
+|---------|------|------|---------|
+| \`proceed\` | (continues normal flow) | — | normal cost |
+| \`replay\` | 200 (original status) | stored response verbatim, with \`X-Idempotent-Replay: true\` header | 0 deducted |
+| \`conflict\` | 409 | \`IDEMPOTENCY_KEY_CONFLICT\` | 0 |
+| \`payload_mismatch\` | 422 | \`IDEMPOTENCY_KEY_PAYLOAD_MISMATCH\` | 0 |
+
+The \`requestHash\` is a stable hash of \`(method, path, sorted query params)\`.
+
+## TTL
+
+Idempotency rows live for **24h**. After that the key is reusable.
+
+## Credits and cache
+
+Replays cost **0 credits** — same as cache hits.`,
 };
 function buildCurl(e) {
     const parts = [];
@@ -133,7 +194,7 @@ function buildCurl(e) {
     }
     const qs = parts.length > 0 ? `?${parts.join("&")}` : "";
     return [
-        `curl "https://socialcrawl.dev/v1/${e.platform}/${e.resource}${qs}" \\`,
+        `curl "https://www.socialcrawl.dev/v1/${e.platform}/${e.resource}${qs}" \\`,
         `  -H "x-api-key: sc_your_api_key_here"`,
     ].join("\n");
 }
@@ -182,9 +243,9 @@ function buildPlatformDoc(slug) {
     const endpoints = getEndpointsByPlatform(slug);
     const header = [
         `# SocialCrawl API — ${platform.name} endpoints`,
-        `# Base URL: https://socialcrawl.dev`,
+        `# Base URL: https://www.socialcrawl.dev`,
         `# Auth: x-api-key header`,
-        `# Full docs: https://socialcrawl.dev/docs/${slug}`,
+        `# Full docs: https://www.socialcrawl.dev/docs/${slug}`,
         "",
         platform.description,
         "",
@@ -204,7 +265,7 @@ function buildFullDoc() {
         "Every request requires an `x-api-key` header:",
         "",
         "```",
-        'curl https://socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio \\',
+        'curl https://www.socialcrawl.dev/v1/tiktok/profile?handle=charlidamelio \\',
         '  -H "x-api-key: sc_your_api_key_here"',
         "```",
         "",
@@ -252,6 +313,7 @@ export const DOCS = (() => {
         authentication: HANDWRITTEN.authentication,
         credits: HANDWRITTEN.credits,
         errors: HANDWRITTEN.errors,
+        idempotency: HANDWRITTEN.idempotency,
         full: buildFullDoc(),
     };
     for (const platform of PLATFORMS) {
@@ -269,6 +331,7 @@ export function getAvailableTopics() {
         "authentication",
         "credits",
         "errors",
+        "idempotency",
         ...PLATFORMS.map((p) => p.slug),
     ];
 }

package/dist/data/docs.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/data/docs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAGnE;;;;GAIG;AAEH,MAAM,WAAW,GAA2B;IAC1C,QAAQ,EAAE;;;;;;;;;;;;;;EAcV,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,aAAa,YAAY,CAAC,CAAC,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;wCAiBzE;IAEtC,cAAc,EAAE;;;;;;;;;;;;;;;;;;;;;mMAqBiL;IAEjM,OAAO,EAAE;;;;;;;;;;;;;;;;;;uKAkB4J;IAErK,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iOAmCuN;CAChO,CAAC;AAEF,SAAS,SAAS,CAAC,CAAW;IAC5B,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,iCAAiC;IACjC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,yEAAyE;IACzE,iEAAiE;IACjE,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAClC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACpF,IAAI,OAAO;YAAE,SAAS;QACtB,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,GAAG,kBAAkB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACtD,CAAC;IAED,MAAM,EAAE,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,OAAO;QACL,oCAAoC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,GAAG,EAAE,MAAM;QACvE,wCAAwC;KACzC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,kBAAkB,CAAC,CAAW;IACrC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;IACtB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC;IAC7D,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,WAAW,gBAAgB,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;QAC7E,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7B,KAAK,MAAM,KAAK,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrD,KAAK,CAAC,IAAI,CAAC,sBAAsB,IAAI,0BAA0B,CAAC,CAAC;QACnE,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,IAAI,CAAC,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC;QACnC,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,cAAc,EAAE,CAAC;YACnC,MAAM,SAAS,GACb,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,GAAG,CAAC,UAAU;gBACnC,CAAC,CAAC,SAAS,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;gBACrC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;YACf,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5D,KAAK,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,IAAI,OAAO,SAAS,IAAI,IAAI,EAAE,CAAC,CAAC;QACxD,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IACzB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAElB,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IACpC,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IACxD,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,MAAM,SAAS,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG;QACb,uBAAuB,QAAQ,CAAC,IAAI,YAAY;QAChD,qCAAqC;QACrC,0BAA0B;QAC1B,6CAA6C,IAAI,EAAE;QACnD,EAAE;QACF,QAAQ,CAAC,WAAW;QACpB,EAAE;QACF,GAAG,SAAS,CAAC,MAAM,YAAY,SAAS,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG;QACnE,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACjE,CAAC;AAED,SAAS,YAAY;IACnB,MAAM,QAAQ,GAAa;QACzB,WAAW,CAAC,QAAQ;QACpB,EAAE;QACF,KAAK;QACL,EAAE;QACF,mBAAmB;QACnB,EAAE;QACF,+CAA+C;QAC/C,EAAE;QACF,KAAK;QACL,wEAAwE;QACxE,wCAAwC;QACxC,KAAK;QACL,EAAE;QACF,oBAAoB;QACpB,EAAE;QACF,qCAAqC;QACrC,EAAE;QACF,SAAS;QACT,GAAG;QACH,oBAAoB;QACpB,yBAAyB;QACzB,qCAAqC;QACrC,8BAA8B;QAC9B,sBAAsB;QACtB,8BAA8B;QAC9B,8BAA8B;QAC9B,mBAAmB;QACnB,GAAG;QACH,KAAK;QACL,EAAE;QACF,KAAK;QACL,EAAE;KACH,CAAC;IAEF,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,QAAQ,CAAC,IAAI,CAAC,KAAK,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClB,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAClB,MAAM,SAAS,GAAG,sBAAsB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;YAC1B,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;YACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACpB,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC;IAED,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,IAAI,GAA2B,CAAC,GAAG,EAAE;IAChD,MAAM,GAAG,GAA2B;QAClC,QAAQ,EAAE,WAAW,CAAC,QAAQ;QAC9B,cAAc,EAAE,WAAW,CAAC,cAAc;QAC1C,OAAO,EAAE,WAAW,CAAC,OAAO;QAC5B,MAAM,EAAE,WAAW,CAAC,MAAM;QAC1B,IAAI,EAAE,YAAY,EAAE;KACrB,CAAC;IACF,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC,EAAE,CAAC;AAEL,MAAM,UAAU,MAAM,CAAC,KAAa;IAClC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,UAAU;QACV,MAAM;QACN,gBAAgB;QAChB,SAAS;QACT,QAAQ;QACR,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;KAChC,CAAC;AACJ,CAAC;AAED,qFAAqF;AACrF,KAAK,SAAS,CAAC"}
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/data/docs.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -2,10 +2,11 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
-import { ListPlatformsInputSchema, ListEndpointsInputSchema, RequestInputSchema, GetDocsInputSchema, } from "./schemas/tools.js";
+import { ListPlatformsInputSchema, ListEndpointsInputSchema, RequestInputSchema, CheckBalanceInputSchema, GetDocsInputSchema, } from "./schemas/tools.js";
 import { listPlatforms } from "./tools/list-platforms.js";
 import { listEndpoints } from "./tools/list-endpoints.js";
 import { request } from "./tools/request.js";
+import { checkBalance } from "./tools/check-balance.js";
 import { getDocs } from "./tools/get-docs.js";
 const server = new McpServer({
     name: SERVER_NAME,
@@ -41,7 +42,7 @@ server.registerTool("socialcrawl_list_endpoints", {
 });
 server.registerTool("socialcrawl_request", {
     title: "Make a SocialCrawl API Request",
-    description: "Make an API request to any SocialCrawl endpoint. Fetches real-time social media data (profiles, posts, comments, search results, analytics) from 21 platforms. Requires a valid SOCIALCRAWL_API_KEY. Validates platform, resource, and parameters before making the call to avoid wasting credits.",
+    description: "Make an API request to any SocialCrawl endpoint. Fetches real-time social media data (profiles, posts, comments, search results, analytics) from 21 platforms. Requires a valid SOCIALCRAWL_API_KEY. Validates platform, resource, and parameters before making the call to avoid wasting credits. Pass an optional idempotencyKey to make the request retry-safe (replays return the original response and deduct 0 credits).",
     inputSchema: RequestInputSchema,
     annotations: {
         readOnlyHint: true,
@@ -54,9 +55,24 @@ server.registerTool("socialcrawl_request", {
         platform: params.platform,
         resource: params.resource,
         params: params.params,
+        idempotencyKey: params.idempotencyKey,
     });
     return { content: [{ type: "text", text: output }] };
 });
+server.registerTool("socialcrawl_check_balance", {
+    title: "Check SocialCrawl Credit Balance",
+    description: "Check the remaining credit balance and recent deductions for the authenticated SocialCrawl account. Calls the meta endpoint GET /v1/credits/balance — costs 0 credits. Requires a valid SOCIALCRAWL_API_KEY.",
+    inputSchema: CheckBalanceInputSchema,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, async () => {
+    const output = await checkBalance();
+    return { content: [{ type: "text", text: output }] };
+});
 server.registerTool("socialcrawl_get_docs", {
     title: "Get SocialCrawl Documentation",
     description: "Retrieve SocialCrawl API documentation. Topics: 'overview' (compact intro), 'full' (comprehensive reference), 'authentication', 'credits', 'errors', or any platform slug (e.g., 'tiktok') for platform-specific docs. No API key required.",

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/schemas/tools.d.ts

@@ -11,15 +11,19 @@ export declare const RequestInputSchema: z.ZodObject<{
     platform: z.ZodEnum<[string, ...string[]]>;
     resource: z.ZodString;
     params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    idempotencyKey: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     platform: string;
     resource: string;
     params?: Record<string, string> | undefined;
+    idempotencyKey?: string | undefined;
 }, {
     platform: string;
     resource: string;
     params?: Record<string, string> | undefined;
+    idempotencyKey?: string | undefined;
 }>;
+export declare const CheckBalanceInputSchema: z.ZodObject<{}, "strict", z.ZodTypeAny, {}, {}>;
 export declare const GetDocsInputSchema: z.ZodObject<{
     topic: z.ZodDefault<z.ZodOptional<z.ZodString>>;
 }, "strict", z.ZodTypeAny, {

package/dist/schemas/tools.js

@@ -19,12 +19,18 @@ export const RequestInputSchema = z.object({
         .record(z.string())
         .optional()
         .describe("Query parameters as key-value pairs (e.g., { handle: 'charlidamelio' })"),
+    idempotencyKey: z
+        .string()
+        .min(16, "Idempotency-Key should be at least 16 characters (UUIDv4 recommended)")
+        .optional()
+        .describe("Optional Idempotency-Key header. Lets you safely retry the same request — replays return the original response and deduct 0 credits (24h TTL)."),
 }).strict();
+export const CheckBalanceInputSchema = z.object({}).strict();
 export const GetDocsInputSchema = z.object({
     topic: z
         .string()
         .optional()
         .default("overview")
-        .describe("Documentation topic: 'overview', 'full', 'authentication', 'credits', 'errors', or a platform slug (e.g., 'tiktok')"),
+        .describe("Documentation topic: 'overview', 'full', 'authentication', 'credits', 'errors', 'idempotency', or a platform slug (e.g., 'tiktok')"),
 }).strict();
 //# sourceMappingURL=tools.js.map

package/dist/schemas/tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/schemas/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAC;AAE5C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAE9D,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,QAAQ,EAAE,CAAC;SACR,IAAI,CAAC,aAAsC,CAAC;SAC5C,QAAQ,CAAC,wDAAwD,CAAC;CACtE,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,QAAQ,EAAE,CAAC;SACR,IAAI,CAAC,aAAsC,CAAC;SAC5C,QAAQ,CAAC,wDAAwD,CAAC;IACrE,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,2BAA2B,CAAC;SACnC,QAAQ,CAAC,4DAA4D,CAAC;IACzE,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SAClB,QAAQ,EAAE;SACV,QAAQ,CAAC,yEAAyE,CAAC;CACvF,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CAAC,qHAAqH,CAAC;CACnI,CAAC,CAAC,MAAM,EAAE,CAAC"}
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/schemas/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,aAAa,GAAG,mBAAmB,EAAE,CAAC;AAE5C,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAE9D,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,QAAQ,EAAE,CAAC;SACR,IAAI,CAAC,aAAsC,CAAC;SAC5C,QAAQ,CAAC,wDAAwD,CAAC;CACtE,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,QAAQ,EAAE,CAAC;SACR,IAAI,CAAC,aAAsC,CAAC;SAC5C,QAAQ,CAAC,wDAAwD,CAAC;IACrE,QAAQ,EAAE,CAAC;SACR,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,EAAE,2BAA2B,CAAC;SACnC,QAAQ,CAAC,4DAA4D,CAAC;IACzE,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SAClB,QAAQ,EAAE;SACV,QAAQ,CAAC,yEAAyE,CAAC;IACtF,cAAc,EAAE,CAAC;SACd,MAAM,EAAE;SACR,GAAG,CAAC,EAAE,EAAE,uEAAuE,CAAC;SAChF,QAAQ,EAAE;SACV,QAAQ,CACP,gJAAgJ,CACjJ;CACJ,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAE7D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,KAAK,EAAE,CAAC;SACL,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,OAAO,CAAC,UAAU,CAAC;SACnB,QAAQ,CACP,oIAAoI,CACrI;CACJ,CAAC,CAAC,MAAM,EAAE,CAAC"}

package/dist/tools/check-balance.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Calls the SEC-02 meta endpoint `GET /v1/credits/balance` (api-key auth, 0 credits).
+ * Returns the wrapped envelope as a markdown-formatted string the agent can read.
+ */
+export declare function checkBalance(): Promise<string>;

package/dist/tools/check-balance.js

@@ -0,0 +1,25 @@
+import { makeRequest } from "../client.js";
+/**
+ * Calls the SEC-02 meta endpoint `GET /v1/credits/balance` (api-key auth, 0 credits).
+ * Returns the wrapped envelope as a markdown-formatted string the agent can read.
+ */
+export async function checkBalance() {
+    const response = await makeRequest({ platform: "meta", resource: "credits/balance" });
+    const header = [
+        "## SocialCrawl Credit Balance",
+        "**Endpoint:** `GET /v1/credits/balance`",
+        "**Credit cost:** 0 credits (meta endpoint)",
+        "",
+    ].join("\n");
+    if (response.startsWith("Error:")) {
+        return `${header}${response}`;
+    }
+    try {
+        const parsed = JSON.parse(response);
+        return `${header}\`\`\`json\n${JSON.stringify(parsed, null, 2)}\n\`\`\``;
+    }
+    catch {
+        return `${header}${response}`;
+    }
+}
+//# sourceMappingURL=check-balance.js.map

package/dist/tools/check-balance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-balance.js","sourceRoot":"","sources":["../../src/tools/check-balance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY;IAChC,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,CAAC;IAEtF,MAAM,MAAM,GAAG;QACb,+BAA+B;QAC/B,yCAAyC;QACzC,4CAA4C;QAC5C,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,IAAI,QAAQ,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClC,OAAO,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC;IAChC,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAA4B,CAAC;QAC/D,OAAO,GAAG,MAAM,eAAe,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC;IAChC,CAAC;AACH,CAAC"}

package/dist/tools/request.d.ts

@@ -2,6 +2,7 @@ interface RequestParams {
     platform: string;
     resource: string;
     params?: Record<string, string>;
+    idempotencyKey?: string;
 }
 export declare function request(input: RequestParams): Promise<string>;
 export {};

package/dist/tools/request.js

@@ -31,6 +31,7 @@ export async function request(input) {
         platform: input.platform,
         resource: input.resource,
         params: input.params,
+        idempotencyKey: input.idempotencyKey,
     });
     const header = [
         `## SocialCrawl API Response`,

package/dist/tools/request.js.map

@@ -1 +1 @@
-{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/tools/request.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request.js","sourceRoot":"","sources":["../../src/tools/request.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "socialcrawl-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP server for SocialCrawl — access 21+ social media platforms through one unified API",
   "type": "module",
   "main": "dist/index.js",