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

package/src/core/gemxql/helpers/readNumeric.ts

@@ -0,0 +1,25 @@
+import { ROW_READER_MODE_CONFIG } from '../constants';
+import { ERowReaderMode } from '../types';
+
+export const readNumeric = (metric: Record<string, unknown> | undefined, key: string): number => {
+  const raw = metric?.[key];
+  if (typeof raw === 'number') return raw;
+  if (typeof raw === 'string') {
+    const n = parseFloat(raw);
+    return isNaN(n) ? 0 : n;
+  }
+  return 0;
+};
+
+export const createNumericRowReader =
+  (row: Record<string, unknown>, mode: ERowReaderMode = ERowReaderMode.DEFAULT) =>
+  (key: string): number => {
+    const { prefix, suffix } = ROW_READER_MODE_CONFIG[mode];
+    const v = row[`${prefix}${key}${suffix}`];
+    if (typeof v === 'number') return v;
+    if (typeof v === 'string') {
+      const n = parseFloat(v);
+      return isNaN(n) ? 0 : n;
+    }
+    return 0;
+  };

package/src/core/gemxql/hooks/index.ts

@@ -0,0 +1,2 @@
+export * from './useAnalyticData';
+export * from './useGemXQlPagination';

package/src/core/gemxql/hooks/useAnalyticData.ts

@@ -0,0 +1,67 @@
+import type { IGetTextPrice } from '../helpers/formatAnalyticData';
+import type { AnalyticValueType } from '../types';
+
+import { useConvertMoneyContext } from '@/providers/ConvertMoneyProvider';
+import { PLACEHOLDER_VALUE } from '../constants';
+import { formatAnalyticData, hasMetricData, readNumeric } from '../helpers';
+
+interface IFormatDataParams {
+  value: AnalyticValueType;
+  formatter?: string;
+  name?: string;
+}
+
+type MetricRecord = Record<string, unknown>;
+interface IComputeMetricParams {
+  metric?: MetricRecord;
+  previousMetric?: MetricRecord;
+  metricKey: string;
+  formatter?: string;
+}
+
+interface IComputeMetricResult {
+  value: AnalyticValueType;
+  change: number | string;
+}
+
+interface IUseAnalyticDataReturn {
+  formatData: (params: IFormatDataParams) => AnalyticValueType;
+  computeMetric: (params: IComputeMetricParams) => IComputeMetricResult;
+}
+
+interface IUseAnalyticDataParams {
+  getTextPrice?: IGetTextPrice;
+}
+
+export const useAnalyticData = ({
+  getTextPrice: getTextPriceParam,
+}: IUseAnalyticDataParams = {}): IUseAnalyticDataReturn => {
+  const { getTextPrice: getTextPriceCtx } = useConvertMoneyContext();
+  const getTextPrice = getTextPriceParam ?? getTextPriceCtx;
+
+  const formatData = ({ value, formatter, name }: IFormatDataParams): AnalyticValueType => {
+    return formatAnalyticData({ value, formatter, getTextPrice, name });
+  };
+
+  const computeMetric = ({
+    metric,
+    previousMetric,
+    metricKey,
+    formatter,
+  }: IComputeMetricParams): IComputeMetricResult => {
+    if (!hasMetricData(metric)) return { value: 0, change: PLACEHOLDER_VALUE };
+
+    const currentValue = readNumeric(metric, metricKey);
+    const previousValue = readNumeric(previousMetric, metricKey);
+    const value = formatData({ value: currentValue, formatter, name: metricKey });
+
+    if (currentValue === 0 && previousValue !== 0) return { value, change: -100 };
+    if (previousValue === 0) return { value, change: PLACEHOLDER_VALUE };
+
+    const change = ((currentValue - previousValue) / previousValue) * 100;
+
+    return { value, change };
+  };
+
+  return { formatData, computeMetric };
+};

package/src/core/gemxql/hooks/useGemXQlPagination.ts

@@ -0,0 +1,79 @@
+import type { GPaginationProps } from '@/shared/components/GPagination/GPagination';
+
+import { GPaginationDirection } from '@/shared/components/GPagination/GPagination';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+export { GPaginationDirection, GPaginationProps };
+
+interface IUseGemXQlPaginationProps {
+  resetKey: unknown;
+  itemsPerPage: number;
+}
+
+interface IBuildPaginationPropsParams {
+  totalRecords: number;
+  isLoading?: boolean;
+}
+
+interface IUseGemXQlPaginationReturn {
+  currentPage: number;
+  offset: number;
+  buildPagination: (params: IBuildPaginationPropsParams) => GPaginationProps;
+}
+
+export const useGemXQlPagination = ({
+  resetKey,
+  itemsPerPage,
+}: IUseGemXQlPaginationProps): IUseGemXQlPaginationReturn => {
+  const [currentPage, setCurrentPage] = useState(1);
+
+  // Serialize so object/array reset keys compare by value, not by reference.
+  const serializedResetKey = useMemo(() => {
+    if (resetKey === undefined) return undefined;
+    try {
+      return JSON.stringify(resetKey);
+    } catch {
+      return String(resetKey);
+    }
+  }, [resetKey]);
+
+  const previousResetKeyRef = useRef<string | undefined>();
+  const shouldResetPagination =
+    currentPage > 1 && previousResetKeyRef.current !== undefined && previousResetKeyRef.current !== serializedResetKey;
+  const effectivePage = shouldResetPagination ? 1 : currentPage;
+
+  const offset = (effectivePage - 1) * itemsPerPage;
+
+  const handlePageChange = useCallback(
+    (totalPages: number) => (direction: GPaginationDirection) => {
+      setCurrentPage((prevPage) => {
+        const isNextPage = direction === GPaginationDirection.NEXT;
+        const nextPage = isNextPage ? prevPage + 1 : prevPage - 1;
+        return Math.min(Math.max(nextPage, 1), totalPages);
+      });
+    },
+    [],
+  );
+
+  useEffect(() => {
+    if (previousResetKeyRef.current !== serializedResetKey) {
+      previousResetKeyRef.current = serializedResetKey;
+      setCurrentPage(1);
+    }
+  }, [serializedResetKey]);
+
+  const buildPagination = useCallback(
+    ({ totalRecords, isLoading }: IBuildPaginationPropsParams): GPaginationProps => {
+      const totalPages = Math.max(1, Math.ceil(totalRecords / itemsPerPage));
+      return {
+        currentPage: effectivePage,
+        totalPages,
+        loading: isLoading,
+        handlePageChange: handlePageChange(totalPages),
+      };
+    },
+    [effectivePage, itemsPerPage, handlePageChange],
+  );
+
+  return { currentPage: effectivePage, offset, buildPagination };
+};

package/src/core/gemxql/index.ts

@@ -0,0 +1,8 @@
+export * from './builder';
+export * from './constants';
+export * from './helpers';
+
+export * from './types';
+export * from './api';
+export * from './graphql';
+export * from './hooks';

package/src/core/gemxql/types/analytic-data.ts

@@ -0,0 +1,26 @@
+export enum EAnalyticDataType {
+  DATE = 'DATE',
+  ARRAY = 'ARRAY',
+  OBJECT = 'OBJECT',
+  STRING = 'STRING',
+  INTEGER = 'INTEGER',
+  CURRENCY = 'CURRENCY',
+  PERCENT = 'PERCENT',
+  DURATION = 'DURATION',
+  MONTH = 'MONTH_TIMESTAMP',
+  QUARTER = 'QUARTER_TIMESTAMP',
+  DAY = 'DAY_TIMESTAMP',
+  WEEK = 'WEEK_TIMESTAMP',
+  YEAR = 'YEAR_TIMESTAMP',
+  HOUR = 'HOUR_TIMESTAMP',
+}
+
+export enum EAnalyticColumnKey {
+  CAMPAIGNS = 'experiments',
+  VISITOR_ITEMS = 'visitor_items',
+  DEVICE_ITEMS = 'device_items',
+  TRAFFIC_SOURCE_ITEMS = 'traffic_source_items',
+}
+
+export type AnalyticPrimitiveValueType = string | number | null;
+export type AnalyticValueType = AnalyticPrimitiveValueType;

package/src/core/gemxql/types/analytic-source.ts

@@ -0,0 +1,4 @@
+export enum EAnalyticSource {
+  SESSIONS = 'sessions',
+  SALES = 'sales',
+}

package/src/core/gemxql/types/extra-condition.ts

@@ -0,0 +1,40 @@
+export enum EComparisonOperator {
+  EQ = '=',
+  IN = 'IN',
+  LIKE = 'LIKE',
+  GROUP = 'GROUP',
+}
+
+export enum EGroupOperator {
+  OR = 'OR',
+  AND = 'AND',
+}
+
+export type IExtraConditionEq = {
+  operator: EComparisonOperator.EQ;
+  fields: string[];
+  value: string | number;
+  groupOperator?: EGroupOperator;
+};
+
+export type IExtraConditionIn = {
+  operator: EComparisonOperator.IN;
+  fields: string[];
+  values: Array<string | number>;
+  groupOperator?: EGroupOperator;
+};
+
+export type IExtraConditionLike = {
+  operator: EComparisonOperator.LIKE;
+  fields: string[];
+  value: string;
+  groupOperator?: EGroupOperator;
+};
+
+export type IExtraConditionGroup = {
+  operator: EComparisonOperator.GROUP;
+  groupOperator: EGroupOperator;
+  conditions: IExtraCondition[];
+};
+
+export type IExtraCondition = IExtraConditionEq | IExtraConditionIn | IExtraConditionLike | IExtraConditionGroup;

package/src/core/gemxql/types/field-filters.ts

@@ -0,0 +1,18 @@
+export enum EFilterField {
+  DEVICE = 'device',
+  DEVICES = 'devices',
+  VISITOR = 'visitor_type',
+  VISITORS = 'visitor_types',
+  TRAFFIC_SOURCE = 'traffic_source',
+  TRAFFIC_SOURCES = 'traffic_sources',
+  VERSION = 'version',
+  VERSIONS = 'versions',
+  SINGLE_PAGE = 'page_path',
+  LIST_PAGE = 'page_paths',
+  GROUP_CAMPAIGN_ITEM = 'group_campaign_item',
+  GROUP_CAMPAIGN_ITEMS = 'group_campaign_items',
+  SINGLE_CAMPAIGN = 'experiment_id',
+  GROUP_CAMPAIGN = 'experiment_group_id',
+  CAMPAIGN_VERSION_ID = 'version_id',
+  GROUP_CAMPAIGN_VERSION_ID = 'group_version_id',
+}

package/src/core/gemxql/types/field-operators.ts

@@ -0,0 +1,8 @@
+export enum EOperatorField {
+  DEVICE_OPERATOR = 'deviceOperator',
+  VISITOR_OPERATOR = 'visitorOperator',
+  TRAFFIC_SOURCE_OPERATOR = 'trafficSourceOperator',
+  VERSION_OPERATOR = 'versionOperator',
+  PAGE_OPERATOR = 'pageOperator',
+  CAMPAIGN_ITEM_OPERATOR = 'campaignItemOperator',
+}

package/src/core/gemxql/types/filter-types.ts

@@ -0,0 +1,33 @@
+import type { EFilterField } from './field-filters';
+import type { EOperatorField } from './field-operators';
+
+export type GemXQlFilters = {
+  [EFilterField.DEVICE]?: string;
+  [EFilterField.VISITOR]?: string;
+  [EFilterField.TRAFFIC_SOURCE]?: string;
+  [EFilterField.VERSION]?: string;
+  [EFilterField.SINGLE_PAGE]?: string;
+  [EFilterField.GROUP_CAMPAIGN_ITEM]?: string;
+  [EFilterField.SINGLE_CAMPAIGN]?: string;
+  [EFilterField.CAMPAIGN_VERSION_ID]?: string;
+  [EFilterField.GROUP_CAMPAIGN_VERSION_ID]?: string;
+
+  [EFilterField.DEVICES]?: string[];
+  [EFilterField.VISITORS]?: string[];
+  [EFilterField.TRAFFIC_SOURCES]?: string[];
+  [EFilterField.VERSIONS]?: string[];
+  [EFilterField.LIST_PAGE]?: string[];
+  [EFilterField.GROUP_CAMPAIGN_ITEMS]?: string[];
+  [EFilterField.GROUP_CAMPAIGN]?: string[];
+
+  [EOperatorField.DEVICE_OPERATOR]?: string;
+  [EOperatorField.VISITOR_OPERATOR]?: string;
+  [EOperatorField.TRAFFIC_SOURCE_OPERATOR]?: string;
+  [EOperatorField.VERSION_OPERATOR]?: string;
+  [EOperatorField.PAGE_OPERATOR]?: string;
+  [EOperatorField.CAMPAIGN_ITEM_OPERATOR]?: string;
+};
+
+export type GemXQlOverrideFilters = GemXQlFilters;
+
+export type GemXQlVersionIds = Record<string, string | undefined>;

package/src/core/gemxql/types/group-with-clause.ts

@@ -0,0 +1,12 @@
+/**
+ * Controls which totals columns are appended to the query result.
+ *
+ * - NONE   → no totals, GROUP BY only.
+ * - TOTALS → adds `<metric>___totals` (grand total only). Use with single-dimension GROUP BY.
+ * - ALL    → adds subtotals per dimension group + grand total. Use with multi-dimension GROUP BY.
+ */
+export enum EGroupWithClause {
+  NONE = '',
+  TOTALS = 'TOTALS',
+  ALL = 'WITH GROUP_TOTALS, TOTALS',
+}

package/src/core/gemxql/types/index.ts

@@ -0,0 +1,11 @@
+export * from './analytic-data';
+export * from './analytic-source';
+export * from './extra-condition';
+export * from './field-filters';
+export * from './field-operators';
+export * from './filter-types';
+export * from './group-with-clause';
+export * from './order-by';
+export * from './page-fields';
+export * from './row-reader-mode';
+export * from './time-dimension';

package/src/core/gemxql/types/order-by.ts

@@ -0,0 +1,13 @@
+export enum EOrderDirectionType {
+  ASC = 'ASC',
+  DESC = 'DESC',
+}
+
+export type OrderDirectionType = EOrderDirectionType.ASC | EOrderDirectionType.DESC;
+
+export type OrderByType = {
+  field: string;
+  direction: OrderDirectionType;
+};
+
+export type OrderByFields = Record<string, OrderByType>;

package/src/core/gemxql/types/page-fields.ts

@@ -0,0 +1,25 @@
+export enum EPageMetric {
+  PAGE_ITEMS = 'page_items',
+  PAGE_PATHS = 'page_paths',
+}
+
+export enum EPageDimension {
+  PAGE_PATH = 'page_path',
+}
+
+export enum EPageField {
+  SHOPIFY_PAGE_ID = 'shopify_page_id',
+  LOCATION_PATH = 'location_path',
+  PAGE_TYPE = 'page_type',
+  PAGE_TITLE = 'page_title',
+  PAGE_PATH = 'page_path',
+  TEMPLATE_SUFFIX = 'template_suffix',
+}
+
+export interface IPageItemsPayload {
+  [EPageField.SHOPIFY_PAGE_ID]: string;
+  [EPageField.LOCATION_PATH]: string;
+  [EPageField.PAGE_TYPE]: string;
+  [EPageField.PAGE_TITLE]: string;
+  [EPageField.TEMPLATE_SUFFIX]: string;
+}

package/src/core/gemxql/types/row-reader-mode.ts

@@ -0,0 +1,6 @@
+export enum ERowReaderMode {
+  DEFAULT = 'DEFAULT',
+  COMPARISON = 'COMPARISON',
+  TOTALS = 'TOTALS',
+  COMPARISON_TOTALS = 'COMPARISON_TOTALS',
+}

package/src/core/gemxql/types/time-dimension.ts

@@ -0,0 +1,8 @@
+export enum ETimeDimension {
+  HOUR = 'hour',
+  DAY = 'day',
+  WEEK = 'week',
+  MONTH = 'month',
+  QUARTER = 'quarter',
+  YEAR = 'year',
+}

package/src/global.d.ts

@@ -0,0 +1,38 @@
+declare namespace JSX {
+  interface IntrinsicElements {}
+}
+
+declare module '*.scss' {
+  const content: Record<string, string>;
+  export default content;
+}
+
+declare module '*.css' {
+  const content: Record<string, string>;
+  export default content;
+}
+
+declare module '*.css?url' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.png' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.svg' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.jpg' {
+  const src: string;
+  export default src;
+}
+
+declare module '*.webp' {
+  const src: string;
+  export default src;
+}

package/src/hooks/index.ts

@@ -0,0 +1,7 @@
+export { useEnhancedEffect } from './useEnhancedEffect';
+export { useFetchCurrencyRates } from './useFetchCurrencyRates';
+export { useFormatLineChartData } from './useFormatLineChartData';
+export { usePopoverResizeObserver } from './usePopoverResizeObserver';
+export { useToggle } from './useToggle';
+export { useWindowSize } from './publish/useWindowSize';
+export { usePreventBodyScroll } from './usePreventBodyScroll';

package/src/hooks/publish/index.ts

@@ -0,0 +1,2 @@
+export { useIsStickyById } from './useStickyDetectById';
+export { useStickyFilterBoxProps } from './useStickyFilterBoxProps';

package/src/hooks/publish/useStickyDetectById.ts

@@ -0,0 +1,39 @@
+import { useEffect, useState } from 'react';
+
+type UseIsStickyByIdProps = {
+  id: string;
+  stickyTop: number;
+  threshold?: number;
+  enabled?: boolean;
+};
+
+function isBrowser() {
+  return typeof window !== 'undefined';
+}
+
+export const useIsStickyById = ({ id, stickyTop, threshold = 0, enabled = true }: UseIsStickyByIdProps) => {
+  const [isSticky, setIsSticky] = useState(false);
+
+  useEffect(() => {
+    if (!enabled || !isBrowser()) return;
+
+    const el = document.getElementById(id);
+    if (!el) return;
+
+    const checkSticky = () => {
+      const rect = el.getBoundingClientRect();
+      setIsSticky(rect.top <= stickyTop + threshold);
+    };
+
+    checkSticky();
+    window.addEventListener('scroll', checkSticky, { passive: true });
+    window.addEventListener('resize', checkSticky);
+
+    return () => {
+      window.removeEventListener('scroll', checkSticky);
+      window.removeEventListener('resize', checkSticky);
+    };
+  }, [id, stickyTop, threshold, enabled]);
+
+  return isSticky;
+};

package/src/hooks/publish/useStickyFilterBoxProps.ts

@@ -0,0 +1,26 @@
+import type { BoxProps } from '@shopify/polaris';
+
+import { useIsStickyById } from './useStickyDetectById';
+import { useWindowSize } from './useWindowSize';
+
+type IUseStickyFilterBoxPropsArgs = {
+  id: string;
+};
+
+// Border is deferred until the row is actually stuck so it doesn't flash on initial render.
+export const useStickyFilterBoxProps = ({ id }: IUseStickyFilterBoxPropsArgs): Partial<BoxProps> => {
+  const { isMobileView } = useWindowSize();
+  const enabled = isMobileView && Boolean(id);
+  const isStuck = useIsStickyById({ id, stickyTop: 0, enabled });
+
+  if (!enabled) return {};
+
+  return {
+    position: 'sticky',
+    insetBlockStart: '0',
+    zIndex: '10',
+    background: 'bg',
+    paddingBlock: '200',
+    ...(isStuck && { borderBlockEndWidth: '025', borderColor: 'border' }),
+  };
+};

package/src/hooks/publish/useWindowSize.ts

@@ -0,0 +1,54 @@
+import { useEffect, useMemo, useState } from 'react';
+
+export interface IWindowSize {
+  width: number;
+  height: number;
+}
+
+export interface IUseWindowSizeResult {
+  windowSize: IWindowSize;
+  windowWidth: {
+    xs: boolean;
+    md: boolean;
+    lg: boolean;
+    xsDown: boolean;
+    '1200Down': boolean;
+    '1040Down': boolean;
+  };
+  isMobileTabletView: boolean;
+  isMobileView: boolean;
+}
+
+export const useWindowSize = (): IUseWindowSizeResult => {
+  const [windowSize, setWindowSize] = useState<IWindowSize>(() => ({
+    width: typeof window !== 'undefined' ? window.innerWidth : 0,
+    height: typeof window !== 'undefined' ? window.innerHeight : 0,
+  }));
+
+  const windowWidth = useMemo(() => {
+    return {
+      xs: windowSize.width <= 768,
+      md: 768 < windowSize.width && windowSize.width <= 1024,
+      lg: windowSize.width > 1024,
+      xsDown: windowSize.width < 768,
+      '1200Down': windowSize.width < 1200,
+      '1040Down': windowSize.width < 1040,
+    };
+  }, [windowSize.width]);
+
+  const isMobileTabletView = !windowWidth.lg;
+  const isMobileView = windowWidth.xs;
+
+  useEffect(() => {
+    const windowSizeHandler = () => {
+      setWindowSize({ width: window.innerWidth, height: window.innerHeight });
+    };
+    window.addEventListener('resize', windowSizeHandler);
+
+    return () => {
+      window.removeEventListener('resize', windowSizeHandler);
+    };
+  }, []);
+
+  return { windowSize, windowWidth, isMobileTabletView, isMobileView };
+};

package/src/hooks/useEnhancedEffect.ts

@@ -0,0 +1,3 @@
+import * as React from 'react';
+
+export const useEnhancedEffect = typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect;

package/src/hooks/useFetchCurrencyRates.ts

@@ -0,0 +1,48 @@
+import { useCurrencyRatesStore, type ICurrencyRates } from '@/stores/currencyRatesStore';
+import { useQuery } from '@tanstack/react-query';
+import { useEffect } from 'react';
+
+const SHOPIFY_CURRENCIES_URL = 'https://cdn.shopify.com/s/javascripts/currencies.js';
+
+const parseCurrencyRates = (scriptText: string): ICurrencyRates => {
+  const rates: ICurrencyRates = {};
+  const match = /var Currency=\{rates:\{(.*?)\}\};/s.exec(scriptText);
+  const ratesStr = match?.[1];
+  if (!ratesStr) return rates;
+
+  const ratePattern = /([A-Z]+):\s*([\d.e+-]+),/g;
+  let m;
+  while ((m = ratePattern.exec(ratesStr)) !== null) {
+    const [, code, value] = m;
+    if (code && value) rates[code] = parseFloat(value);
+  }
+  return rates;
+};
+
+const fetchCurrencyRates = async (): Promise<ICurrencyRates> => {
+  const res = await fetch(SHOPIFY_CURRENCIES_URL);
+  if (!res.ok) throw new Error('Failed to fetch currency rates');
+  const text = await res.text();
+  return parseCurrencyRates(text);
+};
+
+export const useFetchCurrencyRates = () => {
+  const setCurrencyRates = useCurrencyRatesStore((state) => state.setCurrencyRates);
+
+  const { data, error, isError } = useQuery({
+    queryKey: ['sdk-currency-rates'],
+    queryFn: fetchCurrencyRates,
+    staleTime: 1000 * 60 * 60, // 1 hour — rates don't change often
+  });
+
+  useEffect(() => {
+    if (data) setCurrencyRates(data);
+  }, [data, setCurrencyRates]);
+
+  // Surface fetch failures: without rates, money renders in the base currency unconverted.
+  useEffect(() => {
+    if (isError) console.error('[gem-sdk/analytics] Failed to fetch currency rates:', error);
+  }, [isError, error]);
+
+  return { isError, error };
+};

package/src/hooks/useFormatLineChartData.ts

@@ -0,0 +1,28 @@
+import type { LineChartProps } from '@shopify/polaris-viz';
+import type { EMetricKey } from '@/types/metric';
+import type { ColumnTypesMap } from '@/core/gemxql';
+
+import { useAnalyticData } from '@/core/gemxql/hooks';
+
+interface IProps {
+  metricKey?: EMetricKey;
+  columnTypes: ColumnTypesMap;
+}
+
+export const useFormatLineChartData = ({ metricKey, columnTypes }: IProps) => {
+  const { formatData } = useAnalyticData();
+
+  const formatter = metricKey ? columnTypes?.[metricKey] : undefined;
+
+  const formatValue = (value: number) => {
+    return String(formatData({ value, formatter }));
+  };
+
+  const yAxisOptions: LineChartProps['yAxisOptions'] = {
+    labelFormatter: (value) => {
+      return formatValue(Number(value) || 0);
+    },
+  };
+
+  return { formatValue, yAxisOptions };
+};