@agentforge-io/connectors-meta 0.1.0

package/dist/tools/instagram.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * Instagram Graph API tools.
+ *
+ * Six tools covering the MVP scope the agent needs to act as a brand
+ * social-media respondent:
+ *
+ *   1. ig_list_threads      — inbox threads, newest first
+ *   2. ig_list_messages     — messages in a thread
+ *   3. ig_send_message      — send a DM (24h window applies)
+ *   4. ig_list_media        — recent feed posts (id + caption + media URL)
+ *   5. ig_list_comments     — comments on a specific post
+ *   6. ig_reply_comment     — reply to a comment thread
+ *
+ * Token model:
+ *   - `ctx.getAccessToken()` returns the PAGE access token that was
+ *     persisted at connect-time (NOT the user token). All IG Graph
+ *     calls accept the page token for the linked IG Business account.
+ *   - `ctx.metadata.igUserId` is the linked IG Business Account id —
+ *     the IG user id, not the @-handle. Set by the connect modal when
+ *     the operator picks the Page.
+ *
+ * Why these endpoints (not the Basic Display API):
+ *   - The Basic Display API is being deprecated and only covers PERSONAL
+ *     IG accounts. The Graph API (what we use) covers Business +
+ *     Creator accounts via the Page link. For an agent that needs to
+ *     READ and REPLY, Graph API is the only viable choice.
+ *
+ * 24h messaging window:
+ *   - Meta enforces a 24h reply window for unsolicited DMs. Sending
+ *     after 24h returns error code 10. We surface the constraint in
+ *     the tool description but don't pre-validate — there's no reliable
+ *     way to check from the client (the "last user message" timestamp
+ *     of every conversation would be N+1 calls per send), and the API
+ *     error is the authoritative answer.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.igReplyCommentTool = exports.igListCommentsTool = exports.igListMediaTool = exports.igSendMessageTool = exports.igListMessagesTool = exports.igListThreadsTool = void 0;
+const http_1 = require("../http");
+const _shared_1 = require("./_shared");
+exports.igListThreadsTool = {
+    definition: {
+        name: 'ig_list_threads',
+        description: "List the Instagram Business inbox's conversation threads, " +
+            'newest-updated first. Returns thread id, updated time, ' +
+            'participant ids/usernames, and the latest message preview. Use ' +
+            '`cursor` from a previous response to paginate.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: {
+                    type: 'number',
+                    description: 'Max threads (1-50, default 20).',
+                    minimum: 1,
+                    maximum: 50,
+                },
+                cursor: {
+                    type: 'string',
+                    description: 'Pagination cursor from a previous call. Omit on the first page.',
+                },
+            },
+        },
+    },
+    build: (ctx) => async (input) => {
+        const igUserId = (0, _shared_1.resolveIgUserId)(ctx);
+        const accessToken = await ctx.getAccessToken();
+        const limit = Math.min(Math.max(Number(input.limit ?? 20), 1), 50);
+        const result = await (0, http_1.metaGet)({
+            accessToken,
+            path: `/${encodeURIComponent(igUserId)}/conversations`,
+            query: {
+                platform: 'instagram',
+                fields: 'id,updated_time,participants{id,username},messages.limit(1){id,message,from{id,username},created_time}',
+                limit,
+                after: input.cursor,
+            },
+        });
+        return JSON.stringify({
+            threads: result.data.map((t) => ({
+                id: t.id,
+                updatedAt: t.updated_time,
+                participants: t.participants?.data?.map((p) => ({
+                    id: p.id,
+                    username: p.username,
+                })) ?? [],
+                latestMessage: t.messages?.data?.[0]
+                    ? {
+                        id: t.messages.data[0].id,
+                        text: t.messages.data[0].message,
+                        fromId: t.messages.data[0].from?.id,
+                        fromUsername: t.messages.data[0].from?.username,
+                        createdAt: t.messages.data[0].created_time,
+                    }
+                    : null,
+            })),
+            pageInfo: {
+                nextCursor: result.paging?.cursors?.after,
+                hasNextPage: Boolean(result.paging?.next),
+            },
+        });
+    },
+};
+exports.igListMessagesTool = {
+    definition: {
+        name: 'ig_list_messages',
+        description: 'List the messages in an Instagram DM thread, newest first. ' +
+            'Returns message id, text, sender id/username, created time, and ' +
+            'attachment URLs (image/video/audio).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                threadId: {
+                    type: 'string',
+                    description: 'Conversation id from `ig_list_threads`.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max messages (1-100, default 25).',
+                    minimum: 1,
+                    maximum: 100,
+                },
+            },
+            required: ['threadId'],
+        },
+    },
+    build: (ctx) => async (input) => {
+        if (!input.threadId || typeof input.threadId !== 'string') {
+            throw new Error('threadId is required (from ig_list_threads).');
+        }
+        const accessToken = await ctx.getAccessToken();
+        const limit = Math.min(Math.max(Number(input.limit ?? 25), 1), 100);
+        // Conversations expose their messages via the `messages` edge. We
+        // request the inner fields in one shot instead of doing per-message
+        // GETs — it costs the same quota but saves N round-trips.
+        const result = await (0, http_1.metaGet)({
+            accessToken,
+            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}}`,
+            },
+        });
+        return JSON.stringify({
+            messages: result.messages?.data?.map((m) => ({
+                id: m.id,
+                text: m.message,
+                fromId: m.from?.id,
+                fromUsername: m.from?.username,
+                toIds: m.to?.data?.map((t) => t.id),
+                createdAt: m.created_time,
+                attachments: m.attachments?.data?.map((a) => ({
+                    id: a.id,
+                    mimeType: a.mime_type,
+                    name: a.name,
+                    url: a.file_url ?? a.image_data?.url ?? a.video_data?.url,
+                })) ?? [],
+            })) ?? [],
+        });
+    },
+};
+exports.igSendMessageTool = {
+    definition: {
+        name: 'ig_send_message',
+        description: 'Send a DM to a user on Instagram. The recipient must have ' +
+            'messaged the connected IG account within the last 24 hours; ' +
+            'outside that window Meta returns error code 10 and the message ' +
+            "is not delivered. Pass either `recipientId` (the IG user id you " +
+            'got from `ig_list_threads` participants) or `threadId` ' +
+            '(conversation id) — passing both is redundant.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                recipientId: {
+                    type: 'string',
+                    description: 'IG user id of the recipient (from `ig_list_threads` ' +
+                        'participants[].id). Required when `threadId` is not set.',
+                },
+                threadId: {
+                    type: 'string',
+                    description: 'Conversation id (from `ig_list_threads`). When set, the ' +
+                        'message goes to the same thread without needing the ' +
+                        'recipient id.',
+                },
+                text: {
+                    type: 'string',
+                    description: 'Message body, ≤1000 chars (Meta hard limit).',
+                    maxLength: 1000,
+                },
+            },
+            required: ['text'],
+        },
+    },
+    build: (ctx) => async (input) => {
+        const igUserId = (0, _shared_1.resolveIgUserId)(ctx);
+        const accessToken = await ctx.getAccessToken();
+        const text = String(input.text ?? '').trim();
+        if (!text) {
+            throw new Error('text is required and must not be empty.');
+        }
+        const recipientId = input.recipientId;
+        const threadId = input.threadId;
+        if (!recipientId && !threadId) {
+            throw new Error('Either `recipientId` or `threadId` must be provided.');
+        }
+        // Meta accepts EITHER `recipient.id` (a user id) OR
+        // `recipient.thread_key` (a conversation id). We prefer thread_key
+        // when both are provided because it's more robust against IG users
+        // changing their ig-scoped id across re-authentications.
+        const recipient = threadId
+            ? { thread_key: threadId }
+            : { id: recipientId };
+        const result = await (0, http_1.metaPost)({
+            accessToken,
+            path: `/${encodeURIComponent(igUserId)}/messages`,
+            body: {
+                recipient,
+                message: { text },
+            },
+        });
+        return JSON.stringify({
+            messageId: result.message_id,
+            recipientId: result.recipient_id,
+        });
+    },
+};
+exports.igListMediaTool = {
+    definition: {
+        name: 'ig_list_media',
+        description: "List the connected Instagram Business account's published " +
+            'media (feed posts, reels, carousels), newest first. Returns id, ' +
+            'caption, media type, media URL, permalink, and engagement ' +
+            'counts. Use the post id with `ig_list_comments` to read replies.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: {
+                    type: 'number',
+                    description: 'Max items (1-50, default 20).',
+                    minimum: 1,
+                    maximum: 50,
+                },
+                cursor: {
+                    type: 'string',
+                    description: 'Pagination cursor from a previous call.',
+                },
+            },
+        },
+    },
+    build: (ctx) => async (input) => {
+        const igUserId = (0, _shared_1.resolveIgUserId)(ctx);
+        const accessToken = await ctx.getAccessToken();
+        const limit = Math.min(Math.max(Number(input.limit ?? 20), 1), 50);
+        const result = await (0, http_1.metaGet)({
+            accessToken,
+            path: `/${encodeURIComponent(igUserId)}/media`,
+            query: {
+                fields: 'id,caption,media_type,media_url,permalink,thumbnail_url,timestamp,comments_count,like_count',
+                limit,
+                after: input.cursor,
+            },
+        });
+        return JSON.stringify({
+            media: result.data.map((m) => ({
+                id: m.id,
+                caption: m.caption,
+                mediaType: m.media_type,
+                mediaUrl: m.media_url,
+                permalink: m.permalink,
+                thumbnailUrl: m.thumbnail_url,
+                publishedAt: m.timestamp,
+                commentsCount: m.comments_count,
+                likeCount: m.like_count,
+            })),
+            pageInfo: {
+                nextCursor: result.paging?.cursors?.after,
+                hasNextPage: Boolean(result.paging?.next),
+            },
+        });
+    },
+};
+exports.igListCommentsTool = {
+    definition: {
+        name: 'ig_list_comments',
+        description: 'List comments on an Instagram media item (or replies under a ' +
+            'specific parent comment). Returns comment id, text, author ' +
+            'username, like count, hidden flag, and a reply-count hint.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                mediaId: {
+                    type: 'string',
+                    description: 'IG media id from `ig_list_media`. Required when ' +
+                        '`parentCommentId` is not set.',
+                },
+                parentCommentId: {
+                    type: 'string',
+                    description: "Comment id to read replies under. When set, mediaId is " +
+                        'ignored — the API routes through the parent comment.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max comments (1-50, default 25).',
+                    minimum: 1,
+                    maximum: 50,
+                },
+                cursor: {
+                    type: 'string',
+                    description: 'Pagination cursor from a previous call.',
+                },
+            },
+        },
+    },
+    build: (ctx) => async (input) => {
+        const accessToken = await ctx.getAccessToken();
+        const mediaId = input.mediaId;
+        const parentCommentId = input.parentCommentId;
+        if (!mediaId && !parentCommentId) {
+            throw new Error('Either `mediaId` or `parentCommentId` must be provided.');
+        }
+        const limit = Math.min(Math.max(Number(input.limit ?? 25), 1), 50);
+        const path = parentCommentId
+            ? `/${encodeURIComponent(parentCommentId)}/replies`
+            : `/${encodeURIComponent(mediaId)}/comments`;
+        const result = await (0, http_1.metaGet)({
+            accessToken,
+            path,
+            query: {
+                fields: 'id,text,timestamp,username,like_count,hidden,replies.limit(0)',
+                limit,
+                after: input.cursor,
+            },
+        });
+        return JSON.stringify({
+            comments: result.data.map((c) => ({
+                id: c.id,
+                text: c.text,
+                username: c.username,
+                likeCount: c.like_count,
+                hidden: c.hidden,
+                // `replies.limit(0)` returns the paging envelope without rows.
+                // We use the presence of the edge to expose "this comment has
+                // replies" without paying for them.
+                hasReplies: Boolean(c.replies?.data?.length),
+                createdAt: c.timestamp,
+            })),
+            pageInfo: {
+                nextCursor: result.paging?.cursors?.after,
+                hasNextPage: Boolean(result.paging?.next),
+            },
+        });
+    },
+};
+exports.igReplyCommentTool = {
+    definition: {
+        name: 'ig_reply_comment',
+        description: 'Reply to a comment on an Instagram post. The reply nests under ' +
+            'the target comment as a public child reply. Returns the new ' +
+            'comment id.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                commentId: {
+                    type: 'string',
+                    description: 'IG comment id to reply to (from `ig_list_comments`).',
+                },
+                message: {
+                    type: 'string',
+                    description: 'Reply text, ≤2200 chars (IG hard limit).',
+                    maxLength: 2200,
+                },
+            },
+            required: ['commentId', 'message'],
+        },
+    },
+    build: (ctx) => async (input) => {
+        const accessToken = await ctx.getAccessToken();
+        const commentId = String(input.commentId ?? '').trim();
+        const message = String(input.message ?? '').trim();
+        if (!commentId)
+            throw new Error('commentId is required.');
+        if (!message)
+            throw new Error('message is required.');
+        const result = await (0, http_1.metaPost)({
+            accessToken,
+            path: `/${encodeURIComponent(commentId)}/replies`,
+            body: { message },
+        });
+        return JSON.stringify({ commentId: result.id });
+    },
+};

package/dist/tools/messenger.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Messenger (Page DMs) tools.
+ *
+ * Four tools covering the MVP scope for a Page-bound respondent:
+ *
+ *   1. messenger_list_threads    — Page inbox, newest first
+ *   2. messenger_list_messages   — messages in a thread
+ *   3. messenger_send_message    — send a message (24h window + tags)
+ *   4. messenger_mark_seen       — sender_action: mark thread as seen
+ *
+ * Token model:
+ *   - `ctx.getAccessToken()` returns the PAGE access token persisted at
+ *     connect-time. Same property as Instagram — the page token
+ *     authorizes both surfaces.
+ *   - `ctx.metadata.pageId` is the Page id (NOT the IG user id). Used
+ *     in every endpoint path here.
+ *
+ * Why so close to Instagram's shape (but a separate file):
+ *   - Conversations API is shared (same fields), so the response
+ *     parsing is similar. But the routing key is different (page id vs
+ *     IG user id), the platform discriminator is different, and the
+ *     send-message body has a Messenger-specific `messaging_type` +
+ *     `tag` set that doesn't exist on Instagram. Trying to share a
+ *     single send-tool implementation between them would mean a giant
+ *     conditional on platform; cleaner to fork.
+ *
+ * 24h messaging window (the Messenger-specific quirk):
+ *   - Inside 24h of the user's last message → `messaging_type=RESPONSE`
+ *     (free-form, no tag).
+ *   - Outside 24h → `messaging_type=MESSAGE_TAG` + an approved `tag`
+ *     (HUMAN_AGENT, ACCOUNT_UPDATE, CONFIRMED_EVENT_UPDATE,
+ *     POST_PURCHASE_UPDATE). Sending without a tag returns error
+ *     code 10 ("App does not have permission for this messaging").
+ *   - We expose `messagingType` + `tag` in the schema; defaults are
+ *     RESPONSE/null. The agent can pick MESSAGE_TAG when it knows it's
+ *     outside the window — the API is authoritative on the actual
+ *     decision.
+ */
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+export declare const messengerListThreadsTool: ConnectorToolFactory;
+export declare const messengerListMessagesTool: ConnectorToolFactory;
+export declare const messengerSendMessageTool: ConnectorToolFactory;
+export declare const messengerMarkSeenTool: ConnectorToolFactory;