npm package: @kreativa/email-client
Description: Type-safe client SDK for Kreativa Email Service
Author: Kreativa
Latest version: 1.0.1
Deprecated: This package is deprecated. Use @kreativa/tools-client instead.

# @kreativa/email-client

Type-safe client SDK for Kreativa Email Service.

## Installation

```bash
npm install @kreativa/email-client
```

## Quick Start

### Basic Usage (Runtime Validation)

```typescript
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: 'user@example.com',
  params: {
    name: 'John',
    actionUrl: 'https://example.com/verify',
  },
});
```

### Typed Usage (Compile-Time + Runtime Validation)

First, sync types from your email service:

```bash
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:

```typescript
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: 'user@example.com',
  params: {
    name: 'John',        // TypeScript knows this is required
    actionUrl: '...',    // TypeScript knows this is required
  },
});
```

## CLI Commands

### sync

Fetch TypeScript types from the email service:

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

### check

Test connection and list available templates:

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

## API Reference

### `createEmailClient(config)`

Creates an email client with runtime validation.

```typescript
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.

```typescript
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.

```typescript
await client.send('template-slug', {
  to: 'recipient@example.com',  // or ['a@example.com', 'b@example.com']
  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

```typescript
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