TypeScript SDK

@messagebird/sdk è l'SDK TypeScript ufficiale per Bird API. È completamente tipizzato, solo ESM e pronto per l'edge. Funziona su Node.js 20.3+ e runtime edge moderni (Cloudflare Workers, Vercel Edge, Deno) usando API web standard (fetch, AbortSignal, Web Crypto). Questa pagina tratta il client. Per inviare email con SDK, inizia con il quickstart email TypeScript.

Installazione

Esempio di codice

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

Il pacchetto è pubblicato come @messagebird/sdk su npm, dal repository messagebird/bird-sdk-typescript.

Costruire un client

Esempio di codice

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)
});

Solo apiKey è obbligatorio. La region viene dedotta dal prefisso bk_{region}_ della chiave (una chiave bk_eu1_… viene instradata verso https://eu1.platform.bird.com), quindi la maggior parte dei client si costruisce con la sola chiave. Consulta deduzione della region per le regole di risoluzione. Puoi anche impostare valori predefiniti del canale in fase di costruzione (ad esempio email: { from: "hello@acme.com" } rende from opzionale su ogni invio) e il signing secret per i webhook tramite webhooks: { secret }.

Prima chiamata

Esempio di codice

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 si risolve direttamente nel risultato API, che in questo esempio è un messaggio email con il suo ID em_*. Per una guida eseguibile, segui il quickstart TypeScript.

Architettura a due livelli

L'SDK ha un livello generato e un livello scritto a mano. I tipi wire e l'infrastruttura HTTP di basso livello sono generati dalla specifica OpenAPI di Bird, mantenendo le strutture di richiesta e risposta allineate al contratto. Il livello scritto a mano fornisce bird.email.send(...), retry, idempotenza, paginazione e gestione degli errori. I campi wire passano in snake_case (category, created_at); gli identificatori definiti da SDK, come i nomi dei metodi e idempotencyKey, usano camelCase. Gli SDK Go e Python condividono questa architettura. Consulta i concetti SDK per i dettagli.

Idempotenza e retry automatici

Ogni mutazione (POST, PUT, PATCH, DELETE) riceve un header Idempotency-Key generato automaticamente. L’SDK riutilizza la chiave a ogni tentativo, così le richieste corrispondenti possono riprodurre la risposta conservata. Per le chiavi personalizzate tra chiamate separate all’SDK e i limiti di riproduzione, consulta Idempotenza.

I retry sono attivi per impostazione predefinita (maxRetries: 2). Il client riprova in caso di errori di rete, timeout per singolo tentativo e stati transitori (408, 429, 500, 502, 503, 504) con backoff esponenziale jitterato, rispettando l'header Retry-After del server quando presente. Gli errori deterministici (4xx come 401, 404, 422) non vengono mai riprovati. Imposta maxRetries: 0 per disabilitare i retry, oppure sovrascrivi per singola chiamata. Il ciclo di vita completo è descritto nei concetti SDK.

Errori

I metodi lanciano un'eccezione in caso di errore, con una gerarchia tipizzata che puoi restringere con instanceof. BirdError è la radice. BirdAPIError copre ogni risposta di errore dal server, con una sottoclasse per ogni type di errore. Tra queste: BirdAuthError (401), BirdRateLimitError (429, con retryAfter), BirdValidationError (422, con details per campo) e BirdPayloadTooLargeError (413). Gli errori di trasporto senza risposta HTTP usano le classi collaterali BirdConnectionError e BirdTimeoutError.

Esempio di codice

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;
}

Ogni BirdAPIError contiene statusCode, type, code (il codice di errore E##### stabile), requestId e docUrl. Usa la classe (o il type generico) come ramo nel flusso di controllo; usa code quando devi individuare un errore specifico. Preferisci ramificare su un valore invece di catturare? Ogni chiamata ha anche .safe():

Esempio di codice

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);

Webhook

bird.webhooks.unwrap(rawBody, headers) verifica la firma Standard Webhooks di una consegna in entrata e restituisce un evento tipizzato e discriminato. Passa il body grezzo della richiesta, perché il parsing e la ri-serializzazione modificano i byte firmati. Una firma non valida, un timestamp scaduto o header malformati lanciano BirdWebhookVerificationError. Consulta verifica dei webhook per il contratto cross-SDK e Webhook per la configurazione della piattaforma.

Prossimi passi

Quickstart email: usa send, get, list, i valori predefiniti del canale e le strutture di risposta.
Concetti SDK: scopri idempotenza, retry, paginazione, region e webhook in tutti gli SDK Bird.
Reference API: consulta le HTTP API sottostanti. bird.request<T>() raggiunge endpoint non ancora coperti dalla superficie tipizzata, con la stessa autenticazione, gli stessi retry e la stessa idempotenza.

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Ottieni un brief di implementazione