@agentforge-io/connectors-meta 0.1.0 → 0.1.2

package/dist/connector.js

@@ -21,15 +21,26 @@ const whatsapp_1 = require("./tools/whatsapp");
 // 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. */
+/** Instagram (Business Login flow) — uses IG-native scopes issued by
+ *  instagram.com/oauth/authorize. The resulting token is an IG User
+ *  Access Token that graph.instagram.com accepts. The legacy FB Login
+ *  flow's scopes (`instagram_basic` / `pages_show_list`) produce a FB
+ *  User Token that graph.instagram.com rejects with code=190
+ *  "Cannot parse access token".
+ *
+ *  IG expects scopes joined by COMMAS, not spaces — the core OAuth
+ *  builder joins on space, so we collapse the IG scope list into a
+ *  single comma-joined string here and let the builder treat it as one
+ *  entry. (FB Login accepts both forms.)
+ *
+ *  Only works for IG Business / Creator accounts. */
 const INSTAGRAM_SCOPES = [
-    ...IDENTITY_SCOPES,
-    'instagram_basic',
-    'instagram_manage_messages',
-    'instagram_manage_comments',
+    [
+        'instagram_business_basic',
+        'instagram_business_manage_messages',
+        'instagram_business_manage_comments',
+        'instagram_business_content_publish',
+    ].join(','),
 ];
 /** Messenger Page DMs. `pages_messaging` is the send/receive scope;
  *  `pages_read_engagement` is needed to read the existing thread list
@@ -97,18 +108,46 @@ function buildMetaSurfaceDef(args) {
         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',
+            authorizeUrl: args.oauthOverride?.authorizeUrl ??
+                'https://www.facebook.com/v21.0/dialog/oauth',
+            tokenUrl: args.oauthOverride?.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,
+            authorizeExtras: args.oauthOverride?.authorizeExtras ?? AUTHORIZE_EXTRAS,
+            usePkce: args.oauthOverride?.usePkce ?? true,
         },
         tools: args.tools,
         defaultToolPermissions: args.defaultToolPermissions,
+        // Every Meta surface shares the App ID + App Secret pair (one Meta
+        // App backs all four). Surface-specific secrets (e.g. webhook verify
+        // token for IG/Messenger inbox) are appended via `extraSecrets`.
+        requiredSecrets: [
+            {
+                key: 'META_APP_ID',
+                label: 'Meta App ID',
+                description: 'Numeric App ID shown at developers.facebook.com → My Apps → your app → Settings → Basic.',
+                sensitivity: 'low',
+            },
+            {
+                key: 'META_APP_SECRET',
+                label: 'Meta App Secret',
+                description: 'App Secret from the same Settings → Basic page (click "Show"). Used for OAuth code exchange and to verify webhook signatures (X-Hub-Signature-256).',
+                sensitivity: 'high',
+            },
+            ...(args.extraSecrets ?? []),
+        ],
     };
 }
+/** Webhook verify token used by IG and Messenger inbox subscriptions. */
+const META_WEBHOOK_VERIFY_SECRET = {
+    key: 'META_WEBHOOK_VERIFY_TOKEN',
+    label: 'Webhook verify token',
+    description: 'Any random string. Paste the same value into the Meta App\'s webhook subscription form — Meta echoes it back during the GET handshake so the platform can prove the receiver is ours.',
+    sensitivity: 'medium',
+    optional: true,
+};
 // ── Public surface connectors ───────────────────────────────────────────
 /**
  * Instagram connector — DMs, media list, comments.
@@ -153,7 +192,19 @@ function metaInstagramConnector(opts) {
             { name: 'ig_send_message', mode: 'approval' },
             { name: 'ig_reply_comment', mode: 'approval' },
         ],
+        extraSecrets: [META_WEBHOOK_VERIFY_SECRET],
         opts,
+        // IG Business Login OAuth endpoints. The token from this flow is the
+        // only kind graph.instagram.com accepts; FB Login tokens (the other
+        // three Meta surfaces) get rejected with code=190. IG Business Login
+        // does not support PKCE and rejects FB-specific extras like
+        // `display=popup` / `auth_type=rerequest` with "Invalid platform app".
+        oauthOverride: {
+            authorizeUrl: 'https://www.instagram.com/oauth/authorize/',
+            tokenUrl: 'https://api.instagram.com/oauth/access_token',
+            usePkce: false,
+            authorizeExtras: {},
+        },
     });
 }
 /**
@@ -187,6 +238,7 @@ function metaMessengerConnector(opts) {
             // send_message goes through approval — same reasoning as IG.
             { name: 'messenger_send_message', mode: 'approval' },
         ],
+        extraSecrets: [META_WEBHOOK_VERIFY_SECRET],
         opts,
     });
 }

package/dist/http.d.ts

@@ -31,6 +31,15 @@
  */
 export declare const META_GRAPH_VERSION = "v21.0";
 export declare const META_GRAPH_BASE = "https://graph.facebook.com";
+/**
+ * Instagram Graph API base. Used by apps created with "Instagram with
+ * Facebook Login" (Instagram-business apps); those apps expose IG
+ * Messaging on `graph.instagram.com` instead of `graph.facebook.com`.
+ * Calls to `graph.facebook.com` from such apps fail with error code 3
+ * "Application does not have the capability to make this API call",
+ * even when the token has the right scopes.
+ */
+export declare const META_INSTAGRAM_GRAPH_BASE = "https://graph.instagram.com";
 export declare class MetaApiError extends Error {
     readonly status: number;
     readonly statusText: string;
@@ -64,6 +73,8 @@ export interface MetaRequestOptions {
     path: string;
     query?: Record<string, string | number | boolean | undefined>;
     apiVersion?: string;
+    /** Override the base host. See `SendOptions.apiBase`. */
+    apiBase?: string;
 }
 export interface MetaMutateOptions extends MetaRequestOptions {
     body: unknown;

package/dist/http.js

@@ -31,12 +31,21 @@
  *     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.MetaApiError = exports.META_INSTAGRAM_GRAPH_BASE = 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';
+/**
+ * Instagram Graph API base. Used by apps created with "Instagram with
+ * Facebook Login" (Instagram-business apps); those apps expose IG
+ * Messaging on `graph.instagram.com` instead of `graph.facebook.com`.
+ * Calls to `graph.facebook.com` from such apps fail with error code 3
+ * "Application does not have the capability to make this API call",
+ * even when the token has the right scopes.
+ */
+exports.META_INSTAGRAM_GRAPH_BASE = 'https://graph.instagram.com';
 class MetaApiError extends Error {
     constructor(status, statusText, body, 
     /** Meta error code from the response body. The most useful
@@ -66,7 +75,8 @@ const MAX_5XX_RETRIES = 1;
 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}`}`);
+    const base = opts.apiBase ?? exports.META_GRAPH_BASE;
+    const url = new URL(`${base}/${version}${opts.path.startsWith('/') ? opts.path : `/${opts.path}`}`);
     for (const [k, v] of Object.entries(opts.query ?? {})) {
         if (v === undefined || v === null)
             continue;

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export { metaInstagramConnector, metaMessengerConnector, metaFacebookPagesConnector, metaWhatsAppConnector, type MetaConnectorOptions, } from './connector';
-export { exchangeForLongLivedUserToken, listManagedPages, getManagedPage, listWhatsAppBusinessAccounts, MetaPageSelectionError, } from './page';
+export { exchangeForLongLivedUserToken, exchangeForLongLivedIgUserToken, 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 { metaGet, metaPost, metaDelete, MetaApiError, META_GRAPH_VERSION, META_GRAPH_BASE, META_INSTAGRAM_GRAPH_BASE, } from './http';
 export type { MetaRequestOptions, MetaMutateOptions, MetaPaging, } from './http';

package/dist/index.js

@@ -1,6 +1,6 @@
 "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;
+exports.META_INSTAGRAM_GRAPH_BASE = 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.exchangeForLongLivedIgUserToken = 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; } });
@@ -8,6 +8,7 @@ Object.defineProperty(exports, "metaFacebookPagesConnector", { enumerable: true,
 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, "exchangeForLongLivedIgUserToken", { enumerable: true, get: function () { return page_1.exchangeForLongLivedIgUserToken; } });
 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; } });
@@ -69,3 +70,4 @@ Object.defineProperty(exports, "metaDelete", { enumerable: true, get: function (
 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; } });
+Object.defineProperty(exports, "META_INSTAGRAM_GRAPH_BASE", { enumerable: true, get: function () { return http_1.META_INSTAGRAM_GRAPH_BASE; } });

package/dist/page.d.ts

@@ -61,6 +61,22 @@ export declare function exchangeForLongLivedUserToken(opts: {
     clientId: string;
     clientSecret: string;
 }): Promise<LongLivedUserTokenResponse>;
+/**
+ * IG Business Login long-lived exchange.
+ *
+ * Unlike Facebook Login (which uses `fb_exchange_token` and a Bearer-less
+ * call to graph.facebook.com), Instagram Business Login uses
+ * `ig_exchange_token` against graph.instagram.com with the short-lived
+ * IG User Token in the query string. The result is an IG User Token
+ * (~60 days) that graph.instagram.com accepts on every subsequent call.
+ *
+ * The FB Login exchange does NOT work here — passing an IG short-lived
+ * token to `fb_exchange_token` fails with code=190.
+ */
+export declare function exchangeForLongLivedIgUserToken(opts: {
+    shortLivedIgUserToken: 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

package/dist/page.js

@@ -37,6 +37,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MetaPageSelectionError = void 0;
 exports.exchangeForLongLivedUserToken = exchangeForLongLivedUserToken;
+exports.exchangeForLongLivedIgUserToken = exchangeForLongLivedIgUserToken;
 exports.listManagedPages = listManagedPages;
 exports.getManagedPage = getManagedPage;
 exports.listWhatsAppBusinessAccounts = listWhatsAppBusinessAccounts;
@@ -64,6 +65,29 @@ async function exchangeForLongLivedUserToken(opts) {
     }
     return (await res.json());
 }
+/**
+ * IG Business Login long-lived exchange.
+ *
+ * Unlike Facebook Login (which uses `fb_exchange_token` and a Bearer-less
+ * call to graph.facebook.com), Instagram Business Login uses
+ * `ig_exchange_token` against graph.instagram.com with the short-lived
+ * IG User Token in the query string. The result is an IG User Token
+ * (~60 days) that graph.instagram.com accepts on every subsequent call.
+ *
+ * The FB Login exchange does NOT work here — passing an IG short-lived
+ * token to `fb_exchange_token` fails with code=190.
+ */
+async function exchangeForLongLivedIgUserToken(opts) {
+    const url = new URL(`https://graph.instagram.com/access_token`);
+    url.searchParams.set('grant_type', 'ig_exchange_token');
+    url.searchParams.set('client_secret', opts.clientSecret);
+    url.searchParams.set('access_token', opts.shortLivedIgUserToken);
+    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.

package/dist/tools/instagram.js

@@ -67,6 +67,7 @@ exports.igListThreadsTool = {
         const limit = Math.min(Math.max(Number(input.limit ?? 20), 1), 50);
         const result = await (0, http_1.metaGet)({
             accessToken,
+            apiBase: http_1.META_INSTAGRAM_GRAPH_BASE,
             path: `/${encodeURIComponent(igUserId)}/conversations`,
             query: {
                 platform: 'instagram',
@@ -134,6 +135,7 @@ exports.igListMessagesTool = {
         // GETs — it costs the same quota but saves N round-trips.
         const result = await (0, http_1.metaGet)({
             accessToken,
+            apiBase: http_1.META_INSTAGRAM_GRAPH_BASE,
             path: `/${encodeURIComponent(input.threadId)}`,
             query: {
                 fields: `messages.limit(${limit}){id,message,from{id,username},to{id,username},created_time,attachments{id,mime_type,name,file_url,image_data,video_data}}`,
@@ -210,6 +212,7 @@ exports.igSendMessageTool = {
             : { id: recipientId };
         const result = await (0, http_1.metaPost)({
             accessToken,
+            apiBase: http_1.META_INSTAGRAM_GRAPH_BASE,
             path: `/${encodeURIComponent(igUserId)}/messages`,
             body: {
                 recipient,
@@ -251,6 +254,7 @@ exports.igListMediaTool = {
         const limit = Math.min(Math.max(Number(input.limit ?? 20), 1), 50);
         const result = await (0, http_1.metaGet)({
             accessToken,
+            apiBase: http_1.META_INSTAGRAM_GRAPH_BASE,
             path: `/${encodeURIComponent(igUserId)}/media`,
             query: {
                 fields: 'id,caption,media_type,media_url,permalink,thumbnail_url,timestamp,comments_count,like_count',
@@ -322,6 +326,7 @@ exports.igListCommentsTool = {
             : `/${encodeURIComponent(mediaId)}/comments`;
         const result = await (0, http_1.metaGet)({
             accessToken,
+            apiBase: http_1.META_INSTAGRAM_GRAPH_BASE,
             path,
             query: {
                 fields: 'id,text,timestamp,username,like_count,hidden,replies.limit(0)',
@@ -381,6 +386,7 @@ exports.igReplyCommentTool = {
             throw new Error('message is required.');
         const result = await (0, http_1.metaPost)({
             accessToken,
+            apiBase: http_1.META_INSTAGRAM_GRAPH_BASE,
             path: `/${encodeURIComponent(commentId)}/replies`,
             body: { message },
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/connectors-meta",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Meta Graph API connectors for AgentForge — Instagram DMs/comments, Messenger Page DMs, Facebook Page posts/comments, WhatsApp Cloud outbound. One OAuth client → four independent connectors so the operator only grants the scopes the surface needs.",
   "license": "MIT",
   "main": "dist/index.js",