TypeScript SDK

@messagebird/sdk Bird API के लिए आधिकारिक TypeScript SDK है। यह पूरी तरह typed, केवल-ESM और edge-ready है। यह Node.js 20.3+ और आधुनिक edge runtimes (Cloudflare Workers, Vercel Edge, Deno) पर web-standard APIs (fetch, AbortSignal, Web Crypto) का उपयोग करके चलता है। यह पेज क्लाइंट को कवर करता है। SDK से ईमेल भेजने के लिए, TypeScript ईमेल quickstart से शुरू करें।

इंस्टॉल करें

कोड उदाहरण

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

पैकेज messagebird/bird-sdk-typescript से npm पर @messagebird/sdk के रूप में प्रकाशित है।

क्लाइंट बनाएँ

कोड उदाहरण

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

केवल apiKey आवश्यक है। रीजन key के bk_{region}_ प्रीफ़िक्स से अनुमानित होता है (bk_eu1_… key https://eu1.platform.bird.com पर रूट होती है), इसलिए अधिकतर क्लाइंट केवल key से बनाए जाते हैं। रिज़ॉल्यूशन नियमों के लिए रीजन अनुमान देखें। आप construction के समय चैनल डिफ़ॉल्ट भी सेट कर सकते हैं (उदाहरण के लिए email: { from: "hello@acme.com" } हर send पर from को वैकल्पिक बना देता है) और webhook signing secret webhooks: { secret } के ज़रिए सेट कर सकते हैं।

पहला कॉल

कोड उदाहरण

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 सीधे API परिणाम में resolve होता है, जो इस उदाहरण में अपनी em_* ID के साथ एक ईमेल संदेश है। चलाने योग्य walkthrough के लिए TypeScript quickstart अनुसरण करें।

दो-स्तरीय डिज़ाइन

SDK में एक generated लेयर और एक hand-owned लेयर है। Wire types और निचले स्तर की HTTP plumbing Bird की OpenAPI specification से generate होती है, जिससे request और response shapes कॉन्ट्रैक्ट के अनुरूप रहते हैं। Hand-written लेयर bird.email.send(...), retries, idempotency, pagination और errors प्रदान करती है। Wire fields snake_case (category, created_at) में पास होते हैं; SDK-defined identifiers, जैसे method names और idempotencyKey, camelCase का उपयोग करते हैं। Go और Python SDKs भी यही आर्किटेक्चर साझा करते हैं। विवरण के लिए SDK concepts देखें।

स्वचालित idempotency और retries

हर बदलाव करने वाले ऑपरेशन (POST, PUT, PATCH, DELETE) को अपने-आप बना Idempotency-Key हेडर मिलता है। SDK हर बार फिर से प्रयास करते समय उसी कुंजी का उपयोग करता है, ताकि मेल खाने वाले अनुरोध रखी गई प्रतिक्रिया दोबारा पा सकें। अलग-अलग SDK कॉल में कस्टम कुंजियों और प्रतिक्रिया दोबारा लौटाने की सीमाओं के लिए इडेम्पोटेंसी देखें।

Retries डिफ़ॉल्ट रूप से चालू हैं (maxRetries: 2)। क्लाइंट नेटवर्क विफलताओं, per-attempt timeouts और transient statuses (408, 429, 500, 502, 503, 504) पर jittered exponential backoff के साथ फिर से प्रयास करता है, और उपलब्ध होने पर सर्वर के Retry-After हेडर का सम्मान करता है। Deterministic विफलताएँ (4xx जैसे 401, 404, 422) कभी retry नहीं होतीं। अक्षम करने के लिए maxRetries: 0 सेट करें, या per call ओवरराइड करें। पूरा lifecycle SDK concepts में वर्णित है।

त्रुटियाँ

विफलता पर methods एक typed hierarchy throw करते हैं जिसे आप instanceof से narrow करते हैं। BirdError root है। BirdAPIError सर्वर से आने वाली हर त्रुटि प्रतिक्रिया को कवर करता है, प्रत्येक error type के लिए एक subclass के साथ। इनमें BirdAuthError (401), BirdRateLimitError (429, retryAfter के साथ), BirdValidationError (422, per-field details के साथ), और BirdPayloadTooLargeError (413) शामिल हैं। बिना HTTP response वाली transport विफलताएँ sibling classes BirdConnectionError और 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;
}

हर BirdAPIError में statusCode, type, code (स्थिर E##### error code), requestId, और docUrl होता है। control flow के लिए class (या coarse type) पर branch करें; किसी विशिष्ट विफलता से मिलान करने के लिए code का उपयोग करें। catch करने के बजाय value पर branch करना पसंद करते हैं? हर call में .safe() भी है:

कोड उदाहरण

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) एक inbound delivery के Standard Webhooks signature को सत्यापित करता है और एक typed, discriminated event लौटाता है। raw request body पास करें क्योंकि parse और re-serialize करने से signed bytes बदल जाते हैं। गलत signature, पुराना timestamp या विकृत headers BirdWebhookVerificationError throw करते हैं। cross-SDK कॉन्ट्रैक्ट के लिए webhook सत्यापन और प्लेटफ़ॉर्म सेटअप के लिए Webhooks देखें।

अगले कदम

ईमेल quickstart: send, get, list, चैनल डिफ़ॉल्ट और response shapes का उपयोग करें।
SDK concepts: सभी Bird SDKs में idempotency, retries, pagination, regions और webhooks के बारे में जानें।
API reference: अंतर्निहित HTTP API की समीक्षा करें। bird.request<T>() उन endpoints तक पहुँचता है जिन्हें typed surface अभी तक कवर नहीं करता, उसी authentication, retries और idempotency के साथ।

संबंधित संसाधन