@cashtokenai/meta-mcp-server 1.0.0

package/dist/tools/instagram/get-media-insights.js

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import { metaIdSchema } from "../../helpers/schema.js";
+import { runGetViaInsightsApp } from "../shared.js";
+export const inputSchema = z
+    .object({
+    media_id: metaIdSchema.describe("IG media ID."),
+    metrics: z
+        .array(z.string())
+        .default([
+        // v23-safe set covering Reels (the most common modern IG media type
+        // for marketing accounts). 'impressions' is deprecated for IG media
+        // in v22+; 'views' replaces it. See the description for media-type
+        // / metric compatibility.
+        "reach",
+        "views",
+        "likes",
+        "comments",
+        "shares",
+        "saved",
+        "total_interactions",
+    ])
+        .describe("IG media metrics. Defaults are v23-safe for Reels. For IMAGE/CAROUSEL_ALBUM you can drop 'views' and add 'profile_visits'. For STORY use ['views','reach','replies','navigation']. See the tool description for the full media-type/metric compatibility matrix."),
+})
+    .strict();
+export const definition = {
+    name: "meta_ig_get_media_insights",
+    title: "Get Instagram media insights",
+    description: `Per-media metrics: reach, views, saves, likes, comments, shares, total_interactions, profile_visits, follows.
+
+**Requirements (in order of frequency-of-failure):**
+1. Token has 'instagram_manage_insights' scope.
+2. **The configured app must be approved for Standard Access on \`instagram_manage_insights\` via Meta App Review.** In development tier, Meta returns \`(#10) Application does not have permission for this action\` for the IG insights endpoints — even if the scope is on the token. This applies to media insights AND audience demographics. Track the App Review request and surface this to the operator; this tool is functioning correctly when it returns that error.
+3. The IG account must be Business or Creator (not personal).
+
+**Metric / media-type compatibility (post v22 deprecations):**
+- IMAGE / CAROUSEL_ALBUM: reach, saved, likes, comments, shares, total_interactions, profile_visits
+- VIDEO / REELS: views, reach, likes, comments, shares, saved, total_interactions  ('impressions' is deprecated, use 'views')
+- STORY: views, reach, replies, navigation, profile_visits, follows  (impressions is deprecated; use views)
+
+If you see code (#100) "metric not supported for media type", narrow the metrics list to the matching subset above. If you see code (#10), it's almost always App Review (#2 above).`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    return runGetViaInsightsApp(ctx, {
+        path: `${input.media_id}/insights`,
+        params: { metric: input.metrics.join(",") },
+    });
+}

package/dist/tools/instagram/list-accounts.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    limit: number;
+    auto_paginate: boolean;
+    after?: string | undefined;
+}, {
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ig_list_accounts";
+    readonly title: "List Instagram Business accounts reachable via Pages";
+    readonly description: "Walks the Pages visible to the token (/me/assigned_pages) and, for each, resolves the linked Instagram Business account via 'instagram_business_account'. This is the modern discovery path — the /owned_instagram_accounts business edge is unreliable.\n\nRequires 'instagram_basic' scope on the token and 'Analyze Instagram account' task on each IG.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/instagram/list-accounts.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolError, toolResult } from "../../helpers/format.js";
+import { paginationShape } from "../../helpers/schema.js";
+export const inputSchema = z
+    .object({
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_ig_list_accounts",
+    title: "List Instagram Business accounts reachable via Pages",
+    description: `Walks the Pages visible to the token (/me/assigned_pages) and, for each, resolves the linked Instagram Business account via 'instagram_business_account'. This is the modern discovery path — the /owned_instagram_accounts business edge is unreliable.
+
+Requires 'instagram_basic' scope on the token and 'Analyze Instagram account' task on each IG.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    try {
+        // First, list the pages assigned to the token.
+        const pagesPage = await ctx.graph.get({
+            path: "me/assigned_pages",
+            params: { fields: "id,name", limit: input.limit, after: input.after },
+        });
+        const pages = Array.isArray(pagesPage.data) ? pagesPage.data : [];
+        // Resolve IG in parallel.
+        const results = await Promise.all(pages.map(async (p) => {
+            try {
+                const d = await ctx.graph.get({
+                    path: p.id,
+                    params: { fields: "id,name,instagram_business_account{id,username,name}" },
+                });
+                return {
+                    page_id: p.id,
+                    page_name: p.name,
+                    instagram_business_account: d.instagram_business_account ?? null,
+                };
+            }
+            catch (err) {
+                const e = err instanceof MetaError ? err : new MetaError(err.message);
+                return { page_id: p.id, page_name: p.name, error: e.message, hint: e.hint };
+            }
+        }));
+        const linked = results.filter((r) => "instagram_business_account" in r && r.instagram_business_account);
+        const structured = {
+            pages_scanned: pages.length,
+            ig_accounts_found: linked.length,
+            links: results,
+            next_after: pagesPage.paging?.cursors?.after,
+        };
+        return toolResult(structured, jsonBlock(structured));
+    }
+    catch (err) {
+        const e = err instanceof MetaError ? err : new MetaError(err.message);
+        return toolError(e.message, e.hint, {
+            code: e.code,
+            subcode: e.subcode,
+            fbtrace_id: e.fbtraceId,
+            http_status: e.httpStatus,
+        });
+    }
+}

package/dist/tools/instagram/list-media.d.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodNumber>;
+    after: z.ZodOptional<z.ZodString>;
+    auto_paginate: z.ZodDefault<z.ZodBoolean>;
+    ig_user_id: z.ZodString;
+    fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    fields: string[];
+    ig_user_id: string;
+    limit: number;
+    auto_paginate: boolean;
+    after?: string | undefined;
+}, {
+    ig_user_id: string;
+    fields?: string[] | undefined;
+    limit?: number | undefined;
+    after?: string | undefined;
+    auto_paginate?: boolean | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_ig_list_media";
+    readonly title: "List Instagram media (posts, reels, stories)";
+    readonly description: "Lists media posted by an IG Business account. Includes caption, permalink, timestamp, like/comment counts. For per-media metrics (reach, impressions, saves, plays), pass each ID to meta_ig_get_media_insights.";
+    readonly inputSchema: {
+        limit: z.ZodDefault<z.ZodNumber>;
+        after: z.ZodOptional<z.ZodString>;
+        auto_paginate: z.ZodDefault<z.ZodBoolean>;
+        ig_user_id: z.ZodString;
+        fields: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/instagram/list-media.js

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { metaIdSchema, paginationShape } from "../../helpers/schema.js";
+import { runList } from "../shared.js";
+export const inputSchema = z
+    .object({
+    ig_user_id: metaIdSchema,
+    fields: z
+        .array(z.string())
+        .default([
+        "id",
+        "media_type",
+        "media_product_type",
+        "caption",
+        "media_url",
+        "thumbnail_url",
+        "permalink",
+        "timestamp",
+        "like_count",
+        "comments_count",
+        "is_comment_enabled",
+        "shortcode",
+        "owner",
+    ])
+        .describe("Media fields. For Reels add 'ig_id'; for carousels add 'children{...}'."),
+    ...paginationShape,
+})
+    .strict();
+export const definition = {
+    name: "meta_ig_list_media",
+    title: "List Instagram media (posts, reels, stories)",
+    description: `Lists media posted by an IG Business account. Includes caption, permalink, timestamp, like/comment counts. For per-media metrics (reach, impressions, saves, plays), pass each ID to meta_ig_get_media_insights.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+export async function handler(input, ctx) {
+    assertAllowed("ig_user", input.ig_user_id, ctx.config);
+    return runList(ctx, {
+        path: `${input.ig_user_id}/media`,
+        params: { fields: input.fields.join(","), limit: input.limit, after: input.after },
+    }, { auto_paginate: input.auto_paginate, after: input.after, limit: input.limit }, { ig_user_id: input.ig_user_id });
+}

package/dist/tools/meta/graph-read.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    path: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+    api_version: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    params?: Record<string, string | number | boolean> | undefined;
+    api_version?: string | undefined;
+}, {
+    path: string;
+    params?: Record<string, string | number | boolean> | undefined;
+    api_version?: string | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_graph_read";
+    readonly title: "Arbitrary read-only Graph API call";
+    readonly description: "Escape-hatch for arbitrary GET requests against the Meta Graph API.\n\nThis tool exists so the assistant can reach fields and endpoints that do not yet have a dedicated tool wrapper — without ever sending a write. The underlying HTTP client is hard-wired to GET only; POST/PUT/DELETE are refused before the request leaves the process.\n\nRules:\n- Do NOT include 'access_token' or 'appsecret_proof' in params — they are added automatically.\n- Do NOT prefix the path with the API version.\n- Prefer dedicated tools (meta_business_list_assets, meta_ads_get_insights, …) when they exist. Use this as a last resort.";
+    readonly inputSchema: {
+        path: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
+        api_version: z.ZodOptional<z.ZodString>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/meta/graph-read.js

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolError, toolResult } from "../../helpers/format.js";
+const paramsRecord = z
+    .record(z.union([z.string(), z.number(), z.boolean()]))
+    .optional()
+    .describe("Query parameters. `access_token` and `appsecret_proof` are added automatically and must not be supplied here.");
+export const inputSchema = z
+    .object({
+    path: z
+        .string()
+        .min(1)
+        .describe("Graph API path after the version segment. Examples: 'me/businesses', 'act_1234567890/insights', '100000012345/posts'. Do NOT include a leading 'v23.0/' — the configured API version is added automatically."),
+    params: paramsRecord,
+    api_version: z
+        .string()
+        .regex(/^v\d+\.\d+$/)
+        .optional()
+        .describe("Override the Graph API version for this call, e.g. 'v20.0'. Defaults to the configured version."),
+})
+    .strict();
+const FORBIDDEN_PARAMS = new Set(["access_token", "appsecret_proof"]);
+export const definition = {
+    name: "meta_graph_read",
+    title: "Arbitrary read-only Graph API call",
+    description: `Escape-hatch for arbitrary GET requests against the Meta Graph API.
+
+This tool exists so the assistant can reach fields and endpoints that do not yet have a dedicated tool wrapper — without ever sending a write. The underlying HTTP client is hard-wired to GET only; POST/PUT/DELETE are refused before the request leaves the process.
+
+Rules:
+- Do NOT include 'access_token' or 'appsecret_proof' in params — they are added automatically.
+- Do NOT prefix the path with the API version.
+- Prefer dedicated tools (meta_business_list_assets, meta_ads_get_insights, …) when they exist. Use this as a last resort.`,
+    inputSchema: inputSchema.shape,
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+};
+export async function handler(input, ctx) {
+    for (const k of Object.keys(input.params ?? {})) {
+        if (FORBIDDEN_PARAMS.has(k)) {
+            return toolError(`Parameter '${k}' must not be supplied — the server adds it automatically.`, "Remove it from the params object and retry.");
+        }
+    }
+    try {
+        const data = await ctx.graph.get({
+            path: input.path,
+            params: input.params,
+            apiVersion: input.api_version,
+        });
+        const structured = {
+            path: input.path,
+            api_version: input.api_version ?? ctx.config.apiVersion,
+            data,
+        };
+        return toolResult(structured, jsonBlock(data));
+    }
+    catch (err) {
+        const e = err instanceof MetaError ? err : new MetaError(err.message);
+        return toolError(e.message, e.hint, {
+            code: e.code,
+            subcode: e.subcode,
+            fbtrace_id: e.fbtraceId,
+            http_status: e.httpStatus,
+            path: input.path,
+        });
+    }
+}

package/dist/tools/overview/business-overview.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import type { ToolContext } from "../../context.js";
+export declare const inputSchema: z.ZodObject<{
+    business_id: z.ZodOptional<z.ZodString>;
+    date_preset: z.ZodDefault<z.ZodEnum<["today", "yesterday", "this_month", "last_month", "this_quarter", "maximum", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "last_week_mon_sun", "last_week_sun_sat", "last_quarter", "last_year", "this_week_mon_today", "this_week_sun_today", "this_year"]>>;
+    include_pixels: z.ZodDefault<z.ZodBoolean>;
+    include_catalogs: z.ZodDefault<z.ZodBoolean>;
+    include_whatsapp: z.ZodDefault<z.ZodBoolean>;
+    max_ad_accounts: z.ZodDefault<z.ZodNumber>;
+    max_pages: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    date_preset: "today" | "yesterday" | "this_month" | "last_month" | "this_quarter" | "maximum" | "last_3d" | "last_7d" | "last_14d" | "last_28d" | "last_30d" | "last_90d" | "last_week_mon_sun" | "last_week_sun_sat" | "last_quarter" | "last_year" | "this_week_mon_today" | "this_week_sun_today" | "this_year";
+    include_pixels: boolean;
+    include_catalogs: boolean;
+    include_whatsapp: boolean;
+    max_ad_accounts: number;
+    max_pages: number;
+    business_id?: string | undefined;
+}, {
+    business_id?: string | undefined;
+    date_preset?: "today" | "yesterday" | "this_month" | "last_month" | "this_quarter" | "maximum" | "last_3d" | "last_7d" | "last_14d" | "last_28d" | "last_30d" | "last_90d" | "last_week_mon_sun" | "last_week_sun_sat" | "last_quarter" | "last_year" | "this_week_mon_today" | "this_week_sun_today" | "this_year" | undefined;
+    include_pixels?: boolean | undefined;
+    include_catalogs?: boolean | undefined;
+    include_whatsapp?: boolean | undefined;
+    max_ad_accounts?: number | undefined;
+    max_pages?: number | undefined;
+}>;
+export type Input = z.infer<typeof inputSchema>;
+export declare const definition: {
+    readonly name: "meta_business_overview";
+    readonly title: "Eagle's-eye snapshot of a business";
+    readonly description: "One-call consolidated read across the whole Meta surface for a business:\n\n- Identity (system user + token app)\n- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window\n- Instagram Business accounts linked to those Pages (followers, media_count)\n- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)\n- Pixels with last_fired_time (if include_pixels)\n- Catalogs with product counts (if include_catalogs)\n- WhatsApp Business Accounts + phone numbers (if include_whatsapp)\n\nEach section has its own error isolation — one failing asset does not kill the report. Ideal as the opening call for any AI-driven marketing insights conversation.";
+    readonly inputSchema: {
+        business_id: z.ZodOptional<z.ZodString>;
+        date_preset: z.ZodDefault<z.ZodEnum<["today", "yesterday", "this_month", "last_month", "this_quarter", "maximum", "last_3d", "last_7d", "last_14d", "last_28d", "last_30d", "last_90d", "last_week_mon_sun", "last_week_sun_sat", "last_quarter", "last_year", "this_week_mon_today", "this_week_sun_today", "this_year"]>>;
+        include_pixels: z.ZodDefault<z.ZodBoolean>;
+        include_catalogs: z.ZodDefault<z.ZodBoolean>;
+        include_whatsapp: z.ZodDefault<z.ZodBoolean>;
+        max_ad_accounts: z.ZodDefault<z.ZodNumber>;
+        max_pages: z.ZodDefault<z.ZodNumber>;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly destructiveHint: false;
+        readonly idempotentHint: true;
+        readonly openWorldHint: true;
+    };
+};
+export declare function handler(input: Input, ctx: ToolContext): Promise<import("../../helpers/format.js").ToolTextResult>;

package/dist/tools/overview/business-overview.js

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import { assertAllowed } from "../../config.js";
+import { MetaError } from "../../errors.js";
+import { jsonBlock, toolResult } from "../../helpers/format.js";
+import { datePresetSchema, metaIdSchema } from "../../helpers/schema.js";
+export const inputSchema = z
+    .object({
+    business_id: metaIdSchema
+        .optional()
+        .describe("Business Manager ID. **Optional** — if omitted, the server auto-discovers via `META_ALLOWED_BUSINESS_IDS[0]` (if configured) or the first business returned by `/me/businesses`. Always prefer omitting this if you don't have the exact ID — do not guess a placeholder integer."),
+    date_preset: datePresetSchema
+        .default("last_30d")
+        .describe("Date window used for ad account and page insights snapshots."),
+    include_pixels: z.boolean().default(true),
+    include_catalogs: z.boolean().default(true),
+    include_whatsapp: z.boolean().default(true),
+    max_ad_accounts: z.number().int().min(1).max(50).default(10).describe("Cap on number of ad accounts to fetch insights for. Each is one extra Graph call — tune for rate limits."),
+    max_pages: z.number().int().min(1).max(50).default(10).describe("Cap on number of Pages to fetch insights for."),
+})
+    .strict();
+export const definition = {
+    name: "meta_business_overview",
+    title: "Eagle's-eye snapshot of a business",
+    description: `One-call consolidated read across the whole Meta surface for a business:
+
+- Identity (system user + token app)
+- Assigned Pages + each Page's high-level insights (impressions, engagement, fans) for the requested window
+- Instagram Business accounts linked to those Pages (followers, media_count)
+- Owned + client ad accounts with balance, spend cap, amount spent, and last-window insights (spend, impressions, clicks, CTR, CPC, reach)
+- Pixels with last_fired_time (if include_pixels)
+- Catalogs with product counts (if include_catalogs)
+- WhatsApp Business Accounts + phone numbers (if include_whatsapp)
+
+Each section has its own error isolation — one failing asset does not kill the report. Ideal as the opening call for any AI-driven marketing insights conversation.`,
+    inputSchema: inputSchema.shape,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+};
+function ok(data) {
+    return { ok: true, data };
+}
+function fail(err) {
+    const e = err instanceof MetaError ? err : new MetaError(err.message);
+    return { ok: false, error: e.message, hint: e.hint };
+}
+export async function handler(input, ctx) {
+    const started = Date.now();
+    // Auto-discover business_id if not provided. Prefer the configured allowlist
+    // (deployment intent), fall back to /me/businesses. This makes the tool
+    // safe to call with no args — defeats AI-hallucinated-id failure modes.
+    let businessId = input.business_id;
+    let businessIdSource = "input";
+    if (!businessId) {
+        const allowed = ctx.config.allowedBusinessIds;
+        if (allowed && allowed.size > 0) {
+            businessId = allowed.values().next().value;
+            businessIdSource = "allowlist";
+        }
+        else {
+            try {
+                const list = await ctx.graph.get({
+                    path: "me/businesses",
+                    params: { fields: "id,name", limit: 1 },
+                });
+                const first = list.data?.[0];
+                if (first?.id) {
+                    businessId = first.id;
+                    businessIdSource = "discovered";
+                }
+            }
+            catch {
+                /* fall through — businessId remains undefined and structured response will surface the gap */
+            }
+        }
+    }
+    if (!businessId) {
+        return toolResult({
+            error: "no_business_id",
+            hint: "Could not determine business_id. Configure META_ALLOWED_BUSINESS_IDS in the server's environment, or pass business_id explicitly. /me/businesses returned no results for the configured token (this is normal for system-user tokens — they don't list businesses via that edge).",
+            suggestion: "Pass business_id directly. To discover it, an operator should run `meta_business_list_assets business_id=<known>` once with a known ID, or look up the business in Business Settings → Business Info.",
+        }, "{}");
+    }
+    assertAllowed("business", businessId, ctx.config);
+    const token = ctx.graph.get({
+        path: "debug_token",
+        params: { input_token: ctx.config.accessToken },
+        noCache: true,
+    }).then((r) => ok(r.data)).catch(fail);
+    const identity = ctx.graph.get({ path: "me", params: { fields: "id,name" } })
+        .then(ok)
+        .catch(fail);
+    const pages = ctx.graph
+        .get({
+        path: "me/assigned_pages",
+        params: { fields: "id,name,category,fan_count,followers_count", limit: input.max_pages },
+    })
+        .then(ok)
+        .catch(fail);
+    const ownedAds = ctx.graph
+        .get({
+        path: `${businessId}/owned_ad_accounts`,
+        params: { fields: "id,account_id,name,currency,account_status,amount_spent,balance,spend_cap", limit: input.max_ad_accounts },
+    })
+        .then(ok)
+        .catch(fail);
+    const clientAds = ctx.graph
+        .get({
+        path: `${businessId}/client_ad_accounts`,
+        params: { fields: "id,account_id,name,currency,account_status", limit: input.max_ad_accounts },
+    })
+        .then(ok)
+        .catch(fail);
+    const pixels = input.include_pixels
+        ? ctx.graph
+            .get({
+            path: `${businessId}/owned_pixels`,
+            params: { fields: "id,name,last_fired_time,is_unavailable", limit: 25 },
+        })
+            .then(ok)
+            .catch(fail)
+        : Promise.resolve(ok({ skipped: true }));
+    const catalogs = input.include_catalogs
+        ? ctx.graph
+            .get({
+            path: `${businessId}/owned_product_catalogs`,
+            params: { fields: "id,name,vertical,product_count", limit: 25 },
+        })
+            .then(ok)
+            .catch(fail)
+        : Promise.resolve(ok({ skipped: true }));
+    const wabas = input.include_whatsapp
+        ? ctx.graph
+            .get({
+            path: `${businessId}/owned_whatsapp_business_accounts`,
+            params: { fields: "id,name,currency,status,business_verification_status", limit: 25 },
+        })
+            .then(ok)
+            .catch(fail)
+        : Promise.resolve(ok({ skipped: true }));
+    const [identityR, tokenR, pagesR, ownedAdsR, clientAdsR, pixelsR, catalogsR, wabasR] = await Promise.all([
+        identity,
+        token,
+        pages,
+        ownedAds,
+        clientAds,
+        pixels,
+        catalogs,
+        wabas,
+    ]);
+    // Expand each page with linked IG + a small insights fetch.
+    // Page insights require the per-Page access token, so resolve it lazily.
+    const pagesExpanded = pagesR.ok && pagesR.data.data
+        ? await Promise.all(pagesR.data.data.map(async (p) => {
+            const igR = await ctx.graph
+                .get({
+                path: p.id,
+                params: { fields: "instagram_business_account{id,username,name,followers_count,media_count}" },
+            })
+                .then(ok)
+                .catch(fail);
+            // Resolve Page access token for the insights call. If we can't,
+            // record a per-page error rather than blanking the whole report.
+            let insightsR;
+            try {
+                const pageToken = await ctx.graph.getPageAccessToken(p.id);
+                insightsR = await ctx.graph
+                    .get({
+                    path: `${p.id}/insights`,
+                    params: {
+                        // Narrow v23-safe metric set; requires 'read_insights' scope.
+                        metric: "page_impressions,page_post_engagements,page_fans,page_views_total",
+                        date_preset: input.date_preset,
+                    },
+                    accessTokenOverride: pageToken,
+                })
+                    .then((d) => ok({ data: d.data }))
+                    .catch(fail);
+            }
+            catch (err) {
+                insightsR = fail(err);
+            }
+            return {
+                id: p.id,
+                name: p.name,
+                category: p.category,
+                fan_count: p.fan_count,
+                followers_count: p.followers_count,
+                instagram: igR.ok ? igR.data.instagram_business_account ?? null : { error: igR.error, hint: igR.hint },
+                insights_last_window: insightsR.ok ? insightsR.data.data ?? [] : { error: insightsR.error, hint: insightsR.hint },
+            };
+        }))
+        : [];
+    // Same treatment for ad accounts.
+    const adAccountsData = [
+        ...((ownedAdsR.ok && ownedAdsR.data.data) ? ownedAdsR.data.data.map((a) => ({ ...a, scope: "owned" })) : []),
+        ...((clientAdsR.ok && clientAdsR.data.data) ? clientAdsR.data.data.map((a) => ({ ...a, scope: "client" })) : []),
+    ].slice(0, input.max_ad_accounts);
+    const adAccountsExpanded = await Promise.all(adAccountsData.map(async (a) => {
+        const insightsR = await ctx.graph
+            .get({
+            path: `${a.id}/insights`,
+            params: {
+                level: "account",
+                fields: "spend,impressions,reach,frequency,clicks,ctr,cpc,cpm,actions",
+                date_preset: input.date_preset,
+            },
+        })
+            .then(ok)
+            .catch(fail);
+        return {
+            id: a.id,
+            account_id: a.account_id,
+            name: a.name,
+            scope: a.scope,
+            currency: a.currency,
+            account_status: a.account_status,
+            insights_last_window: insightsR.ok ? insightsR.data.data?.[0] ?? null : { error: insightsR.error, hint: insightsR.hint },
+        };
+    }));
+    const structured = {
+        business_id: businessId,
+        business_id_source: businessIdSource,
+        date_preset: input.date_preset,
+        generated_at: new Date().toISOString(),
+        latency_ms: Date.now() - started,
+        identity: identityR,
+        token: tokenR,
+        pages: pagesExpanded,
+        ad_accounts: adAccountsExpanded,
+        pixels: pixelsR,
+        catalogs: catalogsR,
+        whatsapp: wabasR,
+        rate_limit_after: ctx.graph.rateLimit,
+    };
+    return toolResult(structured, jsonBlock(structured));
+}