@chargebee/chargebee-apps-libs 0.0.2

package/templates/serverless-node-starter-app-with-iparams/handler/handler.js

@@ -0,0 +1,39 @@
+/**
+ * Serverless function handlers
+ * Each handler receives a single payload argument with payload.event and payload.iparams.<section>.<param>
+ */
+module.exports = {
+
+  /**
+   * Handles customer_created event
+   * @param {import('../types/types.d.ts').HandlerPayload} payload - Event and iparams
+   */
+  customerCreateHandler: function(/** @type {import('../types/types.d.ts').HandlerPayload} */payload) {
+    console.log('Processing customer_created event');
+    console.log('Customer created for email: ', payload.event.content.customer.email);
+    console.log('Processing fee (%): ', payload.iparams.processing_fee_configuration.fee_percentage);
+    console.log('Processing fee limit: ', payload.iparams.processing_fee_configuration.fee_limit);
+  },
+
+  /**
+   * Handles subscription_created events
+   * @param {import('../types/types.d.ts').HandlerPayload} payload - Event and iparams
+   */
+  subscriptionCreatedHandler: function(/** @type {import('../types/types.d.ts').HandlerPayload} */payload) {
+    console.log('Processing subscription_created event');
+    console.log('Subscription created for email: ', payload.event.content.customer.email);
+    console.log('Late payment fee (%): ', payload.iparams.late_payment_fee_configuration.fee_percentage);
+  },
+
+  /**
+   * Handles invoice_generated events
+   * @param {import('../types/types.d.ts').HandlerPayload} payload - Event and iparams
+   */
+  invoiceGeneratedHandler: function(/** @type {import('../types/types.d.ts').HandlerPayload} */payload) {
+    console.log('Processing invoice_generated event');
+    console.log('Invoice status: ', payload.event.content.invoice.status);
+    console.log('Processing fee (%): ', payload.iparams.processing_fee_configuration.fee_percentage);
+    console.log('Late payment fee (%): ', payload.iparams.late_payment_fee_configuration.fee_percentage);
+  }
+
+};

package/templates/serverless-node-starter-app-with-iparams/iparams.json

@@ -0,0 +1,41 @@
+{
+	"installation_parameters": {
+		"sections": [
+			{
+				"name": "processing_fee_configuration",
+				"display_name": "Processing Fee Configuration",
+				"description": "Provide the fields below to proceed.",
+				"parameters": [
+					{
+						"name": "fee_percentage",
+						"display_name": "Processing Fee (%)",
+						"description": "Percentage fee applied to each transaction",
+						"type": "NUMBER",
+						"required": true
+					},
+					{
+						"name": "fee_limit",
+						"display_name": "Processing Fee Limit",
+						"description": "Maximum processing fee amount to charge (in minor currency units, e.g. cents)",
+						"type": "NUMBER",
+						"default": 100
+					}
+				]
+			},
+			{
+				"name": "late_payment_fee_configuration",
+				"display_name": "Late Payment Fee Configuration",
+				"description": "Configure penalties when invoices are paid after the due date.",
+				"parameters": [
+					{
+						"name": "fee_percentage",
+						"display_name": "Late Payment Fee (%)",
+						"description": "Penalty percentage added to overdue invoice balances",
+						"type": "NUMBER",
+						"required": true
+					}
+				]
+			}
+		]
+	}
+}

package/templates/serverless-node-starter-app-with-iparams/iparams.local.json

@@ -0,0 +1,9 @@
+{
+	"processing_fee_configuration": {
+		"fee_percentage": 3,
+		"fee_limit": 100
+	},
+	"late_payment_fee_configuration": {
+		"fee_percentage": 5
+	}
+}

package/templates/serverless-node-starter-app-with-iparams/jsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "allowJs": true,
+    "checkJs": true,
+    "resolveJsonModule": true,
+    "strict": false,
+    "noImplicitAny": false,
+    "noImplicitReturns": true,
+    "noImplicitThis": false,
+    "noUnusedLocals": true,
+    "noUnusedParameters": false,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"],
+      "@handler/*": ["./handler/*"],
+      "@types/*": ["./types/*"],
+      "@test_data/*": ["./test_data/*"]
+    },
+    "typeRoots": ["./types", "./node_modules/@types"]
+  },
+  "include": [
+    "**/*.js",
+    "**/*.d.ts",
+    "**/*.json"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "*.min.js"
+  ]
+} 

package/templates/serverless-node-starter-app-with-iparams/manifest.json

@@ -0,0 +1,15 @@
+{
+  "name": "<your-app-name>",
+  "description": "<your-app-description>",
+  "events": {
+    "customer_created": {
+      "handler": "customerCreateHandler"
+    },
+    "subscription_created": {
+      "handler": "subscriptionCreatedHandler"
+    },
+    "invoice_generated": {
+      "handler": "invoiceGeneratedHandler"
+    }
+  }
+} 

package/templates/serverless-node-starter-app-with-iparams/test_data/customer_created.json

@@ -0,0 +1,51 @@
+{
+    "api_version": "v2",
+    "content": {
+        "customer": {
+            "allow_direct_debit": false,
+            "auto_collection": "on",
+            "billing_address": {
+                "country": "US",
+                "object": "billing_address",
+                "validation_status": "not_validated"
+            },
+            "card_status": "no_card",
+            "channel": "web",
+            "company": "Example",
+            "created_at": 1755783294,
+            "created_from_ip": "54.88.235.200",
+            "deleted": false,
+            "email": "johndoe@example.com",
+            "excess_payments": 0,
+            "first_name": "John",
+            "id": "AzqUAXUuVzllT3Zr",
+            "last_name": "Doe",
+            "mrr": 0,
+            "net_term_days": 0,
+            "object": "customer",
+            "phone": "123 456 7890",
+            "pii_cleared": "active",
+            "preferred_currency_code": "USD",
+            "promotional_credits": 0,
+            "refundable_credits": 0,
+            "resource_version": 1755783294193,
+            "taxability": "taxable",
+            "unbilled_charges": 0,
+            "updated_at": 1755783294
+        }
+    },
+    "event_type": "customer_created",
+    "id": "ev_AzqUAXUuVzlmf3Zs",
+    "object": "event",
+    "occurred_at": 1755783294,
+    "source": "admin_console",
+    "user": "foo@bar.com",
+    "webhook_status": "scheduled",
+    "webhooks": [
+        {
+            "id": "whv2_169zTyUkn2tgg2fOQ",
+            "object": "webhook",
+            "webhook_status": "scheduled"
+        }
+    ]
+}

package/templates/serverless-node-starter-app-with-iparams/test_data/invoice_generated.json

@@ -0,0 +1,112 @@
+{
+    "api_version": "v2",
+    "content": {
+        "invoice": {
+            "adjustment_credit_notes": [],
+            "amount_adjusted": 0,
+            "amount_due": 0,
+            "amount_paid": 0,
+            "amount_to_collect": 0,
+            "applied_credits": [],
+            "base_currency_code": "USD",
+            "billing_address": {
+                "company": "Example",
+                "country": "US",
+                "first_name": "John",
+                "last_name": "Doe",
+                "object": "billing_address",
+                "validation_status": "not_validated"
+            },
+            "channel": "web",
+            "credits_applied": 0,
+            "currency_code": "USD",
+            "customer_id": "AzqUAXUuVzllT3Zr",
+            "date": 1755783502,
+            "deleted": false,
+            "due_date": 1755783502,
+            "dunning_attempts": [],
+            "exchange_rate": 1,
+            "first_invoice": true,
+            "generated_at": 1755783502,
+            "has_advance_charges": false,
+            "id": "93",
+            "is_gifted": false,
+            "issued_credit_notes": [],
+            "line_items": [
+                {
+                    "amount": 0,
+                    "customer_id": "AzqUAXUuVzllT3Zr",
+                    "date_from": 1755783502,
+                    "date_to": 1758461902,
+                    "description": "Plan-Free",
+                    "discount_amount": 0,
+                    "entity_id": "cbdemo_free",
+                    "entity_type": "plan",
+                    "id": "li_AzZTN3UuW0e4m3il",
+                    "is_taxed": false,
+                    "item_level_discount_amount": 0,
+                    "object": "line_item",
+                    "pricing_model": "flat_fee",
+                    "quantity": 1,
+                    "subscription_id": "AzZTN3UuW0e4B3ij",
+                    "tax_amount": 0,
+                    "tax_exempt_reason": "tax_not_configured",
+                    "unit_amount": 0
+                }
+            ],
+            "linked_orders": [],
+            "linked_payments": [],
+            "net_term_days": 0,
+            "new_sales_amount": 0,
+            "object": "invoice",
+            "paid_at": 1755783502,
+            "price_type": "tax_exclusive",
+            "recurring": true,
+            "resource_version": 1755783502991,
+            "round_off_amount": 0,
+            "site_details_at_creation": {
+                "organization_address": {
+                    "city": "Hyderabad",
+                    "country_code": "IN",
+                    "line1": "asfdgdhfjgfgf",
+                    "organization_name": "Chargebee",
+                    "phone": "01234565543",
+                    "state": "Andaman and Nicobar Islands",
+                    "state_code": "AN",
+                    "zip": "500028"
+                },
+                "timezone": "Universal"
+            },
+            "status": "paid",
+            "sub_total": 0,
+            "subscription_id": "AzZTN3UuW0e4B3ij",
+            "tax": 0,
+            "tax_origin": {
+                "country": "IN"
+            },
+            "term_finalized": true,
+            "total": 0,
+            "updated_at": 1755783502,
+            "write_off_amount": 0
+        }
+    },
+    "event_type": "invoice_generated",
+    "id": "ev_AzZTN3UuW0e7G3in",
+    "object": "event",
+    "occurred_at": 1755783503,
+    "source": "admin_console",
+    "user": "manideep@chargebee.com",
+    "webhook_status": "scheduled",
+    "webhooks": [
+        {
+            "id": "whv2_AzZX7CUVnj5rB1ZHq",
+            "object": "webhook",
+            "webhook_status": "disabled"
+        },
+        {
+            "id": "whv2_169zTyUkn2tgg2fOQ",
+            "object": "webhook",
+            "webhook_status": "scheduled"
+        }
+    ]
+}

package/templates/serverless-node-starter-app-with-iparams/test_data/subscription_created.json

@@ -0,0 +1,173 @@
+{
+    "api_version": "v2",
+    "content": {
+        "customer": {
+            "allow_direct_debit": false,
+            "auto_collection": "on",
+            "billing_address": {
+                "country": "US",
+                "object": "billing_address",
+                "validation_status": "not_validated"
+            },
+            "card_status": "no_card",
+            "channel": "web",
+            "company": "Example",
+            "created_at": 1755783294,
+            "created_from_ip": "54.88.235.200",
+            "deleted": false,
+            "email": "johndoe@example.com",
+            "excess_payments": 0,
+            "first_name": "John",
+            "id": "AzqUAXUuVzllT3Zr",
+            "last_name": "Doe",
+            "mrr": 0,
+            "net_term_days": 0,
+            "object": "customer",
+            "phone": "123 456 7890",
+            "pii_cleared": "active",
+            "preferred_currency_code": "USD",
+            "promotional_credits": 0,
+            "refundable_credits": 0,
+            "resource_version": 1755783294193,
+            "taxability": "taxable",
+            "unbilled_charges": 0,
+            "updated_at": 1755783294
+        },
+        "invoice": {
+            "adjustment_credit_notes": [],
+            "amount_adjusted": 0,
+            "amount_due": 0,
+            "amount_paid": 0,
+            "amount_to_collect": 0,
+            "applied_credits": [],
+            "base_currency_code": "USD",
+            "billing_address": {
+                "company": "Example",
+                "country": "US",
+                "first_name": "John",
+                "last_name": "Doe",
+                "object": "billing_address",
+                "validation_status": "not_validated"
+            },
+            "channel": "web",
+            "credits_applied": 0,
+            "currency_code": "USD",
+            "customer_id": "AzqUAXUuVzllT3Zr",
+            "date": 1755783502,
+            "deleted": false,
+            "due_date": 1755783502,
+            "dunning_attempts": [],
+            "exchange_rate": 1,
+            "first_invoice": true,
+            "generated_at": 1755783502,
+            "has_advance_charges": false,
+            "id": "93",
+            "is_gifted": false,
+            "issued_credit_notes": [],
+            "line_items": [
+                {
+                    "amount": 0,
+                    "customer_id": "AzqUAXUuVzllT3Zr",
+                    "date_from": 1755783502,
+                    "date_to": 1758461902,
+                    "description": "Plan-Free",
+                    "discount_amount": 0,
+                    "entity_id": "cbdemo_free",
+                    "entity_type": "plan",
+                    "id": "li_AzZTN3UuW0e4m3il",
+                    "is_taxed": false,
+                    "item_level_discount_amount": 0,
+                    "object": "line_item",
+                    "pricing_model": "flat_fee",
+                    "quantity": 1,
+                    "subscription_id": "AzZTN3UuW0e4B3ij",
+                    "tax_amount": 0,
+                    "tax_exempt_reason": "tax_not_configured",
+                    "unit_amount": 0
+                }
+            ],
+            "linked_orders": [],
+            "linked_payments": [],
+            "net_term_days": 0,
+            "new_sales_amount": 0,
+            "object": "invoice",
+            "paid_at": 1755783502,
+            "price_type": "tax_exclusive",
+            "recurring": true,
+            "resource_version": 1755783502991,
+            "round_off_amount": 0,
+            "site_details_at_creation": {
+                "organization_address": {
+                    "city": "Hyderabad",
+                    "country_code": "IN",
+                    "line1": "asfdgdhfjgfgf",
+                    "organization_name": "Chargebee",
+                    "phone": "01234565543",
+                    "state": "Andaman and Nicobar Islands",
+                    "state_code": "AN",
+                    "zip": "500028"
+                },
+                "timezone": "Universal"
+            },
+            "status": "paid",
+            "sub_total": 0,
+            "subscription_id": "AzZTN3UuW0e4B3ij",
+            "tax": 0,
+            "tax_origin": {
+                "country": "IN"
+            },
+            "term_finalized": true,
+            "total": 0,
+            "updated_at": 1755783502,
+            "write_off_amount": 0
+        },
+        "subscription": {
+            "activated_at": 1755783502,
+            "billing_period": 1,
+            "billing_period_unit": "month",
+            "channel": "web",
+            "created_at": 1755783502,
+            "created_from_ip": "54.88.235.200",
+            "currency_code": "USD",
+            "current_term_end": 1758461902,
+            "current_term_start": 1755783502,
+            "customer_id": "AzqUAXUuVzllT3Zr",
+            "deleted": false,
+            "due_invoices_count": 0,
+            "has_scheduled_advance_invoices": false,
+            "has_scheduled_changes": false,
+            "id": "AzZTN3UuW0e4B3ij",
+            "mrr": 0,
+            "next_billing_at": 1758461902,
+            "object": "subscription",
+            "plan_amount": 0,
+            "plan_free_quantity": 0,
+            "plan_id": "cbdemo_free",
+            "plan_quantity": 1,
+            "plan_unit_price": 0,
+            "resource_version": 1755783503004,
+            "started_at": 1755783502,
+            "status": "active",
+            "updated_at": 1755783503
+        }
+    },
+    "event_type": "subscription_created",
+    "id": "ev_AzZTN3UuW0e7V3io",
+    "object": "event",
+    "occurred_at": 1755783503,
+    "source": "admin_console",
+    "user": "manideep@chargebee.com",
+    "webhook_status": "scheduled",
+    "webhooks": [
+        {
+            "id": "whv2_AzZX7CUVnj5rB1ZHq",
+            "object": "webhook",
+            "webhook_status": "scheduled"
+        },
+        {
+            "id": "whv2_169zTyUkn2tgg2fOQ",
+            "object": "webhook",
+            "webhook_status": "scheduled"
+        }
+    ]
+}

package/templates/serverless-node-starter-app-with-iparams/types/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Type definitions for Chargebee Apps applications
+ * This file provides TypeScript types for common structures used in Chargebee apps
+ */
+
+/**
+ * Event record structure for Chargebee webhook events
+ * This represents the actual structure of Chargebee webhook events
+ * Note: Event types are dynamically generated by Chargebee
+ * Examples include: 'customer_created', 'subscription_created', 'subscription_renewed', etc.
+ */
+export interface EventRecord {
+	/** API version */
+	api_version: string;
+	/** Event content containing the actual data */
+	content: Record<string, any>;
+	/** Type of the event (e.g., 'customer_created', 'subscription_created') */
+	event_type: string;
+	/** Unique identifier for the event */
+	id: string;
+	/** Object type */
+	object: string;
+	/** Timestamp when the event occurred */
+	occurred_at: number;
+	/** Source of the event */
+	source: string;
+	/** Webhook status */
+	webhook_status: string;
+	/** Array of webhook configurations */
+	webhooks: Array<{
+		id: string;
+		object: string;
+		webhook_status: string;
+	}>;
+}
+
+/** Union of every value an iparam can hold */
+export type IparamValue = string | number | boolean | string[];
+
+/** Parameter values for a single section */
+export interface SectionObject {
+	[key: string]: IparamValue;
+}
+
+/**
+ * Installation parameter values keyed by section name.
+ * Access: payload.iparams.<section_name>.<param_name>
+ * Example: { "offline_payment_sync": { "sync_mode": "Manual Sync" } }
+ */
+export interface IparamInputs {
+	[sectionName: string]: SectionObject;
+}
+
+/**
+ * Single argument passed to every event handler.
+ * Use payload.event for the webhook event and payload.iparams.<section>.<param> for installation parameters.
+ */
+export interface HandlerPayload {
+	/** The webhook event record */
+	event: EventRecord;
+	/** Installation parameter values grouped by section */
+	iparams: IparamInputs;
+}

package/ui/README.md

@@ -0,0 +1,118 @@
+# Web UI
+
+Interactive web interface for testing serverless applications in the Chargebee Apps CLI.
+
+## Overview
+
+The web UI provides a user-friendly interface for testing serverless function handlers locally. It includes:
+- **Interactive Testing**: Visual interface for testing event handlers
+- **JSON Editor**: Syntax-highlighted editor for event data
+- **Developer Guide**: Built-in instructions for adding new events
+- **Real-time Feedback**: Immediate execution results and error messages
+
+## Structure
+
+```
+packages/public-libs/ui/
+└── web/
+    ├── assets/
+    │   ├── css/
+    │   │   └── main.css          # Styling and layout
+    │   ├── js/
+    │   │   └── main.js           # Interactive functionality
+    │   └── images/
+    │       └── Chargebee-logo.png # Brand assets
+    └── index.html             # Main application interface
+```
+
+## Features
+
+### Interactive Interface
+- **Event Selection**: Dropdown populated from `manifest.json`
+- **JSON Editor**: Ace editor with syntax highlighting and autocompletion
+- **Test Execution**: One-click handler testing with custom data
+- **Status Display**: Real-time feedback on execution results
+
+### Developer Guide
+Built-in documentation panel with:
+- **Event Setup**: Step-by-step instructions for adding new events
+- **Testing Guide**: How to test handlers using the interface
+
+### User Experience
+- **Auto-loading**: Sample data loads automatically for each event
+- **Keyboard Shortcuts**: Ctrl+Enter to test, Ctrl+R to reset
+- **Error Handling**: Clear error messages for missing handlers or files
+
+## Technical Implementation
+
+### Frontend Technologies
+- **HTML5**: Semantic markup structure
+- **CSS3**: Modern styling with gradients and animations
+- **Vanilla JavaScript**: No framework dependencies
+- **Ace Editor**: Professional code editor for JSON editing
+
+### API Integration
+The UI communicates with the CLI's API endpoints:
+- `GET /api/manifest` - Loads available events
+- `GET /api/test-data/:eventType` - Loads sample data
+- `POST /api/invoke` - Executes handlers
+
+## Usage
+
+### Starting the Interface
+1. Run the CLI: `npm start -- run my-app`
+2. Open browser: `http://localhost:15000`
+3. The web interface loads automatically
+
+### Testing Workflow
+1. **Select Event**: Choose from dropdown (populated from manifest.json)
+2. **Edit Data**: Modify JSON in the syntax-highlighted editor
+3. **Test Handler**: Click "Test Data" to execute
+4. **View Results**: Check status and terminal output
+
+### Adding New Events
+1. **Update manifest.json**: Add event type and handler mapping
+2. **Create handler function**: Implement in handler.js
+3. **Add sample data**: Create `<event_type>.json` in test_data/
+4. **Test via UI**: New event appears in dropdown automatically
+
+## Development
+
+### No Build Process
+The UI is designed for simplicity:
+- **Static Assets**: Served directly by Express
+- **No Bundling**: No build tools or preprocessing required
+- **Direct Editing**: Modify files and refresh browser
+
+### Customization
+The UI can be customized by:
+- **Styling**: Modify `main.css` for visual changes
+- **Functionality**: Update `main.js` for behavior changes
+- **Content**: Edit `index.html` for structural changes
+
+## Integration
+
+### CLI Integration
+- **Express Server**: Served by the CLI's API server
+- **Static Middleware**: Assets served from `packages/public-libs/ui/web/` directory
+- **API Communication**: Uses CLI's REST endpoints
+
+### Sandbox Integration
+- **Handler Execution**: UI triggers sandbox execution
+- **Logging**: User code output appears in terminal
+- **Error Reporting**: Sandbox errors displayed in UI
+
+## Browser Support
+
+### Supported Browsers
+- **Chrome**: Full support (recommended)
+- **Firefox**: Full support
+- **Safari**: Full support
+- **Edge**: Full support
+
+### Requirements
+- **JavaScript**: Must be enabled
+- **ES6 Support**: Modern JavaScript features used
+- **Fetch API**: For API communication
+
+For detailed API integration, see the [API Module Documentation](../src/api/README.md).