npm package: @isend-ai/nodejs-sdk
Description: Node.js SDK for isend.ai - Send emails easily using email connectors like SES, SendGrid, and more
Author: isend.ai
Latest version: 1.0.1

# isend.ai Node.js SDK

A simple Node.js SDK for sending emails through isend.ai using various email connectors like AWS SES, SendGrid, Mailgun, and more.

## Installation

```bash
npm install @isend-ai/nodejs-sdk
```

## Quick Start

```javascript
const { ISendClient } = require('@isend-ai/nodejs-sdk');

// Initialize the client
const client = new ISendClient('your-api-key-here');

// Send email using template
const emailData = {
  template_id: 124,
  to: 'hi@isend.ai',
  dataMapping: {
    name: 'ISend'
  }
};

client.sendEmail(emailData)
  .then(response => {
    console.log('Email sent successfully!', response);
  })
  .catch(error => {
    console.error('Error sending email:', error.message);
  });
```

### TypeScript

```typescript
import { ISendClient } from '@isend-ai/nodejs-sdk';

// Initialize the client
const client = new ISendClient('your-api-key-here');

// Send email using template
async function sendEmail() {
  try {
    const emailData = {
      template_id: 124,
      to: 'hi@isend.ai',
      dataMapping: {
        name: 'ISend'
      }
    };
    
    const response = await client.sendEmail(emailData);
    console.log('Email sent successfully!', response);
  } catch (error) {
    console.error('Error sending email:', error.message);
  }
}

sendEmail();
```

## Usage

### Send Email Using Template

```javascript
const emailData = {
  template_id: 124,
  to: 'hi@isend.ai',
  dataMapping: {
    name: 'ISend'
  }
};

const response = await client.sendEmail(emailData);
```

### Custom Configuration

```javascript
const client = new ISendClient('your-api-key-here', {
  timeout: 60000, // 60 seconds
  baseURL: 'https://custom.isend.ai/api' // Custom API endpoint
});
```

## API Reference

### ISendClient

#### Constructor
```javascript
new ISendClient(string apiKey, ISendConfig config = {})
```

**Parameters:**
- `apiKey` (string): Your isend.ai API key (required)
- `config` (ISendConfig): Additional configuration options (optional)

#### Methods

##### sendEmail(EmailData emailData): Promise<ISendResponse>
Sends an email using the provided template and data.

**Parameters:**
- `emailData` (EmailData): Email data including:
  - `template_id` (number): The template ID to use
  - `to` (string): Recipient email address
  - `dataMapping` (object): Data mapping for template variables

**Returns:** Promise<ISendResponse>

##### getApiKey(): string
Returns the masked API key for debugging purposes.

**Returns:** string (masked API key)

##### getConfig(): ISendConfig
Returns the current configuration.

**Returns:** ISendConfig

## Types

### ISendConfig
```typescript
interface ISendConfig {
  timeout?: number;    // Request timeout in milliseconds (default: 30000)
  baseURL?: string;    // Custom API base URL (default: 'https://www.isend.ai/api')
}
```

### EmailData
```typescript
interface EmailData {
  template_id: number;                    // Template ID to use
  to: string;                            // Recipient email address
  dataMapping?: Record<string, any>;     // Data mapping for template variables
  [key: string]: any;                    // Additional email properties
}
```

### ISendResponse
```typescript
interface ISendResponse {
  success: boolean;      // Whether the request was successful
  message?: string;      // Response message
  data?: any;           // Response data
  [key: string]: any;   // Additional response properties
}
```

### ISendError
```typescript
interface ISendError {
  message: string;       // Error message
  status?: number;       // HTTP status code
  code?: string;         // Error code
}
```

## Error Handling

The SDK throws `ISendError` for any errors:

```javascript
try {
  const response = await client.sendEmail({
    template_id: 124,
    to: 'hi@isend.ai',
    dataMapping: {
      name: 'ISend'
    }
  });
} catch (error) {
  console.error('Error:', error.message);
  console.error('Status:', error.status);
  console.error('Code:', error.code);
}
```

## Examples

See the `examples/` directory for complete usage examples:

- `examples/send-email.js` - JavaScript example
- `examples/send-email.ts` - TypeScript example

## Development

### Prerequisites

- Node.js 14.0.0 or higher
- npm or yarn

### Setup

```bash
# Clone the repository
git clone https://github.com/isend-ai/nodejs-sdk.git
cd nodejs-sdk

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint
```

### Available Scripts

- `npm run build` - Build the TypeScript code
- `npm test` - Run tests
- `npm run test:watch` - Run tests in watch mode
- `npm run test:coverage` - Run tests with coverage
- `npm run lint` - Run ESLint
- `npm run lint:fix` - Fix ESLint issues

## Requirements

- Node.js 14.0.0 or higher
- npm or yarn

## License

MIT License