@levi-gemcommerce/analytics 2.1.0-test.0 → 3.0.1-dev.3

package/src/types/metric.ts

@@ -0,0 +1,81 @@
+export enum EMetricKey {
+  SESSION = 'sessions',
+  ORDERS = 'orders',
+  PAGE_VIEWS = 'pageviews',
+  VISITORS = 'visitors',
+  BOUNCE_RATE = 'bounce_rate',
+  CTR = 'ctr',
+  CONVERSION_RATE = 'conversion_rate',
+  AVG_TIME_ON_PAGE = 'average_time_on_page',
+  ADDED_TO_CART = 'added_to_cart',
+  ADD_TO_CART_RATE = 'added_to_cart_rate',
+  REACHED_CHECKOUT = 'sessions_that_reached_checkout',
+  COMPLETE_CHECKOUT = 'sessions_that_completed_checkout',
+  CART_ADDITION = 'sessions_with_cart_additions',
+  AOV = 'aov',
+  REVENUE = 'revenue',
+  RPV = 'revenue_per_visitor',
+  VISITOR_ITEMS = 'visitor_items',
+  DEVICE_ITEMS = 'device_items',
+  TRAFFIC_SOURCE_ITEMS = 'traffic_source_items',
+  PAGE_PATH_ANALYSIS = 'PAGE_PATH_ANALYSIS',
+}
+
+export interface IMetricControl {
+  value: string | number | null;
+  change: string | number;
+}
+
+export interface IMetricCardItem {
+  key: EMetricKey;
+  title: string;
+  totalValue: IMetricControl;
+}
+
+export interface IAnalyticStat {
+  totalCount?: number | null;
+  type?: string | null;
+}
+
+export interface IAnalyticMetric {
+  date?: string | null;
+  totalAddedToCart?: number | null;
+  totalClicked?: number | null;
+  totalClickedHasHref?: number | null;
+  totalOrders?: number | null;
+  totalPageViewed?: number | null;
+  totalPageViewedHaveTimeOnPage?: number | null;
+  totalReachedCheckout?: number | null;
+  totalRevenue?: number | null;
+  totalSessions?: number | null;
+  totalSessionsThatCompletedCheckout?: number | null;
+  totalSessionsThatReachedAndCompletedCheckout?: number | null;
+  totalSessionsThatReachedCheckout?: number | null;
+  totalSessionsWithCartAdditions?: number | null;
+  totalSessionsWithoutAction?: number | null;
+  totalTimeOnPage?: number | null;
+  totalVisitors?: number | null;
+  channels?: Array<IAnalyticStat | null> | null;
+  devices?: Array<IAnalyticStat | null> | null;
+  visitors?: Array<IAnalyticStat | null> | null;
+  variantKey?: string;
+}
+
+export interface IBasePageAnalyticMetric {
+  totalPageViewed?: number | null;
+  totalVisitors?: number | null;
+  totalClicked?: number | null;
+  totalAddedToCart?: number | null;
+  totalReachedCheckout?: number | null;
+  totalOrders?: number | null;
+  totalSessions?: number | null;
+  totalSessionsThatCompletedCheckout?: number | null;
+  totalSessionsThatReachedCheckout?: number | null;
+  totalSessionsWithCartAdditions?: number | null;
+  totalClickedHasHref?: number | null;
+  totalSessionsWithoutAction?: number | null;
+  totalContinuationSession?: number | null;
+  totalRevenue?: number | null;
+  totalTimeOnPage?: number | null;
+  totalPageViewedHaveTimeOnPage?: number | null;
+}

package/src/types/pricing.ts

@@ -0,0 +1,38 @@
+/**
+ * Pricing enums mirrored from the host app (`~/modules/pricing/types`).
+ *
+ * They are duplicated here so the SDK no longer needs to import the host's
+ * pricing module directly. The host can import these enums back from
+ * `@gem-sdk/analytics/types` to build the value passed to `PathAnalysisConfigProvider`,
+ * which guarantees the string values stay in sync on both sides.
+ */
+
+export enum IPlanKey {
+  /**
+   * @deprecated This plan is available for users installed before release 1.3.0.
+   */
+  CONTENT_TESTING = 'content-testing',
+  PAGE_OPT = 'page-optimize',
+  FUNNEL_OPT = 'funnel-optimize',
+  PROFIT_OPT = 'profit-optimize',
+  // Trial plans
+  TRIAL_PAGE_OPT = 'trial-page-optimize',
+  TRIAL_FUNNEL_OPT = 'trial-funnel-optimize',
+  TRIAL_PROFIT_OPT = 'trial-profit-optimize',
+}
+
+export enum IShopPlanState {
+  TRIAL_PAGE_OPT = 'TRIAL_PAGE_OPT',
+  TRIAL_FUNNEL_OPT = 'TRIAL_FUNNEL_OPT',
+  TRIAL_PROFIT_OPT = 'TRIAL_PROFIT_OPT',
+  ACTIVE_PAGE_OPT = 'ACTIVE_PAGE_OPT',
+  ACTIVE_FUNNEL_OPT = 'ACTIVE_FUNNEL_OPT',
+  ACTIVE_PROFIT_OPT = 'ACTIVE_PROFIT_OPT',
+
+  LOADING_PLAN = 'LOADING_PLAN',
+  TRIAL_EXPIRED = 'TRIAL_EXPIRED',
+
+  ACTIVE_PAGE_OPT_AND_TRIAL_PAGE_OPT = 'ACTIVE_PAGE_OPT_AND_TRIAL_PAGE_OPT',
+  ACTIVE_PAGE_OPT_AND_TRIAL_FUNNEL_OPT = 'ACTIVE_PAGE_OPT_AND_TRIAL_FUNNEL_OPT',
+  ACTIVE_FUNNEL_OPT_AND_TRIAL_FUNNEL_OPT = 'ACTIVE_FUNNEL_OPT_AND_TRIAL_FUNNEL_OPT',
+}

package/src/types/report-columns.ts

@@ -0,0 +1 @@
+export { EReportColumnKey } from '../shared/reports/ui/ReportTable/types/report-columns';

package/src/types/template.ts

@@ -0,0 +1,19 @@
+export enum TemplateType {
+  ALL = 'all',
+  HOME = 'index',
+  COLLECTION = 'collection',
+  COLLECTION_LIST = 'collection-list',
+  PRODUCT = 'product',
+  ARTICLE = 'article',
+  PAGE = 'page',
+  CART = 'cart',
+  SEARCH = 'search',
+  NOT_FOUND = '404',
+  BLOG = 'blog',
+  PASSWORD = 'password',
+  CONTACT = 'contact',
+  GIF_CART = 'gif-cart',
+  ACCOUNT = 'account',
+  CHECKOUT = 'checkout',
+  GIFT_CARD = 'gift-card',
+}

package/src/utils/analytics.ts

@@ -0,0 +1,75 @@
+import { cleanDecimal } from '@/utils/number';
+import { dayjsTz } from '@/utils';
+
+export enum AnalyticInterval {
+  DAY = 'DAY',
+  HOUR = 'HOUR',
+  MONTH = 'MONTH',
+  QUARTER = 'QUARTER',
+  WEEK = 'WEEK',
+  YEAR = 'YEAR',
+}
+
+const SECONDS_IN_MINUTE = 60;
+const SECONDS_IN_HOUR = SECONDS_IN_MINUTE * SECONDS_IN_MINUTE;
+
+export const getTimeDurationLabel = (valueInSeconds: number): string => {
+  let data = valueInSeconds;
+  if (!Number.isFinite(valueInSeconds) || valueInSeconds == null) {
+    data = 0;
+  }
+
+  const fixedValue = cleanDecimal(data);
+  if (data >= SECONDS_IN_HOUR) {
+    const hours = Math.floor(data / SECONDS_IN_HOUR);
+    const minutes = Math.floor((data % SECONDS_IN_HOUR) / SECONDS_IN_MINUTE);
+    const seconds = Math.floor(data % SECONDS_IN_MINUTE);
+    return `${hours}h ${minutes}m ${seconds}s`;
+  } else if (data >= SECONDS_IN_MINUTE) {
+    const minutes = Math.floor(data / SECONDS_IN_MINUTE);
+    const seconds = Math.floor(data % SECONDS_IN_MINUTE);
+    return `${minutes}m ${seconds}s`;
+  } else {
+    return `${fixedValue}s`;
+  }
+};
+
+export const getFormattedByInterval = (
+  value: string | number | null,
+  interval?: AnalyticInterval,
+  options?: { isExpandDetail?: boolean },
+): string => {
+  if (!value) return '';
+
+  const optionFormat = options?.isExpandDetail
+    ? {
+        formatHouse: 'MMM D, h:mm A',
+        formatDay: 'MMM D, YYYY',
+        formatMonth: 'MMM YYYY',
+        formatYear: 'MMM YYYY',
+      }
+    : {
+        formatHouse: 'h A',
+        formatDay: 'MMM D',
+        formatMonth: 'MMM YYYY',
+        formatYear: 'YYYY',
+      };
+
+  switch (interval) {
+    case AnalyticInterval.HOUR:
+      return dayjsTz(value).format(optionFormat.formatHouse);
+    case AnalyticInterval.DAY:
+    case AnalyticInterval.WEEK:
+      return dayjsTz(value).format(optionFormat.formatDay);
+    case AnalyticInterval.MONTH:
+      return dayjsTz(value).format(optionFormat.formatMonth);
+    case AnalyticInterval.QUARTER: {
+      const d = dayjsTz(value);
+      return `Q${d.quarter()} ${d.format('YYYY')}`;
+    }
+    case AnalyticInterval.YEAR:
+      return dayjsTz(value).format(optionFormat.formatYear);
+  }
+
+  return dayjsTz(value).format(optionFormat.formatMonth);
+};

package/src/utils/array.ts

@@ -0,0 +1,13 @@
+export function findLastIndex<T>(
+  array: T[],
+  predicate: (value: T, index: number, array: T[]) => boolean,
+  thisArg?: unknown,
+): number {
+  for (let i = array.length - 1; i >= 0; i--) {
+    if (predicate.call(thisArg, array[i] as T, i, array)) {
+      return i;
+    }
+  }
+
+  return -1;
+}

package/src/utils/cls.ts

@@ -0,0 +1,18 @@
+type ClassDictionary = Record<string, boolean | undefined | null>;
+type ClassValue = ClassDictionary | string | null | undefined;
+
+function toVal(mix: ClassValue) {
+  if (typeof mix === 'string') {
+    return mix;
+  } else if (typeof mix === 'object' && mix !== null) {
+    return Object.keys(mix)
+      .filter((key) => mix[key])
+      .join(' ');
+  } else {
+    return false;
+  }
+}
+
+export function cls(...classes: ClassValue[]) {
+  return classes.map(toVal).filter(Boolean).join(' ');
+}

package/src/utils/currency.ts

@@ -0,0 +1,42 @@
+import { DEFAULT_CURRENCY_ANALYTIC } from '@/constants';
+
+export interface IGetPriceByCurrencyOptions {
+  locale?: string;
+  compact?: boolean;
+}
+
+export const getPriceByCurrency = (
+  price?: string | number | null,
+  currency: string = DEFAULT_CURRENCY_ANALYTIC,
+  options?: string | IGetPriceByCurrencyOptions,
+): string | undefined => {
+  if (typeof price === 'string') return price;
+  if (typeof price !== 'number') return;
+
+  // Support legacy 3rd arg as locale string
+  const opts = typeof options === 'string' ? { locale: options } : options;
+  const locale = opts?.locale ?? 'en-US';
+
+  // Currency's natural minimum (USD → 2, JPY/KRW/VND → 0); used as the floor for scaled tiers.
+  const currencyMinDigits =
+    new Intl.NumberFormat(locale, { style: 'currency', currency }).resolvedOptions().minimumFractionDigits ?? 0;
+
+  // For scaled tiers, allow extra precision but never force decimals on zero-decimal currencies.
+  const formatCurrency = (value: number, maxDigits?: number) =>
+    new Intl.NumberFormat(locale, {
+      style: 'currency',
+      currency,
+      ...(maxDigits != null && {
+        minimumFractionDigits: Math.min(currencyMinDigits, maxDigits),
+        maximumFractionDigits: maxDigits,
+      }),
+    }).format(value);
+
+  const magnitude = Math.abs(price);
+  if (magnitude >= 1_000_000_000) return `${formatCurrency(price / 1_000_000_000, 2)}B`;
+  if (magnitude >= 1_000_000) return `${formatCurrency(price / 1_000_000, 2)}M`;
+  if (opts?.compact && magnitude >= 1_000) return `${formatCurrency(price / 1_000, 1)}K`;
+
+  // Let Intl pick fraction digits per currency (e.g. JPY/KRW have 0) instead of hardcoding.
+  return formatCurrency(price);
+};

package/src/utils/date-time.ts

@@ -0,0 +1,7 @@
+import { dayjsTz } from './dayjs';
+
+export const formatDateBy = (format: string, date?: string | Date) => {
+  if (!date) date = new Date();
+
+  return dayjsTz(date).format(format) ?? '-';
+};

package/src/utils/dayjs.ts

@@ -0,0 +1,52 @@
+import type { ConfigType, Dayjs } from 'dayjs';
+
+import dayjs from 'dayjs';
+import quarterOfYear from 'dayjs/plugin/quarterOfYear.js';
+import timezone from 'dayjs/plugin/timezone.js';
+import utc from 'dayjs/plugin/utc.js';
+
+dayjs.extend(utc);
+dayjs.extend(timezone);
+dayjs.extend(quarterOfYear);
+
+// Stored on `globalThis` (not a module-local `let`): each entry-point bundle gets its
+// own copy of this module, so a local var would let `setTz` and the query builder read
+// different copies. A shared global slot keeps every bundle in sync.
+const TZ_GLOBAL_KEY = '__GEM_SDK_ANALYTICS_TZ__';
+
+type TzGlobal = typeof globalThis & { [TZ_GLOBAL_KEY]?: string };
+
+const DEFAULT_DATE_FORMAT = 'YYYY-MM-DD HH:mm:ss';
+
+export function getInitialTimezone(): string {
+  return (globalThis as TzGlobal)[TZ_GLOBAL_KEY] ?? 'UTC';
+}
+
+export function setTz(value: string) {
+  (globalThis as TzGlobal)[TZ_GLOBAL_KEY] = value;
+  dayjs.tz.setDefault(value);
+}
+
+export const dayjsTz = (date?: ConfigType) => {
+  const tz = getInitialTimezone();
+  if (!date) return dayjs().tz(tz);
+  return dayjs(date as Parameters<typeof dayjs>[0]).tz(tz);
+};
+
+export const convertDateToTz = (date?: ConfigType) => {
+  const tz = getInitialTimezone();
+  if (!date) return dayjs.tz(dayjs().format(DEFAULT_DATE_FORMAT), tz);
+  return dayjs.tz(dayjs(date as Parameters<typeof dayjs>[0]).format(DEFAULT_DATE_FORMAT), tz);
+};
+
+export const dayjsTzToLocalTZ = (date?: ConfigType) => {
+  if (!date) return dayjs(dayjsTz().format(DEFAULT_DATE_FORMAT));
+  return dayjs(dayjsTz(date).format(DEFAULT_DATE_FORMAT));
+};
+
+export const dayjsTzToDate = (date?: ConfigType) => {
+  return dayjsTzToLocalTZ(date).toDate();
+};
+
+export { dayjs };
+export type { Dayjs };

package/src/utils/deep-copy.ts

@@ -0,0 +1,4 @@
+export const deepCopy = <T>(obj: T): T => {
+  if (typeof obj !== 'object' || obj === null) return obj;
+  return structuredClone(obj);
+};

package/src/utils/index.ts

@@ -0,0 +1,12 @@
+export * from './number';
+export * from './percentage';
+export * from './cls';
+export * from './sort';
+export * from './dayjs';
+export * from './analytics';
+export * from './deep-copy';
+export * from './template-type';
+export * from './string';
+export * from './array';
+export * from './is-browser';
+export * from './date-time';

package/src/utils/is-browser.ts

@@ -0,0 +1,3 @@
+export const isBrowser = () => {
+  return typeof window !== 'undefined';
+};

package/src/utils/number.ts

@@ -0,0 +1,19 @@
+export const TRIM_DECIMAL_ZEROS_REGEX = /\.0+$/;
+export const DEFAULT_DECIMALS = 2;
+
+export const trimDecimalZeros = (number?: string): string => {
+  return `${number}`.replace(TRIM_DECIMAL_ZEROS_REGEX, '');
+};
+
+export const cleanDecimal = (number: number, decimals = DEFAULT_DECIMALS): string => {
+  return trimDecimalZeros(number.toFixed(decimals));
+};
+
+export const semverToNum = (v: string): number => {
+  const [major, minor, patch] = v.split('.').map((n) => Number(n));
+  return (major ?? 0) * 1_000_000 + (minor ?? 0) * 1_000 + (patch ?? 0);
+};
+
+export const numberWithCommas = (x: string | number): string => {
+  return x.toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+};

package/src/utils/percentage.ts

@@ -0,0 +1,40 @@
+/**
+ * Utility function to calculate percentage and format it.
+ * @param part - The part value.
+ * @param total - The total value.
+ * @param decimals - The number of decimal places to format the percentage to.
+ * @returns The formatted percentage as a string.
+ */
+
+import { DEFAULT_DECIMALS, cleanDecimal } from './number';
+
+const PERCENTAGE_THRESHOLD = 0.005;
+const PERCENTAGE_THRESHOLD_STRING = '~0%';
+export const calcPercentage = (part?: number, total?: number, decimals = DEFAULT_DECIMALS): number | undefined => {
+  if (typeof part !== 'number' || !total) return undefined;
+  if (part === 0) return 0;
+
+  const percentage = (part / total) * 100;
+
+  return parseFloat(cleanDecimal(percentage, decimals));
+};
+
+const isLessThanThreshold = (percentage: number) => percentage > 0 && percentage < PERCENTAGE_THRESHOLD;
+export const calcPercentageString = (part: number | undefined, total: number, decimals = 2): string | undefined => {
+  const percentage = calcPercentage(part, total, decimals);
+  if (typeof percentage !== 'number') return undefined;
+
+  if (isLessThanThreshold(percentage)) {
+    return PERCENTAGE_THRESHOLD_STRING;
+  }
+
+  return `${percentage}%`;
+};
+
+export const formatPercentage = (percentage: number, decimals = DEFAULT_DECIMALS): string => {
+  if (isLessThanThreshold(percentage)) {
+    return PERCENTAGE_THRESHOLD_STRING;
+  }
+
+  return `${cleanDecimal(percentage, decimals)}%`;
+};

package/src/utils/sort.ts

@@ -0,0 +1,87 @@
+export type SortOrder = 'asc' | 'desc';
+
+export interface SortOptions<T> {
+  attr: keyof T | string;
+  order?: SortOrder;
+  backupAttr?: keyof T;
+  preferredValue?: string | number | boolean;
+  orderArrayAttr?: keyof T;
+  orderArray?: Record<SortOrder, string[]>;
+}
+
+export function compareValues(a: unknown, b: unknown, order: SortOrder = 'asc'): number {
+  if (a === b) return 0;
+
+  if (a === undefined || b === undefined) {
+    if (a === undefined && b !== undefined) return order === 'asc' ? -1 : 1;
+    if (b === undefined && a !== undefined) return order === 'asc' ? 1 : -1;
+    return 0;
+  }
+
+  const isDate = (val: unknown): boolean => typeof val !== 'boolean' && !isNaN(Date.parse(val as string));
+  const isString = (val: unknown): val is string => typeof val === 'string';
+
+  let comparison = 0;
+
+  if (isDate(a) && isDate(b)) {
+    const dateA = a instanceof Date ? a : new Date(a as string);
+    const dateB = b instanceof Date ? b : new Date(b as string);
+    comparison = dateA > dateB ? 1 : -1;
+  } else if (isString(a) && isString(b)) {
+    comparison = a > b ? 1 : -1;
+  } else {
+    comparison = (a as number) > (b as number) ? 1 : -1;
+  }
+
+  return order === 'asc' ? -comparison : comparison;
+}
+
+export function getNestedValue<T>(obj: T, path: keyof T | string): unknown {
+  if (typeof path === 'string') {
+    return path
+      .replace(/\[(\d+)\]/g, '.$1')
+      .split('.')
+      .reduce<unknown>((acc, key) => (acc as Record<string, unknown>)?.[key], obj);
+  }
+
+  return obj[path];
+}
+
+export function sortByCondition<T>(array: T[], options: SortOptions<T>): T[] {
+  const { attr, order = 'asc', preferredValue, backupAttr, orderArrayAttr, orderArray } = options;
+
+  return array.slice().sort((a, b) => {
+    const valueA = getNestedValue(a, attr);
+    const valueB = getNestedValue(b, attr);
+
+    if (preferredValue !== undefined) {
+      if (valueA === preferredValue && valueB !== preferredValue) return -1;
+      if (valueB === preferredValue && valueA !== preferredValue) return 1;
+    }
+
+    if (orderArrayAttr === attr && orderArray) {
+      const orderArrayValue = orderArray[order];
+      return orderArrayValue.indexOf(valueA as string) - orderArrayValue.indexOf(valueB as string);
+    }
+
+    const primaryComparison = compareValues(valueA, valueB, order);
+
+    if (primaryComparison !== 0) return primaryComparison;
+    if (backupAttr) return compareValues(a[backupAttr], b[backupAttr], order);
+    return 0;
+  });
+}
+
+export function sortByConditions<T>(array: T[], optionsArray: SortOptions<T>[]): T[] {
+  return optionsArray.reduce((sortedArray, options) => {
+    return sortByCondition(sortedArray, options);
+  }, array.slice());
+}
+export function sortByArrayOrder<T>(array: T[], order: T[], sortOrder: SortOrder = 'asc'): T[] {
+  return array.slice().sort((a, b) => {
+    const indexA = order.indexOf(a);
+    const indexB = order.indexOf(b);
+    const comparison = indexA - indexB;
+    return sortOrder === 'asc' ? comparison : -comparison;
+  });
+}

package/src/utils/string.ts

@@ -0,0 +1,20 @@
+export const toCapitalize = (string: string) => {
+  if (!string) return string;
+  return string.charAt(0).toUpperCase() + string.slice(1);
+};
+
+export const generateInitial = (string: string, limit = 3) => {
+  const arr = string.split(' ');
+  if (arr.length === 1) return string.substring(0, 3);
+  let initial = '';
+  for (const c of arr) {
+    initial += c.charAt(0);
+  }
+
+  return initial.substring(0, limit);
+};
+
+export const areStringArraysEqual = (arr1: string[], arr2: string[]) => {
+  if (arr1.length !== arr2.length) return false;
+  return arr1.every((element, index) => element === arr2[index]);
+};

package/src/utils/template-type.ts

@@ -0,0 +1,30 @@
+import { TemplateType } from '@/types/template';
+
+export const parseTemplateType = (templateType?: TemplateType | string): string => {
+  switch (templateType) {
+    case TemplateType.PAGE:
+      return 'Landing page';
+    case TemplateType.COLLECTION:
+      return 'Collection page';
+    case TemplateType.PRODUCT:
+      return 'Product page';
+    case TemplateType.ARTICLE:
+      return 'Blog post page';
+    case TemplateType.HOME:
+      return 'Home page';
+    case TemplateType.BLOG:
+      return 'Blog page';
+    case TemplateType.CART:
+      return 'Cart page';
+    case TemplateType.SEARCH:
+      return 'Search page';
+    case TemplateType.NOT_FOUND:
+      return '404 page';
+    case TemplateType.PASSWORD:
+      return 'Password page';
+    case TemplateType.GIF_CART:
+      return 'GIF Cart page';
+    default:
+      return 'Unknown';
+  }
+};