@promobase/meta-business-sdk-ts 0.0.1

package/README.md

@@ -0,0 +1,168 @@
+# @promobase/meta-business-sdk-ts
+
+> Type-safe TypeScript replacement for [`facebook-nodejs-business-sdk`](https://github.com/facebook/facebook-nodejs-business-sdk)
+
+Fully typed SDK for the **Meta (Facebook) Marketing API**, auto-generated from the official [API specs](https://github.com/facebook/facebook-business-sdk-codegen). Every Graph API object, edge, field, and parameter is typed — wrong field names, missing required params, and bad enum values fail at **compile time**, not runtime.
+
+## Features
+
+- **994 typed API objects** — AdAccount, Campaign, AdSet, Ad, Page, Business, and 988 more
+- **Field-level type narrowing** — request `["id", "name"]` and get `Pick<CampaignFields, "id" | "name">`, not the full object
+- **314 typed node accessors** — `api.adAccount(id)`, `api.campaign(id)`, `api.adSet(id)`, etc.
+- **Async-iterable cursors** — `for await` over paginated results with `.toArray()` and `.take(n)`
+- **Typed create/update params** — required vs optional params enforced at compile time
+- **Zero runtime dependencies** — native `fetch`, no axios/node-fetch/got
+- **Drop-in replacement** for `facebook-nodejs-business-sdk` with actual type safety
+
+## Installation
+
+```bash
+bun add @promobase/meta-business-sdk-ts
+# or
+npm install @promobase/meta-business-sdk-ts
+# or
+pnpm add @promobase/meta-business-sdk-ts
+# or
+yarn add @promobase/meta-business-sdk-ts
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from "@promobase/meta-business-sdk-ts";
+
+const api = createClient({
+  accessToken: process.env.META_ACCESS_TOKEN!,
+});
+
+// List campaigns — fully typed, auto-paginated
+for await (const campaign of api.adAccount("act_123").campaigns.list({
+  fields: ["id", "name", "status", "daily_budget"],
+})) {
+  console.log(campaign.name);        // string
+  console.log(campaign.daily_budget); // string
+}
+```
+
+## Usage
+
+### Read an Ad Account
+
+```typescript
+const account = await api.adAccount("act_123").get({
+  fields: ["id", "name", "currency", "timezone_name", "amount_spent"],
+});
+
+console.log(account.name);         // string
+console.log(account.currency);     // string
+console.log(account.amount_spent); // string
+// account.balance                  // TS error — not in requested fields
+```
+
+### Create a Campaign
+
+```typescript
+await api.adAccount("act_123").campaigns.create({
+  name: "Summer Sale 2025",       // required
+  objective: "OUTCOME_SALES",     // required
+  special_ad_categories: [],      // required
+  status: "PAUSED",               // optional
+  daily_budget: 5000,             // optional
+});
+```
+
+### Update and Delete
+
+```typescript
+await api.campaign("123456").update({
+  name: "Summer Sale 2025 — Updated",
+  status: "ACTIVE",
+});
+
+await api.campaign("123456").delete();
+```
+
+### Pagination
+
+```typescript
+// Auto-pagination with for-await
+for await (const ad of api.adAccount("act_123").ads.list({
+  fields: ["id", "name", "status"],
+})) {
+  console.log(ad.name);
+}
+
+// Manual page-by-page
+const cursor = api.adAccount("act_123").campaigns.list({ fields: ["id", "name"] });
+const page1 = await cursor.next(); // { data: [...], hasNext: true }
+const page2 = await cursor.next(); // { data: [...], hasNext: false }
+
+// Collect all
+const all = await api.adAccount("act_123").campaigns.list({ fields: ["id"] }).toArray();
+
+// Take first N
+const first10 = await api.adAccount("act_123").campaigns.list({ fields: ["id"] }).take(10);
+```
+
+### Error Handling
+
+```typescript
+import { createClient, FacebookApiError } from "@promobase/meta-business-sdk-ts";
+
+try {
+  await api.campaign("invalid").get({ fields: ["id"] });
+} catch (err) {
+  if (err instanceof FacebookApiError) {
+    console.log(err.message);    // "Invalid OAuth access token."
+    console.log(err.code);       // 190
+    console.log(err.subcode);    // 463
+    console.log(err.type);       // "OAuthException"
+    console.log(err.fbtrace_id); // "AbC123xYz"
+  }
+}
+```
+
+### All Node Accessors
+
+```typescript
+api.adAccount(id)        // AdAccount — campaigns, ads, adsets, adcreatives, ...
+api.campaign(id)         // Campaign — ads, adsets, insights, copies, ...
+api.adSet(id)            // AdSet — ads, insights, ...
+api.ad(id)               // Ad — adcreatives, insights, ...
+api.adCreative(id)       // AdCreative
+api.page(id)             // Page — posts, photos, videos, ...
+api.business(id)         // Business — ad accounts, pages, ...
+api.customAudience(id)   // CustomAudience
+api.productCatalog(id)   // ProductCatalog — products, feeds, ...
+// ... 314 typed accessors total
+api.client               // Raw ApiClient for advanced use
+```
+
+## Migrating from facebook-nodejs-business-sdk
+
+| Before (untyped) | After (typed) |
+|---|---|
+| `new AdAccount(id).getCampaigns(fields, params)` | `api.adAccount(id).campaigns.list({ fields, params })` |
+| `new AdAccount(id).createCampaign(fields, params)` | `api.adAccount(id).campaigns.create(params)` |
+| `new Campaign(id).update(fields, params)` | `api.campaign(id).update(params)` |
+| `new Campaign(id).delete(fields, params)` | `api.campaign(id).delete()` |
+| `params: Object` | `params: CampaignCreateParams` (typed) |
+| `fields: Array<string>` | `fields: (keyof CampaignFields)[]` (autocomplete) |
+
+## How It Works
+
+Auto-generated from Meta's official [API spec files](https://github.com/facebook/facebook-business-sdk-codegen). A custom TypeScript codegen pipeline:
+
+1. Parses 994 JSON spec files describing every Graph API object
+2. Applies SDKCodegen.json patches (return type overrides, hidden fields, etc.)
+3. Resolves spec types to TypeScript (`list<map<string, string>>` → `Record<string, string>[]`)
+4. Detects circular imports via Tarjan's SCC algorithm
+5. Emits typed `.ts` files with interfaces, params, and node factory functions
+
+## Related
+
+Part of [`ad-platform-sdks`](https://github.com/promobase/ad-platform-sdks) — type-safe SDKs for Meta, TikTok, and Google ad platforms.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@promobase/meta-business-sdk-ts",
+  "version": "0.0.1",
+  "description": "Type-safe TypeScript SDK for the Meta (Facebook) Marketing API — fully typed Graph API client with auto-generated types for 994 API objects",
+  "keywords": [
+    "meta",
+    "facebook",
+    "meta-business-sdk",
+    "facebook-business-sdk",
+    "facebook-ads",
+    "meta-ads",
+    "facebook-marketing-api",
+    "meta-marketing-api",
+    "graph-api",
+    "facebook-graph-api",
+    "typescript",
+    "type-safe",
+    "typed",
+    "codegen",
+    "ads",
+    "advertising",
+    "ad-account",
+    "campaign",
+    "adset",
+    "sdk",
+    "api-client",
+    "business-sdk",
+    "facebook-nodejs-business-sdk",
+    "facebook-business-sdk-codegen"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/promobase/ad-platform-sdks",
+    "directory": "packages/meta-business-sdk"
+  },
+  "module": "src/generated/index.ts",
+  "main": "src/generated/index.ts",
+  "types": "src/generated/index.ts",
+  "type": "module",
+  "files": [
+    "src/generated/**/*.ts",
+    "src/errors.ts",
+    "src/pagination.ts",
+    "README.md"
+  ],
+  "scripts": {
+    "codegen": "bun src/codegen/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test tests/",
+    "build": "bun build src/generated/index.ts --outdir dist --target node",
+    "publish": "bun publish --access public"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@promobase/sdk-runtime": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,36 @@
+import { ApiError } from "@promobase/sdk-runtime";
+
+export class FacebookApiError extends ApiError {
+  readonly code: number;
+  readonly subcode: number | undefined;
+  readonly type: string;
+  readonly fbtrace_id: string;
+
+  constructor(opts: {
+    message: string; status: number; code: number;
+    subcode?: number; type: string; fbtrace_id: string;
+  }) {
+    super(opts.message, opts.status);
+    this.name = "FacebookApiError";
+    this.code = opts.code;
+    this.subcode = opts.subcode;
+    this.type = opts.type;
+    this.fbtrace_id = opts.fbtrace_id;
+  }
+
+  static fromResponse(status: number, body: unknown): FacebookApiError {
+    if (typeof body === "object" && body !== null && "error" in body &&
+        typeof (body as Record<string, unknown>).error === "object") {
+      const err = (body as { error: Record<string, unknown> }).error;
+      return new FacebookApiError({
+        message: typeof err.message === "string" ? err.message : "Unknown Facebook API error",
+        status,
+        code: typeof err.code === "number" ? err.code : 0,
+        subcode: typeof err.error_subcode === "number" ? err.error_subcode : undefined,
+        type: typeof err.type === "string" ? err.type : "Unknown",
+        fbtrace_id: typeof err.fbtrace_id === "string" ? err.fbtrace_id : "",
+      });
+    }
+    return new FacebookApiError({ message: "Unknown Facebook API error", status, code: 0, type: "Unknown", fbtrace_id: "" });
+  }
+}