@agentforge-io/connectors-meta 0.1.0

package/dist/connector.d.ts

@@ -0,0 +1,80 @@
+import type { ConnectorDefinition } from '@agentforge-io/core';
+/**
+ * Shared options for every Meta surface connector.
+ *
+ * The operator configures ONE Meta App (a single appId/appSecret pair)
+ * and that pair is reused by Instagram, Messenger, Facebook Pages, and
+ * WhatsApp Cloud. This matches Meta's own model where one app declares
+ * the union of products + scopes and individual consent flows request
+ * a subset.
+ *
+ * Why one app, four connectors (vs. one combo "Meta" connector):
+ *   - Each surface needs different scopes. Showing the operator a
+ *     consent screen with `instagram_manage_messages` + `pages_messaging`
+ *     + `pages_manage_posts` + `whatsapp_business_messaging` all at once
+ *     makes Meta's review process much harder to pass — Meta wants the
+ *     scope list to match the declared use case.
+ *   - Per-surface `af_connector_auths` rows mean the operator can
+ *     reconnect Instagram (e.g. after losing the IG password) without
+ *     re-doing FB Pages + WhatsApp.
+ */
+export interface MetaConnectorOptions {
+    /** Meta App ID (developer dashboard → Settings → Basic). */
+    clientId: string;
+    /** Meta App Secret. Treat as opaque — never log it. */
+    clientSecret: string;
+    /** Optional override of the default scope set for THIS surface. */
+    scopes?: string[];
+    /** Optional override of the logo asset URL shown in the Directory. */
+    iconUrl?: string;
+}
+/**
+ * Instagram connector — DMs, media list, comments.
+ *
+ * Connector id: `meta-instagram`.
+ *
+ * Token model: OAuth gives us a user token; the platform exchanges it
+ * for a long-lived user token, then derives a Page access token via
+ * `/me/accounts`. Instagram API calls use the IG Business Account id
+ * (`page.instagram_business_account.id`) with that page token.
+ *
+ * Tools land in Step 3 — this definition ships with an empty `tools[]`
+ * so the connector compiles and registers as a Directory card while we
+ * build the tools out.
+ */
+export declare function metaInstagramConnector(opts: MetaConnectorOptions): ConnectorDefinition;
+/**
+ * Messenger connector — Page-bound Messenger DMs.
+ *
+ * Connector id: `meta-messenger`.
+ *
+ * Same token model as Instagram (user → long-lived → page token).
+ * Tools land in Step 4.
+ */
+export declare function metaMessengerConnector(opts: MetaConnectorOptions): ConnectorDefinition;
+/**
+ * Facebook Pages connector — posts + comments on a Page.
+ *
+ * Connector id: `meta-facebook-pages`.
+ *
+ * Page token is required for every call (user tokens can't publish to
+ * a Page even when the user is admin). Tools land in Step 5.
+ */
+export declare function metaFacebookPagesConnector(opts: MetaConnectorOptions): ConnectorDefinition;
+/**
+ * WhatsApp Cloud connector — outbound messaging only.
+ *
+ * Connector id: `meta-whatsapp`.
+ *
+ * NOTE on scope vs. agentforge-platform's `WhatsAppModule`:
+ *   The platform already ships a WhatsApp gateway receiver (inbound
+ *   webhooks at `/webhooks/inbox/...`). This connector deliberately does
+ *   NOT duplicate that — it only adds OUTBOUND send tools so an agent
+ *   can initiate conversations through the Cloud API. The inbound
+ *   webhook continues to flow through WhatsAppModule.
+ *
+ * Token model: OAuth gives a user token; we exchange for long-lived,
+ * then list WABAs + phone numbers via `/me/businesses{...}`. Tools
+ * target a phone-number id, not the WABA id. Tools land in Step 6.
+ */
+export declare function metaWhatsAppConnector(opts: MetaConnectorOptions): ConnectorDefinition;

package/dist/connector.js

@@ -0,0 +1,263 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.metaInstagramConnector = metaInstagramConnector;
+exports.metaMessengerConnector = metaMessengerConnector;
+exports.metaFacebookPagesConnector = metaFacebookPagesConnector;
+exports.metaWhatsAppConnector = metaWhatsAppConnector;
+const instagram_1 = require("./tools/instagram");
+const messenger_1 = require("./tools/messenger");
+const facebook_pages_1 = require("./tools/facebook-pages");
+const whatsapp_1 = require("./tools/whatsapp");
+// ── Per-surface scope sets ──────────────────────────────────────────────
+//
+// Three scopes show up on every connector because Meta requires them
+// to identify the user/business behind the token:
+//   - `public_profile` — always granted, no consent prompt
+//   - `pages_show_list` — required to call `/me/accounts` (page-token
+//     exchange happens at connect-time for every Page-bound surface)
+//   - `business_management` — required to call `/me/businesses` for
+//     WhatsApp's WABA + phone-number selector; harmless for the others.
+//
+// Each surface then adds its own product scopes on top. Operators who
+// want a stricter set can pass `scopes` explicitly.
+const IDENTITY_SCOPES = ['public_profile', 'pages_show_list'];
+/** Instagram — DMs (`instagram_manage_messages`), media list
+ *  (`instagram_basic`), comments (`instagram_manage_comments`). Only
+ *  works for IG Business / Creator accounts linked to a FB Page —
+ *  personal IG accounts can't be read via the Graph API. */
+const INSTAGRAM_SCOPES = [
+    ...IDENTITY_SCOPES,
+    'instagram_basic',
+    'instagram_manage_messages',
+    'instagram_manage_comments',
+];
+/** Messenger Page DMs. `pages_messaging` is the send/receive scope;
+ *  `pages_read_engagement` is needed to read the existing thread list
+ *  (counter-intuitively, `pages_messaging` alone doesn't unlock thread
+ *  listing). `pages_manage_metadata` is needed to mark threads as seen. */
+const MESSENGER_SCOPES = [
+    ...IDENTITY_SCOPES,
+    'pages_messaging',
+    'pages_read_engagement',
+    'pages_manage_metadata',
+];
+/** Facebook Page posts + comments. `pages_manage_posts` is publish;
+ *  `pages_read_engagement` reads posts/comments; `pages_manage_engagement`
+ *  is required to reply to comments (read-engagement alone won't let
+ *  you POST). */
+const FACEBOOK_PAGE_SCOPES = [
+    ...IDENTITY_SCOPES,
+    'pages_manage_posts',
+    'pages_read_engagement',
+    'pages_manage_engagement',
+];
+/** WhatsApp Cloud outbound. `whatsapp_business_messaging` is the send
+ *  scope; `whatsapp_business_management` is needed for the WABA +
+ *  phone-number selector at connect-time. `business_management` lets
+ *  us walk `/me/businesses` to enumerate WABAs. */
+const WHATSAPP_SCOPES = [
+    ...IDENTITY_SCOPES,
+    'whatsapp_business_messaging',
+    'whatsapp_business_management',
+    'business_management',
+];
+// Meta uses standard OAuth 2.0 with PKCE supported but optional. We
+// enable it because (a) Meta recommends it for native/SPA flows and
+// (b) the rest of the AgentForge OAuth connectors (Google, Slack,
+// Notion, GitHub) all run PKCE, so disabling it here would be the
+// odd-one-out that surprises operators auditing logs.
+//
+// `auth_type=rerequest` forces a consent screen on every authorize so
+// scope changes get a fresh grant — without it, Meta silently issues
+// the OLD scope set when an operator reconnects after we widened the
+// surface, which then surfaces as runtime 200-permission errors.
+const AUTHORIZE_EXTRAS = {
+    auth_type: 'rerequest',
+    // `display=popup` keeps the consent inside the connect modal instead
+    // of a full-window redirect, matching how the operator already
+    // experiences Google + Slack from the same surface.
+    display: 'popup',
+};
+/**
+ * Internal helper. Every surface connector shares the same OAuth URL
+ * pair, PKCE flag, and authorize_extras — only `id`, `name`, scopes,
+ * and the tool list differ.
+ *
+ * The authorize/token URLs are Meta's standard v21.0 endpoints; bumping
+ * the version is a single edit to `META_GRAPH_VERSION` in `http.ts`
+ * (the OAuth dialog accepts any supported version on the path; we don't
+ * version-pin these URLs because Meta keeps the latest stable working
+ * indefinitely).
+ */
+function buildMetaSurfaceDef(args) {
+    return {
+        id: args.id,
+        name: args.name,
+        description: args.description,
+        category: 'Messaging',
+        iconUrl: args.opts.iconUrl,
+        oauth: {
+            authorizeUrl: 'https://www.facebook.com/v21.0/dialog/oauth',
+            tokenUrl: 'https://graph.facebook.com/v21.0/oauth/access_token',
+            clientId: args.opts.clientId,
+            clientSecret: args.opts.clientSecret,
+            scopes: args.opts.scopes ?? args.defaultScopes,
+            authorizeExtras: AUTHORIZE_EXTRAS,
+            usePkce: true,
+        },
+        tools: args.tools,
+        defaultToolPermissions: args.defaultToolPermissions,
+    };
+}
+// ── Public surface connectors ───────────────────────────────────────────
+/**
+ * Instagram connector — DMs, media list, comments.
+ *
+ * Connector id: `meta-instagram`.
+ *
+ * Token model: OAuth gives us a user token; the platform exchanges it
+ * for a long-lived user token, then derives a Page access token via
+ * `/me/accounts`. Instagram API calls use the IG Business Account id
+ * (`page.instagram_business_account.id`) with that page token.
+ *
+ * Tools land in Step 3 — this definition ships with an empty `tools[]`
+ * so the connector compiles and registers as a Directory card while we
+ * build the tools out.
+ */
+function metaInstagramConnector(opts) {
+    return buildMetaSurfaceDef({
+        id: 'meta-instagram',
+        name: 'Instagram',
+        description: 'Read and respond to Instagram DMs, list media, and reply to ' +
+            'post comments. Requires an Instagram Business or Creator ' +
+            'account linked to a Facebook Page.',
+        defaultScopes: INSTAGRAM_SCOPES,
+        tools: [
+            instagram_1.igListThreadsTool,
+            instagram_1.igListMessagesTool,
+            instagram_1.igSendMessageTool,
+            instagram_1.igListMediaTool,
+            instagram_1.igListCommentsTool,
+            instagram_1.igReplyCommentTool,
+        ],
+        defaultToolPermissions: [
+            // Reads are safe — default to allow so the agent can browse the
+            // inbox + posts without an approval round-trip.
+            { name: 'ig_list_threads', mode: 'allow' },
+            { name: 'ig_list_messages', mode: 'allow' },
+            { name: 'ig_list_media', mode: 'allow' },
+            { name: 'ig_list_comments', mode: 'allow' },
+            // Writes go through approval. A wrong DM or a wrong public reply
+            // is high-reputation cost for the brand; the operator gates
+            // them per turn until they explicitly trust the agent.
+            { name: 'ig_send_message', mode: 'approval' },
+            { name: 'ig_reply_comment', mode: 'approval' },
+        ],
+        opts,
+    });
+}
+/**
+ * Messenger connector — Page-bound Messenger DMs.
+ *
+ * Connector id: `meta-messenger`.
+ *
+ * Same token model as Instagram (user → long-lived → page token).
+ * Tools land in Step 4.
+ */
+function metaMessengerConnector(opts) {
+    return buildMetaSurfaceDef({
+        id: 'meta-messenger',
+        name: 'Messenger',
+        description: 'Read and respond to Messenger conversations on a Facebook Page. ' +
+            'Personal Messenger inboxes are not accessible — only Page-owned ' +
+            'threads.',
+        defaultScopes: MESSENGER_SCOPES,
+        tools: [
+            messenger_1.messengerListThreadsTool,
+            messenger_1.messengerListMessagesTool,
+            messenger_1.messengerSendMessageTool,
+            messenger_1.messengerMarkSeenTool,
+        ],
+        defaultToolPermissions: [
+            // Reads + mark_seen default to allow. mark_seen is a presence
+            // signal, not user-facing content — same risk profile as a read.
+            { name: 'messenger_list_threads', mode: 'allow' },
+            { name: 'messenger_list_messages', mode: 'allow' },
+            { name: 'messenger_mark_seen', mode: 'allow' },
+            // send_message goes through approval — same reasoning as IG.
+            { name: 'messenger_send_message', mode: 'approval' },
+        ],
+        opts,
+    });
+}
+/**
+ * Facebook Pages connector — posts + comments on a Page.
+ *
+ * Connector id: `meta-facebook-pages`.
+ *
+ * Page token is required for every call (user tokens can't publish to
+ * a Page even when the user is admin). Tools land in Step 5.
+ */
+function metaFacebookPagesConnector(opts) {
+    return buildMetaSurfaceDef({
+        id: 'meta-facebook-pages',
+        name: 'Facebook Pages',
+        description: 'Publish, list, and engage with posts on a Facebook Page: ' +
+            'create posts, read engagement, and reply to comments.',
+        defaultScopes: FACEBOOK_PAGE_SCOPES,
+        tools: [
+            facebook_pages_1.fbListPostsTool,
+            facebook_pages_1.fbGetPostTool,
+            facebook_pages_1.fbCreatePostTool,
+            facebook_pages_1.fbListCommentsTool,
+            facebook_pages_1.fbReplyCommentTool,
+        ],
+        defaultToolPermissions: [
+            // Reads default to allow.
+            { name: 'fb_list_posts', mode: 'allow' },
+            { name: 'fb_get_post', mode: 'allow' },
+            { name: 'fb_list_comments', mode: 'allow' },
+            // Writes to the public timeline + public comments are
+            // high-blast-radius — gate them per turn until trusted.
+            { name: 'fb_create_post', mode: 'approval' },
+            { name: 'fb_reply_comment', mode: 'approval' },
+        ],
+        opts,
+    });
+}
+/**
+ * WhatsApp Cloud connector — outbound messaging only.
+ *
+ * Connector id: `meta-whatsapp`.
+ *
+ * NOTE on scope vs. agentforge-platform's `WhatsAppModule`:
+ *   The platform already ships a WhatsApp gateway receiver (inbound
+ *   webhooks at `/webhooks/inbox/...`). This connector deliberately does
+ *   NOT duplicate that — it only adds OUTBOUND send tools so an agent
+ *   can initiate conversations through the Cloud API. The inbound
+ *   webhook continues to flow through WhatsAppModule.
+ *
+ * Token model: OAuth gives a user token; we exchange for long-lived,
+ * then list WABAs + phone numbers via `/me/businesses{...}`. Tools
+ * target a phone-number id, not the WABA id. Tools land in Step 6.
+ */
+function metaWhatsAppConnector(opts) {
+    return buildMetaSurfaceDef({
+        id: 'meta-whatsapp',
+        name: 'WhatsApp Cloud',
+        description: 'Send outbound WhatsApp messages (free-form within the 24h ' +
+            'service window, or pre-approved templates outside it) from a ' +
+            'WhatsApp Business phone number. Inbound is handled by the ' +
+            'platform WhatsApp gateway.',
+        defaultScopes: WHATSAPP_SCOPES,
+        tools: [whatsapp_1.waSendTextTool, whatsapp_1.waSendTemplateTool],
+        defaultToolPermissions: [
+            // Both tools are writes that hit a customer's WhatsApp inbox —
+            // higher blast radius than IG/Messenger because users tend to
+            // treat WA as their personal phone. Both gate through approval.
+            { name: 'wa_send_text', mode: 'approval' },
+            { name: 'wa_send_template', mode: 'approval' },
+        ],
+        opts,
+    });
+}

package/dist/http.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Thin HTTP layer for the Meta Graph API. All four connectors in this
+ * package (Instagram, Messenger, Facebook Pages, WhatsApp) talk to
+ * `graph.facebook.com/v{version}` with the same auth + retry policy,
+ * so the transport lives here.
+ *
+ * Endpoints are **fixed** — unlike Shopify's per-shop hostnames, every
+ * Meta surface uses the same base URL and routes via the path
+ * (`/{ig-user-id}/conversations`, `/{page-id}/feed`, etc.). That's why
+ * we don't expose `resolveEndpoints` in the connector definitions.
+ *
+ * Auth: `Authorization: Bearer <accessToken>`. Meta also accepts
+ * `?access_token=` as a query param, but the header form keeps tokens
+ * out of access logs and matches what the official SDKs send.
+ *
+ * Rate limits (the painful ones to remember):
+ *   - App-level: 200 calls/hr/user, tracked in `X-App-Usage` header.
+ *   - Business use case: separate buckets for Messaging, Pages,
+ *     Instagram, each in `X-Business-Use-Case-Usage` / `X-Ad-Account-Usage`.
+ *   - When ≥95% of any bucket: 4xx with code 4 / 17 / 32 / 613.
+ *   - Hard throttle: HTTP 429 (rare; usually they 4xx with the codes
+ *     above first).
+ *
+ * Retry policy:
+ *   - 429: up to 2 retries, honoring `Retry-After` (seconds).
+ *   - 5xx: 1 retry with ~500ms jitter.
+ *   - 4xx with rate-limit code (4, 17, 32, 613): same backoff as 429
+ *     because Meta's "you're at 95%" responses come back as 4xx.
+ *   - 401/403: NEVER retried — the token is invalid/expired/missing
+ *     scope. Caller should surface a "Reconnect Meta" UX.
+ */
+export declare const META_GRAPH_VERSION = "v21.0";
+export declare const META_GRAPH_BASE = "https://graph.facebook.com";
+export declare class MetaApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly body: string;
+    /** Meta error code from the response body. The most useful
+     *  routable values:
+     *    - 4: app-level rate limit (back off)
+     *    - 17: user-level rate limit
+     *    - 32, 613: page/business use-case rate limit
+     *    - 190: access token expired/invalid → re-auth
+     *    - 200: missing permission → re-auth with broader scopes
+     *    - 100: invalid parameter (bug in the tool input) */
+    readonly metaCode?: number | undefined;
+    /** Sub-error type for permission/scope failures. */
+    readonly metaSubcode?: number | undefined;
+    constructor(status: number, statusText: string, body: string, 
+    /** Meta error code from the response body. The most useful
+     *  routable values:
+     *    - 4: app-level rate limit (back off)
+     *    - 17: user-level rate limit
+     *    - 32, 613: page/business use-case rate limit
+     *    - 190: access token expired/invalid → re-auth
+     *    - 200: missing permission → re-auth with broader scopes
+     *    - 100: invalid parameter (bug in the tool input) */
+    metaCode?: number | undefined, 
+    /** Sub-error type for permission/scope failures. */
+    metaSubcode?: number | undefined);
+}
+export interface MetaRequestOptions {
+    accessToken: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    apiVersion?: string;
+}
+export interface MetaMutateOptions extends MetaRequestOptions {
+    body: unknown;
+}
+export declare function metaGet<T>(opts: MetaRequestOptions): Promise<T>;
+export declare function metaPost<T>(opts: MetaMutateOptions): Promise<T>;
+export declare function metaDelete<T>(opts: MetaRequestOptions): Promise<T>;
+/**
+ * Standard Meta paging envelope. Every list endpoint wraps results in
+ * `{ data: [...], paging: { cursors, next } }`. Tools should propagate
+ * the cursor back to the agent so it can fetch the next page.
+ */
+export interface MetaPaging<T> {
+    data: T[];
+    paging?: {
+        cursors?: {
+            before?: string;
+            after?: string;
+        };
+        next?: string;
+        previous?: string;
+    };
+}

package/dist/http.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Thin HTTP layer for the Meta Graph API. All four connectors in this
+ * package (Instagram, Messenger, Facebook Pages, WhatsApp) talk to
+ * `graph.facebook.com/v{version}` with the same auth + retry policy,
+ * so the transport lives here.
+ *
+ * Endpoints are **fixed** — unlike Shopify's per-shop hostnames, every
+ * Meta surface uses the same base URL and routes via the path
+ * (`/{ig-user-id}/conversations`, `/{page-id}/feed`, etc.). That's why
+ * we don't expose `resolveEndpoints` in the connector definitions.
+ *
+ * Auth: `Authorization: Bearer <accessToken>`. Meta also accepts
+ * `?access_token=` as a query param, but the header form keeps tokens
+ * out of access logs and matches what the official SDKs send.
+ *
+ * Rate limits (the painful ones to remember):
+ *   - App-level: 200 calls/hr/user, tracked in `X-App-Usage` header.
+ *   - Business use case: separate buckets for Messaging, Pages,
+ *     Instagram, each in `X-Business-Use-Case-Usage` / `X-Ad-Account-Usage`.
+ *   - When ≥95% of any bucket: 4xx with code 4 / 17 / 32 / 613.
+ *   - Hard throttle: HTTP 429 (rare; usually they 4xx with the codes
+ *     above first).
+ *
+ * Retry policy:
+ *   - 429: up to 2 retries, honoring `Retry-After` (seconds).
+ *   - 5xx: 1 retry with ~500ms jitter.
+ *   - 4xx with rate-limit code (4, 17, 32, 613): same backoff as 429
+ *     because Meta's "you're at 95%" responses come back as 4xx.
+ *   - 401/403: NEVER retried — the token is invalid/expired/missing
+ *     scope. Caller should surface a "Reconnect Meta" UX.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetaApiError = exports.META_GRAPH_BASE = exports.META_GRAPH_VERSION = void 0;
+exports.metaGet = metaGet;
+exports.metaPost = metaPost;
+exports.metaDelete = metaDelete;
+exports.META_GRAPH_VERSION = 'v21.0';
+exports.META_GRAPH_BASE = 'https://graph.facebook.com';
+class MetaApiError extends Error {
+    constructor(status, statusText, body, 
+    /** Meta error code from the response body. The most useful
+     *  routable values:
+     *    - 4: app-level rate limit (back off)
+     *    - 17: user-level rate limit
+     *    - 32, 613: page/business use-case rate limit
+     *    - 190: access token expired/invalid → re-auth
+     *    - 200: missing permission → re-auth with broader scopes
+     *    - 100: invalid parameter (bug in the tool input) */
+    metaCode, 
+    /** Sub-error type for permission/scope failures. */
+    metaSubcode) {
+        super(`Meta API ${status} ${statusText}${metaCode !== undefined ? ` (code=${metaCode}${metaSubcode !== undefined ? `/sub=${metaSubcode}` : ''})` : ''}: ${body.slice(0, 500)}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+        this.metaCode = metaCode;
+        this.metaSubcode = metaSubcode;
+    }
+}
+exports.MetaApiError = MetaApiError;
+const MAX_429_RETRIES = 2;
+const MAX_5XX_RETRIES = 1;
+/** Meta error codes that mean "back off and retry" — surfaced as 4xx
+ *  with a normal JSON body rather than 429. */
+const RATE_LIMIT_CODES = new Set([4, 17, 32, 613]);
+async function send(opts) {
+    const version = opts.apiVersion ?? exports.META_GRAPH_VERSION;
+    const url = new URL(`${exports.META_GRAPH_BASE}/${version}${opts.path.startsWith('/') ? opts.path : `/${opts.path}`}`);
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v === undefined || v === null)
+            continue;
+        url.searchParams.set(k, String(v));
+    }
+    const headers = {
+        authorization: `Bearer ${opts.accessToken}`,
+        accept: 'application/json',
+    };
+    let body;
+    if (opts.body !== undefined && opts.method !== 'GET') {
+        headers['content-type'] = 'application/json';
+        body = JSON.stringify(opts.body);
+    }
+    let attempt429 = 0;
+    let attempt5xx = 0;
+    while (true) {
+        const res = await fetch(url.toString(), {
+            method: opts.method,
+            headers,
+            body,
+        });
+        // HTTP 429 — honor Retry-After.
+        if (res.status === 429 && attempt429 < MAX_429_RETRIES) {
+            const retryAfter = Number(res.headers.get('retry-after') ?? '2');
+            const delayMs = (Number.isFinite(retryAfter) ? retryAfter : 2) * 1000;
+            await sleep(delayMs);
+            attempt429++;
+            continue;
+        }
+        // 4xx with a rate-limit code in the body. We need to peek at the
+        // body to know — peek non-destructively via clone() so the caller's
+        // error path still has access to the original Response.
+        if (res.status >= 400 && res.status < 500 && attempt429 < MAX_429_RETRIES) {
+            const peeked = await res.clone().text().catch(() => '');
+            const code = parseMetaCode(peeked);
+            if (code !== undefined && RATE_LIMIT_CODES.has(code)) {
+                await sleep(2000);
+                attempt429++;
+                continue;
+            }
+        }
+        if (res.status >= 500 && res.status < 600 && attempt5xx < MAX_5XX_RETRIES) {
+            await sleep(400 + Math.floor(Math.random() * 200));
+            attempt5xx++;
+            continue;
+        }
+        return res;
+    }
+}
+function parseMetaCode(body) {
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.error?.code;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+async function unwrap(res) {
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        let metaCode;
+        let metaSubcode;
+        try {
+            const parsed = JSON.parse(body);
+            metaCode = parsed.error?.code;
+            metaSubcode = parsed.error?.error_subcode;
+        }
+        catch {
+            /* not JSON — body stays as-is for the error message */
+        }
+        throw new MetaApiError(res.status, res.statusText, body, metaCode, metaSubcode);
+    }
+    return (await res.json());
+}
+async function metaGet(opts) {
+    return unwrap(await send({ ...opts, method: 'GET' }));
+}
+async function metaPost(opts) {
+    return unwrap(await send({ ...opts, method: 'POST' }));
+}
+async function metaDelete(opts) {
+    return unwrap(await send({ ...opts, method: 'DELETE' }));
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { metaInstagramConnector, metaMessengerConnector, metaFacebookPagesConnector, metaWhatsAppConnector, type MetaConnectorOptions, } from './connector';
+export { exchangeForLongLivedUserToken, listManagedPages, getManagedPage, listWhatsAppBusinessAccounts, MetaPageSelectionError, } from './page';
+export { igListThreadsTool, igListMessagesTool, igSendMessageTool, igListMediaTool, igListCommentsTool, igReplyCommentTool, } from './tools/instagram';
+export { messengerListThreadsTool, messengerListMessagesTool, messengerSendMessageTool, messengerMarkSeenTool, } from './tools/messenger';
+export { fbListPostsTool, fbGetPostTool, fbCreatePostTool, fbListCommentsTool, fbReplyCommentTool, } from './tools/facebook-pages';
+export { waSendTextTool, waSendTemplateTool, } from './tools/whatsapp';
+export type { LongLivedUserTokenResponse, MetaManagedPage, ListManagedPagesResponse, MetaWhatsAppPhoneNumber, MetaWhatsAppBusinessAccount, } from './page';
+export { metaGet, metaPost, metaDelete, MetaApiError, META_GRAPH_VERSION, META_GRAPH_BASE, } from './http';
+export type { MetaRequestOptions, MetaMutateOptions, MetaPaging, } from './http';

package/dist/index.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.META_GRAPH_BASE = exports.META_GRAPH_VERSION = exports.MetaApiError = exports.metaDelete = exports.metaPost = exports.metaGet = exports.waSendTemplateTool = exports.waSendTextTool = exports.fbReplyCommentTool = exports.fbListCommentsTool = exports.fbCreatePostTool = exports.fbGetPostTool = exports.fbListPostsTool = exports.messengerMarkSeenTool = exports.messengerSendMessageTool = exports.messengerListMessagesTool = exports.messengerListThreadsTool = exports.igReplyCommentTool = exports.igListCommentsTool = exports.igListMediaTool = exports.igSendMessageTool = exports.igListMessagesTool = exports.igListThreadsTool = exports.MetaPageSelectionError = exports.listWhatsAppBusinessAccounts = exports.getManagedPage = exports.listManagedPages = exports.exchangeForLongLivedUserToken = exports.metaWhatsAppConnector = exports.metaFacebookPagesConnector = exports.metaMessengerConnector = exports.metaInstagramConnector = void 0;
+var connector_1 = require("./connector");
+Object.defineProperty(exports, "metaInstagramConnector", { enumerable: true, get: function () { return connector_1.metaInstagramConnector; } });
+Object.defineProperty(exports, "metaMessengerConnector", { enumerable: true, get: function () { return connector_1.metaMessengerConnector; } });
+Object.defineProperty(exports, "metaFacebookPagesConnector", { enumerable: true, get: function () { return connector_1.metaFacebookPagesConnector; } });
+Object.defineProperty(exports, "metaWhatsAppConnector", { enumerable: true, get: function () { return connector_1.metaWhatsAppConnector; } });
+var page_1 = require("./page");
+Object.defineProperty(exports, "exchangeForLongLivedUserToken", { enumerable: true, get: function () { return page_1.exchangeForLongLivedUserToken; } });
+Object.defineProperty(exports, "listManagedPages", { enumerable: true, get: function () { return page_1.listManagedPages; } });
+Object.defineProperty(exports, "getManagedPage", { enumerable: true, get: function () { return page_1.getManagedPage; } });
+Object.defineProperty(exports, "listWhatsAppBusinessAccounts", { enumerable: true, get: function () { return page_1.listWhatsAppBusinessAccounts; } });
+Object.defineProperty(exports, "MetaPageSelectionError", { enumerable: true, get: function () { return page_1.MetaPageSelectionError; } });
+var instagram_1 = require("./tools/instagram");
+Object.defineProperty(exports, "igListThreadsTool", { enumerable: true, get: function () { return instagram_1.igListThreadsTool; } });
+Object.defineProperty(exports, "igListMessagesTool", { enumerable: true, get: function () { return instagram_1.igListMessagesTool; } });
+Object.defineProperty(exports, "igSendMessageTool", { enumerable: true, get: function () { return instagram_1.igSendMessageTool; } });
+Object.defineProperty(exports, "igListMediaTool", { enumerable: true, get: function () { return instagram_1.igListMediaTool; } });
+Object.defineProperty(exports, "igListCommentsTool", { enumerable: true, get: function () { return instagram_1.igListCommentsTool; } });
+Object.defineProperty(exports, "igReplyCommentTool", { enumerable: true, get: function () { return instagram_1.igReplyCommentTool; } });
+var messenger_1 = require("./tools/messenger");
+Object.defineProperty(exports, "messengerListThreadsTool", { enumerable: true, get: function () { return messenger_1.messengerListThreadsTool; } });
+Object.defineProperty(exports, "messengerListMessagesTool", { enumerable: true, get: function () { return messenger_1.messengerListMessagesTool; } });
+Object.defineProperty(exports, "messengerSendMessageTool", { enumerable: true, get: function () { return messenger_1.messengerSendMessageTool; } });
+Object.defineProperty(exports, "messengerMarkSeenTool", { enumerable: true, get: function () { return messenger_1.messengerMarkSeenTool; } });
+var facebook_pages_1 = require("./tools/facebook-pages");
+Object.defineProperty(exports, "fbListPostsTool", { enumerable: true, get: function () { return facebook_pages_1.fbListPostsTool; } });
+Object.defineProperty(exports, "fbGetPostTool", { enumerable: true, get: function () { return facebook_pages_1.fbGetPostTool; } });
+Object.defineProperty(exports, "fbCreatePostTool", { enumerable: true, get: function () { return facebook_pages_1.fbCreatePostTool; } });
+Object.defineProperty(exports, "fbListCommentsTool", { enumerable: true, get: function () { return facebook_pages_1.fbListCommentsTool; } });
+Object.defineProperty(exports, "fbReplyCommentTool", { enumerable: true, get: function () { return facebook_pages_1.fbReplyCommentTool; } });
+var whatsapp_1 = require("./tools/whatsapp");
+Object.defineProperty(exports, "waSendTextTool", { enumerable: true, get: function () { return whatsapp_1.waSendTextTool; } });
+Object.defineProperty(exports, "waSendTemplateTool", { enumerable: true, get: function () { return whatsapp_1.waSendTemplateTool; } });
+// Public API of @agentforge-io/connectors-meta.
+//
+// Meta ships as four independent connectors — one per product surface.
+// They share a single Meta App OAuth client (same clientId/clientSecret
+// across all four) but each one only requests the scopes its tools
+// need, lives in its own `af_connector_auths` row, and shows up as a
+// separate card in the Directory.
+//
+//   import {
+//     metaInstagramConnector,
+//     metaMessengerConnector,
+//     metaFacebookPagesConnector,
+//     metaWhatsAppConnector,
+//   } from '@agentforge-io/connectors-meta';
+//
+//   const creds = { clientId: env.META_APP_ID, clientSecret: env.META_APP_SECRET };
+//   registry.register(metaInstagramConnector(creds));
+//   registry.register(metaMessengerConnector(creds));
+//   registry.register(metaFacebookPagesConnector(creds));
+//   registry.register(metaWhatsAppConnector(creds));
+//
+// The four connectors are coming online incrementally:
+//   Step 1 (DONE)     — package skeleton + shared HTTP layer
+//   Step 2 (pending)  — page-token exchange + connector definitions
+//   Step 3 (pending)  — Instagram tools (DMs + media + comments)
+//   Step 4 (pending)  — Messenger tools
+//   Step 5 (pending)  — Facebook Pages tools (posts + comments)
+//   Step 6 (pending)  — WhatsApp Cloud outbound tools
+//   Step 7 (pending)  — Platform wiring (secrets binding + UI)
+var http_1 = require("./http");
+Object.defineProperty(exports, "metaGet", { enumerable: true, get: function () { return http_1.metaGet; } });
+Object.defineProperty(exports, "metaPost", { enumerable: true, get: function () { return http_1.metaPost; } });
+Object.defineProperty(exports, "metaDelete", { enumerable: true, get: function () { return http_1.metaDelete; } });
+Object.defineProperty(exports, "MetaApiError", { enumerable: true, get: function () { return http_1.MetaApiError; } });
+Object.defineProperty(exports, "META_GRAPH_VERSION", { enumerable: true, get: function () { return http_1.META_GRAPH_VERSION; } });
+Object.defineProperty(exports, "META_GRAPH_BASE", { enumerable: true, get: function () { return http_1.META_GRAPH_BASE; } });