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

package/src/core/gemxql/builder/filters/build-filter-conditions.ts

@@ -0,0 +1,161 @@
+import type { GemXQlFilters, GemXQlOverrideFilters, GemXQlVersionIds, OrderByFields } from '../../types';
+
+import { OPERATOR_IS, OPERATOR_IS_ONE_OF } from '../../constants';
+import { EFilterField, EOperatorField } from '../../types';
+
+export interface IBuildFilterConditionsParams {
+  filters: GemXQlFilters;
+  overrideFilters?: GemXQlOverrideFilters;
+}
+
+export interface IBuildVersionIdConditionParams {
+  versionIds?: GemXQlVersionIds;
+}
+
+interface FilterConfig {
+  operator?: EOperatorField;
+  operatorVal?: string;
+  singleField: EFilterField;
+  multiField: EFilterField;
+  condition?: EFilterField;
+  fieldName?: EFilterField;
+}
+
+export const filterConfigs: FilterConfig[] = [
+  {
+    operator: EOperatorField.DEVICE_OPERATOR,
+    singleField: EFilterField.DEVICE,
+    multiField: EFilterField.DEVICES,
+    fieldName: EFilterField.DEVICE,
+  },
+  {
+    operator: EOperatorField.VISITOR_OPERATOR,
+    singleField: EFilterField.VISITOR,
+    multiField: EFilterField.VISITORS,
+    fieldName: EFilterField.VISITOR,
+  },
+  {
+    operator: EOperatorField.TRAFFIC_SOURCE_OPERATOR,
+    singleField: EFilterField.TRAFFIC_SOURCE,
+    multiField: EFilterField.TRAFFIC_SOURCES,
+    fieldName: EFilterField.TRAFFIC_SOURCE,
+  },
+  {
+    operator: EOperatorField.VERSION_OPERATOR,
+    singleField: EFilterField.VERSION,
+    multiField: EFilterField.VERSIONS,
+    fieldName: EFilterField.VERSION,
+  },
+  {
+    operator: EOperatorField.PAGE_OPERATOR,
+    singleField: EFilterField.SINGLE_PAGE,
+    multiField: EFilterField.LIST_PAGE,
+    fieldName: EFilterField.SINGLE_PAGE,
+  },
+  {
+    operator: EOperatorField.CAMPAIGN_ITEM_OPERATOR,
+    singleField: EFilterField.GROUP_CAMPAIGN_ITEM,
+    multiField: EFilterField.GROUP_CAMPAIGN_ITEMS,
+    condition: EFilterField.GROUP_CAMPAIGN,
+    fieldName: EFilterField.SINGLE_CAMPAIGN,
+  },
+  {
+    operatorVal: OPERATOR_IS,
+    singleField: EFilterField.SINGLE_CAMPAIGN,
+    multiField: EFilterField.GROUP_CAMPAIGN,
+  },
+];
+
+const quoteStr = (v: string): string => `'${v.replace(/'/g, "''")}'`;
+
+const buildCondition = (data: {
+  operatorValue: string | undefined;
+  singleValue?: string;
+  multiValue?: string[];
+  fieldName: string;
+}) => {
+  const { operatorValue, singleValue, multiValue, fieldName } = data;
+  if (operatorValue === OPERATOR_IS && singleValue) {
+    return `${fieldName} = ${quoteStr(singleValue)}`;
+  } else if (operatorValue === OPERATOR_IS_ONE_OF && Array.isArray(multiValue) && multiValue.length > 0) {
+    return `${fieldName} IN (${multiValue.map(quoteStr).join(', ')})`;
+  }
+  return '';
+};
+
+const buildOverrideFilterConditions = (overrideFilters?: GemXQlOverrideFilters) => {
+  if (!overrideFilters) return {};
+
+  return Object.fromEntries(
+    Object.entries(overrideFilters)
+      .filter(([, value]) => value !== undefined)
+      .map(([key, value]) => {
+        const condition = Array.isArray(value)
+          ? `${key} IN (${value.map(quoteStr).join(', ')})`
+          : `${key} = ${quoteStr(String(value))}`;
+        return [key, condition];
+      }),
+  );
+};
+
+export const generateFilterConditions = (filters: GemXQlFilters, overrideFilters?: GemXQlOverrideFilters) => {
+  const conditions: string[] = [];
+
+  const hasFilters = Object.keys(filters).length > 0;
+  const hasOverride = !!overrideFilters && Object.keys(overrideFilters).length > 0;
+  if (!hasFilters && !hasOverride) return conditions;
+
+  const overrideConditionsMap = buildOverrideFilterConditions(overrideFilters);
+
+  filterConfigs.forEach(({ operator, operatorVal, singleField, multiField, condition, fieldName }) => {
+    if (overrideConditionsMap[singleField]) {
+      conditions.push(overrideConditionsMap[singleField]);
+      return;
+    }
+
+    const operatorValue = operator ? filters[operator] : operatorVal;
+    let singleValue = filters[singleField];
+    const multiValue = filters[multiField];
+    const conditionValue = condition && filters[condition];
+
+    if (condition && !conditionValue) {
+      return;
+    }
+
+    const resolvedFieldName = fieldName ?? (singleValue ? singleField : multiField);
+
+    if (operatorVal && !singleValue) {
+      singleValue = filters[multiField] as string | undefined;
+    }
+
+    const result = buildCondition({
+      operatorValue,
+      singleValue: Array.isArray(singleValue) ? undefined : singleValue,
+      multiValue: Array.isArray(multiValue) ? multiValue : undefined,
+      fieldName: resolvedFieldName,
+    });
+    if (result) conditions.push(result);
+  });
+
+  return conditions;
+};
+
+export const buildVersionIdCondition = (versionIds?: GemXQlVersionIds) => {
+  const conditions: string[] = [];
+
+  if (!versionIds) return conditions;
+
+  Object.entries(versionIds).forEach(([key, value]) => {
+    if (!value) return;
+    conditions.push(`${key} = ${quoteStr(value)}`);
+  });
+
+  return conditions;
+};
+
+export const getFirstMetricInOrderBy = (orderBy: OrderByFields | undefined, metrics: string[]) => {
+  if (!orderBy || metrics.length === 0) return [];
+
+  const metric = metrics.find((metric) => orderBy[metric]);
+  return metric ? [metric] : [];
+};

package/src/core/gemxql/builder/filters/index.ts

@@ -0,0 +1,2 @@
+export * from './build-extra-conditions';
+export * from './build-filter-conditions';

package/src/core/gemxql/builder/helpers/date-query-helpers.ts

@@ -0,0 +1,41 @@
+import type { Dayjs } from '@/utils';
+import type { AnalyticDateFilter } from '@/components';
+
+import { dayjsTz } from '@/utils';
+import { DATE_QUERY_FORMAT } from '../configs';
+
+const toDate = (value: Dayjs | string): Dayjs => (typeof value === 'string' ? dayjsTz(value) : value);
+
+const isMidnight = (date: Dayjs) => date.hour() === 0 && date.minute() === 0;
+
+const formatDateForQuery = (date: Dayjs, isEndDay = false) => {
+  if (isEndDay && isMidnight(date)) {
+    return date.endOf('day').format(DATE_QUERY_FORMAT);
+  }
+  return date.format(DATE_QUERY_FORMAT);
+};
+
+const getEndOfDayForQuery = (value?: string | Dayjs) => {
+  if (!value) {
+    return formatDateForQuery(dayjsTz().endOf('day'));
+  }
+  return formatDateForQuery(dayjsTz(value).endOf('day'));
+};
+
+export const getDateRangeForQuery = (dateRange: AnalyticDateFilter) => {
+  const startDate = toDate(dateRange.startDate);
+  const endDate = toDate(dateRange.endDate);
+  const isInTheDay = startDate.isSame(endDate);
+
+  if (isInTheDay) {
+    return {
+      dateGTE: formatDateForQuery(startDate),
+      dateLTE: getEndOfDayForQuery(endDate),
+    };
+  }
+
+  return {
+    dateGTE: formatDateForQuery(startDate),
+    dateLTE: formatDateForQuery(endDate, true),
+  };
+};

package/src/core/gemxql/builder/helpers/index.ts

@@ -0,0 +1 @@
+export * from './is-valid-query-input';

package/src/core/gemxql/builder/helpers/is-valid-query-input.ts

@@ -0,0 +1,8 @@
+export function isValidQueryInput(query: string) {
+  if (typeof query !== 'string') return false;
+
+  const q = query.trim();
+  const pattern = /^MODE\b[\s\S]*\bFROM\b[\s\S]*\bSHOW\b[\s\S]*$/;
+
+  return pattern.test(q);
+}

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

@@ -0,0 +1,6 @@
+export * from './build-gemxql-query';
+export * from './clauses';
+export * from './configs';
+export * from './filters';
+export * from './helpers';
+export * from './parse-gemxql-query';

package/src/core/gemxql/builder/parse-gemxql-query.ts

@@ -0,0 +1,43 @@
+import type { AnalyticDateFilter } from '@/components';
+import type { IBuildGemXQlQueryParams } from './build-gemxql-query';
+
+import { parseConditionQuery } from './clauses/condition-query';
+import { parseFromQuery } from './clauses/from-query';
+import { parseGroupQuery } from './clauses/group-query';
+import { parseLimitQuery } from './clauses/limit-query';
+import { parseModeQuery } from './clauses/mode-query';
+import { parseOffsetQuery } from './clauses/offset-query';
+import { parseOrderByQuery } from './clauses/order-by-query';
+import { parseShowQuery } from './clauses/show-query';
+import { parseTimeQuery } from './clauses/time-query';
+import { parseTimeSeriesQuery } from './clauses/time-series-query';
+import { parseTimezoneQuery } from './clauses/timezone-query';
+
+export type IParsedGemXQlQuery = Partial<IBuildGemXQlQueryParams>;
+
+const parse = (query: string): IParsedGemXQlQuery => {
+  const { dateRange, compareDateRange, timeDimension: overrideTimeDimension, overrideFilters } = parseTimeQuery(query);
+  const timeDimension = overrideTimeDimension ?? parseTimeSeriesQuery(query);
+  const { dimensions, groupWithClause } = parseGroupQuery(query);
+  const { filters, versionIds } = parseConditionQuery(query);
+
+  return {
+    mode: parseModeQuery(query),
+    sources: parseFromQuery(query),
+    metrics: parseShowQuery(query),
+    dimensions,
+    groupWithClause,
+    timeDimension,
+    dateRange: dateRange as AnalyticDateFilter,
+    compareDateRange: compareDateRange as AnalyticDateFilter,
+    overrideFilters,
+    filters,
+    versionIds,
+    timezone: parseTimezoneQuery(query),
+    orderBy: parseOrderByQuery(query),
+    limit: parseLimitQuery(query),
+    offset: parseOffsetQuery(query),
+  };
+};
+
+export { parse as parseGemXQlQuery };

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

@@ -0,0 +1,2 @@
+export const NONE_VALUE = 'None';
+export const PLACEHOLDER_VALUE = '-';

package/src/core/gemxql/constants/column-keys.ts

@@ -0,0 +1,4 @@
+export const TOTALS_SUFFIX = '___totals';
+export const COMPARE_PREFIX = 'comparison___';
+export const COMPARE_SUFFIX = '___previous_period';
+export const COMPARE_TOTALS_SUFFIX = `${COMPARE_SUFFIX}${TOTALS_SUFFIX}`;

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

@@ -0,0 +1,4 @@
+export * from './analytic-data';
+export * from './column-keys';
+export * from './operators';
+export * from './row-reader-mode';

package/src/core/gemxql/constants/operators.ts

@@ -0,0 +1,2 @@
+export const OPERATOR_IS = 'is';
+export const OPERATOR_IS_ONE_OF = 'is_one_of';

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

@@ -0,0 +1,9 @@
+import { ERowReaderMode } from '../types';
+import { COMPARE_PREFIX, COMPARE_SUFFIX, COMPARE_TOTALS_SUFFIX, TOTALS_SUFFIX } from './column-keys';
+
+export const ROW_READER_MODE_CONFIG: Record<ERowReaderMode, { prefix: string; suffix: string }> = {
+  [ERowReaderMode.DEFAULT]: { prefix: '', suffix: '' },
+  [ERowReaderMode.COMPARISON]: { prefix: COMPARE_PREFIX, suffix: COMPARE_SUFFIX },
+  [ERowReaderMode.TOTALS]: { prefix: '', suffix: TOTALS_SUFFIX },
+  [ERowReaderMode.COMPARISON_TOTALS]: { prefix: COMPARE_PREFIX, suffix: COMPARE_TOTALS_SUFFIX },
+};

package/src/core/gemxql/graphql/fragments/gemxql.generated.ts

@@ -0,0 +1,80 @@
+export type Maybe<T> = T | null | undefined;
+
+export type TableDataType =
+  | 'ARRAY'
+  | 'CURRENCY'
+  | 'DATE'
+  | 'DAY_TIMESTAMP'
+  | 'DURATION'
+  | 'HOUR_TIMESTAMP'
+  | 'INTEGER'
+  | 'MONTH_TIMESTAMP'
+  | 'OBJECT'
+  | 'PERCENT'
+  | 'QUARTER_TIMESTAMP'
+  | 'STRING'
+  | 'WEEK_TIMESTAMP'
+  | 'YEAR_TIMESTAMP';
+
+export interface IColumn {
+  dataType: TableDataType;
+  displayName?: Maybe<string>;
+  name: string;
+}
+
+export type Scalars = {
+  ID: { input: string; output: string };
+  String: { input: string; output: string };
+  Boolean: { input: boolean; output: boolean };
+  Int: { input: number; output: number };
+  Float: { input: number; output: number };
+  Any: { input: any; output: any };
+  Cursor: { input: string; output: string };
+  Decimal: { input: any; output: any };
+  Map: { input: any; output: any };
+  Time: { input: string; output: string };
+  Uint: { input: string; output: string };
+  Upload: { input: any; output: any };
+};
+
+export interface ITableData {
+  rows: Maybe<Array<Maybe<Scalars['Map']['output']>>>;
+  columns?: Maybe<Array<Maybe<IColumn>>>;
+}
+
+export type ColumnSelectFragment = Pick<IColumn, 'dataType' | 'displayName' | 'name'>;
+
+export type TableDataSelectFragment = Pick<ITableData, 'rows'> & {
+  columns?: Maybe<Array<Maybe<Pick<IColumn, 'dataType' | 'displayName' | 'name'>>>>;
+};
+
+export type GemXqlResultSelectFragment = {
+  tableData?: Maybe<
+    Pick<ITableData, 'rows'> & {
+      columns?: Maybe<Array<Maybe<Pick<IColumn, 'dataType' | 'displayName' | 'name'>>>>;
+    }
+  >;
+};
+
+export const ColumnSelectFragmentDoc = `
+    fragment ColumnSelect on Column {
+  dataType
+  displayName
+  name
+}
+    `;
+export const TableDataSelectFragmentDoc = `
+    fragment TableDataSelect on TableData {
+  columns {
+    ...ColumnSelect
+  }
+  rows
+}
+    `;
+export const GemXqlResultSelectFragmentDoc = `
+    fragment GemXQLResultSelect on GemxQLResult {
+  tableData {
+    ...TableDataSelect
+  }
+}
+    `;

package/src/core/gemxql/graphql/fragments/gemxql.gql

@@ -0,0 +1,18 @@
+fragment ColumnSelect on Column {
+  dataType
+  displayName
+  name
+}
+
+fragment TableDataSelect on TableData {
+  columns {
+    ...ColumnSelect
+  }
+  rows
+}
+
+fragment GemXQLResultSelect on GemxQLResult {
+  tableData {
+    ...TableDataSelect
+  }
+}

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

@@ -0,0 +1,2 @@
+export * from './fragments/gemxql.generated';
+export * from './queries/gemxql.generated';

package/src/core/gemxql/graphql/queries/gemxql.generated.ts

@@ -0,0 +1,26 @@
+import type { Maybe } from '../fragments/gemxql.generated';
+
+import {
+  ColumnSelectFragmentDoc,
+  GemXqlResultSelectFragmentDoc,
+  TableDataSelectFragmentDoc,
+  type GemXqlResultSelectFragment,
+} from '../fragments/gemxql.generated';
+
+export type GemxQlQueryVariables = {
+  input: string;
+};
+
+export type GemxQlQueryResponse = {
+  gemxQLQuery?: Maybe<GemXqlResultSelectFragment>;
+};
+
+export const GemxQlDocument = `
+    query GemxQL($input: String!) {
+  gemxQLQuery(query: $input) {
+    ...GemXQLResultSelect
+  }
+}
+    ${GemXqlResultSelectFragmentDoc}
+${TableDataSelectFragmentDoc}
+${ColumnSelectFragmentDoc}`;

package/src/core/gemxql/graphql/queries/gemxql.gql

@@ -0,0 +1,5 @@
+query GemxQL($input: String!) {
+  gemxQLQuery(query: $input) {
+    ...GemXQLResultSelect
+  }
+}

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

@@ -0,0 +1,8 @@
+import { COMPARE_PREFIX, COMPARE_SUFFIX, TOTALS_SUFFIX } from '../constants';
+
+export const getTotalsKey = (metric: string): string => `${metric}${TOTALS_SUFFIX}`;
+
+export const getComparisonKey = (metric: string): string => `${COMPARE_PREFIX}${metric}${COMPARE_SUFFIX}`;
+
+export const getComparisonTotalsKey = (metric: string): string =>
+  `${COMPARE_PREFIX}${metric}${COMPARE_SUFFIX}${TOTALS_SUFFIX}`;

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

@@ -0,0 +1,18 @@
+import type { GemxQlQueryResponse, TableDataType } from '../graphql';
+
+export type ColumnTypesMap = Record<string, TableDataType>;
+
+export const extractQueryRows = (response?: GemxQlQueryResponse): Record<string, unknown>[] =>
+  (response?.gemxQLQuery?.tableData?.rows as Record<string, unknown>[]) ?? [];
+
+export const extractQueryColumns = (response?: GemxQlQueryResponse) => response?.gemxQLQuery?.tableData?.columns ?? [];
+
+export const extractColumnTypes = (response?: GemxQlQueryResponse): ColumnTypesMap => {
+  const columns = extractQueryColumns(response);
+  const columnTypes: ColumnTypesMap = {};
+
+  for (const column of columns) {
+    if (column?.name) columnTypes[column.name] = column.dataType;
+  }
+  return columnTypes;
+};

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

@@ -0,0 +1,92 @@
+import type { AnalyticValueType } from '../types';
+
+import { calcPercentageString } from '@/utils/percentage';
+import { NONE_VALUE } from '../constants';
+import { EAnalyticColumnKey, EAnalyticDataType } from '../types';
+import { AnalyticInterval, getFormattedByInterval, getTimeDurationLabel, numberWithCommas } from '@/utils';
+import { formatAnalyticDate } from './formatAnalyticDate';
+
+export type IGetTextPrice = (
+  price?: number | string | null,
+  hasCurrency?: boolean,
+  options?: { compact?: boolean },
+) => string;
+
+export const formatAnalyticData = ({
+  value,
+  formatter,
+  getTextPrice,
+  name,
+}: {
+  value: AnalyticValueType;
+  formatter?: string;
+  getTextPrice?: IGetTextPrice;
+  name?: string;
+}): AnalyticValueType => {
+  const dataTypeIsObjectOrArray = value !== null && (typeof value === 'object' || Array.isArray(value));
+
+  if (dataTypeIsObjectOrArray) return value;
+
+  switch (formatter) {
+    case EAnalyticDataType.INTEGER: {
+      return numberWithCommas((value ?? 0).toString());
+    }
+
+    case EAnalyticDataType.CURRENCY: {
+      if (!getTextPrice) return `${value ?? 0}`;
+      return getTextPrice(value as number | null, false);
+    }
+
+    case EAnalyticDataType.DATE: {
+      return formatAnalyticDate(value as string | number | null);
+    }
+
+    case EAnalyticDataType.PERCENT: {
+      if (typeof value !== 'number') return calcPercentageString(0, 1, 2) ?? '';
+      return calcPercentageString(value / 100, 1, 2) ?? '';
+    }
+
+    case EAnalyticDataType.DURATION: {
+      return getTimeDurationLabel(Number(value));
+    }
+
+    case EAnalyticDataType.STRING: {
+      const fallbackValue = name === EAnalyticColumnKey.CAMPAIGNS ? '' : NONE_VALUE;
+      return value ?? fallbackValue;
+    }
+
+    case EAnalyticDataType.DAY: {
+      return getFormattedByInterval(value as string | number | null, AnalyticInterval.DAY, { isExpandDetail: true });
+    }
+
+    case EAnalyticDataType.HOUR: {
+      return getFormattedByInterval(value as string | number | null, AnalyticInterval.HOUR, { isExpandDetail: true });
+    }
+
+    case EAnalyticDataType.MONTH: {
+      return getFormattedByInterval(value as string | number | null, AnalyticInterval.MONTH, { isExpandDetail: true });
+    }
+
+    case EAnalyticDataType.YEAR: {
+      return getFormattedByInterval(value as string | number | null, AnalyticInterval.YEAR);
+    }
+
+    case EAnalyticDataType.WEEK: {
+      return getFormattedByInterval(value as string | number | null, AnalyticInterval.WEEK, { isExpandDetail: true });
+    }
+
+    case EAnalyticDataType.QUARTER: {
+      return getFormattedByInterval(value as string | number | null, AnalyticInterval.QUARTER, {
+        isExpandDetail: true,
+      });
+    }
+
+    case EAnalyticDataType.OBJECT:
+    case EAnalyticDataType.ARRAY: {
+      return value;
+    }
+
+    default:
+      return `${value}`;
+  }
+};

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

@@ -0,0 +1,29 @@
+import { dayjsTz } from '@/utils';
+
+export const formatAnalyticDate = (dateString: string | number | null) => {
+  if (!dateString) return 'None';
+
+  const date = dayjsTz(dateString);
+  const now = dayjsTz();
+  const yesterday = dayjsTz().subtract(1, 'day');
+
+  const isToday = date.format('YYYY-MM-DD') === now.format('YYYY-MM-DD');
+  const isYesterday = date.format('YYYY-MM-DD') === yesterday.format('YYYY-MM-DD');
+
+  if (isToday) {
+    return `Today at ${date.format('HH:mm')}`;
+  }
+
+  if (isYesterday) {
+    return `Yesterday at ${date.format('HH:mm')}`;
+  }
+
+  const daysDiff = now.diff(date, 'day');
+  const isWithinWeek = daysDiff >= 0 && daysDiff < 7;
+
+  if (isWithinWeek) {
+    return `${date.format('dddd')} at ${date.format('HH:mm')}`;
+  }
+
+  return `${date.format('MMM D')} at ${date.format('hh:mm a')}`;
+};

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

@@ -0,0 +1,11 @@
+import type { Dayjs } from '@/utils';
+
+import { ETimeDimension } from '../types';
+
+export const getTimeDimensionByDate = (startDate: Dayjs, endDate: Dayjs): ETimeDimension => {
+  const durationInDays = endDate.diff(startDate, 'day');
+
+  if (durationInDays <= 3) return ETimeDimension.HOUR;
+  if (durationInDays <= 93) return ETimeDimension.DAY;
+  return ETimeDimension.MONTH;
+};

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

@@ -0,0 +1,6 @@
+const SESSION_KEY = 'sessions';
+
+export const hasMetricData = (metric?: Record<string, unknown>): boolean => {
+  const sessions = metric?.[SESSION_KEY];
+  return typeof sessions === 'number' && sessions > 0;
+};

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

@@ -0,0 +1,8 @@
+export * from './columnKeys';
+export * from './extractQueryData';
+export * from './formatAnalyticData';
+export * from './formatAnalyticDate';
+export * from './getTimeDimension';
+export * from './hasMetricData';
+export * from './parseJsonFields';
+export * from './readNumeric';

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

@@ -0,0 +1,36 @@
+import type { IPageItemsPayload } from '../types';
+
+export interface IBreakdownItem<T extends string = string> {
+  type: T;
+  total: number;
+}
+
+const parseRawJson = (raw: unknown): unknown => {
+  if (!raw) return undefined;
+  return typeof raw === 'string' ? JSON.parse(raw) : raw;
+};
+
+export const parseJsonObject = <T extends object>(value: unknown): T | null => {
+  try {
+    const parsed = parseRawJson(value);
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed as T;
+  } catch {
+    return null;
+  }
+};
+
+export const parseJsonArray = <T>(raw: unknown): T[] | undefined => {
+  try {
+    const parsed = parseRawJson(raw);
+    if (!Array.isArray(parsed)) return undefined;
+    return parsed as T[];
+  } catch {
+    return undefined;
+  }
+};
+
+export const parseBreakdownItems = <T extends string = string>(raw: unknown): IBreakdownItem<T>[] | undefined =>
+  parseJsonArray<IBreakdownItem<T>>(raw)?.map((item) => ({ ...item, total: Number(item.total) }));
+
+export const parsePageItems = (value: unknown): IPageItemsPayload | null => parseJsonObject<IPageItemsPayload>(value);