@develemail/sdk 0.1.1 → 0.4.1

package/README.md

@@ -0,0 +1,211 @@
+# @develemail/sdk
+
+Node.js/TypeScript client SDK for the DevelEmail transactional email API. Zero runtime dependencies — uses the global `fetch` API (Node >= 18).
+
+## Quickstart
+
+```ts
+import { DevelEmail } from '@develemail/sdk';
+
+const client = new DevelEmail({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://your-develemail-instance.com',
+});
+
+// Send an email
+const { id, status } = await client.emails.send({
+  from: 'hello@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Welcome!',
+  html: '<h1>Hello!</h1>',
+});
+
+// Check delivery status
+const email = await client.emails.get(id);
+console.log(email.status); // 'queued' | 'delivered' | ...
+```
+
+## Batch send
+
+```ts
+const result = await client.emails.batch([
+  {
+    from: 'hello@yourdomain.com',
+    to: 'a@example.com',
+    subject: 'Hi',
+    text: 'Hello A',
+  },
+  {
+    from: 'hello@yourdomain.com',
+    to: 'b@example.com',
+    subject: 'Hi',
+    text: 'Hello B',
+  },
+]);
+
+console.log(result.created); // 2
+console.log(result.errors); // 0
+```
+
+A failed item carries a stable, machine-readable `code` next to its `error`
+message, so you can retry selectively without matching English text:
+`domain_not_verified`, `reserved_recipient_domain`, `mixed_sandbox_recipients`,
+`recipient_cooldown`, `daily_limit_reached`, `attachment_too_large`,
+`attachment_type_blocked`, `invalid_attachment`, `invalid_sender_domain`,
+`template_not_found`, `missing_subject`, and `send_failed` for anything else.
+
+## Attachments
+
+Pass a `Buffer`/`Uint8Array` for `content` and the SDK base64-encodes it for
+you — or pass an already-base64 `string` directly. Server caps: max 10
+attachments per email, 5 MiB per file, 7 MiB combined decoded size.
+
+```ts
+import { readFile } from 'node:fs/promises';
+
+const csv = await readFile('export.csv');
+
+await client.emails.send({
+  from: 'hello@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Your export is ready',
+  text: 'Attached: export.csv',
+  attachments: [
+    { filename: 'export.csv', content: csv, contentType: 'text/csv' },
+  ],
+});
+```
+
+## Automatic retry + idempotency
+
+Sends automatically retry on network errors, 5xx, and 429 responses with exponential backoff. Each send generates a unique `Idempotency-Key` header so retries never produce duplicate emails.
+
+```ts
+// Custom retry count (default: 3)
+const client = new DevelEmail({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://your-instance.com',
+  maxRetries: 5,
+});
+
+// Supply your own idempotency key
+await client.emails.send(
+  {
+    from: 'hello@yourdomain.com',
+    to: 'user@example.com',
+    subject: 'Hi',
+    text: 'Hello',
+  },
+  { idempotencyKey: 'order-confirmation-12345' },
+);
+```
+
+## Error handling
+
+Error codes are listed in the [API overview](https://docs.develemail.com/api-overview#errors).
+
+```ts
+import { DevelEmail, DevelEmailError } from '@develemail/sdk';
+
+try {
+  await client.emails.send({ ... });
+} catch (err) {
+  if (err instanceof DevelEmailError) {
+    console.log(err.status);  // HTTP status code
+    console.log(err.code);    // 'quota_exceeded', 'domain_not_verified', etc.
+    console.log(err.message); // Human-readable message
+  }
+}
+```
+
+`err.code` is the body's machine-readable `code` field when present, otherwise
+its `error` field. `{ "error": "Forbidden", "code": "EMAIL_NOT_VERIFIED" }`
+gives `err.code === 'EMAIL_NOT_VERIFIED'` (earlier versions returned
+`'Forbidden'`). `err.details.code` still carries the same value.
+
+A `quota_exceeded` (429) response body also carries `upgrade_url` when billing
+is enabled on the instance — link your user there to raise their plan.
+
+## Documentation
+
+Full method reference: [https://docs.develemail.com/sdk-reference](https://docs.develemail.com/sdk-reference).
+
+## Testing without delivering
+
+Send to any address at `sandbox.develemail.com` (e.g.
+`e2e-42@sandbox.develemail.com`) from automated tests. The API accepts the
+send, returns a normal success response and logs it with status `sandboxed`,
+but nothing is handed to Postfix. Sandbox sends skip duplicate detection and
+are excluded from bounce rates, digests and warmup signals.
+
+A send must be all-sandbox or all-real: mixing them is rejected with a
+`400` and `error: "mixed_sandbox_recipients"`.
+
+## Domains & Templates
+
+```ts
+const domains = await client.domains.list();
+const domain = await client.domains.get('domain-id');
+
+const templates = await client.templates.list();
+const template = await client.templates.get('template-id');
+```
+
+## SMS
+
+```ts
+const { id, status } = await client.sms.send({
+  to: '+15551234567',
+  from: '+15557654321',
+  body: 'Your order has shipped!',
+});
+
+// Or render an SMS template (created via the API) server-side
+await client.sms.send({
+  to: '+15551234567',
+  templateName: 'otp-code',
+  variables: { code: '482913' },
+});
+
+// Up to 100 messages per request; each succeeds or fails on its own
+const { results, created, errors } = await client.sms.sendBatch([
+  { to: '+15551234567', body: 'Reminder: appointment at 3pm' },
+  { to: '+15557654321', body: 'Reminder: appointment at 4pm' },
+]);
+// results[i] is { index, id, status } or { index, error, code }
+
+const message = await client.sms.get(id);
+console.log(message.status); // 'queued' | 'delivered' | ...
+
+const { data, nextCursor } = await client.sms.list({
+  status: 'delivered',
+  limit: 25,
+});
+```
+
+Numbers (`to` and `from`) must be in E.164 format (e.g. `+15551234567`), and a
+message body (or rendered template) can be at most 1600 characters.
+`send` and `sendBatch` set an `Idempotency-Key` for you (override it with
+`{ idempotencyKey }`); `POST /v1/sms/batch` returns `207` when any item fails
+and `201` otherwise. Suppressed recipients return `status: 'suppressed'` for
+that item and are not sent.
+
+`POST /v1/sms` honours the `Idempotency-Key` header (1–255 characters): retrying
+with the same key and body sends exactly one SMS and replays the original
+response with `Idempotency-Replayed: true`. Reusing a key with a different body
+returns `422 idempotency_key_reuse`, and a retry while the first request is
+still in flight returns `409 idempotency_conflict`. SMS keys are scoped
+separately from email keys, so the same key on `/v1/emails` never collides. The
+SDK's `sms.send` sets this header for you, reusing the same key across retries.
+
+## Webhook verification
+
+```ts
+import { verifyWebhookSignature } from '@develemail/sdk';
+
+const valid = await verifyWebhookSignature(
+  rawBody,
+  signatureHeader,
+  webhookSecret,
+);
+```