npm package: @sendflowdev/sdk
Description: Official Sendflow SDK for Node.js
Author: Sendflow Team
Latest version: 1.0.0

# @sendflowdev/sdk

Official Node.js SDK for Sendflow - professional email delivery API.

## Installation

```bash
npm install @sendflowdev/sdk
```

## Quick Start

```typescript
import Sendflow from '@sendflowdev/sdk';

const sendflow = new Sendflow({
  apiKey: 'your-api-key'
});

// Send an email
const result = await sendflow.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Welcome!',
  html: '<h1>Hello World</h1>',
  text: 'Hello World'
});

console.log('Email sent:', result.id);
```

## Configuration

```typescript
const sendflow = new Sendflow({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.sendflow.dev/functions/v1',  // Optional: custom base URL
  timeout: 30000,                       // Optional: request timeout (ms)
  maxRetries: 3,                        // Optional: max retry attempts
  retryDelay: 1000                      // Optional: delay between retries (ms)
});
```

## API Reference

### Emails

```typescript
// Send an email
await sendflow.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Hello',
  html: '<p>HTML content</p>',
  text: 'Plain text content'
});

// Send using a saved template
await sendflow.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  template_id: 'template-uuid-here',
  variables: {
    name: 'John Smith',
    company: 'Acme Inc',
    login_url: 'https://app.acme.com/login'
  }
});

// Template with subject override
await sendflow.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  template_id: 'template-uuid-here',
  variables: { name: 'John' },
  subject: 'Custom Subject Override'
});

// Get email status
const email = await sendflow.emails.get('email-id');
```

### Inbound Emails

Receive and process incoming emails on your verified domains.

```typescript
// List inbound emails
const { emails, pagination } = await sendflow.inboundEmails.list({
  domain_id: 'domain-id',  // Optional: filter by domain
  limit: 20,
  offset: 0
});

// Get a specific inbound email with full content
const email = await sendflow.inboundEmails.get('inbound-email-id');
console.log('From:', email.from_address);
console.log('Subject:', email.subject);
console.log('Body:', email.text_content || email.html_content);

// Download an attachment
const attachment = await sendflow.inboundEmails.getAttachment(
  'inbound-email-id',
  'attachment-id'
);
console.log('Download URL:', attachment.download_url);
// URL expires in 1 hour
```

### Domains

```typescript
// List domains
const domains = await sendflow.domains.list();

// Get domain details
const domain = await sendflow.domains.get('domain-id');

// Add domain
const newDomain = await sendflow.domains.add('yourdomain.com');

// Verify domain
const verified = await sendflow.domains.verify('domain-id');
```

### Events

```typescript
// List all events
const events = await sendflow.events.list();

// Filter events
const deliveryEvents = await sendflow.events.list({
  type: 'delivery',
  limit: 50
});
```

### Suppressions

```typescript
// List suppressions
const suppressions = await sendflow.suppressions.list();

// Add suppression
await sendflow.suppressions.add('user@example.com', 'unsubscribe');

// Remove suppression
await sendflow.suppressions.remove('user@example.com');
```

## Webhook Events

Subscribe to webhook events to receive real-time notifications:

```typescript
// Available events
const events = [
  'email.delivered',
  'email.bounced',
  'email.complained',
  'email.opened',
  'email.clicked',
  'email.received',    // Inbound email received
  'domain.created',
  'domain.updated',
  'domain.deleted'
];
```

### Handling Inbound Email Webhooks

```typescript
// Express.js webhook handler
app.post('/webhooks/sendflow', (req, res) => {
  const event = req.body;
  
  if (event.type === 'email.received') {
    console.log('New inbound email from:', event.data.from);
    console.log('Subject:', event.data.subject);
    console.log('Has attachments:', event.data.hasAttachments);
    
    // Fetch full email content if needed
    const fullEmail = await sendflow.inboundEmails.get(event.data.id);
  }
  
  res.status(200).send('OK');
});
```

## Error Handling

```typescript
import { SendflowError } from '@sendflowdev/sdk';

try {
  await sendflow.emails.send({
    from: 'hello@yourdomain.com',
    to: ['invalid@domain'],
    subject: 'Test'
  });
} catch (error) {
  if (error instanceof SendflowError) {
    console.log('Error code:', error.code);
    console.log('Error details:', error.details);
    console.log('Status code:', error.statusCode);
  }
}
```

## TypeScript Support

This SDK is written in TypeScript and includes full type definitions.

```typescript
import Sendflow, { 
  SendEmailRequest, 
  Domain, 
  Event, 
  InboundEmail,
  InboundAttachment 
} from '@sendflowdev/sdk';
```

## License

MIT