theunpartyinvite

Location: unparty-app/theunpartyinvite/
Status: Active Development (Production Hardening Phase)
Primary Purpose: Email automation and invitation system for UNPARTY ecosystem

Overview

theunpartyinvite is a Node.js-based email automation utility designed to handle invitation and communication workflows for the UNPARTY ecosystem. It provides a simple, secure, and extensible foundation for sending transactional emails, user onboarding messages, and system notifications.

Tech Stack

• Framework: Node.js
• Language: JavaScript (Node.js runtime)
• Email Service: Nodemailer (SMTP transport)
• Configuration: dotenv for environment variables
• Testing: Jest with comprehensive test coverage
• Platform: Cross-platform (Linux, macOS, Windows)
• Key Tools:
  • Gmail SMTP (configurable for other providers)
  • Environment-based configuration
  • Automated testing infrastructure

Key Features

Core Functionality

• Email Automation: Programmatic email sending via SMTP
• Template-Based Messages: Customizable subject and content
• Secure Credential Management: Environment variable-based authentication
• Error Handling: Graceful SMTP error management
• Modular Design: Exportable sendEmail function for reuse

Security & Privacy

• Environment Variables: Sensitive credentials never committed to repository
• .gitignore Protection: Automatic exclusion of .env files
• Privacy-First Design: Aligns with UNPARTY's creator ownership principles
• Test Coverage: 100% coverage on core functionality (6 passing tests, 3 skipped validation tests)

Development Features

• Jest Testing Suite: Comprehensive unit tests with mocking
• CI/CD Ready: Configured test scripts for automation
• Documentation: Multiple project health and readiness reports
• Code Quality: Modular, maintainable codebase

Architecture

Email Automation (Node.js)
├── emailSender.js (Core module)
│   ├── SMTP Configuration (Gmail/custom)
│   ├── Transporter Setup (nodemailer)
│   └── sendEmail() Function (async/await)
├── Configuration
│   ├── .env (Credentials - not committed)
│   └── package.json (Dependencies)
├── Testing
│   ├── emailSender.test.js (Jest tests)
│   └── coverage/ (Test reports)
└── Documentation
    ├── README.md (This file)
    ├── PROJECT_HEALTH_REPORT.md
    ├── FEATURE_READINESS_MATRIX.md
    ├── TESTING_STRATEGY.md
    ├── ACTION_ITEMS_TIMELINE.md
    └── DEPENDENCY_ANALYSIS.md

Installation & Setup

1. Clone the Repository

git clone https://github.com/unparty-app/theunpartyinvite.git
cd theunpartyinvite

2. Install Dependencies

npm install

3. Configure Environment Variables

Create a .env file in the project root:

# Email configuration
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password

Important:

• For Gmail, use an App Password instead of your regular password
• Never commit the .env file to version control
• The .gitignore file automatically excludes .env

4. Test the Setup

npm test

Expected output:

Test Suites: 1 passed, 1 total
Tests:       6 passed, 3 skipped, 9 total
Coverage:    100% statements, branches, functions, and lines

Note: 3 tests are skipped as they represent future enhancements (input validation). Current core functionality has 100% coverage.

5. Run the Email Sender

node emailSender.js

Usage

Basic Email Sending

const sendEmail = require('./emailSender');

// Send a welcome email
sendEmail(
  'user@example.com', 
  'Welcome to UNPARTY!', 
  'Thank you for joining our community.'
);

Custom Email Service

Modify the transporter configuration in emailSender.js:

let transporter = nodemailer.createTransport({
  host: 'smtp.your-provider.com',
  port: 587,
  secure: false,
  auth: {
    user: process.env.EMAIL_USER,
    pass: process.env.EMAIL_PASS
  }
});

Integration Example

// Import in your application
const sendInvite = require('./emailSender');

// Send invitation after user signup
async function onUserSignup(email, name) {
  await sendInvite(
    email,
    `Welcome ${name}!`,
    'Your UNPARTY account is ready. Start your journey today.'
  );
}

Integration Points

External Services

• Gmail SMTP: Default email transport (configurable)
• Nodemailer: Email sending library
• dotenv: Environment configuration

UNPARTY Ecosystem

• theunpartyapp (Web Platform): User onboarding emails
• theunpartyunppp (Native App): Welcome notifications
• theunpartyrunway (Dev Tools): System notifications
• theunpartycrawler (Analytics): Report delivery

Business Value

ABOUT (User Understanding)

• Clear Communication: Automated, consistent messaging to users
• Onboarding Experience: Welcome emails set expectations
• System Transparency: Notifications keep users informed
• Brand Consistency: Centralized email template management

BUILD (Creation Enablement)

• Developer Utility: Reusable email module for UNPARTY services
• Extensible Design: Easy to add HTML templates, attachments
• Test-Driven: Comprehensive test suite ensures reliability
• Documentation: Clear setup guides reduce implementation friction

CONNECT (Sharing & Distribution)

• User Engagement: Automated invitations drive adoption
• Community Building: Welcome messages foster connection
• Notification System: Foundation for alerts and updates
• Scalable Communication: Supports growth of UNPARTY ecosystem

Relationship to Ecosystem

theunpartyinvite serves as the communication layer for the UNPARTY ecosystem:

Integration Strategy

• Microservice Pattern: Standalone utility callable from any UNPARTY service
• Shared Module: Can be published as npm package for internal use
• Event-Driven: Triggered by user actions across ecosystem
• Cost Tracking: Email volume monitored via theunpartyrunway

Testing

Run All Tests

npm test

Watch Mode (Development)

npm run test:watch

Coverage Report

npm run test:coverage

Test Structure

• Unit Tests: Core sendEmail function validation
• Mock Testing: Nodemailer transport mocking
• Error Scenarios: SMTP failure handling
• Configuration Tests: Environment variable validation

Development Roadmap

Current Project Health: 3/10 (Basic Functionality Complete, Production Hardening Needed)

See PROJECT_HEALTH_REPORT.md for detailed assessment.

Context: The core email sending functionality is complete and well-tested, but production-grade features like enhanced error handling, logging, rate limiting, and health checks are still needed before deployment at scale.

Priority Improvements

• P0 - Critical:

  • Enhanced error handling and retry logic
  • Input validation and sanitization
  • Production logging framework

• P1 - High Priority:

  • HTML email templates
  • Rate limiting and throttling
  • Health check endpoint
  • CI/CD pipeline integration

• P2 - Medium Priority:

  • Email queue system
  • Template management UI
  • Analytics and tracking
  • Multi-provider support

Future Enhancements

• Rich HTML templates with inline CSS
• Attachment support (images, PDFs)
• Bounce and complaint handling
• A/B testing capabilities
• Internationalization (i18n)
• Email scheduling

Security & Privacy

Current Implementation

✅ Environment-based credentials (not in version control)
✅ .gitignore protection for sensitive files
✅ Test coverage for security-critical paths
✅ Zero external API calls (direct SMTP only)

Recommended Enhancements

• Input sanitization to prevent injection attacks
• Rate limiting per recipient
• Email address validation
• Encrypted credential storage
• Audit logging

Privacy Alignment

UNPARTY Core Principles:

• Creator Ownership: Users control their communication preferences
• Privacy-First: Minimal data collection, no tracking pixels
• Cost-Sensitive: Simple SMTP avoids expensive third-party services

Troubleshooting

Common Issues

1. Gmail Authentication Errors

Solution: Use App Passwords instead of regular password.

2. Missing Environment Variables

Solution: Ensure .env file exists with EMAIL_USER and EMAIL_PASS.

3. SMTP Connection Timeout

Solution: Check network/firewall settings. Gmail uses port 587 (TLS).

4. Module Not Found (Tests)

Solution: Run npm install to install dependencies.

Documentation

Available Reports

• PROJECT_HEALTH_REPORT.md: Code quality and security analysis
• FEATURE_READINESS_MATRIX.md: Production deployment criteria
• TESTING_STRATEGY.md: Test coverage and quality assurance
• ACTION_ITEMS_TIMELINE.md: 6-8 week improvement roadmap
• DEPENDENCY_ANALYSIS.md: Security and license review

Contributing

Development Workflow

1. Create feature branch: git checkout -b feature/your-feature
2. Make changes and add tests
3. Run tests: npm test
4. Commit with descriptive message
5. Push and create pull request

Code Standards

• Maintain 80%+ test coverage
• Follow existing code style
• Document new functions
• Update README for new features

License

ISC License (Permissive)

Dependencies use compatible licenses:

• nodemailer: MIT
• dotenv: BSD-2-Clause
• jest: MIT

Support & Contact

• Issues: GitHub Issues
• Ecosystem: Part of UNPARTY (36 repositories)
• Primary Contact: justin@unparty.app

Last Updated: 2025-10-30
Maintained By: UNPARTY Development Team
Ecosystem Role: Communication & Notification Layer

Status: 🚧 Active Development (Production Hardening Phase)
Focus: Secure, scalable email automation supporting UNPARTY's mission of creator ownership, privacy, and cost-sensitivity.