@agentforge-io/connectors-meta 0.1.0

package/dist/tools/facebook-pages.js

@@ -0,0 +1,362 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fbReplyCommentTool = exports.fbListCommentsTool = exports.fbCreatePostTool = exports.fbGetPostTool = exports.fbListPostsTool = void 0;
+const http_1 = require("../http");
+const _shared_1 = require("./_shared");
+exports.fbListPostsTool = {
+    definition: {
+        name: 'fb_list_posts',
+        description: "List the connected Facebook Page's own published posts, newest " +
+            'first. Returns post id, message, link, created time, permalink, ' +
+            'is-published flag, scheduled time (when applicable), and ' +
+            'engagement totals (likes, comments, shares).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: {
+                    type: 'number',
+                    description: 'Max posts (1-50, default 20).',
+                    minimum: 1,
+                    maximum: 50,
+                },
+                cursor: {
+                    type: 'string',
+                    description: 'Pagination cursor from a previous call.',
+                },
+                includeUnpublished: {
+                    type: 'boolean',
+                    description: 'When true, includes scheduled + draft posts that are not ' +
+                        'yet visible. Default false (published only).',
+                },
+            },
+        },
+    },
+    build: (ctx) => async (input) => {
+        const pageId = (0, _shared_1.resolvePageId)(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,
+            // Meta exposes scheduled/draft posts only via the alternate
+            // `promotable_posts` edge when `is_published=false` is requested.
+            // For the published-only default we use the standard `/posts`.
+            path: input.includeUnpublished
+                ? `/${encodeURIComponent(pageId)}/promotable_posts`
+                : `/${encodeURIComponent(pageId)}/posts`,
+            query: {
+                fields: 'id,message,story,created_time,permalink_url,link,scheduled_publish_time,is_published,likes.summary(true).limit(0),comments.summary(true).limit(0),shares',
+                limit,
+                after: input.cursor,
+            },
+        });
+        return JSON.stringify({
+            posts: result.data.map((p) => ({
+                id: p.id,
+                message: p.message,
+                story: p.story,
+                link: p.link,
+                permalink: p.permalink_url,
+                createdAt: p.created_time,
+                scheduledPublishTime: p.scheduled_publish_time,
+                isPublished: p.is_published ?? true,
+                engagement: {
+                    likes: p.likes?.summary?.total_count ?? 0,
+                    comments: p.comments?.summary?.total_count ?? 0,
+                    shares: p.shares?.count ?? 0,
+                },
+            })),
+            pageInfo: {
+                nextCursor: result.paging?.cursors?.after,
+                hasNextPage: Boolean(result.paging?.next),
+            },
+        });
+    },
+};
+exports.fbGetPostTool = {
+    definition: {
+        name: 'fb_get_post',
+        description: 'Fetch a single Facebook Page post with full engagement + ' +
+            'attachments. Returns message, link, permalink, status type, ' +
+            'attachment metadata (type, URL, title, media URL), and ' +
+            'engagement totals.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                postId: {
+                    type: 'string',
+                    description: 'Post id from `fb_list_posts`.',
+                },
+            },
+            required: ['postId'],
+        },
+    },
+    build: (ctx) => async (input) => {
+        const postId = String(input.postId ?? '').trim();
+        if (!postId)
+            throw new Error('postId is required.');
+        const accessToken = await ctx.getAccessToken();
+        const post = await (0, http_1.metaGet)({
+            accessToken,
+            path: `/${encodeURIComponent(postId)}`,
+            query: {
+                fields: 'id,message,story,created_time,updated_time,permalink_url,link,scheduled_publish_time,is_published,status_type,attachments{type,media_type,url,title,description,media},likes.summary(true).limit(0),comments.summary(true).limit(0),shares,reactions.summary(true).limit(0)',
+            },
+        });
+        return JSON.stringify({
+            id: post.id,
+            message: post.message,
+            story: post.story,
+            link: post.link,
+            permalink: post.permalink_url,
+            createdAt: post.created_time,
+            updatedAt: post.updated_time,
+            statusType: post.status_type,
+            scheduledPublishTime: post.scheduled_publish_time,
+            isPublished: post.is_published ?? true,
+            attachments: post.attachments?.data?.map((a) => ({
+                type: a.type,
+                mediaType: a.media_type,
+                url: a.url,
+                title: a.title,
+                description: a.description,
+                mediaUrl: a.media?.image?.src ?? a.media?.source,
+            })) ?? [],
+            engagement: {
+                likes: post.likes?.summary?.total_count ?? 0,
+                comments: post.comments?.summary?.total_count ?? 0,
+                shares: post.shares?.count ?? 0,
+                reactions: post.reactions?.summary?.total_count ?? 0,
+            },
+        });
+    },
+};
+/** Hard window Meta enforces on `scheduled_publish_time`:
+ *    - earliest: 10 minutes from now
+ *    - latest:   6 months (≈ 180 days) from now
+ *  Outside the window returns code 100 with a useless message; we
+ *  pre-check to give the agent a clearer error. */
+const MIN_SCHEDULE_SECONDS = 10 * 60;
+const MAX_SCHEDULE_SECONDS = 180 * 24 * 60 * 60;
+exports.fbCreatePostTool = {
+    definition: {
+        name: 'fb_create_post',
+        description: 'Publish (or schedule) a text/link post on the connected ' +
+            'Facebook Page. For a link post, set `link` — Meta scrapes the ' +
+            "URL's OG tags to render the preview. For a scheduled post, set " +
+            '`scheduledPublishTime` (unix seconds, 10min–6mo from now). ' +
+            'Returns the new post id.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                message: {
+                    type: 'string',
+                    description: 'Post body. At least one of `message` or `link` is required.',
+                },
+                link: {
+                    type: 'string',
+                    description: 'URL to share. Meta scrapes OG tags and renders a link card. ' +
+                        "At least one of `message` or `link` is required.",
+                },
+                scheduledPublishTime: {
+                    type: 'number',
+                    description: 'Unix seconds at which to publish. Must be between 10 ' +
+                        'minutes and 6 months from now. When omitted, the post ' +
+                        'publishes immediately.',
+                },
+            },
+        },
+    },
+    build: (ctx) => async (input) => {
+        const pageId = (0, _shared_1.resolvePageId)(ctx);
+        const accessToken = await ctx.getAccessToken();
+        const message = input.message
+            ? String(input.message).trim()
+            : undefined;
+        const link = input.link ? String(input.link).trim() : undefined;
+        if (!message && !link) {
+            throw new Error('At least one of `message` or `link` must be provided.');
+        }
+        let scheduledPublishTime;
+        let published = true;
+        if (input.scheduledPublishTime !== undefined) {
+            scheduledPublishTime = Number(input.scheduledPublishTime);
+            const now = Math.floor(Date.now() / 1000);
+            const delta = scheduledPublishTime - now;
+            if (!Number.isFinite(scheduledPublishTime) || delta < MIN_SCHEDULE_SECONDS) {
+                throw new Error('scheduledPublishTime must be at least 10 minutes in the future ' +
+                    `(unix seconds; received ${input.scheduledPublishTime}, now=${now}).`);
+            }
+            if (delta > MAX_SCHEDULE_SECONDS) {
+                throw new Error('scheduledPublishTime must be within 6 months of now.');
+            }
+            published = false;
+        }
+        const result = await (0, http_1.metaPost)({
+            accessToken,
+            path: `/${encodeURIComponent(pageId)}/feed`,
+            body: {
+                ...(message ? { message } : {}),
+                ...(link ? { link } : {}),
+                published,
+                ...(scheduledPublishTime
+                    ? { scheduled_publish_time: scheduledPublishTime }
+                    : {}),
+            },
+        });
+        return JSON.stringify({
+            postId: result.id,
+            published,
+            scheduledPublishTime,
+        });
+    },
+};
+exports.fbListCommentsTool = {
+    definition: {
+        name: 'fb_list_comments',
+        description: 'List comments on a Facebook Page post (or replies under a ' +
+            'specific parent comment). Returns id, message, author, like ' +
+            'count, reply count, hidden flag, parent id, and created time.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                postId: {
+                    type: 'string',
+                    description: 'Post id from `fb_list_posts`. Required when ' +
+                        '`parentCommentId` is not set.',
+                },
+                parentCommentId: {
+                    type: 'string',
+                    description: 'Comment id to read replies under. When set, `postId` is ' +
+                        'ignored.',
+                },
+                order: {
+                    type: 'string',
+                    enum: ['chronological', 'reverse_chronological'],
+                    description: 'Sort order. Default `reverse_chronological` (newest first).',
+                },
+                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 postId = input.postId;
+        const parentCommentId = input.parentCommentId;
+        if (!postId && !parentCommentId) {
+            throw new Error('Either `postId` or `parentCommentId` must be provided.');
+        }
+        const limit = Math.min(Math.max(Number(input.limit ?? 25), 1), 50);
+        const path = parentCommentId
+            ? `/${encodeURIComponent(parentCommentId)}/comments`
+            : `/${encodeURIComponent(postId)}/comments`;
+        const result = await (0, http_1.metaGet)({
+            accessToken,
+            path,
+            query: {
+                fields: 'id,message,created_time,from{id,name},like_count,comment_count,is_hidden,parent{id}',
+                order: input.order ?? 'reverse_chronological',
+                limit,
+                after: input.cursor,
+            },
+        });
+        return JSON.stringify({
+            comments: result.data.map((c) => ({
+                id: c.id,
+                message: c.message,
+                authorId: c.from?.id,
+                authorName: c.from?.name,
+                likeCount: c.like_count ?? 0,
+                replyCount: c.comment_count ?? 0,
+                hidden: c.is_hidden ?? false,
+                parentId: c.parent?.id,
+                createdAt: c.created_time,
+            })),
+            pageInfo: {
+                nextCursor: result.paging?.cursors?.after,
+                hasNextPage: Boolean(result.paging?.next),
+            },
+        });
+    },
+};
+exports.fbReplyCommentTool = {
+    definition: {
+        name: 'fb_reply_comment',
+        description: "Reply to a comment on a Facebook Page post. The reply nests " +
+            'under the target comment as a public child comment. Returns ' +
+            'the new comment id.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                commentId: {
+                    type: 'string',
+                    description: 'FB comment id to reply to (from `fb_list_comments`).',
+                },
+                message: {
+                    type: 'string',
+                    description: 'Reply text, ≤8000 chars (FB hard limit).',
+                    maxLength: 8000,
+                },
+            },
+            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)}/comments`,
+            body: { message },
+        });
+        return JSON.stringify({ commentId: result.id });
+    },
+};

package/dist/tools/instagram.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+import type { ConnectorToolFactory } from '@agentforge-io/core';
+export declare const igListThreadsTool: ConnectorToolFactory;
+export declare const igListMessagesTool: ConnectorToolFactory;
+export declare const igSendMessageTool: ConnectorToolFactory;
+export declare const igListMediaTool: ConnectorToolFactory;
+export declare const igListCommentsTool: ConnectorToolFactory;
+export declare const igReplyCommentTool: ConnectorToolFactory;