sori.studio/lib/analytics.js

import { createHash } from 'node:crypto'

/** @type {RegExp} 추적 제외 경로 */
const EXCLUDED_PATH_PATTERN = /^\/(admin|signin|signup|forgot-password|settings)(\/|$)/

/** @type {RegExp} 봇 User-Agent 패턴 */
const BOT_USER_AGENT_PATTERN = /bot|crawl|spider|slurp|preview|headless|lighthouse|bytespider|facebookexternalhit/i

/**
 * 오늘 날짜(UTC)를 YYYY-MM-DD로 반환한다.
 * @returns {string} 날짜 문자열
 */
export const getAnalyticsDayKey = () => {
  const now = new Date()
  return now.toISOString().slice(0, 10)
}

/**
 * 통계 추적 대상 경로인지 확인한다.
 * @param {string} path - 요청 경로
 * @returns {boolean} 추적 가능 여부
 */
export const isTrackableAnalyticsPath = (path) => {
  const normalized = (path || '').trim()
  if (!normalized.startsWith('/')) {
    return false
  }

  if (EXCLUDED_PATH_PATTERN.test(normalized)) {
    return false
  }

  return true
}

/**
 * 봇 User-Agent 여부
 * @param {string} userAgent - User-Agent
 * @returns {boolean} 봇 여부
 */
export const isBotUserAgent = (userAgent) => {
  const value = (userAgent || '').trim()
  if (!value) {
    return false
  }

  return BOT_USER_AGENT_PATTERN.test(value)
}

/**
 * 일 단위 익명 방문자 해시를 생성한다. 원문 IP·UA는 저장하지 않는다.
 * @param {{ day: string, ip: string, userAgent: string, secret: string }} input - 해시 입력
 * @returns {string} visitor hash
 */
export const createDailyVisitorHash = ({ day, ip, userAgent, secret }) => {
  const payload = `${day}|${ip}|${userAgent}|${secret}`
  return createHash('sha256').update(payload).digest('hex')
}

/**
 * 게시물 slug 정규화
 * @param {string} slug - slug
 * @returns {string} 정규화된 slug
 */
export const normalizePostSlugForAnalytics = (slug) => (slug || '').trim()

/** @type {number} heartbeat 체류시간 상한(초) */
export const ANALYTICS_MAX_DURATION_SECONDS = 1800

/** @type {number} engaged_views 집계 최소 체류(초) */
export const ANALYTICS_ENGAGED_MIN_SECONDS = 10

/** @type {number} 현재 접속자 판정 TTL(초) */
export const ANALYTICS_ACTIVE_SESSION_TTL_SECONDS = 90

/** @type {number[]} 스크롤 구간 임계값 */
export const ANALYTICS_SCROLL_THRESHOLDS = [0.25, 0.5, 0.75, 1]

/**
 * 체류시간(초)을 상한 내로 보정한다.
 * @param {number} seconds - 체류시간
 * @returns {number} 보정된 초
 */
export const clampAnalyticsDurationSeconds = (seconds) => {
  const value = Number(seconds)
  if (!Number.isFinite(value) || value < 0) {
    return 0
  }

  return Math.min(Math.floor(value), ANALYTICS_MAX_DURATION_SECONDS)
}

/**
 * 스크롤 비율을 0~1로 보정한다.
 * @param {number} ratio - 스크롤 비율
 * @returns {number} 보정된 비율
 */
export const clampAnalyticsScrollRatio = (ratio) => {
  const value = Number(ratio)
  if (!Number.isFinite(value) || value < 0) {
    return 0
  }

  return Math.min(value, 1)
}

/**
 * 새로 통과한 스크롤 구간 컬럼명 목록을 반환한다.
 * @param {number} previousRatio - 이전 최대 스크롤
 * @param {number} nextRatio - 갱신된 최대 스크롤
 * @returns {Array<'scroll_25' | 'scroll_50' | 'scroll_75' | 'scroll_100'>} 신규 구간
 */
export const getNewScrollBucketColumns = (previousRatio, nextRatio) => {
  const previous = clampAnalyticsScrollRatio(previousRatio)
  const next = clampAnalyticsScrollRatio(nextRatio)
  const columns = []

  if (previous < 0.25 && next >= 0.25) {
    columns.push('scroll_25')
  }
  if (previous < 0.5 && next >= 0.5) {
    columns.push('scroll_50')
  }
  if (previous < 0.75 && next >= 0.75) {
    columns.push('scroll_75')
  }
  if (previous < 1 && next >= 1) {
    columns.push('scroll_100')
  }

  return columns
}

/**
 * 실시간 세션 해시를 생성한다.
 * @param {{ clientSessionId: string, visitorHash: string, secret: string }} input - 해시 입력
 * @returns {string} session hash
 */
export const createRealtimeSessionHash = ({ clientSessionId, visitorHash, secret }) => {
  const payload = `${clientSessionId}|${visitorHash}|${secret}`
  return createHash('sha256').update(payload).digest('hex')
}