@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

npm install @relay-works/templates

Quick Start

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

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

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

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:

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

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

Order Confirmation

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

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:

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:

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 for guidelines.

License

MIT © Relay Works