facebook-mcp-server 1.6.6

package/dist/client.js

@@ -0,0 +1,140 @@
+/**
+ * Facebook Graph API client.
+ *
+ * Raw fetch wrapper against https://graph.facebook.com/v21.0/.
+ * No SDK — keeps dependencies minimal (Occam's Razor).
+ * Client instances are cached by credential hash.
+ */
+import { createHash } from "node:crypto";
+const GRAPH_API_BASE = "https://graph.facebook.com/v21.0";
+const CLIENT_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+const clientCache = new Map();
+function credentialHash(creds) {
+    const raw = `${creds.accessToken}:${creds.pageId}`;
+    return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+/**
+ * Get or create a cached Facebook client.
+ */
+export function createClient(creds) {
+    const key = credentialHash(creds);
+    const now = Date.now();
+    // Evict stale entries on every call
+    for (const [k, v] of clientCache) {
+        if (now - v.createdAt >= CLIENT_TTL_MS) {
+            clientCache.delete(k);
+        }
+    }
+    const cached = clientCache.get(key);
+    if (cached)
+        return cached.client;
+    const client = new FacebookClient(creds);
+    clientCache.set(key, { client, createdAt: now });
+    return client;
+}
+function isGraphApiError(body) {
+    return (typeof body === "object" &&
+        body !== null &&
+        "error" in body &&
+        typeof body.error === "object" &&
+        typeof body.error.message === "string");
+}
+/**
+ * Error thrown for Graph API failures. Carries structured error data
+ * for suggestAction() to inspect.
+ */
+export class FacebookApiError extends Error {
+    status;
+    code;
+    errorSubcode;
+    errorType;
+    retryAfter;
+    constructor(status, apiError, retryAfter) {
+        super(apiError.message);
+        this.name = "FacebookApiError";
+        this.status = status;
+        this.code = apiError.code;
+        this.errorSubcode = apiError.error_subcode;
+        this.errorType = apiError.type;
+        this.retryAfter = retryAfter;
+    }
+}
+export class FacebookClient {
+    accessToken;
+    pageId;
+    constructor(creds) {
+        this.accessToken = creds.accessToken;
+        this.pageId = creds.pageId;
+    }
+    /**
+     * Make a GET request to the Graph API.
+     */
+    async get(path, params) {
+        const url = new URL(`${GRAPH_API_BASE}${path}`);
+        url.searchParams.set("access_token", this.accessToken);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        const res = await fetch(url, {
+            signal: AbortSignal.timeout(30_000),
+        });
+        return this.handleResponse(res);
+    }
+    /**
+     * Make a POST request to the Graph API.
+     */
+    async post(path, body) {
+        const url = new URL(`${GRAPH_API_BASE}${path}`);
+        url.searchParams.set("access_token", this.accessToken);
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(30_000),
+        });
+        return this.handleResponse(res);
+    }
+    /**
+     * Make a DELETE request to the Graph API.
+     */
+    async delete(path) {
+        const url = new URL(`${GRAPH_API_BASE}${path}`);
+        url.searchParams.set("access_token", this.accessToken);
+        const res = await fetch(url, {
+            method: "DELETE",
+            signal: AbortSignal.timeout(30_000),
+        });
+        return this.handleResponse(res);
+    }
+    async handleResponse(res) {
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            // Non-JSON response (HTML error page during outage, empty body, etc.)
+            throw new FacebookApiError(res.status, {
+                message: `HTTP ${res.status}: Response is not valid JSON (likely an outage or proxy error)`,
+                type: "ParseError",
+                code: res.status,
+            });
+        }
+        if (!res.ok) {
+            const retryAfterHeader = res.headers.get("Retry-After");
+            const seconds = retryAfterHeader ? parseInt(retryAfterHeader, 10) : NaN;
+            const retryAfter = !isNaN(seconds) ? seconds : undefined;
+            if (isGraphApiError(body)) {
+                throw new FacebookApiError(res.status, body.error, retryAfter);
+            }
+            // Non-standard error response — wrap in a generic error
+            throw new FacebookApiError(res.status, {
+                message: `HTTP ${res.status}: ${JSON.stringify(body)}`,
+                type: "UnknownError",
+                code: res.status,
+            }, retryAfter);
+        }
+        return body;
+    }
+}

package/dist/client.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Unit tests for the Graph API HTTP client.
+ *
+ * Uses vi.stubGlobal("fetch", ...) to stub network calls. Every test resets
+ * the stub in afterEach to prevent leakage. The most important test here is
+ * the one asserting GRAPH_API_BASE points at graph.facebook.com — it's a
+ * regression guard ensuring the correct API base URL is used.
+ */
+export {};

package/dist/client.test.js

@@ -0,0 +1,211 @@
+/**
+ * Unit tests for the Graph API HTTP client.
+ *
+ * Uses vi.stubGlobal("fetch", ...) to stub network calls. Every test resets
+ * the stub in afterEach to prevent leakage. The most important test here is
+ * the one asserting GRAPH_API_BASE points at graph.facebook.com — it's a
+ * regression guard ensuring the correct API base URL is used.
+ */
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { createClient, FacebookApiError, FacebookClient, } from "./client.js";
+// Reach into the module's source to read the base URL constant.
+// We assert on actual request URLs below, which is the real contract.
+const creds = {
+    accessToken: "EAALtest123",
+    pageId: "548545275018321",
+};
+function mockFetchOk(body, init = {}) {
+    return vi.fn(async () => new Response(JSON.stringify(body), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+        ...init,
+    }));
+}
+function mockFetchError(status, body, headers = {}) {
+    return vi.fn(async () => new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json", ...headers },
+    }));
+}
+describe("FacebookClient — URL construction", () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it("GET builds URL against graph.facebook.com/v21.0 (REGRESSION: Bug #1)", async () => {
+        const fetchMock = mockFetchOk({ data: [] });
+        vi.stubGlobal("fetch", fetchMock);
+        const client = new FacebookClient(creds);
+        await client.get("/548545275018321/insights");
+        const [url] = fetchMock.mock.calls[0];
+        expect(url.toString()).toMatch(/^https:\/\/graph\.facebook\.com\/v21\.0\/548545275018321\/insights\?/);
+    });
+    it("GET puts access_token and extra params in query string", async () => {
+        const fetchMock = mockFetchOk({ data: [] });
+        vi.stubGlobal("fetch", fetchMock);
+        const client = new FacebookClient(creds);
+        await client.get("/548545275018321/insights", {
+            metric: "reach,profile_views",
+            period: "day",
+        });
+        const url = fetchMock.mock.calls[0][0];
+        expect(url.searchParams.get("access_token")).toBe("EAALtest123");
+        expect(url.searchParams.get("metric")).toBe("reach,profile_views");
+        expect(url.searchParams.get("period")).toBe("day");
+    });
+    it("POST sends JSON body with correct Content-Type", async () => {
+        const fetchMock = mockFetchOk({ id: "new_media_id" });
+        vi.stubGlobal("fetch", fetchMock);
+        const client = new FacebookClient(creds);
+        await client.post("/548545275018321/media", {
+            image_url: "https://example.com/test.jpg",
+            caption: "hello",
+        });
+        const [, init] = fetchMock.mock.calls[0];
+        expect(init?.method).toBe("POST");
+        const headers = init?.headers;
+        expect(headers["Content-Type"]).toBe("application/json");
+        expect(JSON.parse(init?.body)).toEqual({
+            image_url: "https://example.com/test.jpg",
+            caption: "hello",
+        });
+    });
+    it("POST includes access_token in query even when body is present", async () => {
+        const fetchMock = mockFetchOk({ id: "x" });
+        vi.stubGlobal("fetch", fetchMock);
+        const client = new FacebookClient(creds);
+        await client.post("/548545275018321/media_publish", {
+            creation_id: "abc",
+        });
+        const url = fetchMock.mock.calls[0][0];
+        expect(url.searchParams.get("access_token")).toBe("EAALtest123");
+    });
+    it("DELETE sends DELETE method", async () => {
+        const fetchMock = mockFetchOk({ success: true });
+        vi.stubGlobal("fetch", fetchMock);
+        const client = new FacebookClient(creds);
+        await client.delete("/comment_id_123");
+        const [, init] = fetchMock.mock.calls[0];
+        expect(init?.method).toBe("DELETE");
+    });
+});
+describe("FacebookClient — error handling", () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it("parses Graph API error into FacebookApiError with status/code/subcode", async () => {
+        vi.stubGlobal("fetch", mockFetchError(400, {
+            error: {
+                message: "Invalid OAuth access token",
+                type: "OAuthException",
+                code: 190,
+                error_subcode: 460,
+                fbtrace_id: "abc123",
+            },
+        }));
+        const client = new FacebookClient(creds);
+        await expect(client.get("/me")).rejects.toMatchObject({
+            name: "FacebookApiError",
+            status: 400,
+            code: 190,
+            errorSubcode: 460,
+            errorType: "OAuthException",
+            message: "Invalid OAuth access token",
+        });
+    });
+    it("wraps non-JSON HTML error responses in FacebookApiError", async () => {
+        const fetchMock = vi.fn(async () => new Response("<html>502 Bad Gateway</html>", {
+            status: 502,
+            headers: { "content-type": "text/html" },
+        }));
+        vi.stubGlobal("fetch", fetchMock);
+        const client = new FacebookClient(creds);
+        await expect(client.get("/me")).rejects.toMatchObject({
+            status: 502,
+            errorType: "ParseError",
+        });
+    });
+    it("passes through Retry-After header as retryAfter", async () => {
+        vi.stubGlobal("fetch", mockFetchError(429, {
+            error: {
+                message: "Rate limited",
+                type: "OAuthException",
+                code: 4,
+            },
+        }, { "Retry-After": "90" }));
+        const client = new FacebookClient(creds);
+        try {
+            await client.get("/me");
+            expect.fail("should have thrown");
+        }
+        catch (e) {
+            expect(e).toBeInstanceOf(FacebookApiError);
+            expect(e.retryAfter).toBe(90);
+        }
+    });
+    it("wraps non-GraphAPI JSON error shapes in UnknownError", async () => {
+        vi.stubGlobal("fetch", mockFetchError(500, { something: "weird" }));
+        const client = new FacebookClient(creds);
+        await expect(client.get("/me")).rejects.toMatchObject({
+            status: 500,
+            errorType: "UnknownError",
+        });
+    });
+});
+describe("createClient — caching", () => {
+    beforeEach(() => {
+        // Clear module state between tests by re-requiring isn't straightforward
+        // in ESM. Instead we rely on the fact that each cache key includes the
+        // full token+account pair — using unique tokens per test keeps them
+        // isolated.
+    });
+    it("returns the same instance for identical credentials", () => {
+        const a = createClient({ accessToken: "tok_same", pageId: "page_1" });
+        const b = createClient({ accessToken: "tok_same", pageId: "page_1" });
+        expect(a).toBe(b);
+    });
+    it("returns different instances for different tokens", () => {
+        const a = createClient({ accessToken: "tok_A_unique", pageId: "page_x" });
+        const b = createClient({ accessToken: "tok_B_unique", pageId: "page_x" });
+        expect(a).not.toBe(b);
+    });
+    it("returns different instances for different account IDs", () => {
+        const a = createClient({ accessToken: "tok_shared", pageId: "page_1_u" });
+        const b = createClient({ accessToken: "tok_shared", pageId: "page_2_u" });
+        expect(a).not.toBe(b);
+    });
+    it("returned clients carry the provided creds", () => {
+        const client = createClient({
+            accessToken: "tok_readback",
+            pageId: "page_readback",
+        });
+        expect(client.accessToken).toBe("tok_readback");
+        expect(client.pageId).toBe("page_readback");
+    });
+});
+describe("FacebookApiError — shape", () => {
+    it("carries all graph-api error fields", () => {
+        const err = new FacebookApiError(400, {
+            message: "boom",
+            type: "OAuthException",
+            code: 100,
+            error_subcode: 2207052,
+        }, 30);
+        expect(err).toBeInstanceOf(Error);
+        expect(err.name).toBe("FacebookApiError");
+        expect(err.status).toBe(400);
+        expect(err.code).toBe(100);
+        expect(err.errorSubcode).toBe(2207052);
+        expect(err.errorType).toBe("OAuthException");
+        expect(err.retryAfter).toBe(30);
+        expect(err.message).toBe("boom");
+    });
+    it("allows undefined subcode and retryAfter", () => {
+        const err = new FacebookApiError(500, {
+            message: "server error",
+            type: "InternalError",
+            code: 1,
+        });
+        expect(err.errorSubcode).toBeUndefined();
+        expect(err.retryAfter).toBeUndefined();
+    });
+});

package/dist/create-post.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Pure helpers for fb_create_post — validation + request shaping.
+ *
+ * Extracted from index.ts so the attachment-routing logic can be unit-tested
+ * without spinning up the MCP server or mocking HTTP. Every branch here has
+ * a test in create-post.test.ts.
+ */
+export interface CreatePostArgs {
+    message?: string;
+    link?: string;
+    imageUrl?: string;
+    videoUrl?: string;
+    published?: boolean;
+}
+export interface CreatePostValidationError {
+    ok: false;
+    error: string;
+    message: string;
+    action?: string;
+}
+export interface CreatePostRequest {
+    ok: true;
+    endpoint: (pageId: string) => string;
+    body: Record<string, unknown>;
+    type: "text" | "link" | "photo" | "video";
+}
+export type CreatePostResult = CreatePostValidationError | CreatePostRequest;
+export declare const FB_MESSAGE_MAX_LENGTH = 63206;
+/**
+ * Validate fb_create_post arguments and return either a structured error
+ * or the request recipe (endpoint + body + content type) the tool should
+ * send to the Graph API.
+ *
+ * This function is pure — it has no side effects, does no IO, and does not
+ * depend on env vars or a client instance. The caller is responsible for
+ * substituting the real page id into `endpoint(pageId)` and actually
+ * dispatching the request.
+ */
+export declare function buildCreatePostRequest(args: CreatePostArgs): CreatePostResult;

package/dist/create-post.js

@@ -0,0 +1,85 @@
+/**
+ * Pure helpers for fb_create_post — validation + request shaping.
+ *
+ * Extracted from index.ts so the attachment-routing logic can be unit-tested
+ * without spinning up the MCP server or mocking HTTP. Every branch here has
+ * a test in create-post.test.ts.
+ */
+// Facebook Page post hard cap per Meta docs.
+export const FB_MESSAGE_MAX_LENGTH = 63206;
+/**
+ * Validate fb_create_post arguments and return either a structured error
+ * or the request recipe (endpoint + body + content type) the tool should
+ * send to the Graph API.
+ *
+ * This function is pure — it has no side effects, does no IO, and does not
+ * depend on env vars or a client instance. The caller is responsible for
+ * substituting the real page id into `endpoint(pageId)` and actually
+ * dispatching the request.
+ */
+export function buildCreatePostRequest(args) {
+    const hasLink = !!args.link;
+    const hasImage = !!args.imageUrl;
+    const hasVideo = !!args.videoUrl;
+    const attachmentCount = [hasLink, hasImage, hasVideo].filter(Boolean).length;
+    // Rule 1: at most one attachment type
+    if (attachmentCount > 1) {
+        return {
+            ok: false,
+            error: "Invalid input",
+            message: "Exactly one of link, imageUrl, or videoUrl may be provided (or none for text-only).",
+            action: "FIX_INPUT: Pick a single attachment type per post. For multi-photo posts, fall back to calling fb_create_post once per photo.",
+        };
+    }
+    // Rule 2: must have SOMETHING
+    if (!args.message && attachmentCount === 0) {
+        return {
+            ok: false,
+            error: "Invalid input",
+            message: "A post must have at least a message, link, imageUrl, or videoUrl.",
+        };
+    }
+    // Rule 3: message length
+    if (args.message && args.message.length > FB_MESSAGE_MAX_LENGTH) {
+        return {
+            ok: false,
+            error: "Invalid input",
+            message: `Message is ${args.message.length} chars, Facebook max is ${FB_MESSAGE_MAX_LENGTH}.`,
+            action: "CAPTION_TOO_LONG: Shorten the message and retry.",
+        };
+    }
+    // Build the request body
+    const body = {};
+    if (args.message)
+        body.message = args.message;
+    if (args.published === false)
+        body.published = false;
+    // Route to the correct endpoint based on attachment type
+    if (hasImage) {
+        body.url = args.imageUrl;
+        return {
+            ok: true,
+            endpoint: (pageId) => `/${pageId}/photos`,
+            body,
+            type: "photo",
+        };
+    }
+    if (hasVideo) {
+        body.file_url = args.videoUrl;
+        return {
+            ok: true,
+            endpoint: (pageId) => `/${pageId}/videos`,
+            body,
+            type: "video",
+        };
+    }
+    // Text-only OR link attachment — both go through /feed
+    if (hasLink)
+        body.link = args.link;
+    return {
+        ok: true,
+        endpoint: (pageId) => `/${pageId}/feed`,
+        body,
+        type: hasLink ? "link" : "text",
+    };
+}

package/dist/create-post.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Unit tests for buildCreatePostRequest — the pure validation + routing
+ * helper backing fb_create_post.
+ *
+ * Each test is a regression guard for a specific branch of the tool's
+ * pre-flight logic. This closes the coverage gap identified in the Facebook
+ * MCP test audit: the 4 most FB-specific code paths (attachment routing,
+ * mutual-exclusion, caption length, empty-input) were previously only
+ * covered by live manual testing.
+ */
+export {};

package/dist/create-post.test.js

@@ -0,0 +1,175 @@
+/**
+ * Unit tests for buildCreatePostRequest — the pure validation + routing
+ * helper backing fb_create_post.
+ *
+ * Each test is a regression guard for a specific branch of the tool's
+ * pre-flight logic. This closes the coverage gap identified in the Facebook
+ * MCP test audit: the 4 most FB-specific code paths (attachment routing,
+ * mutual-exclusion, caption length, empty-input) were previously only
+ * covered by live manual testing.
+ */
+import { describe, it, expect } from "vitest";
+import { buildCreatePostRequest, FB_MESSAGE_MAX_LENGTH, } from "./create-post.js";
+describe("buildCreatePostRequest — validation", () => {
+    it("rejects empty input (no message, no attachment)", () => {
+        const r = buildCreatePostRequest({});
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.error).toBe("Invalid input");
+            expect(r.message).toMatch(/at least a message, link, imageUrl, or videoUrl/);
+        }
+    });
+    it("rejects when two attachment types are provided (link + imageUrl)", () => {
+        const r = buildCreatePostRequest({
+            message: "x",
+            link: "https://a.com",
+            imageUrl: "https://example.com/x.jpg",
+        });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.message).toMatch(/Exactly one of link, imageUrl, or videoUrl/);
+            expect(r.action).toMatch(/^FIX_INPUT:/);
+        }
+    });
+    it("rejects when all three attachment types are provided", () => {
+        const r = buildCreatePostRequest({
+            link: "https://a.com",
+            imageUrl: "https://example.com/x.jpg",
+            videoUrl: "https://example.com/x.mp4",
+        });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.action).toMatch(/^FIX_INPUT:/);
+        }
+    });
+    it("rejects message longer than Facebook's 63206 char limit", () => {
+        const r = buildCreatePostRequest({ message: "x".repeat(63207) });
+        expect(r.ok).toBe(false);
+        if (!r.ok) {
+            expect(r.message).toMatch(/63207 chars, Facebook max is 63206/);
+            expect(r.action).toMatch(/^CAPTION_TOO_LONG:/);
+        }
+    });
+    it("accepts exactly 63206 chars (boundary condition)", () => {
+        const r = buildCreatePostRequest({
+            message: "x".repeat(FB_MESSAGE_MAX_LENGTH),
+        });
+        expect(r.ok).toBe(true);
+    });
+});
+describe("buildCreatePostRequest — routing", () => {
+    it("routes text-only post to /{pageId}/feed with message", () => {
+        const r = buildCreatePostRequest({ message: "hello world" });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.type).toBe("text");
+            expect(r.endpoint("548545275018321")).toBe("/548545275018321/feed");
+            expect(r.body).toEqual({ message: "hello world" });
+        }
+    });
+    it("routes link post to /feed with link field", () => {
+        const r = buildCreatePostRequest({
+            message: "check this out",
+            link: "https://www.luminarylane.app",
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.type).toBe("link");
+            expect(r.endpoint("548545275018321")).toBe("/548545275018321/feed");
+            expect(r.body).toEqual({
+                message: "check this out",
+                link: "https://www.luminarylane.app",
+            });
+        }
+    });
+    it("routes link post WITHOUT message to /feed (message optional for link)", () => {
+        const r = buildCreatePostRequest({ link: "https://www.luminarylane.app" });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.type).toBe("link");
+            expect(r.body).toEqual({ link: "https://www.luminarylane.app" });
+            expect(r.body.message).toBeUndefined();
+        }
+    });
+    it("routes photo post to /{pageId}/photos with url (not link)", () => {
+        const r = buildCreatePostRequest({
+            message: "a cat",
+            imageUrl: "https://example.com/cat.jpg",
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.type).toBe("photo");
+            expect(r.endpoint("548545275018321")).toBe("/548545275018321/photos");
+            expect(r.body).toEqual({
+                message: "a cat",
+                url: "https://example.com/cat.jpg",
+            });
+            // Ensure we did NOT accidentally set the `link` field
+            expect(r.body.link).toBeUndefined();
+        }
+    });
+    it("routes photo post without caption", () => {
+        const r = buildCreatePostRequest({
+            imageUrl: "https://example.com/cat.jpg",
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.type).toBe("photo");
+            expect(r.body.message).toBeUndefined();
+            expect(r.body.url).toBe("https://example.com/cat.jpg");
+        }
+    });
+    it("routes video post to /{pageId}/videos with file_url", () => {
+        const r = buildCreatePostRequest({
+            message: "watch",
+            videoUrl: "https://example.com/clip.mp4",
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.type).toBe("video");
+            expect(r.endpoint("548545275018321")).toBe("/548545275018321/videos");
+            expect(r.body).toEqual({
+                message: "watch",
+                file_url: "https://example.com/clip.mp4",
+            });
+        }
+    });
+    it("passes published=false through to body when provided", () => {
+        const r = buildCreatePostRequest({
+            message: "draft",
+            published: false,
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.body.published).toBe(false);
+        }
+    });
+    it("does NOT set published when undefined (defaults to FB's true)", () => {
+        const r = buildCreatePostRequest({ message: "live" });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.body.published).toBeUndefined();
+            expect("published" in r.body).toBe(false);
+        }
+    });
+    it("does NOT set published when explicitly true (let FB default stand)", () => {
+        const r = buildCreatePostRequest({
+            message: "live",
+            published: true,
+        });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.body.published).toBeUndefined();
+        }
+    });
+});
+describe("buildCreatePostRequest — endpoint is a pure function of pageId", () => {
+    it("endpoint builder returns different paths for different page ids", () => {
+        const r = buildCreatePostRequest({ message: "x" });
+        expect(r.ok).toBe(true);
+        if (r.ok) {
+            expect(r.endpoint("111")).toBe("/111/feed");
+            expect(r.endpoint("222")).toBe("/222/feed");
+        }
+    });
+});

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Error mapping helpers — pure functions only, no IO.
+ *
+ * extractApiDetail() formats an FacebookApiError for human/agent consumption.
+ * suggestAction() maps (statusCode, detail) → an AGENT_ACTION hint string.
+ *
+ * These functions are pure and heavily unit-tested in errors.test.ts.
+ * Every hint string is a regression guard for a real bug discovered during
+ * live testing against the Facebook Graph API.
+ */
+export declare function extractApiDetail(e: unknown): string | undefined;
+export declare function suggestAction(toolName: string, statusCode: number | undefined, detail: string | undefined, errorMsg?: string): string | undefined;