agent-messenger 1.14.0 → 2.0.0

package/src/platforms/whatsappbot/client.test.ts

@@ -0,0 +1,411 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+
+import { WhatsAppBotClient } from '@/platforms/whatsappbot/client'
+import { WhatsAppBotError } from '@/platforms/whatsappbot/types'
+
+describe('WhatsAppBotClient', () => {
+  const originalFetch = globalThis.fetch
+  let fetchCalls: Array<{ url: string; options?: RequestInit }> = []
+  let fetchResponses: Response[] = []
+  let fetchIndex = 0
+
+  beforeEach(() => {
+    fetchCalls = []
+    fetchResponses = []
+    fetchIndex = 0
+    Object.defineProperty(globalThis, 'fetch', {
+      value: async (url: string | URL | Request, options?: RequestInit): Promise<Response> => {
+        fetchCalls.push({ url: url.toString(), options })
+        const response = fetchResponses[fetchIndex]
+        fetchIndex++
+        if (!response) {
+          throw new Error('No mock response configured')
+        }
+        return response
+      },
+      writable: true,
+      configurable: true,
+    })
+  })
+
+  afterEach(() => {
+    Object.defineProperty(globalThis, 'fetch', {
+      value: originalFetch,
+      writable: true,
+      configurable: true,
+    })
+  })
+
+  const mockResponse = (body: unknown, status = 200, headers: Record<string, string> = {}) => {
+    const defaultHeaders: Record<string, string> = {
+      'Content-Type': 'application/json',
+      ...headers,
+    }
+    fetchResponses.push(
+      new Response(body === null ? null : JSON.stringify(body), {
+        status,
+        headers: defaultHeaders,
+      }),
+    )
+  }
+
+  describe('login', () => {
+    test('throws on empty phoneNumberId', async () => {
+      await expect(new WhatsAppBotClient().login({ phoneNumberId: '', accessToken: 'access-token' })).rejects.toThrow(WhatsAppBotError)
+      await expect(new WhatsAppBotClient().login({ phoneNumberId: '', accessToken: 'access-token' })).rejects.toThrow('Phone number ID is required')
+    })
+
+    test('throws on empty accessToken', async () => {
+      await expect(new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: '' })).rejects.toThrow(WhatsAppBotError)
+      await expect(new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: '' })).rejects.toThrow('Access token is required')
+    })
+
+    test('accepts valid phoneNumberId and accessToken', async () => {
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'access-token' })
+      expect(client).toBeInstanceOf(WhatsAppBotClient)
+    })
+  })
+
+  describe('verifyToken', () => {
+    test('sends GET request with correct URL and auth header', async () => {
+      mockResponse({ verified_name: 'Test Business' })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      const result = await client.verifyToken()
+
+      expect(result.verified_name).toBe('Test Business')
+      expect(fetchCalls.length).toBe(1)
+      expect(fetchCalls[0].url).toBe('https://graph.facebook.com/v23.0/phone-123?fields=verified_name')
+      expect(fetchCalls[0].options?.headers).toMatchObject({
+        Authorization: 'Bearer my-token',
+      })
+    })
+
+    test('throws WhatsAppBotError on API error', async () => {
+      mockResponse({ error: { message: 'Invalid token', code: 190 } }, 401)
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'bad-token' })
+      await expect(client.verifyToken()).rejects.toThrow(WhatsAppBotError)
+    })
+  })
+
+  describe('sendTextMessage', () => {
+    test('sends POST request with correct body shape', async () => {
+      mockResponse({
+        messaging_product: 'whatsapp',
+        contacts: [{ input: '+15551234567', wa_id: '15551234567' }],
+        messages: [{ id: 'wamid.abc123' }],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      const result = await client.sendTextMessage('+15551234567', 'Hello world')
+
+      expect(result.messages[0].id).toBe('wamid.abc123')
+      expect(fetchCalls[0].url).toBe('https://graph.facebook.com/v23.0/phone-123/messages')
+      expect(fetchCalls[0].options?.method).toBe('POST')
+
+      const body = JSON.parse(fetchCalls[0].options?.body as string)
+      expect(body).toMatchObject({
+        messaging_product: 'whatsapp',
+        to: '+15551234567',
+        type: 'text',
+        text: { body: 'Hello world', preview_url: false },
+      })
+    })
+
+    test('sends correct Authorization header', async () => {
+      mockResponse({
+        messaging_product: 'whatsapp',
+        contacts: [],
+        messages: [{ id: 'wamid.test' }],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'secret-token' })
+      await client.sendTextMessage('+15551234567', 'Hello')
+
+      expect(fetchCalls[0].options?.headers).toMatchObject({
+        Authorization: 'Bearer secret-token',
+      })
+    })
+
+    test('returns WhatsAppBotMessageResponse', async () => {
+      mockResponse({
+        messaging_product: 'whatsapp',
+        contacts: [{ input: '+15551234567', wa_id: '15551234567' }],
+        messages: [{ id: 'wamid.abc123' }],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      const result = await client.sendTextMessage('+15551234567', 'Hello')
+
+      expect(result.messaging_product).toBe('whatsapp')
+      expect(result.contacts).toHaveLength(1)
+      expect(result.messages).toHaveLength(1)
+    })
+  })
+
+  describe('sendTemplateMessage', () => {
+    test('sends POST with template payload', async () => {
+      mockResponse({
+        messaging_product: 'whatsapp',
+        contacts: [{ input: '+15551234567', wa_id: '15551234567' }],
+        messages: [{ id: 'wamid.template1' }],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await client.sendTemplateMessage('+15551234567', 'hello_world', 'en_US')
+
+      const body = JSON.parse(fetchCalls[0].options?.body as string)
+      expect(body).toMatchObject({
+        messaging_product: 'whatsapp',
+        to: '+15551234567',
+        type: 'template',
+        template: { name: 'hello_world', language: { code: 'en_US' } },
+      })
+    })
+
+    test('includes components when provided', async () => {
+      mockResponse({
+        messaging_product: 'whatsapp',
+        contacts: [],
+        messages: [{ id: 'wamid.template2' }],
+      })
+
+      const components = [{ type: 'body', parameters: [{ type: 'text', text: 'World' }] }]
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await client.sendTemplateMessage('+15551234567', 'greeting', 'en_US', components)
+
+      const body = JSON.parse(fetchCalls[0].options?.body as string)
+      expect(body.template.components).toEqual(components)
+    })
+  })
+
+  describe('sendReaction', () => {
+    test('sends POST with reaction payload', async () => {
+      mockResponse({
+        messaging_product: 'whatsapp',
+        contacts: [],
+        messages: [{ id: 'wamid.reaction1' }],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await client.sendReaction('+15551234567', 'wamid.orig123', '👍')
+
+      const body = JSON.parse(fetchCalls[0].options?.body as string)
+      expect(body).toMatchObject({
+        messaging_product: 'whatsapp',
+        to: '+15551234567',
+        type: 'reaction',
+        reaction: { message_id: 'wamid.orig123', emoji: '👍' },
+      })
+    })
+  })
+
+  describe('sendImageMessage', () => {
+    test('sends POST with image payload', async () => {
+      mockResponse({
+        messaging_product: 'whatsapp',
+        contacts: [],
+        messages: [{ id: 'wamid.image1' }],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await client.sendImageMessage('+15551234567', 'https://example.com/photo.jpg', 'My photo')
+
+      const body = JSON.parse(fetchCalls[0].options?.body as string)
+      expect(body).toMatchObject({
+        messaging_product: 'whatsapp',
+        to: '+15551234567',
+        type: 'image',
+        image: { link: 'https://example.com/photo.jpg', caption: 'My photo' },
+      })
+    })
+  })
+
+  describe('sendDocumentMessage', () => {
+    test('sends POST with document payload', async () => {
+      mockResponse({
+        messaging_product: 'whatsapp',
+        contacts: [],
+        messages: [{ id: 'wamid.doc1' }],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await client.sendDocumentMessage('+15551234567', 'https://example.com/report.pdf', 'report.pdf', 'Q4 Report')
+
+      const body = JSON.parse(fetchCalls[0].options?.body as string)
+      expect(body).toMatchObject({
+        messaging_product: 'whatsapp',
+        to: '+15551234567',
+        type: 'document',
+        document: { link: 'https://example.com/report.pdf', filename: 'report.pdf', caption: 'Q4 Report' },
+      })
+    })
+  })
+
+  describe('listTemplates', () => {
+    test('sends GET and unwraps data key from response', async () => {
+      mockResponse({
+        data: [
+          { name: 'hello_world', status: 'APPROVED', category: 'UTILITY', language: 'en_US', components: [] },
+          { name: 'order_update', status: 'APPROVED', category: 'UTILITY', language: 'en_US', components: [] },
+        ],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      const templates = await client.listTemplates()
+
+      expect(templates).toHaveLength(2)
+      expect(templates[0].name).toBe('hello_world')
+      expect(templates[1].name).toBe('order_update')
+      expect(fetchCalls[0].url).toContain('/phone-123/message_templates')
+      expect(fetchCalls[0].options?.method).toBe('GET')
+    })
+
+    test('passes limit parameter in URL', async () => {
+      mockResponse({ data: [] })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await client.listTemplates({ limit: 10 })
+
+      expect(fetchCalls[0].url).toContain('limit=10')
+    })
+  })
+
+  describe('getTemplate', () => {
+    test('sends GET with name filter and returns first match', async () => {
+      mockResponse({
+        data: [
+          { name: 'hello_world', status: 'APPROVED', category: 'UTILITY', language: 'en_US', components: [] },
+        ],
+      })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      const template = await client.getTemplate('hello_world')
+
+      expect(template.name).toBe('hello_world')
+      expect(fetchCalls[0].url).toContain('name=hello_world')
+    })
+
+    test('throws WhatsAppBotError with not_found code when template not found', async () => {
+      mockResponse({ data: [] })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+
+      try {
+        await client.getTemplate('nonexistent')
+        expect.unreachable('should have thrown')
+      } catch (err) {
+        expect(err).toBeInstanceOf(WhatsAppBotError)
+        expect((err as WhatsAppBotError).code).toBe('not_found')
+      }
+    })
+  })
+
+  describe('rate limiting', () => {
+    test('waits when x-business-use-case-usage indicates throttle', async () => {
+      const usageHeader = JSON.stringify({
+        '123456789': [
+          {
+            call_count: 100,
+            total_cputime: 50,
+            total_time: 100,
+            type: 'UPLOAD_MEDIA',
+            estimated_time_to_regain_access: 0.1,
+          },
+        ],
+      })
+
+      mockResponse({ verified_name: 'Test Business' }, 200, { 'x-business-use-case-usage': usageHeader })
+      mockResponse({ verified_name: 'Test Business' })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await client.verifyToken()
+
+      const startTime = Date.now()
+      await client.verifyToken()
+      const elapsed = Date.now() - startTime
+
+      expect(elapsed).toBeGreaterThanOrEqual(80)
+      expect(fetchCalls.length).toBe(2)
+    })
+
+    test('retries on 429 with Retry-After header', async () => {
+      mockResponse({ error: { message: 'Rate limited', code: 613 } }, 429, { 'Retry-After': '0.1' })
+      mockResponse({ verified_name: 'Test Business' })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      const result = await client.verifyToken()
+
+      expect(result.verified_name).toBe('Test Business')
+      expect(fetchCalls.length).toBe(2)
+    })
+
+    test('throws after max retries exceeded', async () => {
+      for (let i = 0; i <= 3; i++) {
+        mockResponse({ error: { message: 'Rate limited', code: 613 } }, 429, { 'Retry-After': '0.01' })
+      }
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await expect(client.verifyToken()).rejects.toThrow(WhatsAppBotError)
+      expect(fetchCalls.length).toBe(4)
+    })
+  })
+
+  describe('retry logic', () => {
+    test('retries on 500 server error for GET requests', async () => {
+      mockResponse({ error: { message: 'Internal Server Error' } }, 500)
+      mockResponse({ verified_name: 'Test Business' })
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      const result = await client.verifyToken()
+
+      expect(result.verified_name).toBe('Test Business')
+      expect(fetchCalls.length).toBe(2)
+    })
+
+    test('does not retry on 500 for POST requests', async () => {
+      mockResponse({ error: { message: 'Internal Server Error' } }, 500)
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await expect(client.sendTextMessage('+15551234567', 'Hello')).rejects.toThrow(WhatsAppBotError)
+      expect(fetchCalls.length).toBe(1)
+    })
+
+    test('does not retry on 4xx client errors (except 429)', async () => {
+      mockResponse({ error: { message: 'Not Found', code: 100 } }, 404)
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await expect(client.verifyToken()).rejects.toThrow(WhatsAppBotError)
+      expect(fetchCalls.length).toBe(1)
+    })
+
+    test('does not retry on 403 forbidden', async () => {
+      mockResponse({ error: { message: 'Forbidden', code: 200 } }, 403)
+
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-token' })
+      await expect(client.verifyToken()).rejects.toThrow(WhatsAppBotError)
+      expect(fetchCalls.length).toBe(1)
+    })
+  })
+
+  describe('request URL construction', () => {
+    test('all requests go to https://graph.facebook.com/v23.0/...', async () => {
+      mockResponse({ verified_name: 'Test' })
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'my-phone', accessToken: 'my-token' })
+      await client.verifyToken()
+
+      expect(fetchCalls[0].url.startsWith('https://graph.facebook.com/v23.0/')).toBe(true)
+    })
+
+    test('Authorization header is Bearer <token>', async () => {
+      mockResponse({ verified_name: 'Test' })
+      const client = await new WhatsAppBotClient().login({ phoneNumberId: 'phone-123', accessToken: 'my-secret-token' })
+      await client.verifyToken()
+
+      expect(fetchCalls[0].options?.headers).toMatchObject({
+        Authorization: 'Bearer my-secret-token',
+      })
+    })
+  })
+})

package/src/platforms/whatsappbot/client.ts

@@ -0,0 +1,256 @@
+import type { WhatsAppBotMessageResponse, WhatsAppBotTemplate } from './types'
+import { WhatsAppBotError } from './types'
+
+const BASE_URL = 'https://graph.facebook.com/v23.0'
+const MAX_RETRIES = 3
+const BASE_BACKOFF_MS = 100
+
+export class WhatsAppBotClient {
+  private phoneNumberId: string | null = null
+  private accessToken: string | null = null
+  private rateLimitRemaining: number | null = null
+  private rateLimitResetAt: number = 0
+
+  async login(credentials?: { phoneNumberId: string; accessToken: string }): Promise<this> {
+    if (credentials) {
+      if (!credentials.phoneNumberId) {
+        throw new WhatsAppBotError('Phone number ID is required', 'missing_phone_number_id')
+      }
+      if (!credentials.accessToken) {
+        throw new WhatsAppBotError('Access token is required', 'missing_access_token')
+      }
+      this.phoneNumberId = credentials.phoneNumberId
+      this.accessToken = credentials.accessToken
+      return this
+    }
+    const { WhatsAppBotCredentialManager } = await import('./credential-manager')
+    const credManager = new WhatsAppBotCredentialManager()
+    const creds = await credManager.getCredentials()
+    if (!creds) {
+      throw new WhatsAppBotError(
+        'No WhatsApp Bot credentials found. Run "agent-whatsappbot auth set" first.',
+        'no_credentials',
+      )
+    }
+    return this.login({ phoneNumberId: creds.phone_number_id, accessToken: creds.access_token })
+  }
+
+  private ensureAuth(): void {
+    if (this.phoneNumberId === null) {
+      throw new WhatsAppBotError('Not authenticated. Call .login() first.', 'not_authenticated')
+    }
+  }
+
+  async verifyToken(): Promise<{ verified_name: string }> {
+    return this.request<{ verified_name: string }>('GET', `/${this.phoneNumberId!}?fields=verified_name`)
+  }
+
+  async sendTextMessage(to: string, text: string, previewUrl?: boolean): Promise<WhatsAppBotMessageResponse> {
+    return this.request<WhatsAppBotMessageResponse>('POST', `/${this.phoneNumberId!}/messages`, {
+      messaging_product: 'whatsapp',
+      to,
+      type: 'text',
+      text: { body: text, preview_url: previewUrl ?? false },
+    })
+  }
+
+  async sendTemplateMessage(
+    to: string,
+    templateName: string,
+    languageCode: string,
+    components?: unknown[],
+  ): Promise<WhatsAppBotMessageResponse> {
+    return this.request<WhatsAppBotMessageResponse>('POST', `/${this.phoneNumberId}/messages`, {
+      messaging_product: 'whatsapp',
+      to,
+      type: 'template',
+      template: { name: templateName, language: { code: languageCode }, components },
+    })
+  }
+
+  async sendReaction(to: string, messageId: string, emoji: string): Promise<WhatsAppBotMessageResponse> {
+    return this.request<WhatsAppBotMessageResponse>('POST', `/${this.phoneNumberId}/messages`, {
+      messaging_product: 'whatsapp',
+      to,
+      type: 'reaction',
+      reaction: { message_id: messageId, emoji },
+    })
+  }
+
+  async sendImageMessage(to: string, imageUrl: string, caption?: string): Promise<WhatsAppBotMessageResponse> {
+    return this.request<WhatsAppBotMessageResponse>('POST', `/${this.phoneNumberId}/messages`, {
+      messaging_product: 'whatsapp',
+      to,
+      type: 'image',
+      image: { link: imageUrl, caption },
+    })
+  }
+
+  async sendDocumentMessage(
+    to: string,
+    documentUrl: string,
+    filename?: string,
+    caption?: string,
+  ): Promise<WhatsAppBotMessageResponse> {
+    return this.request<WhatsAppBotMessageResponse>('POST', `/${this.phoneNumberId}/messages`, {
+      messaging_product: 'whatsapp',
+      to,
+      type: 'document',
+      document: { link: documentUrl, filename, caption },
+    })
+  }
+
+  async listTemplates(params?: { limit?: number }): Promise<WhatsAppBotTemplate[]> {
+    return this.request<WhatsAppBotTemplate[]>('GET', this.buildPath(`/${this.phoneNumberId}/message_templates`, params), undefined, 'data')
+  }
+
+  async getTemplate(templateName: string): Promise<WhatsAppBotTemplate> {
+    const templates = await this.request<WhatsAppBotTemplate[]>(
+      'GET',
+      `/${this.phoneNumberId}/message_templates?name=${encodeURIComponent(templateName)}`,
+      undefined,
+      'data',
+    )
+    const template = templates[0]
+    if (!template) {
+      throw new WhatsAppBotError(`Template "${templateName}" not found`, 'not_found')
+    }
+    return template
+  }
+
+  private getHeaders(): Record<string, string> {
+    return {
+      Authorization: `Bearer ${this.accessToken}`,
+      'Content-Type': 'application/json',
+    }
+  }
+
+  private async waitForRateLimit(): Promise<void> {
+    const now = Date.now()
+    if (this.rateLimitRemaining === 0 && this.rateLimitResetAt > now) {
+      await this.sleep(this.rateLimitResetAt - now)
+    }
+  }
+
+  private updateRateLimit(response: Response): void {
+    const usageHeader = response.headers.get('x-business-use-case-usage')
+    if (usageHeader) {
+      try {
+        const usage = JSON.parse(usageHeader) as Record<string, Array<{ call_count: number; total_cputime: number; total_time: number; type: string; estimated_time_to_regain_access: number }>>
+        for (const entries of Object.values(usage)) {
+          for (const entry of entries) {
+            if (entry.call_count >= 100) {
+              this.rateLimitRemaining = 0
+              this.rateLimitResetAt = Date.now() + (entry.estimated_time_to_regain_access ?? 60) * 1000
+            }
+          }
+        }
+      } catch {
+        // ignore parse errors
+      }
+    }
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown, unwrapKey?: string): Promise<T> {
+    this.ensureAuth()
+    const url = `${BASE_URL}${path}`
+    let lastError: Error | undefined
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      await this.waitForRateLimit()
+
+      const options: RequestInit = {
+        method,
+        headers: this.getHeaders(),
+      }
+
+      if (body !== undefined) {
+        options.body = JSON.stringify(body)
+      }
+
+      let response: Response
+
+      try {
+        response = await fetch(url, options)
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error))
+        if (attempt < MAX_RETRIES && method === 'GET') {
+          await this.sleep(BASE_BACKOFF_MS * 2 ** attempt)
+          continue
+        }
+        throw new WhatsAppBotError(`Network error: ${lastError.message}`, 'network_error')
+      }
+
+      this.updateRateLimit(response)
+
+      if (response.status === 429) {
+        if (attempt < MAX_RETRIES) {
+          const retryAfter = Number.parseFloat(response.headers.get('Retry-After') || '1')
+          const retryAfterMs = (Number.isNaN(retryAfter) ? 1 : retryAfter) * 1000
+          await this.sleep(retryAfterMs)
+          continue
+        }
+        throw new WhatsAppBotError('Rate limited', 'rate_limited')
+      }
+
+      if (response.status >= 500 && response.status <= 599) {
+        if (attempt < MAX_RETRIES && method === 'GET') {
+          await this.sleep(BASE_BACKOFF_MS * 2 ** attempt)
+          continue
+        }
+
+        const errorBody = await response.json().catch(() => ({})) as {
+          error?: { message?: string; code?: number }
+        }
+        const msg = errorBody.error?.message || `HTTP ${response.status}`
+        const code = errorBody.error?.code ? String(errorBody.error.code) : `http_${response.status}`
+        throw new WhatsAppBotError(msg, code)
+      }
+
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => ({})) as {
+          error?: { message?: string; code?: number }
+        }
+        const msg = errorBody.error?.message || `HTTP ${response.status}`
+        const code = errorBody.error?.code ? String(errorBody.error.code) : `http_${response.status}`
+        throw new WhatsAppBotError(msg, code)
+      }
+
+      if (response.status === 204) {
+        return undefined as T
+      }
+
+      const data = await response.json()
+      if (unwrapKey && data != null && typeof data === 'object' && unwrapKey in data) {
+        return (data as Record<string, unknown>)[unwrapKey] as T
+      }
+      return data as T
+    }
+
+    throw lastError || new WhatsAppBotError('Request failed after retries', 'max_retries')
+  }
+
+  private buildPath(path: string, params?: Record<string, string | number | undefined>): string {
+    if (!params) {
+      return path
+    }
+
+    const searchParams = new URLSearchParams()
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined) {
+        searchParams.set(key, String(value))
+      }
+    }
+
+    const query = searchParams.toString()
+    if (!query) {
+      return path
+    }
+
+    return `${path}?${query}`
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}