Interact FB

A robust, developer-friendly client for Facebook Graph API. Works in modern browsers with the Facebook JS SDK and in Node.js when you provide an access token.

• Easy token handling: pass a token or let the SDK resolve it automatically
• Strong error handling: consistent custom error classes and retry logic
• Sensible defaults with opt-in overrides

Installation

npm install interact-fb

Quick start

import { initFacebookSdk, getProfile } from 'interact-fb';

await initFacebookSdk('YOUR_APP_ID');
const me = await getProfile();
console.log(me); // { id, name, email?, picture?, ... }

If you already have an access token (e.g., server-side), pass it explicitly to any function instead of relying on the SDK.

import { getPages } from 'interact-fb';

const pages = await getPages('USER_ACCESS_TOKEN');

Which function to use when

• You are building a browser app and need the FB SDK: use initFacebookSdk, then getSDKStatus or isSDKReady/waitForSDK.
• You need the user to log in and grant permissions: use loginWithFacebook (pass scopes you need).
• You just want to know if a user is logged in or get their token: use isLoggedIn and getAccessToken.
• You need the current user's profile:
  • Basic info only: getBasicProfile
  • Custom fields: getProfile({ fields: 'id,name,email,picture' })
  • Profile picture: getProfilePicture
• You need the pages a user manages or info about a page:
  • List managed pages: getPages
  • Get one page by id from managed list: getManagedPage
  • Check whether a user manages a page: managesPage
  • Fetch public page info: getPageInfo
  • Pages with extra counts (insights-like fields): getPagesWithInsights
• You are working with posts and engagement:
  • Recent page posts: getPagePosts
  • Full post details: getPostDetails
  • Post comments: getPostComments (or shortcut getComments)
  • Post likes: getPostLikes (or shortcut getLikes)
  • Posts with embedded comments/likes in one call: getPagePostsWithEngagement
• You are working with lead forms:
  • List lead forms for a page: getLeadForms
  • Only active forms: getActiveLeadForms
  • Form details (questions, counts): getLeadFormDetails
  • Forms across multiple pages: getLeadFormsFromMultiplePages
  • Quick counts/summary: getLeadFormStats
• You are working with leads:
  • Fetch page-by-page: getLeads
  • Fetch all (auto-pagination): getAllLeads
  • Fetch from many forms: getLeadsFromMultipleForms
  • Recent leads window: getRecentLeads({ hours })
  • Developer-friendly shape (flatten field_data): getFormattedLeads
  • Export to CSV: getLeadsAsCSV
  • Computed stats: getLeadStats
• You need to handle permissions:
  • Proactively request during login: use loginWithFacebook(scopes)
  • Inspect current scopes if needed: getAllRequiredPermissions, getAllPermissions, fetchAllPermissions
  • If an API call fails with PERMISSION_DENIED, prompt the user to re-login with required scopes
• You need maximum control over the Graph API:
  • Single request: graphAPI
  • Many requests together: batchGraphAPI

Notes:

• In the browser, if you don’t pass a token, functions auto-resolve it from the SDK (user must be logged in).
• On the server, always pass a user or page token explicitly.

Errors

All functions may throw custom error types:

• FacebookSDKError
• FacebookAuthError
• FacebookAPIError
• FacebookPermissionError
• FacebookTimeoutError

Errors are automatically logged to console in development mode only after all retry attempts fail. You can also import handleError and logError for consistent processing.

Configuration

import { setConfig, getConfig, resetConfig, DEFAULT_CONFIG } from 'interact-fb';

setConfig({ version: 'v23.0', timeout: 15000 });

Config defaults include:

• version, timeout, retryAttempts, retryDelay
• defaultFields: profile, pages, posts, leadForms, leads
• defaultPermissions: basic, pages, leads, posts

SDK Initialization

initFacebookSdk(appId, options?)

Initializes the FB JS SDK in the browser.

• Returns: Promise<{ sdk: 'initialized'|'already_loaded', version, appId, options }>
• Throws: FacebookSDKError on load/init failures

await initFacebookSdk('APP_ID', { xfbml: true, locale: 'en_US' });

getSDKStatus()

• Returns: { isReady, version, appId, options } | null

Auth

loginWithFacebook(scope?, options?)

Prompts login via the SDK. scope can be string or string[].

• Returns: Promise<{ accessToken, expiresIn, userID, grantedScopes[], deniedScopes[], status }>
• Throws: FacebookSDKError, FacebookAuthError

logoutFromFacebook()

• Returns: Promise

getLoginStatus()

• Returns: Promise<{ status: 'connected'|'not_authorized'|'unknown', authResponse? }>

isLoggedIn(), getAccessToken()

• Returns: Promise or Promise<string|null>

Graph API

graphAPI(endpoint, accessToken, method='GET', params={}, options={})

Low-level client with retries and timeouts.

• Returns: Promise (raw Graph response)
• Throws: FacebookAPIError and friends

batchGraphAPI(requests, accessToken, options?)

• Returns: Promise<Array>

Profile

getProfile(accessToken?, options?)

Fetches current user profile.

• Options: { fields=DEFAULT.profile, apiOptions }
• Returns: Promise