@develemail/sdk 0.1.0 → 0.4.0

package/README.md

@@ -0,0 +1,157 @@
+# @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
+```
+
+## 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
+
+```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
+  }
+}
+```
+
+## 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' },
+});
+
+const message = await client.sms.get(id);
+console.log(message.status); // 'queued' | 'delivered' | ...
+
+const { data, nextCursor } = await client.sms.list({
+  status: 'delivered',
+  limit: 25,
+});
+```
+
+## Webhook verification
+
+```ts
+import { verifyWebhookSignature } from '@develemail/sdk';
+
+const valid = await verifyWebhookSignature(
+  rawBody,
+  signatureHeader,
+  webhookSecret,
+);
+```