@chargebee/chargebee-apps-libs

@chargebee/chargebee-apps-libs

Production-ready library implementations for the public Chargebee Apps CLI.

Overview

This package provides concrete implementations of the interfaces defined in @chargebee/chargebee-apps-shared, specifically designed for public use. These implementations focus on local development, testing, and user-facing functionality without exposing internal production details. It also includes the web UI for interactive testing of serverless applications.

Architecture

The public-libs package implements the contracts defined in the shared package while providing functionality optimized for local development environments.

@chargebee/chargebee-apps-libs
├── src/
│   ├── config/          # Configuration management
│   ├── logger/          # Winston-based logging implementations
│   ├── sandbox/         # VM-based sandbox execution
│   ├── libs/            # Utility services (port, template, etc.)
│   └── index.ts         # Main exports

Core Components

This package provides concrete implementations organized into focused modules. Each module has detailed documentation with implementation examples and usage patterns.

Configuration Management

• ConfigLoader - Application configuration with caching and validation

Logging System

• CBPublicLogger - Winston-based logging with multiple transports
• Safe Console - Controlled console interface for sandboxed code

Sandbox Execution

• PublicSandboxWrapper - VM-based secure code execution environment

Utility Services

• PortService - Port validation and parsing utilities
• TemplateService - Template management and file operations
• FileSystemService - File system operations implementation
• ProcessService - Process operations implementation

Web UI

• Interactive Testing Interface - Web-based UI for testing serverless applications
• Event Simulation - Form-based event data input and testing
• Real-time Results - Live display of handler execution results and logs

Templates

Built-in Templates

The package includes starter templates for common use cases:

serverless-node-starter-app

A complete Node.js serverless application template with:

• Pre-configured manifest.json
• Sample event handlers
• Test data files
• TypeScript definitions

templates/serverless-node-starter-app/
├── handler/
│   └── handler.js       # Sample event handlers
├── test_data/
│   ├── customer_created.json
│   ├── subscription_created.json
│   └── invoice_generated.json
├── types/
│   └── types.d.ts       # TypeScript definitions
├── manifest.json        # Application configuration
├── jsconfig.json        # JavaScript configuration
└── README.md            # Template documentation

serverless-node-starter-app-with-iparams

Same as the starter app, plus sectioned installation parameters:

• iparams.json — parameter definitions under installation_parameters.sections
• iparams.local.json — local values keyed by section name
• Handlers receive payload.iparams.<section>.<param>

templates/serverless-node-starter-app-with-iparams/
├── handler/
│   └── handler.js       # Sample event handlers
├── test_data/
│   ├── customer_created.json
│   ├── subscription_created.json
│   └── invoice_generated.json
├── types/
│   └── types.d.ts       # TypeScript definitions
├── iparams.json         # Parameter definitions (sectioned schema)
├── iparams.local.json   # Local parameter values, keyed by section
├── manifest.json        # Application configuration
├── jsconfig.json        # JavaScript configuration
└── README.md            # Template documentation

See templates/serverless-node-starter-app-with-iparams/README.md for the full iparams schema and examples.

Usage Examples

Complete Development Workflow

import {
  ConfigLoader,
  createCBPublicLogger,
  PublicSandboxWrapper,
  ManifestValidator,
  TemplateService
} from '@chargebee/chargebee-apps-libs';
import { DependencyManager } from '@chargebee/chargebee-apps-shared';

// 1. Load configuration
const configLoader = new ConfigLoader();
const allowedModules = configLoader.loadAllowedModules();

// 2. Create application from template
const templateService = new TemplateService();
await templateService.copyTemplate('serverless-node-starter-app', './my-app');

// 3. Validate manifest
const validator = new ManifestValidator(allowedModules);
const manifest = validator.validateFile('./my-app/manifest.json');

// 4. Setup dependencies
const dependencyManager = new DependencyManager();
await dependencyManager.ensureDependencies('./my-app', manifest);

// 5. Create logger for user code
const logger = createCBPublicLogger(fileSystem, process, './my-app');

// 6. Execute user code in sandbox
const sandbox = new PublicSandboxWrapper();
const result = await sandbox.execute(handlerCode, {
  event: eventData,
  console: createSafeConsole(logger),
  require: dependencyManager.createIsolatedRequire('./my-app', allowedModules)
});

Custom Logger Implementation

import { CBPublicLogger, createSafeConsole } from '@chargebee/chargebee-apps-libs';
import { CBFileSystem, CBProcess } from '@chargebee/chargebee-apps-shared';

class MyCustomLogger extends CBPublicLogger {
  constructor(fileSystem: CBFileSystem, process: CBProcess, userCodeDir: string) {
    super(fileSystem, process, userCodeDir);
    // Add custom transports or configuration
  }
  
  customLog(level: string, message: string): void {
    // Custom logging logic
    this.log(level, message);
  }
}

Advanced Sandbox Configuration

import { PublicSandboxWrapper } from '@chargebee/chargebee-apps-libs';

const sandbox = new PublicSandboxWrapper();

// Custom context creation
const context = {
  event: eventData,
  console: createSafeConsole(logger),
  require: customRequireFunction,
  // Add custom globals
  utils: {
    timestamp: () => new Date().toISOString(),
    uuid: () => crypto.randomUUID()
  }
};

const result = await sandbox.execute(handlerCode, context);

Development

Building

npm run build

Testing

npm run test
npm run test:coverage

Linting

npm run lint
npm run lint:fix

Dependencies

Runtime Dependencies

• @chargebee/chargebee-apps-shared: Core interfaces and types
• winston: Logging framework
• archiver: Zip file creation
• chalk: Terminal colors
• semver: Semantic versioning utilities

Development Dependencies

• TypeScript 5.0+: Type system and compilation
• Jest: Unit testing framework
• @types/node: Node.js type definitions

Package Structure

• src/config/ - Configuration management with caching and validation
• src/logger/ - Winston-based logging with multiple transports
• src/sandbox/ - VM-based secure code execution environment
• src/libs/ - Core utility services (port, template, file system, process)
• templates/ - Built-in application templates
• ui/ - Web UI for local development server
• tests/unit/ - Unit tests with comprehensive coverage

Testing

Unit Test Coverage

• Minimum 85% coverage required for all modules
• 90% coverage target for critical paths
• Comprehensive mocking of external dependencies
• Edge case and error condition testing

Test Categories

• Service Tests: Individual service functionality
• Integration Tests: Service interactions
• Template Tests: Template copying and validation
• Configuration Tests: Config loading and caching
• Dependency Tests: npm operations and module validation

Security Considerations

• Module Whitelisting: Only approved modules can be installed
• Version Constraints: Semver validation prevents malicious versions
• Path Traversal Protection: File operations are restricted to safe paths
• Sandboxed Execution: User code runs in isolated VM contexts
• Controlled Logging: User code logging is managed and correlated

Performance Features

• Configuration Caching: Loaded configs are cached for performance
• Lazy Dependency Installation: Dependencies installed only when needed
• Efficient File Operations: Optimized file copying and validation
• Memory Management: Proper cleanup of temporary resources

Error Handling

• Graceful Degradation: Services handle errors without crashing
• Detailed Error Messages: Clear, actionable error descriptions
• Proper Exit Codes: Consistent error reporting for automation
• Logging Integration: All errors are properly logged with context

Contributing

When adding new services or features:

• Implement the corresponding interface from @chargebee/chargebee-apps-shared
• Add comprehensive unit tests with 85%+ coverage
• Include JSDoc documentation for all public methods
• Follow the existing error handling patterns
• Update this README with usage examples