Huefy SDK for JavaScript/TypeScript

The official JavaScript/TypeScript SDK for Huefy - App Mail Templates. Create and manage email templates for your applications with dynamic data and multi-provider sending capabilities.

Installation

1npm install @teracrafts/huefy-sdk-js

Quick Start

1import { HuefyClient } from '@teracrafts/huefy-sdk-js';
2
3const huefy = new HuefyClient({
4  apiKey: 'your-api-key'
5});
6
7// Send an email
8const result = await huefy.sendEmail('welcome-email', {
9  name: 'John Doe',
10  company: 'Acme Corp'
11}, 'john@example.com');
12
13console.log('Email sent:', result.messageId);

Features

• ✅ Type Safe - Full TypeScript support with comprehensive type definitions
• ✅ Error Handling - Detailed error types with retry logic
• ✅ Multiple Providers - Support for SES, SendGrid, Mailgun, Mailchimp
• ✅ Retry Logic - Automatic retries with exponential backoff
• ✅ Bulk Sending - Send multiple emails efficiently
• ✅ Validation - Input validation for all parameters
• ✅ Node.js & Browser - Works in both environments

Configuration

1const huefy = new HuefyClient({
2  apiKey: 'your-api-key',
3  timeout: 30000, // Optional, default 30 seconds
4  retryAttempts: 3, // Optional, default 3
5  retryDelay: 1000, // Optional, default 1 second
6});

Sending Emails

Basic Usage

1// Send with default SES provider
2await huefy.sendEmail('welcome-email', {
3  name: 'John Doe',
4  company: 'Acme Corp'
5}, 'john@example.com');

Custom Provider

1// Send with specific provider
2await huefy.sendEmail('newsletter', {
3  name: 'Jane Smith',
4  unsubscribe_url: 'https://app.example.com/unsubscribe'
5}, 'jane@example.com', {
6  provider: 'sendgrid'
7});

Bulk Sending

1const results = await huefy.sendBulkEmails([
2  {
3    templateKey: 'welcome-email',
4    data: { name: 'John Doe' },
5    recipient: 'john@example.com'
6  },
7  {
8    templateKey: 'welcome-email',
9    data: { name: 'Jane Smith' },
10    recipient: 'jane@example.com',
11    options: { provider: 'mailgun' }
12  }
13]);
14
15results.forEach(result => {
16  if (result.success) {
17    console.log(`Email sent to ${result.email}: ${result.result?.messageId}`);
18  } else {
19    console.error(`Failed to send to ${result.email}: ${result.error?.message}`);
20  }
21});

Error Handling

1import { 
2  HuefyError, 
3  TemplateNotFoundError, 
4  RateLimitError 
5} from '@teracrafts/huefy';
6
7try {
8  await huefy.sendEmail('template-key', data, 'user@example.com');
9} catch (error) {
10  if (error instanceof TemplateNotFoundError) {
11    console.error('Template not found:', error.details.template_key);
12  } else if (error instanceof RateLimitError) {
13    console.error('Rate limit exceeded, retry after:', error.details.reset_at);
14  } else if (error instanceof HuefyError) {
15    console.error('Huefy API error:', error.code, error.message);
16  } else {
17    console.error('Unexpected error:', error);
18  }
19}

Event Callbacks

1const huefy = new HuefyClient(config, {
2  onSendStart: (request) => {
3    console.log('Sending email:', request.template_key);
4  },
5  onSendSuccess: (response) => {
6    console.log('Email sent successfully:', response.message_id);
7  },
8  onSendError: (error) => {
9    console.error('Email send failed:', error.message);
10  },
11  onRetry: (attempt, error) => {
12    console.log(`Retry attempt ${attempt}:`, error.message);
13  }
14});

Available Providers

• ses - Amazon SES (default)
• sendgrid - SendGrid
• mailgun - Mailgun
• mailchimp - Mailchimp

API Reference

HuefyClient

Constructor

• new HuefyClient(config: HuefyConfig, callbacks?: HuefyEventCallbacks)

Methods

• sendEmail(templateKey: string, data: EmailData, recipient: string, options?: SendEmailOptions): Promise<SendEmailResponse>
• sendBulkEmails(emails: BulkEmailRequest[]): Promise<BulkEmailResult[]>
• healthCheck(): Promise<HealthResponse>
• validateTemplate(templateKey: string, testData: EmailData): Promise<boolean>
• getConfig(): ClientConfig

Types

See the full type definitions for comprehensive TypeScript support.

Examples

Check out the examples directory for complete working examples.

Development

1# Install dependencies
2npm install
3
4# Build the SDK
5npm run build
6
7# Run tests
8npm test
9
10# Run linter
11npm run lint
12
13# Type check
14npm run typecheck

License

MIT - see LICENSE for details.