npm package: @ircg/tes
Description: Transactional Email Service SDK for IRCG
Author: Isar Ramses
Latest version: 1.23.7

# @ircg/tes

Transactional Email Service (TES) SDK for IRCG.

## Installation

```bash
pnpm add @ircg/tes
```

## Usage

```typescript
import { TESClient } from '@ircg/tes';

// Initialize the client
const tes = new TESClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://ircg.dev' // optional, defaults to https://ircg.dev
});

// Send a simple text email
await tes.sendText(
  'recipient@example.com',
  'sender@yourdomain.com',
  'Hello from IRCG',
  'This is a plain text email.'
);

// Send an HTML email
await tes.sendHtml(
  'recipient@example.com',
  'sender@yourdomain.com',
  'Welcome!',
  '<h1>Welcome to our service!</h1><p>Thank you for signing up.</p>',
  'Welcome to our service! Thank you for signing up.' // optional text fallback
);

// Send to multiple recipients
await tes.sendText(
  ['user1@example.com', 'user2@example.com'],
  'sender@yourdomain.com',
  'Bulk notification',
  'This email is sent to multiple recipients.'
);

// Advanced usage with all options
const result = await tes.send({
  sender: 'noreply@yourdomain.com',
  recipients: ['user@example.com'],
  subject: 'Important notification',
  html: '<p>HTML content</p>',
  text: 'Text content',
  carbon_copy: 'cc@example.com',
  reply_to: 'support@yourdomain.com'
}, 'complete');

console.log(result.email_sent);
```

## API Reference

### `TESClient`

#### Constructor

```typescript
new TESClient(config: IRCGClientConfig)
```

- `config.apiKey` (required): Your IRCG API key
- `config.baseUrl` (optional): Base URL for the API (default: 'https://ircg.dev')

#### Methods

##### `send(data)`

Send a transactional email with full control.

- `data.recipients` (required): Recipient email address(es)
- `data.sender` (required): Sender email address
- `data.subject` (required): Email subject
- `data.html` (optional): HTML content
- `data.text` (optional): Plain text content
- `data.carbon_copy` (optional): CC email address(es)
- `data.reply_to` (optional): Reply-to email address(es)
- `data.fields` (required): Array of fields to include in the response
- `data.lang` (optional): Language for error messages ('es' | 'en')

**Note**: At least one of `html` or `text` must be provided.

Returns: `Promise<{ email_sent?, error? }>`

##### `sendText(to, from, subject, text, fields)`

Send a simple plain text email.

- `to` (required): Recipient email address
- `from` (required): Sender email address
- `subject` (required): Email subject
- `text` (required): Plain text content
- `fields` (required): Array of fields to include in the response

Returns: `Promise<{ email_sent?, error? }>`

##### `sendHtml(to, from, subject, html, text?, fields?)`

Send an HTML email with optional text fallback.

- `to` (required): Recipient email address
- `from` (required): Sender email address
- `subject` (required): Email subject
- `html` (required): HTML content
- `text` (optional): Plain text fallback
- `fields` (required): Array of fields to include in the response

Returns: `Promise<{ email_sent?, error? }>`

## Important Notes

### Domain Verification

The sender email address must use a domain that is verified in your IRCG account. For example, if you have verified `yourdomain.com`, you can send from:
- `noreply@yourdomain.com`
- `support@yourdomain.com`
- Any email at `yourdomain.com`

### Rate Limits

Be aware of your service's rate limits. The SDK will throw an `IRCGRateLimitError` if you exceed your quota.

## Error Handling

```typescript
import { TESClient } from '@ircg/tes';
import { 
  IRCGError, 
  IRCGAuthenticationError, 
  IRCGValidationError,
  IRCGRateLimitError 
} from '@ircg/core';

const tes = new TESClient({ apiKey: 'your-api-key' });

try {
  await tes.sendText(
    'invalid-email',
    'sender@yourdomain.com',
    'Test',
    'Test message'
  );
} catch (error) {
  if (error instanceof IRCGAuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof IRCGValidationError) {
    console.error('Validation error:', error.details);
  } else if (error instanceof IRCGRateLimitError) {
    console.error('Rate limit exceeded');
  } else if (error instanceof IRCGError) {
    console.error('IRCG error:', error.message);
  }
}
```

## License

MIT