@chargebee/chargebee-apps-shared 0.0.2

package/dist/validator/manifest-validator.d.ts

@@ -0,0 +1,48 @@
+import { CBFileSystem } from '../node/file-system';
+import { AllowedModule, Manifest } from '../types/common';
+/**
+ * ManifestValidator provides validation for Chargebee Apps application manifests
+ * Public implementation for validating user applications
+ */
+export declare class ManifestValidator {
+    private allowedModules;
+    private fileSystem;
+    constructor(allowedModulesConfig: AllowedModule[], fileSystem: CBFileSystem);
+    /**
+     * Validates a manifest file from disk
+     * @param {string} path - Path to the manifest.json file
+     * @returns {Object} The validated manifest
+     * @throws {Error} If manifest file is invalid or cannot be read
+     */
+    validateAndGetManifestFile(path: string): Manifest;
+    /**
+     * Validates a complete manifest object
+     * @param {Manifest} manifest - The manifest object to validate
+     * @returns {Manifest} The validated manifest
+     * @throws {Error} If manifest is invalid
+     */
+    protected validate(manifest: Manifest): void;
+    /**
+     * Validates the basic structure of the manifest
+     * @param {Object} manifest - The manifest object
+     * @throws {Error} If basic structure is invalid
+     */
+    protected validateBasicStructure(manifest: Manifest): void;
+    /**
+     * Validates the events configuration
+     * @param {Object} manifest - The manifest object
+     * @throws {Error} If events configuration is invalid
+     */
+    protected validateEvents(manifest: Manifest): void;
+    /**
+     * Validates the dependencies configuration
+     * @param {Object} manifest - The manifest object
+     * @throws {Error} If dependencies are invalid
+     */
+    protected validateDependencies(manifest: Manifest): void;
+    /**
+     * Validates the metadata fields
+     * @param {Object} manifest - The manifest object
+     */
+    protected validateMetadata(manifest: Manifest): void;
+}

package/dist/validator/manifest-validator.js

@@ -0,0 +1,138 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ManifestValidator = void 0;
+const semver_1 = __importDefault(require("semver"));
+const internal_logger_1 = require("../logger/internal-logger");
+/**
+ * ManifestValidator provides validation for Chargebee Apps application manifests
+ * Public implementation for validating user applications
+ */
+class ManifestValidator {
+    constructor(allowedModulesConfig, fileSystem) {
+        this.allowedModules = allowedModulesConfig || [];
+        this.fileSystem = fileSystem;
+    }
+    /**
+     * Validates a manifest file from disk
+     * @param {string} path - Path to the manifest.json file
+     * @returns {Object} The validated manifest
+     * @throws {Error} If manifest file is invalid or cannot be read
+     */
+    validateAndGetManifestFile(path) {
+        if (!this.fileSystem.existsSync(path)) {
+            throw new Error(`manifest.json not found in user code directory`);
+        }
+        try {
+            const manifestContent = this.fileSystem.readFileSync(path, 'utf8');
+            const manifest = JSON.parse(manifestContent);
+            this.validate(manifest);
+            return manifest;
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new Error(`Failed to parse manifest file: ${error.message}`);
+            }
+            const err = error;
+            throw new Error(`Failed to read manifest file: ${err.message}`);
+        }
+    }
+    /**
+     * Validates a complete manifest object
+     * @param {Manifest} manifest - The manifest object to validate
+     * @returns {Manifest} The validated manifest
+     * @throws {Error} If manifest is invalid
+     */
+    validate(manifest) {
+        // Basic structure validation
+        this.validateBasicStructure(manifest);
+        // Events validation
+        this.validateEvents(manifest);
+        // Dependencies validation
+        this.validateDependencies(manifest);
+        // Metadata validation
+        this.validateMetadata(manifest);
+    }
+    /**
+     * Validates the basic structure of the manifest
+     * @param {Object} manifest - The manifest object
+     * @throws {Error} If basic structure is invalid
+     */
+    validateBasicStructure(manifest) {
+        if (!manifest || typeof manifest !== 'object') {
+            throw new Error('Manifest must be a valid object');
+        }
+        if (manifest.events && typeof manifest.events !== 'object') {
+            throw new Error('Events mapping must be an object');
+        }
+        if (manifest.dependencies && typeof manifest.dependencies !== 'object') {
+            throw new Error('Dependencies must be an object');
+        }
+    }
+    /**
+     * Validates the events configuration
+     * @param {Object} manifest - The manifest object
+     * @throws {Error} If events configuration is invalid
+     */
+    validateEvents(manifest) {
+        if (!manifest.events) {
+            throw new Error('Invalid manifest: missing "events" mapping');
+        }
+        for (const [eventType, handler] of Object.entries(manifest.events)) {
+            if (!handler || typeof handler !== 'object') {
+                throw new Error(`Handler name for event "${eventType}" must be a non-empty string`);
+            }
+        }
+    }
+    /**
+     * Validates the dependencies configuration
+     * @param {Object} manifest - The manifest object
+     * @throws {Error} If dependencies are invalid
+     */
+    validateDependencies(manifest) {
+        if (!manifest.dependencies) {
+            return; // Dependencies are optional
+        }
+        if (typeof manifest.dependencies !== 'object') {
+            throw new Error('Invalid manifest: "dependencies" must be an object');
+        }
+        for (const [depName, depVersion] of Object.entries(manifest.dependencies)) {
+            if (typeof depName !== 'string' || typeof depVersion !== 'string') {
+                throw new Error(`Invalid dependency in manifest: "${depName}" must have string name and version`);
+            }
+            // Check if module is allowed
+            const allowedModule = this.allowedModules.find(module => module.name === depName);
+            if (!allowedModule) {
+                throw new Error(`Dependency "${depName}" is not allowed in this environment`);
+            }
+            // Validate version range
+            if (!semver_1.default.validRange(depVersion)) {
+                throw new Error(`Invalid version range "${depVersion}" for dependency "${depName}"`);
+            }
+            // Check version constraints if specified
+            if (allowedModule.version) {
+                if (!semver_1.default.satisfies(depVersion, allowedModule.version)) {
+                    internal_logger_1.__logger.warn(`Dependency "${depName}" version range "${depVersion}" differs from allowed version constraint "${allowedModule.version}" - proceeding with warning`);
+                }
+            }
+            else {
+                throw new Error(`Configuration error: Allowed module "${depName}" does not have a version constraint`);
+            }
+            internal_logger_1.__logger.debug(`Dependency "${depName}" version "${depVersion}" is allowed`);
+        }
+        internal_logger_1.__logger.debug(`Validated ${Object.keys(manifest.dependencies).length} dependencies in manifest`);
+    }
+    /**
+     * Validates the metadata fields
+     * @param {Object} manifest - The manifest object
+     */
+    validateMetadata(manifest) {
+        // Check for reasonable limits
+        if (manifest.dependencies && Object.keys(manifest.dependencies).length > 10) {
+            internal_logger_1.__logger.warn('Large number of dependencies detected - consider minimizing dependencies for better performance');
+        }
+    }
+}
+exports.ManifestValidator = ManifestValidator;

package/dist/validator/package-validator.d.ts

@@ -0,0 +1,27 @@
+import { CBFileSystem } from "../node/file-system";
+/**
+ * Package validator for validating app structure.
+ * This primarily validates the app directory and the structure of the app which developer bundles and uploads to Chargebee.
+ */
+export declare class PackageValidator {
+    private fileSystem;
+    constructor(fileSystem: CBFileSystem);
+    /**
+     * Validates that the app directory exists
+     * @param {string} targetDir - Target directory path
+     * @returns {boolean} True if directory exists
+     */
+    validateAppDirectoryExists(targetDir: string): boolean;
+    /**
+     * Validates that manifest.json exists in the app directory
+     * @param {string} targetDir - Target directory path
+     * @returns {boolean} True if manifest.json exists
+     */
+    validateManifestExists(targetDir: string): boolean;
+    /**
+     * Validates that handler.js exists in the app directory
+     * @param {string} targetDir - Target directory path
+     * @returns {boolean} True if handler.js exists
+     */
+    validateHandlerExists(targetDir: string): boolean;
+}

package/dist/validator/package-validator.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageValidator = void 0;
+const path_1 = __importDefault(require("path"));
+/**
+ * Package validator for validating app structure.
+ * This primarily validates the app directory and the structure of the app which developer bundles and uploads to Chargebee.
+ */
+class PackageValidator {
+    constructor(fileSystem) {
+        this.fileSystem = fileSystem;
+    }
+    /**
+     * Validates that the app directory exists
+     * @param {string} targetDir - Target directory path
+     * @returns {boolean} True if directory exists
+     */
+    validateAppDirectoryExists(targetDir) {
+        return this.fileSystem.existsSync(targetDir);
+    }
+    /**
+     * Validates that manifest.json exists in the app directory
+     * @param {string} targetDir - Target directory path
+     * @returns {boolean} True if manifest.json exists
+     */
+    validateManifestExists(targetDir) {
+        const manifestPath = path_1.default.join(targetDir, 'manifest.json');
+        return this.fileSystem.existsSync(manifestPath);
+    }
+    /**
+     * Validates that handler.js exists in the app directory
+     * @param {string} targetDir - Target directory path
+     * @returns {boolean} True if handler.js exists
+     */
+    validateHandlerExists(targetDir) {
+        const handlerPath = path_1.default.join(targetDir, 'handler', 'handler.js');
+        return this.fileSystem.existsSync(handlerPath);
+    }
+}
+exports.PackageValidator = PackageValidator;

package/dist/validator/validator-utils.d.ts

@@ -0,0 +1,13 @@
+import { CBFileSystem } from '../node/file-system';
+/**
+ * True only when `value` is a string and is not empty or whitespace-only after trim.
+ * Logically the opposite of `(typeof value !== 'string' || value.trim() === '')`.
+ * @param {unknown} value - Value to check
+ * @returns {value is string} Whether `value` is a usable non-empty string
+ */
+export declare function isNonEmptyString(value: unknown): value is string;
+/**
+ * Throws if `filePath` does not exist on the given filesystem.
+ * Message uses the file basename, e.g. `iparams.json not found`.
+ */
+export declare function ensureFileExists(fileSystem: CBFileSystem, filePath: string): void;

package/dist/validator/validator-utils.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNonEmptyString = isNonEmptyString;
+exports.ensureFileExists = ensureFileExists;
+const path_1 = __importDefault(require("path"));
+/**
+ * True only when `value` is a string and is not empty or whitespace-only after trim.
+ * Logically the opposite of `(typeof value !== 'string' || value.trim() === '')`.
+ * @param {unknown} value - Value to check
+ * @returns {value is string} Whether `value` is a usable non-empty string
+ */
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+/**
+ * Throws if `filePath` does not exist on the given filesystem.
+ * Message uses the file basename, e.g. `iparams.json not found`.
+ */
+function ensureFileExists(fileSystem, filePath) {
+    if (!fileSystem.existsSync(filePath)) {
+        throw new Error(`${path_1.default.basename(filePath)} not found`);
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@chargebee/chargebee-apps-shared",
+  "version": "0.0.2",
+  "description": "Shared interfaces and utilities for Chargebee Apps CLI",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist && rm -rf coverage",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "test:unit": "jest --testPathPattern=tests/unit",
+    "minify": "esbuild 'dist/**/*.js' --minify --platform=node --outdir=dist --allow-overwrite"
+  },
+  "dependencies": {
+    "yauzl": "^2.10.0",
+    "winston": "^3.11.0",
+    "semver": "^7.7.2",
+    "archiver": "^7.0.1"
+  },
+  "devDependencies": {
+    "@types/archiver": "^6.0.3",
+    "@types/jest": "^29.5.0",
+    "@types/node": "^24.3.0",
+    "@types/yauzl": "^2.10.0",
+    "@types/winston": "^2.4.4",
+    "esbuild": "^0.28.1",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}