Centpub SDK

A JavaScript/TypeScript SDK for handling email notifications and messaging services.

Installation

npm install centpub-sdk
# or
yarn add centpub-sdk

Features

• Email notification system with templated messages
• Queue-based message processing
• TypeScript support with type definitions
• Built-in validation for email payloads
• Connection management for message queues

Getting Started

Initialize the SDK

import { Mailing } from 'centpub-sdk';

// Get the mailing instance
const mailing = Mailing.getInstance();

Email Notifications

Available Email Templates

The SDK provides several pre-built email templates:

1. Admin Invite (admin-invite)

   • Subject: "Verify your email"
   • Required variables:
     • business: string
     • firstname: string
     • link: string
     • role: string

2. Password Change Request (password-change-request)

   • Subject: "Reset temporary password"
   • Required variables:
     • name: string
     • verification_code: string

3. Password Change Notification (password-change-notification)

   • Subject: "Reset password Notification"
   • Required variables:
     • name: string
     • date: string

4. New Sign-in (new-signin)

   • Subject: "Wallet by Poket - New Sign-in"
   • Required variables:
     • name: string
   • Optional variables:
     • deviceName: string
     • timeZone: string
     • time: string

Sending Emails

import { Mailing, MailTemplates } from 'centpub-sdk';

const mailing = Mailing.getInstance();

try {
  const result = await mailing.sendEmail({
    email: '[email protected]',
    template: MailTemplates.ADMIN_INVITE,
    data: {
      business: 'My Business',
      firstname: 'John',
      link: 'https://example.com/verify',
      role: 'admin'
    }
  });
  
  console.log('Email job created:', result);
  // { jobId: 'job-123', jobQueue: 'mailing' }
} catch (error) {
  console.error('Failed to send email:', error);
}

Message Queue System

The SDK uses a queue-based system for processing messages. All email notifications are processed through a queue to ensure reliable delivery.

Queue Configuration

The SDK automatically handles queue configuration and connection management. The following queues are available:

• mailing: Handles email notifications

Job Types

• send_mail: Processes email sending jobs

Error Handling

The SDK includes built-in error handling for common scenarios:

try {
  await mailing.sendEmail({
    email: '[email protected]',
    template: MailTemplates.ADMIN_INVITE,
    data: {
      // ... template data
    }
  });
} catch (error) {
  if (error instanceof QueueError) {
    console.error(`Queue error: ${error.queue} - ${error.operation}`);
  } else {
    console.error('Unexpected error:', error);
  }
}

Connection Management

The SDK manages connections automatically, but you can manually close connections when needed:

const mailing = Mailing.getInstance();

// Close the connection when done
mailing.closeConnection();

TypeScript Support

The SDK is written in TypeScript and includes type definitions for all features. This provides better development experience with autocomplete and type checking.

Type Definitions

interface EmailPayload {
  email: string;
  subject?: string;
  template: MailTemplates;
  data: Record<string, any>;
  from?: string;
}

enum MailTemplates {
  ADMIN_INVITE = 'admin-invite',
  PASSWORD_CHANGE_REQUEST = 'password-change-request',
  PASSWORD_CHANGE_NOTIFICATION = 'password-change-notification',
  NEW_SIGNIN = 'new-signin'
}

Best Practices

1. Error Handling

   • Always wrap SDK operations in try-catch blocks
   • Handle queue errors appropriately
   • Validate email payloads before sending

2. Connection Management

   • Close connections when they're no longer needed
   • Handle connection errors gracefully

3. Email Templates

   • Use the provided template enums to ensure type safety
   • Provide all required variables for the selected template
   • Validate data before sending

Future Features

The following features are planned for future releases:

Email Templates

• Support for more templates for account and liquidity service

Database Integration

• Support for database connections (MongoDB)

Webhook System

• Get all webhooks
• Support for multiple webhook formats (JSON, XML)
• Retry mechanisms for failed webhook deliveries
• Rate limiting and throttling

Enhanced Email Features

• Support for HTML email templates
• Rich text editor integration
• Email tracking and analytics
• A/B testing capabilities
• Bulk email sending
• Email scheduling
• Custom SMTP server support