@eusend_dev/sdk 0.1.0

package/README.md

@@ -0,0 +1,536 @@
+# eusend
+
+Official Node.js SDK for the [Eusend](https://eusend.dev) API — the EU-native transactional email platform.
+
+```bash
+npm install @eusend_dev/sdk
+# or
+bun add @eusend_dev/sdk
+```
+
+---
+
+## Getting started
+
+```ts
+import { Eusend } from '@eusend_dev/sdk'
+
+const client = new Eusend('eu_live_...')
+```
+
+Your API key can also be set via the `EUSEND_API_KEY` environment variable, in which case the constructor argument can be omitted:
+
+```ts
+const client = new Eusend()
+```
+
+---
+
+## Emails
+
+### Send an email
+
+```ts
+const { data, error } = await client.emails.send({
+  from: 'you@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<p>Hello world</p>',
+  text: 'Hello world',
+})
+
+console.log(data?.id) // em_...
+```
+
+#### Options
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `from` | `string` | Sender email address |
+| `to` | `string \| string[]` | Recipient(s) |
+| `cc` | `string \| string[]` | CC recipient(s) |
+| `bcc` | `string \| string[]` | BCC recipient(s) |
+| `replyTo` | `string \| string[]` | Reply-to address(es) |
+| `subject` | `string` | Email subject |
+| `html` | `string` | HTML body |
+| `text` | `string` | Plain text body |
+| `templateId` | `string` | ID of a saved template |
+| `variables` | `Record<string, unknown>` | Template variable substitutions |
+| `headers` | `Record<string, string>` | Custom email headers |
+| `trackOpens` | `boolean` | Track open events (default: `true`) |
+| `trackClicks` | `boolean` | Track click events (default: `true`) |
+
+At least one of `html`, `text`, or `templateId` is required.
+
+### Idempotent sends
+
+Pass an `idempotencyKey` to safely retry without sending duplicates. If a request with the same key was already accepted, the original email ID is returned.
+
+```ts
+const { data } = await client.emails.send(
+  {
+    from: 'you@yourdomain.com',
+    to: 'user@example.com',
+    subject: 'Your receipt',
+    html: '<p>Thanks for your order.</p>',
+  },
+  { idempotencyKey: `receipt-${orderId}` },
+)
+```
+
+### Send a batch
+
+Up to 100 emails in a single request.
+
+```ts
+const { data } = await client.emails.batch([
+  {
+    from: 'you@yourdomain.com',
+    to: 'alice@example.com',
+    subject: 'Hello Alice',
+    html: '<p>Hi Alice</p>',
+  },
+  {
+    from: 'you@yourdomain.com',
+    to: 'bob@example.com',
+    subject: 'Hello Bob',
+    html: '<p>Hi Bob</p>',
+  },
+])
+
+console.log(data?.data) // [{ id: '...' }, { id: '...' }]
+```
+
+### Retrieve an email
+
+```ts
+const { data } = await client.emails.get('em_...')
+
+console.log(data?.status)  // 'delivered'
+console.log(data?.events)  // [{ type: 'sent', ... }, { type: 'delivered', ... }]
+```
+
+### List emails
+
+```ts
+const { data } = await client.emails.list({ limit: 20 })
+
+console.log(data?.data)       // array of emails
+console.log(data?.nextCursor) // pass as cursor to fetch the next page
+```
+
+#### Filtering
+
+```ts
+// By status
+await client.emails.list({ status: 'delivered' })
+
+// By sender
+await client.emails.list({ from: 'you@yourdomain.com' })
+
+// By recipient
+await client.emails.list({ to: 'user@example.com' })
+
+// Pagination
+await client.emails.list({ limit: 50, cursor: data.nextCursor })
+```
+
+Available statuses: `queued` `sending` `sent` `delivered` `bounced` `complained` `suppressed` `failed`
+
+---
+
+## Domains
+
+### Add a domain
+
+```ts
+const { data } = await client.domains.create('yourdomain.com')
+
+// DNS records to add to your domain
+console.log(data?.dkim)   // { type: 'TXT', name: 'eusend._domainkey.yourdomain.com', value: '...' }
+console.log(data?.spf)    // { type: 'TXT', name: 'yourdomain.com', value: '...' }
+console.log(data?.dmarc)  // { type: 'TXT', name: '_dmarc.yourdomain.com', value: '...' }
+```
+
+### Verify a domain
+
+After adding the DNS records, trigger verification:
+
+```ts
+await client.domains.verify(domainId)
+```
+
+### List domains
+
+```ts
+const { data } = await client.domains.list()
+// [{ id, name, status: 'verified', createdAt }]
+```
+
+### Get a domain
+
+```ts
+const { data } = await client.domains.get(domainId)
+// { id, name, dkimPublicKey, dkimSelector, status, createdAt, verifiedAt }
+```
+
+### Delete a domain
+
+```ts
+await client.domains.delete(domainId)
+```
+
+---
+
+## API Keys
+
+### Create an API key
+
+```ts
+const { data } = await client.apiKeys.create({ name: 'Production' })
+
+console.log(data?.key) // eu_live_... — only returned once, store it securely
+```
+
+Pass `testMode: true` to create a sandbox key. Emails sent with a test key are accepted and tracked but never delivered.
+
+```ts
+const { data } = await client.apiKeys.create({ name: 'Sandbox', testMode: true })
+// data.key → 'eu_test_...'
+```
+
+### List API keys
+
+```ts
+const { data } = await client.apiKeys.list()
+// [{ id, name, prefix, testMode, createdAt, lastUsedAt }]
+```
+
+The full key is never returned after creation — only the prefix (e.g. `eu_live_Lx_e`).
+
+### Delete an API key
+
+```ts
+await client.apiKeys.delete(keyId)
+```
+
+---
+
+## Audiences & Contacts
+
+### Create an audience
+
+```ts
+const { data } = await client.audiences.create('Newsletter')
+const audienceId = data!.id
+```
+
+### List audiences
+
+```ts
+const { data } = await client.audiences.list()
+// [{ id, name, createdAt, contactCount }]
+```
+
+### Delete an audience
+
+```ts
+await client.audiences.delete(audienceId)
+```
+
+### Add a contact
+
+```ts
+const { data } = await client.audiences.createContact(audienceId, {
+  email: 'user@example.com',
+  firstName: 'Jane',
+  lastName: 'Smith',
+})
+```
+
+If a contact with that email already exists in the audience, it will be updated instead.
+
+### Bulk import contacts
+
+Up to 1,000 contacts per call. Existing contacts are upserted.
+
+```ts
+const { data } = await client.audiences.batchCreateContacts(audienceId, {
+  contacts: [
+    { email: 'alice@example.com', firstName: 'Alice' },
+    { email: 'bob@example.com', firstName: 'Bob' },
+  ],
+})
+
+console.log(data?.count) // 2
+```
+
+### List contacts
+
+```ts
+const { data } = await client.audiences.listContacts(audienceId, { limit: 100 })
+
+// Filter by subscription status
+await client.audiences.listContacts(audienceId, { subscribed: true })
+await client.audiences.listContacts(audienceId, { subscribed: false })
+
+// Search by email
+await client.audiences.listContacts(audienceId, { search: 'gmail.com' })
+
+// Pagination
+await client.audiences.listContacts(audienceId, { cursor: data.nextCursor })
+```
+
+### Get a contact
+
+```ts
+const { data } = await client.audiences.getContact(audienceId, contactId)
+// { id, audienceId, email, firstName, lastName, status, unsubscribedAt, createdAt, updatedAt }
+```
+
+### Update a contact
+
+```ts
+// Update name
+await client.audiences.updateContact(audienceId, contactId, {
+  firstName: 'Janet',
+})
+
+// Unsubscribe
+await client.audiences.updateContact(audienceId, contactId, {
+  unsubscribed: true,
+})
+
+// Re-subscribe
+await client.audiences.updateContact(audienceId, contactId, {
+  unsubscribed: false,
+})
+```
+
+### Delete a contact
+
+```ts
+await client.audiences.deleteContact(audienceId, contactId)
+```
+
+---
+
+## Templates
+
+Templates let you define reusable email layouts with `{{variable}}` placeholders that are substituted at send time.
+
+### Create a template (HTML)
+
+```ts
+const { data } = await client.templates.create({
+  name: 'Welcome email',
+  subject: 'Welcome, {{name}}!',
+  html: '<h1>Hi {{name}}</h1><p>Welcome to {{product}}.</p>',
+})
+```
+
+### Create a template (React)
+
+Pass JSX using `@react-email/components`. The server renders it to email-safe HTML at save time, with `{{variable}}` placeholders preserved for send-time substitution.
+
+```ts
+const { data } = await client.templates.create({
+  name: 'Order confirmation',
+  subject: 'Your order {{order_id}} is confirmed',
+  reactSource: `
+<Html>
+  <Head />
+  <Preview>Order {{order_id}} confirmed</Preview>
+  <Body style={{ backgroundColor: '#f4f4f5', fontFamily: 'system-ui, sans-serif' }}>
+    <Container style={{ maxWidth: '520px', margin: '40px auto', backgroundColor: '#fff', borderRadius: '8px' }}>
+      <Section style={{ padding: '32px' }}>
+        <Heading>Order confirmed ✓</Heading>
+        <Text>Hi {{first_name}}, your order <strong>{{order_id}}</strong> is on its way.</Text>
+        <Button href="https://yourapp.com/orders/{{order_id}}">View order</Button>
+      </Section>
+    </Container>
+  </Body>
+</Html>`,
+})
+```
+
+### Send using a template
+
+```ts
+await client.emails.send({
+  from: 'you@yourdomain.com',
+  to: 'user@example.com',
+  templateId: data!.id,
+  variables: {
+    first_name: 'Jane',
+    order_id: 'ORD-1234',
+  },
+})
+```
+
+### List, get, update, delete
+
+```ts
+await client.templates.list()
+await client.templates.get(templateId)
+await client.templates.update(templateId, { name: 'New name', subject: 'New subject' })
+await client.templates.delete(templateId)
+```
+
+---
+
+## Webhooks
+
+Receive real-time events when email statuses change.
+
+### Create a webhook
+
+```ts
+const { data } = await client.webhooks.create({
+  url: 'https://yourapp.com/webhooks/eusend',
+  events: ['email.sent', 'email.delivered', 'email.bounced', 'email.complained'],
+})
+
+console.log(data?.secret) // signing secret — only returned once, store it securely
+```
+
+Pass `'*'` in the events array to subscribe to all events.
+
+Available events: `email.sent` `email.delivered` `email.bounced` `email.complained` `email.opened` `email.clicked`
+
+### Verifying webhook signatures
+
+Every delivery is signed with HMAC-SHA256. Verify the signature before processing:
+
+```ts
+import { createHmac, timingSafeEqual } from 'crypto'
+
+function verifyWebhook(req: Request, secret: string): boolean {
+  const webhookId = req.headers.get('x-webhook-id') ?? ''
+  const timestamp = req.headers.get('x-webhook-timestamp') ?? ''
+  const signature = req.headers.get('x-webhook-signature') ?? ''
+
+  const body = await req.text()
+  const expected = 'v1,' + createHmac('sha256', secret)
+    .update(`${webhookId}.${timestamp}.${body}`)
+    .digest('base64')
+
+  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
+}
+```
+
+### List, get, update, delete
+
+```ts
+await client.webhooks.list()
+await client.webhooks.get(webhookId)    // includes recent deliveries
+await client.webhooks.update(webhookId, { events: ['email.bounced'] })
+await client.webhooks.delete(webhookId)
+```
+
+---
+
+## Broadcasts
+
+Send a single email to every contact in an audience.
+
+### Create a broadcast
+
+```ts
+const { data } = await client.broadcasts.create({
+  name: 'May newsletter',
+  audienceId: 'aud_...',
+  from: 'Sivert <hello@yourdomain.com>',
+  subject: 'May update',
+  html: '<p>Hi {{first_name}}, here is this month's update...</p>',
+})
+```
+
+`{{first_name}}`, `{{last_name}}`, `{{full_name}}`, and `{{email}}` are automatically available per recipient. Custom variables can be defined on the broadcast and are merged with per-recipient data.
+
+### Send a broadcast
+
+```ts
+await client.broadcasts.send(broadcastId)
+```
+
+### Schedule a broadcast
+
+```ts
+await client.broadcasts.send(broadcastId, {
+  scheduledAt: '2026-06-01T09:00:00.000Z',
+})
+```
+
+### Cancel a broadcast
+
+```ts
+await client.broadcasts.cancel(broadcastId)
+```
+
+### List, get, update, delete
+
+```ts
+await client.broadcasts.list()
+await client.broadcasts.get(broadcastId)   // includes delivery stats
+await client.broadcasts.update(broadcastId, { subject: 'Updated subject' })
+await client.broadcasts.delete(broadcastId)
+```
+
+---
+
+## Error handling
+
+Every method returns `{ data, error, headers }`. On success `error` is `null`; on failure `data` is `null`.
+
+```ts
+const { data, error } = await client.emails.send({ ... })
+
+if (error) {
+  console.error(error.name)       // 'MONTHLY_LIMIT_EXCEEDED'
+  console.error(error.message)    // 'Monthly send limit exceeded'
+  console.error(error.statusCode) // 429
+} else {
+  console.log(data.id)
+}
+```
+
+#### Error codes
+
+| Code | Status | Description |
+|------|--------|-------------|
+| `UNAUTHORIZED` | 401 | Invalid or missing API key |
+| `FORBIDDEN` | 403 | Action not allowed on your plan |
+| `NOT_FOUND` | 404 | Resource not found |
+| `VALIDATION_ERROR` | 400 | Invalid request body |
+| `CONFLICT` | 409 | Resource already exists |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `MONTHLY_LIMIT_EXCEEDED` | 429 | Monthly send quota reached |
+| `DAILY_LIMIT_EXCEEDED` | 429 | Daily send quota reached (free plan) |
+| `PLAN_LIMIT_EXCEEDED` | 403 | Feature not available on your plan |
+| `ALL_SUPPRESSED` | 422 | All recipients are on the suppression list |
+| `INTERNAL_ERROR` | 500 | Server error |
+| `application_error` | `null` | Network failure — request never reached the server |
+
+---
+
+## TypeScript
+
+The SDK is written in TypeScript and ships with full type definitions. All request options, response shapes, and error codes are typed.
+
+```ts
+import type {
+  SendEmailOptions,
+  Email,
+  EmailStatus,
+  EusendError,
+  EusendResponse,
+} from '@eusend_dev/sdk'
+```
+
+---
+
+## Requirements
+
+- Node.js 18 or later (uses the native `fetch` API)
+- An Eusend account and API key — [eusend.dev](https://eusend.dev)