@chargebee/chargebee-apps-shared

@chargebee/chargebee-apps-shared

Core interfaces, types, and utilities shared across all Chargebee Apps CLI packages.

Overview

This package serves as the foundation for the Chargebee Apps CLI ecosystem, providing:

• Common interfaces that all implementations must follow
• Shared types used across packages
• Core utilities for logging, sandbox management, and validation
• Contracts that ensure consistency between public and private implementations

Architecture

The shared package follows a strict interface-first design, ensuring that both public-facing and internal implementations adhere to the same contracts.

@chargebee/chargebee-apps-shared
├── src/
│   ├── config/          # Environment detection and path resolution
│   ├── dependency/      # Dependency management and npm operations
│   ├── types/           # Common TypeScript interfaces and types
│   ├── logger/          # Logging interfaces and utilities
│   ├── sandbox/         # Sandbox execution interfaces
│   ├── event-handler/   # Event handling interfaces
│   └── index.ts         # Main exports

Components

This package contains core interfaces and utilities organized into focused modules. Each module has detailed documentation with code examples and usage patterns.

Configuration and Environment

• EnvironmentConfig - Detects execution environment (development, production, test)
• PathResolver - Centralized path resolution based on environment

Dependency Management

• DependencyManager - Isolated npm installations and secure module loading

Core Interfaces and Types

• File System Operations (CBFileSystem) - Abstracted file operations
• Process Operations (CBProcess) - Abstracted process operations
• Logger Interface (ICBLogger) - Standardized logging for user code
• Event Data Structures (EventRecord, Manifest) - Event and configuration types
• Command Options - Standardized CLI option interfaces

Utilities

• Internal Logger (__logger) - CLI operation logging
• Sandbox Context (SandboxContext) - Execution context correlation
• Validation Utilities - Application structure validation

Sandbox Framework

• Sandbox Wrapper (ISandboxWrapper) - Secure code execution interface
• Event Handler (IEventHandler) - Event processing interface

Usage

This package is imported by other packages in the workspace to implement the defined interfaces:

import { 
	ICBLogger, 
	CBFileSystem, 
	ISandboxWrapper, 
	DependencyManager,
	PathResolver,
	EnvironmentConfig 
} from '@chargebee/chargebee-apps-shared';

// Environment detection
const envConfig = new EnvironmentConfig();
console.log(`Running in ${envConfig.getEnvironment()} mode`);

// Path resolution
const pathResolver = new PathResolver();
const templatesPath = pathResolver.getPublicLibsTemplatesDir();

// Dependency management
const dependencyManager = new DependencyManager();
await dependencyManager.ensureDependencies('/app/path', manifest);

// Implement interfaces in your package
export class MyLogger implements ICBLogger {
  // Implementation details...
}

Development

Standard npm scripts: build, test, test:coverage, and type-check.

Dependencies

Runtime: semver (for dependency version validation) Development: TypeScript 5.0+, Jest, @types/node

Package Structure

• src/config/ - Environment detection and path resolution utilities
• src/dependency/ - Dependency management with isolated npm installations and secure module loading
• src/types/ - Core types and interfaces with usage examples
• src/logger/ - Logging interfaces and utilities with implementation patterns
• src/sandbox/ - Sandbox execution interfaces with security examples
• src/event-handler/ - Event handling interfaces with processing patterns
• tests/unit/ - Unit tests

Contributing

When adding new interfaces or types:

• Define clear contracts with comprehensive JSDoc comments
• Ensure backward compatibility when possible
• Add comprehensive unit tests
• Consider impact on both public and private implementations