@reservamos/browser-analytics 0.1.1 → 0.1.4-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reservamos/browser-analytics",
-  "version": "0.1.1",
+  "version": "0.1.4-alpha.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/reservamos/reservamos-browser-analytics.git"

package/src/events/identify/identify.ts

@@ -0,0 +1,85 @@
+import validatorService from '@/services/validator';
+import fingerprintService from '../../services/fingerprint';
+import mixpanelService from '../../services/mixpanel';
+import { DefaultProperties } from './identifySchema';
+
+const KNOWN_PROPERTIES = ['firstName', 'lastName', 'email', 'phone'];
+const FINGERPRINT_PROPERTY = 'Known Fingerprints';
+
+export interface UserProperties
+  extends DefaultProperties,
+    Record<string, string | number | boolean | undefined> {}
+
+/**
+ * Maps user properties to a format compatible with Mixpanel's expected structure.
+ *
+ * This function takes a UserProperties object and transforms it into a Record
+ * where known properties are mapped to Mixpanel's specific keys (e.g., $first_name),
+ * and any additional properties are included as-is.
+ * @param {UserProperties} properties - The user properties to be mapped.
+ * @returns {Record<string, unknown>} A new object with mapped properties.
+ * @example
+ * const userProps = { firstName: 'John', lastName: 'Doe', age: 30 };
+ * const mappedProps = mapProperties(userProps);
+ * // Returns: { $first_name: 'John', $last_name: 'Doe', age: 30 }
+ */
+function mapProperties(properties: UserProperties): Record<string, unknown> {
+  const parsedProperties = {
+    $first_name: properties?.firstName,
+    $last_name: properties?.lastName,
+    $email: properties?.email,
+    $phone: properties?.phone,
+  };
+
+  const additionalProperties = Object.keys(properties).reduce(
+    (acc, key) => {
+      if (!KNOWN_PROPERTIES.includes(key)) {
+        acc[key] = properties[key];
+      }
+      return acc;
+    },
+    {} as Record<string, unknown>,
+  );
+
+  return { ...parsedProperties, ...additionalProperties };
+}
+
+/**
+ * Identifies a user with given properties and fingerprint.
+ * @param {string} userId - The unique identifier for the user.
+ * @param {UserProperties} properties - Optional user properties.
+ * @throws {Error} If analytics service is not initialized or userId is missing.
+ * @returns {Promise<void>}
+ */
+export async function identify(
+  userId: string,
+  properties: UserProperties = {},
+): Promise<void> {
+  if (!mixpanelService.isReady()) {
+    throw new Error('Analytics service is not initialized');
+  }
+
+  const validationResults = validatorService.parseIdentifyProps(properties);
+
+  if (validationResults.status === 'error') {
+    throw validationResults;
+  }
+
+  if (!userId) {
+    throw new Error('User ID is required');
+  }
+
+  const mappedProps = mapProperties(properties);
+
+  mixpanelService.identify(userId, mappedProps);
+
+  try {
+    const fingerprint = await fingerprintService.getFingerprint();
+
+    if (fingerprint) {
+      mixpanelService.attachProperty(FINGERPRINT_PROPERTY, fingerprint);
+    }
+  } catch (error) {
+    console.error('Error attaching fingerprint:', error);
+  }
+}

package/src/events/identify/identifySchema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+const IdentifySchema = z.object({
+  firstName: z.string().optional(),
+  lastName: z.string().optional(),
+  email: z.string().email().optional(),
+  phone: z
+    .string()
+    .regex(/^\+?[1-9]\d{1,14}$/)
+    .optional(),
+});
+
+export type DefaultProperties = z.infer<typeof IdentifySchema>;
+
+export default IdentifySchema;

package/src/events/identify/index.ts

@@ -0,0 +1,3 @@
+import { identify } from './identify';
+
+export default identify;

package/src/events/test/index.ts

@@ -0,0 +1,3 @@
+import trackTest from './trackTest';
+
+export default trackTest;

package/src/events/{trackTest.ts → test/trackTest.ts}

@@ -1,10 +1,12 @@
-import { trackEvent } from '../track';
+import { trackEvent } from '@/track';
 
 const EVENT_NAME = 'Track Test';
 
 /**
   First test event to track, it purpose is to test the tracking library and the identification service.ws
  */
-export function trackTest() {
+function trackTest() {
   trackEvent(EVENT_NAME, {});
 }
+
+export default trackTest;

package/src/index.ts

@@ -1,12 +1,13 @@
-import { trackTest } from './events/trackTest';
-import { init } from './init';
+import identify from '@/events/identify';
+import trackTest from '@/events/test';
+import { init } from '@/init';
 
-export { init } from './init';
-export { trackTest } from './events/trackTest';
-
-const tracker = {
+const analytics = {
   init,
-  trackTest,
+  identify,
+  track: {
+    test: trackTest,
+  },
 };
 
-export default tracker;
+export default analytics;

package/src/init.ts

@@ -1,9 +1,7 @@
 import { z } from 'zod';
-import validator, {
-  InitConfigSchema,
-} from './events/event_schema/validationSchema';
-import { initFingerprint } from './fingerprint'; // Import the new fingerprint initialization function
-import { initMixpanel, isMixpanelReady } from './mixpanel'; // Import Mixpanel functions
+import fingerprintService from '@/services/fingerprint';
+import mixpanelService from '@/services/mixpanel';
+import validator, { InitConfigSchema } from './services/validator';
 
 /**
  * Configuration object for initializing the tracking library.
@@ -30,11 +28,11 @@ export async function init(config: InitConfig) {
 
   const { mixpanelToken, debug = false, identificationKey } = config;
 
-  await initMixpanel(mixpanelToken, debug);
+  await mixpanelService.init(mixpanelToken, debug);
 
   // Only mixpanel is required to be ready to dispatch the 'Tracker Ready' event
   try {
-    await initFingerprint(identificationKey);
+    await fingerprintService.initFingerprint(identificationKey);
   } catch (error) {
     console.error('Error initializing identification service:', error);
   }
@@ -50,5 +48,5 @@ export async function init(config: InitConfig) {
  * @returns {boolean} Returns true if the Mixpanel tracker is ready, otherwise false.
  */
 export function isTrackerReady(): boolean {
-  return isMixpanelReady();
+  return mixpanelService.isReady();
 }

package/src/{fingerprint.ts → services/fingerprint.ts}

@@ -68,7 +68,7 @@ const setCachedFingerprint = (fingerprint: string): void => {
  * @returns {Promise<void>} A promise that resolves when initialization is complete.
  * @throws {Error} Throws an error if initialization fails.
  */
-export async function initFingerprint(apiKey: string): Promise<void> {
+async function initFingerprint(apiKey: string): Promise<void> {
   window.fingerprintConfig = {};
   window.fpClient = new FpjsClient({
     loadOptions: {
@@ -90,7 +90,7 @@ export async function initFingerprint(apiKey: string): Promise<void> {
  * @returns {Promise<string>} A promise that resolves with the fingerprint.
  * @throws {Error} Throws an error if retrieval fails.
  */
-export async function getFingerprint(cacheOnly = false): Promise<string> {
+async function getFingerprint(cacheOnly = false): Promise<string> {
   if (!window.fingerprintConfig) {
     throw new Error('Fingerprint configuration is not initialized.');
   }
@@ -126,6 +126,14 @@ export async function getFingerprint(cacheOnly = false): Promise<string> {
  * and is ready to use by checking if the `fpClient` instance exists on the window object.
  * @returns {boolean} Returns true if the identification service is ready, otherwise false.
  */
-export function isFingerprintReady(): boolean {
+function isFingerprintReady(): boolean {
   return window.fpClient !== undefined;
 }
+
+const fingerprintService = {
+  initFingerprint,
+  getFingerprint,
+  isFingerprintReady,
+};
+
+export default fingerprintService;

package/src/services/mixpanel.ts

@@ -0,0 +1,89 @@
+import mixpanel from 'mixpanel-browser';
+
+declare global {
+  interface Window {
+    mixpanel: typeof mixpanel;
+  }
+}
+
+/**
+ * Initializes Mixpanel with the provided token and debug flag.
+ * @param {string} mixpanelToken - The Mixpanel token used for authenticating API requests.
+ * @param {boolean} debug - Optional flag to enable or disable debug mode.
+ * @returns {Promise<void>} A promise that resolves when Mixpanel is initialized.
+ */
+function init(mixpanelToken: string, debug = false): Promise<void> {
+  return new Promise<void>((resolve) => {
+    mixpanel.init(mixpanelToken, {
+      debug,
+      loaded: () => {
+        window.mixpanel = mixpanel;
+        resolve();
+      },
+    });
+  });
+}
+
+/**
+ * Identifies a user in Mixpanel and sets their properties.
+ * @param {string} userId - The unique identifier for the user.
+ * @param {Record<string, unknown>} properties - An object containing user properties to be set.
+ * @returns {void}
+ * @throws {Error} If Mixpanel is not initialized (handled internally).
+ */
+function identify(userId: string, properties: Record<string, unknown>): void {
+  if (!isReady()) {
+    return;
+  }
+
+  mixpanel.identify(userId);
+  mixpanel.people.set(properties);
+}
+
+/**
+ * Appends a unique value to a property for the currently identified user in Mixpanel.
+ * If the property doesn't exist, it creates an array with the value.
+ * If the property exists, it adds the value only if it's not already present.
+ * @param {string} key - The name of the property to append to.
+ * @param {unknown} value - The value to append to the property.
+ * @throws {Error} If Mixpanel is not initialized (handled internally).
+ */
+function attachProperty(key: string, value: unknown): void {
+  if (!isReady()) {
+    return;
+  }
+
+  mixpanel.people.union(key, [value]);
+}
+
+/**
+ * Checks if the Mixpanel tracker is ready.
+ * @returns {boolean} Returns true if the Mixpanel tracker is ready, otherwise false.
+ */
+function isReady(): boolean {
+  return window.mixpanel !== undefined;
+}
+/**
+ * Tracks an event in Mixpanel with the given name and properties.
+ * @param {string} eventName - The name of the event to track.
+ * @param {Record<string, unknown>} properties - An object containing event properties.
+ * @returns {void}
+ * @throws {Error} If Mixpanel is not initialized (handled internally).
+ */
+function track(eventName: string, properties: Record<string, unknown>): void {
+  if (!isReady()) {
+    return;
+  }
+
+  mixpanel.track(eventName, properties);
+}
+
+const mixpanelService = {
+  init,
+  isReady,
+  track,
+  identify,
+  attachProperty,
+};
+
+export default mixpanelService;

package/src/services/validator.ts

@@ -0,0 +1,161 @@
+import { z, ZodError, ZodSchema } from 'zod';
+import IdentifySchema from '@/events/identify/identifySchema';
+
+const TrackTestEventSchema = z.object({}); // Allow empty object for track test event
+export const InitConfigSchema = z.object({
+  /**
+   * The Mixpanel token used for authenticating API requests.
+   */
+  mixpanelToken: z.string().min(1, 'Mixpanel token is required'),
+  /**
+   * Optional flag to enable or disable debug mode.
+   * When set to true, additional debug information will be logged.
+   */
+  debug: z.boolean().optional(),
+  /**
+   * Key for tracking user identities.
+   */
+  identificationKey: z.string().min(1, 'Identification key is required'),
+});
+interface CustomError {
+  field: string;
+  error_type: string;
+  expected: string;
+  received: string;
+  message: string;
+  suggestion: string;
+}
+// Error formatting
+const SchemaErrorFormatter = (error: ZodError): CustomError[] => {
+  return error.issues.map((issue) => {
+    console.log('issue==>', issue);
+    let error_type = 'INVALID_FIELD';
+    let expected = '';
+    let received = '';
+    let suggestion = '';
+
+    if (issue.code === 'invalid_type') {
+      error_type = 'TYPE_MISMATCH';
+      expected = issue.expected;
+      received = issue.received;
+      suggestion = `Expected ${expected} but received ${received}. Please provide a value of type ${expected}.`;
+    } else if (issue.code === 'too_small') {
+      error_type = 'VALUE_TOO_SMALL';
+      suggestion = `Increase the value to at least ${issue.minimum}.`;
+    } else if (issue.code === 'too_big') {
+      error_type = 'VALUE_TOO_BIG';
+      suggestion = `Reduce the value to no more than ${issue.maximum}.`;
+    } else {
+      error_type = 'INVALID_FIELD';
+      suggestion = `Ensure the field matches the expected format and value type.`;
+    }
+    return {
+      field: issue.path.join('.'),
+      error_type,
+      expected,
+      received,
+      message: issue.message,
+      suggestion,
+    };
+  });
+};
+
+// Mapping event names to Zod schemas
+const eventSchemas: Record<string, z.ZodSchema> = {
+  'Track Test': TrackTestEventSchema,
+};
+
+type EventData = z.infer<(typeof eventSchemas)[keyof typeof eventSchemas]>;
+
+export interface ValidationResult {
+  status: 'ok' | 'error';
+  message: string;
+  errors?: CustomError[];
+}
+
+/**
+ * Validates the event data against the predefined schema for the given event name.
+ * @param {string} eventName - The name of the event to validate.
+ * @param {EventData} eventData - The data of the event to validate.
+ * @returns {ValidationResult} - The result of the validation, including status and message.
+ */
+function parseEventProps(
+  eventName: string,
+  eventData: EventData,
+): ValidationResult {
+  const eventSchema = eventSchemas[eventName];
+
+  if (!eventSchema) {
+    return { status: 'error', message: `Event ${eventName} not found` };
+  }
+  // Validate schema normally if not an empty object
+  try {
+    eventSchema.parse(eventData);
+    return { status: 'ok', message: 'Schema is valid' };
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const errors = SchemaErrorFormatter(error);
+      return {
+        status: 'error',
+        message: 'Schema validation failed',
+        errors,
+      };
+    }
+    return { status: 'error', message: 'Unknown validation error' };
+  }
+}
+
+/**
+ * Generic function to validate properties against a given schema.
+ * @param {object} properties - The properties to validate.
+ * @param {ZodSchema} schema - The schema to validate against.
+ * @returns {ValidationResult} - The result of the validation, including status and message.
+ */
+function validateProps(
+  properties: object,
+  schema: ZodSchema,
+): ValidationResult {
+  try {
+    schema.parse(properties);
+    return { status: 'ok', message: 'Properties are valid' };
+  } catch (error) {
+    if (error instanceof ZodError) {
+      const errors = SchemaErrorFormatter(error);
+      return {
+        status: 'error',
+        message: 'Schema validation failed',
+        errors,
+      };
+    }
+    return { status: 'error', message: 'Unknown validation error' };
+  }
+}
+
+/**
+ * Validates the initialization properties.
+ * @param {object} initProps - The properties to validate for init.
+ * @returns {ValidationResult} - The result of the validation, including status and message.
+ */
+function parseInitProps(initProps: object): ValidationResult {
+  return validateProps(initProps, InitConfigSchema);
+}
+
+/**
+ * Validates the properties for user identification.
+ * @param {Record<string, unknown>} properties - The properties to validate for user identification.
+ * @returns {ValidationResult} - The result of the validation, including status and message.
+ */
+function parseIdentifyProps(
+  properties: Record<string, unknown>,
+): ValidationResult {
+  return validateProps(properties, IdentifySchema);
+}
+
+const validatorService = {
+  parseEventProps,
+  parseInitProps,
+  parseIdentifyProps,
+};
+
+// Export the validator object
+export default validatorService;

package/src/track.ts

@@ -1,7 +1,6 @@
-import mixpanel from 'mixpanel-browser';
-import validator from './events/event_schema/validationSchema';
-import { getFingerprint } from './fingerprint';
-import { isMixpanelReady } from './mixpanel';
+import fingerprintService from '@/services/fingerprint';
+import mixpanelService from '@/services/mixpanel';
+import validator from '@/services/validator';
 
 /**
  * List of events that trigger the fingerprint to be sent with the event. other eventes will only fetch the cached fingerprint.
@@ -19,7 +18,7 @@ export async function trackEvent(
   eventName: string,
   eventProperties: object,
 ): Promise<void> {
-  if (!isMixpanelReady()) {
+  if (!mixpanelService.isReady()) {
     throw new Error('Mixpanel is not initialized.');
   }
 
@@ -32,7 +31,7 @@ export async function trackEvent(
 
     const cacheOnly = !FP_TRIGGER_EVENTS.includes(eventName);
 
-    const fingerprint = await getFingerprint(cacheOnly);
+    const fingerprint = await fingerprintService.getFingerprint(cacheOnly);
     const defaultProperties = {
       'User Fingerprint': fingerprint,
     };
@@ -42,7 +41,7 @@ export async function trackEvent(
       ...eventProperties,
     };
 
-    mixpanel.track(eventName, properties);
+    mixpanelService.track(eventName, properties);
   } catch (error) {
     console.error('Error tracking event:', error);
     throw error;