sendrly/README.md

Official Sendrly TypeScript/JavaScript SDK - Simple, type-safe email automation for developers

# Sendrly

The official SDK for Sendrly - making email automation simple and easy to use.

## Table of Contents
- [Installation](#installation)
- [Setup](#setup)
- [Core Features](#core-features)
  - [Send Events](#1-send-events)
  - [Get Contact Info](#2-get-contact-info)
  - [List Events](#3-list-events)
  - [Delete Contact](#4-delete-contact)
- [Response Types](#response-types)
- [Error Handling](#error-handling)
- [Need Help?](#need-help)

## Installation

```bash
npm install sendrly
# or
yarn add sendrly
# or
pnpm add sendrly
```

### Requirements
- Node.js 14 or later
- TypeScript 4.5 or later (for TypeScript users)

## Setup

```typescript
import { Sendrly } from 'sendrly'

// Create your client
const sendrly = new Sendrly({
  apiKey: 'your_api_key_here',  // 👈 Replace with your API key
  debug: true  // Shows helpful logs
})
```

## Core Features

### 1. Send Events

```typescript
import { Sendrly } from 'sendrly'

const sendrly = new Sendrly({ apiKey: 'your_api_key_here' })

// Simple event (e.g., signup)
try {
  await sendrly.sendEvent({
    email: 'user@example.com',
    event: 'user.signup'
  })
} catch (e) {
  console.error(`Error: ${e.message}`)
}

// Detailed event (e.g., purchase)
try {
  await sendrly.sendEvent({
    email: 'customer@example.com',
    event: 'order.completed',
    contact_properties: {
      name: 'John Smith',
      company: 'Acme Inc',
      plan: 'pro'
    },
    event_properties: {
      order_id: 'ORDER-123',
      amount: 99.99,
      items: ['item1', 'item2']
    }
  })
} catch (e) {
  console.error(`Error: ${e.message}`)
}
```

### 2. Get Contact Info

```typescript
import { Sendrly } from 'sendrly'

const sendrly = new Sendrly({ apiKey: 'your_api_key_here' })

try {
  const contact = await sendrly.getContact('user@example.com')
  console.log({
    name: contact.properties.name,
    company: contact.properties.company,
    allProperties: contact.properties,
    emailAddresses: contact.emails.map(e => e.email)
  })
} catch (e) {
  if (e.code === 'NOT_FOUND') {
    console.log('Contact not found')
  } else {
    console.error(`Error: ${e.message}`)
  }
}
```

### 3. List Events

```typescript
import { Sendrly } from 'sendrly'

const sendrly = new Sendrly({ apiKey: 'your_api_key_here' })

// Get all signups
try {
  const signups = await sendrly.listEvents('user.signup')
  signups.forEach(signup => {
    console.log({
      email: signup.contact_emails[0].email,
      when: signup.received_at,
      details: signup.event_properties
    })
  })
} catch (e) {
  console.error(`Error: ${e.message}`)
}

// Calculate total sales
try {
  const purchases = await sendrly.listEvents('order.completed')
  const total = purchases.reduce((sum, p) => sum + (p.event_properties.amount || 0), 0)
  console.log(`Total Sales: $${total.toLocaleString('en-US', { minimumFractionDigits: 2 })}`)
} catch (e) {
  console.error(`Error: ${e.message}`)
}
```

### 4. Delete Contact

```typescript
import { Sendrly } from 'sendrly'

const sendrly = new Sendrly({ apiKey: 'your_api_key_here' })

try {
  await sendrly.deleteContact('user@example.com')
  console.log('Contact deleted')
} catch (e) {
  if (e.code === 'NOT_FOUND') {
    console.log('Contact was already deleted')
  } else {
    console.error(`Error: ${e.message}`)
  }
}
```

## Response Types

### Contact Response
```typescript
interface ContactResponse {
  id: string              // Unique ID for the contact
  marketing_opt_out: boolean  // If they opted out of marketing
  properties: {           // Custom properties you've set
    name?: string
    company?: string
    [key: string]: any   // Any other properties
  }
  emails: Array<{        // Their email addresses
    email: string
    status: string       // 'active', 'bounced', etc.
  }>
}
```

### Event Response
```typescript
interface EventResponse {
  id: string              // Unique ID for the event
  event_name: string      // Name of the event (e.g., 'user.signup')
  event_properties: {     // Properties you sent with the event
    [key: string]: any   // Any properties
  }
  contact_id: string      // ID of the contact who triggered it
  received_at: string     // When it happened
  contact_emails: Array<{
    email: string
    status: string       // 'active', 'bounced', etc.
  }>
}
```

## Error Handling

```typescript
try {
  await sendrly.sendEvent(...)
} catch (e) {
  switch (e.code) {
    case 'INVALID_API_KEY':
      console.log('Your API key is not working')
      break
    case 'NOT_FOUND':
      console.log('Resource not found')
      break
    case 'API_ERROR':
      console.error(`API Error: ${e.message}`)
      break
    default:
      console.error(`Unexpected error: ${e.message}`)
  }
}
```

### Error Codes

| Code | Meaning |
|------|---------|
| `INVALID_CONFIG` | Invalid settings (e.g., missing API key) |
| `INVALID_API_KEY` | Invalid API key |
| `NOT_FOUND` | Resource not found |
| `API_ERROR` | API request failed |
| `UNKNOWN_ERROR` | Unexpected error |

## Need Help?

- **Email**: support@sendrly.com
- **Documentation**: https://docs.sendrly.com
- **Examples**: https://github.com/sendrly/examples

## License

MIT License - see [LICENSE](LICENSE) for details.