sovrium 0.0.2

package/src/presentation/api/routes/activity.ts

@@ -0,0 +1,339 @@
+/**
+ * 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 } from '@/application/use-cases/activity/programs'
+import {
+  type ActivityLogOutput,
+  ListActivityLogs,
+  ListActivityLogsLayer,
+} from '@/application/use-cases/list-activity-logs'
+import { getUserRole } from '@/application/use-cases/tables/user-role'
+import { DatabaseLive } from '@/infrastructure/database'
+import { getSessionContext } from '@/presentation/api/utils/context-helpers'
+import { sanitizeError, getStatusCode } from '@/presentation/api/utils/error-sanitizer'
+import type { Context, Hono } from 'hono'
+
+/**
+ * User metadata in activity log API response
+ */
+interface ActivityLogResponseUser {
+  readonly id: string
+  readonly name: string
+  readonly email: string
+}
+
+/**
+ * Activity log API response type
+ *
+ * Maps application ActivityLogOutput to API JSON response format.
+ * Uses camelCase for all fields per API conventions.
+ * user is null for system-logged activities (no user_id).
+ */
+interface ActivityLogResponse {
+  readonly id: string
+  readonly createdAt: string
+  readonly userId: string | undefined
+  readonly action: 'create' | 'update' | 'delete' | 'restore'
+  readonly tableName: string
+  readonly recordId: string
+  readonly user: ActivityLogResponseUser | null
+}
+
+/**
+ * Pagination metadata for list responses
+ */
+interface PaginationMeta {
+  readonly total: number
+  readonly page: number
+  readonly pageSize: number
+  readonly totalPages: number
+}
+
+/**
+ * Parsed and validated pagination parameters
+ */
+interface PaginationParams {
+  readonly page: number
+  readonly pageSize: number
+}
+
+/**
+ * Map ActivityLogOutput to API response format
+ */
+function mapToApiResponse(log: ActivityLogOutput): ActivityLogResponse {
+  return {
+    id: log.id,
+    createdAt: log.createdAt,
+    userId: log.userId,
+    action: log.action,
+    tableName: log.tableName,
+    recordId: log.recordId,
+    user: log.user,
+  }
+}
+
+/**
+ * Parse and validate pagination query parameters
+ *
+ * Returns undefined if parameters are invalid.
+ */
+function parsePaginationParams(
+  pageParam: string | undefined,
+  pageSizeParam: string | undefined
+): PaginationParams | undefined {
+  const page = pageParam === undefined ? 1 : parseInt(pageParam, 10)
+  const pageSize = pageSizeParam === undefined ? 50 : parseInt(pageSizeParam, 10)
+
+  if (isNaN(page) || page < 1) return undefined
+  if (isNaN(pageSize) || pageSize < 1 || pageSize > 100) return undefined
+
+  return { page, pageSize }
+}
+
+/**
+ * Build paginated response from activity log list
+ */
+function buildPaginatedResponse(
+  logs: readonly ActivityLogOutput[],
+  page: number,
+  pageSize: number
+): { activities: readonly ActivityLogResponse[]; pagination: PaginationMeta } {
+  const total = logs.length
+  const totalPages = Math.ceil(total / pageSize)
+  const start = (page - 1) * pageSize
+  const paginatedLogs = logs.slice(start, start + pageSize)
+  const pagination: PaginationMeta = { total, page, pageSize, totalPages }
+  return { activities: paginatedLogs.map(mapToApiResponse), pagination }
+}
+
+/**
+ * Handle GET /api/activity/:activityId - Get activity log details
+ */
+async function handleGetActivityById(c: Context) {
+  const activityId = c.req.param('activityId')
+
+  const program = GetActivityById(activityId).pipe(Effect.provide(DatabaseLive))
+
+  const result = await Effect.runPromise(program.pipe(Effect.either))
+
+  if (result._tag === 'Left') {
+    const error = result.left
+
+    if (error._tag === 'InvalidActivityIdError') {
+      return c.json(
+        { success: false, message: 'Invalid activity ID format', code: 'INVALID_ACTIVITY_ID' },
+        400
+      )
+    }
+
+    if (error._tag === 'ActivityNotFoundError') {
+      return c.json(
+        { success: false, message: 'Activity not found', code: 'ACTIVITY_NOT_FOUND' },
+        404
+      )
+    }
+
+    return c.json(
+      { success: false, message: 'Failed to fetch activity', code: 'DATABASE_ERROR' },
+      500
+    )
+  }
+
+  return c.json(result.right, 200)
+}
+
+/**
+ * Valid activity action types
+ */
+const VALID_ACTIONS = ['create', 'update', 'delete', 'restore'] as const
+
+/**
+ * Parse and validate action filter parameter
+ *
+ * Returns undefined if no filter, null if invalid value.
+ */
+function parseActionFilter(
+  action: string | undefined
+): 'create' | 'update' | 'delete' | 'restore' | undefined | null {
+  if (action === undefined) return undefined
+  if (VALID_ACTIONS.includes(action as (typeof VALID_ACTIONS)[number])) {
+    return action as 'create' | 'update' | 'delete' | 'restore'
+  }
+  // eslint-disable-next-line unicorn/no-null -- Null signals invalid action (vs undefined = no filter)
+  return null
+}
+
+/**
+ * Check if a user is authorized to filter by the given userId
+ *
+ * Admins can filter by any userId.
+ * Non-admin users can only filter by their own userId.
+ * Returns true if authorized, false if forbidden.
+ */
+async function isAuthorizedForUserIdFilter(
+  sessionUserId: string,
+  userIdFilter: string | undefined
+): Promise<boolean> {
+  if (userIdFilter === undefined) return true
+  if (userIdFilter === sessionUserId) return true
+  const role = await getUserRole(sessionUserId)
+  return role === 'admin'
+}
+
+/**
+ * Filter options for activity log queries
+ */
+interface ActivityFilters {
+  readonly tableName?: string
+  readonly action?: 'create' | 'update' | 'delete' | 'restore'
+  readonly userId?: string
+  readonly startDate?: Date
+}
+
+/**
+ * Apply tableName, action, userId, and startDate filters to activity logs
+ */
+function applyFilters(
+  logs: readonly ActivityLogOutput[],
+  filters: ActivityFilters
+): readonly ActivityLogOutput[] {
+  return logs.filter(
+    (log) =>
+      (filters.tableName === undefined || log.tableName === filters.tableName) &&
+      (filters.action === undefined || log.action === filters.action) &&
+      (filters.userId === undefined || log.userId === filters.userId) &&
+      (filters.startDate === undefined || new Date(log.createdAt) >= filters.startDate)
+  )
+}
+
+/**
+ * Parse query filter parameters from request context
+ *
+ * Returns undefined for tableName/userId if not provided,
+ * null for action if invalid value provided.
+ */
+function parseQueryFilters(c: Context): {
+  tableName: string | undefined
+  action: 'create' | 'update' | 'delete' | 'restore' | undefined | null
+  userId: string | undefined
+  startDate: Date | undefined
+} {
+  return {
+    tableName: c.req.query('tableName'),
+    action: parseActionFilter(c.req.query('action')),
+    userId: c.req.query('userId'),
+    startDate:
+      c.req.query('startDate') !== undefined ? new Date(c.req.query('startDate')!) : undefined,
+  }
+}
+
+/**
+ * Validation error response from list activity request validation
+ */
+interface ListActivityValidationError {
+  readonly status: number
+  readonly body: { success: false; message: string; code: string }
+}
+
+/**
+ * Validate list activity request parameters
+ *
+ * Returns error response object if invalid, or undefined if valid.
+ */
+async function validateListActivityRequest(
+  c: Context,
+  sessionUserId: string
+): Promise<ListActivityValidationError | undefined> {
+  const params = parsePaginationParams(c.req.query('page'), c.req.query('pageSize'))
+  if (params === undefined) {
+    return {
+      status: 400,
+      body: { success: false, message: 'Invalid pagination parameters', code: 'INVALID_PARAMETER' },
+    }
+  }
+
+  const { action } = parseQueryFilters(c)
+  if (action === null) {
+    return {
+      status: 400,
+      body: { success: false, message: 'Invalid action filter', code: 'INVALID_PARAMETER' },
+    }
+  }
+
+  const userIdFilter = c.req.query('userId')
+  const authorized = await isAuthorizedForUserIdFilter(sessionUserId, userIdFilter)
+  if (!authorized) {
+    return {
+      status: 403,
+      body: {
+        success: false,
+        message: 'Forbidden: cannot view other users activities',
+        code: 'FORBIDDEN',
+      },
+    }
+  }
+
+  return undefined
+}
+
+/**
+ * Handle GET /api/activity - List activity logs with pagination
+ */
+async function handleListActivityLogs(c: Context) {
+  const session = getSessionContext(c)
+  if (!session) {
+    return c.json({ success: false, message: 'Authentication required', code: 'UNAUTHORIZED' }, 401)
+  }
+
+  const validationError = await validateListActivityRequest(c, session.userId)
+  if (validationError !== undefined) {
+    return c.json(validationError.body, validationError.status as 400 | 403)
+  }
+
+  const params = parsePaginationParams(c.req.query('page'), c.req.query('pageSize'))!
+  const { tableName, action, userId, startDate } = parseQueryFilters(c)
+
+  const result = await Effect.runPromise(
+    ListActivityLogs({ userId: session.userId }).pipe(
+      Effect.provide(ListActivityLogsLayer),
+      Effect.either
+    )
+  )
+
+  if (result._tag === 'Left') {
+    const sanitized = sanitizeError(result.left, crypto.randomUUID())
+    return c.json(
+      { success: false, message: sanitized.message ?? sanitized.error, code: sanitized.code },
+      getStatusCode(sanitized.code)
+    )
+  }
+
+  const filtered = applyFilters(result.right, {
+    tableName,
+    action: action ?? undefined,
+    userId,
+    startDate,
+  })
+  return c.json(buildPaginatedResponse(filtered, params.page, params.pageSize), 200)
+}
+
+/**
+ * Chain activity routes onto a Hono app
+ *
+ * Provides:
+ * - GET /api/activity/:activityId - Get activity log details
+ * - GET /api/activity - List activity logs (admin/member only)
+ *
+ * @param honoApp - Hono instance to chain routes onto
+ * @returns Hono app with activity routes chained
+ */
+export function chainActivityRoutes<T extends Hono>(honoApp: T): T {
+  return honoApp
+    .get('/api/activity/:activityId', handleGetActivityById)
+    .get('/api/activity', handleListActivityLogs) as T
+}

package/src/presentation/api/routes/analytics.ts

@@ -0,0 +1,328 @@
+/**
+ * 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 { zValidator } from '@hono/zod-validator'
+import { Effect } from 'effect'
+import { collectPageView } from '@/application/use-cases/analytics/collect-page-view'
+import { purgeOldAnalyticsData } from '@/application/use-cases/analytics/purge-old-data'
+import { queryCampaigns } from '@/application/use-cases/analytics/query-campaigns'
+import { queryDevices } from '@/application/use-cases/analytics/query-devices'
+import { queryOverview } from '@/application/use-cases/analytics/query-overview'
+import { queryPages } from '@/application/use-cases/analytics/query-pages'
+import { queryReferrers } from '@/application/use-cases/analytics/query-referrers'
+import { analyticsCollectSchema, analyticsQuerySchema } from '@/domain/models/api/analytics'
+import { AnalyticsRepositoryLive } from '@/infrastructure/database/repositories/analytics-repository-live'
+import { matchesAnyGlobPattern } from '@/infrastructure/utils/glob-matcher'
+import { getSessionContext } from '@/presentation/api/utils/context-helpers'
+import type { Context, Hono } from 'hono'
+
+/**
+ * Extract client IP from request headers
+ */
+function extractClientIp(xForwardedFor: string | undefined): string {
+  if (xForwardedFor) {
+    const first = xForwardedFor.split(',')[0]
+    return first?.trim() ?? 'unknown'
+  }
+  return 'unknown'
+}
+
+/**
+ * Parse and validate analytics query parameters from request
+ */
+function parseAnalyticsQuery(
+  c: Context,
+  appName: string
+):
+  | {
+      readonly appName: string
+      readonly from: Date
+      readonly to: Date
+      readonly granularity: 'hour' | 'day' | 'week' | 'month'
+    }
+  | undefined {
+  const fromStr = c.req.query('from')
+  const toStr = c.req.query('to')
+  const validGranularities = new Set(['hour', 'day', 'week', 'month'])
+  const rawGranularity = c.req.query('granularity') ?? 'day'
+  const granularity = (validGranularities.has(rawGranularity) ? rawGranularity : 'day') as
+    | 'hour'
+    | 'day'
+    | 'week'
+    | 'month'
+
+  if (!fromStr || !toStr) return undefined
+
+  const parsed = analyticsQuerySchema.safeParse({ from: fromStr, to: toStr, granularity })
+  if (!parsed.success) return undefined
+
+  // Round `to` up to the end of its second so that the query range captures
+  // all events within the same wall-clock second.  Without this, sub-second
+  // differences between the client timestamp and server-side NOW() can exclude
+  // rows that logically fall within the requested window.
+  const toDate = new Date(parsed.data.to)
+  const toEndOfSecond = new Date(Math.ceil(toDate.getTime() / 1000) * 1000 + 999)
+
+  return {
+    appName,
+    from: new Date(parsed.data.from),
+    to: toEndOfSecond,
+    granularity: parsed.data.granularity,
+  }
+}
+
+/**
+ * Handle POST /api/analytics/collect — public endpoint, no auth required
+ *
+ * Records a page view with privacy-safe visitor hashing.
+ * Also triggers retention cleanup (fire-and-forget) to purge stale records.
+ * Returns 204 No Content for fastest response.
+ */
+// eslint-disable-next-line max-params -- All parameters are configured per-app and forwarded from route registration
+async function handleCollect(
+  c: Context,
+  appName: string,
+  retentionDays?: number,
+  excludedPaths?: readonly string[],
+  respectDoNotTrack?: boolean
+): Promise<Response> {
+  const body = c.req.valid('json' as never)
+  const pagePath = (body as { readonly p: string }).p
+
+  // Check if path is excluded - return 204 without recording
+  if (matchesAnyGlobPattern(excludedPaths, pagePath)) {
+    // eslint-disable-next-line unicorn/no-null
+    return c.body(null, 204)
+  }
+
+  // Check Do Not Track header when respectDoNotTrack is enabled
+  const dntHeader = c.req.header('DNT')
+  if (respectDoNotTrack && dntHeader === '1') {
+    // eslint-disable-next-line unicorn/no-null
+    return c.body(null, 204)
+  }
+
+  const ip = extractClientIp(c.req.header('x-forwarded-for'))
+  const userAgent = c.req.header('user-agent') ?? ''
+  const acceptLanguage = c.req.header('accept-language') ?? ''
+
+  // Fire-and-forget: record page view and purge stale data asynchronously
+  // eslint-disable-next-line functional/no-expression-statements
+  void Effect.runPromise(
+    Effect.all(
+      [
+        collectPageView({
+          appName,
+          pagePath,
+          pageTitle: (body as { readonly t?: string }).t,
+          referrerUrl: (body as { readonly r?: string }).r,
+          ip,
+          userAgent,
+          acceptLanguage,
+          screenWidth: (body as { readonly sw?: number }).sw,
+          screenHeight: (body as { readonly sh?: number }).sh,
+          utmSource: (body as { readonly us?: string }).us,
+          utmMedium: (body as { readonly um?: string }).um,
+          utmCampaign: (body as { readonly uc?: string }).uc,
+          utmContent: (body as { readonly ux?: string }).ux,
+          utmTerm: (body as { readonly ut?: string }).ut,
+        }),
+        purgeOldAnalyticsData(appName, retentionDays),
+      ],
+      { concurrency: 'unbounded' }
+    ).pipe(
+      Effect.provide(AnalyticsRepositoryLive),
+      Effect.catchAll(() => Effect.void)
+    )
+  )
+
+  // eslint-disable-next-line unicorn/no-null
+  return c.body(null, 204)
+}
+
+/**
+ * Handle GET /api/analytics/overview — requires auth
+ */
+async function handleOverview(c: Context, appName: string): Promise<Response> {
+  const session = getSessionContext(c)
+  if (!session) {
+    return c.json({ error: 'Authentication required', code: 'UNAUTHORIZED' }, 401)
+  }
+
+  const params = parseAnalyticsQuery(c, appName)
+  if (!params) {
+    return c.json({ error: 'Missing or invalid from/to parameters', code: 'VALIDATION_ERROR' }, 400)
+  }
+
+  const result = await Effect.runPromise(
+    queryOverview({
+      appName: params.appName,
+      from: params.from,
+      to: params.to,
+      granularity: params.granularity,
+    }).pipe(Effect.provide(AnalyticsRepositoryLive), Effect.either)
+  )
+
+  if (result._tag === 'Left') {
+    return c.json({ error: 'Failed to query analytics', code: 'INTERNAL_ERROR' }, 500)
+  }
+
+  return c.json(result.right, 200)
+}
+
+/**
+ * Handle GET /api/analytics/pages — requires auth
+ */
+async function handlePages(c: Context, appName: string): Promise<Response> {
+  const session = getSessionContext(c)
+  if (!session) {
+    return c.json({ error: 'Authentication required', code: 'UNAUTHORIZED' }, 401)
+  }
+
+  const params = parseAnalyticsQuery(c, appName)
+  if (!params) {
+    return c.json({ error: 'Missing or invalid from/to parameters', code: 'VALIDATION_ERROR' }, 400)
+  }
+
+  const result = await Effect.runPromise(
+    queryPages({
+      appName: params.appName,
+      from: params.from,
+      to: params.to,
+    }).pipe(Effect.provide(AnalyticsRepositoryLive), Effect.either)
+  )
+
+  if (result._tag === 'Left') {
+    return c.json({ error: 'Failed to query pages', code: 'INTERNAL_ERROR' }, 500)
+  }
+
+  return c.json(result.right, 200)
+}
+
+/**
+ * Handle GET /api/analytics/referrers — requires auth
+ */
+async function handleReferrers(c: Context, appName: string): Promise<Response> {
+  const session = getSessionContext(c)
+  if (!session) {
+    return c.json({ error: 'Authentication required', code: 'UNAUTHORIZED' }, 401)
+  }
+
+  const params = parseAnalyticsQuery(c, appName)
+  if (!params) {
+    return c.json({ error: 'Missing or invalid from/to parameters', code: 'VALIDATION_ERROR' }, 400)
+  }
+
+  const result = await Effect.runPromise(
+    queryReferrers({
+      appName: params.appName,
+      from: params.from,
+      to: params.to,
+    }).pipe(Effect.provide(AnalyticsRepositoryLive), Effect.either)
+  )
+
+  if (result._tag === 'Left') {
+    return c.json({ error: 'Failed to query referrers', code: 'INTERNAL_ERROR' }, 500)
+  }
+
+  return c.json(result.right, 200)
+}
+
+/**
+ * Handle GET /api/analytics/devices — requires auth
+ */
+async function handleDevices(c: Context, appName: string): Promise<Response> {
+  const session = getSessionContext(c)
+  if (!session) {
+    return c.json({ error: 'Authentication required', code: 'UNAUTHORIZED' }, 401)
+  }
+
+  const params = parseAnalyticsQuery(c, appName)
+  if (!params) {
+    return c.json({ error: 'Missing or invalid from/to parameters', code: 'VALIDATION_ERROR' }, 400)
+  }
+
+  const result = await Effect.runPromise(
+    queryDevices({
+      appName: params.appName,
+      from: params.from,
+      to: params.to,
+    }).pipe(Effect.provide(AnalyticsRepositoryLive), Effect.either)
+  )
+
+  if (result._tag === 'Left') {
+    return c.json({ error: 'Failed to query devices', code: 'INTERNAL_ERROR' }, 500)
+  }
+
+  return c.json(result.right, 200)
+}
+
+/**
+ * Handle GET /api/analytics/campaigns — requires auth
+ */
+async function handleCampaigns(c: Context, appName: string): Promise<Response> {
+  const session = getSessionContext(c)
+  if (!session) {
+    return c.json({ error: 'Authentication required', code: 'UNAUTHORIZED' }, 401)
+  }
+
+  const params = parseAnalyticsQuery(c, appName)
+  if (!params) {
+    return c.json({ error: 'Missing or invalid from/to parameters', code: 'VALIDATION_ERROR' }, 400)
+  }
+
+  const result = await Effect.runPromise(
+    queryCampaigns({
+      appName: params.appName,
+      from: params.from,
+      to: params.to,
+    }).pipe(Effect.provide(AnalyticsRepositoryLive), Effect.either)
+  )
+
+  if (result._tag === 'Left') {
+    return c.json({ error: 'Failed to query campaigns', code: 'INTERNAL_ERROR' }, 500)
+  }
+
+  return c.json(result.right, 200)
+}
+
+/**
+ * Chain analytics routes onto a Hono app
+ *
+ * Provides:
+ * - POST /api/analytics/collect - Record page view (public, no auth)
+ * - GET /api/analytics/overview - Summary + time series (auth required)
+ * - GET /api/analytics/pages - Top pages (auth required)
+ * - GET /api/analytics/referrers - Top referrers (auth required)
+ * - GET /api/analytics/devices - Device breakdown (auth required)
+ * - GET /api/analytics/campaigns - UTM campaigns (auth required)
+ *
+ * @param honoApp - Hono instance to chain routes onto
+ * @param appName - Application name for multi-tenant analytics
+ * @param retentionDays - Number of days to retain analytics data (triggers cleanup on collect)
+ * @param excludedPaths - Glob patterns for paths excluded from tracking
+ * @param respectDoNotTrack - Whether to honor Do Not Track (DNT:1) header
+ * @returns Hono app with analytics routes chained
+ */
+// eslint-disable-next-line max-params -- All parameters are configured per-app and forwarded from route setup
+export function chainAnalyticsRoutes<T extends Hono>(
+  honoApp: T,
+  appName: string,
+  retentionDays?: number,
+  excludedPaths?: readonly string[],
+  respectDoNotTrack?: boolean
+): T {
+  return honoApp
+    .post('/api/analytics/collect', zValidator('json', analyticsCollectSchema), (c) =>
+      handleCollect(c, appName, retentionDays, excludedPaths, respectDoNotTrack)
+    )
+    .get('/api/analytics/overview', (c) => handleOverview(c, appName))
+    .get('/api/analytics/pages', (c) => handlePages(c, appName))
+    .get('/api/analytics/referrers', (c) => handleReferrers(c, appName))
+    .get('/api/analytics/devices', (c) => handleDevices(c, appName))
+    .get('/api/analytics/campaigns', (c) => handleCampaigns(c, appName)) as T
+}