@kreativa/email-client

Type-safe client SDK for Kreativa Email Service.

Installation

npm install @kreativa/email-client

Quick Start

Basic Usage (Runtime Validation)

import { createEmailClient } from '@kreativa/email-client';

const email = await createEmailClient({
  baseUrl: 'https://email.yoursite.com',
  apiKey: process.env.EMAIL_API_KEY!,
});

// Send an email - params are validated at runtime
await email.send('welcome', {
  to: '[email protected]',
  params: {
    name: 'John',
    actionUrl: 'https://example.com/verify',
  },
});

Typed Usage (Compile-Time + Runtime Validation)

First, sync types from your email service:

npx @kreativa/email-client sync \
  --url https://email.yoursite.com \
  --api-key $EMAIL_API_KEY \
  --output ./src/generated/email-types.ts

Then use the typed client:

import { createTypedEmailClient } from '@kreativa/email-client';
import type { TemplateMap } from './generated/email-types';

const email = await createTypedEmailClient<TemplateMap>({
  baseUrl: 'https://email.yoursite.com',
  apiKey: process.env.EMAIL_API_KEY!,
});

// Full autocomplete and type checking!
await email.send('welcome', {
  to: '[email protected]',
  params: {
    name: 'John',        // TypeScript knows this is required
    actionUrl: '...',    // TypeScript knows this is required
  },
});

CLI Commands

sync

Fetch TypeScript types from the email service:

npx @kreativa/email-client sync \
  --url <service-url> \
  --api-key <api-key> \
  --output <output-path>

check

Test connection and list available templates:

npx @kreativa/email-client check \
  --url <service-url> \
  --api-key <api-key>

API Reference

createEmailClient(config)

Creates an email client with runtime validation.

const client = await createEmailClient({
  baseUrl: string;      // Email service URL
  apiKey: string;       // API key for authentication
  fetchSchemas?: boolean; // Fetch schemas on init (default: true)
});

createTypedEmailClient<TTemplates>(config)

Creates a typed email client with compile-time type checking.

import type { TemplateMap } from './generated/email-types';

const client = await createTypedEmailClient<TemplateMap>({
  baseUrl: string;
  apiKey: string;
});

client.send(templateSlug, options)

Send an email using a template.

await client.send('template-slug', {
  to: '[email protected]',  // or ['[email protected]', '[email protected]']
  params: { ... },              // Template variables
  subject?: 'Override subject', // Optional subject override
});

client.getTemplates()

Get all available templates.

client.refreshSchemas()

Refresh template schemas from the service.

Error Handling

import { EmailValidationError, EmailApiError } from '@kreativa/email-client';

try {
  await email.send('welcome', { to: '...', params: {} });
} catch (error) {
  if (error instanceof EmailValidationError) {
    console.log('Missing params:', error.missingParams);
  } else if (error instanceof EmailApiError) {
    console.log('API error:', error.statusCode, error.message);
  }
}

License

MIT