// ═══════════════════════════════════════════════════════════
// API Response Types — from CONTRACTS.md §1.3
// ═══════════════════════════════════════════════════════════

/** Standard success response envelope */
export interface ApiResponse<T> {
  ok: true;
  data: T;
  meta?: ResponseMeta;
}

export interface ResponseMeta {
  requestId: string;
  timestamp: string;
  pagination?: PaginationMeta;
  rateLimit?: RateLimitMeta;
}

export interface PaginationMeta {
  page: number;
  limit: number;
  total: number;
  totalPages: number;
  hasNext: boolean;
  hasPrev: boolean;
}

export interface RateLimitMeta {
  limit: number;
  remaining: number;
  resetAt: string;
}

/** Standard error response */
export interface ApiError {
  ok: false;
  error: {
    code: ErrorCode;
    message: string;
    details?: Record<string, unknown>;
    field?: string;
    requestId: string;
  };
}

export type ErrorCode =
  | "BAD_REQUEST"
  | "VALIDATION_ERROR"
  | "UNAUTHORIZED"
  | "FORBIDDEN"
  | "NOT_FOUND"
  | "CONFLICT"
  | "GONE"
  | "RATE_LIMITED"
  | "INTERNAL_ERROR"
  | "SERVICE_UNAVAILABLE"
  | "TIMEOUT";

/** Standard pagination request params */
export interface PaginationParams {
  page?: number;
  limit?: number;
  sort?: string;
}

/** JWT payload shape */
export interface JWTPayload {
  sub: string;
  email: string;
  role: Role;
  scopes: Scope[];
  iat: number;
  exp: number;
}

export type Role = "owner" | "admin" | "operator" | "viewer" | "agent";

export type Scope =
  | "pipelines:read" | "pipelines:write"
  | "tasks:read" | "tasks:approve" | "tasks:reject"
  | "deploy:staging" | "deploy:production"
  | "agents:manage"
  | "assets:read" | "assets:write"
  | "audit:read"
  | "feedback:read" | "feedback:write"
  | "learning:read" | "learning:write";
