POC sample apps for new iparam structure

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/.env

@@ -0,0 +1,4 @@
+# Only these three variables are supported. Replace values for local development only. Do not add new vars.
+MKPLC_CB_READ_ONLY_API=REPLACE_WITH_READ_ONLY_API_KEY
+MKPLC_CB_READ_WRITE_API=REPLACE_WITH_READ_WRITE_API_KEY
+MKPLC_SITE_DOMAIN=REPLACE_WITH_SITE_DOMAIN

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/README.md

@@ -0,0 +1,31 @@
+# POC Sample App — iParam Access With Sections
+
+Internal feedback sample. Compare with [`poc-sample-app-with-direct-iparam-access`](../poc-sample-app-with-direct-iparam-access).
+
+## Accessing iparams in the handler
+
+```javascript
+payload.iparams.processing_fee_configuration.fee_percentage
+payload.iparams.processing_fee_configuration.fee_limit
+payload.iparams.late_payment_fee_configuration.fee_percentage
+```
+Parameters are read through the section name. Both sections use the parameter name `fee_percentage`.
+
+
+
+## `iparams.local.json`
+```json
+{
+  "processing_fee_configuration": {
+    "fee_percentage": 3,
+    "fee_limit": 10000
+  },
+  "late_payment_fee_configuration": {
+    "fee_percentage": 1.5
+  }
+}
+```
+
+## Duplicate parameter names across sections
+
+**Allowed.** The same parameter name (e.g. `fee_percentage`) can be used in multiple sections because each value is scoped under its section key.

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/handler/handler.js

@@ -0,0 +1,70 @@
+/**
+ * Serverless function handlers
+ * Each handler receives a single payload argument with payload.event and payload.iparams
+ */
+module.exports = {
+
+  /**
+   * 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) {
+    const invoice = payload.event.content.invoice;
+
+    // Need feedback on this
+    // ------------------------------------------------------------------------------------------------
+    // Here is one way of using the iparams where we access parameters through their section.
+    // In the iparams.json file, we have defined the parameters inside sections called
+    // "processing_fee_configuration" and "late_payment_fee_configuration".
+    // Both sections use the same parameter name "fee_percentage".
+
+    // We access them as payload.iparams.processing_fee_configuration.fee_percentage and
+    // payload.iparams.late_payment_fee_configuration.fee_percentage.
+
+    // This approach allows duplicate parameter names across sections since each name is scoped to its section.
+    // ------------------------------------------------------------------------------------------------
+
+    const processingFeePercentage = Number(
+      payload.iparams.processing_fee_configuration.fee_percentage
+    );
+    const processingFeeLimit = Number(
+      payload.iparams.processing_fee_configuration.fee_limit
+    );
+    const latePaymentFeePercentage = Number(
+      payload.iparams.late_payment_fee_configuration.fee_percentage
+    );
+
+    const isUnpaid = invoice.status !== 'paid';
+    const hasChargeableTotal = invoice.total > 0;
+    const isPastDue = invoice.due_date < payload.event.occurred_at;
+
+    if (isUnpaid && hasChargeableTotal) {
+      const calculatedProcessingFee = calculateAdditionalFee(invoice.total, processingFeePercentage);
+      const processingFee = Math.min(calculatedProcessingFee, processingFeeLimit);
+      applyAdditionalFee(invoice, processingFee);
+    }
+
+    if (isUnpaid && isPastDue && hasChargeableTotal) {
+      const latePaymentFee = calculateAdditionalFee(invoice.total, latePaymentFeePercentage);
+      applyAdditionalFee(invoice, latePaymentFee);
+    }
+  }
+
+};
+
+/**
+ * @param {Record<string, unknown>} invoice - Invoice object from the event payload
+ * @param {number} additionalFee - Fee amount to charge on the invoice
+ */
+function applyAdditionalFee(invoice, additionalFee) {
+  // The code for applying the additional fee goes here
+}
+
+/**
+ * @param {number} invoiceTotal - Invoice total in minor currency units (e.g. cents)
+ * @param {number} feePercentage - Fee percentage from installation parameters
+ * @returns {number}
+ */
+function calculateAdditionalFee(invoiceTotal, feePercentage) {
+  return (invoiceTotal * feePercentage) / 100;
+}

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/iparams.json

@@ -0,0 +1,44 @@
+{
+	"installation_parameters": {
+		"sections": [
+			{
+				"name": "processing_fee_configuration",
+				"display_name": "Processing Fee Configuration",
+				"description": "Complete the fields below to proceed.",
+				"parameters": [
+					{
+						"name": "fee_percentage",
+						"display_name": "Processing Fee (%)",
+						"description": "Percentage fee applied to each transaction",
+						"type": "NUMBER",
+						"default": "3",
+						"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": "10000",
+						"required": true
+					}
+				]
+			},
+			{
+				"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",
+						"default": "1.5",
+						"required": true
+					}
+				]
+			}
+		]
+	}
+}

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/iparams.local.json

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

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/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"
+  ]
+} 

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/manifest.json

@@ -0,0 +1,7 @@
+{
+  "events": {
+    "invoice_generated": {
+      "handler": "invoiceGeneratedHandler"
+    }
+  }
+}

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/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"
+        }
+    ]
+}

sample-apps/iparams-new-structure-with-groups/poc-sample-app-iparam-access-with-section/types/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Type definitions for Chargebee Marketplace applications
+ * This file provides TypeScript types for common structures used in marketplace applications
+ */
+
+/**
+ * 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;
+    }>;
+}
+
+/**
+ * Parameter values within a section
+ */
+export interface SectionValue {
+    [key: string]: string | number | boolean | string[];
+}
+
+/**
+ * iparam inputs keyed by section name, then parameter name
+ * Example: { "processing_fee_configuration": { "fee_percentage": 3 } }
+ */
+export interface IparamInputs {
+    [sectionName: string]: SectionValue;
+}
+
+/**
+ * Single argument passed to every event handler.
+ * Use payload.event for the webhook event and payload.iparams for installation parameters.
+ */
+export interface HandlerPayload {
+	/** The webhook event record */
+	event: EventRecord;
+	/** Installation parameter values */
+	iparams: IparamInputs;
+}

sample-apps/iparams-new-structure-with-groups/poc-sample-app-with-direct-iparam-access/.env

@@ -0,0 +1,4 @@
+# Only these three variables are supported. Replace values for local development only. Do not add new vars.
+MKPLC_CB_READ_ONLY_API=REPLACE_WITH_READ_ONLY_API_KEY
+MKPLC_CB_READ_WRITE_API=REPLACE_WITH_READ_WRITE_API_KEY
+MKPLC_SITE_DOMAIN=REPLACE_WITH_SITE_DOMAIN