@ariaflowagents/messaging-meta 0.8.1

package/README.md

@@ -0,0 +1,236 @@
+# @ariaflowagents/messaging-meta
+
+Meta platform clients (WhatsApp, Messenger, Instagram) for AriaFlow messaging. Each client implements the `PlatformClient` interface from `@ariaflowagents/messaging`.
+
+## Install
+
+```bash
+npm install @ariaflowagents/messaging-meta @ariaflowagents/messaging
+```
+
+## WhatsApp
+
+```ts
+import { createWhatsAppClient } from '@ariaflowagents/messaging-meta/whatsapp';
+
+const whatsapp = createWhatsAppClient({
+  accessToken: process.env.WHATSAPP_ACCESS_TOKEN!,
+  appSecret: process.env.META_APP_SECRET!,
+  phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
+  verifyToken: process.env.WHATSAPP_VERIFY_TOKEN!,
+});
+
+// Listen for messages
+whatsapp.onMessage(async (msg) => {
+  await whatsapp.markAsRead(msg.id);
+  await whatsapp.sendText(msg.from.phone!, `You said: ${msg.text}`);
+});
+
+// Mount webhook (Hono)
+app.route('/whatsapp', whatsapp.webhookRouter());
+```
+
+### Templates and Interactive Messages
+
+```ts
+import { buildTemplateSendPayload } from '@ariaflowagents/messaging-meta/whatsapp';
+
+// Template
+await whatsapp.sendTemplate('+1234567890', buildTemplateSendPayload({
+  name: 'order_confirmation',
+  language: { code: 'en_US' },
+  components: [{ type: 'body', parameters: [{ type: 'text', text: 'ORD-1234' }] }],
+}));
+
+// Buttons
+await whatsapp.sendInteractiveButtons('+1234567890', {
+  body: 'How can we help?',
+  buttons: [{ id: 'sales', title: 'Sales' }, { id: 'support', title: 'Support' }],
+});
+
+// List
+await whatsapp.sendListMessage('+1234567890', {
+  body: 'Select a department',
+  button: 'View Options',
+  sections: [{ title: 'Departments', rows: [{ id: 'eng', title: 'Engineering' }] }],
+});
+```
+
+### WhatsApp-Specific Methods
+
+| Method | Description |
+|---|---|
+| `sendText(to, text)` | Send text (auto-splits at 4096 chars) |
+| `sendMedia(to, media)` | Send image, video, audio, document, sticker |
+| `sendTemplate(to, template)` | Send approved template message |
+| `sendTextOrTemplate(to, opts)` | Send text if window open, template if closed |
+| `sendInteractiveButtons(to, msg)` | Send button message (max 3) |
+| `sendListMessage(to, list)` | Send list picker |
+| `sendCTAButton(to, cta)` | Send call-to-action URL button |
+| `sendInteractiveFlow(to, flow)` | Launch a WhatsApp Flow |
+| `sendReaction(to, messageId, emoji)` | React to a message |
+| `sendLocation(to, location)` | Send a location pin |
+| `sendContacts(to, contacts)` | Send contact cards |
+| `uploadMedia(file, options)` | Upload media, get `MediaHandle` |
+| `downloadMedia(mediaId)` | Download media by ID |
+| `markAsRead(messageId)` | Mark message as read |
+
+## Messenger
+
+```ts
+import { createMessengerClient } from '@ariaflowagents/messaging-meta/messenger';
+
+const messenger = createMessengerClient({
+  pageAccessToken: process.env.MESSENGER_PAGE_ACCESS_TOKEN!,
+  appSecret: process.env.META_APP_SECRET!,
+  pageId: process.env.MESSENGER_PAGE_ID!,
+  verifyToken: process.env.MESSENGER_VERIFY_TOKEN!,
+});
+
+messenger.onMessage(async (msg) => {
+  await messenger.sendText(msg.from.id, `Echo: ${msg.text}`);
+});
+```
+
+### Templates and Quick Replies
+
+```ts
+// Button template
+await messenger.sendButtonTemplate(psid, {
+  text: 'What would you like to do?',
+  buttons: [{ type: 'postback', title: 'Track Order', payload: 'TRACK' }],
+});
+
+// Generic template (carousel)
+await messenger.sendGenericTemplate(psid, {
+  elements: [{ title: 'Product A', subtitle: '$29.99', image_url: 'https://example.com/a.jpg' }],
+});
+
+// Quick replies
+await messenger.sendQuickReplies(psid, 'Choose one:', [
+  { content_type: 'text', title: 'Yes', payload: 'YES' },
+  { content_type: 'text', title: 'No', payload: 'NO' },
+]);
+```
+
+### Messenger-Specific Methods
+
+| Method | Description |
+|---|---|
+| `sendText(to, text)` | Send text (max 2000 chars) |
+| `sendMedia(to, media)` | Send image, video, audio, or file |
+| `sendButtonTemplate(to, template)` | Send button template (max 3 buttons) |
+| `sendGenericTemplate(to, template)` | Send carousel (max 10 elements) |
+| `sendQuickReplies(to, text, replies)` | Send quick reply buttons |
+| `sendSenderAction(to, action)` | Send typing_on, typing_off, mark_seen |
+| `getUserProfile(psid)` | Fetch user's name and profile picture |
+| `uploadMedia(file, options)` | Upload media for reuse |
+| `downloadMedia(mediaUrl)` | Download media by URL |
+
+## Instagram
+
+```ts
+import { createInstagramClient } from '@ariaflowagents/messaging-meta/instagram';
+
+const instagram = createInstagramClient({
+  accessToken: process.env.INSTAGRAM_ACCESS_TOKEN!,
+  appSecret: process.env.META_APP_SECRET!,
+  igId: process.env.INSTAGRAM_ACCOUNT_ID!,
+  verifyToken: process.env.INSTAGRAM_VERIFY_TOKEN!,
+});
+
+instagram.onMessage(async (msg) => {
+  await instagram.sendText(msg.from.id, `Thanks for your message!`);
+});
+```
+
+### Ice Breakers
+
+```ts
+// Set conversation starters
+await instagram.iceBreakers.set([
+  { question: 'What are your hours?', payload: 'HOURS' },
+  { question: 'Track my order', payload: 'TRACK' },
+]);
+
+// Get current ice breakers
+const breakers = await instagram.iceBreakers.get();
+
+// Delete all
+await instagram.iceBreakers.delete();
+```
+
+### Instagram-Specific Methods
+
+| Method | Description |
+|---|---|
+| `sendText(to, text)` | Send text (auto-splits at 1000 bytes) |
+| `sendMedia(to, media)` | Send image attachment only |
+| `sendQuickReplies(to, text, replies)` | Send quick reply buttons (max 13) |
+| `sendGenericTemplate(to, template)` | Send carousel template |
+| `sendButtonTemplate(to, template)` | Send button template |
+| `sendPrivateReply(options)` | Reply privately to a comment |
+| `sendTextWithTag(to, text, tag)` | Send with message tag (e.g. HUMAN_AGENT) |
+| `iceBreakers.set(breakers)` | Set conversation starters |
+| `iceBreakers.get()` | Get current ice breakers |
+| `iceBreakers.delete()` | Remove all ice breakers |
+
+## Standalone Webhook Utilities
+
+For server-side webhook handling without the full client:
+
+```ts
+import { verifySignature, normalizeWebhook } from '@ariaflowagents/messaging-meta/server';
+
+app.post('/webhook', async (c) => {
+  const rawBody = await c.req.text();
+  const sig = c.req.header('x-hub-signature-256') ?? '';
+
+  if (!verifySignature({ appSecret, rawBody, signatureHeader: sig })) {
+    return c.text('Invalid signature', 403);
+  }
+
+  const events = normalizeWebhook(JSON.parse(rawBody));
+  // events.messages, events.statuses, events.reactions
+});
+```
+
+## Platform Comparison
+
+| Feature | WhatsApp | Messenger | Instagram |
+|---|:---:|:---:|:---:|
+| Text limit | 4096 chars | 2000 chars | 1000 bytes |
+| Media types | all | all | image only |
+| Buttons / List / Carousel | 3 / yes / no | 3 / no / 10 | 3 / no / 10 |
+| Quick replies | no | 13 | 13 |
+| Templates | yes | yes | yes |
+| Typing + reactions | yes | yes | yes |
+| Message window | 24h | none | 7d (tag) |
+| Unique features | Flows, CTA, lists | Personas, profiles | Ice breakers, private reply |
+
+## AriaFlow Integration
+
+Use with `@ariaflowagents/messaging` to connect clients to the AriaFlow runtime:
+
+```ts
+import { createMessagingRouter } from '@ariaflowagents/messaging';
+
+const router = createMessagingRouter({ runtime, platforms: { whatsapp, messenger, instagram } });
+app.route('/messaging', router);
+// Webhooks: /messaging/{whatsapp,messenger,instagram}/webhook
+```
+
+## Subpath Exports
+
+| Import path | Contents |
+|---|---|
+| `@ariaflowagents/messaging-meta` | GraphAPIClient, errors, webhook utilities |
+| `@ariaflowagents/messaging-meta/whatsapp` | WhatsAppClient, templates, flows, format converter |
+| `@ariaflowagents/messaging-meta/messenger` | MessengerClient, format converter |
+| `@ariaflowagents/messaging-meta/instagram` | InstagramClient, ice breakers, format converter |
+| `@ariaflowagents/messaging-meta/server` | `verifySignature` + `normalizeWebhook` only |
+
+## Related
+
+- [`@ariaflowagents/messaging`](../ariaflow-messaging) -- Core interfaces and runtime adapter
+- [`@ariaflowagents/core`](../ariaflow-core) -- Runtime, agents, flows

package/dist/graph-api/client.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @module graph-api/client
+ *
+ * Typed HTTP client for Meta's Graph API.
+ *
+ * Shared by WhatsApp, Messenger, and Instagram platform clients. Handles
+ * authentication, retry, rate limiting, and error classification transparently.
+ */
+import type { RetryConfig } from './retry.js';
+import type { RateLimiterConfig } from './rate-limiter.js';
+/** Minimal structured logger accepted by the client. */
+export interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/** Configuration for {@link GraphAPIClient}. */
+export interface GraphAPIClientConfig {
+    /** Long-lived or system-user access token for the Graph API. */
+    accessToken: string;
+    /** App secret used for webhook signature verification and appsecret_proof. */
+    appSecret: string;
+    /** Graph API version (e.g. `"v21.0"`). Default `"v21.0"`. */
+    apiVersion?: string;
+    /** Base URL for the Graph API. Default `"https://graph.facebook.com"`. */
+    baseUrl?: string;
+    /** Retry configuration. Uses sensible defaults when omitted. */
+    retry?: Partial<RetryConfig>;
+    /** Rate limiter configuration. Uses sensible defaults when omitted. */
+    rateLimiter?: Partial<RateLimiterConfig>;
+    /** Optional logger for request/response tracing. */
+    logger?: Logger;
+}
+/**
+ * Typed HTTP client for Meta's Graph API.
+ *
+ * Provides `get`, `post`, `postFormData`, and `fetchBinary` methods that
+ * handle authentication, exponential-backoff retry, token-bucket rate
+ * limiting, and error classification automatically.
+ *
+ * @example
+ * ```ts
+ * const client = new GraphAPIClient({
+ *   accessToken: process.env.META_ACCESS_TOKEN!,
+ *   appSecret: process.env.META_APP_SECRET!,
+ * });
+ *
+ * const profile = await client.get<{ name: string }>('me', { fields: 'name' });
+ * ```
+ */
+export declare class GraphAPIClient {
+    private readonly accessToken;
+    private readonly appSecret;
+    private readonly apiVersion;
+    private readonly baseUrl;
+    private readonly retryQueue;
+    private readonly rateLimiter;
+    private readonly logger?;
+    constructor(config: GraphAPIClientConfig);
+    /**
+     * Perform an authenticated GET request against the Graph API.
+     *
+     * @typeParam T - Expected response shape.
+     * @param endpoint - API endpoint relative to the version root (e.g. `"me/messages"`).
+     * @param params   - Optional query-string parameters.
+     * @returns Parsed JSON response body.
+     */
+    get<T>(endpoint: string, params?: Record<string, string>): Promise<T>;
+    /**
+     * Perform an authenticated POST request with a JSON body.
+     *
+     * @typeParam T - Expected response shape.
+     * @param endpoint - API endpoint relative to the version root.
+     * @param body     - JSON-serializable request body.
+     * @returns Parsed JSON response body.
+     */
+    post<T>(endpoint: string, body: unknown): Promise<T>;
+    /**
+     * Perform an authenticated POST request with form-data (multipart).
+     *
+     * Primarily used for media uploads where the payload includes binary data.
+     *
+     * @typeParam T - Expected response shape.
+     * @param endpoint - API endpoint relative to the version root.
+     * @param formData - `FormData` instance containing the fields/files to upload.
+     * @returns Parsed JSON response body.
+     */
+    postFormData<T>(endpoint: string, formData: FormData): Promise<T>;
+    /**
+     * Download a binary resource from a direct URL (e.g. media CDN link).
+     *
+     * This method does NOT prepend the Graph API base URL — pass the full URL
+     * returned by the media endpoint.
+     *
+     * @param url - Absolute URL to fetch.
+     * @returns Raw binary content as a `Buffer`.
+     */
+    fetchBinary(url: string): Promise<Buffer>;
+    /**
+     * Build a fully-qualified Graph API URL.
+     *
+     * @param endpoint - Relative endpoint (e.g. `"12345/messages"`).
+     * @param params   - Additional query-string parameters.
+     * @returns A `URL` instance with access token and params applied.
+     */
+    private buildUrl;
+    /** Standard headers included on every JSON request. */
+    private defaultHeaders;
+    /**
+     * Core request executor with retry and rate limiting.
+     *
+     * Wraps `fetch` in the retry queue and acquires/releases rate limiter
+     * tokens around each attempt.
+     */
+    private executeRequest;
+    /**
+     * Map a non-2xx Graph API response to a typed {@link MessagingError}.
+     *
+     * Delegates to {@link classifyMetaError} which maps Meta error codes
+     * and HTTP statuses to the appropriate error subclass.
+     */
+    private classifyError;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/graph-api/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/graph-api/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAQ3D,wDAAwD;AACxD,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAChD,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CAClD;AAMD,gDAAgD;AAChD,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B,uEAAuE;IACvE,WAAW,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACzC,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,MAAM,EAAE,oBAAoB;IAcxC;;;;;;;OAOG;IACG,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAU3E;;;;;;;OAOG;IACG,IAAI,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAc1D;;;;;;;;;OASG;IACG,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC;IAcvE;;;;;;;;OAQG;IACG,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgC/C;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAchB,uDAAuD;IACvD,OAAO,CAAC,cAAc;IAOtB;;;;;OAKG;YACW,cAAc;IAoB5B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;CAGtB"}

package/dist/graph-api/client.js

@@ -0,0 +1,204 @@
+/**
+ * @module graph-api/client
+ *
+ * Typed HTTP client for Meta's Graph API.
+ *
+ * Shared by WhatsApp, Messenger, and Instagram platform clients. Handles
+ * authentication, retry, rate limiting, and error classification transparently.
+ */
+import { RetryQueue } from './retry.js';
+import { RateLimiter } from './rate-limiter.js';
+import { classifyMetaError } from './errors.js';
+// ---------------------------------------------------------------------------
+// GraphAPIClient
+// ---------------------------------------------------------------------------
+/**
+ * Typed HTTP client for Meta's Graph API.
+ *
+ * Provides `get`, `post`, `postFormData`, and `fetchBinary` methods that
+ * handle authentication, exponential-backoff retry, token-bucket rate
+ * limiting, and error classification automatically.
+ *
+ * @example
+ * ```ts
+ * const client = new GraphAPIClient({
+ *   accessToken: process.env.META_ACCESS_TOKEN!,
+ *   appSecret: process.env.META_APP_SECRET!,
+ * });
+ *
+ * const profile = await client.get<{ name: string }>('me', { fields: 'name' });
+ * ```
+ */
+export class GraphAPIClient {
+    accessToken;
+    appSecret;
+    apiVersion;
+    baseUrl;
+    retryQueue;
+    rateLimiter;
+    logger;
+    constructor(config) {
+        this.accessToken = config.accessToken;
+        this.appSecret = config.appSecret;
+        this.apiVersion = config.apiVersion ?? 'v21.0';
+        this.baseUrl = (config.baseUrl ?? 'https://graph.facebook.com').replace(/\/+$/, '');
+        this.retryQueue = new RetryQueue(config.retry);
+        this.rateLimiter = new RateLimiter(config.rateLimiter);
+        this.logger = config.logger;
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    /**
+     * Perform an authenticated GET request against the Graph API.
+     *
+     * @typeParam T - Expected response shape.
+     * @param endpoint - API endpoint relative to the version root (e.g. `"me/messages"`).
+     * @param params   - Optional query-string parameters.
+     * @returns Parsed JSON response body.
+     */
+    async get(endpoint, params) {
+        const url = this.buildUrl(endpoint, params);
+        this.logger?.debug('[GraphAPI] GET %s', url.toString());
+        return this.executeRequest(url.toString(), {
+            method: 'GET',
+            headers: this.defaultHeaders(),
+        });
+    }
+    /**
+     * Perform an authenticated POST request with a JSON body.
+     *
+     * @typeParam T - Expected response shape.
+     * @param endpoint - API endpoint relative to the version root.
+     * @param body     - JSON-serializable request body.
+     * @returns Parsed JSON response body.
+     */
+    async post(endpoint, body) {
+        const url = this.buildUrl(endpoint);
+        this.logger?.debug('[GraphAPI] POST %s', url.toString());
+        return this.executeRequest(url.toString(), {
+            method: 'POST',
+            headers: {
+                ...this.defaultHeaders(),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    /**
+     * Perform an authenticated POST request with form-data (multipart).
+     *
+     * Primarily used for media uploads where the payload includes binary data.
+     *
+     * @typeParam T - Expected response shape.
+     * @param endpoint - API endpoint relative to the version root.
+     * @param formData - `FormData` instance containing the fields/files to upload.
+     * @returns Parsed JSON response body.
+     */
+    async postFormData(endpoint, formData) {
+        const url = this.buildUrl(endpoint);
+        this.logger?.debug('[GraphAPI] POST (form-data) %s', url.toString());
+        // Do NOT set Content-Type manually — `fetch` sets the boundary automatically.
+        return this.executeRequest(url.toString(), {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.accessToken}`,
+            },
+            body: formData,
+        });
+    }
+    /**
+     * Download a binary resource from a direct URL (e.g. media CDN link).
+     *
+     * This method does NOT prepend the Graph API base URL — pass the full URL
+     * returned by the media endpoint.
+     *
+     * @param url - Absolute URL to fetch.
+     * @returns Raw binary content as a `Buffer`.
+     */
+    async fetchBinary(url) {
+        this.logger?.debug('[GraphAPI] FETCH_BINARY %s', url);
+        return this.retryQueue.execute(async () => {
+            await this.rateLimiter.acquire();
+            try {
+                const response = await fetch(url, {
+                    method: 'GET',
+                    headers: {
+                        Authorization: `Bearer ${this.accessToken}`,
+                    },
+                });
+                this.rateLimiter.updateFromHeaders(response.headers);
+                if (!response.ok) {
+                    const body = await response.json().catch(() => null);
+                    throw this.classifyError(response, body);
+                }
+                const arrayBuffer = await response.arrayBuffer();
+                return Buffer.from(arrayBuffer);
+            }
+            finally {
+                this.rateLimiter.release();
+            }
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Private helpers
+    // -----------------------------------------------------------------------
+    /**
+     * Build a fully-qualified Graph API URL.
+     *
+     * @param endpoint - Relative endpoint (e.g. `"12345/messages"`).
+     * @param params   - Additional query-string parameters.
+     * @returns A `URL` instance with access token and params applied.
+     */
+    buildUrl(endpoint, params) {
+        const cleanEndpoint = endpoint.replace(/^\/+/, '');
+        const url = new URL(`${this.baseUrl}/${this.apiVersion}/${cleanEndpoint}`);
+        url.searchParams.set('access_token', this.accessToken);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url;
+    }
+    /** Standard headers included on every JSON request. */
+    defaultHeaders() {
+        return {
+            Authorization: `Bearer ${this.accessToken}`,
+            Accept: 'application/json',
+        };
+    }
+    /**
+     * Core request executor with retry and rate limiting.
+     *
+     * Wraps `fetch` in the retry queue and acquires/releases rate limiter
+     * tokens around each attempt.
+     */
+    async executeRequest(url, init) {
+        return this.retryQueue.execute(async () => {
+            await this.rateLimiter.acquire();
+            try {
+                const response = await fetch(url, init);
+                this.rateLimiter.updateFromHeaders(response.headers);
+                if (!response.ok) {
+                    const body = await response.json().catch(() => null);
+                    throw this.classifyError(response, body);
+                }
+                return (await response.json());
+            }
+            finally {
+                this.rateLimiter.release();
+            }
+        });
+    }
+    /**
+     * Map a non-2xx Graph API response to a typed {@link MessagingError}.
+     *
+     * Delegates to {@link classifyMetaError} which maps Meta error codes
+     * and HTTP statuses to the appropriate error subclass.
+     */
+    classifyError(response, body) {
+        return classifyMetaError(response.status, body, 'meta');
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/graph-api/client.js.map

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

package/dist/graph-api/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @module graph-api/errors
+ *
+ * Meta-specific error classification helper.
+ *
+ * Imports the canonical error hierarchy from `@ariaflowagents/messaging` and
+ * re-exports it alongside the {@link classifyMetaError} function. This ensures
+ * that `instanceof` checks work correctly across the entire SDK — there is only
+ * ONE `WindowClosedError` class, ONE `RateLimitError` class, etc.
+ */
+import { MessagingError, RateLimitError, AuthenticationError, PermissionError, RecipientError, WindowClosedError, TemplateError, MediaError, WebhookVerificationError } from '@ariaflowagents/messaging';
+export { MessagingError, RateLimitError, AuthenticationError, PermissionError, RecipientError, WindowClosedError, TemplateError, MediaError, WebhookVerificationError, };
+/** Shape of a Meta Graph API error response body. */
+export interface MetaErrorResponse {
+    error?: {
+        message?: string;
+        type?: string;
+        code?: number;
+        error_subcode?: number;
+        fbtrace_id?: string;
+    };
+}
+/**
+ * Classify a Meta Graph API error response into a typed {@link MessagingError}.
+ *
+ * The mapping follows Meta's documented error codes:
+ * - 429 / codes 4, 32, 613 -> {@link RateLimitError}
+ * - 401 / code 190 -> {@link AuthenticationError}
+ * - 403 / codes 10, 200 -> {@link PermissionError}
+ * - 404 -> {@link RecipientError}
+ * - code 131047 -> {@link WindowClosedError} (24-hour window expired)
+ * - code 131026 -> {@link RecipientError} (not on WhatsApp)
+ * - codes 132000-132999 -> {@link TemplateError}
+ *
+ * @param status  - HTTP status code from the response.
+ * @param body    - Parsed JSON body (may be `null` if parsing failed).
+ * @param platform - Platform identifier (e.g. `"whatsapp"`, `"messenger"`).
+ * @returns A typed {@link MessagingError} subclass.
+ */
+export declare function classifyMetaError(status: number, body: unknown, platform: string): MessagingError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/graph-api/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/graph-api/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,wBAAwB,EACzB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,cAAc,EACd,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,wBAAwB,GACzB,CAAC;AAMF,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE;QACN,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;CACH;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,MAAM,GACf,cAAc,CA6ChB"}