@chargebee/chargebee-apps 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,472 @@
+# @chargebee/chargebee-apps
+
+The official CLI tool for creating, testing, and packaging serverless applications for Chargebee Apps.
+
+**CLI Command Name**: `chargebee-apps`
+
+## Overview
+
+The Chargebee Apps CLI is a comprehensive command-line tool that enables developers to build, test, and package serverless applications for Chargebee Apps platform. It provides a complete local development environment with web UI, secure sandbox execution, and automated packaging capabilities.
+
+## Installation
+
+### Global Installation (Recommended)
+```bash
+npm install -g @chargebee/chargebee-apps
+```
+
+### Local Installation
+```bash
+npm install @chargebee/chargebee-apps
+npx chargebee-apps --help
+```
+
+## Quick Start
+
+```bash
+# 1. Create a new serverless application
+chargebee-apps create my-app
+
+# 2. Run the application locally with web UI
+chargebee-apps run my-app
+
+# 3. Open http://localhost:15000 to test your handlers
+
+# 4. Package for deployment
+chargebee-apps package my-app
+```
+
+## Commands
+
+### `create <directory>`
+
+Creates a new serverless application from a template.
+
+```bash
+chargebee-apps create my-app
+chargebee-apps create my-app --template serverless-node-starter-app
+chargebee-apps create my-app --template serverless-node-starter-app-with-iparams
+```
+
+**Options:**
+- `--template <name>` - Template to use (default: `serverless-node-starter-app`)
+  - `serverless-node-starter-app` — basic event handlers
+  - `serverless-node-starter-app-with-iparams` — includes support for installation parameters
+
+**What it creates:**
+- `manifest.json` - Application configuration
+- `handler/handler.js` - Event handler implementations
+- `test_data/` - Sample event data for testing
+- `types/types.d.ts` - TypeScript definitions
+- `jsconfig.json` - JavaScript project configuration
+
+### `run <directory>`
+
+Starts a local development server for testing your application.
+
+```bash
+chargebee-apps run my-app
+chargebee-apps run my-app --port 3000
+```
+
+**Options:**
+- `-p, --port <port>` - Port to run the server on (default: `15000`)
+
+**Features:**
+- **Web UI**: Interactive testing interface at `http://localhost:15000`
+- **Iparams UI**: Edit sectioned parameter definitions and local values (when using the iparams template)
+- **API Endpoints**: RESTful API for programmatic testing
+- **Real-time Testing**: Execute handlers with custom event data
+- **Iparam validation**: Validates `iparams.json` on startup when present
+- **Error Handling**: Clear error messages and debugging info
+
+**Web UI Features:**
+- Event type selection from your manifest
+- JSON editor with syntax highlighting
+- Auto-loading of sample test data
+- Real-time execution results
+- Error reporting and debugging
+
+### `package <directory>`
+
+Creates a deployment-ready zip package of your application.
+
+```bash
+chargebee-apps package my-app
+chargebee-apps package my-app --name production-v1.0.0
+```
+
+**Options:**
+- `--name <name>` - Custom package name (without .zip extension)
+
+**Package Contents:**
+- `manifest.json` - Application configuration
+- `iparams.json` - Parameter definitions (when present)
+- `handler/` - All JavaScript and JSON files from handler directory
+- Excludes: development files, node_modules, test files, `iparams.local.json`
+
+**Output:**
+- Creates `dist/` directory in your app
+- Generates `{app-name}.zip` or custom named package
+- Displays package size and contents
+
+## Application Structure
+
+### Required Files
+
+#### `manifest.json`
+Defines your application configuration and event handlers.
+
+```json
+{
+  "events": {
+    "customer_created": {
+      "handler": "customerCreateHandler"
+    },
+    "subscription_created": {
+      "handler": "subscriptionCreatedHandler"
+    }
+  },
+  "dependencies": {
+    "lodash": "^4.17.21"
+  }
+}
+```
+
+#### `handler/handler.js`
+Contains your event handler implementations. Each handler receives a single `payload` object with `payload.event` (event data) and, when iparams are defined, `payload.iparams.<section>.<param>` (installation parameters).
+
+```javascript
+module.exports = {
+  customerCreateHandler: function(payload) {
+    console.log('Customer created:', payload.event.content.customer.email);
+    console.log('Processing fee (%):', payload.iparams.processing_fee_configuration.fee_percentage);
+    return {
+      status: 'success',
+      message: 'Customer processed successfully'
+    };
+  },
+
+  subscriptionCreatedHandler: function(payload) {
+    console.log('Subscription created:', payload.event.content.subscription.id);
+    console.log('Late payment fee (%):', payload.iparams.late_payment_fee_configuration.fee_percentage);
+    return {
+      status: 'success',
+      message: 'Subscription processed successfully'
+    };
+  }
+};
+```
+
+### Optional Files
+
+#### `test_data/`
+Sample event data files for testing (JSON format).
+
+```
+test_data/
+├── customer_created.json
+├── subscription_created.json
+└── invoice_generated.json
+```
+
+#### `types/types.d.ts`
+TypeScript definitions for better development experience.
+
+```typescript
+interface HandlerPayload {
+  event: EventRecord;
+  iparams?: Record<string, Record<string, string | number | boolean | string[]>>;
+}
+```
+
+#### `iparams.json` and `iparams.local.json` (optional)
+For apps that need user-configurable settings beyond the three system env vars. Parameters are grouped into **sections**:
+
+- **`iparams.json`** — schema under `installation_parameters.sections[]` (packaged for deployment)
+- **`iparams.local.json`** — local test values keyed by section name (not packaged)
+
+Handlers access values as `payload.iparams.<section_name>.<param_name>`. An empty `{}` in either file means no iparams are defined.
+
+See the [iparams template README](../public-libs/templates/serverless-node-starter-app-with-iparams/README.md#installation-parameters-iparams) for the full schema, validation rules, and examples.
+
+## API Reference
+
+When running the development server, these endpoints are available:
+
+### `GET /`
+Serves the web UI for interactive testing.
+
+### `GET /api/manifest`
+Returns application manifest and handler validation status.
+
+**Response:**
+```json
+{
+  "events": [
+    {
+      "event_type": "customer_created",
+      "handler": {
+        "name": "customerCreateHandler",
+        "exists": true
+      },
+      "has_test_data": true
+    }
+  ]
+}
+```
+
+### `GET /api/test-data/:eventType`
+Returns sample test data for the specified event type.
+
+### `POST /api/invoke`
+Executes a handler with provided event data.
+
+**Request:**
+```json
+{
+  "event_type": "customer_created",
+  "id": "evt_123",
+  "occurred_at": "2024-01-01T00:00:00Z",
+  "customer": {
+    "email": "test@example.com"
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "status": "success"
+}
+```
+
+### `GET /api/iparams`
+Returns the sectioned parameter definitions from `iparams.json`.
+
+### `POST /api/iparams`
+Saves validated parameter definitions to `iparams.json`.
+
+**Request body:** `{ "iparams": { "installation_parameters": { "sections": [...] } } }`
+
+### `GET /api/iparams/inputs`
+Returns parameter values from `iparams.local.json` (keyed by section).
+
+### `POST /api/iparams/inputs`
+Validates and saves parameter values to `iparams.local.json`.
+
+**Request body:** `{ "inputs": { "<section_name>": { "<param_name>": <value> } } }`
+
+## Development Workflow
+
+### 1. Project Creation
+```bash
+# Create new project
+chargebee-apps create my-serverless-app
+cd my-serverless-app
+
+# Examine the generated structure
+ls -la
+```
+
+### 2. Local Development
+```bash
+# Start development server
+chargebee-apps run . --port 3000
+
+# Open web UI in browser
+open http://localhost:3000
+```
+
+### 3. Testing
+- Use the web UI to test different event types
+- Modify handler code and refresh to see changes
+- Check console logs for handler output
+- Use custom JSON data for edge case testing
+
+### 4. Packaging
+```bash
+# Create deployment package
+chargebee-apps package . --name production-v1.0.0
+
+# Verify package contents
+unzip -l dist/production-v1.0.0.zip
+```
+
+## Advanced Usage
+
+### Custom Templates
+You can create custom templates by placing them in the templates directory:
+
+```
+templates/
+└── my-custom-template/
+    ├── manifest.json
+    ├── handler/
+    │   └── handler.js
+    └── README.md
+```
+
+### Environment Configuration
+The CLI respects these environment variables:
+
+- `MKPLC_CB_READ_ONLY_API` - Chargebee read-only API key for accessing Chargebee data without modifications
+- `MKPLC_CB_READ_WRITE_API` - Chargebee read-write API key for full access to modify Chargebee data
+- `MKPLC_SITE_DOMAIN` - Chargebee site domain (e.g., `your-site.chargebee.com`) that gets passed to the application handlers
+- `CB_LOG_LEVEL` - Controls logging verbosity (DEBUG, INFO, WARN, ERROR)
+- `NODE_ENV` - Affects development vs production behavior
+
+### Programmatic API Testing
+
+```bash
+# Test via curl
+curl -X POST http://localhost:15000/api/invoke \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event_type": "customer_created",
+    "customer": {"email": "test@example.com"}
+  }'
+```
+
+### Multiple Applications
+```bash
+# Run multiple apps on different ports
+chargebee-apps run app1 --port 3001
+chargebee-apps run app2 --port 3002
+chargebee-apps run app3 --port 3003
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Application directory does not exist"
+Make sure you're running commands from the correct directory or providing the correct path.
+
+#### "manifest.json not found"
+Ensure your application has a valid `manifest.json` file in the root directory.
+
+#### "handler.js not found"
+Make sure you have a `handler/handler.js` file with your event handler implementations.
+
+#### "Invalid port number"
+Port must be a valid number between 1 and 65535.
+
+#### "Port already in use"
+Choose a different port using the `--port` option.
+
+### Debug Mode
+```bash
+CB_LOG_LEVEL=DEBUG chargebee-apps run my-app
+```
+
+### Getting Help
+```bash
+chargebee-apps --help
+chargebee-apps create --help
+chargebee-apps run --help
+chargebee-apps package --help
+```
+
+## Package Structure
+
+- [`src/commands/`](src/commands/README.md) - CLI command implementations (create, run, package)
+- [`src/api/`](src/api/README.md) - Express server with web UI and API endpoints
+- `src/registry.ts` - Dependency injection registry
+- `tests/unit/` - Unit tests for CLI commands
+- `tests/integration/` - Integration tests for end-to-end workflows
+
+## Architecture
+
+### Dependencies
+The public CLI uses these core packages:
+- `@chargebee/chargebee-apps-shared` - Common interfaces and types
+- `@chargebee/chargebee-apps-libs` - Local development implementations
+
+### Security
+- **Sandboxed Execution**: User code runs in isolated VM contexts
+- **Module Whitelisting**: Only approved npm modules can be used
+- **Path Restrictions**: File operations are limited to safe directories
+- **Input Validation**: All user inputs are validated before processing
+
+### Performance
+- **Fast Startup**: Optimized for quick development iterations
+- **Efficient Packaging**: Only includes necessary files in packages
+- **Caching**: Configuration and dependencies are cached for performance
+
+## Examples
+
+### Basic Handler
+```javascript
+// handler/handler.js
+module.exports = {
+  customerCreateHandler: function(event) {
+    // Process customer creation
+    const customer = event.customer;
+    
+    console.log(`New customer: ${customer.email}`);
+    
+    // Return response
+    return {
+      status: 'success',
+      message: `Customer ${customer.email} processed`
+    };
+  }
+};
+```
+
+### Using Dependencies
+```javascript
+// handler/handler.js
+const _ = require('lodash');
+
+module.exports = {
+  dataProcessHandler: function(event) {
+    // Use lodash for data manipulation
+    const processedData = _.map(event.data, item => ({
+      id: item.id,
+      name: _.capitalize(item.name),
+      timestamp: new Date().toISOString()
+    }));
+    
+    return {
+      status: 'success',
+      processed_count: processedData.length,
+      data: processedData
+    };
+  }
+};
+```
+
+### Error Handling
+```javascript
+// handler/handler.js
+module.exports = {
+  robustHandler: function(event) {
+    try {
+      // Process event
+      if (!event.required_field) {
+        throw new Error('Missing required field');
+      }
+      
+      // Business logic here
+      const result = processBusinessLogic(event);
+      
+      return {
+        status: 'success',
+        result: result
+      };
+    } catch (error) {
+      console.error('Handler error:', error.message);
+      return {
+        status: 'error',
+        message: error.message
+      };
+    }
+  }
+};
+```
+
+## Version History
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

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/bin/index.js

@@ -0,0 +1 @@
+require("../dist/index.js");

package/dist/api/iparams.routes.d.ts

@@ -0,0 +1,6 @@
+import { CBFileSystem } from '@chargebee/chargebee-apps-shared';
+import { Application } from 'express';
+/**
+ * Sets up all iparams-related API routes
+ */
+export declare function setupIparamsRoutes(app: Application, userCodeDir: string, fileSystem: CBFileSystem): void;

package/dist/api/iparams.routes.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupIparamsRoutes = setupIparamsRoutes;
+const chargebee_apps_shared_1 = require("@chargebee/chargebee-apps-shared");
+const registry_1 = require("../registry");
+const REGISTRY = registry_1.PublicCliRegistry.getInstance();
+const __logger = REGISTRY.logger;
+/**
+ * Sets up all iparams-related API routes
+ */
+function setupIparamsRoutes(app, userCodeDir, fileSystem) {
+    const service = new chargebee_apps_shared_1.IparamsService(fileSystem);
+    app.get('/api/iparams', (_req, res) => {
+        try {
+            return res.json({ iparams: service.loadIparamDefns(userCodeDir) });
+        }
+        catch (error) {
+            __logger.error('Error: Failed to load iparams.json', error);
+            const rawContent = error.rawContent ?? null;
+            return res.status(400).json({
+                error: 'Failed to load iparams.json',
+                message: error instanceof Error ? error.message : 'Unknown error',
+                rawContent
+            });
+        }
+    });
+    app.post('/api/iparams', (req, res) => {
+        try {
+            const iparamDefns = req.body.iparams;
+            service.saveIparamDefns(userCodeDir, iparamDefns);
+            return res.json({ success: true, message: 'Iparams saved successfully' });
+        }
+        catch (error) {
+            __logger.error('Error: Failed to save iparams', error);
+            return res.status(400).json({
+                error: 'Failed to save iparams',
+                message: error instanceof Error ? error.message : 'Unknown error'
+            });
+        }
+    });
+    app.get('/api/iparams/inputs', (_req, res) => {
+        try {
+            return res.json({ inputs: service.loadInputs(userCodeDir) });
+        }
+        catch (error) {
+            __logger.error('Error: Failed to load iparams.local.json', error);
+            return res.status(400).json({
+                error: 'Failed to load iparams.local.json',
+                message: error instanceof Error ? error.message : 'Unknown error'
+            });
+        }
+    });
+    app.post('/api/iparams/inputs', (req, res) => {
+        try {
+            service.saveInputs(userCodeDir, req.body.inputs);
+            return res.json({ success: true, message: 'Inputs saved successfully' });
+        }
+        catch (error) {
+            if (error instanceof chargebee_apps_shared_1.MissingRequiredParamsError) {
+                return res.status(400).json({
+                    valid: false,
+                    missing: error.missing,
+                    message: error.message
+                });
+            }
+            __logger.error('Error: Failed to save iparams inputs', error);
+            return res.status(400).json({
+                error: 'Failed to save iparams inputs',
+                message: error instanceof Error ? error.message : 'Unknown error'
+            });
+        }
+    });
+}

package/dist/api/routes.d.ts

@@ -0,0 +1,39 @@
+import { CBFileSystem, CBProcess, DependencyManager, EventRecord, ICBLogger } from '@chargebee/chargebee-apps-shared';
+import { Application } from 'express';
+import * as http from "http";
+/**
+ * Sets up and start an Express server for the serverless app tester
+ * @param {number} port - The port number to run the server on
+ * @param {string} userCodeDir - The user code directory where logs should be stored
+ * @param {CBFileSystem} fileSystem - The filesystem implementation to use
+ * @param {CBProcess} processService - The process implementation to use
+ * @param {DependencyManager} dependencyManager - The dependency manager implementation to use
+ */
+export declare function setupServer(port: number, userCodeDir: string, fileSystem?: CBFileSystem, processService?: CBProcess, dependencyManager?: DependencyManager): http.Server;
+/**
+ * Invokes an event handler based on the event data
+ * @param {EventRecord} eventData - The event data containing event_type and payload
+ * @param {ICBLogger} sessionLogger - The logger instance for this server session
+ * @param {string} userCodeDir - The user code directory
+ * @param {CBFileSystem} fileSystem - The filesystem implementation to use
+ * @param {DependencyManager} dependencyManager - The dependency manager implementation to use
+ * @returns {Promise<any>} The result from the handler function
+ * @throws {Error} If handler file, manifest, or handler function is not found
+ */
+export declare function invokeEventHandler(eventData: EventRecord, sessionLogger: ICBLogger, userCodeDir: string, fileSystem: CBFileSystem, dependencyManager: DependencyManager): Promise<any>;
+/**
+ * Sets up all API routes for the serverless app tester
+ * @param {Application} app - Express application instance
+ * @param {ICBLogger} sessionLogger - The logger instance for this server session
+ * @param {string} userCodeDir - The user code directory
+ * @param {CBFileSystem} fileSystem - The filesystem implementation to use
+ * @param {CBProcess} process - The process implementation to use
+ * @param {DependencyManager} dependencyManager - The dependency manager implementation to use
+ */
+export declare function setupApiRoutes(app: Application, sessionLogger: ICBLogger, userCodeDir: string, fileSystem: CBFileSystem, process: CBProcess, dependencyManager: DependencyManager): void;
+/**
+ * Sets up application routes for serving the web UI
+ * @param {Application} app - Express application instance
+ * @param {CBFileSystem} fileSystem - The filesystem implementation to use
+ */
+export declare function setupAppRoutes(app: Application, fileSystem: CBFileSystem): void;