/**
 * Service Contract
 *
 * Orchestration boundary for server-side operations.
 * 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 Result<ApiDto, DomainError>
 */

import { Result } from '@/lib/contracts/Result';

/**
 * Domain error type for services
 * Services should define specific error types based on their domain
 */
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 Result with API DTO or Domain Error
   */
  execute(...args: unknown[]): Promise<Result<TApiDto, TError>>;
}