@tabsircg/fb-sdk 1.2.1 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tabsir Ahammed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,76 +1,433 @@
 # @tabsircg/fb-sdk
 
-A strongly-typed, modern TypeScript SDK for the Facebook Graph API (v25.0). It provides a fluent, resource-based interface with automatic `camelCase` ↔ `snake_case` transformation, seamless request batching, and an advanced type-safe field selector system that mimics GraphQL.
+A small, strongly-typed Facebook Graph API SDK for Node.js.
 
-## Tech Stack
-- **TypeScript** (v5.9.3) - Core language and advanced type system
-- **Axios** (v1.13.6) - HTTP client for interacting with the Graph API
-- **form-data** (v4.0.5) - For handling multipart/form-data (used in batching and media uploads)
-- **dotenv** (v17.3.1) - Environment variable management
-- **tsx** (v4.21.0) - For rapid development and execution of TypeScript files
+It started as the Facebook layer for a scheduling tool (Scheduly) and was extracted as a standalone package. The goal is a thin, predictable wrapper around the Graph API — not a kitchen-sink client. **It currently covers a focused subset of the Graph API.** More surface area will land over time; see [Coverage](#coverage).
 
-## Environment Variables
+> Status: early. The published version is `1.2.x`. The public shape (resource factories, `BatchableRequest`, field selectors) is stable enough to use, but minor versions may still tighten types.
 
-No required environment variables are hardcoded into the SDK itself. However, to interact with the Facebook Graph API, you must supply a valid Access Token when initializing the client wrapper. 
+---
 
-For development (`npm run dev`), you likely need to configure your `.env` file with a token to test against `src/temp/test.ts` (though `dotenv` usage is up to the consumer).
+## Highlights
 
-## Scripts
+- **Declarative field selection, fully typed.** The shape you await is exactly the shape you asked for — no `any`, no over-fetching, no manual type narrowing.
+- **One primitive: `BatchableRequest<T>`.** Every Graph call returns a thenable that doubles as a batch sub-request. The same value can be `await`-ed directly or passed into `sdk.batch([...])`.
+- **Automatic camelCase ↔ snake_case** at both runtime and type level. You write `createdTime`, the API sees `created_time`, you await `createdTime` again.
+- **Native batch API** with automatic chunking past Facebook's 50-request limit.
+- **First-class webhooks.** Facebook + Instagram webhooks normalized into one typed `onEvent` stream, plus an in-memory and a Redis store for store-accelerated comment fan-out.
+- **Async upload helpers** for videos, reels, and images — including the 3-phase reel upload session, status polling, and 504 recovery.
+- **Typed error hook.** An optional `onError` reports a strictly-typed `FacebookError` — a discriminated union you narrow on `.category`, with a `raw` escape hatch — for every failed request and batch sub-response. Observational: it never changes what's thrown or returned.
 
-| Command | Description |
-| :--- | :--- |
-| `npm run build` | Compiles the TypeScript source code to JavaScript ES2022 format inside the `dist/` directory. |
-| `npm run dev` | Runs the scratchpad/test file located at `src/temp/test.ts` using `tsx`. Useful for local testing. |
-| `npm run prepublishOnly` | Automatically runs `npm run build` prior to publishing the package to npm. |
+---
 
-## Quick Start
+## Install
 
-```typescript
-import { createFbSdk } from '@tabsircg/fb-sdk';
+```bash
+npm install @tabsircg/fb-sdk
+# or
+pnpm add @tabsircg/fb-sdk
+```
+
+Node 18+ recommended (the package is ESM and ships native ESM output).
+
+The SDK pins **Graph API v25.0**.
+
+---
+
+## Quick start
+
+```ts
+import { createFbSdk } from "@tabsircg/fb-sdk";
+
+const sdk = createFbSdk()(process.env.FB_ACCESS_TOKEN!);
+
+// Fetch the current user (the token's owner)
+const me = await sdk.me.get({ id: true, name: true, picture: true });
+//    ^? { id: string; name: string; picture: { data: PictureData } }
+
+// List the pages the user manages
+const pages = await sdk.me.accounts({
+  fields: { id: true, name: true, accessToken: true },
+});
+
+// Fetch a single post with nested comments and reactions
+const post = await sdk.post("123_456").get({
+  id: true,
+  message: true,
+  reactions: { summary: true },
+  comments: {
+    fields: { id: true, message: true, from: { id: true, name: true } },
+    options: { limit: 25 },
+  },
+});
+
+// Update a comment
+await sdk.comment("789").update({ message: "edited" });
+```
+
+Every call above is a `BatchableRequest<T>`. Each can be `await`-ed directly, *or* you can drop them into a batch:
+
+```ts
+const [postRes, commentsRes] = await sdk.batch([
+  sdk.post("123_456").get({ id: true, message: true }),
+  sdk.page("me").comments.list({ fields: { id: true, message: true } }),
+]);
+
+if (postRes.status === 200) {
+  console.log(postRes.data.message);
+}
+```
+
+---
+
+## Coverage
+
+What ships today:
+
+| Area      | Resource                                    | Operations                                                          |
+| --------- | ------------------------------------------- | ------------------------------------------------------------------- |
+| User      | `sdk.me`                                    | `get`, `accounts` (list managed pages)                              |
+| Page      | `sdk.page(id).posts`                        | `list`                                                              |
+| Page      | `sdk.page(id).videos` / `.reels`            | `list`, `publish` (with thumbnail + status polling)                 |
+| Page      | `sdk.page(id).images`                       | `publish`                                                           |
+| Page      | `sdk.page(id).comments`                     | `list` — aggregated across recent posts, store-accelerated          |
+| Page/Post | `.insights`                                 | `list` — typed metrics → `{ timeSeries, total \| snapshot }`        |
+| Post      | `sdk.post(id)`                              | `get`, `expire`, `comments`, `insights`                             |
+| Comment   | `sdk.comment(id)`                           | `get`, `update`, `delete`, `like`, `unlike`, `reply`, `replies`     |
+| Batch     | `sdk.batch`                                 | Up to 50 per request, auto-chunked                                  |
+| Webhook   | `createWebhookHandler`                      | `handleVerify`, `handleEvent` — signature-verified, typed `onEvent` dispatch (FB + IG) |
+| Stores    | `createMemoryStore`, `createRedisStore`     | In-process and Redis sorted-set backed                              |
+
+Instagram is a **separate SDK** — `createInstagramSdk()(igToken)` — talking to `graph.instagram.com` (Instagram API with Instagram Login), fully decoupled from the Facebook token:
+
+| Area      | Resource                                    | Operations                                                          |
+| --------- | ------------------------------------------- | ------------------------------------------------------------------- |
+| Account   | `ig.account(id)`                            | `get`, `media` (publish/list), `insights`, `mentions`, `stories`, `tags` |
+| Media     | `ig.media(id)`                              | `get`, `insights`, `comments`, `setCommentEnabled`                  |
+| Comment   | `ig.comment(id)`                            | `get`, `reply`, `replies`, `hide`, `delete`                         |
+
+Not covered yet: ads, business management, leadgen retrieval, messenger, marketing API, app events. PRs welcome — see [Contributing](#contributing).
+
+---
+
+## Core concepts
+
+### 1. Field selectors
+
+Instead of building a Graph `fields=...` string by hand, you describe the shape you want as a plain object:
+
+```ts
+const post = await sdk.post("123").get({
+  id: true,
+  message: true,
+  comments: {
+    fields: { id: true, message: true },
+    options: { limit: 10, order: ORDER.NEWEST },
+  },
+});
+```
+
+- Leaves are `true`.
+- Plain object children (`{ summary: true }`) descend into nested fields.
+- **Collection** fields use `{ fields, options? }`. `options` becomes Graph's `.limit(N).order(...)` syntax.
+- Unknown keys are rejected at compile time. Selecting `id` does not give you `message` in the result type.
+
+The selector is converted to a Graph string by [`toGraphFields`](src/internal/utils.ts):
+
+```
+{ id: true, comments: { fields: { id: true }, options: { limit: 5 } } }
+→  "id,comments.limit(5){id}"
+```
+
+See [docs/type-system.md](docs/type-system.md) for the recursive types behind this (`FbFieldSelector`, `FbPickDeep`, `DeepStrict`, `Fields`).
+
+### 2. `BatchableRequest<T>` — one value, two uses
+
+Every method on a resource returns a `BatchableRequest<T>`. It carries:
+
+- `method` and `relative_url` — what the FB batch API needs to embed it in a batch.
+- `then` / `catch` — so `await req` Just Works.
+- `transform(fn)` — map the response in a way that survives batching.
+
+```ts
+const idOnly = sdk.post("123").get({ id: true }).transform((p) => p.id);
+//    ^? BatchableRequest<string>
+
+const id = await idOnly;                  // works
+const [{ data: id2 }] = await sdk.batch([idOnly]);  // also works
+```
+
+`transform` is the trick that makes `sdk.batch([...])` return typed, post-processed data — the same transform runs in both code paths. See [docs/batching.md](docs/batching.md).
+
+### 3. camelCase everywhere
+
+The SDK does case conversion in both directions, at both the runtime and the type level:
+
+- Outgoing params and bodies: `toSnakeObj` / `toSnakeFormData` / `toSnakeCase` convert your camelCase keys before they hit the wire.
+- Incoming responses: `toCamel` rewrites all keys recursively. The axios instance applies it as a global response transform.
+- At the type level: `KeysToCamel<T>` and `KeysToSnake<T>` recursively transform key strings using template literal types, so `FacebookPostRaw` (snake) and `FacebookPost` (camel) stay in sync from a single source of truth.
+
+```ts
+// You write:
+sdk.page("me").posts.list({ fields: { id: true, createdTime: true } });
+// Wire sees: fields=id,created_time
+// You await: { data: { id: string; createdTime: string }[]; paging: ... }
+```
+
+Keys starting with `_` are preserved by `KeysToCamel` (used for internal type-level markers like `_edgeOptions`).
+
+### 4. Batching
+
+```ts
+const results = await sdk.batch([
+  sdk.post("a").get({ id: true }),
+  sdk.post("b").get({ id: true, message: true }),
+  sdk.comment("c").like(),
+]);
 
-// 1. Initialize the SDK factory (optionally pass configuration like a Store)
-const sdkFactory = createFbSdk();
+// results is a tuple matching input order:
+// [
+//   { status: 200; data: { id: string } },
+//   { status: 200; data: { id: string; message: string } },
+//   { status: 200; data: LikeCommentResponse },
+// ]
+```
+
+- Up to 50 requests per HTTP call. Larger arrays are chunked transparently.
+- POSTs created from a JSON payload carry their body into the batch. FormData uploads can't be batched.
+- Each result is `{ status, data }`. Non-200 responses leave `data` as the raw body string; sub-requests Facebook timed out come back as `{ status: 0, data: null }`.
+- `includeHeaders` is opt-in.
+
+### 5. Page-level comment fan-out
+
+The `sdk.page(id).comments.list(...)` resource is the one place the SDK does something more than a 1:1 Graph call — it aggregates comments across multiple posts. There are two modes:
+
+- **Store-backed** (recommended): pass a `Store` in `createFbSdk({ store })` and run the webhook handler. The store remembers which posts had recent comment activity; `list({ options: { since } })` only fetches comments from those posts.
+- **On-demand**: no store. The SDK pulls the latest posts on the page (`createFbSdk({ postsLimit })`, default 50, max 100) and fans out comments across them.
+
+Pagination uses a base64url-encoded cursor that bundles per-post cursors so the caller sees a single opaque `after` token. See [docs/webhooks-and-stores.md](docs/webhooks-and-stores.md).
+
+---
 
-// 2. Instantiate the client with a Page or User Access Token
-const sdk = sdkFactory("EAAGYourAccessTokenHere...");
+## Webhooks
 
-async function run() {
-  // Fetch a page's recent posts, selecting specific fields
-  const posts = await sdk.page("PAGE_ID").posts.list({
-    fields: {
-      id: true,
-      message: true,
-      createdTime: true
-    },
-    options: {
-      limit: 5
+```ts
+import express from "express";
+import {
+  createFbSdk,
+  createMemoryStore,
+  createWebhookHandler,
+} from "@tabsircg/fb-sdk";
+
+const store = createMemoryStore();
+const sdk = createFbSdk({ store });
+
+const webhook = createWebhookHandler({
+  verifyToken: process.env.FB_VERIFY_TOKEN!,
+  appSecret: process.env.FB_APP_SECRET!,
+  store, // optional — auto-records FB Page comment activity for store-accelerated reads
+  onEvent: async (event) => {
+    switch (event.type) {
+      case "comment.added":
+        // event.platform: "facebook" | "instagram" — narrow for the differing fields
+        if (event.platform === "instagram") {
+          await notify(event.mediaId, event.commentId, event.text);
+        } else {
+          await notify(event.postId, event.commentId, event.text);
+        }
+        break;
+      case "mention.created":
+        await flagMention(event);
+        break;
+      // comment.edited | comment.removed | comment.hidden | comment.unhidden
+      // post.published | reaction.added | reaction.removed
+      // review.created | review.updated | unknown
     }
-  });
+  },
+});
+
+const app = express();
+app.use(express.json({ verify: (req, _res, buf) => ((req as any).rawBody = buf) }));
+
+app.get("/webhook", webhook.handleVerify);
+app.post("/webhook", webhook.handleEvent);
+```
+
+The handler:
+
+- Verifies the `X-Hub-Signature-256` HMAC against `appSecret` (timing-safe), responds `200` immediately (Meta retries otherwise), then processes in the background.
+- Parses **Facebook and Instagram** payloads — including both Instagram login shapes (flat `field`/`value` and nested `changes[]`) and the `from`/`sender_*` author variants — into one normalized, camelCase `WebhookEvent` union. Switch on `event.type`, narrow on `event.platform`.
+- Delivers anything not modeled (DMs/messaging, `live_comments`, `story_insights`) as an `unknown` event with the original payload on `event.raw` — captured, never dropped.
+- If a `store` is supplied, Facebook Page comment-adds are recorded automatically (`recordActivity`) so store-accelerated reads keep working — independent of `onEvent`.
+- Routes background failures (store outages, a throwing `onEvent`) to the optional `onError` callback instead of crashing after the response is sent.
+
+**Event types:** `comment.added` · `comment.edited` · `comment.removed` · `comment.hidden` · `comment.unhidden` · `post.published` · `reaction.added` · `reaction.removed` · `mention.created` · `review.created` · `review.updated` · `unknown`.
+
+Then your reader uses the same store:
+
+```ts
+// Only hits posts that had comments after `since`
+const comments = await sdk.page(pageId).comments.list({
+  fields: {
+    id: true,
+    message: true,
+    post: { id: true, message: true, picture: true },
+  },
+  options: { since: Date.now() - 24 * 60 * 60 * 1000 },
+});
+```
+
+For multi-process deployments use the Redis store:
+
+```ts
+import Redis from "ioredis";
+import { createRedisStore } from "@tabsircg/fb-sdk";
+
+const redis = new Redis(process.env.REDIS_URL!);
+const store = createRedisStore(redis);
+```
+
+`createRedisStore` accepts anything matching the `RedisLike` interface — `ioredis`, `node-redis` v4 with a thin adapter, or your own mock. It uses `ZADD GT` (Redis ≥ 6.2) so out-of-order webhook deliveries can't move activity timestamps backwards.
+
+---
+
+## Error handling
+
+Pass an `onError` hook to `createFbSdk`. It runs after a response is received but **before** it is returned or thrown, whenever an error is detected — on direct requests *and* on individual batch sub-responses. It is purely observational: registering it never changes what the SDK throws or returns.
 
-  console.log("Recent posts:", posts.data);
+```ts
+import { createFbSdk } from "@tabsircg/fb-sdk";
 
-  // Example: Publish a new image
-  const publishTarget = await sdk.page("PAGE_ID").images.publish({
-    url: "https://example.com/image.png",
-    message: "Hello world!"
-  });
-  
-  console.log("Published Post ID:", publishTarget.postId);
+const sdk = createFbSdk({
+  // `ctx` identifies the failing call: { method, relativeUrl, accessToken, source }
+  onError: (err, ctx) => {
+    switch (err.category) {
+      case "auth": // token expired/revoked — ctx.accessToken is the page/channel key
+        markChannelRevoked(ctx.accessToken);
+        break;
+      case "rate_limit": // back off; usage headers say roughly for how long
+        logger.warn("throttled", err.usage?.appUsage);
+        break;
+      case "network": // timeout / DNS / transport — usually retryable
+        metrics.increment("fb.network_error");
+        break;
+      default:
+        logger.warn({ trace: err.traceId, call: `${ctx.method} ${ctx.relativeUrl}` }, err.message);
+    }
+  },
+})(token);
+```
+
+The hook receives two arguments: the typed error, and a `context` (`{ method, relativeUrl, accessToken, source }`) identifying *which* call failed. `accessToken` is the call's own token — for a multi-page app it's the unique key to the page/channel, so an `auth` error tells you exactly which channel to mark revoked. The second argument is optional to consume; `(err) => …` keeps working.
+
+Error types and classes live at the **`@tabsircg/fb-sdk/errors`** subpath — kept off the main entry to keep it uncluttered. Inside the hook, `err` and `ctx` are inferred, so you often don't need to import anything.
+
+The hook receives a strictly-typed `FacebookError` — a discriminated union you narrow on `.category`:
+
+| category        | when                                                            | retryable             |
+| --------------- | --------------------------------------------------------------- | --------------------- |
+| `auth`          | token expired/revoked/invalid (190, 102)                        | no — re-authenticate  |
+| `permission`    | missing permission or Page role (10, 3, 200–299, 190+492)       | no                    |
+| `rate_limit`    | throttled (4, 17, 32, 341, 613, 80000–80014); carries `usage`   | yes — back off        |
+| `invalid_param` | bad request / params / object (100, 506, 1609005, …)            | no                    |
+| `policy_block`  | integrity/abuse block (368)                                     | after a wait          |
+| `transient`     | temporary server error (1, 2, `is_transient`, or 5xx)           | yes — immediate       |
+| `unknown`       | a Graph envelope the SDK did not classify                       | inspect `code` / `raw`|
+| `network`       | no Graph envelope: timeout, DNS, non-JSON body, batch timeout   | usually               |
+
+Every error carries `category`, `httpStatus`, `isTransient`, and `raw` (the unprocessed, camelized envelope — the escape hatch). Graph-envelope errors (everything except `network`) also carry `code`, `type`, `message`, and optional `subcode`, `traceId`, `userTitle`, `userMessage`.
+
+Because Facebook's code space is open-ended and version-volatile, `code` and `subcode` stay plain `number` — never closed literal unions. Named constants are exported for the documented values:
+
+```ts
+import { FacebookErrorCode, FacebookAuthSubcode } from "@tabsircg/fb-sdk/errors";
+
+if (err.code === FacebookErrorCode.ACCESS_TOKEN && err.subcode === FacebookAuthSubcode.EXPIRED) {
+  // token expired
 }
+```
+
+The error classes are exported from `@tabsircg/fb-sdk/errors` for `instanceof` checks — `FacebookErrorBase` (any SDK error), `FacebookGraphError` (any error carrying a Graph envelope), and the concrete per-category classes (`FacebookAuthError`, `FacebookRateLimitError`, …).
+
+> The SDK still throws the original `AxiosError` for direct requests, and `sdk.batch([...])` still returns the same `{ status, data }` results — `onError` only *observes* them. A hook that throws or rejects is swallowed so it can never mask the underlying error.
 
-run().catch(console.error);
+---
+
+## Project layout
+
+```
+src/
+├── client.ts              Public entry — createFbSdk + re-exports
+├── errors.ts              Public error surface ("@tabsircg/fb-sdk/errors")
+├── httpClient.ts          Axios wrapper, request → BatchableRequest
+├── internal/
+│   ├── batchable.ts       createBatchableRequest, buildRelativeUrl
+│   ├── fetchers.ts        Page-level comment aggregator
+│   ├── poller.ts          poll() + pollVideoStatus / pollReelStatus
+│   ├── error.ts           FacebookUploadError + typed FacebookError model & hook
+│   └── utils.ts           toGraphFields (selector → Graph string)
+├── lib/
+│   └── transformCase.ts   toCamel / toSnake + KeysToCamel / KeysToSnake types
+├── resources/
+│   ├── PageResource.ts    videos, reels, images, posts (page sub-resources)
+│   ├── PostResource.ts    Single post, plus media node
+│   ├── UserResource.ts    /me, /me/accounts
+│   ├── InsightResource.ts Page + post insights with typed metric maps
+│   ├── createBatchResource.ts   batch([...]) with 50-chunking
+│   └── comment/
+│       ├── CommentResource.ts        Single-comment CRUD + reply
+│       └── PageCommentResource.ts    Cross-post aggregation
+├── store/
+│   ├── types.ts           Store interface
+│   ├── memory.ts          createMemoryStore
+│   └── redis.ts           createRedisStore + RedisLike interface
+├── webhook/
+│   ├── handler.ts         createWebhookHandler
+│   └── normalize.ts       raw payload → WebhookEvent[]
+└── types/
+    ├── shared.ts          FbFieldSelector, FbPickDeep, DeepStrict, BatchableRequest
+    ├── facebookpost.ts    FacebookPost / Comment / write-op params
+    ├── facebookpage.ts    FacebookPage
+    ├── facebookuser.ts    FacebookUser
+    ├── facebookmedia.ts   FacebookMedia + publish params
+    ├── facebookinsights.ts Page/Post metric maps, InsightResult shapes
+    └── webhook.ts         Raw envelope + normalized WebhookEvent union
+
+tests/
+├── unit/                  vitest runtime tests
+└── types/                 expect-type compile-time tests (typecheck only)
+```
+
+---
+
+## Development
+
+```bash
+pnpm install
+pnpm lint               # eslint (type-aware rules)
+pnpm test               # vitest — unit tests + compile-time type tests
+pnpm check              # lint + test
+pnpm build              # check, then tsc → dist/
 ```
 
-## Common Errors & Fixes
+- Unit tests: `tests/unit/*.test.ts` (vitest). `httpClientContract.test.ts` exercises the **real** axios pipeline via adapter injection — keep it green when touching `httpClient.ts` or `batchable.ts`.
+- Type tests: `tests/types/*.test-d.ts` — typecheck only, using `expect-type`. They include `@ts-expect-error` markers to assert that invalid usages fail to compile. They run as part of `pnpm test`.
+- Linting runs before anything ships: `build` (and therefore `prepublishOnly`) is `lint → test → tsc`.
+- `tsconfig.json` is on the strict end: `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, `noPropertyAccessFromIndexSignature`, `verbatimModuleSyntax` all on.
+
+---
+
+## Contributing
+
+Bug reports, type-system gotchas, and PRs for missing Graph resources are all welcome. A few rough guidelines:
+
+- Mirror the existing resource shape: a `createXResource({ http, id, config? })` factory returning typed methods that each produce a `BatchableRequest<T>`.
+- Type the raw API shape as a `*Raw` interface (snake_case) and export the camelCase view as `KeysToCamel<*Raw>`. This is how every type stays in sync without duplication.
+- Add a unit test under `tests/unit/` for runtime behaviour and a `.test-d.ts` under `tests/types/` for the type surface — especially `@ts-expect-error` cases for what *shouldn't* compile.
+- Don't add retry / rate-limit logic without discussion; the current direction is to leave retries to the caller. The typed errors expose what a retry layer would need — `category` (`rate_limit`/`transient`/`policy_block` are retryable), `isTransient`, and `FacebookRateLimitError.usage`.
 
-**FacebookUploadError**
-- *Symptom:* The SDK throws an error during a video or reel upload, typically containing a `FacebookMedia["status"]` payload.
-- *Fix:* This is an asynchronous processing error on Facebook's side. The SDK polls the status of uploads. Inspect the error message (extracted via `getProcessingError` in `poller.ts`) which might indicate unsupported codecs, file size limits exceeded, or temporary Facebook outages.
+---
 
-**Batching Issues ("API Error code 2/3")**
-- *Symptom:* `sdk.batch([ ...requests ])` fails with a confusing Graph API error.
-- *Fix:* Ensure all requests inside the batch call were invoked without `await`. A `BatchableRequest` triggers a standard HTTP call if awaited, but returns `{ method, relative_url }` otherwise which the `batch` method leverages.
+## License
 
-**Type errors on `fields` selector**
-- *Symptom:* TypeScript complains when selecting nested fields like `comments: { ... }`.
-- *Fix:* Verify that the nested property is defined as an object or `CollectionOf<T>` in the type definitions (`src/types/`). Ensure you use the exact camelCase keys for fields (e.g., `createdTime` instead of `created_time`).
+ISC.

package/dist/client.d.ts

@@ -1,7 +1,10 @@
-import { HttpClient } from "./httpClient.js";
-import { Store } from "./client.js";
+import { type HttpClient } from "./httpClient.js";
+import type { Store } from "./store/types.js";
+import type { FacebookErrorHook } from "./internal/error.js";
 export interface FbSdkConfig {
     store?: Store;
+    postsLimit?: number;
+    onError?: FacebookErrorHook;
 }
 export interface CreateResourceParams {
     http: HttpClient;
@@ -17,7 +20,7 @@ export declare function createFbSdk(config?: FbSdkConfig): (accessToken: string)
             create: import("./resources/comment/CommentResource.js").CreateComment;
         };
         insights: {
-            list: <F extends import("./client.js").FbFieldSelector<{
+            list: <F extends import("./types/shared.js").FbFieldSelector<{
                 postMediaView: {
                     name: "post_media_view";
                     values: {
@@ -295,7 +298,7 @@ export declare function createFbSdk(config?: FbSdkConfig): (accessToken: string)
                         endTime?: string;
                     }[];
                 };
-            }, 10>>(query: import("./client.js").InsightQuery<{
+            }, 10>>(query: import("./types/facebookinsights.js").InsightQuery<{
                 postMediaView: {
                     name: "post_media_view";
                     values: {
@@ -573,7 +576,7 @@ export declare function createFbSdk(config?: FbSdkConfig): (accessToken: string)
                         endTime?: string;
                     }[];
                 };
-            }, F>) => import("./client.js").BatchableRequest<import("./client.js").InsightResponse<{
+            }, F>) => import("./types/shared.js").BatchableRequest<import("./types/facebookinsights.js").InsightResponse<{
                 postMediaView: {
                     name: "post_media_view";
                     values: {
@@ -870,10 +873,10 @@ export declare function createFbSdk(config?: FbSdkConfig): (accessToken: string)
             list: import("./resources/PageResource.js").ListPosts;
         };
         comments: {
-            list: import("./resources/comment/PageCommentResouorce.js").GetPageComments;
+            list: import("./resources/comment/PageCommentResource.js").GetPageComments;
         };
         insights: {
-            list: <F extends import("./client.js").FbFieldSelector<{
+            list: <F extends import("./types/shared.js").FbFieldSelector<{
                 pageMediaView: {
                     name: "page_media_view";
                     values: {
@@ -1136,7 +1139,7 @@ export declare function createFbSdk(config?: FbSdkConfig): (accessToken: string)
                         endTime?: string;
                     }[];
                 };
-            }, 10>>(query: import("./client.js").InsightQuery<{
+            }, 10>>(query: import("./types/facebookinsights.js").InsightQuery<{
                 pageMediaView: {
                     name: "page_media_view";
                     values: {
@@ -1399,7 +1402,7 @@ export declare function createFbSdk(config?: FbSdkConfig): (accessToken: string)
                         endTime?: string;
                     }[];
                 };
-            }, F>) => import("./client.js").BatchableRequest<import("./client.js").InsightResponse<{
+            }, F>) => import("./types/shared.js").BatchableRequest<import("./types/facebookinsights.js").InsightResponse<{
                 pageMediaView: {
                     name: "page_media_view";
                     values: {
@@ -1679,7 +1682,7 @@ export declare function createFbSdk(config?: FbSdkConfig): (accessToken: string)
         accounts: import("./resources/UserResource.js").ListAccounts;
     };
     http: HttpClient;
-    batch: <const T extends readonly import("./client.js").BatchSubRequest[]>(requests: T, options?: import("./resources/createBatchResource.js").BatchRequestOptions) => Promise<{ -readonly [K in keyof T]: T[K] extends import("./client.js").BatchableRequest<infer R> ? {
+    batch: <const T extends readonly import("./types/shared.js").BatchSubRequest[]>(requests: T, batchOptions?: import("./resources/createBatchResource.js").BatchRequestOptions) => Promise<{ -readonly [K in keyof T]: T[K] extends import("./types/shared.js").BatchableRequest<infer R> ? {
         status: number;
         data: R;
     } : {
@@ -1687,15 +1690,21 @@ export declare function createFbSdk(config?: FbSdkConfig): (accessToken: string)
         data: any;
     }; }>;
 };
+export { createInstagramSdk } from "./instagramClient.js";
+export type { InstagramSdkConfig } from "./instagramClient.js";
 export { createMemoryStore } from "./store/memory.js";
 export { createRedisStore } from "./store/redis.js";
 export { createWebhookHandler } from "./webhook/handler.js";
+export { ORDER } from "./types/shared.js";
+export type { HttpClient } from "./httpClient.js";
 export type { Store } from "./store/types.js";
 export type { RedisLike } from "./store/redis.js";
 export type { WebhookHandlerConfig } from "./webhook/handler.js";
 export type { PageCommentConfig } from "./resources/comment/CommentResource.js";
 export type * from "./types/facebookinsights.js";
 export type * from "./types/facebookmedia.js";
+export type * from "./types/instagram.js";
+export type * from "./types/instagraminsights.js";
 export type * from "./types/facebookpage.js";
 export type * from "./types/facebookpost.js";
 export type * from "./types/facebookuser.js";

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -6,18 +6,20 @@ import { createCommentResource } from "./resources/comment/CommentResource.js";
 import { createBatchResource } from "./resources/createBatchResource.js";
 export function createFbSdk(config = {}) {
     return (accessToken) => {
-        const http = createHttpClient(accessToken);
+        const http = createHttpClient(accessToken, { onError: config.onError });
         return {
             post: (postId) => createPostResource({ http, id: postId, config }),
             page: (pageId) => createPageResource({ http, id: pageId, config }),
             comment: (commentId) => createCommentResource({ http, id: commentId, config }),
             me: createUserResource({ http, config, id: "me" }),
             http,
-            batch: createBatchResource(http),
+            batch: createBatchResource(http, { onError: config.onError }),
         };
     };
 }
+export { createInstagramSdk } from "./instagramClient.js";
 export { createMemoryStore } from "./store/memory.js";
 export { createRedisStore } from "./store/redis.js";
 export { createWebhookHandler } from "./webhook/handler.js";
+export { ORDER } from "./types/shared.js";
 //# sourceMappingURL=client.js.map