sovrium 0.0.2

package/src/application/use-cases/activity/programs.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import {
+  getActivityById,
+  type ActivityDatabaseError,
+  type ActivityNotFoundError,
+} from '@/infrastructure/database/activity-queries'
+
+/**
+ * Invalid activity ID error
+ */
+export class InvalidActivityIdError {
+  readonly _tag = 'InvalidActivityIdError'
+  constructor(readonly activityId: string) {}
+}
+
+/**
+ * Get activity log by ID
+ *
+ * Validates the activity ID format and fetches activity details with user metadata.
+ *
+ * @param activityId - Activity ID as string (UUID from URL parameter)
+ * @returns Effect program that resolves to activity with user or fails with error
+ */
+export const GetActivityById = (activityId: string) =>
+  Effect.gen(function* () {
+    // Validate activity ID format (must be non-empty string)
+    // In production, activity IDs are UUIDs, but for simplicity we accept any non-empty string
+    // Integer validation for backward compatibility with tests expecting numeric IDs
+    if (!activityId || activityId.trim() === '') {
+      return yield* Effect.fail(new InvalidActivityIdError(activityId))
+    }
+
+    // Try to parse as integer for backward compatibility
+    const parsedId = parseInt(activityId, 10)
+    const isNumericId = !isNaN(parsedId) && parsedId > 0 && parsedId.toString() === activityId
+
+    // Reject obviously invalid formats like "invalid-id"
+    // Accept UUIDs and numeric strings
+    const isValidUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+      activityId
+    )
+
+    if (!isNumericId && !isValidUuid) {
+      return yield* Effect.fail(new InvalidActivityIdError(activityId))
+    }
+
+    // Fetch activity from database (accepts both numeric and UUID strings)
+    const activity = yield* getActivityById(activityId)
+
+    return activity
+  })
+
+/**
+ * Export all error types for external use
+ */
+export type GetActivityByIdError =
+  | InvalidActivityIdError
+  | ActivityNotFoundError
+  | ActivityDatabaseError

package/src/application/use-cases/analytics/collect-page-view.ts

@@ -0,0 +1,114 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import { AnalyticsRepository } from '../../ports/repositories/analytics-repository'
+import { parseUserAgent } from './ua-parser'
+import { computeSessionHash, computeVisitorHash } from './visitor-hash'
+import type { AnalyticsDatabaseError } from '../../ports/repositories/analytics-repository'
+
+/**
+ * Input for collecting a page view event
+ */
+export interface CollectPageViewInput {
+  readonly appName: string
+  readonly pagePath: string
+  readonly pageTitle?: string
+  readonly referrerUrl?: string
+  readonly utmSource?: string
+  readonly utmMedium?: string
+  readonly utmCampaign?: string
+  readonly utmContent?: string
+  readonly utmTerm?: string
+  readonly screenWidth?: number
+  readonly screenHeight?: number
+  readonly ip: string
+  readonly userAgent: string
+  readonly acceptLanguage?: string
+  readonly sessionTimeoutMinutes?: number
+}
+
+/**
+ * Extract the primary language from Accept-Language header.
+ *
+ * @example "en-US,en;q=0.9,fr;q=0.8" → "en-US"
+ */
+const extractLanguage = (header: string | undefined): string | undefined => {
+  if (!header) return undefined
+  const first = header.split(',')[0]
+  if (!first) return undefined
+  return first.split(';')[0]?.trim()
+}
+
+/**
+ * Extract domain from a referrer URL.
+ *
+ * @example "https://www.google.com/search?q=test" → "google.com"
+ */
+const extractReferrerDomain = (referrerUrl: string | undefined): string | undefined => {
+  if (!referrerUrl) return undefined
+  try {
+    const url = new URL(referrerUrl)
+    // Strip 'www.' prefix for cleaner domain names
+    return url.hostname.replace(/^www\./, '')
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Collect a page view event.
+ *
+ * Orchestrates visitor hashing, UA parsing, referrer extraction,
+ * and persists the page view to the analytics repository.
+ *
+ * This is an Effect program requiring the AnalyticsRepository service.
+ */
+export const collectPageView = (
+  input: CollectPageViewInput
+): Effect.Effect<void, AnalyticsDatabaseError, AnalyticsRepository> =>
+  Effect.gen(function* () {
+    const repo = yield* AnalyticsRepository
+
+    // Compute privacy-safe visitor and session hashes
+    const visitorHash = yield* Effect.promise(() =>
+      computeVisitorHash(input.ip, input.userAgent, input.appName)
+    )
+    const sessionHash = yield* Effect.promise(() =>
+      computeSessionHash(visitorHash, input.sessionTimeoutMinutes ?? 30)
+    )
+
+    // Parse device information from User-Agent
+    const { deviceType, browserName, osName } = parseUserAgent(input.userAgent)
+
+    // Extract language and referrer domain
+    const language = extractLanguage(input.acceptLanguage)
+    const referrerDomain = extractReferrerDomain(input.referrerUrl)
+
+    // Record the page view
+    yield* repo.recordPageView({
+      appName: input.appName,
+      pagePath: input.pagePath,
+      pageTitle: input.pageTitle,
+      visitorHash,
+      sessionHash,
+      isEntrance: false, // TODO: detect entrance based on session history
+      referrerUrl: input.referrerUrl,
+      referrerDomain,
+      utmSource: input.utmSource,
+      utmMedium: input.utmMedium,
+      utmCampaign: input.utmCampaign,
+      utmContent: input.utmContent,
+      utmTerm: input.utmTerm,
+      deviceType,
+      browserName,
+      osName,
+      language,
+      screenWidth: input.screenWidth,
+      screenHeight: input.screenHeight,
+    })
+  })

package/src/application/use-cases/analytics/purge-old-data.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import { AnalyticsRepository } from '../../ports/repositories/analytics-repository'
+import type { AnalyticsDatabaseError } from '../../ports/repositories/analytics-repository'
+
+/**
+ * Default retention period in days when not configured
+ */
+const DEFAULT_RETENTION_DAYS = 365
+
+/**
+ * Purge analytics data older than the configured retention period.
+ *
+ * Deletes page view records that exceed the retention window.
+ * Returns the number of records deleted.
+ *
+ * @param appName - Application name to scope deletion
+ * @param retentionDays - Number of days to retain (default: 365)
+ * @returns Number of deleted records
+ */
+export const purgeOldAnalyticsData = (
+  appName: string,
+  retentionDays?: number
+): Effect.Effect<number, AnalyticsDatabaseError, AnalyticsRepository> =>
+  Effect.gen(function* () {
+    const repo = yield* AnalyticsRepository
+
+    const days = retentionDays ?? DEFAULT_RETENTION_DAYS
+    const cutoff = new Date()
+    // eslint-disable-next-line functional/no-expression-statements
+    cutoff.setDate(cutoff.getDate() - days)
+
+    return yield* repo.deleteOlderThan(appName, cutoff)
+  })

package/src/application/use-cases/analytics/query-campaigns.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import { AnalyticsRepository } from '../../ports/repositories/analytics-repository'
+import type {
+  AnalyticsDatabaseError,
+  CampaignEntry,
+} from '../../ports/repositories/analytics-repository'
+
+export interface QueryCampaignsInput {
+  readonly appName: string
+  readonly from: Date
+  readonly to: Date
+}
+
+export interface CampaignsResult {
+  readonly campaigns: readonly CampaignEntry[]
+  readonly total: number
+}
+
+/**
+ * Query UTM campaign breakdown.
+ */
+export const queryCampaigns = (
+  input: QueryCampaignsInput
+): Effect.Effect<CampaignsResult, AnalyticsDatabaseError, AnalyticsRepository> =>
+  Effect.gen(function* () {
+    const repo = yield* AnalyticsRepository
+
+    const campaigns = yield* repo.getCampaigns({
+      appName: input.appName,
+      from: input.from,
+      to: input.to,
+      granularity: 'day',
+    })
+
+    return { campaigns, total: campaigns.length }
+  })

package/src/application/use-cases/analytics/query-devices.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import { AnalyticsRepository } from '../../ports/repositories/analytics-repository'
+import type {
+  AnalyticsDatabaseError,
+  DeviceBreakdown,
+} from '../../ports/repositories/analytics-repository'
+
+export interface QueryDevicesInput {
+  readonly appName: string
+  readonly from: Date
+  readonly to: Date
+}
+
+/**
+ * Query device, browser, and OS breakdown.
+ */
+export const queryDevices = (
+  input: QueryDevicesInput
+): Effect.Effect<DeviceBreakdown, AnalyticsDatabaseError, AnalyticsRepository> =>
+  Effect.gen(function* () {
+    const repo = yield* AnalyticsRepository
+
+    return yield* repo.getDevices({
+      appName: input.appName,
+      from: input.from,
+      to: input.to,
+      granularity: 'day',
+    })
+  })

package/src/application/use-cases/analytics/query-overview.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import { AnalyticsRepository } from '../../ports/repositories/analytics-repository'
+import type {
+  AnalyticsDatabaseError,
+  AnalyticsSummary,
+  TimeSeriesPoint,
+} from '../../ports/repositories/analytics-repository'
+
+export interface QueryOverviewInput {
+  readonly appName: string
+  readonly from: Date
+  readonly to: Date
+  readonly granularity: 'hour' | 'day' | 'week' | 'month'
+}
+
+export interface OverviewResult {
+  readonly summary: AnalyticsSummary
+  readonly timeSeries: readonly TimeSeriesPoint[]
+}
+
+/**
+ * Query analytics overview: summary metrics + time series data.
+ */
+export const queryOverview = (
+  input: QueryOverviewInput
+): Effect.Effect<OverviewResult, AnalyticsDatabaseError, AnalyticsRepository> =>
+  Effect.gen(function* () {
+    const repo = yield* AnalyticsRepository
+
+    const params = {
+      appName: input.appName,
+      from: input.from,
+      to: input.to,
+      granularity: input.granularity,
+    }
+
+    const [summary, timeSeries] = yield* Effect.all([
+      repo.getSummary(params),
+      repo.getTimeSeries(params),
+    ])
+
+    return { summary, timeSeries }
+  })

package/src/application/use-cases/analytics/query-pages.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import { AnalyticsRepository } from '../../ports/repositories/analytics-repository'
+import type { AnalyticsDatabaseError, TopPage } from '../../ports/repositories/analytics-repository'
+
+export interface QueryPagesInput {
+  readonly appName: string
+  readonly from: Date
+  readonly to: Date
+}
+
+export interface TopPagesResult {
+  readonly pages: readonly TopPage[]
+  readonly total: number
+}
+
+/**
+ * Query top pages ranked by page views.
+ */
+export const queryPages = (
+  input: QueryPagesInput
+): Effect.Effect<TopPagesResult, AnalyticsDatabaseError, AnalyticsRepository> =>
+  Effect.gen(function* () {
+    const repo = yield* AnalyticsRepository
+
+    const pages = yield* repo.getTopPages({
+      appName: input.appName,
+      from: input.from,
+      to: input.to,
+      granularity: 'day', // Not used for top pages, but required by interface
+    })
+
+    return { pages, total: pages.length }
+  })

package/src/application/use-cases/analytics/query-referrers.ts

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+import { Effect } from 'effect'
+import { AnalyticsRepository } from '../../ports/repositories/analytics-repository'
+import type {
+  AnalyticsDatabaseError,
+  TopReferrer,
+} from '../../ports/repositories/analytics-repository'
+
+export interface QueryReferrersInput {
+  readonly appName: string
+  readonly from: Date
+  readonly to: Date
+}
+
+export interface TopReferrersResult {
+  readonly referrers: readonly TopReferrer[]
+  readonly total: number
+}
+
+/**
+ * Query top referrer domains ranked by page views.
+ */
+export const queryReferrers = (
+  input: QueryReferrersInput
+): Effect.Effect<TopReferrersResult, AnalyticsDatabaseError, AnalyticsRepository> =>
+  Effect.gen(function* () {
+    const repo = yield* AnalyticsRepository
+
+    const referrers = yield* repo.getTopReferrers({
+      appName: input.appName,
+      from: input.from,
+      to: input.to,
+      granularity: 'day',
+    })
+
+    return { referrers, total: referrers.length }
+  })

package/src/application/use-cases/analytics/ua-parser.ts

@@ -0,0 +1,89 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Lightweight User-Agent parser — zero external dependencies.
+ *
+ * Covers the major browsers, OS, and device types.
+ * Not exhaustive, but sufficient for analytics breakdown.
+ */
+
+export interface ParsedUserAgent {
+  readonly deviceType: 'desktop' | 'mobile' | 'tablet'
+  readonly browserName: string
+  readonly osName: string
+}
+
+/**
+ * Parse device type from User-Agent string.
+ *
+ * Detection order matters: tablet before mobile (tablets include mobile keywords).
+ */
+const parseDeviceType = (ua: string): 'desktop' | 'mobile' | 'tablet' => {
+  // Tablet detection (must come before mobile — iPads include "mobile" sometimes)
+  if (/ipad|tablet|playbook|silk/i.test(ua)) return 'tablet'
+  if (/android/i.test(ua) && !/mobile/i.test(ua)) return 'tablet'
+  // Mobile detection
+  if (/mobile|iphone|ipod|android.*mobile|windows phone|blackberry|opera mini|iemobile/i.test(ua))
+    return 'mobile'
+  // Default to desktop
+  return 'desktop'
+}
+
+/**
+ * Parse browser name from User-Agent string.
+ *
+ * Detection order matters: more specific browsers first (Edge before Chrome).
+ */
+const parseBrowserName = (ua: string): string => {
+  // Edge (Chromium-based includes "Edg/")
+  if (/edg\//i.test(ua)) return 'Edge'
+  // Opera (includes "OPR/" or "Opera")
+  if (/opr\//i.test(ua) || /opera/i.test(ua)) return 'Opera'
+  // Samsung Internet
+  if (/samsungbrowser/i.test(ua)) return 'Samsung Internet'
+  // Chrome (must be after Edge and Opera which also include "Chrome")
+  if (/chrome|crios/i.test(ua)) return 'Chrome'
+  // Safari (must be after Chrome — Chrome also includes "Safari")
+  if (/safari/i.test(ua) && !/chrome/i.test(ua)) return 'Safari'
+  // Firefox
+  if (/firefox|fxios/i.test(ua)) return 'Firefox'
+  // IE
+  if (/msie|trident/i.test(ua)) return 'IE'
+  return 'Other'
+}
+
+/**
+ * Parse OS name from User-Agent string.
+ */
+const parseOsName = (ua: string): string => {
+  // iOS (must be before macOS — iPads can include "Macintosh")
+  if (/iphone|ipad|ipod/i.test(ua)) return 'iOS'
+  // Android
+  if (/android/i.test(ua)) return 'Android'
+  // Windows
+  if (/windows/i.test(ua)) return 'Windows'
+  // macOS
+  if (/macintosh|mac os x/i.test(ua)) return 'macOS'
+  // Linux (must be after Android which includes "Linux")
+  if (/linux/i.test(ua)) return 'Linux'
+  // Chrome OS
+  if (/cros/i.test(ua)) return 'Chrome OS'
+  return 'Other'
+}
+
+/**
+ * Parse a User-Agent string into device type, browser, and OS.
+ *
+ * @param ua - User-Agent header string
+ * @returns Parsed device info with deviceType, browserName, osName
+ */
+export const parseUserAgent = (ua: string): ParsedUserAgent => ({
+  deviceType: parseDeviceType(ua),
+  browserName: parseBrowserName(ua),
+  osName: parseOsName(ua),
+})

package/src/application/use-cases/analytics/visitor-hash.ts

@@ -0,0 +1,77 @@
+/**
+ * Copyright (c) 2025 ESSENTIAL SERVICES
+ *
+ * This source code is licensed under the Business Source License 1.1
+ * found in the LICENSE.md file in the root directory of this source tree.
+ */
+
+/**
+ * Privacy-safe visitor identification using SHA-256 hashing.
+ *
+ * Hashing strategy:
+ * - Visitor hash: SHA-256(date + IP + UA + salt) — rotates daily, no PII stored
+ * - Session hash: SHA-256(visitorHash + timeWindow) — groups views into sessions
+ *
+ * Uses Web Crypto API (crypto.subtle) — zero external dependencies.
+ */
+
+/**
+ * Convert ArrayBuffer to hex string
+ */
+const toHex = (buffer: ArrayBuffer): string =>
+  Array.from(new Uint8Array(buffer))
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('')
+
+/**
+ * Compute SHA-256 hash of a string using Web Crypto API
+ */
+const sha256 = async (input: string): Promise<string> => {
+  const encoder = new TextEncoder()
+  const data = encoder.encode(input)
+  const hash = await crypto.subtle.digest('SHA-256', data)
+  return toHex(hash)
+}
+
+/**
+ * Compute a privacy-safe visitor hash.
+ *
+ * Hash rotates daily (date component), making it impossible to track
+ * a visitor across days. No cookies or PII are stored.
+ *
+ * @param ip - Client IP address (from X-Forwarded-For or connection)
+ * @param userAgent - Client User-Agent string
+ * @param salt - Application-specific salt for additional privacy
+ * @returns SHA-256 hex string (64 characters)
+ */
+export const computeVisitorHash = async (
+  ip: string,
+  userAgent: string,
+  salt: string
+): Promise<string> => {
+  const today = new Date().toISOString().slice(0, 10) // YYYY-MM-DD
+  return sha256(`${today}|${ip}|${userAgent}|${salt}`)
+}
+
+/**
+ * Compute a session hash from a visitor hash and session timeout.
+ *
+ * Sessions are grouped by time windows based on the configured timeout.
+ * A new session starts after the timeout period of inactivity.
+ *
+ * @param visitorHash - The visitor's daily hash
+ * @param sessionTimeoutMinutes - Session timeout in minutes (default: 30)
+ * @returns SHA-256 hex string (64 characters)
+ */
+export const computeSessionHash = async (
+  visitorHash: string,
+  sessionTimeoutMinutes: number = 30
+): Promise<string> => {
+  // Create time windows based on session timeout
+  // e.g., with 30min timeout: 0-29min -> window 0, 30-59min -> window 1
+  const now = new Date()
+  const minutesSinceMidnight = now.getHours() * 60 + now.getMinutes()
+  const timeWindow = Math.floor(minutesSinceMidnight / sessionTimeoutMinutes)
+  const dateStr = now.toISOString().slice(0, 10)
+  return sha256(`${visitorHash}|${dateStr}|${timeWindow}`)
+}