@chargebee/chargebee-apps-libs 0.0.2

package/LICENSE

@@ -0,0 +1,24 @@
+The MIT License
+
+Copyright (c) 2011-2024 Chargebee, Inc.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+# @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`](templates/serverless-node-starter-app-with-iparams/README.md) for the full iparams schema and examples.
+
+## Usage Examples
+
+### Complete Development Workflow
+
+```typescript
+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
+
+```typescript
+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
+
+```typescript
+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
+```bash
+npm run build
+```
+
+### Testing
+```bash
+npm run test
+npm run test:coverage
+```
+
+### Linting
+```bash
+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/`](src/config/README.md) - Configuration management with caching and validation
+- [`src/logger/`](src/logger/README.md) - Winston-based logging with multiple transports
+- [`src/sandbox/`](src/sandbox/README.md) - VM-based secure code execution environment  
+- [`src/libs/`](src/libs/README.md) - Core utility services (port, template, file system, process)
+- `templates/` - Built-in application templates
+- [`ui/`](ui/README.md) - 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:
+1. Implement the corresponding interface from `@chargebee/chargebee-apps-shared`
+2. Add comprehensive unit tests with 85%+ coverage
+3. Include JSDoc documentation for all public methods
+4. Follow the existing error handling patterns
+5. Update this README with usage examples

package/SECURITY.md

@@ -0,0 +1,8 @@
+# Security Policy
+
+At Chargebee, we take data integrity and security very seriously. Due to the nature of the product and service we provide, we are committed to working with individuals to stay updated on the latest security techniques and fix any security weakness in our application or infrastructure reported to us responsibly by external parties.
+
+https://www.chargebee.com/security/responsible-disclosure-policy/
+
+## Reporting a vulnerability
+Reach out to us at security@chargebee.com. Please do not open GitHub issues or pull requests as this makes the problem immediately visible to everyone, including malicious actors. Chargebee's security team will triage your report and respond according to its impact.

package/config/README.md

@@ -0,0 +1,83 @@
+# Configuration
+
+This directory contains static configuration files for the Chargebee Apps CLI tool.
+
+## Files
+
+### `allowed-modules.json`
+
+Defines the list of Node.js modules that are allowed to be used in user applications. This configuration ensures security by restricting which modules can be imported in the sandbox environment.
+
+#### Structure
+
+```json
+{
+  "modules": [
+    {
+      "name": "module-name",
+      "version": "semver-range"
+    }
+  ]
+}
+```
+
+#### Fields
+
+- **name** (required): The npm package name
+- **version** (optional): A semver range that specifies allowed versions
+
+#### Example
+
+```json
+{
+  "modules": [
+    {
+      "name": "lodash",
+      "version": "^4.17.0",
+      "description": "Utility library for common JavaScript operations"
+    },
+    {
+      "name": "axios",
+      "version": "^1.0.0",
+      "description": "HTTP client for making API requests"
+    },
+    {
+      "name": "uuid",
+      "version": "^9.0.0 || ^10.0.0",
+      "description": "Generate RFC-compliant UUIDs"
+    }
+  ]
+}
+```
+
+#### Semver Version Examples
+
+The `version` field supports various semver patterns:
+
+- **All versions**: `*` (allows any version)
+- **Exact version**: `4.17.21` (only this specific version)
+- **Caret range**: `^4.17.0` (allows 4.17.x but not 5.0.0)
+- **Tilde range**: `~4.17.0` (allows 4.17.x but not 4.18.0)
+- **Range**: `>=4.17.0 <5.0.0` (custom range)
+- **Multiple ranges**: `^9.0.0 || ^10.0.0` (allows either 9.x.x or 10.x.x)
+
+## Usage
+
+The configuration is loaded by the `ConfigLoader` class in `src/libs/config-loader.ts` and used by the sandbox environment to validate user dependencies.
+
+## Notes
+
+- This is static configuration that doesn't change during runtime
+- Located in the root directory for easy access and modification
+- Used by the sandbox to enforce security restrictions
+
+## Future Plans
+
+**⚠️ Temporary Implementation**: This static JSON configuration is a temporary solution. In the future, the allowed modules configuration will be moved to a dynamic API that will be served by Chargebee. This will allow for:
+
+- **Dynamic updates**: Module allowlist can be updated without CLI releases
+- **Centralized management**: All configurations managed by Chargebee
+- **Real-time changes**: Immediate updates to security policies
+- **Better scalability**: Support for more complex module management
+
+The current static JSON approach is maintained for development and testing purposes until the API integration is complete. 

package/config/allowed-modules.json

@@ -0,0 +1,24 @@
+{
+    "modules": [
+        {
+            "name": "lodash",
+            "version": "^4.17.0",
+            "description": "Utility library for common JavaScript operations"
+        },
+        {
+            "name": "axios",
+            "version": "^1.0.0",
+            "description": "HTTP client for making API requests"
+        },
+        {
+            "name": "uuid",
+            "version": "^9.0.0 || ^10.0.0",
+            "description": "Generate RFC-compliant UUIDs"
+        },
+        {
+            "name": "chargebee",
+            "version": "^3.0.0",
+            "description": "Chargebee SDK for Node.js"
+        }
+    ]
+} 

package/dist/config/config-loader.d.ts

@@ -0,0 +1,24 @@
+import { AllowedModule, CBFileSystem } from '@chargebee/chargebee-apps-shared';
+/**
+ * ConfigLoader provides utilities for loading and managing configuration files
+ * Public implementation for loading allowed modules configuration
+ */
+export declare class ConfigLoader {
+    private cache;
+    private fileSystem;
+    constructor(fileSystem: CBFileSystem);
+    /**
+     * Loads and validates the allowed modules configuration
+     * @returns {AllowedModule[]} Array of validated allowed modules
+     * @throws {Error} If configuration is invalid or cannot be loaded
+     */
+    loadAllowedModules(): AllowedModule[];
+    /**
+     * Loads a JSON configuration file with caching
+     * @param {string} configPath - Path to the configuration file
+     * @param {boolean} useCache - Whether to use cached version if available
+     * @returns {any} Parsed configuration object
+     * @throws {Error} If file cannot be loaded or parsed
+     */
+    loadConfig(configPath: string, useCache?: boolean): any;
+}

package/dist/config/config-loader.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigLoader = void 0;
+const chargebee_apps_shared_1 = require("@chargebee/chargebee-apps-shared");
+const path_1 = __importDefault(require("path"));
+const semver_1 = __importDefault(require("semver"));
+/**
+ * ConfigLoader provides utilities for loading and managing configuration files
+ * Public implementation for loading allowed modules configuration
+ */
+class ConfigLoader {
+    constructor(fileSystem) {
+        this.fileSystem = fileSystem;
+        this.cache = new Map();
+    }
+    /**
+     * Loads and validates the allowed modules configuration
+     * @returns {AllowedModule[]} Array of validated allowed modules
+     * @throws {Error} If configuration is invalid or cannot be loaded
+     */
+    loadAllowedModules() {
+        try {
+            // Get config file path
+            let configPath;
+            try {
+                // Production: Find @chargebee/chargebee-apps-libs package and get config from package root
+                const packageJsonPath = require.resolve('@chargebee/chargebee-apps-libs');
+                const packageRoot = path_1.default.dirname(path_1.default.dirname(packageJsonPath));
+                configPath = path_1.default.join(packageRoot, 'config', 'allowed-modules.json');
+            }
+            catch (error) {
+                chargebee_apps_shared_1.__logger.error('Error: Failed to find allowed modules in the published package', error);
+                // Development: Use relative path
+                configPath = path_1.default.join(__dirname, '../../config/allowed-modules.json');
+            }
+            const config = this.loadConfig(configPath);
+            if (!config.modules || !Array.isArray(config.modules)) {
+                throw new Error('Invalid allowed modules format: "modules" must be an array');
+            }
+            const validatedModules = config.modules.map((module, index) => {
+                if (!module.name || typeof module.name !== 'string') {
+                    throw new Error(`Invalid module at index ${index}: "name" must be a string`);
+                }
+                if (module.version && typeof module.version !== 'string') {
+                    throw new Error(`Invalid module "${module.name}": "version" must be a string`);
+                }
+                if (module.version && !semver_1.default.validRange(module.version)) {
+                    throw new Error(`Invalid semver range "${module.version}" for module "${module.name}"`);
+                }
+                return module;
+            });
+            chargebee_apps_shared_1.__logger.debug(`Loaded ${validatedModules.length} allowed modules from configuration`);
+            return validatedModules;
+        }
+        catch (error) {
+            const err = error;
+            chargebee_apps_shared_1.__logger.error('Failed to load allowed-modules.json:', err.message);
+            throw err;
+        }
+    }
+    /**
+     * Loads a JSON configuration file with caching
+     * @param {string} configPath - Path to the configuration file
+     * @param {boolean} useCache - Whether to use cached version if available
+     * @returns {any} Parsed configuration object
+     * @throws {Error} If file cannot be loaded or parsed
+     */
+    loadConfig(configPath, useCache = true) {
+        const absolutePath = path_1.default.resolve(configPath);
+        // Check cache first
+        if (useCache && this.cache.has(absolutePath)) {
+            return this.cache.get(absolutePath);
+        }
+        try {
+            if (!this.fileSystem.existsSync(absolutePath)) {
+                throw new Error(`Configuration file not found: ${absolutePath}`);
+            }
+            const configContent = this.fileSystem.readFileSync(absolutePath, 'utf8');
+            const config = JSON.parse(configContent);
+            // Cache the result
+            if (useCache) {
+                this.cache.set(absolutePath, config);
+            }
+            return config;
+        }
+        catch (error) {
+            const err = error;
+            throw new Error(`Failed to load configuration from ${absolutePath}: ${err.message}`);
+        }
+    }
+}
+exports.ConfigLoader = ConfigLoader;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './config/config-loader';
+export * from './libs/port-service';
+export * from './logger/cb-public-logger';
+export * from './sandbox/public-sandbox-wrapper';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Export all public library implementations
+__exportStar(require("./config/config-loader"), exports);
+__exportStar(require("./libs/port-service"), exports);
+__exportStar(require("./logger/cb-public-logger"), exports);
+__exportStar(require("./sandbox/public-sandbox-wrapper"), exports);

package/dist/libs/port-service.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Port parsing service
+ */
+export declare class PortService {
+    constructor();
+    /**
+     * Validates port number
+     * @param {string} port - Port string input
+     * @returns {boolean} True if port is valid
+     */
+    isValidPort(port: string): boolean;
+    /**
+     * Parses port number from string input
+     * @param {string} port - Port string input
+     * @returns {number} Parsed port number or default
+     */
+    parsePort(port: string): number;
+}

package/dist/libs/port-service.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PortService = void 0;
+/**
+ * Port parsing service
+ */
+class PortService {
+    constructor() { }
+    /**
+     * Validates port number
+     * @param {string} port - Port string input
+     * @returns {boolean} True if port is valid
+     */
+    isValidPort(port) {
+        const parsedPort = parseInt(port);
+        return !isNaN(parsedPort);
+    }
+    /**
+     * Parses port number from string input
+     * @param {string} port - Port string input
+     * @returns {number} Parsed port number or default
+     */
+    parsePort(port) {
+        return parseInt(port);
+    }
+}
+exports.PortService = PortService;

package/dist/logger/cb-public-logger.d.ts

@@ -0,0 +1,59 @@
+import { CBFileSystem, CBProcess, ICBLogger, SafeConsole } from '@chargebee/chargebee-apps-shared';
+import winston from 'winston';
+/**
+ * Public logger implementation for local development
+ * This logger provides controlled logging capabilities for sandboxed code execution
+ * with correlation context and formatted output using Winston
+ */
+export declare class CBPublicLogger implements ICBLogger {
+    private logger;
+    private userCodeDir;
+    private fileSystem;
+    private process;
+    constructor(fileSystem: CBFileSystem, process: CBProcess, userCodeDir: string);
+    /**
+     * Creates a Winston logger with console and file transports
+     * @returns {winston.Logger} Configured Winston logger instance
+     */
+    protected createWinstonLogger(): winston.Logger;
+    /**
+     * Logs an info message
+     * @param {...any[]} args - The message arguments to log
+     */
+    info(...args: any[]): void;
+    /**
+     * Logs a warning message
+     * @param {...any[]} args - The message arguments to log
+     */
+    warn(...args: any[]): void;
+    /**
+     * Logs an error message
+     * @param {...any[]} args - The message arguments to log
+     */
+    error(...args: any[]): void;
+    /**
+     * Logs a debug message
+     * @param {...any[]} args - The message arguments to log
+     */
+    debug(...args: any[]): void;
+    /**
+     * Formats a message with timestamp and level
+     * @param {winston.Logform.TransformableInfo} info - The log info
+     * @returns {string} The formatted message
+     */
+    formatMessage(info: winston.Logform.TransformableInfo): string;
+}
+/**
+ * Creates a safe console object that uses the logger
+ * @param {ICBLogger} logger - The logger instance to use
+ * @returns {SafeConsole} A safe console object
+ */
+export declare function createSafeConsole(logger: ICBLogger): SafeConsole;
+/**
+ * Creates a new CBPublicLogger instance for a specific user code directory
+ * @param {CBFileSystem} fileSystem - The filesystem implementation to use
+ * @param {CBProcess} process - The process implementation to use
+ * @param {string} userCodeDir - The user code directory where logs should be stored
+ * @returns {CBPublicLogger} A new CBPublicLogger instance
+ */
+export declare function createCBPublicLogger(fileSystem: CBFileSystem, process: CBProcess, userCodeDir: string): CBPublicLogger;