Skip to content

Getting started

bun add @adgentic/meta-sdk

The package has no runtime dependencies. It needs a global fetch and WebCrypto, so it runs on Node 20+, Bun, Deno, Cloudflare Workers and other edge runtimes.

import { createClient } from '@adgentic/meta-sdk';
const fb = createClient({
accessToken: process.env.FB_TOKEN,
appSecret: process.env.FB_APP_SECRET, // optional: adds appsecret_proof to every call
});
const me = await fb.user('me').get({ fields: ['name'] });
const account = await fb.adAccount('act_123').get({ fields: ['name', 'currency', 'account_status'] });
console.log(account.name, account.currency);

The token is sent as a Bearer header. accessToken can also be a function, possibly async, that returns the token. It is called once per request, which is handy when tokens rotate:

declare const tokenStore: { current(): Promise<string> }; // your own token cache
const fb = createClient({ accessToken: async () => tokenStore.current() });
Option Description
accessToken A string, or a (possibly async) function that returns one.
appSecret Adds appsecret_proof (HMAC-SHA256 via WebCrypto).
version Graph API version. Defaults to the version the types were generated from (API_VERSION).
fetch Custom fetch implementation, for tests, proxies and instrumentation.
retry { maxRetries, baseDelayMs, maxDelayMs }, or false to disable retries. See Errors, retries & rate limits.
timeoutMs Timeout for each attempt.
headers Headers added to every request.
baseUrl / videoBaseUrl Default https://graph.facebook.com and https://graph-video.facebook.com.
onResponse Called after every HTTP response with status, timing and parsed rate-limit headers.
throttle { threshold, maxWaitMs }, or false. On by default: requests wait while reported rate-limit usage is at or above threshold percent. See proactive throttling.
onThrottle Called with { waitMs, scope, usage } before a request waits because of throttle.

fb.withOptions({ accessToken: otherToken }) returns a client that shares the setup but replaces some options, for example to act with a Page token.

  • Root accessors. There is one per node type: fb.adAccount(id), fb.campaign(id), fb.page(id), fb.igUser(id) and so on. fb.node('AdAccount', id) does the same by type name. The Post node is reached as fb.postNode(id), because fb.post() is the raw POST method.
  • Node operations. get({ fields, params }), update(params) and delete() exist only on node types that support them.
  • Edges. handle.<edge> gives list(), create(), delete(), and the rarer update() (PUT) and head(). Edge names are camelCase forms of the endpoint: adcreatives becomes adCreatives.
const campaigns = fb.adAccount('act_123').campaigns;
const { id } = await campaigns.create({
name: 'Spring sale',
objective: 'OUTCOME_SALES',
special_ad_categories: [],
status: 'PAUSED',
});
await fb.campaign(id!).update({ status: 'ACTIVE' });
await fb.campaign(id!).delete();

Every operation returns a lazy GraphRequest. Nothing is sent until you await it, and the result is memoized. The API reference lists every node, edge and parameter.

The client uses only fetch and WebCrypto, so it runs unchanged in a Worker. Create the client inside the handler, where env is available:

import { createClient, GraphApiError } from '@adgentic/meta-sdk';
interface Env {
FB_TOKEN: string;
FB_APP_SECRET: string;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const fb = createClient({ accessToken: env.FB_TOKEN, appSecret: env.FB_APP_SECRET, timeoutMs: 10_000 });
const accountId = new URL(request.url).searchParams.get('account') ?? 'act_123';
try {
const campaigns = await fb
.adAccount(accountId)
.campaigns.list({ fields: ['name', 'effective_status'], limit: 50 })
.toArray({ max: 200 });
return Response.json(campaigns);
} catch (error) {
if (error instanceof GraphApiError) {
return Response.json({ message: error.message, code: error.code }, { status: error.status });
}
throw error;
}
},
};

Meta SDK (@adgentic/meta-sdk) is an independent project by Adgentic. It is not affiliated with, endorsed by or sponsored by Meta Platforms, Inc. Meta, Facebook, Instagram, Threads and WhatsApp are trademarks of their respective owners.