@chargebee/chargebee-apps-shared 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,113 @@
+# @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

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/dist/config/environment.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Environment type enum
+ */
+export declare enum EnvironmentType {
+    DEVELOPMENT = "development",
+    PRODUCTION = "production"
+}
+/**
+ * Environment configuration interface
+ */
+export interface IEnvironmentConfig {
+    /**
+     * Get the current environment type
+     * @returns {EnvironmentType} The current environment
+     */
+    getEnvironment(): EnvironmentType;
+    /**
+     * Check if running in development mode
+     * @returns {boolean} True if in development mode
+     */
+    isDevelopment(): boolean;
+    /**
+     * Check if running in production mode
+     * @returns {boolean} True if in production mode
+     */
+    isProduction(): boolean;
+}
+/**
+ * Environment configuration class that detects the current environment
+ * @class EnvironmentConfig
+ * @implements {IEnvironmentConfig}
+ *
+ * @description
+ * This class provides environment detection based on multiple indicators:
+ * 1. NODE_ENV environment variable
+ * 2. Presence of workspace structure (workspaces field in package.json)
+ * 3. Module resolution capability (can resolve published packages)
+ *
+ * @example
+ * ```typescript
+ * const envConfig = new EnvironmentConfig();
+ * if (envConfig.isDevelopment()) {
+ *   console.log('Running in development mode');
+ * }
+ * ```
+ */
+export declare class EnvironmentConfig implements IEnvironmentConfig {
+    private environment;
+    constructor();
+    /**
+     * Detects the current environment based on various indicators
+     * @returns {EnvironmentType} The detected environment type
+     * @private
+     */
+    private detectEnvironment;
+    /**
+     * Finds the project root by traversing up the directory tree
+     * @param {string} startDir - Directory to start searching from
+     * @returns {string | null} Path to project root or null if not found
+     * @private
+     */
+    private findProjectRoot;
+    /**
+     * Gets the current environment type
+     * @returns {EnvironmentType} The current environment
+     */
+    getEnvironment(): EnvironmentType;
+    /**
+     * Checks if running in development mode
+     * @returns {boolean} True if in development mode
+     */
+    isDevelopment(): boolean;
+    /**
+     * Checks if running in production mode
+     * @returns {boolean} True if in production mode
+     */
+    isProduction(): boolean;
+}

package/dist/config/environment.js

@@ -0,0 +1,150 @@
+"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 __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvironmentConfig = exports.EnvironmentType = void 0;
+const path_1 = __importDefault(require("path"));
+const fs = __importStar(require("fs"));
+/**
+ * Environment type enum
+ */
+var EnvironmentType;
+(function (EnvironmentType) {
+    EnvironmentType["DEVELOPMENT"] = "development";
+    EnvironmentType["PRODUCTION"] = "production";
+})(EnvironmentType || (exports.EnvironmentType = EnvironmentType = {}));
+/**
+ * Environment configuration class that detects the current environment
+ * @class EnvironmentConfig
+ * @implements {IEnvironmentConfig}
+ *
+ * @description
+ * This class provides environment detection based on multiple indicators:
+ * 1. NODE_ENV environment variable
+ * 2. Presence of workspace structure (workspaces field in package.json)
+ * 3. Module resolution capability (can resolve published packages)
+ *
+ * @example
+ * ```typescript
+ * const envConfig = new EnvironmentConfig();
+ * if (envConfig.isDevelopment()) {
+ *   console.log('Running in development mode');
+ * }
+ * ```
+ */
+class EnvironmentConfig {
+    constructor() {
+        this.environment = this.detectEnvironment();
+    }
+    /**
+     * Detects the current environment based on various indicators
+     * @returns {EnvironmentType} The detected environment type
+     * @private
+     */
+    detectEnvironment() {
+        // Check NODE_ENV first
+        const nodeEnv = process.env['NODE_ENV']?.toLowerCase();
+        if (nodeEnv === 'production') {
+            return EnvironmentType.PRODUCTION;
+        }
+        if (nodeEnv === 'development') {
+            return EnvironmentType.DEVELOPMENT;
+        }
+        // If NODE_ENV is not set, detect based on workspace structure
+        // In development, we should be in a monorepo with workspaces
+        // In production, packages are published and installed independently
+        try {
+            const currentDir = __dirname;
+            const projectRoot = this.findProjectRoot(currentDir);
+            if (projectRoot) {
+                const packageJsonPath = path_1.default.join(projectRoot, 'package.json');
+                if (fs.existsSync(packageJsonPath)) {
+                    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+                    // If workspaces field exists, we're in development
+                    if (packageJson.workspaces) {
+                        return EnvironmentType.DEVELOPMENT;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            // If we can't find workspace structure, assume production
+        }
+        // Default to production if we can't determine
+        return EnvironmentType.PRODUCTION;
+    }
+    /**
+     * Finds the project root by traversing up the directory tree
+     * @param {string} startDir - Directory to start searching from
+     * @returns {string | null} Path to project root or null if not found
+     * @private
+     */
+    findProjectRoot(startDir) {
+        let currentDir = startDir;
+        const root = path_1.default.parse(currentDir).root;
+        while (currentDir !== root) {
+            const packageJsonPath = path_1.default.join(currentDir, 'package.json');
+            if (fs.existsSync(packageJsonPath)) {
+                return currentDir;
+            }
+            currentDir = path_1.default.dirname(currentDir);
+        }
+        return null;
+    }
+    /**
+     * Gets the current environment type
+     * @returns {EnvironmentType} The current environment
+     */
+    getEnvironment() {
+        return this.environment;
+    }
+    /**
+     * Checks if running in development mode
+     * @returns {boolean} True if in development mode
+     */
+    isDevelopment() {
+        return this.environment === EnvironmentType.DEVELOPMENT;
+    }
+    /**
+     * Checks if running in production mode
+     * @returns {boolean} True if in production mode
+     */
+    isProduction() {
+        return this.environment === EnvironmentType.PRODUCTION;
+    }
+}
+exports.EnvironmentConfig = EnvironmentConfig;

package/dist/config/path-resolver.d.ts

@@ -0,0 +1,117 @@
+import { IEnvironmentConfig } from './environment';
+/**
+ * Path type enum for different package paths
+ */
+export declare enum PathType {
+    /** Root directory of the CLI workspace */
+    CLI_ROOT = "CLI_ROOT",
+    /** Private application distribution directory */
+    PRIVATE_APP_DIST = "PRIVATE_APP_DIST",
+    /** Private application root directory */
+    PRIVATE_APP_ROOT = "PRIVATE_APP_ROOT",
+    /** Public libs templates directory */
+    PUBLIC_LIBS_TEMPLATES = "PUBLIC_LIBS_TEMPLATES",
+    /** Public libs UI web directory */
+    PUBLIC_LIBS_UI_WEB = "PUBLIC_LIBS_UI_WEB"
+}
+/**
+ * Path resolver interface
+ */
+export interface IPathResolver {
+    /**
+     * Resolves a path based on the current environment
+     * @param {PathType} pathType - Type of path to resolve
+     * @returns {string} Resolved path
+     */
+    resolvePath(pathType: PathType): string;
+    /**
+     * Gets the CLI workspace root path
+     * @returns {string} Path to CLI workspace root
+     */
+    getCliRoot(): string;
+    /**
+     * Gets the private application distribution directory path
+     * @returns {string} Path to private application dist directory
+     */
+    getPrivateAppDistDir(): string;
+    /**
+     * Gets the private application root directory path
+     * @returns {string} Path to private application root directory
+     */
+    getPrivateAppRootDir(): string;
+    /**
+     * Gets the public libs templates directory path
+     * @returns {string} Path to public libs templates directory
+     */
+    getPublicLibsTemplatesDir(): string;
+    /**
+     * Gets the public libs UI web directory path
+     * @returns {string} Path to public libs UI web directory
+     */
+    getPublicLibsUiWebDir(): string;
+}
+/**
+ * Path resolver class for resolving paths based on environment
+ * @class PathResolver
+ * @implements {IPathResolver}
+ *
+ * @description
+ * This class provides centralized path resolution for all packages in the CLI.
+ * It detects the environment (development vs production) and resolves paths accordingly:
+ * - In development: Uses workspace-relative paths
+ * - In production: Uses require.resolve to find installed packages
+ *
+ * This eliminates the need for try-catch error handling scattered across the codebase.
+ *
+ * @example
+ * ```typescript
+ * const pathResolver = new PathResolver();
+ * const templatesDir = pathResolver.getPublicLibsTemplatesDir();
+ * console.log(`Templates directory: ${templatesDir}`);
+ * ```
+ */
+export declare class PathResolver implements IPathResolver {
+    private envConfig;
+    private cliRoot;
+    constructor(envConfig?: IEnvironmentConfig);
+    /**
+     * Resolves a path based on the path type and environment
+     * @param {PathType} pathType - Type of path to resolve
+     * @returns {string} Resolved path
+     * @throws {Error} If path cannot be resolved
+     */
+    resolvePath(pathType: PathType): string;
+    /**
+     * Gets the CLI workspace root path
+     * @returns {string} Path to CLI workspace root
+     */
+    getCliRoot(): string;
+    /**
+     * Gets the private application distribution directory path
+     * @returns {string} Path to private application dist directory
+     */
+    getPrivateAppDistDir(): string;
+    /**
+     * Gets the private application root directory path
+     * @returns {string} Path to private application root directory
+     */
+    getPrivateAppRootDir(): string;
+    /**
+     * Gets the public libs templates directory path
+     * @returns {string} Path to public libs templates directory
+     */
+    getPublicLibsTemplatesDir(): string;
+    /**
+     * Gets the public libs UI web directory path
+     * @returns {string} Path to public libs UI web directory
+     */
+    getPublicLibsUiWebDir(): string;
+    /**
+     * Finds the project root by looking for package.json with workspaces
+     * @param {string} startDir - Directory to start searching from
+     * @returns {string} Path to project root
+     * @throws {Error} If project root cannot be found
+     * @private
+     */
+    private findProjectRootWithWorkspaces;
+}