n8n-nodes-lemonsqueezy 0.8.0 → 0.9.0

package/README.md

@@ -65,7 +65,7 @@ The main node for interacting with the Lemon Squeezy API.
 | **Product** | Get, Get Many |
 | **Store** | Get, Get Many |
 | **Subscription** | Get, Get Many, Update, Cancel, Resume |
-| **Subscription Invoice** | Get, Get Many |
+| **Subscription Invoice** | Get, Get Many, Generate, Refund |
 | **Usage Record** | Create, Get, Get Many |
 | **User** | Get Current |
 | **Variant** | Get, Get Many |
@@ -304,6 +304,21 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Changelog
 
+### v0.9.0
+
+**New Features:**
+- Added **Subscription Invoice Generate operation** for generating invoices on subscriptions with outstanding balances
+- Added **Subscription Invoice Refund operation** for issuing full or partial refunds
+- Added custom data payload size validation (max 10KB) for checkout creation
+- Added Retry-After header extraction for smarter rate limit handling
+- Added resource validation guard to catch unknown resources early
+
+**Improvements:**
+- Added JSDoc documentation to all resource files
+- Improved field descriptions with units (cents), ranges (0-100), and examples
+- Added maxValue (100) to all limit fields for API compliance
+- 189 tests with comprehensive coverage
+
 ### v0.8.0
 
 **New Features:**

package/dist/nodes/LemonSqueezy/LemonSqueezy.node.js

@@ -95,6 +95,8 @@ async function handleCreate(ctx, resource, itemIndex) {
         }
         if (additionalOptions.customData !== undefined && additionalOptions.customData !== null) {
             const customDataValue = additionalOptions.customData;
+            // Validate payload size before processing (max 10KB)
+            (0, helpers_1.validateCustomDataSize)(customDataValue);
             if (typeof customDataValue === 'string') {
                 try {
                     const parsed = JSON.parse(customDataValue);
@@ -356,6 +358,10 @@ class LemonSqueezy {
             try {
                 let responseData;
                 const endpoint = constants_1.RESOURCE_ENDPOINTS[resource];
+                // Validate that the resource exists in our endpoints mapping
+                if (!endpoint && !['user'].includes(resource)) {
+                    throw new Error(`Unknown resource: ${resource}`);
+                }
                 if (operation === 'get') {
                     const idParam = constants_1.RESOURCE_ID_PARAMS[resource];
                     const id = this.getNodeParameter(idParam, i);
@@ -444,6 +450,21 @@ class LemonSqueezy {
                 else if (resource === 'user' && operation === 'getCurrent') {
                     responseData = await helpers_1.lemonSqueezyApiRequest.call(this, 'GET', '/users/me');
                 }
+                else if (resource === 'subscriptionInvoice') {
+                    if (operation === 'generate') {
+                        const subscriptionId = this.getNodeParameter('generateSubscriptionId', i);
+                        const body = (0, helpers_1.buildJsonApiBody)('subscription-invoices', {}, { subscription: { type: 'subscriptions', id: subscriptionId } });
+                        responseData = await helpers_1.lemonSqueezyApiRequest.call(this, 'POST', '/subscription-invoices', body);
+                    }
+                    else if (operation === 'refund') {
+                        const invoiceId = this.getNodeParameter('subscriptionInvoiceId', i);
+                        const refundAmount = this.getNodeParameter('refundAmount', i, 0);
+                        const body = refundAmount > 0
+                            ? { data: { type: 'subscription-invoices', attributes: { amount: refundAmount } } }
+                            : {};
+                        responseData = await helpers_1.lemonSqueezyApiRequest.call(this, 'POST', `/subscription-invoices/${invoiceId}/refund`, body);
+                    }
+                }
                 const executionData = this.helpers.constructExecutionMetaData(this.helpers.returnJsonArray(responseData), { itemData: { item: i } });
                 returnData.push(...executionData);
             }

package/dist/nodes/LemonSqueezy/helpers.d.ts

@@ -139,6 +139,34 @@ export declare function safeJsonParse<T = unknown>(jsonString: string, fieldName
  * validateDiscountAmount(-100, 'fixed') // throws "Fixed discount amount must be a positive integer"
  */
 export declare function validateDiscountAmount(amount: number, amountType: string): void;
+/**
+ * Validates that a custom data payload doesn't exceed the maximum size.
+ *
+ * This prevents memory issues and potential abuse from extremely large payloads.
+ *
+ * @param data - The custom data object or string to validate
+ * @param maxSizeBytes - Maximum allowed size in bytes (default: 10KB)
+ * @throws Error if the payload exceeds the maximum size
+ *
+ * @example
+ * validateCustomDataSize({ key: 'value' }) // passes
+ * validateCustomDataSize(veryLargeObject) // throws if > 10KB
+ */
+export declare function validateCustomDataSize(data: unknown, maxSizeBytes?: number): void;
+/**
+ * Extracts the Retry-After header value from an error response.
+ *
+ * The Retry-After header indicates how long to wait before retrying
+ * a rate-limited or temporarily unavailable request.
+ *
+ * @param error - The error object that may contain Retry-After header
+ * @returns Number of seconds to wait, or undefined if not present
+ *
+ * @example
+ * getRetryAfterSeconds({ response: { headers: { 'retry-after': '60' } } }) // 60
+ * getRetryAfterSeconds({ response: { headers: {} } }) // undefined
+ */
+export declare function getRetryAfterSeconds(error: unknown): number | undefined;
 /**
  * Checks if an error is a rate limit error (HTTP 429).
  *

package/dist/nodes/LemonSqueezy/helpers.js

@@ -52,6 +52,8 @@ exports.isPositiveInteger = isPositiveInteger;
 exports.validateField = validateField;
 exports.safeJsonParse = safeJsonParse;
 exports.validateDiscountAmount = validateDiscountAmount;
+exports.validateCustomDataSize = validateCustomDataSize;
+exports.getRetryAfterSeconds = getRetryAfterSeconds;
 exports.isRateLimitError = isRateLimitError;
 exports.isRetryableError = isRetryableError;
 exports.lemonSqueezyApiRequest = lemonSqueezyApiRequest;
@@ -311,6 +313,57 @@ function validateDiscountAmount(amount, amountType) {
         }
     }
 }
+/** Maximum payload size for custom data (10KB) */
+const MAX_CUSTOM_DATA_SIZE_BYTES = 10 * 1024;
+/**
+ * Validates that a custom data payload doesn't exceed the maximum size.
+ *
+ * This prevents memory issues and potential abuse from extremely large payloads.
+ *
+ * @param data - The custom data object or string to validate
+ * @param maxSizeBytes - Maximum allowed size in bytes (default: 10KB)
+ * @throws Error if the payload exceeds the maximum size
+ *
+ * @example
+ * validateCustomDataSize({ key: 'value' }) // passes
+ * validateCustomDataSize(veryLargeObject) // throws if > 10KB
+ */
+function validateCustomDataSize(data, maxSizeBytes = MAX_CUSTOM_DATA_SIZE_BYTES) {
+    const jsonString = typeof data === 'string' ? data : JSON.stringify(data);
+    const sizeBytes = Buffer.byteLength(jsonString, 'utf8');
+    if (sizeBytes > maxSizeBytes) {
+        const sizeKb = Math.round(sizeBytes / 1024);
+        const maxKb = Math.round(maxSizeBytes / 1024);
+        throw new Error(`Custom data exceeds maximum size (${sizeKb}KB > ${maxKb}KB). Reduce the payload size.`);
+    }
+}
+/**
+ * Extracts the Retry-After header value from an error response.
+ *
+ * The Retry-After header indicates how long to wait before retrying
+ * a rate-limited or temporarily unavailable request.
+ *
+ * @param error - The error object that may contain Retry-After header
+ * @returns Number of seconds to wait, or undefined if not present
+ *
+ * @example
+ * getRetryAfterSeconds({ response: { headers: { 'retry-after': '60' } } }) // 60
+ * getRetryAfterSeconds({ response: { headers: {} } }) // undefined
+ */
+function getRetryAfterSeconds(error) {
+    var _a, _b;
+    if (error && typeof error === 'object') {
+        const err = error;
+        const retryAfter = (_b = (_a = err.response) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? void 0 : _b['retry-after'];
+        if (retryAfter) {
+            const seconds = parseInt(retryAfter, 10);
+            if (!isNaN(seconds) && seconds > 0) {
+                return seconds;
+            }
+        }
+    }
+    return undefined;
+}
 /**
  * Checks if an error is a rate limit error (HTTP 429).
  *

package/dist/nodes/LemonSqueezy/resources/customer.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Customer Resource
+ *
+ * Provides operations for managing customers in Lemon Squeezy.
+ *
+ * Available operations:
+ * - Create: Create a new customer
+ * - Delete: Archive a customer
+ * - Get: Retrieve a single customer by ID
+ * - Get Many: Retrieve multiple customers with filtering
+ * - Update: Update customer information
+ *
+ * @see https://docs.lemonsqueezy.com/api/customers
+ */
 import type { INodeProperties } from 'n8n-workflow';
 export declare const customerOperations: INodeProperties;
 export declare const customerFields: INodeProperties[];

package/dist/nodes/LemonSqueezy/resources/discount.d.ts

@@ -1,3 +1,17 @@
+/**
+ * Discount Resource
+ *
+ * Provides operations for managing discount codes in Lemon Squeezy.
+ *
+ * Available operations:
+ * - Create: Create a new discount code
+ * - Delete: Delete an existing discount code
+ * - Get: Retrieve a single discount by ID
+ * - Get Many: Retrieve multiple discounts with filtering
+ * - Update: Update an existing discount code
+ *
+ * @see https://docs.lemonsqueezy.com/api/discounts
+ */
 import type { INodeProperties } from 'n8n-workflow';
 export declare const discountOperations: INodeProperties;
 export declare const discountFields: INodeProperties[];

package/dist/nodes/LemonSqueezy/resources/discount.js

@@ -98,7 +98,7 @@ exports.discountFields = [
         type: 'number',
         required: true,
         default: 0,
-        description: 'Discount amount (percentage 0-100 or fixed amount in cents)',
+        description: 'Discount amount. For percent type: 0-100 (e.g., 25 = 25% off). For fixed type: amount in cents (e.g., 1000 = $10.00 off).',
         displayOptions: {
             show: { resource: ['discount'], operation: ['create'] },
         },

package/dist/nodes/LemonSqueezy/resources/order.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Order Resource
+ *
+ * Provides operations for managing orders in Lemon Squeezy.
+ * Orders are created when customers complete purchases.
+ *
+ * Available operations:
+ * - Get: Retrieve a single order by ID
+ * - Get Many: Retrieve multiple orders with filtering
+ * - Refund: Issue a full refund for an order
+ *
+ * @see https://docs.lemonsqueezy.com/api/orders
+ */
 import type { INodeProperties } from 'n8n-workflow';
 export declare const orderOperations: INodeProperties;
 export declare const orderFields: INodeProperties[];

package/dist/nodes/LemonSqueezy/resources/order.js

@@ -62,8 +62,8 @@ exports.orderFields = [
         name: 'limit',
         type: 'number',
         default: 50,
-        description: 'Max number of results to return',
-        typeOptions: { minValue: 1 },
+        description: 'Max number of results to return (API maximum is 100 per page)',
+        typeOptions: { minValue: 1, maxValue: 100 },
         displayOptions: {
             show: { resource: ['order'], operation: ['getAll'], returnAll: [false] },
         },

package/dist/nodes/LemonSqueezy/resources/product.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Product Resource
+ *
+ * Provides read-only operations for products in Lemon Squeezy.
+ * Products are managed in the Lemon Squeezy dashboard and cannot be
+ * created, updated, or deleted via the API.
+ *
+ * Available operations:
+ * - Get: Retrieve a single product by ID
+ * - Get Many: Retrieve multiple products with filtering
+ *
+ * @see https://docs.lemonsqueezy.com/api/products
+ */
 import type { INodeProperties } from 'n8n-workflow';
 export declare const productOperations: INodeProperties;
 export declare const productFields: INodeProperties[];

package/dist/nodes/LemonSqueezy/resources/product.js

@@ -56,8 +56,8 @@ exports.productFields = [
         name: 'limit',
         type: 'number',
         default: 50,
-        description: 'Max number of results to return',
-        typeOptions: { minValue: 1 },
+        description: 'Max number of results to return (API maximum is 100 per page)',
+        typeOptions: { minValue: 1, maxValue: 100 },
         displayOptions: {
             show: { resource: ['product'], operation: ['getAll'], returnAll: [false] },
         },

package/dist/nodes/LemonSqueezy/resources/subscriptionInvoice.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Subscription Invoice Resource
+ *
+ * Provides operations for managing subscription invoices in Lemon Squeezy.
+ *
+ * Available operations:
+ * - Get: Retrieve a single subscription invoice by ID
+ * - Get Many: Retrieve multiple subscription invoices with filtering
+ * - Generate: Generate a new invoice for an outstanding balance
+ * - Refund: Issue a refund for a subscription invoice
+ *
+ * @see https://docs.lemonsqueezy.com/api/subscription-invoices
+ */
 import type { INodeProperties } from 'n8n-workflow';
 export declare const subscriptionInvoiceOperations: INodeProperties[];
 export declare const subscriptionInvoiceFields: INodeProperties[];

package/dist/nodes/LemonSqueezy/resources/subscriptionInvoice.js

@@ -13,6 +13,12 @@ exports.subscriptionInvoiceOperations = [
             },
         },
         options: [
+            {
+                name: 'Generate',
+                value: 'generate',
+                description: 'Generate an invoice for outstanding subscription balance',
+                action: 'Generate a subscription invoice',
+            },
             {
                 name: 'Get',
                 value: 'get',
@@ -25,12 +31,18 @@ exports.subscriptionInvoiceOperations = [
                 description: 'Get many subscription invoices',
                 action: 'Get many subscription invoices',
             },
+            {
+                name: 'Refund',
+                value: 'refund',
+                description: 'Issue a refund for a subscription invoice',
+                action: 'Refund a subscription invoice',
+            },
         ],
         default: 'getAll',
     },
 ];
 exports.subscriptionInvoiceFields = [
-    // Get
+    // Subscription Invoice ID for Get and Refund operations
     {
         displayName: 'Subscription Invoice ID',
         name: 'subscriptionInvoiceId',
@@ -40,10 +52,43 @@ exports.subscriptionInvoiceFields = [
         displayOptions: {
             show: {
                 resource: ['subscriptionInvoice'],
-                operation: ['get'],
+                operation: ['get', 'refund'],
+            },
+        },
+        description: 'The ID of the subscription invoice (e.g., "123456")',
+    },
+    // Subscription ID for Generate operation
+    {
+        displayName: 'Subscription ID',
+        name: 'generateSubscriptionId',
+        type: 'string',
+        required: true,
+        default: '',
+        displayOptions: {
+            show: {
+                resource: ['subscriptionInvoice'],
+                operation: ['generate'],
+            },
+        },
+        description: 'The ID of the subscription to generate an invoice for. Only works if the subscription has an outstanding balance.',
+    },
+    // Refund Options
+    {
+        displayName: 'Refund Amount',
+        name: 'refundAmount',
+        type: 'number',
+        required: false,
+        default: 0,
+        displayOptions: {
+            show: {
+                resource: ['subscriptionInvoice'],
+                operation: ['refund'],
             },
         },
-        description: 'The ID of the subscription invoice to retrieve',
+        description: 'Amount to refund in cents (e.g., 1000 = $10.00). Leave at 0 for full refund. Must not exceed the original invoice amount.',
+        typeOptions: {
+            minValue: 0,
+        },
     },
     // Get All
     {

package/dist/nodes/LemonSqueezy/resources/webhook.d.ts

@@ -1,3 +1,22 @@
+/**
+ * Webhook Resource
+ *
+ * Provides operations for managing webhooks in Lemon Squeezy.
+ * Webhooks allow your application to receive real-time notifications
+ * about events in your store.
+ *
+ * Available operations:
+ * - Create: Create a new webhook endpoint
+ * - Delete: Delete an existing webhook
+ * - Get: Retrieve a single webhook by ID
+ * - Get Many: Retrieve multiple webhooks with filtering
+ * - Update: Update webhook URL, events, or secret
+ *
+ * Security: Webhook secrets must be at least 32 characters.
+ * Generate one using: openssl rand -hex 32
+ *
+ * @see https://docs.lemonsqueezy.com/api/webhooks
+ */
 import type { INodeProperties } from 'n8n-workflow';
 export declare const webhookOperations: INodeProperties;
 export declare const webhookFields: INodeProperties[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n8n-nodes-lemonsqueezy",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "n8n community node for Lemon Squeezy - digital products and subscriptions platform",
   "keywords": [
     "n8n-community-node-package",