@reservamos/browser-analytics 0.1.4-alpha.9 → 0.2.0

package/src/init.ts

@@ -1,4 +1,6 @@
+import { setConfig as setApiConfig } from '@reservamos/js-api-client';
 import { z } from 'zod';
+import configService from '@/services/config';
 import fingerprintService from '@/services/fingerprint';
 import mixpanelService from '@/services/mixpanel';
 import validator, { InitConfigSchema } from './services/validator';
@@ -26,17 +28,32 @@ function onLoaded() {
 export async function init(config: InitConfig) {
   validator.parseInitProps(config);
 
-  const { mixpanelToken, debug = false, identificationKey } = config;
+  const {
+    mixpanelToken,
+    debug = false,
+    identificationKey,
+    isSandbox = false,
+    mixpanelProxyUrl,
+    identifyProxyUrl,
+  } = config;
 
-  await mixpanelService.init(mixpanelToken, debug);
+  await mixpanelService.init(mixpanelToken, debug, mixpanelProxyUrl);
 
   // Only mixpanel is required to be ready to dispatch the 'Tracker Ready' event
   try {
-    await fingerprintService.initFingerprint(identificationKey);
+    await fingerprintService.initFingerprint(
+      identificationKey,
+      identifyProxyUrl,
+    );
   } catch (error) {
     console.error('Error initializing identification service:', error);
   }
 
+  const environment = isSandbox ? 'sandbox' : 'prod';
+  const apiConfig = configService.coreAPIConfig[environment];
+
+  setApiConfig(apiConfig);
+
   // Dispatch the 'Tracker Ready' event
   onLoaded();
 }

package/src/js-api-client.d.ts

@@ -0,0 +1,15 @@
+declare module '@reservamos/js-api-client' {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export const core: any; // Replace 'any' with a more specific type if possible
+
+  interface ConfigOptions {
+    coreUrl: string;
+    coreVersion?: string;
+    withCredentials?: boolean;
+    headers?: {
+      Origin?: string;
+    };
+  }
+
+  export function setConfig(options: ConfigOptions): void;
+}

package/src/profiles/createAnonymousProfile/createAnonymousProfile.test.ts

@@ -0,0 +1,38 @@
+/**
+ * Tests for the createAnonymousProfile method.
+ * Cases:
+ * - Should not throw an error if the payload is invalid
+ * - Should not throw an error if the payload is valid but the API call fails.
+ */
+
+import type { CreateAnonymousProfileProps } from './createAnonymousProfileSchema';
+import { describe, expect, it } from 'vitest';
+import validatorService from '@/services/validator';
+import createAnonymousProfile from './createAnonymousProfile';
+import CreateAnonymousProfileSchema from './createAnonymousProfileSchema';
+
+describe('createAnonymousProfile', () => {
+  it('should not throw an error if the payload is invalid', async () => {
+    const invalidPayload = {};
+    expect(() =>
+      validatorService.validateProps(
+        invalidPayload,
+        CreateAnonymousProfileSchema,
+      ),
+    ).toThrow();
+    await expect(createAnonymousProfile(invalidPayload)).resolves.not.toThrow();
+  });
+
+  it('should not throw an error if the payload is valid but the API call fails', async () => {
+    const validPayload: CreateAnonymousProfileProps = {
+      email: 'test@test.com',
+    };
+    expect(() =>
+      validatorService.validateProps(
+        validPayload,
+        CreateAnonymousProfileSchema,
+      ),
+    ).not.toThrow();
+    await expect(createAnonymousProfile(validPayload)).resolves.not.toThrow();
+  });
+});

package/src/profiles/createAnonymousProfile/createAnonymousProfile.ts

@@ -0,0 +1,78 @@
+import type { CreateAnonymousProfileProps } from './createAnonymousProfileSchema';
+import { core as coreApi } from '@reservamos/js-api-client';
+import fingerprintService from '@/services/fingerprint';
+import mixpanelService from '@/services/mixpanel';
+import validatorService from '@/services/validator';
+import CreateAnonymousProfileSchema from './createAnonymousProfileSchema';
+
+type IdentifierKey = 'phone' | 'email';
+
+interface AnonymousProfilePayload {
+  identifier_key: IdentifierKey;
+  identifier_value: string;
+  details: Record<string, string | number | boolean>;
+}
+
+/**
+ * Transforms the identifier object based on the provided values.
+ * @param {CreateAnonymousProfileProps} values - The values to transform.
+ * @returns {AnonymousProfilePayload} The transformed identifier object.
+ */
+function getAnonymousProfilePayload(
+  values: CreateAnonymousProfileProps,
+): AnonymousProfilePayload {
+  let identifier_key: IdentifierKey = 'phone';
+  let identifier_value: string = values.phone || '';
+  const details: Record<string, string | number | boolean> = {};
+
+  if (values.email) {
+    identifier_key = 'email';
+    identifier_value = values.email;
+  }
+
+  Object.entries(values).forEach(([key, value]) => {
+    if (key !== 'email' && key !== identifier_key && value !== undefined) {
+      details[key] = value as string | number | boolean;
+    }
+  });
+
+  return {
+    identifier_key,
+    identifier_value,
+    details,
+  };
+}
+
+interface AnonymousIdentifier {
+  key: string;
+  value: string;
+}
+
+/**
+ * Creates an anonymous profile using the provided payload.
+ * @param {CreateAnonymousProfileProps} payload - The payload to create the anonymous profile.
+ * @returns {Promise<void>} - A promise that resolves when the anonymous profile is created.
+ */
+async function createAnonymousProfile(
+  payload: CreateAnonymousProfileProps,
+): Promise<void> {
+  try {
+    validatorService.validateProps(payload, CreateAnonymousProfileSchema);
+
+    const identifiers: AnonymousIdentifier[] = [];
+    const userFingerprintId = fingerprintService.getCachedFingerprint();
+    const distinctId = mixpanelService.getMixpanelDistinctId();
+
+    if (userFingerprintId)
+      identifiers.push({ key: 'fingerprint_id', value: userFingerprintId });
+    if (distinctId) identifiers.push({ key: 'distinct_id', value: distinctId });
+
+    const dataPayload = getAnonymousProfilePayload(payload);
+
+    await coreApi.createAnonymousProfile({ ...dataPayload, identifiers });
+  } catch (error) {
+    console.error('Could not create anonymous profile:', error);
+  }
+}
+
+export default createAnonymousProfile;

package/src/profiles/createAnonymousProfile/createAnonymousProfileSchema.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+const CreateAnonymousProfileSchema = z
+  .object({
+    email: z.string().email().optional(),
+    phone: z.string().optional(),
+  })
+  .refine((data) => data.email || data.phone, {
+    message: "At least one of 'email' or 'phone' must be provided",
+  });
+
+type CreateAnonymousProfileProps = z.infer<typeof CreateAnonymousProfileSchema>;
+
+export type { CreateAnonymousProfileProps };
+export default CreateAnonymousProfileSchema;

package/src/profiles/createAnonymousProfile/index.ts

@@ -0,0 +1,5 @@
+import type { CreateAnonymousProfileProps } from './createAnonymousProfileSchema';
+import createAnonymousProfile from './createAnonymousProfile';
+
+export type { CreateAnonymousProfileProps };
+export default createAnonymousProfile;

package/src/services/config.ts

@@ -0,0 +1,24 @@
+const origin = window.location.origin;
+
+const coreAPIConfig = {
+  sandbox: {
+    coreUrl: 'https://datalake-api-dev.reservamossaas.com/api',
+    coreVersion: 'v1',
+    headers: {
+      Origin: origin,
+    },
+  },
+  prod: {
+    coreUrl: 'https://datalake-api-dev.reservamossaas.com/api',
+    coreVersion: 'v1',
+    headers: {
+      Origin: origin,
+    },
+  },
+};
+
+const configService = {
+  coreAPIConfig,
+};
+
+export default configService;

package/src/services/fingerprint.ts

@@ -1,4 +1,7 @@
-import { FpjsClient } from '@fingerprintjs/fingerprintjs-pro-spa';
+import {
+  FingerprintJSPro,
+  FpjsClient,
+} from '@fingerprintjs/fingerprintjs-pro-spa';
 
 declare global {
   interface Window {
@@ -6,12 +9,15 @@ declare global {
     fingerprintConfig: {
       cacheName?: string;
       cacheTimeInDays?: number;
+      proxyUrl?: string;
     };
   }
 }
 
 const DEFAULT_CACHE_NAME = 'default_fingerprint_cache';
 const DEFAULT_CACHE_TIME_IN_DAYS = 7;
+const PROXY_QUERY_PARAM =
+  'apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>';
 
 /**
  * Calculates the expiration date based on the cache time.
@@ -62,17 +68,46 @@ const setCachedFingerprint = (fingerprint: string): void => {
   localStorage.setItem(cacheName, JSON.stringify(cacheData));
 };
 
+/**
+ * Builds a proxy URL by appending a query parameter to the given URL.
+ *
+ * This function takes a base URL and appends a predefined query parameter
+ * to create a proxy URL. The query parameter is defined by the constant
+ * PROXY_QUERY_PARAM, which should be declared elsewhere in the file.
+ * @param {string} url - The base URL to which the proxy query parameter will be appended.
+ * @returns {string} The constructed proxy URL with the appended query parameter.
+ */
+function buildProxyUrl(url: string) {
+  return `${url}?${PROXY_QUERY_PARAM}`;
+}
+
 /**
  * Initializes identification service with the provided API key and stores the instance in the window object.
  * @param {string} apiKey - The API key for Fingerprint.js.
+ * @param {string} proxyUrl - Optional proxy URL for Fingerprint.js requests.
  * @returns {Promise<void>} A promise that resolves when initialization is complete.
  * @throws {Error} Throws an error if initialization fails.
  */
-async function initFingerprint(apiKey: string): Promise<void> {
+async function initFingerprint(
+  apiKey: string,
+  proxyUrl?: string,
+): Promise<void> {
+  const customEndpointArray = [FingerprintJSPro.defaultEndpoint];
+
+  const customScriptEndpointArray = [FingerprintJSPro.defaultScriptUrlPattern];
+
+  if (proxyUrl) {
+    // @ts-expect-error - This is a valid operation but fingerprintjs-pro-spa types are incorrect
+    customEndpointArray.unshift(proxyUrl);
+    customScriptEndpointArray.unshift(buildProxyUrl(proxyUrl));
+  }
+
   window.fingerprintConfig = {};
   window.fpClient = new FpjsClient({
     loadOptions: {
       apiKey,
+      endpoint: customEndpointArray,
+      scriptUrlPattern: customScriptEndpointArray,
     },
   });
 
@@ -134,6 +169,7 @@ const fingerprintService = {
   initFingerprint,
   getFingerprint,
   isFingerprintReady,
+  getCachedFingerprint,
 };
 
 export default fingerprintService;

package/src/services/mixpanel.ts

@@ -10,9 +10,14 @@ declare global {
  * 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.
+ * @param {string} proxyUrl - Optional proxy URL for Mixpanel requests.
  * @returns {Promise<void>} A promise that resolves when Mixpanel is initialized.
  */
-function init(mixpanelToken: string, debug = false): Promise<void> {
+function init(
+  mixpanelToken: string,
+  debug = false,
+  proxyUrl?: string,
+): Promise<void> {
   return new Promise<void>((resolve) => {
     mixpanel.init(mixpanelToken, {
       debug,
@@ -20,6 +25,7 @@ function init(mixpanelToken: string, debug = false): Promise<void> {
         window.mixpanel = mixpanel;
         resolve();
       },
+      ...(proxyUrl && { api_host: proxyUrl }),
     });
   });
 }
@@ -78,12 +84,26 @@ function track(eventName: string, properties: Record<string, unknown>): void {
   mixpanel.track(eventName, properties);
 }
 
+/**
+ * Retrieves the distinct ID from Mixpanel.
+ * This function checks if Mixpanel is initialized and returns the current user's
+ * distinct ID. If Mixpanel is not initialized, it returns null.
+ * @returns {string | null} The distinct ID if available, or null if Mixpanel is not initialized.
+ */
+export const getMixpanelDistinctId = (): string | null => {
+  if (mixpanel && mixpanel.get_distinct_id) {
+    return mixpanel.get_distinct_id();
+  }
+  return null;
+};
+
 const mixpanelService = {
   init,
   isReady,
   track,
   identify,
   attachProperty,
+  getMixpanelDistinctId,
 };
 
 export default mixpanelService;

package/src/services/validator.ts

@@ -1,4 +1,5 @@
 import { z, ZodError, ZodSchema } from 'zod';
+import { customEventSchema } from '@/events/customEvent/customEventSchema';
 import IdentifySchema from '@/events/identify/identifySchema';
 import { interestInHomeSchema } from '@/events/interestInHome';
 import { interestInSearchSchema } from '@/events/interestInSearch';
@@ -25,6 +26,19 @@ export const InitConfigSchema = z.object({
    * Key for tracking user identities.
    */
   identificationKey: z.string().min(1, 'Identification key is required'),
+  /**
+   * Optional flag to determine if the sandbox environment should be used.
+   * When set to true, the sandbox environment will be used; otherwise, the production environment will be used.
+   */
+  isSandbox: z.boolean().optional().default(false),
+  /**
+   * Optional proxy URL for Mixpanel requests.
+   */
+  mixpanelProxyUrl: z.string().optional(),
+  /**
+   * Optional proxy URL for identify requests.
+   */
+  identifyProxyUrl: z.string().optional(),
 });
 interface CustomError {
   field: string;
@@ -82,16 +96,18 @@ const eventSchemas: Record<string, z.ZodSchema> = {
   'Picked Departure': pickedDepartureSchema,
 };
 
-type EventData = z.infer<(typeof eventSchemas)[keyof typeof eventSchemas]>;
+type EventDataSchema = z.infer<
+  (typeof eventSchemas)[keyof typeof eventSchemas]
+>;
 
 /**
  * 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.
+ * @param {EventDataSchema} eventData - The data of the event to validate.
  * @throws {Error} - Throws an error if validation fails.
  */
-function parseEventProps(eventName: string, eventData: EventData): void {
-  const eventSchema = eventSchemas[eventName];
+function parseEventProps(eventName: string, eventData: EventDataSchema): void {
+  const eventSchema = eventSchemas[eventName] || customEventSchema;
 
   if (!eventSchema) {
     throw { message: `Event ${eventName} not found` };
@@ -148,6 +164,7 @@ const validatorService = {
   parseEventProps,
   parseInitProps,
   parseIdentifyProps,
+  validateProps,
 };
 
 // Export the validator object

package/src/track.ts

@@ -1,22 +1,55 @@
 import fingerprintService from '@/services/fingerprint';
 import mixpanelService from '@/services/mixpanel';
 import validator from '@/services/validator';
+import EventData, { AllowedPrimitive } from './types/eventData';
 
 /**
- * List of events that trigger the fingerprint to be sent with the event. other eventes will only fetch the cached fingerprint.
+ * List of events that trigger the fingerprint to be sent with the event. other events will only fetch the cached fingerprint.
  */
-const FP_TRIGGER_EVENTS = ['Track Test', 'Search', 'View Results'];
+const FP_TRIGGER_EVENTS = ['Search', 'View Results'];
+
+/**
+ * Simplifies the structure of event data by flattening nested objects and arrays.
+ * @param {object} data - The event data to simplify.
+ * @returns {EventData} - The flattened event data.
+ */
+function flattenEventData(data: object): EventData {
+  return Object.entries(data).reduce((flattenedData, [key, value]) => {
+    if (!Array.isArray(value)) {
+      flattenedData[key] = value as AllowedPrimitive;
+      return flattenedData;
+    }
+
+    value.forEach((item) => {
+      if (typeof item !== 'object' || item === null) return;
+
+      Object.entries(item).forEach(([innerKey, innerValue]) => {
+        if (!flattenedData[innerKey]) {
+          flattenedData[innerKey] = [innerValue as AllowedPrimitive];
+        } else {
+          (flattenedData[innerKey] as AllowedPrimitive[]).push(
+            innerValue as AllowedPrimitive,
+          );
+        }
+      });
+    });
+
+    return flattenedData;
+  }, {} as EventData);
+}
 
 /**
  * Base function to track events with Mixpanel.
  * This function adds default properties like User Fingerprint.
  * @param {string} eventName - The name of the event to track.
  * @param {object} eventProperties - The properties of the event to track.
+ * @param {EventData} meta - Additional metadata to include in the event.
  * @throws {Error} Throws an error if Mixpanel or Fingerprint is not ready.
  */
 export async function trackEvent(
   eventName: string,
   eventProperties: object,
+  meta: EventData = {},
 ): Promise<void> {
   if (!mixpanelService.isReady()) {
     throw new Error('Mixpanel is not initialized.');
@@ -31,14 +64,15 @@ export async function trackEvent(
       'User Fingerprint': fingerprint,
     };
 
+    const simplifiedData = flattenEventData(eventProperties);
     const properties = {
       ...defaultProperties,
-      ...eventProperties,
+      ...simplifiedData,
+      ...meta,
     };
 
     mixpanelService.track(eventName, properties);
   } catch (error) {
-    console.error('Error tracking event:', error);
-    throw error;
+    console.error(`Error tracking event '${eventName}':`, error);
   }
 }

package/src/types/eventData.ts

@@ -0,0 +1,5 @@
+export type AllowedPrimitive = string | boolean | number | undefined;
+
+type EventData = Record<string, AllowedPrimitive | AllowedPrimitive[]>;
+
+export default EventData;

package/src/util/primitiveFields.ts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import dateValidation from '@/util/dateValidation';
+
+/**
+ * Creates a Zod schema for a string field with a custom error message.
+ * @param {string} fieldName - The name of the field to be validated.
+ * @returns {z.ZodEffects<z.ZodString, string, string>} A Zod schema for string validation.
+ */
+export const stringField = (fieldName: string) =>
+  z.string().refine((val) => val, {
+    message: `${fieldName} must be a string`,
+  });
+
+/**
+ * Creates a Zod schema for a number field with a custom error message.
+ * @param {string} fieldName - The name of the field to be validated.
+ * @returns {z.ZodEffects<z.ZodNumber, number, number>} A Zod schema for number validation.
+ */
+export const numberField = (fieldName: string) =>
+  z.number().refine((val) => val, {
+    message: `${fieldName} must be a number`,
+  });
+
+/**
+ * Creates a Zod schema for an integer field with a custom error message.
+ * @param {string} fieldName - The name of the field to be validated.
+ * @returns {z.ZodEffects<z.ZodNumber, number, number>} A Zod schema for integer validation.
+ */
+export const intField = (fieldName: string) =>
+  z
+    .number()
+    .int()
+    .refine((val) => val, {
+      message: `${fieldName} must be an integer`,
+    });
+
+/**
+ * Creates a Zod schema for a date field with custom validation and error message.
+ * @param {string} fieldName - The name of the field to be validated.
+ * @returns {z.ZodEffects<z.ZodString, string, string>} A Zod schema for date validation.
+ */
+export const dateField = (fieldName: string) =>
+  z.string().refine(dateValidation, {
+    message: `Invalid ${fieldName} datetime format`,
+  });
+
+/**
+ * Creates a Zod schema for an array field with a custom schema and optional minimum length.
+ * @param {z.ZodType<T>} schema - The Zod schema to be applied to each array element.
+ * @param {string} fieldName - The name of the field to be validated.
+ * @param {number} [minLength] - The optional minimum length of the array.
+ * @returns {z.ZodArray<z.ZodType<T>>} A Zod schema for array validation.
+ * @template T
+ */
+export const arrayField = <T>(
+  schema: z.ZodType<T>,
+  fieldName: string,
+  minLength?: number,
+) => {
+  const arraySchema = z.array(schema);
+
+  if (minLength !== undefined) {
+    return arraySchema.min(
+      minLength,
+      `${fieldName} must have at least ${minLength} items`,
+    );
+  }
+
+  return arraySchema;
+};