mailerbot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MailerBot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +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