Facebook (Pages API)

scope: pages_manage_posts,pages_read_engagement,pages_show_list,publish_to_groups

Stored in integrations:
  provider:   'facebook'
  api_key:    encrypt(long_lived_page_access_token)
  metadata:   {
    pageId:           '111222333444',
    pageName:         'Acme Plumbing',
    accessToken:      string,   // Page access token (not user token)
    tokenExpiresAt:   string,   // Long-lived page tokens don't expire, but track anyway
  }

class FacebookTool {
  constructor(
    private pageId:      string,
    private accessToken: string,
    private baseUrl:     string = 'https://graph.facebook.com/v19.0',
  ) {}
 
  async publishPost(options: {
    message:      string;    // Post copy text
    link?:        string;    // Optional URL to attach (shows link preview)
    imageUrls?:   string[];  // URLs of images to attach
    published?:   boolean;   // true = publish now; false = create as draft (default: false)
    scheduledAt?: Date;      // Schedule for future time (requires published: false)
  }): Promise<{ postId: string; postUrl: string }> {
    // If images provided, create a multi-photo post
    if (options.imageUrls?.length) {
      return this.publishPhotoPost(options);
    }
 
    const params: Record<string, any> = {
      message:     options.message,
      access_token: this.accessToken,
    };
 
    if (options.link)          params.link        = options.link;
    if (options.published === false) params.published = false;
    if (options.scheduledAt)   {
      params.published        = false;
      params.scheduled_publish_time = Math.floor(options.scheduledAt.getTime() / 1000);
    }
 
    const response = await axios.post(
      `${this.baseUrl}/${this.pageId}/feed`,
      params,
    );
 
    return {
      postId:  response.data.id,
      postUrl: `https://www.facebook.com/${response.data.id}`,
    };
  }
 
  private async publishPhotoPost(options: {
    message:   string;
    imageUrls: string[];
    published?: boolean;
  }): Promise<{ postId: string; postUrl: string }> {
    // Upload each photo as unpublished, then attach to a multi-image post
    const mediaIds = await Promise.all(
      options.imageUrls.map(url =>
        axios.post(`${this.baseUrl}/${this.pageId}/photos`, {
          url,
          published:    false,
          access_token: this.accessToken,
        }).then(r => ({ media_fbid: r.data.id })),
      ),
    );
 
    const response = await axios.post(`${this.baseUrl}/${this.pageId}/feed`, {
      message:      options.message,
      attached_media: mediaIds,
      published:    options.published ?? false,
      access_token: this.accessToken,
    });
 
    return {
      postId:  response.data.id,
      postUrl: `https://www.facebook.com/${response.data.id}`,
    };
  }
 
  async getPageInsights(options: {
    metrics:    string[];   // e.g. ['page_impressions', 'page_engaged_users']
    startDate:  string;     // YYYY-MM-DD
    endDate:    string;
    period?:    string;     // 'day' | 'week' | 'month' (default: 'day')
  }): Promise<PageInsightRow[]> {
    const response = await axios.get(
      `${this.baseUrl}/${this.pageId}/insights`,
      {
        params: {
          metric:       options.metrics.join(','),
          since:        options.startDate,
          until:        options.endDate,
          period:       options.period ?? 'day',
          access_token: this.accessToken,
        },
      },
    );
    return response.data.data.map((metric: any) => ({
      name:   metric.name,
      period: metric.period,
      values: metric.values,  // [{ value, end_time }]
    }));
  }
 
  async getPages(): Promise<{ id: string; name: string; category: string }[]> {
    const response = await axios.get(`${this.baseUrl}/me/accounts`, {
      params: { access_token: this.accessToken },
    });
    return response.data.data.map((p: any) => ({
      id:       p.id,
      name:     p.name,
      category: p.category,
    }));
  }
 
  async verify(): Promise<void> {
    const response = await axios.get(`${this.baseUrl}/${this.pageId}`, {
      params: {
        fields:       'id,name',
        access_token: this.accessToken,
      },
    });
    if (!response.data.id) throw new Error('Facebook Page not found');
  }
}

Social Calendar Planner generates monthly post schedule
        │
        ▼
Social Post Writer creates copy for each Facebook slot
        │
        ▼ (HITL approval)
Social Publisher worker
  ├── Resolve tenant's Facebook integration
  ├── Post copy → Graph API /feed (as draft or scheduled)
  └── Store postId + postUrl in social_posts.external_id + social_posts.publish_url