# Core Types and Interfaces

This directory defines the fundamental contracts and types used throughout the Chargebee Apps CLI ecosystem.

## Files

### `common.ts`
Contains all core interfaces, types, command options, and constants that ensure type safety and consistent behavior across all packages.

## Core Interfaces

### CBFileSystem
File system abstraction interface that enables cross-platform compatibility and testability by abstracting Node.js `fs` operations.

**Purpose:** Allows dependency injection of file system operations for testing and different environments.

**Usage:**
```typescript
import { CBFileSystem } from '@chargebee/chargebee-apps-shared';

class ConfigLoader {
  constructor(private fileSystem: CBFileSystem) {}
  
  loadConfig(path: string): any {
    if (this.fileSystem.existsSync(path)) {
      return JSON.parse(this.fileSystem.readFileSync(path, 'utf8'));
    }
    return {};
  }
}
```

### CBProcess
Process operations abstraction that wraps Node.js `process` object for environment interaction and testing.

**Purpose:** Enables dependency injection of process operations and provides a testable interface for environment variables and process control.

**Usage:**
```typescript
import { CBProcess } from '@chargebee/chargebee-apps-shared';

class EnvironmentService {
  constructor(private process: CBProcess) {}
  
  getEnvironment(): string {
    return this.process.env.NODE_ENV || 'development';
  }
}
```

### ICBLogger
Structured logging interface that provides consistent logging across all packages and environments.

**Purpose:** Defines the contract for logging implementations, allowing different loggers (console, file, cloud) to be used interchangeably.

**Usage:**
```typescript
import { ICBLogger } from '@chargebee/chargebee-apps-shared';

class EventProcessor {
  constructor(private logger: ICBLogger) {}
  
  process(event: any): void {
    this.logger.info('Processing event', { eventId: event.id });
    // Process logic
  }
}
```

## Core Types

### EventRecord
Defines the structure for webhook event data received from external systems.

**Purpose:** Ensures consistent event data structure across all event handlers and processing logic.

**Usage:**
```typescript
function handleWebhook(event: EventRecord): void {
  console.log(`Processing ${event.event_type} at ${event.occurred_at}`);
  // Handle specific event type
}
```

### Manifest
Application configuration structure that defines events, handlers, and dependencies.

**Purpose:** Standardizes how serverless applications declare their event handlers and dependencies.

**Usage:**
```typescript
function validateManifest(manifest: Manifest): boolean {
  return Object.keys(manifest.events).length > 0;
}
```

### AllowedModule
Module whitelist configuration for security and dependency management.

**Purpose:** Controls which npm modules can be used in user applications for security and compatibility.

**Usage:**
```typescript
function checkModule(name: string, modules: AllowedModule[]): boolean {
  return modules.some(m => m.name === name);
}
```

## Command Options

### CreateOptions, RunOptions, PackageOptions
Type definitions for CLI command options and arguments.

**Purpose:** Provides type safety for command-line interface implementations and ensures consistent option handling.

**Usage:**
```typescript
import { CreateOptions } from '@chargebee/chargebee-apps-shared';

function createApp(dir: string, options: CreateOptions): void {
  const template = options.template || 'default';
  // Create application logic
}
```

## Constants

### LOG_LEVELS
Defines available logging levels for consistent logging configuration.

**Purpose:** Standardizes log level names across all logging implementations.

**Usage:**
```typescript
import { LOG_LEVELS } from '@chargebee/chargebee-apps-shared';

function setLogLevel(level: string): boolean {
  return Object.values(LOG_LEVELS).includes(level as any);
}
```

## Best Practices

1. **Use interfaces for dependency injection** - Pass interfaces to constructors instead of concrete implementations
2. **Implement all required methods** - TypeScript enforces interface compliance
3. **Handle errors gracefully** - Don't let interface implementations throw unexpected errors
4. **Validate at boundaries** - Check types when data enters your system
5. **Use type guards** - Validate runtime types match compile-time expectations