# @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:

```typescript
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/`](src/config/README.md) - Environment detection and path resolution utilities
- [`src/dependency/`](src/dependency/README.md) - Dependency management with isolated npm installations and secure module loading
- [`src/types/`](src/types/README.md) - Core types and interfaces with usage examples
- [`src/logger/`](src/logger/README.md) - Logging interfaces and utilities with implementation patterns
- [`src/sandbox/`](src/sandbox/README.md) - Sandbox execution interfaces with security examples  
- [`src/event-handler/`](src/event-handler/README.md) - Event handling interfaces with processing patterns
- `tests/unit/` - Unit tests

## Contributing

When adding new interfaces or types:
1. Define clear contracts with comprehensive JSDoc comments
2. Ensure backward compatibility when possible  
3. Add comprehensive unit tests
4. Consider impact on both public and private implementations