instagram-mcp-server 1.6.6

package/dist/client.js

@@ -0,0 +1,140 @@
+/**
+ * Instagram Graph API client.
+ *
+ * Raw fetch wrapper against https://graph.instagram.com/v22.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.accountId}`;
+    return createHash("sha256").update(raw).digest("hex").slice(0, 16);
+}
+/**
+ * Get or create a cached Instagram 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 InstagramClient(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 InstagramApiError extends Error {
+    status;
+    code;
+    errorSubcode;
+    errorType;
+    retryAfter;
+    constructor(status, apiError, retryAfter) {
+        super(apiError.message);
+        this.name = "InstagramApiError";
+        this.status = status;
+        this.code = apiError.code;
+        this.errorSubcode = apiError.error_subcode;
+        this.errorType = apiError.type;
+        this.retryAfter = retryAfter;
+    }
+}
+export class InstagramClient {
+    accessToken;
+    accountId;
+    constructor(creds) {
+        this.accessToken = creds.accessToken;
+        this.accountId = creds.accountId;
+    }
+    /**
+     * 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 InstagramApiError(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 InstagramApiError(res.status, body.error, retryAfter);
+            }
+            // Non-standard error response — wrap in a generic error
+            throw new InstagramApiError(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,10 @@
+/**
+ * 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 for Bug #1 discovered during live testing (the scaffold
+ * incorrectly used graph.instagram.com which rejects Facebook Login tokens).
+ */
+export {};

package/dist/client.test.js

@@ -0,0 +1,212 @@
+/**
+ * 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 for Bug #1 discovered during live testing (the scaffold
+ * incorrectly used graph.instagram.com which rejects Facebook Login tokens).
+ */
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { createClient, InstagramApiError, InstagramClient, } 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",
+    accountId: "17841400000000000",
+};
+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("InstagramClient — 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 InstagramClient(creds);
+        await client.get("/17841400000000000/insights");
+        const [url] = fetchMock.mock.calls[0];
+        expect(url.toString()).toMatch(/^https:\/\/graph\.facebook\.com\/v21\.0\/17841400000000000\/insights\?/);
+    });
+    it("GET puts access_token and extra params in query string", async () => {
+        const fetchMock = mockFetchOk({ data: [] });
+        vi.stubGlobal("fetch", fetchMock);
+        const client = new InstagramClient(creds);
+        await client.get("/17841400000000000/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 InstagramClient(creds);
+        await client.post("/17841400000000000/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 InstagramClient(creds);
+        await client.post("/17841400000000000/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 InstagramClient(creds);
+        await client.delete("/comment_id_123");
+        const [, init] = fetchMock.mock.calls[0];
+        expect(init?.method).toBe("DELETE");
+    });
+});
+describe("InstagramClient — error handling", () => {
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it("parses Graph API error into InstagramApiError 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 InstagramClient(creds);
+        await expect(client.get("/me")).rejects.toMatchObject({
+            name: "InstagramApiError",
+            status: 400,
+            code: 190,
+            errorSubcode: 460,
+            errorType: "OAuthException",
+            message: "Invalid OAuth access token",
+        });
+    });
+    it("wraps non-JSON HTML error responses in InstagramApiError", 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 InstagramClient(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 InstagramClient(creds);
+        try {
+            await client.get("/me");
+            expect.fail("should have thrown");
+        }
+        catch (e) {
+            expect(e).toBeInstanceOf(InstagramApiError);
+            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 InstagramClient(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", accountId: "acc_1" });
+        const b = createClient({ accessToken: "tok_same", accountId: "acc_1" });
+        expect(a).toBe(b);
+    });
+    it("returns different instances for different tokens", () => {
+        const a = createClient({ accessToken: "tok_A_unique", accountId: "acc_x" });
+        const b = createClient({ accessToken: "tok_B_unique", accountId: "acc_x" });
+        expect(a).not.toBe(b);
+    });
+    it("returns different instances for different account IDs", () => {
+        const a = createClient({ accessToken: "tok_shared", accountId: "acc_1_u" });
+        const b = createClient({ accessToken: "tok_shared", accountId: "acc_2_u" });
+        expect(a).not.toBe(b);
+    });
+    it("returned clients carry the provided creds", () => {
+        const client = createClient({
+            accessToken: "tok_readback",
+            accountId: "acc_readback",
+        });
+        expect(client.accessToken).toBe("tok_readback");
+        expect(client.accountId).toBe("acc_readback");
+    });
+});
+describe("InstagramApiError — shape", () => {
+    it("carries all graph-api error fields", () => {
+        const err = new InstagramApiError(400, {
+            message: "boom",
+            type: "OAuthException",
+            code: 100,
+            error_subcode: 2207052,
+        }, 30);
+        expect(err).toBeInstanceOf(Error);
+        expect(err.name).toBe("InstagramApiError");
+        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 InstagramApiError(500, {
+            message: "server error",
+            type: "InternalError",
+            code: 1,
+        });
+        expect(err.errorSubcode).toBeUndefined();
+        expect(err.retryAfter).toBeUndefined();
+    });
+});

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Error mapping helpers — pure functions only, no IO.
+ *
+ * extractApiDetail() formats an InstagramApiError 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 Instagram 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;

package/dist/errors.js

@@ -0,0 +1,87 @@
+/**
+ * Error mapping helpers — pure functions only, no IO.
+ *
+ * extractApiDetail() formats an InstagramApiError 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 Instagram Graph API.
+ */
+import { InstagramApiError } from "./client.js";
+export function extractApiDetail(e) {
+    if (e instanceof InstagramApiError) {
+        const sub = e.errorSubcode ? ` (subcode: ${e.errorSubcode})` : "";
+        return `${e.errorType}: ${e.message}${sub}`;
+    }
+    return undefined;
+}
+export function suggestAction(toolName, statusCode, detail, errorMsg) {
+    const d = (detail || errorMsg || "").toLowerCase();
+    // Network-level errors
+    if (statusCode === undefined) {
+        if (d.includes("enotfound") || d.includes("dns"))
+            return "DNS_FAILURE: Cannot resolve graph.facebook.com. Check your internet connection.";
+        if (d.includes("timeout") || d.includes("abort"))
+            return "TIMEOUT: Request to Instagram timed out. Check your connection and retry.";
+        if (d.includes("econnrefused") || d.includes("econnreset"))
+            return "CONNECTION_FAILED: Cannot connect to Instagram. The service may be down. Retry in 30s.";
+        if (d.includes("fetch failed"))
+            return "NETWORK_ERROR: Network request failed. Check your internet connection and retry.";
+        return undefined;
+    }
+    // Token-invalidity errors can come back as 400 with an OAuthException.
+    // Match only explicit token-failure phrasing — NOT the bare word "oauth",
+    // because OAuthException is the generic error type for all Graph API failures.
+    if (d.includes("invalid oauth access token") ||
+        d.includes("access token has expired") ||
+        d.includes("session has expired") ||
+        d.includes("access token is invalid") ||
+        d.includes("cannot parse access token") ||
+        d.includes("malformed access token")) {
+        return "AUTH_FAILED: Access token is invalid or expired. Generate a new long-lived token via the Facebook Developer Console.";
+    }
+    switch (statusCode) {
+        case 400:
+            if ((d.includes("invalid") && d.includes("media")) ||
+                d.includes("photo or video can be accepted") ||
+                d.includes("2207052") ||
+                d.includes("2207027"))
+                return "INVALID_MEDIA: The media URL is invalid or inaccessible. Ensure the URL is publicly accessible, returns image/jpeg or image/png content-type, is not behind a redirect, and is not rate-limited by the host.";
+            if (d.includes("caption") || d.includes("too long"))
+                return "CAPTION_TOO_LONG: Caption exceeds 2200 characters. Shorten it and retry.";
+            if (d.includes("children") || d.includes("carousel"))
+                return "INVALID_CAROUSEL: Carousel requires 2-10 items. Check item count and media URLs.";
+            if (d.includes("hashtag"))
+                return "INVALID_HASHTAG: Hashtag search is limited to 30 unique hashtags per 7-day rolling window.";
+            return "INVALID_REQUEST: Check the error message and fix the input parameters.";
+        case 401:
+            return "AUTH_FAILED: Access token is invalid or expired. Generate a new long-lived token via the Facebook Developer Console.";
+        case 403:
+            if (d.includes("permission"))
+                return "PERMISSION_DENIED: Your token lacks the required permission. Check token permissions in Facebook Developer Console.";
+            if (d.includes("not approved") || d.includes("app not"))
+                return "APP_NOT_APPROVED: Your Facebook app needs approval for this permission. Submit for review in the App Dashboard.";
+            if (d.includes("business"))
+                return "BUSINESS_ACCOUNT_REQUIRED: This feature requires an Instagram Business or Creator account linked to a Facebook Page.";
+            return "FORBIDDEN: Instagram rejected this action. Check the error message for details.";
+        case 404: {
+            const t = toolName.toLowerCase();
+            if (t.includes("comment"))
+                return "COMMENT_NOT_FOUND: This comment may have been deleted. Skip it and move on.";
+            if (t.includes("post") || t.includes("insight"))
+                return "MEDIA_NOT_FOUND: This post may have been deleted or the ID is invalid. Skip it.";
+            if (t.includes("story"))
+                return "STORY_NOT_FOUND: Stories expire after 24 hours. This story is no longer available.";
+            return "NOT_FOUND: The requested resource does not exist. It may have been deleted.";
+        }
+        case 429:
+            return "RATE_LIMITED: Instagram rate limit hit after automatic retries. Wait 60s and retry, or switch to a different task.";
+        case 500:
+        case 502:
+        case 503:
+            return "SERVER_ERROR: Instagram is having issues. Wait 30s and retry once.";
+        default:
+            return undefined;
+    }
+}

package/dist/errors.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Unit tests for error mapping helpers.
+ *
+ * Every test case here is a regression guard for a specific bug discovered
+ * during live testing against the real Instagram Graph API. Changing any of
+ * the asserted strings without updating the tool's error-handling docs is
+ * a contract break for agents consuming these responses.
+ */
+export {};

package/dist/errors.test.js

@@ -0,0 +1,164 @@
+/**
+ * Unit tests for error mapping helpers.
+ *
+ * Every test case here is a regression guard for a specific bug discovered
+ * during live testing against the real Instagram Graph API. Changing any of
+ * the asserted strings without updating the tool's error-handling docs is
+ * a contract break for agents consuming these responses.
+ */
+import { describe, it, expect } from "vitest";
+import { extractApiDetail, suggestAction } from "./errors.js";
+import { InstagramApiError } from "./client.js";
+describe("extractApiDetail", () => {
+    it("returns undefined for non-InstagramApiError values", () => {
+        expect(extractApiDetail(new Error("boom"))).toBeUndefined();
+        expect(extractApiDetail("string error")).toBeUndefined();
+        expect(extractApiDetail(null)).toBeUndefined();
+        expect(extractApiDetail(undefined)).toBeUndefined();
+    });
+    it("formats InstagramApiError without subcode", () => {
+        const err = new InstagramApiError(400, {
+            message: "Invalid OAuth access token - Cannot parse access token",
+            type: "OAuthException",
+            code: 190,
+        });
+        expect(extractApiDetail(err)).toBe("OAuthException: Invalid OAuth access token - Cannot parse access token");
+    });
+    it("formats InstagramApiError with subcode", () => {
+        const err = new InstagramApiError(400, {
+            message: "Media ID is not available",
+            type: "OAuthException",
+            code: 100,
+            error_subcode: 2207027,
+        });
+        expect(extractApiDetail(err)).toBe("OAuthException: Media ID is not available (subcode: 2207027)");
+    });
+});
+describe("suggestAction — network errors (no statusCode)", () => {
+    it("ENOTFOUND → DNS_FAILURE", () => {
+        const r = suggestAction("ig_get_account_insights", undefined, undefined, "getaddrinfo ENOTFOUND graph.facebook.com");
+        expect(r).toMatch(/^DNS_FAILURE:/);
+    });
+    it("timeout → TIMEOUT", () => {
+        expect(suggestAction("ig_get_comments", undefined, undefined, "The operation was aborted due to timeout")).toMatch(/^TIMEOUT:/);
+    });
+    it("ECONNREFUSED → CONNECTION_FAILED", () => {
+        expect(suggestAction("ig_get_comments", undefined, undefined, "connect ECONNREFUSED 31.13.84.4:443")).toMatch(/^CONNECTION_FAILED:/);
+    });
+    it("fetch failed → NETWORK_ERROR", () => {
+        expect(suggestAction("ig_get_comments", undefined, undefined, "fetch failed")).toMatch(/^NETWORK_ERROR:/);
+    });
+    it("unknown network error → undefined", () => {
+        expect(suggestAction("ig_get_comments", undefined, undefined, "something weird")).toBeUndefined();
+    });
+});
+describe("suggestAction — token errors (high priority for Bug #6)", () => {
+    it("'Invalid OAuth access token' → AUTH_FAILED", () => {
+        const r = suggestAction("ig_get_account_insights", 400, "OAuthException: Invalid OAuth access token - Cannot parse access token");
+        expect(r).toMatch(/^AUTH_FAILED:/);
+    });
+    it("'Cannot parse access token' → AUTH_FAILED", () => {
+        expect(suggestAction("any", 400, "Cannot parse access token")).toMatch(/^AUTH_FAILED:/);
+    });
+    it("'access token has expired' → AUTH_FAILED", () => {
+        expect(suggestAction("any", 400, "Error validating access token: access token has expired")).toMatch(/^AUTH_FAILED:/);
+    });
+    it("'session has expired' → AUTH_FAILED", () => {
+        expect(suggestAction("any", 400, "The session has expired on Tuesday")).toMatch(/^AUTH_FAILED:/);
+    });
+    it("'malformed access token' → AUTH_FAILED", () => {
+        expect(suggestAction("any", 400, "Malformed access token")).toMatch(/^AUTH_FAILED:/);
+    });
+    // REGRESSION: generic OAuthException for metric errors must NOT be AUTH_FAILED
+    it("metric error mentioning OAuthException is NOT AUTH_FAILED", () => {
+        const metricErr = "OAuthException: (#100) metric[2] must be one of the following values: reach, follower_count, profile_views";
+        const r = suggestAction("ig_get_stories_insights", 400, metricErr);
+        expect(r).not.toMatch(/^AUTH_FAILED:/);
+        expect(r).toMatch(/^INVALID_REQUEST:/);
+    });
+});
+describe("suggestAction — 400 media errors (regression guard for Bug #9)", () => {
+    it("'photo or video can be accepted' → INVALID_MEDIA", () => {
+        const r = suggestAction("ig_publish_photo", 400, "OAuthException: Only photo or video can be accepted as media type. (subcode: 2207052)");
+        expect(r).toMatch(/^INVALID_MEDIA:/);
+    });
+    it("subcode 2207052 → INVALID_MEDIA", () => {
+        expect(suggestAction("ig_publish_carousel", 400, "Some error text (subcode: 2207052)")).toMatch(/^INVALID_MEDIA:/);
+    });
+    it("subcode 2207027 → INVALID_MEDIA", () => {
+        expect(suggestAction("ig_publish_photo", 400, "Media ID is not available (subcode: 2207027)")).toMatch(/^INVALID_MEDIA:/);
+    });
+    it("'invalid media URL' → INVALID_MEDIA", () => {
+        expect(suggestAction("ig_publish_photo", 400, "Invalid media URL provided")).toMatch(/^INVALID_MEDIA:/);
+    });
+});
+describe("suggestAction — other 400 branches", () => {
+    it("caption mention → CAPTION_TOO_LONG", () => {
+        expect(suggestAction("ig_publish_photo", 400, "Caption is too long")).toMatch(/^CAPTION_TOO_LONG:/);
+    });
+    it("'too long' → CAPTION_TOO_LONG", () => {
+        expect(suggestAction("ig_publish_photo", 400, "Value too long")).toMatch(/^CAPTION_TOO_LONG:/);
+    });
+    it("carousel children error → INVALID_CAROUSEL", () => {
+        expect(suggestAction("ig_publish_carousel", 400, "Carousel children must be between 2 and 10")).toMatch(/^INVALID_CAROUSEL:/);
+    });
+    it("hashtag error → INVALID_HASHTAG", () => {
+        expect(suggestAction("ig_get_hashtag_search", 400, "Hashtag quota exceeded")).toMatch(/^INVALID_HASHTAG:/);
+    });
+    it("unmatched 400 → INVALID_REQUEST", () => {
+        expect(suggestAction("any", 400, "Unknown bad request reason")).toMatch(/^INVALID_REQUEST:/);
+    });
+});
+describe("suggestAction — 401/403/404", () => {
+    it("401 → AUTH_FAILED", () => {
+        expect(suggestAction("any", 401, "anything")).toMatch(/^AUTH_FAILED:/);
+    });
+    it("403 with 'permission' → PERMISSION_DENIED", () => {
+        expect(suggestAction("any", 403, "You lack the required permission")).toMatch(/^PERMISSION_DENIED:/);
+    });
+    it("403 with 'not approved' → APP_NOT_APPROVED", () => {
+        expect(suggestAction("any", 403, "This feature is not approved for your app")).toMatch(/^APP_NOT_APPROVED:/);
+    });
+    it("403 with 'business' → BUSINESS_ACCOUNT_REQUIRED", () => {
+        expect(suggestAction("any", 403, "A business account is required")).toMatch(/^BUSINESS_ACCOUNT_REQUIRED:/);
+    });
+    it("403 unmatched → FORBIDDEN", () => {
+        expect(suggestAction("any", 403, "generic denial")).toMatch(/^FORBIDDEN:/);
+    });
+    it("404 comment tool → COMMENT_NOT_FOUND", () => {
+        expect(suggestAction("ig_delete_comment", 404, "not found")).toMatch(/^COMMENT_NOT_FOUND:/);
+    });
+    it("404 insight tool → MEDIA_NOT_FOUND", () => {
+        expect(suggestAction("ig_get_post_insights", 404, "not found")).toMatch(/^MEDIA_NOT_FOUND:/);
+    });
+    it("404 story tool → STORY_NOT_FOUND", () => {
+        // Tool name must include 'story' AND NOT 'insight' / 'post' / 'comment'
+        // (those are checked first). ig_story_publish is a hypothetical example.
+        expect(suggestAction("ig_story_fetch", 404, "not found")).toMatch(/^STORY_NOT_FOUND:/);
+    });
+    // Real-world: ig_get_stories_insights contains both 'story' and 'insight',
+    // and 'insight' is checked first → MEDIA_NOT_FOUND (documented quirk).
+    it("404 ig_get_stories_insights → MEDIA_NOT_FOUND (insight wins)", () => {
+        expect(suggestAction("ig_get_stories_insights", 404, "not found")).toMatch(/^MEDIA_NOT_FOUND:/);
+    });
+    it("404 generic tool → NOT_FOUND", () => {
+        expect(suggestAction("ig_misc_tool", 404, "not found")).toMatch(/^NOT_FOUND:/);
+    });
+});
+describe("suggestAction — 429 and 5xx", () => {
+    it("429 → RATE_LIMITED", () => {
+        expect(suggestAction("any", 429, "rate limited")).toMatch(/^RATE_LIMITED:/);
+    });
+    it("500 → SERVER_ERROR", () => {
+        expect(suggestAction("any", 500, "internal server error")).toMatch(/^SERVER_ERROR:/);
+    });
+    it("502 → SERVER_ERROR", () => {
+        expect(suggestAction("any", 502, "bad gateway")).toMatch(/^SERVER_ERROR:/);
+    });
+    it("503 → SERVER_ERROR", () => {
+        expect(suggestAction("any", 503, "service unavailable")).toMatch(/^SERVER_ERROR:/);
+    });
+    it("unknown status → undefined", () => {
+        expect(suggestAction("any", 418, "I'm a teapot")).toBeUndefined();
+    });
+});

package/dist/first-comment.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Regression tests for the #1995 first-comment partial-success contract (#1931).
+ *
+ * The whole point of first-comment publishing is "no lying success": if the
+ * media publishes but the follow-up comment fails, the handler must surface a
+ * partial failure — never a clean success. postFirstComment is the isolated
+ * step the three publish handlers (photo/carousel/reel) all delegate to, so a
+ * test here guards every IG publish path against the silent-swallow regression.
+ */
+export {};