sovrium 0.0.2

package/src/infrastructure/database/table-queries/mutation-helpers/delete-helpers.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 { sql } from 'drizzle-orm'
+import { SessionContextError } from '@/domain/errors'
+import { validateTableName, validateColumnName } from '../shared/validation'
+import { hasDeletedByColumn, getDeletedByValue } from './authorship-helpers'
+import type { DrizzleTransaction } from '@/infrastructure/database/drizzle/db'
+
+/**
+ * Cascade soft delete to related records
+ *
+ * Helper function to cascade soft delete to child records based on onDelete: 'cascade' configuration
+ */
+// eslint-disable-next-line max-params, max-lines-per-function -- Cascade delete requires app config, userId, and complex conditional logic for deleted_by
+export async function cascadeSoftDelete(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordId: string,
+  app: {
+    readonly tables?: ReadonlyArray<{
+      readonly name: string
+      readonly fields: ReadonlyArray<{
+        readonly name: string
+        readonly type: string
+        readonly relatedTable?: string
+        readonly onDelete?: string
+      }>
+    }>
+  },
+  userId?: string
+): Promise<void> {
+  if (!app.tables) return
+
+  // Find all tables with relationship fields that reference this table with onDelete: 'cascade'
+  const relatedTables = app.tables.flatMap((table) =>
+    table.fields
+      .filter(
+        (field) =>
+          field.type === 'relationship' &&
+          field.relatedTable === tableName &&
+          field.onDelete === 'cascade'
+      )
+      .map((field) => ({
+        tableName: table.name,
+        fieldName: field.name,
+      }))
+  )
+
+  const deletedByValue = getDeletedByValue(userId)
+
+  // Cascade soft delete to each related table
+  // eslint-disable-next-line functional/no-expression-statements -- Database updates for cascade delete are required side effects
+  await Promise.all(
+    relatedTables.map(async (relatedInfo) => {
+      const childTable = relatedInfo.tableName
+      const childColumn = relatedInfo.fieldName
+
+      validateTableName(childTable)
+      validateColumnName(childColumn)
+
+      // Check if child table has deleted_at column
+      const childColumnCheck = (await tx.execute(
+        sql`SELECT column_name FROM information_schema.columns WHERE table_name = ${childTable} AND column_name = 'deleted_at'`
+      )) as readonly Record<string, unknown>[]
+
+      if (childColumnCheck.length > 0) {
+        // Check if child table has deleted_by column (using helper)
+        const hasDeletedByCol = await hasDeletedByColumn(tx, childTable)
+
+        // Cascade soft delete to related records with deleted_by if column exists
+        if (hasDeletedByCol) {
+          // eslint-disable-next-line functional/no-expression-statements -- Database update for cascade is required
+          await tx.execute(
+            sql`UPDATE ${sql.identifier(childTable)} SET deleted_at = NOW(), deleted_by = ${deletedByValue} WHERE ${sql.identifier(childColumn)} = ${recordId} AND deleted_at IS NULL`
+          )
+        } else {
+          // eslint-disable-next-line functional/no-expression-statements -- Database update for cascade is required
+          await tx.execute(
+            sql`UPDATE ${sql.identifier(childTable)} SET deleted_at = NOW() WHERE ${sql.identifier(childColumn)} = ${recordId} AND deleted_at IS NULL`
+          )
+        }
+      }
+    })
+  )
+}
+
+/**
+ * Execute soft delete operation
+ * Promise-based for transaction use
+ */
+export async function executeSoftDelete(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordId: string,
+  userId?: string
+): Promise<boolean> {
+  try {
+    // Check if table has deleted_by column using helper
+    const hasDeletedByCol = await hasDeletedByColumn(tx, tableName)
+    const deletedByValue = getDeletedByValue(userId)
+
+    const tableIdent = sql.identifier(tableName)
+
+    // Build UPDATE query with or without deleted_by
+    const result = hasDeletedByCol
+      ? ((await tx.execute(
+          sql`UPDATE ${tableIdent} SET deleted_at = NOW(), deleted_by = ${deletedByValue} WHERE id = ${recordId} AND deleted_at IS NULL RETURNING id`
+        )) as readonly Record<string, unknown>[])
+      : ((await tx.execute(
+          sql`UPDATE ${tableIdent} SET deleted_at = NOW() WHERE id = ${recordId} AND deleted_at IS NULL RETURNING id`
+        )) as readonly Record<string, unknown>[])
+
+    return result.length > 0
+  } catch (error) {
+    // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+    throw new SessionContextError(`Failed to delete record ${recordId} from ${tableName}`, error)
+  }
+}
+
+/**
+ * Execute hard delete operation
+ * Promise-based for transaction use
+ */
+export async function executeHardDelete(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordId: string
+): Promise<boolean> {
+  try {
+    const tableIdent = sql.identifier(tableName)
+    const result = (await tx.execute(
+      sql`DELETE FROM ${tableIdent} WHERE id = ${recordId} RETURNING id`
+    )) as readonly Record<string, unknown>[]
+    return result.length > 0
+  } catch (error) {
+    // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+    throw new SessionContextError(`Failed to delete record ${recordId} from ${tableName}`, error)
+  }
+}
+
+/**
+ * Check if table has deleted_at column for soft delete support
+ * Promise-based for transaction use
+ */
+export async function checkDeletedAtColumn(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string
+): Promise<boolean> {
+  try {
+    const columnCheck = (await tx.execute(
+      sql`SELECT column_name FROM information_schema.columns WHERE table_name = ${tableName} AND column_name = 'deleted_at'`
+    )) as readonly Record<string, unknown>[]
+    return columnCheck.length > 0
+  } catch (error) {
+    // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+    throw new SessionContextError(`Failed to check columns for ${tableName}`, error)
+  }
+}

package/src/infrastructure/database/table-queries/mutation-helpers/record-fetch-helpers.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 { sql } from 'drizzle-orm'
+import { Effect } from 'effect'
+import { SessionContextError } from '@/domain/errors'
+import type { DrizzleTransaction } from '@/infrastructure/database/drizzle/db'
+
+/**
+ * Fetch a single record by ID (Promise-based for transaction use)
+ *
+ * Used before mutations (update/delete) for activity logging.
+ * Throws SessionContextError on database failure.
+ */
+export async function fetchRecordById(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordId: string
+): Promise<Record<string, unknown> | undefined> {
+  try {
+    const result = (await tx.execute(
+      sql`SELECT * FROM ${sql.identifier(tableName)} WHERE id = ${recordId} LIMIT 1`
+    )) as readonly Record<string, unknown>[]
+    return result[0]
+  } catch (error) {
+    // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+    throw new SessionContextError(`Failed to fetch record ${recordId}`, error)
+  }
+}
+
+/**
+ * Fetch a single record by ID (Effect-based for batch operations)
+ *
+ * Returns undefined on error — non-critical for batch activity logging.
+ */
+export function fetchRecordByIdEffect(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordId: string
+): Effect.Effect<Record<string, unknown> | undefined, never> {
+  return Effect.tryPromise({
+    try: async () => {
+      const result = (await tx.execute(
+        sql`SELECT * FROM ${sql.identifier(tableName)} WHERE id = ${recordId} LIMIT 1`
+      )) as readonly Record<string, unknown>[]
+      return result[0]
+    },
+    catch: () => undefined,
+  }).pipe(Effect.orElseSucceed(() => undefined))
+}
+
+/**
+ * Fetch multiple records by IDs (Effect-based for batch operations)
+ *
+ * Fails with SessionContextError on database failure.
+ */
+export function fetchRecordsByIds(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordIds: readonly string[]
+): Effect.Effect<readonly Record<string, unknown>[], SessionContextError> {
+  return Effect.tryPromise({
+    try: async () => {
+      const idParams = sql.join(
+        recordIds.map((id) => sql`${id}`),
+        sql.raw(', ')
+      )
+      const result = (await tx.execute(
+        sql`SELECT * FROM ${sql.identifier(tableName)} WHERE id IN (${idParams})`
+      )) as readonly Record<string, unknown>[]
+      return result
+    },
+    catch: (error) => new SessionContextError('Failed to fetch records before operation', error),
+  })
+}

package/src/infrastructure/database/table-queries/mutation-helpers/update-helpers.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 { sql } from 'drizzle-orm'
+import { SessionContextError, type DrizzleTransaction } from '@/infrastructure/database'
+import { validateColumnName } from '../shared/validation'
+
+/**
+ * Validate fields object is not empty
+ * Returns entries directly or throws error (Promise-based for transaction use)
+ */
+export async function validateFieldsNotEmpty(
+  fields: Readonly<Record<string, unknown>>
+): Promise<readonly [string, unknown][]> {
+  const entries = Object.entries(fields)
+
+  if (entries.length === 0) {
+    // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+    throw new SessionContextError('Cannot update record with no fields', undefined)
+  }
+
+  return entries
+}
+
+/**
+ * Build UPDATE SET clause with validated columns (CRUD version)
+ */
+export function buildUpdateSetClauseCRUD(
+  entries: readonly [string, unknown][]
+): Readonly<ReturnType<typeof sql.join>> {
+  const setClauses = entries.map(([key, value]) => {
+    validateColumnName(key)
+    return sql`${sql.identifier(key)} = ${value}`
+  })
+  return sql.join(setClauses, sql.raw(', '))
+}
+
+/**
+ * Execute UPDATE query with permission enforcement
+ * Promise-based for transaction use
+ */
+export async function executeRecordUpdateCRUD(
+  tx: Readonly<DrizzleTransaction>,
+  tableName: string,
+  recordId: string,
+  setClause: Readonly<ReturnType<typeof sql.join>>
+): Promise<Record<string, unknown>> {
+  try {
+    const result = (await tx.execute(
+      sql`UPDATE ${sql.identifier(tableName)} SET ${setClause} WHERE id = ${recordId} RETURNING *`
+    )) as readonly Record<string, unknown>[]
+
+    // If no rows were updated, record not found or access denied
+    if (result.length === 0) {
+      // eslint-disable-next-line functional/no-throw-statements -- Permission blocking requires error propagation
+      throw new Error(`Record not found or access denied`)
+    }
+
+    return result[0]!
+  } catch (error) {
+    // Preserve "not found" or "access denied" in wrapper message for API error handling
+    const errorMsg = error instanceof Error ? error.message : String(error)
+    if (errorMsg.includes('not found') || errorMsg.includes('access denied')) {
+      // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+      throw new SessionContextError(errorMsg, error)
+    }
+    // eslint-disable-next-line functional/no-throw-statements -- Required for transaction error handling
+    throw new SessionContextError(`Failed to update record ${recordId} in ${tableName}`, error)
+  }
+}

package/src/infrastructure/database/table-queries/query-helpers/activity-log-helpers.ts

@@ -0,0 +1,53 @@
+/**
+ * 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 { db, SessionContextError } from '@/infrastructure/database'
+import { activityLogs } from '@/infrastructure/database/drizzle/schema/activity-log'
+import type { App } from '@/domain/models/app'
+import type { Session } from '@/infrastructure/auth/better-auth/schema'
+
+/**
+ * Common activity logging helper
+ *
+ * Logs database operations (create, update, delete) for audit trail.
+ * This is a non-critical operation that should not fail the main operation.
+ */
+export function logActivity(config: {
+  readonly session: Readonly<Session>
+  readonly tableName: string
+  readonly action: 'create' | 'update' | 'delete' | 'restore'
+  readonly recordId: string
+  readonly changes: {
+    readonly before?: Record<string, unknown>
+    readonly after?: Record<string, unknown>
+  }
+  readonly app?: App
+}): Effect.Effect<void, never> {
+  const { session, tableName, action, recordId, changes, app } = config
+  return Effect.ignore(
+    Effect.tryPromise({
+      try: async () => {
+        // Get table ID from app schema if available
+        const table = app?.tables?.find((t) => t.name === tableName)
+        const tableId = table?.id ? String(table.id) : '1'
+
+        // eslint-disable-next-line functional/no-expression-statements -- Database insert for logging is an acceptable side effect
+        await db.insert(activityLogs).values({
+          id: crypto.randomUUID(),
+          userId: session.userId,
+          action,
+          tableName,
+          tableId,
+          recordId,
+          changes,
+        })
+      },
+      catch: (error) => new SessionContextError('Failed to log activity', error),
+    })
+  )
+}

package/src/infrastructure/database/table-queries/query-helpers/activity-queries.ts

@@ -0,0 +1,106 @@
+/**
+ * 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 { eq, and, asc, gte, sql } from 'drizzle-orm'
+import { Effect } from 'effect'
+import { users } from '@/infrastructure/auth/better-auth/schema'
+import { SessionContextError } from '@/infrastructure/database'
+import { db } from '@/infrastructure/database/drizzle'
+import { activityLogs } from '@/infrastructure/database/drizzle/schema/activity-log'
+import { extractUserFromRow } from '../shared/user-join-helpers'
+import type { ActivityHistoryEntry } from '@/application/ports/repositories/activity-repository'
+import type { Session } from '@/infrastructure/auth/better-auth/schema'
+
+/**
+ * Build where condition for activity log queries (with 1-year retention policy)
+ */
+function buildActivityWhereCondition(tableName: string, recordId: string) {
+  const now = new Date()
+  const oneYearAgo = new Date(now.getFullYear() - 1, now.getMonth(), now.getDate())
+  return and(
+    eq(activityLogs.tableName, tableName),
+    eq(activityLogs.recordId, recordId),
+    gte(activityLogs.createdAt, oneYearAgo)
+  )
+}
+
+/**
+ * Transform an activity log row into an ActivityHistoryEntry
+ */
+function transformActivityRow(row: {
+  readonly action: string
+  readonly createdAt: Date
+  readonly changes: unknown
+  readonly userId: string | null
+  readonly userName: string | null
+  readonly userEmail: string | null
+  readonly userImage: string | null
+}): ActivityHistoryEntry {
+  return {
+    action: row.action,
+    createdAt: row.createdAt,
+    changes: row.changes,
+    user: extractUserFromRow(row),
+  }
+}
+
+/**
+ * Fetch activity history for a specific record with optional pagination
+ */
+export function getRecordHistory(config: {
+  readonly session: Readonly<Session>
+  readonly tableName: string
+  readonly recordId: string
+  readonly limit?: number
+  readonly offset?: number
+}): Effect.Effect<
+  {
+    readonly entries: readonly ActivityHistoryEntry[]
+    readonly total: number
+  },
+  SessionContextError
+> {
+  const { tableName, recordId, limit, offset } = config
+
+  return Effect.tryPromise({
+    try: async () => {
+      const whereCondition = buildActivityWhereCondition(tableName, recordId)
+
+      const countResult = await db
+        .select({ count: sql<number>`count(*)::int` })
+        .from(activityLogs)
+        .where(whereCondition)
+      const total = countResult[0]?.count ?? 0
+
+      const baseQuery = db
+        .select({
+          action: activityLogs.action,
+          createdAt: activityLogs.createdAt,
+          changes: activityLogs.changes,
+          userId: activityLogs.userId,
+          userName: users.name,
+          userEmail: users.email,
+          userImage: users.image,
+        })
+        .from(activityLogs)
+        .leftJoin(users, eq(activityLogs.userId, users.id))
+        .where(whereCondition)
+        .orderBy(asc(activityLogs.createdAt))
+
+      const paginatedQuery =
+        limit !== undefined
+          ? offset !== undefined
+            ? baseQuery.limit(limit).offset(offset)
+            : baseQuery.limit(limit)
+          : baseQuery
+
+      const results = await paginatedQuery
+      return { entries: results.map(transformActivityRow), total }
+    },
+    catch: (error) => new SessionContextError('Failed to fetch activity history', error),
+  })
+}