Zync NestJS Library

A comprehensive NestJS library providing database backup utilities, file upload services, and common utilities for modern web applications.

📦 Features

• Database Backup Service: Automated MongoDB backup with cloud storage support
• File Upload Service: Handle file uploads with image resizing and cloud storage
• Bucket Service: AWS S3/DigitalOcean Spaces integration
• Firebase Service: Push notification service with FCM integration
• Mailer Service: Email sending service with template support
• Exabytes SMS Service: SMS sending service via Exabytes API
• UltraMsg Service: WhatsApp messaging service via UltraMsg API
• Message Service: Unified messaging service for various channels
• Utility Functions: Common helpers for date formatting, file handling, and more

🚀 Installation

Local Development

# Clone the repository
git clone <repository-url>
cd zync-nest-library

# Install dependencies
pnpm install

# Build the library
pnpm run build

Using in Other Projects

Method 1: File Path Dependency (Recommended for pnpm)

In your project's package.json:

{
  "dependencies": {
    "zync-nest-library": "file:../../zync-library/zync-nest-library"
  }
}

Then run:

pnpm install

Method 2: npm link (For npm users)

# In the library directory
npm link

# In your consuming project
npm link zync-nest-library

Method 3: pnpm link (Alternative for pnpm)

# Setup pnpm global bin directory (one-time setup)
pnpm setup

# In the library directory
pnpm link --global

# In your consuming project
pnpm link --global zync-nest-library

📚 Usage

Basic Setup

Import the required modules in your NestJS application:

import { Module } from '@nestjs/common';
import { 
  ApDbBackupModule, 
  UploadModule,
  FirebaseModule,
  MailerModule,
  MessageModule
} from 'zync-nest-library';

@Module({
  imports: [
    ApDbBackupModule,
    UploadModule,
    FirebaseModule,
    MailerModule,
    MessageModule,
    // ... other modules
  ],
})
export class AppModule {}

Database Backup Service

The DbBackupService provides automated MongoDB backup functionality with optional cloud storage.

Configuration

import { IDbBackupConfig } from 'zync-nest-library';

const backupConfig: IDbBackupConfig = {
  env: 'production',
  mongodb: {
    connectionStrings: 'mongodb://localhost:27017/mydb'
    // or multiple connections: ['mongodb://...', 'mongodb://...']
  },
  backup: {
    dir: './backups',
    enabled: true,
    maxBackups: 10,
    isDownload: false,
    uploadToSpace: true
  },
  spaces: {
    name: 'my-bucket',
    region: 'nyc3',
    key: 'your-access-key',
    secret: 'your-secret-key',
    endpoint: 'https://nyc3.digitaloceanspaces.com',
    dir: 'backups'
  }
};

Usage

import { Injectable } from '@nestjs/common';
import { DbBackupService } from 'zync-nest-library';

@Injectable()
export class MyService {
  constructor(private readonly backupService: DbBackupService) {}

  async createBackup() {
    await this.backupService.backup();
  }

  async scheduleBackups() {
    // Set up automated backups (runs every 6 hours by default)
    this.backupService.startBackupSchedule();
  }
}

Upload Service

The UploadService handles file uploads with automatic image resizing and cloud storage integration.

Interfaces

import { IUpload, IUploadResult } from 'zync-nest-library';

// Upload interface
interface IUpload {
  type?: "base64" | "buffer";
  file: any;
  filepath?: string;
  filename: string;
  filetype: string;
  dir?: string;
  transformName?: boolean;
}

// Upload result
interface IUploadResult {
  name: string;
  type: string;
  uri: string;
  lgUri?: string;  // Large thumbnail
  mdUri?: string;  // Medium thumbnail
  smUri?: string;  // Small thumbnail
}

Usage

import { Injectable } from '@nestjs/common';
import { UploadService } from 'zync-nest-library';

@Injectable()
export class FileService {
  constructor(private readonly uploadService: UploadService) {}

  async uploadFile(file: Express.Multer.File): Promise<IUploadResult> {
    const uploadData: IUpload = {
      type: 'buffer',
      file: file.buffer,
      filename: file.originalname,
      filetype: file.mimetype,
      dir: 'uploads',
      transformName: true
    };

    return await this.uploadService.uploadFile(uploadData);
  }

  async uploadBase64Image(base64: string): Promise<IUploadResult> {
    const uploadData: IUpload = {
      type: 'base64',
      file: base64,
      filename: 'image.jpg',
      filetype: 'image/jpeg',
      dir: 'images'
    };

    return await this.uploadService.uploadFile(uploadData);
  }
}

Bucket Service

The BucketService provides direct integration with cloud storage services (AWS S3, DigitalOcean Spaces).

Configuration

// In your environment or config
export default () => ({
  bucket: {
    name: process.env.aws_bucket,
    region: process.env.aws_s3_region,
    key: process.env.aws_access_key_id,
    secret: process.env.aws_secret_access_key,
    endpoint: process.env.aws_s3_endpoint,
  }
});

Usage

import { Injectable } from '@nestjs/common';
import { BucketService } from 'zync-nest-library';

@Injectable()
export class CloudStorageService {
  constructor(private readonly bucketService: BucketService) {}

  async uploadToBucket(buffer: Buffer, key: string) {
    return await this.bucketService.upload(buffer, key);
  }

  async downloadFromBucket(key: string) {
    return await this.bucketService.download(key);
  }

  async deleteFromBucket(key: string) {
    return await this.bucketService.delete(key);
  }
}

Firebase Service

The FirebaseService provides push notification functionality using Firebase Cloud Messaging (FCM).

Configuration

First, you need to set up Firebase Admin SDK with a service account key:

1. Download your Firebase service account key JSON file
2. Place it in your project root as serviceAccount.json
3. The service will automatically initialize Firebase Admin SDK

Interfaces

import { INotification } from 'zync-nest-library';

interface INotification {
  title: string;
  body: string;
  topic?: string;
  image?: string;
  data?: {
    type: "ORDER" | "SCHEME" | "RATE" | "PUSH" | "FEED";
    [x: string]: string;
  };
}

Usage

import { Injectable } from '@nestjs/common';
import { FirebaseService, INotification } from 'zync-nest-library';

@Injectable()
export class NotificationService {
  constructor(private readonly firebaseService: FirebaseService) {}

  async sendToDevices(tokens: string[], notification: INotification) {
    await this.firebaseService.sendPushNotification(tokens, notification);
  }

  async sendToTopic(topic: string, notification: INotification) {
    await this.firebaseService.sendPushNotificationToTopic(topic, notification);
  }

  async subscribeToTopic(topic: string, tokens: string[]) {
    await this.firebaseService.subscribeToTopic(topic, tokens);
  }
}

Mailer Service

The MailerService provides email sending functionality with template support.

Configuration

import { IMailerConfig } from 'zync-nest-library';

const mailerConfig: IMailerConfig = {
  logo: 'https://example.com/logo.png',
  host: 'smtp.gmail.com',
  user: '[email protected]',
  pass: 'your-app-password',
  from: '[email protected]',
  port: '587',
  playStore: 'https://play.google.com/store/apps/details?id=your.app',
  appStore: 'https://apps.apple.com/app/your-app/id123456789'
};

Environment Variables

# Email Configuration
MAILER_HOST=smtp.gmail.com
[email protected]
MAILER_PASS=your-app-password
[email protected]
MAILER_PORT=587
MAILER_LOGO=https://example.com/logo.png
MAILER_PLAY_STORE=https://play.google.com/store/apps/details?id=your.app
MAILER_APP_STORE=https://apps.apple.com/app/your-app/id123456789

Usage

import { Injectable } from '@nestjs/common';
import { MailerService, IMail } from 'zync-nest-library';

@Injectable()
export class EmailService {
  constructor(private readonly mailerService: MailerService) {}

  async sendEmail(mailData: IMail) {
    await this.mailerService.sendMail(mailData);
  }

  async sendWelcomeEmail(email: string, name: string) {
    const mailData: IMail = {
      to: email,
      subject: 'Welcome to Our Platform',
      template: 'welcome',
      context: {
        name: name,
        loginUrl: 'https://yourapp.com/login'
      }
    };
    
    await this.mailerService.sendMail(mailData);
  }
}

Exabytes SMS Service

The Exabytes SMS service provides SMS sending functionality via Exabytes API.

Configuration

Configure the Exabytes SMS service using environment variables:

# Exabytes SMS Configuration
exabytes_sms_username=your_username
exabytes_sms_password=your_password
exabytes_sms_url=https://sms.exabytes.com/api/send
exabytes_sms_sendid=YOUR_SENDER_ID

Usage

The Exabytes SMS service is typically used through the unified Message Service for SMS functionality.

UltraMsg Service

The UltraMsgService provides WhatsApp messaging functionality via UltraMsg API.

Configuration

Configure the UltraMsg service using environment variables:

# UltraMsg Configuration
ultramsg_instance=your_instance_id
ultramsg_token=your_api_token
ultramsg_url=https://api.ultramsg.com

Usage

import { Injectable } from '@nestjs/common';
import { UltraMsgService } from 'zync-nest-library';

@Injectable()
export class WhatsAppService {
  constructor(private readonly ultraMsgService: UltraMsgService) {}

  async sendMessage(phone: string, message: string) {
    return await this.ultraMsgService.sendMessage(phone, message);
  }

  async sendDocument(phone: string, document: string, caption?: string) {
    return await this.ultraMsgService.sendDocument(phone, document, caption);
  }
}

Message Service

The MessageService provides a unified interface for sending messages across different channels (Email, SMS, WhatsApp, Push Notifications).

Usage

import { Injectable } from '@nestjs/common';
import { MessageService } from 'zync-nest-library';

@Injectable()
export class UnifiedMessageService {
  constructor(private readonly messageService: MessageService) {}

  async sendMultiChannelMessage(
    email: string,
    phone: string,
    pushTokens: string[],
    message: any
  ) {
    // Send via email
    await this.messageService.sendEmail({
      to: email,
      subject: message.subject,
      template: message.template,
      context: message.context
    });

    // Send via SMS (if configured)
    // await this.messageService.sendSMS(phone, message.text);

    // Send via WhatsApp (if configured)
    // await this.messageService.sendWhatsApp(phone, message.text);

    // Send push notification
    await this.messageService.sendPushNotification(pushTokens, {
      title: message.title,
      body: message.body,
      data: message.data
    });
  }
}

Utility Functions

The library includes various utility functions for common operations:

import {
  DateUtils,
  mkdir,
  uuidFilenameTransform,
  bufferFromBase64,
  getBase64FileName,
  toSlug,
  fileDownloadResponse
} from 'zync-nest-library';

// Date utilities
const timestamp = DateUtils.formatStringDate('25/12/2023');

// File utilities
const uniqueFilename = uuidFilenameTransform('image.jpg'); // Returns: uuid.jpg
const buffer = bufferFromBase64('data:image/jpeg;base64,...');
const filename = getBase64FileName('data:image/jpeg;base64,...'); // Returns: uuid.jpeg

// String utilities
const slug = toSlug('My Product Title'); // Returns: my-product-title-abc123

// Directory creation
mkdir('./uploads/images');

// File download response (Express)
fileDownloadResponse(res, buffer, 'report', 'pdf');

🔧 Configuration

Environment Variables

# Cloud Storage (DigitalOcean Spaces / AWS S3)
#-----------------s3-----------------#
aws_access_key_id=xxxx
aws_secret_access_key=xxxxx
aws_s3_region=nyc3
aws_s3_endpoint=https://xxxx.nyc3.digitaloceanspaces.com
aws_bucket=xxxx
aws_base_key=development

# Email Configuration (Mailer Service)
#-----------------mailer-----------------#
MAILER_HOST=smtp.gmail.com
[email protected]
MAILER_PASS=your-app-password
[email protected]
MAILER_PORT=587
MAILER_LOGO=https://example.com/logo.png
MAILER_PLAY_STORE=https://play.google.com/store/apps/details?id=your.app
MAILER_APP_STORE=https://apps.apple.com/app/your-app/id123456789

# Exabytes SMS Configuration
#-----------------exabytes-----------------#
exabytes_sms_username=your_username
exabytes_sms_password=your_password
exabytes_sms_url=https://sms.exabytes.com/api/send
exabytes_sms_sendid=YOUR_SENDER_ID

# UltraMsg WhatsApp Configuration
#-----------------ultramsg-----------------#
ultramsg_instance=your_instance_id
ultramsg_token=your_api_token
ultramsg_url=https://api.ultramsg.com

# Firebase Configuration
#-----------------firebase-----------------#
# Note: Firebase requires a service account JSON file
# Place your serviceAccount.json file in the project root
# Download from: Firebase Console > Project Settings > Service Accounts

🛠️ Development

Scripts

# Build the library
pnpm run build

# Build in watch mode
pnpm run build:watch

# Clean build artifacts
pnpm run clean

# Build and clean
pnpm run clean && pnpm run build

Project Structure

libs/
├── src/
│   ├── dbbackup/          # Database backup functionality
│   │   ├── backup.config.ts
│   │   ├── backup.interface.ts
│   │   ├── backup.module.ts
│   │   └── backup.service.ts
│   ├── upload/            # File upload functionality
│   │   ├── bucket/        # Cloud storage integration
│   │   ├── upload.interface.ts
│   │   ├── upload.module.ts
│   │   ├── upload.service.ts
│   │   └── upload.utils.ts
│   ├── firebase/          # Firebase push notifications
│   │   ├── firebase.interface.ts
│   │   ├── firebase.module.ts
│   │   └── firebase.service.ts
│   ├── mailer/            # Email service
│   │   ├── mailer.interface.ts
│   │   ├── mailer.module.ts
│   │   └── mailer.service.ts
│   ├── message/           # Unified messaging service
│   │   ├── message.module.ts
│   │   └── message.service.ts
│   ├── exabytes/          # SMS service via Exabytes
│   │   ├── exabytes.config.ts
│   │   ├── exabytes.interface.ts
│   │   ├── exabytes.module.ts
│   │   └── exabytes.service.ts
│   ├── ultramsg/          # WhatsApp service via UltraMsg
│   │   ├── ultramsg.config.ts
│   │   ├── ultramsg.interface.ts
│   │   ├── ultramsg.module.ts
│   │   └── ultramsg.service.ts
│   ├── utils/             # Utility functions
│   │   ├── date.ts
│   │   ├── object.ts
│   │   └── index.ts
│   └── index.ts           # Main exports
└── tsconfig.lib.json

Common Issues

1. pnpm link not working

If pnpm link doesn't work, use the file path dependency method instead:

{
  "dependencies": {
    "zync-nest-library": "file:../../zync-library/zync-nest-library"
  }
}

2. Peer dependency warnings

If you see peer dependency warnings (e.g., @nestjs/core version mismatch), you can:

• Update your project's NestJS version to match
• Or add to your package.json:

{
  "pnpm": {
    "peerDependencyRules": {
      "ignoreMissing": ["@nestjs/core"]
    }
  }
}

3. Build errors after linking

Make sure to build the library first:

cd zync-nest-library
pnpm run build

4. Changes not reflected

After making changes to the library:

# In library directory
pnpm run build

# No need to reinstall - changes are automatically available in linked projects

🐛 Issues

If you encounter any issues or have questions, please file an issue on the project repository.