@chargebee/chargebee-apps-shared 0.0.1

package/dist/sandbox/sandbox-context.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sandboxContext = exports.SandboxContext = void 0;
+const async_hooks_1 = require("async_hooks");
+/**
+ * SandboxContext manages the execution context for sandboxed code execution
+ * using AsyncLocalStorage to maintain correlation between event and site information
+ */
+class SandboxContext {
+    constructor() {
+        this.asyncLocalStorage = new async_hooks_1.AsyncLocalStorage();
+    }
+    /**
+     * Creates a new execution context with event and site information
+     * @param {Object} contextData - The context data containing event and site information
+     * @param {string} contextData.eventId - The unique identifier for the event
+     * @param {string} contextData.eventType - The type of the event (e.g., 'customer_created')
+     * @param {string} contextData.site - The site/tenant identifier in Chargebee
+     * @param {Function} callback - The function to execute within this context
+     * @returns {Promise<any>} The result of the callback execution
+     */
+    async run(contextData, callback) {
+        const context = {
+            eventId: contextData.eventId || 'unknown',
+            eventType: contextData.eventType || 'unknown',
+            startTime: new Date().toISOString(),
+        };
+        return this.asyncLocalStorage.run(context, () => callback());
+    }
+    /**
+     * Gets the current execution context
+     * @returns {Object|null} The current context or null if not in an execution context
+     */
+    getCurrentContext() {
+        return this.asyncLocalStorage.getStore();
+    }
+    /**
+     * Checks if there is an active execution context
+     * @returns {boolean} True if there is an active context, false otherwise
+     */
+    hasContext() {
+        return this.asyncLocalStorage.getStore() !== undefined;
+    }
+}
+exports.SandboxContext = SandboxContext;
+// Create a singleton instance
+exports.sandboxContext = new SandboxContext();
+exports.default = exports.sandboxContext;

package/dist/sandbox/sandbox-wrapper.d.ts

@@ -0,0 +1,75 @@
+import { ICBLogger } from '../logger/cb-logger';
+import { HandlerPayload } from '../types/common';
+/**
+ * Result of sandbox execution
+ */
+export interface ExecutionResult {
+    /** Whether the execution was successful */
+    success: boolean;
+    /** HTTP status code (200 for success, error code for failures) */
+    statusCode?: number;
+    /** Error message if execution failed */
+    error?: string;
+    /** Stack trace if execution failed */
+    stack?: string | undefined;
+}
+/**
+ * Sandbox environment configuration
+ */
+export interface SandboxEnvironment {
+    /** Controlled console object */
+    console: any;
+    /** Read-only payload (event + iparams) passed to handler(payload) */
+    payload: HandlerPayload;
+    /** Safe async primitives */
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+    setImmediate: typeof setImmediate;
+    clearImmediate: typeof clearImmediate;
+    /** CommonJS emulation */
+    module: {
+        exports: any;
+    };
+    exports: any;
+    /** Controlled module access */
+    require: (moduleName: string) => any;
+    /** Limited process access */
+    process: {
+        cwd: () => string;
+        env: Record<string, string>;
+        nextTick: typeof process.nextTick;
+    };
+    /** Prevented escape hatches */
+    global?: undefined;
+    Buffer?: undefined;
+    __dirname?: undefined;
+    __filename?: undefined;
+}
+/**
+ * Interface for sandbox wrapper implementations
+ * This defines the contract that both public and private sandbox implementations must follow
+ */
+export interface ISandboxWrapper {
+    /**
+     * Creates a safe require function that uses isolated node_modules
+     * @param projectPath - Path to the user project
+     * @returns A safe require function
+     */
+    createSafeRequire(projectPath: string): (moduleName: string) => any;
+    /**
+     * Creates a secure sandbox environment for code execution
+     * @param projectPath - Path to the user project
+     * @param payload - Handler payload (event + iparams) to expose to user code as handler(payload)
+     * @param sessionLogger - Logger instance for this server session
+     * @returns The sandbox environment object; handlers are invoked with payload
+     */
+    createSandbox(projectPath: string, payload: HandlerPayload, sessionLogger: ICBLogger): SandboxEnvironment;
+    /**
+     * Executes user-provided code in a secure sandbox environment
+     * @param userCodePath - Path to the directory containing user code
+     * @param payload - Handler payload (event + iparams) to pass to the user handler
+     * @param sessionLogger - The logger instance for this server session
+     * @returns {Promise<ExecutionResult>} Execution result with success status and data/error
+     */
+    execute(userCodePath: string, payload: HandlerPayload, sessionLogger: ICBLogger): Promise<ExecutionResult>;
+}

package/dist/sandbox/sandbox-wrapper.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/common.d.ts

@@ -0,0 +1,135 @@
+/**
+ * EventRecord is the type for the event data that is passed to the handler function.
+ */
+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;
+    }>;
+}
+export interface AllowedModule {
+    name: string;
+    version?: string;
+    description?: string;
+    type: 'internal' | 'public';
+}
+export interface Manifest {
+    events: Record<string, {
+        handler: string;
+    }>;
+    dependencies?: Record<string, string>;
+}
+/**
+ * Create options for create command
+ */
+export interface CreateOptions {
+    template: string;
+}
+/**
+ * Run options for run command
+ */
+export interface RunOptions {
+    port: string;
+}
+/**
+ * Package options for package command
+ */
+export interface PackageOptions {
+    name: string;
+}
+/**
+ * Map of iparam `type` identifiers to placeholder values.
+ * Keys match valid `type` values in `iparams.json`; each value’s TypeScript type is the allowed
+ * JSON shape for that type in definition defaults and `iparams.local.json`.
+ */
+export declare const IPARAM_TYPE_VALUE_MAP: {
+    NUMBER: number;
+    TEXT: string;
+    DROPDOWN: string;
+    MULTISELECT_DROPDOWN: string[];
+    DATE: string;
+    URL: string;
+    BOOLEAN: boolean;
+    SECRET: string;
+};
+/** Parameter type (keys of {@link IPARAM_TYPE_VALUE_MAP}) */
+export type IparamType = keyof typeof IPARAM_TYPE_VALUE_MAP;
+/** Per-type value type; derived from {@link IPARAM_TYPE_VALUE_MAP} */
+export type IparamValueByType = {
+    [K in IparamType]: (typeof IPARAM_TYPE_VALUE_MAP)[K];
+};
+/** Valid `type` strings for runtime checks. */
+export declare const VALID_IPARAM_TYPES: IparamType[];
+/** Union of every value an iparam can hold. */
+export type IparamValue = IparamValueByType[IparamType];
+/** Single parameter entry inside a section in `iparams.json`. */
+export interface IparamDefn {
+    name: string;
+    display_name: string;
+    description: string;
+    type: IparamType;
+    required?: boolean;
+    default?: IparamValue;
+    options?: string[];
+}
+/** Group of related parameters in `iparams.json`. */
+export interface IparamSection {
+    name: string;
+    display_name: string;
+    description: string;
+    parameters: IparamDefn[];
+}
+/** Parameter values for a single section in `iparams.local.json`. */
+export interface SectionObject {
+    [key: string]: IparamValue;
+}
+/**
+ * Root schema for `iparams.json`.
+ * An empty object means no installation parameters are defined.
+ * Parameter names are unique within a section and may repeat across sections.
+ */
+export interface IparamDefns {
+    installation_parameters?: {
+        sections: IparamSection[];
+    };
+}
+/**
+ * Root values for `iparams.local.json`, keyed by section name.
+ * Access in handlers: `payload.iparams.<section_name>.<param_name>`.
+ */
+export interface IparamInputs {
+    [sectionName: string]: SectionObject;
+}
+/** SNS payload version */
+export type PayloadVersion = 'v1' | 'v2';
+/**
+ * Single argument passed to event handlers.
+ * Handlers receive payload with event data and installation parameters.
+ */
+export interface HandlerPayload {
+    /** The webhook event record */
+    event: EventRecord;
+    /**
+     * Installation parameter values.
+     * Present for templates/apps that define iparams; omitted for templates without iparams.
+     */
+    iparams?: IparamInputs;
+}

package/dist/types/common.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VALID_IPARAM_TYPES = exports.IPARAM_TYPE_VALUE_MAP = void 0;
+/**
+ * Map of iparam `type` identifiers to placeholder values.
+ * Keys match valid `type` values in `iparams.json`; each value’s TypeScript type is the allowed
+ * JSON shape for that type in definition defaults and `iparams.local.json`.
+ */
+exports.IPARAM_TYPE_VALUE_MAP = {
+    NUMBER: 0,
+    TEXT: '',
+    DROPDOWN: '',
+    MULTISELECT_DROPDOWN: [],
+    DATE: '',
+    URL: '',
+    BOOLEAN: false,
+    SECRET: ''
+};
+/** Valid `type` strings for runtime checks. */
+exports.VALID_IPARAM_TYPES = Object.keys(exports.IPARAM_TYPE_VALUE_MAP);

package/dist/validator/iparam-constants.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Allowed top-level keys in `iparams.json`.
+ */
+export declare const IPARAMS_INSTALLATION_PARAMETERS_LABEL = "installation_parameters";
+export declare const IPARAMS_ROOT_ALLOWED_KEYS: readonly ["installation_parameters"];
+/**
+ * File name for iparam definitions in an app directory.
+ */
+export declare const IPARAMS_JSON_FILENAME = "iparams.json";
+/**
+ * Label for the `sections` array in validation error messages.
+ */
+export declare const IPARAMS_SECTIONS_LABEL = "sections";
+/**
+ * Allowed keys under `installation_parameters` in `iparams.json`.
+ */
+export declare const IPARAMS_INSTALLATION_PARAMETERS_ALLOWED_KEYS: readonly ["sections"];
+/**
+ * Maximum number of parameter definitions allowed in a single `iparams.json` array.
+ */
+export declare const IPARAMS_MAX_COUNT = 20;
+/**
+ * Central limits for iparam definition fields (`iparams.json`).
+ */
+export declare const IPARAM_DEFN_MAX_LENGTHS: {
+    readonly NAME: 50;
+    readonly DISPLAY_NAME: 50;
+    readonly DESCRIPTION: 250;
+};
+/**
+ * Limits for DROPDOWN and MULTISELECT_DROPDOWN `options` arrays in definitions.
+ */
+export declare const OPTIONS_LIMITS: {
+    readonly MAX_COUNT: 20;
+    readonly MAX_OPTION_LENGTH: 250;
+};
+/**
+ * Max lengths for iparam input values when validating `iparams.local.json` / runtime inputs.
+ */
+export declare const IPARAM_VALUE_MAX_LENGTHS: {
+    readonly TEXT: 250;
+    readonly SECRET: 250;
+    readonly URL: 250;
+    readonly DATE: 10;
+};
+/**
+ * Allowed {@link URL#protocol} values for iparam type `URL`.
+ */
+export declare const IPARAM_URL_ALLOWED_PROTOCOLS: readonly ["http:", "https:"];

package/dist/validator/iparam-constants.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IPARAM_URL_ALLOWED_PROTOCOLS = exports.IPARAM_VALUE_MAX_LENGTHS = exports.OPTIONS_LIMITS = exports.IPARAM_DEFN_MAX_LENGTHS = exports.IPARAMS_MAX_COUNT = exports.IPARAMS_INSTALLATION_PARAMETERS_ALLOWED_KEYS = exports.IPARAMS_SECTIONS_LABEL = exports.IPARAMS_JSON_FILENAME = exports.IPARAMS_ROOT_ALLOWED_KEYS = exports.IPARAMS_INSTALLATION_PARAMETERS_LABEL = void 0;
+/**
+ * Allowed top-level keys in `iparams.json`.
+ */
+exports.IPARAMS_INSTALLATION_PARAMETERS_LABEL = 'installation_parameters';
+exports.IPARAMS_ROOT_ALLOWED_KEYS = [exports.IPARAMS_INSTALLATION_PARAMETERS_LABEL];
+/**
+ * File name for iparam definitions in an app directory.
+ */
+exports.IPARAMS_JSON_FILENAME = 'iparams.json';
+/**
+ * Label for the `sections` array in validation error messages.
+ */
+exports.IPARAMS_SECTIONS_LABEL = 'sections';
+/**
+ * Allowed keys under `installation_parameters` in `iparams.json`.
+ */
+exports.IPARAMS_INSTALLATION_PARAMETERS_ALLOWED_KEYS = [exports.IPARAMS_SECTIONS_LABEL];
+/**
+ * Maximum number of parameter definitions allowed in a single `iparams.json` array.
+ */
+exports.IPARAMS_MAX_COUNT = 20;
+/**
+ * Central limits for iparam definition fields (`iparams.json`).
+ */
+exports.IPARAM_DEFN_MAX_LENGTHS = {
+    NAME: 50,
+    DISPLAY_NAME: 50,
+    DESCRIPTION: 250
+};
+/**
+ * Limits for DROPDOWN and MULTISELECT_DROPDOWN `options` arrays in definitions.
+ */
+exports.OPTIONS_LIMITS = {
+    MAX_COUNT: 20,
+    MAX_OPTION_LENGTH: 250
+};
+/**
+ * Max lengths for iparam input values when validating `iparams.local.json` / runtime inputs.
+ */
+exports.IPARAM_VALUE_MAX_LENGTHS = {
+    TEXT: 250,
+    SECRET: 250,
+    URL: 250,
+    DATE: 10
+};
+/**
+ * Allowed {@link URL#protocol} values for iparam type `URL`.
+ */
+exports.IPARAM_URL_ALLOWED_PROTOCOLS = ['http:', 'https:'];

package/dist/validator/iparam-defns-validator.d.ts

@@ -0,0 +1,46 @@
+import { CBFileSystem } from '../node/file-system';
+import { IparamDefns } from '../types/common';
+/**
+ * Validator for iparamDefns
+ * Validates the sectioned iparams.json schema
+ */
+export declare class IparamDefnsValidator {
+    private fileSystem;
+    private inputsValidator;
+    constructor(fileSystem: CBFileSystem);
+    /**
+     * Validates and loads the iparamDefns from a file
+     * @param {string} path - Path to the iparams.json file
+     * @returns {IparamDefns} The validated iparamDefns
+     * @throws {Error} If the iparamDefns is invalid or cannot be read
+     */
+    validateAndGetIparamDefnsFile(path: string): IparamDefns;
+    /**
+     * Validates an iparamDefns object
+     * @param {IparamDefns} iparamDefns - The iparamDefns object to validate
+     * @throws {Error} If the iparamDefns is invalid
+     */
+    validate(iparamDefns: IparamDefns): void;
+    /**
+     * Validates a single section definition
+     * @param {any} section - The section definition to validate
+     * @param {number} index - The index of the section in the array (for error messages)
+     * @throws {Error} If the section is invalid
+     */
+    private validateSection;
+    /**
+     * Validates a single parameter definition
+     * @param {any} param - The parameter definition to validate
+     * @param {string} sectionName - Parent section name for error messages
+     * @param {number} index - The index of the parameter in the section (for error messages)
+     * @throws {Error} If the parameter is invalid
+     */
+    private validateParameter;
+    private requireNonEmptyStringField;
+    private rejectUnknownKeys;
+    private validateSectionName;
+    private validateParamName;
+    private validateType;
+    private validateOptions;
+    private validateDefaultValue;
+}