@chargebee/chargebee-apps 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,297 @@
+# Chargebee Apps CLI Developer Guide
+
+The Chargebee Apps CLI is a command-line tool for building private serverless applications that extend Chargebee Billing. Use it to scaffold a new app, implement and test event handlers locally, and package the app into a ZIP file. When your app is ready, upload it to the Apps portal in Chargebee Billing to publish it privately to your site.
+
+In Chargebee, a serverless application (also called an app) is a set of Node.js event handlers that run in Chargebee's hosted environment in response to Chargebee events. You write only the handler logic; Chargebee runs it automatically when a matching event occurs, so there is no server or infrastructure for you to provision, scale, or maintain.
+
+With the Apps CLI, you can:
+
+- Generate a ready-to-run app template.
+- Implement and test event handlers locally.
+- Trigger events interactively through a built-in web testing UI.
+- Package your app into a deployable artifact.
+
+## Prerequisites
+
+- Node.js 22 is required.
+
+## Install and verify the CLI
+
+Install the CLI globally:
+
+```bash
+npm install -g @chargebee/chargebee-apps
+```
+
+Verify the installation by confirming that the version and help commands run successfully:
+
+```bash
+chargebee-apps --version
+chargebee-apps --help
+```
+
+If both commands display the version and the list of `chargebee-apps` commands, your setup is complete.
+
+## Create a new application
+
+Scaffold a new project with the `create` command. Choose the template that matches your app's requirements.
+
+### Standard template
+
+Use the default template, `serverless-node-starter-app`, if your app performs pure event processing without user-configurable settings.
+
+```bash
+# Create in the current directory
+chargebee-apps create <app_name>
+
+# Create within a specific subdirectory path
+chargebee-apps create <subdirectory_path>/<app_name>
+```
+
+### iParams template
+
+Use the iParams template if your app needs installation parameters (iParams) — user-configurable settings such as API keys, URLs, fee rules, or feature flags that users supply when they install the app.
+
+```bash
+chargebee-apps create <app_name> --template serverless-node-starter-app-with-iparams
+```
+
+## Understand the app structure
+
+The files in your project depend on the template you chose. Files marked as packaged are included in the deployable artifact; the rest are used only for local development.
+
+| File or folder | Standard template | iParams template | Packaged | Purpose |
+| --- | --- | --- | --- | --- |
+| `manifest.json` | Yes | Yes | Yes | Maps Chargebee events to handler functions and declares npm dependencies. |
+| `handler/handler.js` | Yes | Yes | Yes | Contains your core event-handling logic. |
+| `iparams.json` | No | Yes | Yes | iParams template only. Defines the installation parameter schema. |
+| `iparams.local.json` | No | Yes | No | iParams template only. Stores local test values, keyed by section name. |
+| `test_data/` | Yes | Yes | No | Mock JSON event payloads used only for local testing. |
+| `.env` | Yes | Yes | No | Local system environment variables. |
+| `logs/cb.log` | Yes | Yes | No | Local development log file. |
+
+### manifest.json — App configuration
+
+The `manifest.json` file defines your app's metadata, maps event subscriptions to their handler functions, and declares required third-party package dependencies.
+
+```json
+{
+  "name": "your_app_name",
+  "description": "A clear description of what your serverless app does",
+  "events": {
+    "customer_created": {
+      "handler": "customerCreateHandler"
+    },
+    "invoice_generated": {
+      "handler": "invoiceGeneratedHandler"
+    }
+  },
+  "dependencies": {
+    "chargebee": "3.14.0"
+  }
+}
+```
+
+- **Event names:** Each key under `events` must exactly match a valid Chargebee webhook event type.
+- **Handler names:** Each `handler` value must match a function exported from `handler/handler.js`.
+- **Dependencies:** Only `chargebee` and `axios` are currently supported. For any additional npm packages, [contact the Chargebee support team](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team).
+
+### handler/handler.js — Application logic
+
+Write your event-handling logic in `handler/handler.js`. Each handler receives a single `payload` argument. Use `payload.event` to access the event data. If you use the iParams template, access installation parameters through `payload.iparams.<section_name>.<param_name>`.
+
+```javascript
+module.exports = {
+  customerCreateHandler: function (payload) {
+    console.log("Processing customer_created event");
+    console.log("Customer created for email:", payload.event.content.customer.email);
+
+    // iParams template only: read configuration if present
+    if (payload.iparams && payload.iparams.processing_fee_configuration) {
+      const fees = payload.iparams.processing_fee_configuration;
+      console.log("Processing fee (%):", fees.fee_percentage);
+      console.log("Processing fee limit:", fees.fee_limit);
+    }
+  },
+
+  invoiceGeneratedHandler: function (payload) {
+    console.log("Processing invoice_generated event");
+    console.log("Invoice status:", payload.event.content.invoice.status);
+
+    // iParams template only: read configuration if present
+    if (payload.iparams && payload.iparams.late_payment_fee_configuration) {
+      const lateFees = payload.iparams.late_payment_fee_configuration;
+      console.log("Late payment fee (%):", lateFees.fee_percentage);
+    }
+  }
+};
+```
+
+### .env — Environment variables
+
+Define your Chargebee API keys and site domain in a `.env` file. The CLI supports only these three variables:
+
+```plain text
+MKPLC_CB_READ_ONLY_API=your_read_only_api_key_here
+MKPLC_CB_READ_WRITE_API=your_read_write_api_key_here
+MKPLC_SITE_DOMAIN=your_site_domain_here
+```
+
+Access these values in your handler code through `process.env`, for example `process.env.MKPLC_CB_READ_ONLY_API`. The `.env` file is used for local development only and is not included when you package your app. In the hosted environment, Chargebee injects these variables automatically.
+
+<Note>
+These environment variables are different from installation parameters (iParams). Environment variables are standard system values that Chargebee injects automatically and require no user action. iParams are user-defined settings that an installer provides when they install or update the app.
+</Note>
+
+## Define installation parameters (iParams)
+
+This section applies only to apps built with the iParams template. Installation parameters let users configure your app when they install it — for example, API keys, endpoints, fee rules, or feature flags. An empty object (`{}`) in `iparams.json` means no installation parameters are defined.
+
+### Schema structure
+
+Parameters are grouped into named sections in `iparams.json`. A maximum of 20 parameters is allowed in total across all sections.
+
+Each section supports the following properties:
+
+- `name` (required): Unique section identifier. Maximum 50 characters.
+- `display_name` (required): Human-readable section title shown in the UI. Maximum 50 characters.
+- `description` (required): Explains what the section configures. Maximum 250 characters.
+- `parameters` (required): A non-empty array of parameter definitions.
+
+Each parameter supports the following attributes:
+
+- `name` (required): Unique parameter key within the section. Maximum 50 characters.
+- `display_name` (required): Human-readable input label. Maximum 50 characters.
+- `description` (required): Explains what the parameter is used for. Maximum 250 characters.
+- `type` (required): One of the supported types listed below.
+- `required` (optional): Defaults to `false`.
+- `default` (optional): Default fallback value. Not allowed for the `SECRET` type.
+- `options` (conditional): Required only for `DROPDOWN` and `MULTISELECT_DROPDOWN`.
+
+### Supported parameter types
+
+| Type | Input or use case |
+| --- | --- |
+| `TEXT` | String (maximum 250 characters) for names, labels, and non-sensitive keys. |
+| `SECRET` | String (maximum 250 characters) for passwords and API tokens. Encrypted at rest. Never log these values. |
+| `URL` | Enforces valid `http://` or `https://` webhook and API endpoints. |
+| `NUMBER` | Integer or decimal values for percentages, limits, and counts. |
+| `BOOLEAN` | `true` or `false` toggles for feature flags. |
+| `DROPDOWN` | Single selection from the choices in the `options` array. |
+| `MULTISELECT_DROPDOWN` | Multiple selections from the choices in the `options` array. |
+| `DATE` | Enforces `YYYY-MM-DD` formatting for expiry or start dates. |
+
+### Example: CRM schema with URL and SECRET
+
+The following `iparams.json` defines a section with a URL endpoint and a secret token:
+
+```json
+{
+  "installation_parameters": {
+    "sections": [
+      {
+        "name": "crm_integration",
+        "display_name": "CRM Integration",
+        "description": "HubSpot contacts API credentials and endpoint.",
+        "parameters": [
+          {
+            "name": "crm_webhook_url",
+            "display_name": "HubSpot contacts API URL",
+            "description": "Example: https://api.hubapi.com/crm/v3/objects/contacts",
+            "type": "URL",
+            "required": true
+          },
+          {
+            "name": "crm_auth_token",
+            "display_name": "HubSpot private app token",
+            "description": "Sent as Authorization: Bearer <token>.",
+            "type": "SECRET",
+            "required": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Provide local test inputs
+
+To test your parametrized handlers locally, supply mock values in `iparams.local.json`, keyed by section name:
+
+```json
+{
+  "crm_integration": {
+    "crm_webhook_url": "https://api.hubapi.com/crm/v3/objects/contacts",
+    "crm_auth_token": "pat-your-test-token"
+  }
+}
+```
+
+<Note>
+`iparams.local.json` is never packaged. In production, users provide these values when they install or update the app.
+</Note>
+
+## Run and test locally
+
+Start the local development server:
+
+```bash
+chargebee-apps run <app_directory>
+```
+
+To run the server on a custom port, add the `--port` option:
+
+```bash
+chargebee-apps run <app_directory> --port 16000
+```
+
+Then open the local development UI in your browser:
+
+- Default URL: `http://localhost:15000` (or your custom port).
+
+If you use the iParams template, the CLI validates your `iparams.json` schema on startup. Fix any schema errors before you execute handlers.
+
+### Use the local web UI
+
+- **Event testing:** Select an event type from the dropdown, for example `customer_created`. Review or edit the mock JSON payload loaded from `test_data/`, then click **Execute Handler**.
+- **iParams tab (iParams template only):** Edit your parameter schema fields interactively. Saving writes directly to `iparams.json`.
+- **iParams inputs tab (iParams template only):** Provide test values through a form or a raw JSON editor. Saving writes directly to `iparams.local.json`.
+- **Logs:** Console output appears in the terminal running the server and is appended to `logs/cb.log`.
+
+## Package your application
+
+After testing, bundle your application directory into a production-ready ZIP file:
+
+```bash
+chargebee-apps package <app_directory>
+```
+
+To set a custom version name, use the `--name` option:
+
+```bash
+chargebee-apps package <app_directory> --name my-app-v1.0.0
+```
+
+The package includes `manifest.json`, the `handler/` folder, and `iparams.json` (iParams template only). It excludes `test_data/`, `iparams.local.json`, `.env`, `logs/`, and `node_modules/`.
+
+The command compiles the deployable artifact into the `dist/` folder:
+
+```plain text
+my-first-app/
+└── dist/
+    └── app.zip
+```
+
+## Publish your app
+
+After you package your app, upload the ZIP file to the Apps portal in Chargebee Billing.
+
+1. In Chargebee Billing, go to **Apps** to open the Apps portal.
+2. Click **Create App**.
+3. On the **Upload Package** step, upload your app's `.zip` file. Click the upload area to browse, or drag and drop the file.
+4. On the **Review Details** step, review your app's details.
+5. Submit the app. Its status changes to **Under Review**.
+6. When the review is complete, the **Result** step shows the outcome.
+
+After your app is published, it appears in the Apps portal list, where you can track each app's type (private or public) and status, and manage updates.

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;