@emailr/sdk 1.0.0

package/README.md

@@ -0,0 +1,241 @@
+# @emailr/sdk
+
+Official Emailr API SDK for TypeScript/JavaScript.
+
+## Installation
+
+```bash
+npm install @emailr/sdk
+# or
+pnpm add @emailr/sdk
+# or
+yarn add @emailr/sdk
+```
+
+## Quick Start
+
+```typescript
+import { Emailr } from '@emailr/sdk';
+
+const emailr = new Emailr({ apiKey: 'your-api-key' });
+
+// Send an email
+const result = await emailr.emails.send({
+  to: 'recipient@example.com',
+  from: 'sender@yourdomain.com',
+  subject: 'Hello!',
+  html: '<h1>Hello World</h1>',
+});
+
+console.log(result.message_id);
+```
+
+## Configuration
+
+```typescript
+const emailr = new Emailr({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.emailr.dev', // optional
+  timeout: 30000, // optional, in milliseconds
+});
+```
+
+## Resources
+
+### Emails
+
+```typescript
+// Send an email
+const result = await emailr.emails.send({
+  to: 'recipient@example.com',
+  from: 'sender@yourdomain.com',
+  subject: 'Hello!',
+  html: '<h1>Hello World</h1>',
+  text: 'Hello World',
+});
+
+// Send with a template
+const result = await emailr.emails.send({
+  to: 'recipient@example.com',
+  template_id: 'template-uuid',
+  template_data: { name: 'John', company: 'Acme' },
+});
+
+// Get email by ID
+const email = await emailr.emails.get('email-uuid');
+
+// List emails
+const emails = await emailr.emails.list({ page: 1, limit: 50 });
+```
+
+### Contacts
+
+```typescript
+// Create a contact
+const contact = await emailr.contacts.create({
+  email: 'contact@example.com',
+  first_name: 'John',
+  last_name: 'Doe',
+  metadata: { source: 'website' },
+});
+
+// List contacts
+const contacts = await emailr.contacts.list({ limit: 100 });
+
+// Update a contact
+const updated = await emailr.contacts.update('contact-uuid', {
+  first_name: 'Jane',
+});
+
+// Delete a contact
+await emailr.contacts.delete('contact-uuid');
+
+// Bulk create contacts
+const result = await emailr.contacts.bulkCreate({
+  contacts: [
+    { email: 'user1@example.com', first_name: 'User 1' },
+    { email: 'user2@example.com', first_name: 'User 2' },
+  ],
+});
+```
+
+### Templates
+
+```typescript
+// Create a template
+const template = await emailr.templates.create({
+  name: 'Welcome Email',
+  subject: 'Welcome to {{company}}',
+  html_content: '<h1>Welcome {{name}}</h1>',
+  variables: ['name', 'company'],
+});
+
+// List templates
+const templates = await emailr.templates.list();
+
+// Update a template
+const updated = await emailr.templates.update('template-uuid', {
+  subject: 'New Subject',
+});
+
+// Delete a template
+await emailr.templates.delete('template-uuid');
+```
+
+### Domains
+
+```typescript
+// Add a domain
+const domain = await emailr.domains.add({ domain: 'example.com' });
+
+// List domains
+const domains = await emailr.domains.list();
+
+// Verify domain
+const status = await emailr.domains.verify('domain-uuid');
+
+// Check DNS status
+const dnsStatus = await emailr.domains.checkDns('domain-uuid');
+
+// Delete a domain
+await emailr.domains.delete('domain-uuid');
+```
+
+### Webhooks
+
+```typescript
+// Create a webhook
+const webhook = await emailr.webhooks.create({
+  name: 'Email Events',
+  url: 'https://api.example.com/webhooks',
+  events: ['email.sent', 'email.delivered', 'email.bounced'],
+});
+
+// List webhooks
+const webhooks = await emailr.webhooks.list();
+
+// Enable/disable webhook
+await emailr.webhooks.enable('webhook-uuid');
+await emailr.webhooks.disable('webhook-uuid');
+
+// Delete a webhook
+await emailr.webhooks.delete('webhook-uuid');
+```
+
+### Broadcasts
+
+```typescript
+// Create a broadcast
+const broadcast = await emailr.broadcasts.create({
+  name: 'Newsletter - January',
+  subject: 'Your monthly update',
+  from_email: 'newsletter@example.com',
+  segment_id: 'segment-uuid',
+  html_content: '<h1>Newsletter</h1>',
+});
+
+// Send a broadcast
+const result = await emailr.broadcasts.send('broadcast-uuid');
+
+// Schedule a broadcast
+await emailr.broadcasts.schedule('broadcast-uuid', '2024-01-15T10:00:00Z');
+
+// Cancel a scheduled broadcast
+await emailr.broadcasts.cancel('broadcast-uuid');
+```
+
+### Segments
+
+```typescript
+// Create a segment
+const segment = await emailr.segments.create({
+  name: 'Active Users',
+  description: 'Users who opened an email in the last 30 days',
+  conditions: { opened_email: { within_days: 30 } },
+});
+
+// List segments
+const segments = await emailr.segments.list();
+
+// Get contacts in a segment
+const contacts = await emailr.segments.getContacts('segment-uuid');
+
+// Get segment count
+const count = await emailr.segments.getCount('segment-uuid');
+```
+
+## Error Handling
+
+```typescript
+import { Emailr, EmailrError, ValidationError, RateLimitError } from '@emailr/sdk';
+
+try {
+  await emailr.emails.send({ to: 'invalid-email' });
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error('Validation failed:', error.message, error.details);
+  } else if (error instanceof RateLimitError) {
+    console.error('Rate limited. Retry after:', error.retryAfter, 'seconds');
+  } else if (error instanceof EmailrError) {
+    console.error('API error:', error.message, error.statusCode, error.code);
+  }
+}
+```
+
+## TypeScript Support
+
+This SDK is written in TypeScript and provides full type definitions for all API requests and responses.
+
+```typescript
+import type { SendEmailRequest, Email, Contact } from '@emailr/sdk';
+
+const request: SendEmailRequest = {
+  to: 'recipient@example.com',
+  subject: 'Hello',
+  html: '<h1>Hello</h1>',
+};
+```
+
+## License
+
+MIT