mailerbot 0.1.0 → 0.1.1

package/README.md

@@ -1,290 +1,290 @@
-# MailerBot Node.js SDK
-
-Official TypeScript/JavaScript SDK for the [MailerBot](https://mailerbot.com) direct mail API. Send letters and postcards programmatically.
-
-## Installation
-
-```bash
-npm install mailerbot
-```
-
-Requires Node.js 18+ (uses native `fetch`).
-
-## Authentication
-
-Generate an API key in your [MailerBot dashboard](https://app.mailerbot.com/settings/api-keys), then pass it to the client:
-
-```ts
-import { MailerBot } from "mailerbot";
-
-const client = new MailerBot("mb_live_...");
-```
-
-## Quick Start
-
-```ts
-import { MailerBot } from "mailerbot";
-
-const client = new MailerBot("mb_live_...");
-
-// List contacts
-const page = await client.contacts.list({ page: 1, pageSize: 25 });
-console.log(`${page.total} total contacts`);
-for (const contact of page.items) {
-  console.log(`  ${contact.firstName} ${contact.lastName}, ${contact.city}, ${contact.state}`);
-}
-
-// Dashboard stats
-const stats = await client.dashboard.stats();
-console.log(`Letters sent: ${stats.lettersSent}`);
-console.log(`Total spent: $${stats.totalSpent.toFixed(2)}`);
-```
-
-## Common Workflows
-
-### Create and send a letter mailing
-
-```ts
-import { MailerBot } from "mailerbot";
-
-const client = new MailerBot("mb_live_...");
-
-// 1. Create a contact list
-const contactList = await client.contactLists.create("My Campaign List");
-
-// 2. Add contacts (countryCode defaults to "US" if omitted)
-const contact = await client.contacts.create({
-  firstName: "Jane",
-  lastName: "Smith",
-  addressLine1: "123 Main St",
-  city: "Austin",
-  state: "TX",
-  zip: "78701",
-});
-await client.contactLists.addContacts(contactList.id, [contact.id]);
-
-// 3. Write a letter document
-const doc = await client.documents.create({
-  title: "Spring Promo Letter",
-  content: "<p>Dear {{first_name}},</p><p>Check out our spring deals!</p>",
-});
-
-// 4. Create the mailing (postage defaults to cheapest rate per zone)
-const mailing = await client.mailings.create({
-  name: "Spring 2026 Promo",
-  type: "letter",
-  contactListId: contactList.id,
-  documentId: doc.id,
-});
-
-// 5. Review the cost
-const cost = await client.mailings.calculateCost(mailing.id);
-console.log(`Product cost: $${cost.totalProductCost.toFixed(2)} (${cost.recipientCount} recipients)`);
-for (const zone of cost.zoneCounts) {
-  console.log(`  ${zone.postageZoneName}: ${zone.recipientCount} recipients`);
-}
-
-// 6. Create a Stripe payment intent, complete payment on your end, then send
-const intent = await client.payments.createPaymentIntent(mailing.id);
-// ... complete Stripe payment using intent.clientSecret ...
-
-// 7. Send
-const sent = await client.mailings.send(mailing.id);
-console.log(`Mailing status: ${sent.status}`);
-```
-
-### Bulk import contacts from CSV data
-
-```ts
-const result = await client.contacts.importCsv(
-  [
-    { firstName: "Alice", lastName: "Wu", addressLine1: "456 Oak Ave",
-      city: "Dallas", state: "TX", zip: "75201" },
-    { firstName: "Bob", lastName: "Smith", addressLine1: "789 Pine Rd",
-      city: "Houston", state: "TX", zip: "77001" },
-  ],
-  { listName: "Imported List" },
-);
-console.log(`Imported ${result.importedCount} contacts into list ${result.listId}`);
-```
-
-### International contacts
-
-```ts
-// List available countries
-const countries = await client.pricing.countries();
-for (const c of countries) {
-  console.log(`  ${c.code} — ${c.name} (active: ${c.isActive})`);
-}
-
-// Create a Canadian contact
-const contact = await client.contacts.create({
-  firstName: "Marie",
-  lastName: "Tremblay",
-  addressLine1: "350 Rue Saint-Paul",
-  city: "Montréal",
-  state: "QC",
-  zip: "H2Y 1H2",
-  countryCode: "CA",
-});
-```
-
-### Estimate cost before creating a mailing
-
-```ts
-const cost = await client.mailings.estimateCost({
-  type: "postcard",
-  contactListId: "<list_id>",
-});
-console.log(`Product cost: $${cost.totalProductCost.toFixed(2)}`);
-for (const zone of cost.zoneCounts) {
-  console.log(`  ${zone.postageZoneName}: ${zone.recipientCount} recipients`);
-}
-for (const u of cost.unavailable) {
-  console.log(`  ⚠ ${u.countryName}: ${u.recipientCount} recipients (${u.reason})`);
-}
-
-// See available postage rates
-const rates = await client.pricing.postageRates({ productType: "postcard" });
-for (const r of rates) {
-  console.log(`  ${r.postageZoneName} — ${r.label}: $${r.costPerPiece}`);
-}
-```
-
-### Iterate over all contacts (auto-pagination)
-
-```ts
-for await (const contact of client.contacts.iterAll({ pageSize: 100 })) {
-  console.log(contact.firstName, contact.lastName);
-}
-```
-
-### Send a postcard mailing
-
-```ts
-// Browse available templates
-const templates = await client.postcards.listTemplates();
-console.log(`${templates.length} templates available`);
-
-// Create a postcard from scratch (or use the canvas builder in the dashboard)
-const postcard = await client.postcards.create({ title: "Summer Sale Card" });
-
-const mailing = await client.mailings.create({
-  name: "Summer Postcard Drop",
-  type: "postcard",
-  contactListId: "<list_id>",
-  postcardId: postcard.id,
-});
-const cost = await client.mailings.calculateCost(mailing.id);
-console.log(`$${cost.totalProductCost.toFixed(2)} for ${cost.recipientCount} postcards`);
-```
-
-### Track QR code scans
-
-```ts
-// Create a trackable short link
-const link = await client.qr.create({ destinationUrl: "https://yoursite.com/promo" });
-console.log(`Short URL: ${link.shortUrl}`);
-
-// Get analytics
-const analytics = await client.qr.analytics({ days: 30 });
-console.log(`${analytics.totalScans} scans across ${analytics.uniqueLinks} links`);
-for (const day of analytics.scansByDay) {
-  console.log(`  ${day.date}: ${day.count} scans`);
-}
-```
-
-### Track USPS delivery per piece
-
-```ts
-const mailing = await client.mailings.get("<mailing_id>");
-console.log(`${mailing.itemsDelivered}/${mailing.itemCount} delivered, ${mailing.itemsReturned} returned`);
-
-// Pieces USPS flagged as return-to-sender (filter: none, in_transit,
-// out_for_delivery, forwarded, delivered, returned)
-for await (const item of client.mailings.iterItems(mailing.id, { trackingStatus: "returned" })) {
-  console.log(`${item.recipientName}: ${item.lastScanLabel} at ${item.lastScanLocation}`);
-}
-
-// Full scan history for one piece
-const page = await client.mailings.listItems(mailing.id, { pageSize: 1 });
-for (const scan of await client.mailings.listItemScans(mailing.id, page.items[0].id)) {
-  console.log(`  ${scan.scanDatetime} ${scan.label} (${scan.facilityCity}, ${scan.facilityState})`);
-}
-```
-
-Or subscribe to the `mail_delivered` and `mail_returned` webhook events to be pushed these updates instead of polling.
-
-### Use coupon codes in mailings
-
-```ts
-// Create a coupon list and import codes
-const couponList = await client.coupons.create("Spring Sale Coupons");
-const result = await client.coupons.importCodes(couponList.id, ["SAVE10", "SAVE20", "SAVE30"]);
-console.log(`Imported ${result.importedCount} codes`);
-
-// Check there are enough codes before sending
-const avail = await client.coupons.checkAvailability(couponList.id, 500);
-if (!avail.sufficient) {
-  console.log(`Only ${avail.availableCodes} codes available, need 500`);
-}
-
-// Attach to a mailing — each recipient gets a unique code
-const mailing = await client.mailings.create({
-  name: "Spring Promo",
-  type: "letter",
-  contactListId: "<list_id>",
-  documentId: "<doc_id>",
-  couponListId: couponList.id,
-});
-```
-
-## Error Handling
-
-```ts
-import { MailerBot, AuthenticationError, NotFoundError, ValidationError, MailerBotError } from "mailerbot";
-
-try {
-  const client = new MailerBot("bad_key");
-  await client.contacts.list();
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.log(`Auth failed: ${error.message}`);
-  } else if (error instanceof NotFoundError) {
-    console.log(`Resource not found: ${error.message}`);
-  } else if (error instanceof ValidationError) {
-    console.log(`Bad request: ${error.message}`, error.response);
-  } else if (error instanceof MailerBotError) {
-    console.log(`API error ${error.statusCode}: ${error.message}`);
-  }
-}
-```
-
-### Exception hierarchy
-
-| Error class | HTTP status |
-|---|---|
-| `AuthenticationError` | 401 |
-| `PermissionError` | 403 |
-| `NotFoundError` | 404 |
-| `ValidationError` | 422 |
-| `RateLimitError` | 429 |
-| `ServerError` | 5xx |
-| `MailerBotError` | base class / other |
-
-## Configuration
-
-```ts
-const client = new MailerBot("mb_live_...", {
-  baseUrl: "https://api.mailerbot.com/api/v1", // default
-  timeout: 30_000,                              // milliseconds, default 30000
-});
-```
-
-## Full API Reference
-
-See [https://mailerbot.com/docs](https://mailerbot.com/docs) for complete endpoint documentation.
-
-## License
-
-MIT
+# MailerBot Node.js SDK
+
+Official TypeScript/JavaScript SDK for the [MailerBot](https://mailerbot.com) direct mail API. Send letters and postcards programmatically.
+
+## Installation
+
+```bash
+npm install mailerbot
+```
+
+Requires Node.js 18+ (uses native `fetch`).
+
+## Authentication
+
+Generate an API key in your [MailerBot dashboard](https://app.mailerbot.com/settings/api-keys), then pass it to the client:
+
+```ts
+import { MailerBot } from "mailerbot";
+
+const client = new MailerBot("mb_live_...");
+```
+
+## Quick Start
+
+```ts
+import { MailerBot } from "mailerbot";
+
+const client = new MailerBot("mb_live_...");
+
+// List contacts
+const page = await client.contacts.list({ page: 1, pageSize: 25 });
+console.log(`${page.total} total contacts`);
+for (const contact of page.items) {
+  console.log(`  ${contact.firstName} ${contact.lastName}, ${contact.city}, ${contact.state}`);
+}
+
+// Dashboard stats
+const stats = await client.dashboard.stats();
+console.log(`Letters sent: ${stats.lettersSent}`);
+console.log(`Total spent: $${stats.totalSpent.toFixed(2)}`);
+```
+
+## Common Workflows
+
+### Create and send a letter mailing
+
+```ts
+import { MailerBot } from "mailerbot";
+
+const client = new MailerBot("mb_live_...");
+
+// 1. Create a contact list
+const contactList = await client.contactLists.create("My Campaign List");
+
+// 2. Add contacts (countryCode defaults to "US" if omitted)
+const contact = await client.contacts.create({
+  firstName: "Jane",
+  lastName: "Smith",
+  addressLine1: "123 Main St",
+  city: "Austin",
+  state: "TX",
+  zip: "78701",
+});
+await client.contactLists.addContacts(contactList.id, [contact.id]);
+
+// 3. Write a letter document
+const doc = await client.documents.create({
+  title: "Spring Promo Letter",
+  content: "<p>Dear {{first_name}},</p><p>Check out our spring deals!</p>",
+});
+
+// 4. Create the mailing (postage defaults to cheapest rate per zone)
+const mailing = await client.mailings.create({
+  name: "Spring 2026 Promo",
+  type: "letter",
+  contactListId: contactList.id,
+  documentId: doc.id,
+});
+
+// 5. Review the cost
+const cost = await client.mailings.calculateCost(mailing.id);
+console.log(`Product cost: $${cost.totalProductCost.toFixed(2)} (${cost.recipientCount} recipients)`);
+for (const zone of cost.zoneCounts) {
+  console.log(`  ${zone.postageZoneName}: ${zone.recipientCount} recipients`);
+}
+
+// 6. Create a Stripe payment intent, complete payment on your end, then send
+const intent = await client.payments.createPaymentIntent(mailing.id);
+// ... complete Stripe payment using intent.clientSecret ...
+
+// 7. Send
+const sent = await client.mailings.send(mailing.id);
+console.log(`Mailing status: ${sent.status}`);
+```
+
+### Bulk import contacts from CSV data
+
+```ts
+const result = await client.contacts.importCsv(
+  [
+    { firstName: "Alice", lastName: "Wu", addressLine1: "456 Oak Ave",
+      city: "Dallas", state: "TX", zip: "75201" },
+    { firstName: "Bob", lastName: "Smith", addressLine1: "789 Pine Rd",
+      city: "Houston", state: "TX", zip: "77001" },
+  ],
+  { listName: "Imported List" },
+);
+console.log(`Imported ${result.importedCount} contacts into list ${result.listId}`);
+```
+
+### International contacts
+
+```ts
+// List available countries
+const countries = await client.pricing.countries();
+for (const c of countries) {
+  console.log(`  ${c.code} — ${c.name} (active: ${c.isActive})`);
+}
+
+// Create a Canadian contact
+const contact = await client.contacts.create({
+  firstName: "Marie",
+  lastName: "Tremblay",
+  addressLine1: "350 Rue Saint-Paul",
+  city: "Montréal",
+  state: "QC",
+  zip: "H2Y 1H2",
+  countryCode: "CA",
+});
+```
+
+### Estimate cost before creating a mailing
+
+```ts
+const cost = await client.mailings.estimateCost({
+  type: "postcard",
+  contactListId: "<list_id>",
+});
+console.log(`Product cost: $${cost.totalProductCost.toFixed(2)}`);
+for (const zone of cost.zoneCounts) {
+  console.log(`  ${zone.postageZoneName}: ${zone.recipientCount} recipients`);
+}
+for (const u of cost.unavailable) {
+  console.log(`  ⚠ ${u.countryName}: ${u.recipientCount} recipients (${u.reason})`);
+}
+
+// See available postage rates
+const rates = await client.pricing.postageRates({ productType: "postcard" });
+for (const r of rates) {
+  console.log(`  ${r.postageZoneName} — ${r.label}: $${r.costPerPiece}`);
+}
+```
+
+### Iterate over all contacts (auto-pagination)
+
+```ts
+for await (const contact of client.contacts.iterAll({ pageSize: 100 })) {
+  console.log(contact.firstName, contact.lastName);
+}
+```
+
+### Send a postcard mailing
+
+```ts
+// Browse available templates
+const templates = await client.postcards.listTemplates();
+console.log(`${templates.length} templates available`);
+
+// Create a postcard from scratch (or use the canvas builder in the dashboard)
+const postcard = await client.postcards.create({ title: "Summer Sale Card" });
+
+const mailing = await client.mailings.create({
+  name: "Summer Postcard Drop",
+  type: "postcard",
+  contactListId: "<list_id>",
+  postcardId: postcard.id,
+});
+const cost = await client.mailings.calculateCost(mailing.id);
+console.log(`$${cost.totalProductCost.toFixed(2)} for ${cost.recipientCount} postcards`);
+```
+
+### Track QR code scans
+
+```ts
+// Create a trackable short link
+const link = await client.qr.create({ destinationUrl: "https://yoursite.com/promo" });
+console.log(`Short URL: ${link.shortUrl}`);
+
+// Get analytics
+const analytics = await client.qr.analytics({ days: 30 });
+console.log(`${analytics.totalScans} scans across ${analytics.uniqueLinks} links`);
+for (const day of analytics.scansByDay) {
+  console.log(`  ${day.date}: ${day.count} scans`);
+}
+```
+
+### Track USPS delivery per piece
+
+```ts
+const mailing = await client.mailings.get("<mailing_id>");
+console.log(`${mailing.itemsDelivered}/${mailing.itemCount} delivered, ${mailing.itemsReturned} returned`);
+
+// Pieces USPS flagged as return-to-sender (filter: none, in_transit,
+// out_for_delivery, forwarded, delivered, returned)
+for await (const item of client.mailings.iterItems(mailing.id, { trackingStatus: "returned" })) {
+  console.log(`${item.recipientName}: ${item.lastScanLabel} at ${item.lastScanLocation}`);
+}
+
+// Full scan history for one piece
+const page = await client.mailings.listItems(mailing.id, { pageSize: 1 });
+for (const scan of await client.mailings.listItemScans(mailing.id, page.items[0].id)) {
+  console.log(`  ${scan.scanDatetime} ${scan.label} (${scan.facilityCity}, ${scan.facilityState})`);
+}
+```
+
+Or subscribe to the `mail_delivered` and `mail_returned` webhook events to be pushed these updates instead of polling.
+
+### Use coupon codes in mailings
+
+```ts
+// Create a coupon list and import codes
+const couponList = await client.coupons.create("Spring Sale Coupons");
+const result = await client.coupons.importCodes(couponList.id, ["SAVE10", "SAVE20", "SAVE30"]);
+console.log(`Imported ${result.importedCount} codes`);
+
+// Check there are enough codes before sending
+const avail = await client.coupons.checkAvailability(couponList.id, 500);
+if (!avail.sufficient) {
+  console.log(`Only ${avail.availableCodes} codes available, need 500`);
+}
+
+// Attach to a mailing — each recipient gets a unique code
+const mailing = await client.mailings.create({
+  name: "Spring Promo",
+  type: "letter",
+  contactListId: "<list_id>",
+  documentId: "<doc_id>",
+  couponListId: couponList.id,
+});
+```
+
+## Error Handling
+
+```ts
+import { MailerBot, AuthenticationError, NotFoundError, ValidationError, MailerBotError } from "mailerbot";
+
+try {
+  const client = new MailerBot("bad_key");
+  await client.contacts.list();
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.log(`Auth failed: ${error.message}`);
+  } else if (error instanceof NotFoundError) {
+    console.log(`Resource not found: ${error.message}`);
+  } else if (error instanceof ValidationError) {
+    console.log(`Bad request: ${error.message}`, error.response);
+  } else if (error instanceof MailerBotError) {
+    console.log(`API error ${error.statusCode}: ${error.message}`);
+  }
+}
+```
+
+### Exception hierarchy
+
+| Error class | HTTP status |
+|---|---|
+| `AuthenticationError` | 401 |
+| `PermissionError` | 403 |
+| `NotFoundError` | 404 |
+| `ValidationError` | 422 |
+| `RateLimitError` | 429 |
+| `ServerError` | 5xx |
+| `MailerBotError` | base class / other |
+
+## Configuration
+
+```ts
+const client = new MailerBot("mb_live_...", {
+  baseUrl: "https://api.mailerbot.com/api/v1", // default
+  timeout: 30_000,                              // milliseconds, default 30000
+});
+```
+
+## Full API Reference
+
+See [https://mailerbot.com/docs](https://mailerbot.com/docs) for complete endpoint documentation.
+
+## License
+
+MIT