website refactor

apps/website/lib/contracts/mutations/Mutation.ts

@@ -5,8 +5,13 @@ import { Result } from "../Result";
  *
  * Purpose: Framework-agnostic write operations
  *
- * Rules:
- * - Orchestrates services for writes
+ * Architecture:
+ * - Server Action constructs Mutation
+ * - Mutation constructs Service
+ * - Service creates own dependencies (API Client, Logger, ErrorReporter)
+ * - Service returns Result<void, DomainError>
+ * - Mutation maps DomainError → MutationError
+ * - Mutation returns Result<void, MutationError>
  * - No HTTP/API calls directly
  * - No 'use client' directive
  * - No 'use server' directive
@@ -18,18 +23,48 @@ import { Result } from "../Result";
  * Pattern:
  * Server Action → Mutation → Service → API Client
  *
+ * Example:
+ * ```typescript
+ * export class UpdateUserStatusMutation implements Mutation<UpdateUserStatusInput, void> {
+ *   async execute(input: UpdateUserStatusInput): Promise<Result<void, MutationError>> {
+ *     const service = new UserService();
+ *     const result = await service.updateUserStatus(input.userId, input.status);
+ *
+ *     if (result.isErr()) {
+ *       return Result.err(mapToMutationError(result.error));
+ *     }
+ *
+ *     return Result.ok(undefined);
+ *   }
+ * }
+ * ```
+ *
  * Design Principle:
  * Each mutation does ONE thing. If you need multiple operations,
  * create multiple mutation classes (e.g., UpdateUserStatusMutation, DeleteUserMutation).
  * This follows the same pattern as Page Queries.
+ *
+ * @template TInput - The input type for the mutation
+ * @template TOutput - The output type on success
+ * @template TError - The error type (default: string for backward compatibility)
  */
 
-export interface Mutation<TInput = void, TOutput = void> {
+export interface Mutation<TInput = void, TOutput = void, TError = string> {
   /**
    * Execute the mutation
    *
+   * Manual construction pattern:
+   * ```typescript
+   * const service = new MyService();
+   * const result = await service.doWrite(input);
+   * if (result.isErr()) {
+   *   return Result.err(mapToMutationError(result.error));
+   * }
+   * return Result.ok(undefined);
+   * ```
+   *
    * @param input - Mutation input
-   * @returns Result indicating success or error
+   * @returns Promise<Result<TOutput, TError>>
    */
-  execute(input: TInput): Promise<Result<TOutput, string>>;
+  execute(input: TInput): Promise<Result<TOutput, TError>>;
 }

apps/website/lib/contracts/mutations/MutationError.ts

@@ -0,0 +1,45 @@
+/**
+ * Mutation Error Type
+ * 
+ * Errors that can be handled by the client after a mutation.
+ * These are mapped from DomainErrors by Mutations.
+ */
+
+export type MutationError = 
+  | 'userNotFound'       // User doesn't exist
+  | 'noPermission'       // Insufficient permissions
+  | 'invalidData'        // Validation failed
+  | 'updateFailed'       // Update operation failed
+  | 'deleteFailed'       // Delete operation failed
+  | 'createFailed'       // Create operation failed
+  | 'networkError'       // Network/communication error
+  | 'serverError'        // Generic server error
+  | 'unknown';           // Unknown error
+
+// Helper to map DomainError to MutationError
+export function mapToMutationError(domainError: any): MutationError {
+  const errorType = domainError?.type || domainError?.name || 'unknown';
+  
+  switch (errorType) {
+    case 'notFound':
+    case 'NotFoundError':
+    case 'userNotFound':
+      return 'userNotFound';
+    case 'unauthorized':
+    case 'UnauthorizedError':
+    case 'ForbiddenError':
+      return 'noPermission';
+    case 'validationError':
+    case 'ValidationError':
+      return 'invalidData';
+    case 'serverError':
+    case 'ServerError':
+    case 'HttpServerError':
+      return 'serverError';
+    case 'networkError':
+    case 'NetworkError':
+      return 'networkError';
+    default:
+      return 'unknown';
+  }
+}