TypeScript SDK

@messagebird/sdk is de officiële TypeScript SDK voor de Bird API. Het is volledig getypeerd, ESM-only en edge-ready. Het draait op Node.js 20.3+ en moderne edge-runtimes (Cloudflare Workers, Vercel Edge, Deno) met web-standaard-API's (fetch, AbortSignal, Web Crypto). Deze pagina behandelt de client. Om e-mail te versturen met de SDK, begin je met de TypeScript e-mail-quickstart.

Installeren

npm install @messagebird/sdk
# pnpm add @messagebird/sdk
# yarn add @messagebird/sdk
# bun add @messagebird/sdk

Het pakket is gepubliceerd als @messagebird/sdk op npm, vanuit messagebird/bird-sdk-typescript.

Een client aanmaken

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY!,
  region: "eu1", // optional; overrides the region from the key prefix
  baseUrl: "http://localhost:8080", // optional; overrides region (local or self-hosted)
  timeout: 60_000, // per-attempt timeout in ms (default 60_000)
  maxRetries: 2, // retry budget for transient failures (default 2)
});

Alleen apiKey is vereist. De regio wordt afgeleid uit het bk_{region}_-prefix van de key (een bk_eu1_…-key routeert naar https://eu1.platform.bird.com), dus de meeste clients worden alleen met de key aangemaakt. Zie regio-inferentie voor de afleidsregels. Je kunt ook kanaalstandaarden instellen bij het aanmaken (bijvoorbeeld email: { from: "hello@acme.com" } maakt from optioneel bij elke verzending) en het webhook-ondertekeningsgeheim via webhooks: { secret }.

Eerste aanroep

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});
console.log(msg.id, msg.status); // "em_…", "accepted"

await resolvet direct naar het API-resultaat, wat in dit voorbeeld een e-mailbericht is met zijn em_*-ID. Volg de TypeScript-quickstart voor een uitvoerbare walkthrough.

Tweelaags ontwerp

De SDK heeft een gegenereerde laag en een handmatig onderhouden laag. Wire-types en low-level HTTP-plumbing worden gegenereerd uit de OpenAPI-specificatie van Bird, zodat request- en response-shapes in lijn blijven met het contract. De handgeschreven laag biedt bird.email.send(...), nieuwe pogingen, idempotentie, paginering en fouten. Wire-velden worden ongewijzigd doorgegeven in snake_case (category, created_at); door SDK gedefinieerde identifiers, zoals methodenamen en idempotencyKey, gebruiken camelCase. De SDK's voor Go, Python en PHP delen deze architectuur. Zie SDK-concepten voor details.

Automatische idempotentie en nieuwe pogingen

Elke mutatie (POST, PUT, PATCH, DELETE) krijgt een automatisch gegenereerde header Idempotency-Key. De SDK gebruikt die sleutel bij elke nieuwe poging opnieuw, zodat overeenkomende verzoeken het bewaarde antwoord opnieuw kunnen krijgen. Zie Idempotentie voor eigen sleutels over afzonderlijke SDK-aanroepen en de grenzen aan het opnieuw teruggeven van antwoorden.

Nieuwe pogingen staan standaard aan (maxRetries: 2). De client probeert het opnieuw bij netwerkfouten, timeouts per poging en tijdelijke statussen (408, 429, 500, 502, 503, 504) met jittered exponential backoff, en respecteert de Retry-After-header van de server wanneer die aanwezig is. Deterministische fouten (4xx zoals 401, 404, 422) worden nooit opnieuw geprobeerd. Stel maxRetries: 0 in om nieuwe pogingen uit te schakelen, of overschrijf dit per aanroep. De volledige levenscyclus staat beschreven in SDK-concepten.

Fouten

Methoden throwen bij een fout met een getypeerde hiërarchie die je vernauwt met instanceof. BirdError is de root. BirdAPIError dekt elke foutrespons van de server, met één subklasse per fout-type. Hieronder vallen BirdAuthError (401), BirdRateLimitError (429, met retryAfter), BirdValidationError (422, met per-veld details) en BirdPayloadTooLargeError (413). Transportfouten zonder HTTP-respons gebruiken de zusterklassen BirdConnectionError en BirdTimeoutError.

import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";

try {
  await bird.email.send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  });
} catch (err) {
  if (err instanceof BirdRateLimitError) console.log(`rate limited; retry in ${err.retryAfter}s`);
  else if (err instanceof BirdValidationError) console.error(err.details);
  else if (err instanceof BirdAPIError) console.error(err.code, err.requestId);
  else throw err;
}

Elke BirdAPIError bevat statusCode, type, code (de stabiele E#####-foutcode), requestId en docUrl. Branch op de klasse (of de grove type) voor control flow; gebruik code als je één specifieke fout wilt matchen. Wil je op een waarde branchen in plaats van een fout te catchen? Roep dan .safe() aan:

const { data, error } = await bird.email
  .send({
    from: { email: "onboarding@messagebird.dev", name: "Bird" },
    to: ["delivered@messagebird.dev"],
    subject: "Hello from Bird",
    html: "<p>My first Bird email.</p>",
  })
  .safe();
if (error) console.error(error.message);
else console.log(data.id);

Webhooks

bird.webhooks.unwrap(rawBody, headers) verifieert de Standard Webhooks-handtekening van een inkomende delivery en retourneert een getypeerd, gediscrimineerd event. Geef de onbewerkte request-body door, omdat parsen en opnieuw serialiseren de ondertekende bytes verandert. Een ongeldige handtekening, verlopen timestamp of misvormde headers throwen BirdWebhookVerificationError. Zie webhookverificatie voor het cross-SDK-contract en Webhooks voor de platformconfiguratie.

Volgende stappen

• E-mail-quickstart: Gebruik send, get, list, kanaalstandaarden en de response-shapes.
• SDK-concepten: Leer over idempotentie, nieuwe pogingen, paginering, regio's en webhooks in alle Bird-SDK's.
• API-referentie: Bekijk de onderliggende HTTP API. bird.request<T>() bereikt endpoints die het getypeerde oppervlak nog niet dekt, met dezelfde authenticatie, nieuwe pogingen en idempotentie.