npm package: @relay-works/templates
Description: Official SMS message templates for Relay
Author: Relay Works
Latest version: 1.0.1

# @relay-works/templates

Official SMS message templates for Relay - A single source of truth for SMS templates with type-safe schemas, validation, and rendering.

## Features

- **9 Production-Ready Templates** - Authentication, transactions, and appointments
- **Type-Safe** - Full TypeScript support with auto-completion
- **Validation** - Runtime validation with helpful error messages
- **Rendering** - Safe variable substitution with sanitization
- **Compliance Ready** - 10DLC campaign type metadata included
- **SMS Optimized** - Character counting and segment calculation

## Installation

```bash
npm install @relay-works/templates
```

## Quick Start

```typescript
import { getTemplate, validateTemplateData, renderTemplate } from '@relay-works/templates'

// Get a template
const otpTemplate = getTemplate('otp-verify')

// Validate your data
const validation = validateTemplateData(otpTemplate, {
  code: '482916',
  company: 'Acme'
})

if (!validation.valid) {
  console.error('Validation errors:', validation.errors)
}

// Render the template
const result = renderTemplate(otpTemplate, {
  code: '482916',
  company: 'Acme'
})

console.log(result.text) // "482916 is your Acme verification code."
console.log(result.segments) // 1
```

## Available Templates

### Authentication (4 templates)
- `otp-verify` - OTP verification code
- `password-reset` - Password reset link
- `new-login-alert` - New login security alert
- `account-security-alert` - Generic security notification

### Transaction (4 templates)
- `order-confirmed` - Order confirmation
- `order-shipped` - Shipping notification
- `payment-confirmed` - Payment received
- `payment-failed` - Payment declined

### Appointment (1 template)
- `appointment-reminder` - Appointment reminder with confirmation

## API Reference

### Template Discovery

```typescript
import {
  templates,
  getTemplate,
  getTemplatesByCategory,
  getTemplatesByTag,
  searchTemplates
} from '@relay-works/templates'

// All templates
console.log(templates.length) // 9

// Get by ID
const template = getTemplate('otp-verify')

// Get by category
const authTemplates = getTemplatesByCategory('authentication')

// Get by tag
const securityTemplates = getTemplatesByTag('security')

// Search
const results = searchTemplates('password')
```

### Validation

```typescript
import { validateTemplateData, validateTemplateSyntax } from '@relay-works/templates'

// Validate data against template schema
const validation = validateTemplateData(template, data)
if (!validation.valid) {
  validation.errors.forEach(error => {
    console.log(`${error.field}: ${error.message}`)
    console.log(`Suggestion: ${error.suggestion}`)
  })
}

// Validate template body syntax
const syntaxCheck = validateTemplateSyntax('Hello {{name}}')
```

### Rendering

```typescript
import { renderTemplate, extractVariables, generateSampleData } from '@relay-works/templates'

// Render with options
const result = renderTemplate(template, data, {
  strict: false,    // Don't throw on missing variables
  validate: true,   // Validate before rendering
  sanitize: true    // Sanitize variable values
})

// Extract variable names from body
const vars = extractVariables('Hello {{name}}, code: {{code}}')
// ['name', 'code']

// Generate sample data
const sample = generateSampleData(template)
```

## Type Safety

The package provides full TypeScript support:

```typescript
import type { TemplateId, TemplateData } from '@relay-works/templates'

// Type-safe template IDs
const templateId: TemplateId = 'otp-verify'

// Type-safe data per template
const data: TemplateData<'otp-verify'> = {
  code: '482916',
  company: 'Acme'
}

// Compile error if wrong data structure
const wrong: TemplateData<'otp-verify'> = {
  code: '123',
  // Missing 'company' - TypeScript error!
}
```

## Examples

### OTP Verification

```typescript
const template = getTemplate('otp-verify')
const result = renderTemplate(template, {
  code: '482916',
  company: 'Acme'
})
// "482916 is your Acme verification code."
```

### Order Confirmation

```typescript
const template = getTemplate('order-confirmed')
const result = renderTemplate(template, {
  company: 'Acme Store',
  orderNumber: 'A1B2C3',
  itemCount: 3,
  amount: '49.99',
  url: 'https://relay.link/order-123'
})
// "Acme Store: Order #A1B2C3 confirmed! 3 items, $49.99. Track: https://relay.link/order-123"
```

### Password Reset

```typescript
const template = getTemplate('password-reset')
const result = renderTemplate(template, {
  company: 'Acme',
  url: 'https://relay.link/rst-x7k',
  minutes: 15
})
// "Reset your Acme password: https://relay.link/rst-x7k. Link expires in 15 min."
```

## Compliance Features

Each template includes 10DLC compliance metadata:

```typescript
const template = getTemplate('otp-verify')

console.log(template.compliance)
// {
//   campaignType: '2FA',
//   riskLevel: 'LOW',
//   requiresOptIn: false,
//   containsAuthCode: true,
//   shaftScore: 0
// }
```

## Best Practices

Templates include built-in best practices:

```typescript
const template = getTemplate('otp-verify')

console.log(template.metadata.bestPractices)
// [
//   'Code MUST be first for iOS Security Code AutoFill',
//   'Keep company name under 20 chars',
//   ...
// ]
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT © Relay Works