@messagebird/sdk 0.29.0 → 0.31.0

package/README.md

@@ -67,7 +67,7 @@ for await (const message of bird.email.list()) {
 ## WhatsApp
 
 ```ts
-await bird.whatsapp.send({ to, template }); // resolves when accepted (202); Bird picks the sender from the template's category
+await bird.whatsapp.send({ to, template }); // resolves when accepted (202); `from` is required except for a Bird-managed template
 await bird.whatsapp.get(messageId); // delivery status + failure detail
 
 // `await` yields the first page; `for await` walks every message across pages.
@@ -78,6 +78,22 @@ for await (const message of bird.whatsapp.list()) {
 const { data } = await bird.whatsapp.listEvents(messageId); // full lifecycle timeline, not paginated
 ```
 
+## Lookup
+
+Every answer is billed. A phone number lookup bills once for the base answer plus once per **delivered** property; an email lookup bills once per answered address. Nothing is billed for a failed lookup, and nothing is billed for a property that came back unanswered, so read `status` before you read a value.
+
+```ts
+const number = await bird.lookup.phoneNumber({ phone_number, type: ["score"] });
+number.country_code; // base answer: always present, always billed
+if (number.score?.status === "ok") number.score.value; // only `ok` carries a value, and only `ok` is billed
+
+const address = await bird.lookup.email({ email });
+address.result; // valid | neutral | risky | undeliverable | typo: an open vocabulary
+address.delivery_confidence; // 0-100, always present: the safe fallback for a verdict you don't know
+```
+
+Pass an `Idempotency-Key` so a retry replays the stored answer instead of buying a second one.
+
 ## Webhooks
 
 `unwrap` verifies a delivery's Standard Webhooks signature and returns a typed, discriminated event. **Pass the raw request body** — never the parsed JSON. Set the signing secret once via `webhooks: { secret }` on the client (or pass `{ secret }` per call).
@@ -111,7 +127,7 @@ try {
     html: "<p>My first Bird email.</p>",
   });
 } catch (err) {
-  if (err instanceof BirdRateLimitError) console.log(`rate limited — retry in ${err.retryAfter}s`);
+  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;