@agentforge-io/connectors-meta 0.1.0

package/dist/page.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Page-token + WhatsApp business helpers.
+ *
+ * Meta's OAuth flow gives the connector a USER access token. For every
+ * surface except `metaWhatsAppConnector`, the actual API calls use a
+ * PAGE access token (or an IG-business-account token derived from one)
+ * because user tokens can't read Page-owned conversations, posts, or
+ * Instagram business inboxes.
+ *
+ * Why this matters for the connector:
+ *   - The OAuth callback persists a user token in `af_connector_auths`.
+ *   - Before the tools can run, we exchange that user token for a list
+ *     of page tokens (`GET /me/accounts`) and the operator picks one in
+ *     the connect modal.
+ *   - We persist the picked page id + token alongside the user token so
+ *     subsequent API calls can grab it from `ctx.metadata.pageId` /
+ *     `ctx.getAccessToken()` without a roundtrip every turn.
+ *
+ * Why one helper instead of one per surface:
+ *   - The `/me/accounts` payload is the same for Instagram, Messenger,
+ *     and FB Pages — every Page object includes its `instagram_business_account`
+ *     edge when the IG account is linked. So one fetch covers all three.
+ *   - Three of the four connectors share the same Page-selector UX in
+ *     the dashboard (analogous to Shopify's shop selector); only
+ *     WhatsApp has its own selector (phone number id, not Page id).
+ *
+ * Long-lived tokens:
+ *   - The user token returned by the OAuth callback is short-lived
+ *     (~1h). Before calling `/me/accounts` we MUST upgrade it via
+ *     `GET /oauth/access_token?grant_type=fb_exchange_token` — the
+ *     long-lived form lasts ~60 days.
+ *   - Page tokens derived from a long-lived user token are themselves
+ *     **non-expiring** (as long as the user keeps a valid session with
+ *     Facebook). That's the property we want — no refresh dance ever.
+ */
+export declare class MetaPageSelectionError extends Error {
+    readonly raw: string;
+    constructor(raw: string, message: string);
+}
+/**
+ * Exchange a short-lived user access token for a long-lived one.
+ * Meta returns short-lived tokens (~1h) from the OAuth callback even
+ * when we asked for `offline` access — you MUST call this helper before
+ * deriving page tokens, or the page tokens inherit the short TTL.
+ *
+ * Endpoint:
+ *   GET /oauth/access_token?grant_type=fb_exchange_token
+ *       &client_id=...&client_secret=...&fb_exchange_token=<short-lived>
+ *
+ * Returns `{ access_token, token_type, expires_in }`. The
+ * `expires_in` is in seconds; for production we treat any value above
+ * 30 days as "long-lived enough" and don't pre-emptively refresh.
+ */
+export interface LongLivedUserTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+}
+export declare function exchangeForLongLivedUserToken(opts: {
+    shortLivedUserToken: string;
+    clientId: string;
+    clientSecret: string;
+}): Promise<LongLivedUserTokenResponse>;
+/**
+ * One row from `GET /me/accounts`. Includes the page access token and,
+ * when the IG account is linked, the IG business account id used by the
+ * Instagram tools.
+ */
+export interface MetaManagedPage {
+    id: string;
+    name: string;
+    access_token: string;
+    /** Page roles the calling user has on this Page. We don't filter on
+     *  this — tools that need a specific role surface a 403 with a clear
+     *  message at runtime. */
+    tasks?: string[];
+    category?: string;
+    category_list?: Array<{
+        id: string;
+        name: string;
+    }>;
+    /** Present when the Page has an Instagram Business Account linked.
+     *  This is the id the Instagram Graph API expects, NOT the @-handle. */
+    instagram_business_account?: {
+        id: string;
+        username?: string;
+    };
+}
+export interface ListManagedPagesResponse {
+    data: MetaManagedPage[];
+    paging?: {
+        cursors?: {
+            before?: string;
+            after?: string;
+        };
+        next?: string;
+    };
+}
+/**
+ * Fetch the Pages the operator manages, each with its own page access
+ * token. Used at connect-time to populate the page-selector modal.
+ *
+ * We request a wide-ish field set in one shot to avoid an N+1 (the
+ * naive flow without `fields=` only returns id + name, then each Page
+ * needs a follow-up for the access_token).
+ *
+ * The token argument should be a LONG-LIVED user token; passing a
+ * short-lived one technically works but the derived page tokens inherit
+ * the short TTL.
+ */
+export declare function listManagedPages(longLivedUserToken: string): Promise<MetaManagedPage[]>;
+/**
+ * Fetch a specific managed Page by id. Used by the page selector after
+ * the operator clicks one to confirm the choice, and at tool-run time
+ * if we ever need to re-resolve fresh metadata (e.g. the operator
+ * unlinked the IG account between OAuth and first tool call).
+ */
+export declare function getManagedPage(longLivedUserToken: string, pageId: string): Promise<MetaManagedPage | null>;
+/**
+ * One WhatsApp Business Account (WABA) the operator can pick. Each WABA
+ * owns one or more phone numbers; tools target a phone number id
+ * (`/{phone-number-id}/messages`), not the WABA id directly.
+ */
+export interface MetaWhatsAppPhoneNumber {
+    id: string;
+    display_phone_number: string;
+    verified_name?: string;
+    quality_rating?: 'GREEN' | 'YELLOW' | 'RED';
+}
+export interface MetaWhatsAppBusinessAccount {
+    id: string;
+    name?: string;
+    phone_numbers: MetaWhatsAppPhoneNumber[];
+}
+/**
+ * Fetch the WABAs the operator's Business Manager owns, each with the
+ * phone numbers attached. Used by the WhatsApp connector's
+ * phone-number selector.
+ *
+ * Requires `whatsapp_business_management` scope. The endpoint is
+ * `/me/businesses/{business-id}/owned_whatsapp_business_accounts` —
+ * but to avoid a Business-Manager listing roundtrip we use the
+ * `/me?fields=businesses{owned_whatsapp_business_accounts{...}}` shape.
+ */
+export interface ListWabasResponse {
+    data: Array<{
+        id: string;
+        businesses?: {
+            data: Array<{
+                id: string;
+                owned_whatsapp_business_accounts?: {
+                    data: Array<{
+                        id: string;
+                        name?: string;
+                        phone_numbers?: {
+                            data: MetaWhatsAppPhoneNumber[];
+                        };
+                    }>;
+                };
+            }>;
+        };
+    }>;
+}
+export declare function listWhatsAppBusinessAccounts(longLivedUserToken: string): Promise<MetaWhatsAppBusinessAccount[]>;

package/dist/page.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Page-token + WhatsApp business helpers.
+ *
+ * Meta's OAuth flow gives the connector a USER access token. For every
+ * surface except `metaWhatsAppConnector`, the actual API calls use a
+ * PAGE access token (or an IG-business-account token derived from one)
+ * because user tokens can't read Page-owned conversations, posts, or
+ * Instagram business inboxes.
+ *
+ * Why this matters for the connector:
+ *   - The OAuth callback persists a user token in `af_connector_auths`.
+ *   - Before the tools can run, we exchange that user token for a list
+ *     of page tokens (`GET /me/accounts`) and the operator picks one in
+ *     the connect modal.
+ *   - We persist the picked page id + token alongside the user token so
+ *     subsequent API calls can grab it from `ctx.metadata.pageId` /
+ *     `ctx.getAccessToken()` without a roundtrip every turn.
+ *
+ * Why one helper instead of one per surface:
+ *   - The `/me/accounts` payload is the same for Instagram, Messenger,
+ *     and FB Pages — every Page object includes its `instagram_business_account`
+ *     edge when the IG account is linked. So one fetch covers all three.
+ *   - Three of the four connectors share the same Page-selector UX in
+ *     the dashboard (analogous to Shopify's shop selector); only
+ *     WhatsApp has its own selector (phone number id, not Page id).
+ *
+ * Long-lived tokens:
+ *   - The user token returned by the OAuth callback is short-lived
+ *     (~1h). Before calling `/me/accounts` we MUST upgrade it via
+ *     `GET /oauth/access_token?grant_type=fb_exchange_token` — the
+ *     long-lived form lasts ~60 days.
+ *   - Page tokens derived from a long-lived user token are themselves
+ *     **non-expiring** (as long as the user keeps a valid session with
+ *     Facebook). That's the property we want — no refresh dance ever.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetaPageSelectionError = void 0;
+exports.exchangeForLongLivedUserToken = exchangeForLongLivedUserToken;
+exports.listManagedPages = listManagedPages;
+exports.getManagedPage = getManagedPage;
+exports.listWhatsAppBusinessAccounts = listWhatsAppBusinessAccounts;
+const http_1 = require("./http");
+class MetaPageSelectionError extends Error {
+    constructor(raw, message) {
+        super(message);
+        this.raw = raw;
+        this.name = 'MetaPageSelectionError';
+    }
+}
+exports.MetaPageSelectionError = MetaPageSelectionError;
+async function exchangeForLongLivedUserToken(opts) {
+    // This endpoint is OAuth-flavored and lives at the same /oauth/...
+    // base — but uses query-string params and no Authorization header,
+    // so we bypass the standard `metaGet` (which always sends Bearer).
+    const url = new URL(`https://graph.facebook.com/${http_1.META_GRAPH_VERSION}/oauth/access_token`);
+    url.searchParams.set('grant_type', 'fb_exchange_token');
+    url.searchParams.set('client_id', opts.clientId);
+    url.searchParams.set('client_secret', opts.clientSecret);
+    url.searchParams.set('fb_exchange_token', opts.shortLivedUserToken);
+    const res = await fetch(url.toString(), { method: 'GET' });
+    if (!res.ok) {
+        throw new http_1.MetaApiError(res.status, res.statusText, await res.text().catch(() => ''));
+    }
+    return (await res.json());
+}
+/**
+ * Fetch the Pages the operator manages, each with its own page access
+ * token. Used at connect-time to populate the page-selector modal.
+ *
+ * We request a wide-ish field set in one shot to avoid an N+1 (the
+ * naive flow without `fields=` only returns id + name, then each Page
+ * needs a follow-up for the access_token).
+ *
+ * The token argument should be a LONG-LIVED user token; passing a
+ * short-lived one technically works but the derived page tokens inherit
+ * the short TTL.
+ */
+async function listManagedPages(longLivedUserToken) {
+    const res = await (0, http_1.metaGet)({
+        accessToken: longLivedUserToken,
+        path: '/me/accounts',
+        query: {
+            fields: 'id,name,access_token,tasks,category,category_list,instagram_business_account{id,username}',
+            limit: 100,
+        },
+    });
+    return res.data ?? [];
+}
+/**
+ * Fetch a specific managed Page by id. Used by the page selector after
+ * the operator clicks one to confirm the choice, and at tool-run time
+ * if we ever need to re-resolve fresh metadata (e.g. the operator
+ * unlinked the IG account between OAuth and first tool call).
+ */
+async function getManagedPage(longLivedUserToken, pageId) {
+    try {
+        return await (0, http_1.metaGet)({
+            accessToken: longLivedUserToken,
+            path: `/${encodeURIComponent(pageId)}`,
+            query: {
+                fields: 'id,name,access_token,tasks,category,category_list,instagram_business_account{id,username}',
+            },
+        });
+    }
+    catch (err) {
+        // 404 / 100-invalid-parameter → the Page no longer exists or the
+        // user lost admin access. Treat as "not found" rather than rethrow
+        // so the selector UX can show a clean message.
+        if (err instanceof http_1.MetaApiError &&
+            (err.status === 404 || err.metaCode === 100)) {
+            return null;
+        }
+        throw err;
+    }
+}
+async function listWhatsAppBusinessAccounts(longLivedUserToken) {
+    // `me` returns a single user object, but we ask for the nested
+    // edges in one query so we don't pay an N+1 over Business Manager
+    // → WABA → phone numbers.
+    const res = await (0, http_1.metaGet)({
+        accessToken: longLivedUserToken,
+        path: '/me',
+        query: {
+            fields: 'businesses{id,owned_whatsapp_business_accounts{id,name,phone_numbers{id,display_phone_number,verified_name,quality_rating}}}',
+        },
+    });
+    const wabas = [];
+    for (const business of res.businesses?.data ?? []) {
+        for (const waba of business.owned_whatsapp_business_accounts?.data ?? []) {
+            wabas.push({
+                id: waba.id,
+                name: waba.name,
+                phone_numbers: waba.phone_numbers?.data ?? [],
+            });
+        }
+    }
+    return wabas;
+}

package/dist/tools/_shared.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared helpers every Meta tool needs:
+ *
+ *   - `resolvePageId(ctx)` — pulls the Page id the operator picked at
+ *     connect-time out of `ctx.metadata.pageId`. Every Page-bound
+ *     surface (IG / Messenger / FB Pages) needs it.
+ *
+ *   - `resolveIgUserId(ctx)` — pulls the Instagram Business Account id
+ *     (NOT the @-handle) out of `ctx.metadata.igUserId`. Only Instagram
+ *     tools call this; Messenger + FB Pages don't.
+ *
+ *   - `resolveWaPhoneId(ctx)` — pulls the WhatsApp phone-number id out
+ *     of `ctx.metadata.waPhoneNumberId`. WhatsApp tools route by phone
+ *     number, not by WABA — that's an easy thing to get wrong.
+ *
+ * Failure mode: every helper throws a descriptive error if the
+ * metadata is missing, pointing the operator at the fix ("reconnect
+ * the connector from the Directory"). The platform's tool runner
+ * surfaces that string back to the agent's turn, which surfaces it to
+ * the operator.
+ */
+import type { ConnectorToolContext } from '@agentforge-io/core';
+export declare function resolvePageId(ctx: ConnectorToolContext): string;
+export declare function resolveIgUserId(ctx: ConnectorToolContext): string;
+export declare function resolveWaPhoneId(ctx: ConnectorToolContext): string;

package/dist/tools/_shared.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePageId = resolvePageId;
+exports.resolveIgUserId = resolveIgUserId;
+exports.resolveWaPhoneId = resolveWaPhoneId;
+const RECONNECT_HINT = 'This usually means the user connected before the per-Page selection ' +
+    'was wired. Ask them to disconnect and reconnect the Meta surface ' +
+    'from the Directory.';
+function resolvePageId(ctx) {
+    const pageId = ctx.metadata?.pageId;
+    if (typeof pageId !== 'string' || !pageId) {
+        throw new Error(`Meta connector is missing its pageId metadata. ${RECONNECT_HINT}`);
+    }
+    return pageId;
+}
+function resolveIgUserId(ctx) {
+    const igUserId = ctx.metadata?.igUserId;
+    if (typeof igUserId !== 'string' || !igUserId) {
+        throw new Error('Instagram connector is missing its igUserId metadata. The selected ' +
+            'Page may not have an Instagram Business Account linked. Ask the ' +
+            'operator to link an IG Business account to the Page and reconnect.');
+    }
+    return igUserId;
+}
+function resolveWaPhoneId(ctx) {
+    const phoneId = ctx.metadata?.waPhoneNumberId;
+    if (typeof phoneId !== 'string' || !phoneId) {
+        throw new Error(`WhatsApp connector is missing its phone-number id metadata. ${RECONNECT_HINT}`);
+    }
+    return phoneId;
+}

package/dist/tools/facebook-pages.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Facebook Pages tools.
+ *
+ * Five tools for managing a Page's published content + engagement:
+ *
+ *   1. fb_list_posts      — Page's own posts, newest first
+ *   2. fb_get_post        — single post with engagement breakdown
+ *   3. fb_create_post     — publish or schedule a text/link post
+ *   4. fb_list_comments   — comments on a post
+ *   5. fb_reply_comment   — reply nested under a comment
+ *
+ * Token model:
+ *   - `ctx.getAccessToken()` returns the PAGE access token.
+ *   - `ctx.metadata.pageId` is the Page id — every endpoint here
+ *     routes through it.
+ *
+ * Why `/posts` (Page-authored) and not `/feed` (everything):
+ *   - `/{page-id}/feed` returns posts the Page made PLUS posts by
+ *     other people on the Page wall. Agents usually want "what did
+ *     WE publish?" so `/posts` is the right default; if we ever need
+ *     the wall, a future `fb_list_feed` can take the same shape.
+ *
+ * Scheduled posts:
+ *   - Setting `published: false` + `scheduled_publish_time` (unix
+ *     seconds) defers publication. Window: 10 minutes to 6 months
+ *     from now (Meta hard limit; sending outside returns code 100).
+ *
+ * Media:
+ *   - This step covers text + link posts only. Photo/video uploads
+ *     require a separate /photos or /videos endpoint with multipart
+ *     bodies, which deserves its own tool (`fb_create_photo_post`)
+ *     and isn't part of the MVP. Posting an external image via the
+ *     `link` field is supported — Meta scrapes the URL for OG tags
+ *     and renders the link preview.
+ */
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+export declare const fbListPostsTool: ConnectorToolFactory;
+export declare const fbGetPostTool: ConnectorToolFactory;
+export declare const fbCreatePostTool: ConnectorToolFactory;
+export declare const fbListCommentsTool: ConnectorToolFactory;
+export declare const fbReplyCommentTool: ConnectorToolFactory;