contracts.d.ts

/**
 * TaskFlow API contract — the single source of truth for the shapes that cross
 * the network between the NestJS backend and the Next.js frontend.
 *
 * This is a TYPE-ONLY declaration file on purpose:
 *  - `import type` from it erases at compile time, so neither app gains a
 *    runtime dependency, a build step, or a bundled module — each still runs
 *    with a plain `npm install && npm run dev`.
 *  - Both apps validate against it at COMPILE time: the frontend derives its
 *    types from here, and the backend asserts its enums/event names match
 *    (see `backend/src/contracts.parity.ts`). Drift becomes a build error.
 *
 * Note: this describes the WIRE shape (JSON). Dates are ISO strings here —
 * the backend's domain entity uses `Date` and serialises to this on the way out.
 */

export type TaskStatus = 'todo' | 'in_progress' | 'done' | 'archived';
export type TaskPriority = 1 | 2 | 3;

export interface TaskDto {
  id: string;
  title: string;
  description?: string;
  status: TaskStatus;
  priority: TaskPriority;
  tags: string[];
  createdAt: string;
  updatedAt: string;
}

export interface TaskPageDto {
  items: TaskDto[];
  nextCursor: string | null;
  total: number;
}

export interface TaskStatsDto {
  total: number;
  byStatus: Record<TaskStatus, number>;
  byPriority: Record<TaskPriority, number>;
}

/** Server → client WebSocket event names. */
export type TaskEventName = 'task:created' | 'task:updated' | 'task:deleted';

/** Stable, machine-readable error codes in the error envelope. */
export type ErrorCode =
  | 'VALIDATION_ERROR'
  | 'INVALID_API_KEY'
  | 'TASK_NOT_FOUND'
  | 'ILLEGAL_STATUS_TRANSITION'
  | 'EMPTY_UPDATE'
  | 'TASK_ARCHIVED_READONLY'
  | 'INVALID_CURSOR'
  | 'INTERNAL_ERROR';

export interface ApiErrorBody {
  statusCode: number;
  code: ErrorCode;
  message: string | string[];
  path: string;
  timestamp: string;
}