@verasity/shared-models

A comprehensive shared models package for database schemas, utilities, and constants used across all applications in the email campaign system.

Overview

This package provides a centralized location for:

• Database Models: Mongoose schemas for all entities
• Utilities: Common functions for campaigns, users, validation, and tracking
• Constants: Application-wide constants and enums

Installation

From GitHub Packages (Private)

# Configure npm to use GitHub Packages
npm config set @verasity:registry https://npm.pkg.github.com

# Install the package
npm install @verasity/shared-models

Local Development

# Clone and install locally
git clone https://github.com/yourcompany/shared-models.git
cd shared-models
npm install
npm link

# In your project
npm link @verasity/shared-models

Usage

Basic Import

const { EmailCampaign, EmailTemplate, EmailTracking } = require('@verasity/shared-models');

// Use models directly
const campaign = new EmailCampaign({
    campaign_name: 'Test Campaign',
    user_id: userId,
    // ... other fields
});

Organized Imports

const { campaigns, templates, users, utils } = require('@verasity/shared-models');

// Access models by category
const campaign = new campaigns.EmailCampaign({ /* ... */ });
const template = new templates.EmailTemplate({ /* ... */ });
const user = new users.User({ /* ... */ });

// Use utilities
const riskCategory = utils.campaignUtils.getRiskCategory(75);
const isValid = utils.validationUtils.isValidEmail('[email protected]');

Constants

const { constants } = require('@verasity/shared-models');

// Use application constants
if (campaign.status === constants.CAMPAIGN_STATUS.COMPLETED) {
    // Handle completed campaign
}

// Credit types
const emailCredits = await CreditModel.findByCode(userId, constants.CREDIT_TYPES.EMAIL_CREDITS);

Available Models

Campaign Models

• EmailCampaign: Email campaign management with risk-based assignment
• SmsCampaign: SMS campaign management (TODO)
• VoiceCampaign: Voice campaign management (TODO)
• VideoCampaign: Video campaign management (TODO)

Template Models

• EmailTemplate: Email template with performance metrics
• SmsTemplate: SMS template (TODO)
• VoiceTemplate: Voice template (TODO)

Landing Page Models

• EmailLandingPage: Landing pages with conversion tracking
• SmsLandingPage: SMS landing pages (TODO)

Tracking Models

• EmailTracking: Comprehensive email tracking events
• SmsTracking: SMS tracking (TODO)

User Models

• User: Main user accounts with subscription management
• GroupUser: Individual users within groups for campaigns
• Group: User group management with analytics

Credit Models

• CreditModel: Credit management with expiration and renewal
• Assignment: Credit assignment tracking and audit trail

Risk Models

• RiskScore: User risk scoring with behavioral analysis

Utilities

Campaign Utils

const { campaignUtils } = require('@verasity/shared-models').utils;

// Risk category calculation
const category = campaignUtils.getRiskCategory(riskScore);

// Campaign validation
const validation = campaignUtils.validateTemplateMappings(mappings, templates, landingPages);

// Processing time estimation
const estimatedTime = campaignUtils.estimateProcessingTime(userCount, batchSize);

User Utils

const { userUtils } = require('@verasity/shared-models').utils;

// Email validation
const isValid = userUtils.isValidEmail(email);

// User data sanitization
const cleanData = userUtils.sanitizeUserData(rawUserData);

// Engagement calculation
const engagement = userUtils.calculateEngagementScore(user);

Validation Utils

const { validationUtils } = require('@verasity/shared-models').utils;

// Schema validation
const result = validationUtils.validateAndSanitize(data, schema);

// Campaign data validation
const campaignValidation = validationUtils.validateCampaignData(campaign);

Tracking Utils

const { trackingUtils } = require('@verasity/shared-models').utils;

// Generate tracking pixels
const pixel = trackingUtils.generateTrackingPixel(campaignId, userId, baseUrl);

// Calculate engagement metrics
const metrics = trackingUtils.calculateEngagementMetrics(trackingEvents);

// Performance reporting
const report = trackingUtils.generatePerformanceReport(campaignId, events);

Constants

All application constants are available through the constants export:

const { constants } = require('@verasity/shared-models');

// Campaign status
constants.CAMPAIGN_STATUS.DRAFT
constants.CAMPAIGN_STATUS.PROCESSING
constants.CAMPAIGN_STATUS.COMPLETED

// Credit types
constants.CREDIT_TYPES.EMAIL_CAMPAIGNS
constants.CREDIT_TYPES.EMAIL_CREDITS

// Risk levels
constants.RISK_LEVELS.LOW
constants.RISK_LEVELS.MEDIUM
constants.RISK_LEVELS.HIGH

// Default values
constants.DEFAULTS.BATCH_SIZE
constants.DEFAULTS.EMAIL_CONCURRENCY

Model Features

Advanced Features

Risk-Based Campaign Assignment

const campaign = new EmailCampaign({
    template_landing_mappings: [
        {
            template_id: templateId,
            landing_page_id: landingPageId,
            risk_score: 'high'
        }
    ]
});

Credit Management with Expiration

const credit = new CreditModel({
    code: 'EMAIL_CREDITS',
    credit: 1000,
    expires_at: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
    auto_renew: true
});

Comprehensive Tracking

const tracking = new EmailTracking({
    type: 'opened',
    campaign_id: campaignId,
    groupuser_id: userId,
    device_info: {
        device_type: 'mobile',
        browser: 'Chrome',
        os: 'iOS'
    }
});

Virtual Properties

Models include useful virtual properties:

// Campaign success rate
console.log(campaign.successRate); // Calculated from emails_sent/total_users

// User engagement rate
console.log(user.engagement_rate); // Calculated from interaction metrics

// Credit usage percentage
console.log(credit.usage_percentage); // Calculated from used/initial

Instance Methods

Models provide helpful instance methods:

// Update campaign progress
await campaign.updateProgress(emailsSent, emailsFailed);

// Record user interaction
await riskScore.recordCampaignInteraction('clicked', campaignId);

// Deduct credits
await credit.deductCredit(100, campaignId, 'campaign', 'Campaign execution');

Database Indexes

All models include optimized indexes for performance:

• Campaign queries: user_id + status, worker_instance + status
• User queries: email, group_id + isDeleted, risk_category
• Tracking queries: campaign_id + type, groupuser_id + type
• Credit queries: user_id + code, expires_at

Migration Guide

From Individual Models

If you're currently importing models individually:

// Old way
const EmailCampaign = require('../models/EmailCampaign');
const EmailTemplate = require('../models/EmailTemplate');

// New way
const { EmailCampaign, EmailTemplate } = require('@verasity/shared-models');

Worker Server Integration

For worker servers, use the shared models:

// worker-server/processors/emailCampaignProcessor.js
const { EmailCampaign, EmailTemplate, EmailTracking } = require('@verasity/shared-models');

// No need to maintain separate model files

Development

Adding New Models

1. Create the model file in the appropriate category folder
2. Add comprehensive schema with indexes and methods
3. Export from the main index.js file
4. Update this README with usage examples
5. Add tests for the new model

Testing

# Run tests (when implemented)
npm test

# Lint code
npm run lint

# Check for security vulnerabilities
npm audit

Publishing

To GitHub Packages

# Build and publish
npm run prepublishOnly
npm publish

Version Management

# Patch version (bug fixes)
npm version patch

# Minor version (new features)
npm version minor

# Major version (breaking changes)
npm version major

Support

For issues, questions, or contributions:

1. Check existing issues in the repository
2. Create a new issue with detailed description
3. For urgent issues, contact the development team

License

Private - Internal use only

Note: This package is designed for internal use within the email campaign system. All models and utilities are optimized for the specific requirements of phishing simulation and security awareness training platforms.