n8n-nodes-lemonsqueezy 0.4.0 → 0.6.0

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

@@ -1,61 +1,335 @@
+/**
+ * Lemon Squeezy API Helper Functions
+ *
+ * This module provides utility functions for:
+ * - Input validation (email, URL, date, etc.)
+ * - API request handling with retry logic
+ * - Webhook signature verification
+ * - JSON:API body construction
+ * - Query parameter building
+ *
+ * @module helpers
+ */
 import type { IExecuteFunctions, IWebhookFunctions, IHookFunctions, IHttpRequestMethods, IDataObject } from 'n8n-workflow';
+import type { PaginationOptions } from './types';
 /**
- * Validate email format
+ * Validates email format using RFC 5322 compliant regex.
+ *
+ * The validation checks for:
+ * - Valid local part characters (alphanumeric and special chars)
+ * - Single @ symbol
+ * - Valid domain with proper TLD (at least one dot)
+ *
+ * @param email - The email address to validate
+ * @returns True if the email format is valid, false otherwise
+ *
+ * @example
+ * isValidEmail('user@example.com') // true
+ * isValidEmail('invalid') // false
+ * isValidEmail('user@localhost') // false (no TLD)
  */
 export declare function isValidEmail(email: string): boolean;
 /**
- * Validate URL format
+ * Validates URL format and ensures it's a safe external URL.
+ *
+ * Security features:
+ * - Only allows http:// and https:// protocols
+ * - Blocks localhost and loopback addresses (127.0.0.1, ::1, [::1])
+ * - Blocks private network ranges (10.x, 172.16-31.x, 192.168.x)
+ * - Blocks link-local addresses (169.254.x - AWS metadata endpoint)
+ *
+ * This prevents Server-Side Request Forgery (SSRF) attacks.
+ *
+ * @param url - The URL to validate
+ * @returns True if the URL is valid and safe, false otherwise
+ *
+ * @example
+ * isValidUrl('https://example.com') // true
+ * isValidUrl('http://localhost:3000') // false (internal)
+ * isValidUrl('ftp://files.example.com') // false (non-http protocol)
+ * isValidUrl('http://169.254.169.254') // false (AWS metadata)
  */
 export declare function isValidUrl(url: string): boolean;
 /**
- * Validate ISO 8601 date format
+ * Validates ISO 8601 date format.
+ *
+ * Accepts dates in formats like:
+ * - 2024-01-15
+ * - 2024-01-15T10:30:00Z
+ * - 2024-01-15T10:30:00.000Z
+ *
+ * @param dateString - The date string to validate
+ * @returns True if the date is valid ISO 8601 format, false otherwise
+ *
+ * @example
+ * isValidIsoDate('2024-01-15T10:30:00Z') // true
+ * isValidIsoDate('invalid') // false
+ * isValidIsoDate('01/15/2024') // false (no dash separator)
  */
 export declare function isValidIsoDate(dateString: string): boolean;
 /**
- * Validate that a value is a positive integer
+ * Validates that a value is a positive integer (greater than 0).
+ *
+ * @param value - The value to validate
+ * @returns True if the value is a positive integer, false otherwise
+ *
+ * @example
+ * isPositiveInteger(5) // true
+ * isPositiveInteger(0) // false
+ * isPositiveInteger(-1) // false
+ * isPositiveInteger(3.14) // false
+ * isPositiveInteger('5') // false (string, not number)
  */
 export declare function isPositiveInteger(value: unknown): boolean;
 /**
- * Validate field with specific type and throw descriptive error
+ * Validates a field value and throws a descriptive error if invalid.
+ *
+ * Supports multiple validation types:
+ * - 'required': Ensures value is not empty/null/undefined
+ * - 'email': RFC 5322 compliant email validation
+ * - 'url': Safe URL validation with SSRF protection
+ * - 'date': ISO 8601 date format validation
+ * - 'positiveInteger': Positive integer validation
+ *
+ * @param fieldName - The name of the field (used in error messages)
+ * @param value - The value to validate
+ * @param validationType - The type of validation to perform
+ * @throws Error with descriptive message if validation fails
+ *
+ * @example
+ * validateField('email', 'user@example.com', 'email') // passes
+ * validateField('email', 'invalid', 'email') // throws "email must be a valid email address"
  */
 export declare function validateField(fieldName: string, value: unknown, validationType: 'email' | 'url' | 'date' | 'positiveInteger' | 'required'): void;
 /**
- * Safely parse JSON with error handling
+ * Safely parses a JSON string with descriptive error handling.
+ *
+ * @template T - The expected type of the parsed JSON
+ * @param jsonString - The JSON string to parse
+ * @param fieldName - The name of the field (used in error messages)
+ * @returns The parsed JSON object
+ * @throws Error if the JSON is invalid
+ *
+ * @example
+ * const data = safeJsonParse<{name: string}>('{"name": "test"}', 'config')
+ * // Returns: {name: "test"}
+ *
+ * safeJsonParse('invalid json', 'config')
+ * // Throws: "config contains invalid JSON"
  */
 export declare function safeJsonParse<T = unknown>(jsonString: string, fieldName: string): T;
 /**
- * Make an authenticated request to the Lemon Squeezy API with retry logic
+ * Pauses execution for a specified duration.
+ *
+ * Used for implementing retry delays and rate limit backoff.
+ *
+ * @param ms - The number of milliseconds to sleep
+ * @returns A promise that resolves after the specified duration
+ *
+ * @example
+ * await sleep(1000) // Wait 1 second
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Checks if an error is a rate limit error (HTTP 429).
+ *
+ * Handles both direct statusCode and nested response.statusCode patterns.
+ *
+ * @param error - The error object to check
+ * @returns True if the error is a rate limit error, false otherwise
+ *
+ * @example
+ * isRateLimitError({ statusCode: 429 }) // true
+ * isRateLimitError({ response: { statusCode: 429 } }) // true
+ * isRateLimitError({ statusCode: 500 }) // false
+ */
+export declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Checks if an error is retryable (5xx server errors or network errors).
+ *
+ * Retryable conditions:
+ * - HTTP 5xx status codes (500-599)
+ * - Network errors: ECONNRESET, ETIMEDOUT, ECONNREFUSED
+ *
+ * @param error - The error object to check
+ * @returns True if the error is retryable, false otherwise
+ *
+ * @example
+ * isRetryableError({ statusCode: 503 }) // true (server error)
+ * isRetryableError({ code: 'ECONNRESET' }) // true (network error)
+ * isRetryableError({ statusCode: 404 }) // false (client error)
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Makes an authenticated request to the Lemon Squeezy API with retry logic.
+ *
+ * Features:
+ * - Automatic authentication using stored credentials
+ * - Rate limit handling with automatic retry after delay
+ * - Exponential backoff for server errors (5xx)
+ * - Configurable request timeout (default: 30 seconds)
+ * - Detailed error messages using NodeApiError
+ *
+ * @param this - The n8n execution context
+ * @param method - HTTP method (GET, POST, PATCH, DELETE)
+ * @param endpoint - API endpoint path (e.g., '/v1/products')
+ * @param body - Optional request body for POST/PATCH requests
+ * @param qs - Optional query string parameters
+ * @param timeout - Request timeout in milliseconds (default: 30000)
+ * @returns The API response data
+ * @throws NodeApiError if the request fails after all retries or times out
+ *
+ * @example
+ * // GET request
+ * const product = await lemonSqueezyApiRequest.call(this, 'GET', '/v1/products/123')
+ *
+ * // POST request with body
+ * const checkout = await lemonSqueezyApiRequest.call(this, 'POST', '/v1/checkouts', {
+ *   data: { type: 'checkouts', attributes: { ... } }
+ * })
+ *
+ * // Request with custom timeout (60 seconds)
+ * const data = await lemonSqueezyApiRequest.call(this, 'GET', '/v1/orders', undefined, {}, 60000)
  */
-export declare function lemonSqueezyApiRequest(this: IExecuteFunctions | IWebhookFunctions | IHookFunctions, method: IHttpRequestMethods, endpoint: string, body?: IDataObject, qs?: Record<string, string | number>): Promise<IDataObject>;
+export declare function lemonSqueezyApiRequest(this: IExecuteFunctions | IWebhookFunctions | IHookFunctions, method: IHttpRequestMethods, endpoint: string, body?: IDataObject, qs?: Record<string, string | number>, timeout?: number): Promise<IDataObject>;
 /**
- * Make paginated requests to fetch all items
+ * Makes paginated requests to fetch all items from a Lemon Squeezy API endpoint.
+ *
+ * Automatically handles pagination by following 'next' links until all items
+ * are retrieved. Includes rate limit handling for long-running fetches.
+ *
+ * Features:
+ * - Optional maxItems limit to prevent memory issues with large datasets
+ * - Optional timeout to prevent long-running requests
+ * - Rate limit handling with automatic retry
+ *
+ * @param this - The n8n execution context
+ * @param method - HTTP method (typically 'GET')
+ * @param endpoint - API endpoint path (e.g., '/v1/products')
+ * @param qs - Optional query string parameters (filters, sorting, etc.)
+ * @param paginationOptions - Optional pagination configuration
+ * @returns Array of all items from all pages (up to maxItems if specified)
+ * @throws NodeApiError if any request fails or timeout is exceeded
+ *
+ * @example
+ * // Fetch all products with filtering
+ * const products = await lemonSqueezyApiRequestAllItems.call(
+ *   this, 'GET', '/v1/products', { 'filter[store_id]': 123 }
+ * )
+ *
+ * // Fetch with limits
+ * const products = await lemonSqueezyApiRequestAllItems.call(
+ *   this, 'GET', '/v1/products', {}, { maxItems: 1000, timeout: 60000 }
+ * )
  */
-export declare function lemonSqueezyApiRequestAllItems(this: IExecuteFunctions, method: IHttpRequestMethods, endpoint: string, qs?: Record<string, string | number>): Promise<IDataObject[]>;
+export declare function lemonSqueezyApiRequestAllItems(this: IExecuteFunctions, method: IHttpRequestMethods, endpoint: string, qs?: Record<string, string | number>, paginationOptions?: PaginationOptions): Promise<IDataObject[]>;
 /**
- * Validate required fields before making API request
+ * Validates that all required fields are present and non-empty.
+ *
+ * @param fields - Object containing field values to validate
+ * @param requiredFields - Array of field names that are required
+ * @throws Error listing all missing fields if any are empty
+ *
+ * @example
+ * validateRequiredFields({ name: 'Test', email: '' }, ['name', 'email'])
+ * // Throws: "Missing required fields: email"
  */
 export declare function validateRequiredFields(fields: Record<string, unknown>, requiredFields: string[]): void;
 /**
- * Build filter query string parameters
+ * Builds filter query string parameters for Lemon Squeezy API.
+ *
+ * Converts camelCase field names to snake_case and wraps them in
+ * filter[] syntax as required by the API.
+ *
+ * @param filters - Object containing filter key-value pairs
+ * @returns Query string parameters object for API request
+ *
+ * @example
+ * buildFilterParams({ storeId: 123, status: 'active' })
+ * // Returns: { 'filter[store_id]': 123, 'filter[status]': 'active' }
  */
 export declare function buildFilterParams(filters: IDataObject): Record<string, string | number>;
 /**
- * Build JSON:API request body
+ * Builds a JSON:API compliant request body for create/update operations.
+ *
+ * Constructs the proper structure expected by Lemon Squeezy API:
+ * - data.type: Resource type (e.g., 'checkouts', 'customers')
+ * - data.attributes: Resource attributes
+ * - data.relationships: Optional related resource references
+ * - data.id: Optional resource ID (for updates)
+ *
+ * @param type - The JSON:API resource type
+ * @param attributes - Resource attributes to include
+ * @param relationships - Optional relationships to other resources
+ * @param id - Optional resource ID (required for updates)
+ * @returns Properly structured JSON:API request body
+ *
+ * @example
+ * buildJsonApiBody('customers', { name: 'John', email: 'john@example.com' },
+ *   { store: { type: 'stores', id: '123' } })
+ * // Returns: { data: { type: 'customers', attributes: {...}, relationships: {...} } }
  */
 export declare function buildJsonApiBody(type: string, attributes: IDataObject, relationships?: Record<string, {
     type: string;
     id: string;
 }>, id?: string): IDataObject;
 /**
- * Parse webhook signature for validation
+ * Verifies a webhook signature using HMAC-SHA256.
+ *
+ * Uses timing-safe comparison to prevent timing attacks.
+ *
+ * @param payload - The raw webhook payload string
+ * @param signature - The signature from X-Signature header
+ * @param secret - The webhook signing secret
+ * @returns True if signature is valid, false otherwise
+ *
+ * @example
+ * const isValid = verifyWebhookSignature(
+ *   '{"data": {...}}',
+ *   'abc123signature',
+ *   'webhook_secret_key'
+ * )
  */
 export declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 /**
- * Build query params with relationship expansion (include)
+ * Builds query parameters for including related resources in API responses.
+ *
+ * Uses the JSON:API include parameter to fetch related resources in a single
+ * request, reducing the number of API calls needed.
+ *
+ * @param includes - Array of relationship names to include
+ * @returns Query string parameters object with 'include' key
+ *
+ * @example
+ * buildIncludeParams(['store', 'customer', 'order-items'])
+ * // Returns: { include: 'store,customer,order-items' }
+ *
+ * buildIncludeParams([])
+ * // Returns: {}
  */
 export declare function buildIncludeParams(includes: string[]): Record<string, string>;
 /**
- * Build advanced filter params with date range support
+ * Builds advanced filter parameters with support for date ranges and sorting.
+ *
+ * Features:
+ * - Converts camelCase to snake_case for API compatibility
+ * - Handles date range filters with _after/_before suffixes
+ * - Adds sorting with ascending/descending direction
+ *
+ * @param filters - Object containing filter key-value pairs
+ * @param options - Optional configuration for date fields and sorting
+ * @param options.dateFields - Array of field names that are date ranges
+ * @param options.sortField - Field name to sort by
+ * @param options.sortDirection - Sort direction ('asc' or 'desc')
+ * @returns Query string parameters object for API request
+ *
+ * @example
+ * buildAdvancedFilterParams(
+ *   { status: 'active', createdAt: { from: '2024-01-01', to: '2024-12-31' } },
+ *   { dateFields: ['createdAt'], sortField: 'created_at', sortDirection: 'desc' }
+ * )
+ * // Returns: { 'filter[status]': 'active', 'filter[created_at_after]': '2024-01-01',
+ * //           'filter[created_at_before]': '2024-12-31', sort: '-created_at' }
  */
 export declare function buildAdvancedFilterParams(filters: IDataObject, options?: {
     dateFields?: string[];
@@ -63,10 +337,36 @@ export declare function buildAdvancedFilterParams(filters: IDataObject, options?
     sortDirection?: 'asc' | 'desc';
 }): Record<string, string | number>;
 /**
- * Extract data from JSON:API response with proper typing
+ * Extracts the 'data' field from a JSON:API response with proper typing.
+ *
+ * JSON:API responses wrap the actual resource data in a 'data' field.
+ * This helper extracts it while preserving type information.
+ *
+ * @template T - The expected type of the extracted data
+ * @param response - The full JSON:API response object
+ * @returns The extracted data, or undefined if not present
+ *
+ * @example
+ * const response = { data: { id: '1', type: 'products', attributes: {...} } }
+ * const product = extractResponseData<Product>(response)
+ * // Returns: { id: '1', type: 'products', attributes: {...} }
  */
 export declare function extractResponseData<T = IDataObject>(response: IDataObject): T | T[] | undefined;
 /**
- * Extract included resources from JSON:API response
+ * Extracts included related resources from a JSON:API response.
+ *
+ * When using the 'include' query parameter, related resources are returned
+ * in the 'included' array of the response. This helper extracts them.
+ *
+ * @param response - The full JSON:API response object
+ * @returns Array of included resources, or empty array if none
+ *
+ * @example
+ * const response = {
+ *   data: {...},
+ *   included: [{ id: '1', type: 'stores', attributes: {...} }]
+ * }
+ * const stores = extractIncludedResources(response)
+ * // Returns: [{ id: '1', type: 'stores', attributes: {...} }]
  */
 export declare function extractIncludedResources(response: IDataObject): IDataObject[];