// types/clickup.d.ts

/**
 * Base Task Interface - Shared mutable fields across operations
 * Contains all fields that can be SENT in create/update requests
 * and RECEIVED in responses (excluding read-only metadata)
 */
interface TaskBase {
  // Core Content
  name: string;
  description?: string;
  text_content?: string;

  // Status & Priority
  status?: string;
  priority?: 1 | 2 | 3 | 4;

  // Time Management
  due_date?: number | null;
  start_date?: number | null;
  time_estimate?: number | null;
  time_spent?: number | null;

  // People & Assignments
  assignees?: number[];
  tags?: string[];
  custom_fields?: Array<{
    id: string;
    value: any;
  }>;

  // Task Relationships
  parent?: string | null;
  links_to?: string;

  // Advanced Features
  markdown_description?: string;
  notify_all?: boolean;
  check_required_custom_fields?: boolean;
  custom_item_id?: number | null;
  source?: string;
}

/**
 * Task Creation Parameters
 * @see https://developer.clickup.com/reference/createtask
 */
interface TaskCreate extends TaskBase {
  /** Required Fields */
  list_id: string;
  name: string;

  /** Creation-Specific Fields */
  custom_task_id?: string;
  team_id?: number;
}

/**
 * Task Update Parameters
 * @see https://developer.clickup.com/reference/updatetask
 */
interface TaskUpdate extends Partial<TaskBase> {
  /** Required Identifier */
  id: string;

  /** Update-Specific Fields */
  task_revision?: number;
  task_template_id?: string;
  idempotency_key?: string;
}

/**
 * Full Task Response
 * @see https://developer.clickup.com/reference/gettask
 */
interface TaskResponse extends TaskBase {
  /** Read-Only Metadata */
  id: string;
  url: string;
  orderindex: string;
  date_created: string;
  date_updated: string;
  date_closed?: string | null;
  date_done?: string | null;
  archived: boolean;

  /** System Relationships */
  list: {
    id: string;
    name: string;
    access: boolean;
  };
  space: {
    id: string;
    name: string;
  };
  folder: {
    id: string;
    name: string;
    hidden: boolean;
    access: boolean;
  };

  /** People & Permissions */
  creator: User;
  watchers: User[];
  followers: User[];
  permission_level: string;
  shared: SharedAccess[];

  /** Complex Structures */
  checklists: Checklist[];
  dependencies: Dependency[];
  linked_tasks: LinkedTask[];
  subtasks: TaskResponse[];
  attachments: Attachment[];

  /** Status Details */
  status: {
    status: string;
    color: string;
    orderindex: number;
    type: 'open' | 'closed' | 'custom';
  };

  /** Priority Details */
  priority: {
    id: string;
    priority: 'urgent' | 'high' | 'normal' | 'low';
    color: string;
  } | null;
}

// Supporting Interfaces
interface User {
  id: number;
  username: string;
  email: string;
  color: string;
  initials: string;
  profilePicture?: string;
}

interface Checklist {
  id: string;
  name: string;
  orderindex: number;
  resolved: number;
  unresolved: number;
  items: ChecklistItem[];
}

interface ChecklistItem {
  id: string;
  name: string;
  orderindex: number;
  assignee?: number;
  resolved: boolean;
  parent?: string;
  date_created: string;
  children?: string[];
}

interface Tag {
  name: string;
  tag_fg: string;
  tag_bg: string;
  creator?: number;
}

interface Dependency {
  task_id: string;
  depends_on: string;
  type: number;
  date_created: string;
  userid: string;
}

interface LinkedTask {
  task_id: string;
  link_id: string;
  date_created: string;
  userid: string;
}

interface CustomField {
  id: string;
  name: string;
  type: string;
  type_config: {
    [key: string]: any;
    options?: Array<{
      id: string;
      name: string;
      color?: string;
      orderindex?: number;
    }>;
  };
  value: any;
}

interface Attachment {
  id: string;
  version: string;
  date: string;
  title: string;
  extension: string;
  thumbnail_small: string;
  thumbnail_large: string;
  size: number;
}

interface SharedAccess {
  id: string;
  name: string;
  type: string;
  access_level: string;
  team_id: string;
}

/**
 * Full task hierarchy types
 * Ref: https://developer.clickup.com/docs
 */
interface ClickUpHierarchy {
  workspace_id: string;
  space_id: string;
  folder_id?: string;
  list_id: string;
  task_id: string;
}

/**
 * API error response format
 * Ref: https://developer.clickup.com/docs/errors
 */
interface ClickUpError {
  err: string;
  code: number;
  message?: string;
}