@chargebee/chargebee-apps-shared 0.0.1

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,73 @@
+# @chargebee/chargebee-apps-shared
+
+Shared interfaces, types, and utilities for the Chargebee Apps CLI ecosystem.
+
+## Installation
+
+```bash
+npm install @chargebee/chargebee-apps-shared
+```
+
+This package is typically installed as a dependency of [`@chargebee/chargebee-apps`](https://www.npmjs.com/package/@chargebee/chargebee-apps) or [`@chargebee/chargebee-apps-libs`](https://www.npmjs.com/package/@chargebee/chargebee-apps-libs).
+
+## Overview
+
+Provides the common building blocks used across Chargebee Apps packages:
+
+- **Configuration** — environment detection and path resolution
+- **Dependency management** — isolated npm installs and secure module loading
+- **Validation** — manifest, package, and iparams validation
+- **File and archive services** — packaging and file operations
+- **Logging** — standardized logging interfaces
+- **Sandbox** — secure code execution contracts
+- **Types** — shared event, manifest, and handler types
+
+## Usage
+
+```typescript
+import {
+	DependencyManager,
+	ManifestValidator,
+	PathResolver,
+	EnvironmentConfig,
+	CBFileSystem,
+	CBProcess,
+} from '@chargebee/chargebee-apps-shared';
+
+const envConfig = new EnvironmentConfig();
+const pathResolver = new PathResolver();
+
+const fileSystem = new CBFileSystem();
+const dependencyManager = new DependencyManager(fileSystem);
+
+const allowedModules = [{ name: 'lodash', version: '^4.17.21' }];
+const validator = new ManifestValidator(allowedModules);
+const manifest = validator.validateFile('./my-app/manifest.json');
+
+await dependencyManager.ensureDependencies('./my-app', manifest);
+```
+
+## Main exports
+
+| Export | Purpose |
+|--------|---------|
+| `EnvironmentConfig` | Detect development vs production runtime |
+| `PathResolver` | Resolve CLI and package paths |
+| `DependencyManager` | Install and load app dependencies safely |
+| `ManifestValidator` | Validate `manifest.json` |
+| `PackageValidator` | Validate app package structure |
+| `ArchiveService` | Create and extract zip packages |
+| `TemplateService` | Copy app templates |
+| `FileManagementService` | Collect files for packaging |
+| `IparamsService` | Load and validate iparams |
+| `CBFileSystem` / `CBProcess` | File and process abstractions |
+| `sandboxContext` | Correlate sandbox execution context |
+
+## Related packages
+
+- [`@chargebee/chargebee-apps`](https://www.npmjs.com/package/@chargebee/chargebee-apps) — CLI for creating, running, and packaging apps
+- [`@chargebee/chargebee-apps-libs`](https://www.npmjs.com/package/@chargebee/chargebee-apps-libs) — library implementations and templates
+
+## License
+
+MIT

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;
+}