Quickstart

/**
 * Courier agent quick reference (Node.js)
 *
 * Setup:
 *   npm install @trycourier/courier
 *   export COURIER_API_KEY="your-api-key"
 *
 * Core endpoints:
 *   POST /send
 *   POST /profiles/{user_id} (merge profile)
 *   PUT  /profiles/{user_id} (replace entire profile)
 *   POST /auth/issue-token
 *
 * Error/status patterns:
 *   401 Unauthorized -> invalid/missing API key
 *   UNDELIVERABLE -> invalid recipient or blocked domain
 *   UNROUTABLE -> no provider or missing profile channel data
 *   UNMAPPED -> missing template id
 *
 * Guardrails:
 *   - Use POST /profiles/{user_id} for updates; PUT replaces and can delete fields.
 *   - Use method:"single" for transactional sends (OTP/billing), method:"all" for fanout.
 *   - Pass Idempotency-Key via headers; do not rely on idempotencyKey option.
 */
import Courier from "@trycourier/courier";

const client = new Courier(); // Reads COURIER_API_KEY

// 1) Merge a user profile
await client.profiles.create("user-123", {
  profile: {
    email: "alice@example.com",
    name: "Alice",
    phone_number: "+14155550123",
  },
});

// 2) Send transactional email with idempotency
const transactional = await client.send.message(
  {
    message: {
      to: { user_id: "user-123" },
      content: {
        title: "Your order shipped",
        body: "Order #{{orderId}} is on its way.",
      },
      data: { orderId: "ORD-456" },
      routing: { method: "single", channels: ["email", "sms"] },
    },
  },
  { headers: { "Idempotency-Key": "order-ORD-456-user-123" } }
);

// 3) Send informational fanout to email + inbox
await client.send.message({
  message: {
    to: { user_id: "user-123" },
    content: {
      title: "New activity",
      body: "Your weekly summary is ready.",
    },
    routing: { method: "all", channels: ["email", "inbox"] },
  },
});

// 4) Issue JWT for Inbox client auth
const { token } = await client.auth.issueToken({
  scope: "user_id:user-123 inbox:read:messages inbox:write:events",
  expires_in: "1 day",
});

console.log({ requestId: transactional.requestId, inboxJwt: token });