sovrium 0.0.2

package/src/application/errors/app-validation-error.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { createTaggedError } from '@/domain/errors/create-tagged-error'
+
+/**
+ * Error class for app validation failures
+ */
+export const AppValidationError = createTaggedError('AppValidationError')
+export type AppValidationError = InstanceType<typeof AppValidationError>

package/src/application/errors/static-generation-error.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 { Data } from 'effect'
+
+/**
+ * Error class for static site generation failures
+ */
+export class StaticGenerationError extends Data.TaggedError('StaticGenerationError')<{
+  readonly message: string
+  readonly cause?: unknown
+}> {}

package/src/application/metadata/favicon-transformer.ts

@@ -0,0 +1,127 @@
+/**
+ * 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 type { FaviconSet } from '@/domain/models/app/page/meta/favicon-set'
+import type { FaviconsConfig } from '@/domain/models/app/page/meta/favicons-config'
+
+/**
+ * Normalizes a favicon path to ensure it starts with './'
+ *
+ * @param href - Favicon path (with or without './' prefix)
+ * @returns Path guaranteed to start with './'
+ *
+ * @example
+ * ```typescript
+ * normalizeFaviconPath('/icon.svg')    // './icon.svg'
+ * normalizeFaviconPath('./icon.svg')   // './icon.svg'
+ * normalizeFaviconPath('icon.svg')     // './icon.svg'
+ * ```
+ */
+function normalizeFaviconPath(href: string): string {
+  return href.startsWith('./') ? href : `.${href}`
+}
+
+/**
+ * Transforms FaviconsConfig (object format) to FaviconSet (array format)
+ *
+ * This function converts the simplified object-based configuration format
+ * into the array-based FaviconSet format expected by the rendering components.
+ *
+ * Transformation rules:
+ * - icon → { rel: 'icon', type: 'image/svg+xml', href: icon }
+ * - appleTouchIcon → { rel: 'apple-touch-icon', href: appleTouchIcon }
+ * - sizes → { rel: 'icon', type: 'image/png', sizes: size, href: href }
+ *
+ * @param config - FaviconsConfig object with named properties
+ * @returns FaviconSet array with favicon items
+ *
+ * @example
+ * ```typescript
+ * const config = {
+ *   icon: '/icon.svg',
+ *   appleTouchIcon: '/apple-touch-icon.png',
+ *   sizes: [
+ *     { size: '32x32', href: '/favicon-32x32.png' },
+ *     { size: '16x16', href: '/favicon-16x16.png' }
+ *   ]
+ * }
+ *
+ * const faviconSet = transformFaviconsConfigToSet(config)
+ * // [
+ * //   { rel: 'icon', type: 'image/svg+xml', href: './icon.svg' },
+ * //   { rel: 'apple-touch-icon', href: './apple-touch-icon.png' },
+ * //   { rel: 'icon', type: 'image/png', sizes: '32x32', href: './favicon-32x32.png' },
+ * //   { rel: 'icon', type: 'image/png', sizes: '16x16', href: './favicon-16x16.png' }
+ * // ]
+ * ```
+ */
+export function transformFaviconsConfigToSet(config: FaviconsConfig): FaviconSet {
+  // Transform icon
+  const iconItems = config.icon
+    ? [
+        {
+          rel: 'icon' as const,
+          type: 'image/svg+xml' as const,
+          href: normalizeFaviconPath(config.icon),
+        },
+      ]
+    : []
+
+  // Transform appleTouchIcon
+  const appleTouchIconItems = config.appleTouchIcon
+    ? [
+        {
+          rel: 'apple-touch-icon' as const,
+          href: normalizeFaviconPath(config.appleTouchIcon),
+        },
+      ]
+    : []
+
+  // Transform sizes
+  const sizeItems =
+    config.sizes?.map((sizeItem) => ({
+      rel: 'icon' as const,
+      type: 'image/png' as const,
+      sizes: sizeItem.size,
+      href: normalizeFaviconPath(sizeItem.href),
+    })) ?? []
+
+  return [...iconItems, ...appleTouchIconItems, ...sizeItems]
+}
+
+/**
+ * Type guard to check if favicons is FaviconsConfig (object format)
+ */
+export function isFaviconsConfig(
+  favicons: FaviconSet | FaviconsConfig | undefined
+): favicons is FaviconsConfig {
+  if (!favicons) return false
+  return (
+    !Array.isArray(favicons) &&
+    typeof favicons === 'object' &&
+    ('icon' in favicons || 'appleTouchIcon' in favicons || 'sizes' in favicons)
+  )
+}
+
+/**
+ * Normalizes favicons to FaviconSet array format
+ *
+ * Accepts both FaviconSet (array) and FaviconsConfig (object) formats,
+ * returning a normalized FaviconSet array.
+ *
+ * @param favicons - Favicons in either format
+ * @returns FaviconSet array or undefined
+ */
+export function normalizeFavicons(
+  favicons: FaviconSet | FaviconsConfig | undefined
+): FaviconSet | undefined {
+  if (!favicons) return undefined
+  if (isFaviconsConfig(favicons)) {
+    return transformFaviconsConfigToSet(favicons)
+  }
+  return favicons as FaviconSet
+}

package/src/application/models/server.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 type { Effect } from 'effect'
+import type { Hono } from 'hono'
+
+/**
+ * Running server instance with stop capability
+ *
+ * This represents a domain concept of a running web server
+ * that can be controlled (stopped) through Effect operations.
+ *
+ * The actual server implementation (Bun.serve) is hidden
+ * behind this interface to maintain layer separation.
+ *
+ * The Hono app is exposed for static site generation (SSG) purposes.
+ */
+export interface ServerInstance {
+  readonly server: ReturnType<typeof Bun.serve>
+  readonly url: string
+  readonly stop: Effect.Effect<void>
+  readonly app: Readonly<Hono>
+}

package/src/application/ports/models/user-metadata.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.
+ */
+
+/**
+ * Minimal user metadata embedded in domain records
+ *
+ * Represents the common shape returned by user-joined queries
+ * (activity logs, comments, activity history). Defined at the
+ * application boundary so both application and infrastructure
+ * layers can reference the same contract.
+ *
+ * Variants:
+ * - `UserMetadata` — core fields (id, name, email)
+ * - `UserMetadataWithImage` — adds optional image (comments, activity history)
+ */
+export interface UserMetadata {
+  readonly id: string
+  readonly name: string
+  readonly email: string
+}
+
+export interface UserMetadataWithImage extends UserMetadata {
+  readonly image: string | null | undefined
+}
+
+/**
+ * Variant with image typed as `string | undefined` only (no null).
+ * Used by comment queries where infrastructure converts null → undefined.
+ */
+export interface UserMetadataWithOptionalImage extends UserMetadata {
+  readonly image: string | undefined
+}

package/src/application/ports/models/user-session.ts

@@ -0,0 +1,34 @@
+/**
+ * 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.
+ */
+
+/**
+ * User session interface for application layer
+ *
+ * Structurally compatible with Better Auth's Session type
+ * so infrastructure implementations can accept it without conversion.
+ * Application layer uses this instead of importing from infrastructure.
+ */
+export interface UserSession {
+  readonly id: string
+  readonly userId: string
+  readonly token: string
+  readonly expiresAt: Date
+  readonly createdAt: Date
+  readonly updatedAt: Date
+  readonly ipAddress: string | null
+  readonly userAgent: string | null
+  readonly impersonatedBy: string | null
+}
+
+/**
+ * Session type alias for backward compatibility
+ *
+ * Allows presentation layer to import Session from the application
+ * boundary instead of reaching into infrastructure. Structurally
+ * compatible with the Drizzle-inferred Session type from Better Auth.
+ */
+export type Session = UserSession

package/src/application/ports/repositories/activity-log-repository.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 { Context, Data } from 'effect'
+import type { UserMetadata } from '@/application/ports/models/user-metadata'
+import type { Effect } from 'effect'
+
+/**
+ * Activity Log record type (port-level definition)
+ *
+ * Structurally compatible with the Drizzle schema inference.
+ * Defined here to avoid application→infrastructure dependency.
+ */
+export interface ActivityLog {
+  readonly id: string
+  readonly createdAt: Date
+  readonly userId: string | null
+  readonly sessionId: string | null
+  readonly action: 'create' | 'update' | 'delete' | 'restore'
+  readonly tableName: string
+  readonly tableId: string | null
+  readonly recordId: string
+  readonly changes: {
+    readonly before?: Record<string, unknown>
+    readonly after?: Record<string, unknown>
+  } | null
+  readonly ipAddress: string | null
+  readonly userAgent: string | null
+  readonly user?: UserMetadata | null | undefined
+}
+
+/**
+ * Database error for activity log operations
+ */
+export class ActivityLogDatabaseError extends Data.TaggedError('ActivityLogDatabaseError')<{
+  readonly cause: unknown
+}> {}
+
+/**
+ * Activity Log Repository Port
+ *
+ * Provides type-safe database operations for activity logs.
+ * Implementation lives in infrastructure layer (activity-log-repository-live.ts).
+ */
+export class ActivityLogRepository extends Context.Tag('ActivityLogRepository')<
+  ActivityLogRepository,
+  {
+    readonly listAll: () => Effect.Effect<readonly ActivityLog[], ActivityLogDatabaseError>
+    readonly create: (log: {
+      readonly userId: string
+      readonly action: 'create' | 'update' | 'delete' | 'restore'
+      readonly tableName: string
+      readonly tableId: string
+      readonly recordId: string
+      readonly changes: {
+        readonly before?: Record<string, unknown>
+        readonly after?: Record<string, unknown>
+      }
+      readonly sessionId?: string
+      readonly ipAddress?: string
+      readonly userAgent?: string
+    }) => Effect.Effect<ActivityLog, ActivityLogDatabaseError>
+  }
+>() {}

package/src/application/ports/repositories/activity-repository.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { Context } from 'effect'
+import type { UserMetadataWithImage } from '@/application/ports/models/user-metadata'
+import type { UserSession } from '@/application/ports/models/user-session'
+import type { SessionContextError } from '@/domain/errors'
+import type { Effect } from 'effect'
+
+/**
+ * Activity history entry with user metadata
+ */
+export interface ActivityHistoryEntry {
+  readonly action: string
+  readonly createdAt: Date
+  readonly changes: unknown
+  readonly user: UserMetadataWithImage | undefined
+}
+
+/**
+ * Activity Repository Port
+ */
+export class ActivityRepository extends Context.Tag('ActivityRepository')<
+  ActivityRepository,
+  {
+    readonly getRecordHistory: (config: {
+      readonly session: Readonly<UserSession>
+      readonly tableName: string
+      readonly recordId: string
+      readonly limit?: number
+      readonly offset?: number
+    }) => Effect.Effect<
+      {
+        readonly entries: readonly ActivityHistoryEntry[]
+        readonly total: number
+      },
+      SessionContextError
+    >
+    readonly checkRecordExists: (config: {
+      readonly session: Readonly<UserSession>
+      readonly tableName: string
+      readonly recordId: string
+    }) => Effect.Effect<boolean, SessionContextError>
+  }
+>() {}

package/src/application/ports/repositories/analytics-repository.ts

@@ -0,0 +1,164 @@
+/**
+ * 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 { Context, Data } from 'effect'
+import type { Effect } from 'effect'
+
+// ============================================================================
+// Port-level types (avoid infrastructure dependency)
+// ============================================================================
+
+/**
+ * Page view input for recording a new event
+ */
+export interface PageViewInput {
+  readonly appName: string
+  readonly pagePath: string
+  readonly pageTitle?: string
+  readonly visitorHash: string
+  readonly sessionHash: string
+  readonly isEntrance: boolean
+  readonly referrerUrl?: string
+  readonly referrerDomain?: string
+  readonly utmSource?: string
+  readonly utmMedium?: string
+  readonly utmCampaign?: string
+  readonly utmContent?: string
+  readonly utmTerm?: string
+  readonly deviceType?: string
+  readonly browserName?: string
+  readonly osName?: string
+  readonly language?: string
+  readonly screenWidth?: number
+  readonly screenHeight?: number
+}
+
+/**
+ * Query parameters for analytics data retrieval
+ */
+export interface AnalyticsQueryParams {
+  readonly appName: string
+  readonly from: Date
+  readonly to: Date
+  readonly granularity: 'hour' | 'day' | 'week' | 'month'
+}
+
+/**
+ * Time series data point
+ */
+export interface TimeSeriesPoint {
+  readonly period: string
+  readonly pageViews: number
+  readonly uniqueVisitors: number
+  readonly sessions: number
+}
+
+/**
+ * Summary metrics
+ */
+export interface AnalyticsSummary {
+  readonly pageViews: number
+  readonly uniqueVisitors: number
+  readonly sessions: number
+}
+
+/**
+ * Top page entry
+ */
+export interface TopPage {
+  readonly path: string
+  readonly pageViews: number
+  readonly uniqueVisitors: number
+}
+
+/**
+ * Top referrer entry
+ */
+export interface TopReferrer {
+  readonly domain: string | null
+  readonly pageViews: number
+  readonly uniqueVisitors: number
+}
+
+/**
+ * Breakdown entry (device type, browser, OS)
+ */
+export interface BreakdownEntry {
+  readonly name: string
+  readonly count: number
+  readonly percentage: number
+}
+
+/**
+ * Device breakdown result
+ */
+export interface DeviceBreakdown {
+  readonly deviceTypes: readonly BreakdownEntry[]
+  readonly browsers: readonly BreakdownEntry[]
+  readonly operatingSystems: readonly BreakdownEntry[]
+}
+
+/**
+ * Campaign entry
+ */
+export interface CampaignEntry {
+  readonly source: string | null
+  readonly medium: string | null
+  readonly campaign: string | null
+  readonly pageViews: number
+  readonly uniqueVisitors: number
+}
+
+// ============================================================================
+// Error type
+// ============================================================================
+
+/**
+ * Database error for analytics operations
+ */
+export class AnalyticsDatabaseError extends Data.TaggedError('AnalyticsDatabaseError')<{
+  readonly cause: unknown
+}> {}
+
+// ============================================================================
+// Repository port
+// ============================================================================
+
+/**
+ * Analytics Repository Port
+ *
+ * Provides type-safe database operations for analytics page views.
+ * Implementation lives in infrastructure layer (analytics-repository-live.ts).
+ */
+export class AnalyticsRepository extends Context.Tag('AnalyticsRepository')<
+  AnalyticsRepository,
+  {
+    readonly recordPageView: (input: PageViewInput) => Effect.Effect<void, AnalyticsDatabaseError>
+    readonly getTimeSeries: (
+      params: AnalyticsQueryParams
+    ) => Effect.Effect<readonly TimeSeriesPoint[], AnalyticsDatabaseError>
+    readonly getSummary: (
+      params: AnalyticsQueryParams
+    ) => Effect.Effect<AnalyticsSummary, AnalyticsDatabaseError>
+    readonly getTopPages: (
+      params: AnalyticsQueryParams
+    ) => Effect.Effect<readonly TopPage[], AnalyticsDatabaseError>
+    readonly getTopReferrers: (
+      params: AnalyticsQueryParams
+    ) => Effect.Effect<readonly TopReferrer[], AnalyticsDatabaseError>
+    readonly getDevices: (
+      params: AnalyticsQueryParams
+    ) => Effect.Effect<DeviceBreakdown, AnalyticsDatabaseError>
+    readonly getCampaigns: (
+      params: AnalyticsQueryParams
+    ) => Effect.Effect<readonly CampaignEntry[], AnalyticsDatabaseError>
+    readonly deleteOlderThan: (
+      appName: string,
+      cutoff: Date
+    ) => Effect.Effect<number, AnalyticsDatabaseError>
+  }
+>() {}

package/src/application/ports/repositories/auth-repository.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 { Context, Data } from 'effect'
+import type { Effect } from 'effect'
+
+/**
+ * Database error for auth operations (users table)
+ */
+export class AuthDatabaseError extends Data.TaggedError('AuthDatabaseError')<{
+  readonly cause: unknown
+}> {}
+
+/**
+ * Auth Repository Port
+ *
+ * Provides type-safe database operations for authentication-related
+ * user management (email verification, role lookup).
+ * Both methods operate on the Better Auth `users` table.
+ *
+ * Implementation lives in infrastructure layer (auth-repository-live.ts).
+ */
+export class AuthRepository extends Context.Tag('AuthRepository')<
+  AuthRepository,
+  {
+    readonly verifyUserEmail: (userId: string) => Effect.Effect<void, AuthDatabaseError>
+    readonly getUserRole: (userId: string) => Effect.Effect<string | undefined, AuthDatabaseError>
+  }
+>() {}

package/src/application/ports/repositories/batch-repository.ts

@@ -0,0 +1,86 @@
+/**
+ * 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 { Context } from 'effect'
+import type { UserSession } from '@/application/ports/models/user-session'
+import type { SessionContextError, ValidationError } from '@/domain/errors'
+import type { Effect } from 'effect'
+
+/**
+ * Batch validation error interface
+ *
+ * Structurally compatible with infrastructure's BatchValidationError
+ * (Data.TaggedError). Defined here so application layer doesn't need
+ * to import from infrastructure.
+ */
+export interface BatchValidationError extends Error {
+  readonly _tag: 'BatchValidationError'
+  readonly message: string
+  readonly details?: readonly string[]
+}
+
+/**
+ * Upsert operation result
+ */
+export interface UpsertResult {
+  readonly records: readonly Record<string, unknown>[]
+  readonly created: number
+  readonly updated: number
+}
+
+/**
+ * Batch Repository port for batch operations
+ *
+ * Defines the contract for bulk create, update, delete, restore, and upsert.
+ *
+ * @example
+ * ```typescript
+ * const program = Effect.gen(function* () {
+ *   const batch = yield* BatchRepository
+ *   const result = yield* batch.batchCreate(session, 'users', records)
+ * })
+ * ```
+ */
+export class BatchRepository extends Context.Tag('BatchRepository')<
+  BatchRepository,
+  {
+    readonly batchCreate: (
+      session: Readonly<UserSession>,
+      tableName: string,
+      recordsData: readonly Record<string, unknown>[]
+    ) => Effect.Effect<readonly Record<string, unknown>[], SessionContextError | ValidationError>
+
+    readonly batchUpdate: (
+      session: Readonly<UserSession>,
+      tableName: string,
+      updates: readonly {
+        readonly id: string
+        readonly fields?: Record<string, unknown>
+      }[]
+    ) => Effect.Effect<readonly Record<string, unknown>[], SessionContextError | ValidationError>
+
+    readonly batchDelete: (
+      session: Readonly<UserSession>,
+      tableName: string,
+      recordIds: readonly string[],
+      permanent?: boolean
+    ) => Effect.Effect<number, SessionContextError>
+
+    readonly batchRestore: (
+      session: Readonly<UserSession>,
+      tableName: string,
+      recordIds: readonly string[]
+    ) => Effect.Effect<number, SessionContextError>
+
+    readonly upsert: (
+      session: Readonly<UserSession>,
+      tableName: string,
+      recordsData: readonly Record<string, unknown>[],
+      fieldsToMergeOn: readonly string[]
+    ) => Effect.Effect<UpsertResult, SessionContextError | BatchValidationError | ValidationError>
+  }
+>() {}