@automate-army/common

A professional TypeScript utility library providing shared services and common operations for modern applications. Built with modularity, type safety, and developer experience in mind.

Overview

@automate-army/common is a comprehensive utilities package designed to provide robust, well-tested, and type-safe solutions for common development needs. Each module is independently usable while maintaining consistent patterns and professional standards.

Features

• 🏗️ Modular Architecture - Import only what you need
• 📝 Full TypeScript Support - Complete type definitions and IntelliSense
• 🛡️ Professional Error Handling - Comprehensive error classes with detailed information
• ✅ Thoroughly Tested - High test coverage with comprehensive test suites
• 🔧 Flexible Configuration - Environment variables and constructor options
• 🚀 Production Ready - Battle-tested and optimized for performance

Installation

npm install @automate-army/common

Available Modules

🔐 Security

Professional encryption and security utilities with AES-256-CBC encryption, flexible key management, and batch operations.

import { CryptoService } from '@automate-army/common';

const crypto = new CryptoService();
const result = crypto.encrypt('sensitive-data');
const decrypted = crypto.decrypt(result.encrypted, result.iv);

Key Features:

• AES encryption with multiple algorithm support
• Environment variable and constructor-based key management
• Batch encryption/decryption operations
• Comprehensive error handling

📖 Security Module Documentation

🛡️ Validation (Coming Soon)

Input validation, sanitization, and data verification utilities.

📅 Date & Time (Coming Soon)

Date manipulation, formatting, and timezone utilities.

🌐 Network (Coming Soon)

HTTP utilities, request helpers, and network-related tools.

Quick Start

Basic Usage

// Import main utilities
import { CryptoService } from '@automate-army/common';

// Use the service
const crypto = new CryptoService({
  encryptionKey: 'your-256-bit-key-in-hex-format'
});

const result = crypto.encrypt('Hello, World!');
console.log('Encrypted:', result.encrypted);
console.log('IV:', result.iv);

Modular Imports

// Import from specific modules for advanced usage
import { CryptoService, InvalidKeyError } from '@automate-army/common/security';

// Tree-shakable imports
import { CryptoService } from '@automate-army/common';

Security Module

The Security module provides professional-grade encryption services with flexible configuration and comprehensive error handling.

CryptoService

Constructor

new CryptoService(options?: CryptoOptions)

Configuration Options:

• algorithm?: string - Encryption algorithm (default: 'aes-256-cbc')
• encryptionKey?: string - Hex-encoded encryption key

Key Management Priority:

1. Constructor parameter
2. AUTOMATE_ARMY_ENCRYPTION_KEY environment variable
3. Throws InvalidKeyError if neither provided

Core Methods

encrypt(data: string, iv?: string): EncryptResult

Encrypts data using the configured algorithm.

const crypto = new CryptoService({ encryptionKey: 'your-key' });

// With random IV (recommended)
const result = crypto.encrypt('sensitive-data');

// With specific IV (for deterministic encryption)
const result = crypto.encrypt('sensitive-data', 'your-iv-in-hex');

decrypt(encryptedData: string, iv: string): string

Decrypts previously encrypted data.

const decrypted = crypto.decrypt(result.encrypted, result.iv);

batchEncrypt(params: BatchEncryptParams): BatchEncryptResult

Efficiently encrypts multiple items.

const result = crypto.batchEncrypt({
  tokens: ['item1', 'item2', 'item3']
});

batchDecrypt(params: BatchDecryptParams): BatchDecryptResult

Efficiently decrypts multiple items.

const result = crypto.batchDecrypt({
  encryptedData: [
    { encrypted: 'data1', iv: 'iv1' },
    { encrypted: 'data2', iv: 'iv2' }
  ]
});

Environment Configuration

# Set encryption key via environment variable
export AUTOMATE_ARMY_ENCRYPTION_KEY="your-256-bit-key-in-hex"

Key Requirements:

• Valid hexadecimal string
• Length must match algorithm:
  • AES-256: 64 hex characters (32 bytes)
  • AES-192: 48 hex characters (24 bytes)
  • AES-128: 32 hex characters (16 bytes)

Error Handling

Comprehensive error handling with detailed error information:

import { CryptoService, InvalidKeyError } from '@automate-army/common/security';

try {
  const crypto = new CryptoService();
  const result = crypto.encrypt('data');
} catch (error) {
  if (error instanceof InvalidKeyError) {
    console.log('Error:', error.message);
    console.log('Code:', error.code);
    console.log('Timestamp:', error.timestamp);
  }
}

Available Error Types:

• CryptoError - Base error class
• InvalidKeyError - Key-related issues
• EncryptionError - Encryption failures
• DecryptionError - Decryption failures
• InvalidIVError - IV validation errors
• InvalidInputError - Input validation errors
• UnsupportedAlgorithmError - Algorithm support errors

Supported Algorithms

• aes-256-cbc (default) - 32-byte key
• aes-192-cbc - 24-byte key
• aes-128-cbc - 16-byte key
• Any algorithm supported by Node.js crypto module

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { CryptoService, EncryptResult } from '@automate-army/common';

const crypto = new CryptoService();
const result: EncryptResult = crypto.encrypt('data');

Development

Setup

git clone https://github.com/automatearmy/common.git
cd common
npm install

Available Scripts

npm run build          # Build the package
npm run test           # Run tests
npm run test:coverage  # Run tests with coverage
npm run lint           # Run ESLint
npm run format         # Format code with Prettier
npm run docs           # Generate documentation

Testing

Comprehensive test coverage including:

• Unit tests for all functionality
• Integration tests with real operations
• Edge cases and error scenarios
• Performance tests for large datasets

npm test

Security Best Practices

1. Key Management: Use secure key management systems in production
2. Environment Variables: Store sensitive keys in environment variables
3. Key Rotation: Implement regular key rotation policies
4. IV Usage: Never reuse initialization vectors with the same key
5. Error Handling: Implement proper error handling for all operations

Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Commit Convention

This project uses Conventional Commits for automatic versioning:

• feat: - New features (minor version bump)
• fix: - Bug fixes (patch version bump)
• feat!: or BREAKING CHANGE: - Breaking changes (major version bump)

Roadmap

• ✅ Security Module (Encryption/Decryption)
• 🔄 Validation Module (Input validation and sanitization)
• 📋 Date & Time Module (Date manipulation and formatting)
• 📋 Network Module (HTTP utilities and helpers)
• 📋 String Module (String manipulation and utilities)
• 📋 Array Module (Array operations and transformations)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for a detailed list of changes.

Made with ❤️ by Automate Army