@chargebee/chargebee-apps

@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)

npm install -g @chargebee/chargebee-apps

Local Installation

npm install @chargebee/chargebee-apps
npx chargebee-apps --help

Quick Start

# 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.

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.

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.

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.

{
  "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).

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.

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 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:

{
  "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:

{
  "event_type": "customer_created",
  "id": "evt_123",
  "occurred_at": "2024-01-01T00:00:00Z",
  "customer": {
    "email": "[e-mail]"
  }
}

Response:

{
  "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

# Create new project
chargebee-apps create my-serverless-app
cd my-serverless-app

# Examine the generated structure
ls -la

2. Local Development

# 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

# 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

# Test via curl
curl -X POST http://localhost:15000/api/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "customer_created",
    "customer": {"email": "[e-mail]"}
  }'

Multiple Applications

# 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

CB_LOG_LEVEL=DEBUG chargebee-apps run my-app

Getting Help

chargebee-apps --help
chargebee-apps create --help
chargebee-apps run --help
chargebee-apps package --help

Package Structure

• src/commands/ - CLI command implementations (create, run, package)
• src/api/ - 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

// 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

// 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

// 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 for detailed version history.