mkt-business-meta

TypeScript library for Meta business automation flows:

• Login (including 2FA)
• Resolve business pages and page access tokens
• Create Facebook posts and reels with media upload support

Built for Bun runtime.

Features

• FbMetaClient with modular services: auth, businessPages, composer
• Upload pipeline for:
  • image posts
  • video posts
  • mixed media posts
  • reels
• File-path-first media input (filePath) with internal base64 conversion
• Structured success/failure responses for all public APIs

Installation

bun add mkt-business-meta

For local development in this repo:

bun install

Quick Start

import { FbMetaClient } from 'mkt-business-meta'

const client = new FbMetaClient({
  appId: process.env.META_APP_ID!,
  appAccessToken: process.env.META_APP_ACCESS_TOKEN!,
  logLevel: 'info',
})

API Overview

1) Auth

const login = await client.auth.login({
  email: '[email protected]',
  password: 'your-password',
  // optional when account has 2FA
  twoFactorSecret: 'BASE32_SECRET',
})

Success response:

{
  success: true,
  data: {
    uid: string,
    accessToken: string,
    cookieHeader?: string,
    machineId?: string,
    cookies?: Array<{ name: string; value: string }>
  }
}

Error response:

{
  success: false,
  error: {
    message: string,
    code?: number,
    subcode?: number,
    raw?: unknown
  }
}

2) Business Pages / Page Tokens

const pageTokens = await client.businessPages.getPageAccessTokens({
  accessToken: '<USER_ACCESS_TOKEN>',
  // optional filter
  pageIds: ['1132154543308068'],
})

Success response:

{
  success: true,
  data: {
    pages: Array<{
      pageId: string,
      pageName?: string,
      actorId: string,
      accessToken: string,
      tokenSource: 'admin_info' | 'mailbox',
      scopeId?: string,
      scopeName?: string,
      scopeType?: string,
      fetchedAt: number
    }>,
    failedPages: Array<{
      pageId: string,
      pageName?: string,
      message: string
    }>,
    totalRequested: number,
    totalResolved: number,
    totalFailed: number
  }
}

Error response:

{
  success: false,
  error: {
    message: string,
    raw?: unknown
  }
}

3) Create Post

const post = await client.composer.createPost({
  pageId: '1132154543308068',
  accessToken: '<PAGE_ACCESS_TOKEN>',
  message: 'Hello from library',
  images: [
    { filePath: '/absolute/path/to/image-1.jpg' },
    { filePath: '/absolute/path/to/image-2.png' },
  ],
  videos: [{ filePath: '/absolute/path/to/video.mp4' }],
})

Success response:

{
  success: true,
  data: {
    postId: string,
    storyId: string,
    cacheId: string,
    postIdSource?: 'story' | 'video_fallback',
    channelErrors: Record<string, unknown>
  }
}

Error response:

{
  success: false,
  error: {
    message: string,
    raw?: unknown
  }
}

4) Create Reel

const reel = await client.composer.createReel({
  pageId: '1132154543308068',
  accessToken: '<PAGE_ACCESS_TOKEN>',
  // optional
  message: 'Reel caption',
  videos: [{ filePath: '/absolute/path/to/reel.mp4' }],
})

Success response:

{
  success: true,
  data: {
    postId: string,
    storyId: string,
    cacheId: string,
    postIdSource?: 'story' | 'video_fallback',
    channelErrors: Record<string, unknown>
  }
}

API Matrix

| API | Input | Success | Notes | | --- | --- | --- | --- | | auth.login | email, password, optional twoFactorSecret | uid, accessToken, optional cookies/machineId | Returns structured auth/session data | | businessPages.getPageAccessTokens | user access token, optional pageIds | list of page access tokens + failed pages summary | token source is admin_info or mailbox | | composer.createPost | page token, message, optional images/videos | postId, storyId, cacheId, postIdSource, channelErrors | single-video post can fallback postId = videoId | | composer.createReel | page token, one video, optional message | postId, storyId, cacheId, postIdSource, channelErrors | fallback postId = videoId when story id unavailable |

Error response:

{
  success: false,
  error: {
    message: string,
    raw?: unknown
  }
}

Exported Types

The package exports these public payload/response aliases from src/index.ts:

• LoginPayload, LoginResponse
• GetPageAccessTokensPayload, GetPageAccessTokensResponse
• GetBusinessScopesResponse
• CreatePostPayload, CreatePostResponse
• CreateReelPayload, CreateReelResponse

Example:

import type {
  CreatePostPayload,
  CreatePostResponse,
  CreateReelPayload,
  CreateReelResponse,
  LoginPayload,
  LoginResponse,
} from 'mkt-business-meta'

Media Input Rules

• images[].filePath is required for post images.
• videos[].filePath is required for post/reel videos.
• Library reads file content internally and sends base64 payload to Meta APIs.
• Optional fields like filename, mimeType, and video metadata are supported.

Response Behavior

Create Post

• content -> returns postId when story identifiers are available.
• content + multiple images -> returns postId when story identifiers are available.
• content + 1 video -> if story identifiers are missing, fallback postId = videoId.
• content + multiple images + 1 video -> no video-id fallback; requires story identifiers.

Create Reel

• only video -> returns postId from story when available; fallback postId = videoId.
• text + video -> same behavior as above.

postIdSource values:

• story: post id returned from story identifiers.
• video_fallback: fallback from uploaded video id.

Error Shape

All services return either:

• { success: true, data: ... }
• { success: false, error: { message, raw? } }

Example:

{
  success: false,
  error: {
    message: 'There was a problem with this request. Try again later.',
    raw: unknown
  }
}

Development

bun run typecheck
bun run lint
bun test

Security Notes

• Do not commit real access tokens.
• Use environment variables for all credentials.
• Revoke test tokens after validation.