pi-facebook

Production-ready starter for connecting Pi.dev agents to the Facebook Graph API.

Features

| Feature | Method | Status | |--------------------|------------------------------|--------| | Post text | FacebookClient.postText() | ✅ | | Post photo | FacebookClient.postPhoto() | ✅ | | Delete post | FacebookClient.deletePost()| ✅ | | List posts | FacebookClient.listPosts() | ✅ | | Get insights | FacebookClient.getInsights()| ✅ |

Environment Variables

FACEBOOK_PAGE_ID=your_page_id
FACEBOOK_PAGE_TOKEN=your_page_access_token
FACEBOOK_GRAPH_VERSION=v24.0

Note: The Graph API version defaults to v24.0 and can be overridden via FACEBOOK_GRAPH_VERSION.

Usage

Post Text

import { FacebookClient } from './src/facebook.js';

const client = new FacebookClient(PAGE_ID, TOKEN);
const result = await client.postText('Hello from pi-facebook!');
// { id: "123456789_987654321" }

Post Photo

import { FacebookClient } from './src/facebook.js';

const client = new FacebookClient(PAGE_ID, TOKEN);
const result = await client.postPhoto({
  url: 'https://example.com/photo.jpg',
  message: 'Check out this photo!',  // optional
});
// { id: "123456789_987654321" }

Delete Post

import { FacebookClient } from './src/facebook.js';

const client = new FacebookClient(PAGE_ID, TOKEN);
const result = await client.deletePost('{pageId}_{postId}');
// { success: true }

List Posts

import { FacebookClient } from './src/facebook.js';

const client = new FacebookClient(PAGE_ID, TOKEN);
const posts = await client.listPosts(5);  // limit optional (default 10)
// { data: [...], paging: { ... } }

Get Insights

import { FacebookClient } from './src/facebook.js';

const client = new FacebookClient(PAGE_ID, TOKEN);
const insights = await client.getInsights(
  'page_impressions,page_engaged_users',
  'day',  // 'day' | 'week' | 'days_28' | 'month' | 'lifetime'
);
// { data: [...], paging: { ... } }

AI Prompt Examples (สำหรับ Pi Agent)

หลังจากติดตั้ง pi-facebook แล้ว เพียงแค่พิมพ์บอก Pi ด้วยภาษาธรรมชาติ:

# โพสต์ข้อความ
"โพสต์ข้อความ 'hello world' ไปที่ Facebook Page"
"แคปชั่นเก๋ๆ เกี่ยวกับกาแฟหน่อย"

# โพสต์รูป
"โพสต์รูปนี้ไปที่ Facebook Page พร้อมแคปชั่น"
"แชร์รูปโปรโมทสินค้าลงเพจ"

# ลบโพสต์
"ลบโพสต์ล่าสุด"
"ลบโพสต์ id xxx"

# ดูโพสต์
"แสดง 5 โพสต์ล่าสุดบนเพจ"
"มีอะไรใหม่บนเพจบ้าง"

# ดู Insights
"ยอด reach เมื่อวานเท่าไหร่"
"แสดง engagement 7 วันที่ผ่านมา"
"สถิติเพจเดือนนี้"

Pi จะเลือกใช้ tool ที่เหมาะสมให้อัตโนมัติ!

Tool Wrappers (for Pi Agent MCP)

Each feature also exposes a standalone tool function for Pi agent invocation:

import { facebook_post_text } from './src/tools/postText.js';
import { facebook_post_photo } from './src/tools/postPhoto.js';
import { facebook_delete_post } from './src/tools/deletePost.js';
import { facebook_list_posts } from './src/tools/listPosts.js';
import { facebook_get_insights } from './src/tools/getInsights.js';

await facebook_post_text(PAGE_ID, TOKEN, 'Hello!');
await facebook_post_photo(PAGE_ID, TOKEN, 'https://...', 'Optional caption');
await facebook_delete_post(PAGE_ID, TOKEN, '{pageId}_{postId}');
await facebook_list_posts(PAGE_ID, TOKEN, 10);
await facebook_get_insights(PAGE_ID, TOKEN, 'page_impressions', 'day');

Architecture

Scheduler → AI Agent → pi-facebook → Facebook Graph API → Facebook Page

Project Structure

pi-facebook/
├── README.md
├── package.json
├── tsconfig.json
├── docs/
│   └── architecture.md
└── src/
    ├── facebook.ts              # FacebookClient (core)
    └── tools/
        ├── postText.ts
        ├── postPhoto.ts
        ├── deletePost.ts
        ├── listPosts.ts
        └── getInsights.ts

Development

npm install       # install dependencies
npm test          # run vitest tests
npm run build     # tsc compile