TypeScript SDK

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

इंस्टॉल करें

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

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

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

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 आवश्यक है। क्षेत्र कुंजी के bk_{region}_ प्रीफ़िक्स से तय होता है (bk_eu1_… कुंजी https://eu1.platform.bird.com पर जाती है), इसलिए अधिकांश क्लाइंट केवल कुंजी से बनाए जाते हैं। निर्धारण के नियमों के लिए क्षेत्र अनुमान देखें। आप क्लाइंट बनाते समय चैनल डिफ़ॉल्ट भी सेट कर सकते हैं (उदाहरण के लिए, email: { from: "hello@acme.com" } सेट करने पर हर भेजने में from वैकल्पिक हो जाता है), और 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 परिणाम देता है, जो इस उदाहरण में अपनी em_* ID के साथ एक ईमेल संदेश है। चलाने योग्य चरण-दर-चरण उदाहरण के लिए TypeScript क्विकस्टार्ट देखें।

दो-परतों वाली संरचना

SDK में एक जनरेट की गई परत और एक हाथ से लिखी गई परत है। वायर टाइप और निचले स्तर की HTTP व्यवस्था Bird के OpenAPI विनिर्देश से जनरेट होती है, ताकि अनुरोध और प्रतिक्रिया की संरचना अनुबंध के अनुरूप रहे। हाथ से लिखी गई परत bird.email.send(...), फिर से प्रयास, आइडेम्पोटेंसी, पेजिनेशन और त्रुटियाँ प्रदान करती है। वायर फ़ील्ड snake_case (category, created_at) में ही आगे जाते हैं; SDK द्वारा परिभाषित पहचानकर्ता, जैसे मेथड नाम और idempotencyKey, camelCase का उपयोग करते हैं। Go और Python SDK भी यही संरचना अपनाते हैं। विवरण के लिए SDK अवधारणाएँ देखें।

स्वचालित आइडेम्पोटेंसी और फिर से प्रयास

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

फिर से प्रयास डिफ़ॉल्ट रूप से चालू रहते हैं (maxRetries: 2)। क्लाइंट नेटवर्क विफलताओं, हर प्रयास के टाइमआउट और अस्थायी स्थितियों (408, 429, 500, 502, 503, 504) पर जिटर वाले घातीय बैकऑफ़ के साथ फिर से प्रयास करता है। सर्वर का Retry-After हेडर मौजूद होने पर क्लाइंट उसका पालन करता है। निश्चित विफलताओं (401, 404, 422 जैसी 4xx) पर कभी फिर से प्रयास नहीं होता। बंद करने के लिए maxRetries: 0 सेट करें, या हर कॉल में इसे बदलें। पूरा जीवनचक्र SDK अवधारणाएँ में बताया गया है।

त्रुटियाँ

विफल होने पर मेथड टाइप की गई श्रेणीबद्ध त्रुटि फेंकते हैं, जिसे आप instanceof से सीमित करते हैं। BirdError मूल क्लास है। BirdAPIError सर्वर की हर त्रुटि प्रतिक्रिया को कवर करता है, और हर त्रुटि type के लिए एक उपक्लास है। इनमें BirdAuthError (401), BirdRateLimitError (429, retryAfter के साथ), BirdValidationError (422, हर फ़ील्ड के details के साथ) और BirdPayloadTooLargeError (413) शामिल हैं। जिन ट्रांसपोर्ट विफलताओं में कोई HTTP प्रतिक्रिया नहीं होती, उनके लिए सहोदर क्लास 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##### त्रुटि कोड), requestId और docUrl होते हैं। नियंत्रण प्रवाह के लिए क्लास (या मोटे type) के आधार पर शाखा बनाएँ। किसी एक खास विफलता से मिलान करना हो, तो code इस्तेमाल करें। अगर आप त्रुटि पकड़ने के बजाय किसी मान के आधार पर शाखा बनाना चाहते हैं, तो हर कॉल में .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);

वेबहुक

bird.webhooks.unwrap(rawBody, headers) आने वाली डिलीवरी के Standard Webhooks हस्ताक्षर की जाँच करता है और टाइप किया गया, भेदित इवेंट लौटाता है। अनुरोध की मूल बॉडी पास करें, क्योंकि उसे पार्स करके दोबारा सीरियलाइज़ करने से हस्ताक्षरित बाइट बदल जाते हैं। गलत हस्ताक्षर, पुराना टाइमस्टैम्प या गलत हेडर होने पर BirdWebhookVerificationError फेंका जाता है। सभी SDK में लागू अनुबंध के लिए वेबहुक सत्यापन और प्लेटफ़ॉर्म सेटअप के लिए वेबहुक देखें।

अगले कदम

• ईमेल क्विकस्टार्ट: send, get, list, चैनल डिफ़ॉल्ट और प्रतिक्रिया संरचनाओं का इस्तेमाल करें।
• SDK अवधारणाएँ: सभी Bird SDK में आइडेम्पोटेंसी, फिर से प्रयास, पेजिनेशन, क्षेत्रों और वेबहुक के बारे में जानें।
• API संदर्भ: अंतर्निहित HTTP API देखें। bird.request<T>() उन एंडपॉइंट तक पहुँचता है जिन्हें टाइप की गई सतह अभी कवर नहीं करती, और इसमें वही प्रमाणीकरण, फिर से प्रयास और आइडेम्पोटेंसी लागू होती है।