vwo-fme-react-sdk 0.1.0

package/lib/logger/core/TransportManager.ts

@@ -0,0 +1,142 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { dynamic } from '../../types/Common';
+import { LogLevelEnum } from '../enums/LogLevelEnum';
+import { LogMessageBuilder } from '../LogMessageBuilder';
+import { Logger } from '../Logger';
+import { isFunction } from '../../utils/DataTypeUtil';
+
+enum LogLevelNumberEnum {
+  TRACE = 0,
+  DEBUG = 1,
+  INFO = 2,
+  WARN = 3,
+  ERROR = 4,
+}
+
+interface IlogTransport extends Logger {
+  transports: Array<Record<string, dynamic>>;
+  config: Record<string, dynamic>;
+
+  // Determines if a message should be logged based on the transport and configuration levels
+  shouldLog(transportLevel: string, configLevel: string): boolean;
+  // Logs a message at a specified level
+  log(level: string, message: string): void;
+}
+
+/**
+ * Manages logging transports and delegates logging messages to them based on configuration.
+ * Implements the IlogTransport interface.
+ */
+export class LogTransportManager implements IlogTransport {
+  transports: Array<Record<string, any>>;
+  config: Record<string, any>;
+
+  /**
+   * Initializes the manager with a configuration object.
+   * @param {Record<string, any>} config - Configuration settings for the log manager.
+   */
+  constructor(config: Record<string, any>) {
+    this.transports = [];
+    this.config = config;
+  }
+
+  /**
+   * Adds a new transport to the manager.
+   * @param {Record<string, any>} transport - The transport object to be added.
+   */
+  addTransport(transport: Record<string, any>): void {
+    this.transports.push(transport);
+  }
+
+  /**
+   * Determines if the log should be processed based on the transport and configuration levels.
+   * @param {string} transportLevel - The log level set for the transport.
+   * @param {string} configLevel - The log level set in the configuration.
+   * @returns {boolean} - Returns true if the log level is appropriate for logging, false otherwise.
+   */
+  shouldLog(transportLevel: string, configLevel: string): boolean {
+    // Default to the most specific level available
+    // transportLevel = transportLevel || configLevel || this.config.level;
+
+    const targetLevel = LogLevelNumberEnum[transportLevel.toUpperCase()];
+    const desiredLevel = LogLevelNumberEnum[(configLevel || this.config.level).toUpperCase()];
+
+    return targetLevel >= desiredLevel;
+  }
+
+  /**
+   * Logs a message at TRACE level.
+   * @param {string} message - The message to log.
+   */
+  trace(message: string): void {
+    this.log(LogLevelEnum.TRACE, message);
+  }
+
+  /**
+   * Logs a message at DEBUG level.
+   * @param {string} message - The message to log.
+   */
+  debug(message: string): void {
+    this.log(LogLevelEnum.DEBUG, message);
+  }
+
+  /**
+   * Logs a message at INFO level.
+   * @param {string} message - The message to log.
+   */
+  info(message: string): void {
+    this.log(LogLevelEnum.INFO, message);
+  }
+
+  /**
+   * Logs a message at WARN level.
+   * @param {string} message - The message to log.
+   */
+  warn(message: string): void {
+    this.log(LogLevelEnum.WARN, message);
+  }
+
+  /**
+   * Logs a message at ERROR level.
+   * @param {string} message - The message to log.
+   */
+  error(message: string): void {
+    this.log(LogLevelEnum.ERROR, message);
+  }
+
+  /**
+   * Delegates the logging of messages to the appropriate transports.
+   * @param {string} level - The level at which to log the message.
+   * @param {string} message - The message to log.
+   */
+  log(level: string, message: string): void {
+    for (let i = 0; i < this.transports.length; i++) {
+      const logMessageBuilder = new LogMessageBuilder(this.config, this.transports[i]);
+      const formattedMessage = logMessageBuilder.formatMessage(level, message);
+      if (this.shouldLog(level, this.transports[i].level)) {
+        if (this.transports[i].log && isFunction(this.transports[i].log)) {
+          // Use custom log handler if available
+          this.transports[i].log(level, message);
+        } else {
+          // Otherwise, use the default log method
+          this.transports[i][level](formattedMessage);
+        }
+      }
+    }
+  }
+}

package/lib/logger/enums/LogLevelEnum.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export enum LogLevelEnum {
+  TRACE = 'trace',
+  DEBUG = 'debug',
+  INFO = 'info',
+  WARN = 'warn',
+  ERROR = 'error',
+}

package/lib/logger/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export { LogManager, ILogManager } from './core/LogManager';
+export { LogLevelEnum } from './enums/LogLevelEnum';

package/lib/logger/transports/ConsoleTransport.ts

@@ -0,0 +1,85 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { LogLevelEnum } from '../enums/LogLevelEnum';
+import { Logger } from '../Logger';
+
+/**
+ * ConsoleTransport class implements the Logger interface to provide logging functionality.
+ * It outputs logs to the console based on the log level set in the configuration.
+ */
+export class ConsoleTransport implements Logger {
+  config: Record<string, any>; // Configuration object for the logger
+  level: string; // Current log level
+
+  /**
+   * Constructor initializes the ConsoleTransport with a configuration object.
+   * @param {Record<string, any>} config - Configuration settings for the logger, including 'level'.
+   */
+  constructor(config: Record<string, any> = {}) {
+    this.config = config; // Store the configuration
+    this.level = this.config.level; // Set the logging level from the configuration
+  }
+
+  /**
+   * Logs a trace message.
+   * @param {string} message - The message to log.
+   */
+  trace(message: string): void {
+    this.consoleLog(LogLevelEnum.TRACE, message);
+  }
+
+  /**
+   * Logs a debug message.
+   * @param {string} message - The message to log.
+   */
+  debug(message: string): void {
+    this.consoleLog(LogLevelEnum.DEBUG, message);
+  }
+
+  /**
+   * Logs an informational message.
+   * @param {string} message - The message to log.
+   */
+  info(message: string): void {
+    this.consoleLog(LogLevelEnum.INFO, message);
+  }
+
+  /**
+   * Logs a warning message.
+   * @param {string} message - The message to log.
+   */
+  warn(message: string): void {
+    this.consoleLog(LogLevelEnum.WARN, message);
+  }
+
+  /**
+   * Logs an error message.
+   * @param {string} message - The message to log.
+   */
+  error(message: string): void {
+    this.consoleLog(LogLevelEnum.ERROR, message);
+  }
+
+  /**
+   * Generic log function that logs messages to the console based on the log level.
+   * @param {string} level - The log level under which the message should be logged.
+   * @param {string} message - The message to log.
+   */
+  consoleLog(level: string, message: string): void {
+    console[level](message); // Use console's logging function dynamically based on the level
+  }
+}

package/lib/services/LoggerService.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * logger.ts - Global Logger Singleton
+ */
+import { LogManager } from '../logger/core/LogManager';
+
+let logger: LogManager | null = null;
+
+/**
+ * Initializes the global logger instance.
+ * This function should be called inside `VWOProvider` before logging is used anywhere in the application.
+ *
+ * @param {object} config - The logger configuration object.
+ * @param {object} config.logger - Optional logging configuration (e.g., log level, transports).
+ * @returns {void} No return value; initializes the logger instance.
+ */
+export function initLogger(config: any) {
+  if (!logger) {
+    logger = new LogManager(config.logger || {});
+  }
+}
+
+/**
+ * Retrieves the global logger instance.
+ * Ensures that `initLogger` has been called before attempting to use logging.
+ *
+ * @returns {LogManager} The global logger instance.
+ */
+export function getLogger(): LogManager {
+  if (!logger) {
+    logger = new LogManager({ level: 'error' });
+  }
+  return logger;
+}

package/lib/types/Common.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Defines a type `dynamic` which can be used to represent a variety of data types.
+ * This type is flexible and can handle multiple types including primitive types,
+ * complex objects, and collections.
+ */
+export type dynamic =
+  | boolean // Represents a boolean value
+  | number // Represents a numeric value
+  | string // Represents a string value
+  | Date // Represents a date object
+  | void // Represents the absence of a value
+  | undefined // Represents an undefined value
+  | null // Represents a null value
+  | Record<string, any> // Represents an object with string keys and any type of values
+  | Array<dynamicArray> // Represents an array of `dynamicArray` type
+  | Map<string, dynamicArray>; // Represents a map with string keys and `dynamicArray` type values
+
+/**
+ * Defines a type `dynamicArray` which is used within the `dynamic` type.
+ * This type is intended for use in arrays and supports several basic data types and objects.
+ */
+export type dynamicArray =
+  | boolean // Represents a boolean value
+  | number // Represents a numeric value
+  | string // Represents a string value
+  | Record<string, any>; // Represents an object with string keys and any type of values

package/lib/useGetFlag.ts

@@ -0,0 +1,81 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useState, useEffect, useMemo } from 'react';
+import { useVWOContext } from './VWOContext';
+import { getLogger } from './services/LoggerService';
+import { isObject } from './utils/DataTypeUtil';
+import { dynamic } from './types/Common';
+
+/**
+ * Hook to get a feature flag value
+ * @param featureKey - The key of the feature flag to get
+ * @returns The feature flag value
+ */
+export const useGetFlag = (featureKey: string) => {
+  // This is the return schema for the flag if the feature key is not found or the flag is not enabled
+  const errorReturnSchema = {
+    isEnabled: (): boolean => false,
+    getVariables: (): Array<Record<string, dynamic>> => [],
+    getVariable: (_key: string, defaultValue: any): dynamic => defaultValue,
+  };
+  const logger = getLogger();
+  try {
+    if (!featureKey) {
+      logger.error('Feature key is required for useGetFlag hook');
+      return errorReturnSchema;
+    }
+
+    const [flag, setFlag] = useState<any | null>(null);
+    const { vwoClient, userContext } = useVWOContext();
+
+    if (!vwoClient) {
+      logger.error('VWO Client is missing in useGetFlag hook. Ensure VWOProvider is correctly initialized.');
+      return errorReturnSchema;
+    }
+
+    if (!userContext || !isObject(userContext)) {
+      logger.error('Invalid user context in useGetFlag hook. Ensure a valid userContext is provided.');
+      return errorReturnSchema;
+    }
+
+    // Memoize the userContext to avoid unnecessary re-fetching
+    const stableUserContext = useMemo(() => userContext, [userContext]);
+
+    // Memoize the getFlag function to avoid re-creation
+    const getFlag = useMemo(() => {
+      return async () => {
+        try {
+          const result = await vwoClient.getFlag(featureKey, stableUserContext);
+          setFlag(result);
+        } catch (error) {
+          logger.error(`Error fetching feature flag "${featureKey}": ${error}`);
+          setFlag({});
+        }
+      };
+    }, [featureKey, vwoClient, stableUserContext]);
+
+    // Runs only when `getFlag` reference changes
+    useEffect(() => {
+      getFlag();
+    }, [getFlag]);
+
+    return flag;
+  } catch (error) {
+    logger.error(`Error getting feature flag: ${error}`);
+    return errorReturnSchema;
+  }
+};

package/lib/useGetFlagVariable.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { isObject } from './utils/DataTypeUtil';
+import { getLogger } from './services/LoggerService';
+
+/**
+ * Hook to get all variables from a flag
+ * @param flag - The flag to get the variables from
+ * @returns The variables from the flag
+ */
+export const useGetFlagVariables = (flag: any) => {
+  const logger = getLogger();
+  try {
+    if (!flag || !isObject(flag)) {
+      logger.error('Flag is required for useGetFlagVariables hook and should be an object');
+      return [];
+    }
+
+    return flag.getVariables();
+  } catch (error) {
+    logger.error(`Error getting flag variables: ${error}`);
+    return [];
+  }
+};
+
+/**
+ * Hook to get a flag variable
+ * @param flag - The flag to get the variable from
+ * @param variableKey - The key of the variable to get
+ * @param defaultValue - The default value to return if the variable is not found
+ * @returns The value of the variable
+ */
+export const useGetFlagVariable = (flag: any, variableKey: string, defaultValue: any) => {
+  const logger = getLogger();
+  try {
+    if (!flag || !isObject(flag)) {
+      logger.error('Flag is required for useGetFlagVariable hook and should be an object');
+      return [];
+    }
+
+    if (!flag || !variableKey) {
+      logger.error('Flag and variable key are required for useGetFlagVariable hook');
+      return defaultValue;
+    }
+
+    return flag.getVariable(variableKey, defaultValue);
+  } catch (error) {
+    logger.error(`Error getting flag variable: ${error}`);
+    return defaultValue;
+  }
+};

package/lib/useSetAttribute.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { useVWOContext } from './VWOContext';
+import { isObject } from './utils/DataTypeUtil';
+import { getLogger } from './services/LoggerService';
+
+/**
+ * Hook to set attributes for the user
+ * @param attributeMap - The map of attributes to set
+ */
+export const useSetAttribute = (attributeMap: Record<string, string>) => {
+  const logger = getLogger();
+  try {
+    if (!attributeMap || !isObject(attributeMap) || Object.keys(attributeMap).length === 0) {
+      logger.error(
+        'attributeMap(object having key-value pairs of user attributes) is required for useSetAttribute hook',
+      );
+      return;
+    }
+
+    // Fetch the vwoClient and userContext from the context
+    const { vwoClient, userContext } = useVWOContext();
+
+    if (!userContext || !isObject(userContext)) {
+      logger.error('Invalid user context in useSetAttribute hook. Ensure a valid userContext is provided.');
+      return {};
+    }
+
+    // Set the attributes
+    vwoClient.setAttribute(attributeMap, userContext);
+  } catch (error) {
+    logger.error(`Error setting attributes: ${error}`);
+  }
+};

package/lib/useTrackEvent.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { getLogger } from './services/LoggerService';
+import { useVWOContext } from './VWOContext';
+import { isObject, isString } from './utils/DataTypeUtil';
+
+/**
+ * Hook to track an event
+ * @param eventName - The name of the event to track
+ * @param eventProperties - The properties of the event to track (optional)
+ */
+export const useTrackEvent = (eventName: string, eventProperties: Record<string, string> = {}) => {
+  const logger = getLogger();
+  try {
+    if (!eventName && !isString(eventName)) {
+      logger.error('Event name is required for useTrackEvent hook and it should be a string');
+      return;
+    }
+
+    // Fetch the vwoClient and userContext from the context
+    const { vwoClient, userContext } = useVWOContext();
+
+    if (!vwoClient) {
+      logger.error('VWO Client is missing in useTrackEvent hook. Ensure VWOProvider is correctly initialized.');
+      return {};
+    }
+
+    if (!userContext || !isObject(userContext)) {
+      logger.error('Invalid user context in useTrackEvent hook. Ensure a valid userContext is provided.');
+      return {};
+    }
+
+    // Track the event
+    vwoClient.trackEvent(eventName, userContext, eventProperties);
+  } catch (error) {
+    logger.error(`Error tracking event: ${error}`);
+  }
+};

package/lib/useVWOClient.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright 2025 Wingify Software Pvt. Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { getLogger } from './services/LoggerService';
+import { useVWOContext } from './VWOContext';
+
+/**
+ * Returns the VWO SDK client instance
+ * @returns VWO SDK client instance
+ */
+export const useVWOClient = () => {
+  const logger = getLogger();
+  try {
+    const context = useVWOContext();
+
+    // If the VWO SDK client is not found, throw an error
+    if (!context || !context.vwoClient) {
+      logger.error('useVWOClient must be used within a VWOProvider !!');
+      return null;
+    }
+
+    // Return the VWO SDK client
+    return context.vwoClient;
+  } catch (error) {
+    logger.error(`Error in useVWOClient hook: ${error}`);
+    return null;
+  }
+};