@messagebird/sdk 0.1.1 → 0.2.1

package/README.md

@@ -2,6 +2,8 @@
 
 The official TypeScript SDK for the [Bird](https://bird.com) API — fully typed, edge-ready, ESM.
 
+📚 **Documentation:** https://bird.com/docs/sdks/typescript
+
 ## Requirements
 
 - **Node.js 20.3+** or a modern edge runtime (Cloudflare Workers, Vercel Edge, Deno). The SDK uses only web-standard APIs (`fetch`, `AbortSignal`, Web Crypto) and ships no Node built-ins.
@@ -17,19 +19,21 @@ pnpm add @messagebird/sdk
 
 ## Quickstart
 
+<!-- bird:snippet quickstart-email -->
+
 ```ts
 import { BirdClient } from "@messagebird/sdk";
 
 const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
 
-const email = await bird.email.send({
-  from: "hello@acme.com",
-  to: ["customer@example.com"],
-  subject: "Welcome aboard",
-  html: "<h1>Hi there</h1>",
+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(email.id);
+console.log(msg.id, msg.status);
 ```
 
 The region is inferred from the API key prefix (`bk_{region}_…`). For a local or self-hosted server, pass `baseUrl` (which overrides region resolution).
@@ -80,14 +84,22 @@ switch (event.type) {
 
 Methods **throw** on failure with a typed error hierarchy you narrow with `instanceof`:
 
+<!-- bird:snippet email.errors -->
+
 ```ts
-import { BirdRateLimitError, BirdValidationError } from "@messagebird/sdk";
+import { BirdRateLimitError, BirdValidationError, BirdAPIError } from "@messagebird/sdk";
 
 try {
-  await bird.email.send({ from, to, subject, html });
+  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) await sleep(err.retryAfter);
+  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;
 }
 ```
@@ -96,10 +108,19 @@ Every API error carries `statusCode`, `requestId`, and `type`. The core retries
 
 Prefer to branch on a value instead of catching? Use `.safe()`:
 
+<!-- bird:snippet email.safe -->
+
 ```ts
-const { data, error } = await bird.email.send({ from, to, subject, html }).safe();
-if (error) return; // data is null; error is a BirdError
-data.id; // narrowed
+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);
 ```
 
 And `.withResponse()` exposes transport metadata (status, headers, request id) on success: