@gradientfi/centpub NPM

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:

Admin Invite (admin-invite)
- Subject: "Verify your email"
- Required variables:
  - business: string
  - firstname: string
  - link: string
  - role: string
Password Change Request (password-change-request)
- Subject: "Reset temporary password"
- Required variables:
  - name: string
  - verification_code: string
Password Change Notification (password-change-notification)
- Subject: "Reset password Notification"
- Required variables:
  - name: string
  - date: string
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: 'user@example.com',
    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: 'user@example.com',
    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

Error Handling
- Always wrap SDK operations in try-catch blocks
- Handle queue errors appropriately
- Validate email payloads before sending
Connection Management
- Close connections when they're no longer needed
- Handle connection errors gracefully
Email Templates
- Use the provided template enums to ensure type safety
- Provide all required variables for the selected template
- Validate data before sending