Workflow & Cycle Management

/**
 * Get cycles with filtering and pagination
 * @param variables - Query parameters including filters and pagination
 * @returns Promise resolving to a connection of cycles
 */
cycles(variables?: CyclesQueryVariables): LinearFetch<CycleConnection>;

/**
 * Get a single cycle by ID
 * @param id - The cycle ID
 * @returns Promise resolving to the cycle
 */
cycle(id: string): LinearFetch<Cycle>;

/**
 * Create a new cycle
 * @param input - Cycle creation data
 * @returns Promise resolving to the creation result
 */
createCycle(input: CycleCreateInput): LinearFetch<CyclePayload>;

/**
 * Update an existing cycle
 * @param id - The cycle ID to update
 * @param input - Cycle update data
 * @returns Promise resolving to the update result
 */
updateCycle(id: string, input: CycleUpdateInput): LinearFetch<CyclePayload>;

/**
 * Archive a cycle
 * @param id - The cycle ID to archive
 * @returns Promise resolving to the archive result
 */
archiveCycle(id: string): LinearFetch<ArchivePayload>;

interface CycleCreateInput {
  /** Cycle name */
  name: string;
  /** Cycle description */
  description?: string;
  /** Team ID this cycle belongs to */
  teamId: string;
  /** Cycle start date */
  startsAt: DateTime;
  /** Cycle end date */
  endsAt: DateTime;
  /** Whether cycle is completed */
  completedAt?: DateTime;
}

interface CycleUpdateInput {
  /** Update cycle name */
  name?: string;
  /** Update cycle description */
  description?: string;
  /** Update start date */
  startsAt?: DateTime;
  /** Update end date */
  endsAt?: DateTime;
  /** Update completion date */
  completedAt?: DateTime;
}

import { LinearClient } from "@linear/sdk";

const client = new LinearClient({ apiKey: "your-api-key" });

// Get current cycle for a team
const currentCycles = await client.cycles({
  filter: {
    team: { key: { eq: "ENG" } },
    isCurrent: { eq: true }
  }
});

// Create a new 2-week cycle
const newCycle = await client.createCycle({
  name: "Sprint 23",
  description: "Focus on performance improvements",
  teamId: "team-engineering",
  startsAt: "2024-01-15T00:00:00Z",
  endsAt: "2024-01-29T00:00:00Z"
});

// Complete a cycle
const completedCycle = await client.updateCycle("cycle-id", {
  completedAt: new Date().toISOString()
});

/**
 * Get workflow states with filtering and pagination
 * @param variables - Query parameters
 * @returns Promise resolving to a connection of workflow states
 */
workflowStates(variables?: WorkflowStatesQueryVariables): LinearFetch<WorkflowStateConnection>;

/**
 * Get a single workflow state by ID
 * @param id - The workflow state ID
 * @returns Promise resolving to the workflow state
 */
workflowState(id: string): LinearFetch<WorkflowState>;

/**
 * Create a new workflow state
 * @param input - Workflow state creation data
 * @returns Promise resolving to the creation result
 */
createWorkflowState(input: WorkflowStateCreateInput): LinearFetch<WorkflowStatePayload>;

/**
 * Update a workflow state
 * @param id - The workflow state ID to update
 * @param input - Workflow state update data
 * @returns Promise resolving to the update result
 */
updateWorkflowState(id: string, input: WorkflowStateUpdateInput): LinearFetch<WorkflowStatePayload>;

/**
 * Archive a workflow state
 * @param id - The workflow state ID to archive
 * @returns Promise resolving to the archive result
 */
archiveWorkflowState(id: string): LinearFetch<ArchivePayload>;

interface WorkflowStateCreateInput {
  /** State name */
  name: string;
  /** State description */
  description?: string;
  /** State color */
  color: string;
  /** State type */
  type: WorkflowType;
  /** Team ID this state belongs to */
  teamId: string;
  /** Position in the workflow */
  position?: number;
}

interface WorkflowStateUpdateInput {
  /** Update state name */
  name?: string;
  /** Update state description */
  description?: string;
  /** Update state color */
  color?: string;
  /** Update position */
  position?: number;
}

enum WorkflowType {
  Backlog = "backlog",
  Unstarted = "unstarted",
  Started = "started",
  Completed = "completed",
  Canceled = "canceled"
}

/**
 * Get cycle analytics for progress tracking
 * @param cycleId - The cycle ID to analyze
 * @returns Promise resolving to cycle analytics
 */
cycleAnalytics(cycleId: string): LinearFetch<CycleAnalytics>;

interface CycleAnalytics {
  /** Total issues in cycle */
  issueCount: number;
  /** Completed issues count */
  completedIssueCount: number;
  /** In progress issues count */
  inProgressIssueCount: number;
  /** Backlog issues count */
  backlogIssueCount: number;
  /** Total story points */
  totalStoryPoints: number;
  /** Completed story points */
  completedStoryPoints: number;
  /** Cycle completion percentage */
  progress: number;
}

/** Cycle model representing a development cycle */
class Cycle extends Request {
  /** Unique cycle identifier */
  id: string;
  /** Cycle name */
  name: string;
  /** Cycle description */
  description?: string;
  /** Cycle number */
  number: number;
  /** Cycle start date */
  startsAt: DateTime;
  /** Cycle end date */
  endsAt: DateTime;
  /** Cycle completion date */
  completedAt?: DateTime;
  /** Whether cycle is current/active */
  isCurrent: boolean;
  /** Whether cycle is next */
  isNext: boolean;
  /** Whether cycle is previous */
  isPrevious: boolean;
  /** Progress percentage (0-1) */
  progress: number;
  /** Associated team */
  team: Team;
  /** Issues in this cycle */
  issues: IssueConnection;
  /** Unfinished issues from previous cycle */
  uncompletedIssuesUponClose: IssueConnection;
  /** Creation timestamp */
  createdAt: DateTime;
  /** Last update timestamp */
  updatedAt: DateTime;
  /** Archive timestamp */
  archivedAt?: DateTime;
}

/** Workflow state model */
class WorkflowState extends Request {
  /** Unique workflow state identifier */
  id: string;
  /** State name */
  name: string;
  /** State description */
  description?: string;
  /** State color hex code */
  color: string;
  /** State type enum */
  type: WorkflowType;
  /** Position in workflow */
  position: number;
  /** Associated team */
  team: Team;
  /** Issues in this state */
  issues: IssueConnection;
  /** Creation timestamp */
  createdAt: DateTime;
  /** Last update timestamp */
  updatedAt: DateTime;
  /** Archive timestamp */
  archivedAt?: DateTime;
}

/** Response payload for cycle mutations */
interface CyclePayload {
  /** The mutated cycle */
  cycle?: Cycle;
  /** Whether the mutation was successful */
  success: boolean;
  /** Last sync ID */
  lastSyncId: number;
}

/** Response payload for workflow state mutations */
interface WorkflowStatePayload {
  /** The mutated workflow state */
  workflowState?: WorkflowState;
  /** Whether the mutation was successful */
  success: boolean;
  /** Last sync ID */
  lastSyncId: number;
}

/** Paginated connection of cycles */
class CycleConnection extends Connection<Cycle> {
  /** Cycles in this page */
  nodes: Cycle[];
  /** Pagination information */
  pageInfo: PageInfo;
}

/** Paginated connection of workflow states */
class WorkflowStateConnection extends Connection<WorkflowState> {
  /** Workflow states in this page */
  nodes: WorkflowState[];
  /** Pagination information */
  pageInfo: PageInfo;
}