@chargebee/chargebee-apps-libs 0.0.2

package/templates/serverless-node-starter-app/README.md

@@ -0,0 +1,290 @@
+# Serverless Node.js App Template
+
+This is a serverless Node.js application template that demonstrates how to build and test serverless functions with event-driven architecture. This template provides a foundation for creating scalable serverless applications with built-in testing capabilities.
+
+## Features
+
+- **Event-Driven Architecture**: Configure multiple event handlers in `manifest.json`
+- **Handler Functions**: Implement your business logic in `handler.js`
+- **Test Data**: Sample event data for local development and testing
+- **Local Testing UI**: Interactive web interface to test your handlers
+- **Logging**: Built-in logging system for debugging and monitoring
+
+## How It Works
+
+1. **Event Configuration**: The `manifest.json` file maps event types to their corresponding handler functions
+2. **Handler Implementation**: Each event type has its handler function in `handler.js`
+3. **Test Data**: Sample JSON files in `test_data/` folder match your event names (e.g., `onCustomerCreate.json`)
+4. **Local Testing**: Use the CLI tool to start a local testing server with a web UI
+5. **Interactive Testing**: Select event types from the dropdown and click "Test Data" to execute handlers
+6. **Real-time Logs**: View execution logs directly in your terminal
+
+## Quick Start
+
+1. **Create your app**: `chargebee-apps create <app_directory>`
+2. **Navigate to app**: `cd <app_directory>`
+3. **Configure API keys** (optional): Edit `.env` file and replace placeholder values with your Chargebee API keys
+4. **Start local server**: `chargebee-apps run <app_directory>`
+5. **Open browser**: Visit `http://localhost:15000`
+6. **Test handlers**: Select an event type and click "Test Data"
+7. **View logs**: Check your terminal for execution output
+8. **Package your app**: `chargebee-apps package <app_directory>`
+
+## Project Structure
+
+```
+├── handler/handler.js  # Main serverless function handler
+├── test_data/          # Test data directory
+├── types/types.d.ts    # Recognised types that can be used as JSDoc inside handler function
+├── .env                # Environment variables (API keys)
+├── jsconfig.json       # JS config for dev
+├── manifest.json       # Project configuration
+└── README.md           # Read me file
+```
+
+## Configuration
+
+### Manifest.json
+
+The `manifest.json` file is the core configuration file for your serverless application. It defines:
+
+1. **Event Handlers**: Maps Chargebee webhook events to your handler functions
+2. **Application Metadata**: Basic information about your application
+3. **Dependencies**: Custom npm packages your application requires
+
+#### Basic Structure
+
+```json
+{
+  "name": "my-app",
+  "version": "1.0.0",
+  "description": "A custom app",
+  "events": {
+    "customer_created": {
+      "handler": "customerCreateHandler"
+    },
+    "subscription_created": {
+      "handler": "subscriptionCreatedHandler"
+    },
+    "invoice_generated": {
+      "handler": "invoiceGeneratedHandler"
+    }
+  },
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "axios": "^1.6.0"
+  }
+}
+```
+
+#### Event Handler Configuration
+
+Each event in the `events` object maps a Chargebee webhook event to a handler function:
+
+```json
+{
+  "events": {
+    "customer_created": {
+      "handler": "customerCreateHandler"
+    }
+  }
+}
+```
+
+The handler function must be exported from `handler/handler.js`. Each handler receives a single `payload` argument; use `payload.event` to access the event data:
+
+```javascript
+// handler/handler.js
+module.exports = {
+  customerCreateHandler: function(/** @type {import('../types/types.d.ts').HandlerPayload} */payload) {
+    // Your business logic here
+    console.log('Customer created:', payload.event.content.customer.email);
+    
+    // Example: Send welcome email
+    const customerEmail = payload.event.content.customer.email;
+    const customerName = payload.event.content.customer.first_name;
+    
+    // You can use custom dependencies here
+    const moment = require('moment');
+    const welcomeMessage = `Welcome ${customerName}! You joined on ${moment().format('MMMM Do YYYY')}`;
+    
+    console.log(welcomeMessage);
+  }
+};
+```
+
+#### Custom Dependencies
+
+You can add custom npm packages to your application by including them in the `dependencies` section:
+
+```json
+{
+  "dependencies": {
+    "lodash": "^4.17.21",
+    "axios": "^1.6.0",
+    "uuid": "^9.0.0"
+  }
+}
+```
+
+Then use them in your handler functions:
+
+```javascript
+// handler/handler.js
+const _ = require('lodash');
+const axios = require('axios');
+const moment = require('moment');
+const { v4: uuidv4 } = require('uuid');
+
+module.exports = {
+  customerCreateHandler: function(/** @type {import('../types/types.d.ts').HandlerPayload} */payload) {
+    // Use lodash for data manipulation
+    const customerData = _.pick(payload.event.content.customer, ['email', 'first_name', 'last_name']);
+    
+    // Generate unique ID
+    const customerId = uuidv4();
+    
+    // Make HTTP requests
+    axios.post('https://api.example.com/customers', {
+      id: customerId,
+      ...customerData,
+      created_at: moment().toISOString()
+    }).then(response => {
+      console.log('Customer synced to external system:', response.data);
+    }).catch(error => {
+      console.error('Failed to sync customer:', error.message);
+    });
+  },
+  
+  subscriptionCreatedHandler: function(/** @type {import('../types/types.d.ts').HandlerPayload} */payload) {
+    // Use moment for date formatting
+    const subscriptionDate = moment(payload.event.content.subscription.created_at * 1000);
+    const formattedDate = subscriptionDate.format('MMMM Do YYYY, h:mm:ss a');
+    
+    console.log(`New subscription created on ${formattedDate}`);
+    
+    // Use lodash for data validation
+    const requiredFields = ['id', 'customer_id', 'plan_id'];
+    const missingFields = _.difference(requiredFields, Object.keys(payload.event.content.subscription));
+    
+    if (missingFields.length > 0) {
+      console.warn('Missing subscription fields:', missingFields);
+    }
+  }
+};
+```
+
+#### Supported Event Types
+Chargebee Apps supports all the event types that are provided in the Chargebee's [documentation](https://apidocs.chargebee.com/docs/api/events#event_types).
+
+### Environment Variables
+
+The CLI exposes **only these three** variables via `process.env`; no other environment variables are available to your handlers:
+
+| Variable | Description |
+|----------|-------------|
+| `MKPLC_CB_READ_ONLY_API` | Chargebee read-only API key |
+| `MKPLC_CB_READ_WRITE_API` | Chargebee read-write API key |
+| `MKPLC_SITE_DOMAIN` | Chargebee site domain |
+
+- **Production:** The system provides these values at runtime. You do not configure them in production.
+- **Local development:** You must provide these values in the `.env` file so your handlers can run locally.
+
+#### Setting up .env for local development
+
+1. **Open the `.env` file** in your project root
+2. **Replace the placeholder values** with your actual Chargebee API keys:
+
+```env
+# Replace these with your actual Chargebee API keys
+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=yousite123
+```
+
+#### Using these variables in your handlers
+
+Access them through the `process.env` object in your handler functions:
+
+```javascript
+// handler/handler.js
+module.exports = {
+  customerCreateHandler: async function(/** @type {import('../types/types.d.ts').HandlerPayload} */payload) {
+    // Access your API keys
+    const readOnlyApiKey = process.env.MKPLC_CB_READ_ONLY_API;
+    const readWriteApiKey = process.env.MKPLC_CB_READ_WRITE_API;
+
+    if (!readOnlyApiKey || !readWriteApiKey) {
+      console.error('API keys not configured. Please check your .env file.');
+      return;
+    }
+
+    // Use the API keys for Chargebee API calls
+    console.log('Using API keys for Chargebee integration');
+
+    const Chargebee = require('chargebee');
+    const chargebee = new Chargebee({
+      site: process.env.MKPLC_SITE_DOMAIN,
+      apiKey: process.env.MKPLC_CB_READ_ONLY_API
+    });
+
+    const result = await chargebee.customer.retrieve(payload.event.content.customer.id);
+    console.log(result.customer);
+  }
+};
+```
+
+#### Security Notes
+
+- **Never commit real API keys** to version control
+- The `.env` file in this template contains placeholder values
+- Replace the placeholder values with your actual API keys before testing
+- Keep your API keys secure and don't share them publicly
+
+## Local Testing
+
+Use the CLI tool to test your functions locally with an interactive web interface:
+
+```bash
+# Start the testing server on a specific port
+chargebee-apps run <app_directory> --port <port>
+# Example:
+chargebee-apps run ./sample_app_v0 --port 16000
+
+# Open http://localhost:16000 in your browser
+# Select event types from the dropdown and click "Test Data" to execute handlers
+# View real-time logs in your terminal
+```
+
+## Testing
+
+Test data files are located in the `test_data/` directory. Each file is named after its corresponding event type (e.g., `customer_created.json`, `customer_updated.json`). These JSON files contain sample event data that you can use to test your handlers during local development.
+
+The test data structure should match the expected input format for your handler functions. You can modify these files to test different scenarios or add new test data files for additional event types.
+
+## Packaging
+
+The package command bundles your serverless application into a zip file for deployment.
+
+### Basic Usage
+
+```bash
+# Package with default name (app directory name)
+chargebee-apps package <app_directory>
+
+# Package with custom name
+chargebee-apps package <app_directory> --name my-app-v1.0.0
+```
+
+### Examples
+
+```bash
+# Package current directory
+chargebee-apps package .
+
+# Package specific directory
+chargebee-apps package ./my-app
+
+# Package with versioned name
+chargebee-apps package ./my-app --name my-app-v1.0.0
+```

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

@@ -0,0 +1,34 @@
+/**
+ * Serverless function handlers
+ * Each handler receives a single payload argument with payload.event
+ */
+module.exports = {
+
+  /**
+   * Handles customer_created events
+   * @param {import('../types/types.d.ts').HandlerPayload} payload 
+   */
+  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);
+  },
+
+  /**
+   * Handles subscription_created events
+   * @param {import('../types/types.d.ts').HandlerPayload} payload
+   */
+  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);
+  },
+
+  /**
+   * Handles invoice_generated events
+   * @param {import('../types/types.d.ts').HandlerPayload} payload
+   */
+  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);
+  }
+  
+};

package/templates/serverless-node-starter-app/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/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/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/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"
+        }
+    ]
+}