@kirimdev/sdk

Official TypeScript SDK for the Kirimdev Public API.

Install

npm install @kirimdev/sdk
# or
bun add @kirimdev/sdk

Quickstart

import { Kirim } from '@kirimdev/sdk'

const kirim = new Kirim({ apiKey: process.env.KIRIM_API_KEY! })

// Scope to a WhatsApp phone number (Meta `business_phone_number_id`).
// Look it up via `kirim.accounts.list()` if you don't have it handy.
const phone = kirim.phoneNumbers('106540352242922')

// Send a message
const msg = await phone.messages.send({
  messaging_product: 'whatsapp',
  to: '628123456789',
  type: 'text',
  text: { body: 'Halo dari SDK!' },
})

// Paginate
for await (const m of phone.messages.list({ limit: 50 })) {
  console.log(m.id, m.status)
}

Webhook verification

verifyWebhookSignature parses the X-Kirim-Signature header (Stripe-style t=<unix>,v1=<hex> format), checks the timestamp against a tolerance window, verifies the HMAC-SHA256 against one or more active secrets (supports rotation), and returns the parsed JSON body. It throws on every failure mode — never returns false. Uses Web Crypto so it runs unchanged on Node 18+, Bun, Deno, and edge runtimes.

import { verifyWebhookSignature, InvalidSignatureError } from '@kirimdev/sdk/webhooks'

export async function POST(req: Request) {
  const rawBody = await req.text()
  try {
    const event = await verifyWebhookSignature({
      rawBody,
      signatureHeader: req.headers.get('x-kirim-signature'),
      secrets: [process.env.KIRIM_WEBHOOK_SECRET!],
    })
    // event is KirimWebhookEvent — narrow on event.type or event.object
    return new Response('ok')
  } catch (err) {
    if (err instanceof InvalidSignatureError) return new Response('bad sig', { status: 401 })
    throw err
  }
}

Errors thrown (all extend KirimWebhookError):

• InvalidSignatureError — header missing/malformed, or no v1= matched any provided secret
• SignatureExpiredError — |now - t| exceeds toleranceSeconds (default 300s)
• MalformedPayloadError — signature matched but body is not valid JSON

Features

• Full coverage of the Kirimdev /v1 API (~35 endpoints)
• Type-safe — generated from the live OpenAPI 3.1 spec
• Automatic retries with exponential backoff (429, 5xx, network errors)
• Automatic Idempotency-Key injection for POST requests
• Async iterator pagination (for await ... of kirim.messages.list(...))
• Typed error class hierarchy keyed off stable API error codes
• Webhook HMAC-SHA256 verifier
• Zero Node-specific dependencies — works in Node 18+, Bun, Deno

Configuration

new Kirim({
  apiKey: 'kdv_live_...',                    // required
  baseUrl: 'https://api.kirimdev.com/v1', // optional
  timeout: 30_000,                            // ms, default 30s
  maxRetries: 2,                              // default 2
  fetch: globalThis.fetch,                    // injectable for testing
})

License

MIT