facebook-nodejs-business-sdk

The Facebook Business SDK for Node.js is Meta’s official client library for the Marketing API, bundling ad account management, campaign and ad set creation, creative uploads, and the Conversions API into a single isomorphic package that runs in both Node.js and the browser. Every Graph API node (AdAccount, Campaign, AdSet, Ad, Page, and hundreds more) is generated as a class under src/objects, giving callers property-style field access and CRUD helper methods instead of hand-built REST calls.

Beyond core Marketing API coverage, the SDK includes a dedicated ServerSideUtils module for hashing and normalizing user data (email, phone, name) before sending server-side Conversions API events, plus a Cursor class that transparently paginates edge results. It ships as CommonJS, AMD, UMD, and browser-global builds via a Babel/Gulp/Rollup toolchain, so the same codebase can be required in a backend service or bundled for client-side use.

What You Get

• A FacebookAdsApi client class that centralizes access token handling, request signing, and debug logging for every Graph API call
• Auto-generated node classes (AdAccount, Campaign, AdSet, Ad, AdCreative, Page, and 1,000+ others) with property-style field access and built-in create/read/update/delete methods
• A Cursor class that wraps paginated edge responses so you can iterate results without manually following paging.next links
• ServerSideUtils helpers for normalizing and SHA-256 hashing PII (email, phone, name) before submitting Conversions API events
• Batch request support via FacebookAdsApiBatch for grouping multiple Graph API calls into one HTTP round trip
• Isomorphic distribution builds (CommonJS, AMD, UMD, browser globals) generated from a single source tree via the Gulp/Rollup build pipeline

Common Use Cases

• Programmatically creating and managing ad campaigns, ad sets, and ads across Facebook, Instagram, and Audience Network placements
• Sending server-side Conversions API events to improve attribution when browser-side Pixel tracking is blocked or unreliable
• Building internal tooling or agency dashboards that read ad account insights, spend, and performance metrics via the Graph API
• Bulk-uploading ad creatives (images, videos, carousel assets) through the AdCreative and AdImage/AdVideo node classes
• Automating audience management, including custom audience creation and updates for retargeting campaigns

Under The Hood

Architecture The SDK is built around a small core (FacebookAdsApi in src/api.js, Http in src/http.js, Cursor in src/cursor.js) that every generated node class extends via AbstractCrudObject and AbstractObject in src/abstract-crud-object.js and src/abstract-object.js. Each of the roughly one thousand files under src/objects defines one Graph API node as a class with a frozen Fields enum and inherited CRUD methods, so adding support for a new API object is a mechanical, generated task rather than hand-written integration code; FacebookAdsApi.call() is the single choke point all requests pass through, meaning auth, debug logging, and error wrapping (FacebookRequestError) live in one place despite the large surface area.

Tech Stack The library targets both Node.js and the browser: axios handles server-side HTTP while Http.xmlHttpRequest provides a browser fallback, and the source is written in Flow-typed ES6/ES2015 (@flow annotations throughout) transpiled with a Babel 6 toolchain (babel-preset-env, babel-preset-flow) and bundled with Gulp and Rollup into CommonJS, AMD, UMD, and browser-global distributions. Small focused dependencies (js-sha256 for hashing, email-validator, iso-3166-1, currency-codes, mixwith for mixins) support the Conversions API and field-validation helpers without pulling in a heavier framework.

Code Quality Tests live under __tests__ and run via Jest, covering the ServerSideUtils hashing/normalization logic, batch processing, and custom-data/event-request builders with focused unit tests rather than end-to-end API coverage; the generated src/objects classes themselves are not independently unit-tested since they are thin, mechanically-produced wrappers. Flow provides static type checking (npm run flow) alongside semistandard/ESLint linting, and GitHub Actions CI runs the Flow check across multiple Node versions on every push and PR.

What Makes It Unique Unlike hand-maintained API clients, this SDK’s near-complete one-class-per-node coverage of the Marketing/Business API graph is machine-generated from Meta’s own API schema, letting it track new ad objects, fields, and API versions release after release with comprehensive breadth that a manually written client for a surface this large would struggle to sustain. Bundling Conversions API hashing utilities directly alongside the ad-management classes is also distinctive, sparing integrators from writing their own PII-normalization logic to match Meta’s server-side event-matching requirements.