website refactor

apps/website/lib/contracts/services/Service.ts

@@ -1,37 +1,50 @@
 /**
- * Service contract
- * 
+ * Service Contract
+ *
  * Orchestration boundary for server-side operations.
- * Returns API DTOs or Page DTOs only.
+ * Services are self-contained and create their own dependencies.
+ * Returns Result<ApiDto, DomainError> for type-safe error handling.
  * Must be stateless.
- * 
+ *
+ * Architecture:
+ * - Services are self-contained (no constructor parameters)
+ * - Services create their own dependencies (API Client, Logger, ErrorReporter)
+ * - Services return Result<ApiDto, DomainError>
+ * - Services convert HTTP errors to Domain errors
+ *
  * Based on WEBSITE_CONTRACT.md:
  * - Services orchestrate IO and composition
  * - They do not prepare UI
- * - They return ApiDto or PageDto only
+ * - They return Result<ApiDto, DomainError>
  */
 
+import { Result } from '@/lib/contracts/Result';
+
 /**
- * Base service interface for orchestration operations
+ * Domain error type for services
+ * Services should define specific error types based on their domain
  */
-export interface Service<TApiDto = unknown, TPageDto = unknown> {
+export type DomainError =
+  | { type: 'notFound'; message: string }
+  | { type: 'unauthorized'; message: string }
+  | { type: 'forbidden'; message: string }
+  | { type: 'validation'; message: string }
+  | { type: 'serverError'; message: string }
+  | { type: 'networkError'; message: string }
+  | { type: 'unknown'; message: string };
+
+/**
+ * Service interface for orchestration operations
+ * All service methods must return Result with domain errors
+ *
+ * Type Parameters:
+ * - TApiDto: The API Transport DTO type returned on success
+ * - TError: The domain error type (defaults to DomainError)
+ */
+export interface Service<TApiDto = unknown, TError extends DomainError = DomainError> {
   /**
    * Execute a service operation
-   * Returns either API Transport DTO or Page DTO
+   * Returns Result with API DTO or Domain Error
    */
-  execute(...args: unknown[]): Promise<TApiDto | TPageDto>;
-}
-
-/**
- * Service that returns API Transport DTOs
- */
-export interface ApiService<TApiDto = unknown> extends Service<TApiDto, never> {
-  execute(...args: unknown[]): Promise<TApiDto>;
-}
-
-/**
- * Service that returns Page DTOs
- */
-export interface PageService<TPageDto = unknown> extends Service<never, TPageDto> {
-  execute(...args: unknown[]): Promise<TPageDto>;
+  execute(...args: unknown[]): Promise<Result<TApiDto, TError>>;
 }