base

plane-src/packages/services/src/cycle/cycle-analytics.service.ts

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import { API_BASE_URL } from "@plane/constants";
+import type { TCycleDistribution, TProgressSnapshot, TCycleEstimateDistribution } from "@plane/types";
+import { APIService } from "../api.service";
+
+/**
+ * Service class for managing cycles within a workspace and project context.
+ * Extends APIService to handle HTTP requests to the cycle-related endpoints.
+ * @extends {APIService}
+ */
+export class CycleAnalyticsService extends APIService {
+  constructor(BASE_URL?: string) {
+    super(BASE_URL || API_BASE_URL);
+  }
+
+  /**
+   * Retrieves analytics for active cycles in a workspace.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The cycle identifier
+   * @param {string} [analytic_type="points"] - The type of analytics to retrieve
+   * @returns {Promise<TCycleDistribution | TCycleEstimateDistribution>} The cycle analytics data
+   * @throws {Error} If the request fails
+   */
+  async workspaceActiveCyclesAnalytics(
+    workspaceSlug: string,
+    projectId: string,
+    cycleId: string,
+    analytic_type: string = "points"
+  ): Promise<TCycleDistribution | TCycleEstimateDistribution> {
+    return this.get(
+      `/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/analytics?type=${analytic_type}`
+    )
+      .then((res) => res?.data)
+      .catch((err) => {
+        throw err?.response?.data;
+      });
+  }
+
+  /**
+   * Retrieves progress data for active cycles.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The cycle identifier
+   * @returns {Promise<TProgressSnapshot>} The cycle progress data
+   * @throws {Error} If the request fails
+   */
+  async workspaceActiveCyclesProgress(
+    workspaceSlug: string,
+    projectId: string,
+    cycleId: string
+  ): Promise<TProgressSnapshot> {
+    return this.get(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/progress/`)
+      .then((res) => res?.data)
+      .catch((err) => {
+        throw err?.response?.data;
+      });
+  }
+
+  /**
+   * Retrieves advanced progress data for active cycles (Pro feature).
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The cycle identifier
+   * @returns {Promise<TProgressSnapshot>} The detailed cycle progress data
+   * @throws {Error} If the request fails
+   */
+  async workspaceActiveCyclesProgressPro(
+    workspaceSlug: string,
+    projectId: string,
+    cycleId: string
+  ): Promise<TProgressSnapshot> {
+    return this.get(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/cycle-progress/`)
+      .then((res) => res?.data)
+      .catch((err) => {
+        throw err?.response?.data;
+      });
+  }
+}

plane-src/packages/services/src/cycle/cycle-archive.service.ts

@@ -0,0 +1,89 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import { API_BASE_URL } from "@plane/constants";
+import type { ICycle } from "@plane/types";
+import { APIService } from "../api.service";
+
+/**
+ * Service class for managing archived cycles in a project
+ * Provides methods for retrieving, archiving, and restoring project cycles
+ * @extends {APIService}
+ */
+export class CycleArchiveService extends APIService {
+  constructor(BASE_URL?: string) {
+    super(BASE_URL || API_BASE_URL);
+  }
+
+  /**
+   * Retrieves all archived cycles for a specific project
+   * @param {string} workspaceSlug - The unique identifier for the workspace
+   * @param {string} projectId - The unique identifier for the project
+   * @returns {Promise<ICycle[]>} Array of archived cycles
+   * @throws {Error} Throws response data if the request fails
+   */
+  async list(workspaceSlug: string, projectId: string): Promise<ICycle[]> {
+    return this.get(`/api/workspaces/${workspaceSlug}/projects/${projectId}/archived-cycles/`)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Retrieves details of a specific archived cycle
+   * @param {string} workspaceSlug - The unique identifier for the workspace
+   * @param {string} projectId - The unique identifier for the project
+   * @param {string} cycleId - The unique identifier for the cycle
+   * @returns {Promise<ICycle>} Details of the archived cycle
+   * @throws {Error} Throws response data if the request fails
+   */
+  async retrieve(workspaceSlug: string, projectId: string, cycleId: string): Promise<ICycle> {
+    return this.get(`/api/workspaces/${workspaceSlug}/projects/${projectId}/archived-cycles/${cycleId}/`)
+      .then((res) => res?.data)
+      .catch((err) => {
+        throw err?.response?.data;
+      });
+  }
+
+  /**
+   * Archives a specific cycle in a project
+   * @param {string} workspaceSlug - The unique identifier for the workspace
+   * @param {string} projectId - The unique identifier for the project
+   * @param {string} cycleId - The unique identifier for the cycle to archive
+   * @returns {Promise<{archived_at: string}>} Object containing the archive timestamp
+   * @throws {Error} Throws response data if the request fails
+   */
+  async archive(
+    workspaceSlug: string,
+    projectId: string,
+    cycleId: string
+  ): Promise<{
+    archived_at: string;
+  }> {
+    return this.post(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/archive/`)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Restores a previously archived cycle
+   * @param {string} workspaceSlug - The unique identifier for the workspace
+   * @param {string} projectId - The unique identifier for the project
+   * @param {string} cycleId - The unique identifier for the cycle to restore
+   * @returns {Promise<void>} Resolves when the cycle is successfully restored
+   * @throws {Error} Throws response data if the request fails
+   */
+  async restore(workspaceSlug: string, projectId: string, cycleId: string): Promise<void> {
+    return this.delete(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/archive/`)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+}

plane-src/packages/services/src/cycle/cycle-operations.service.ts

@@ -0,0 +1,76 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import { API_BASE_URL } from "@plane/constants";
+import { APIService } from "../api.service";
+
+export class CycleOperationsService extends APIService {
+  constructor(BASE_URL?: string) {
+    super(BASE_URL || API_BASE_URL);
+  }
+
+  /**
+   * Adds a cycle to user favorites.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {{cycle: string}} data - The favorite cycle data
+   * @returns {Promise<any>} The response data
+   * @throws {Error} If the request fails
+   */
+  async addToFavorites(
+    workspaceSlug: string,
+    projectId: string,
+    data: {
+      cycle: string;
+    }
+  ): Promise<any> {
+    return this.post(`/api/workspaces/${workspaceSlug}/projects/${projectId}/user-favorite-cycles/`, data)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Removes a cycle from user favorites.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The cycle identifier
+   * @returns {Promise<any>} The removal response
+   * @throws {Error} If the request fails
+   */
+  async removeFromFavorites(workspaceSlug: string, projectId: string, cycleId: string): Promise<any> {
+    return this.delete(`/api/workspaces/${workspaceSlug}/projects/${projectId}/user-favorite-cycles/${cycleId}/`)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Transfers issues between cycles.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The source cycle identifier
+   * @param {{new_cycle_id: string}} data - The target cycle data
+   * @returns {Promise<any>} The transfer response
+   * @throws {Error} If the request fails
+   */
+  async transferIssues(
+    workspaceSlug: string,
+    projectId: string,
+    cycleId: string,
+    data: {
+      new_cycle_id: string;
+    }
+  ): Promise<any> {
+    return this.post(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/transfer-issues/`, data)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+}

plane-src/packages/services/src/cycle/cycle.service.ts

@@ -0,0 +1,190 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+import { API_BASE_URL } from "@plane/constants";
+import type { CycleDateCheckData, ICycle, TIssuesResponse, IWorkspaceActiveCyclesResponse } from "@plane/types";
+import { APIService } from "../api.service";
+
+/**
+ * Service class for managing cycles within a workspace and project context.
+ * Extends APIService to handle HTTP requests to the cycle-related endpoints.
+ * @extends {APIService}
+ */
+export class CycleService extends APIService {
+  constructor(BASE_URL?: string) {
+    super(BASE_URL || API_BASE_URL);
+  }
+
+  /**
+   * Retrieves paginated list of active cycles in a workspace.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} cursor - The pagination cursor
+   * @param {number} per_page - Number of items per page
+   * @returns {Promise<IWorkspaceActiveCyclesResponse>} Paginated active cycles data
+   * @throws {Error} If the request fails
+   */
+  async workspaceActiveCycles(
+    workspaceSlug: string,
+    cursor: string,
+    per_page: number
+  ): Promise<IWorkspaceActiveCyclesResponse> {
+    return this.get(`/api/workspaces/${workspaceSlug}/active-cycles/`, {
+      params: {
+        per_page,
+        cursor,
+      },
+    })
+      .then((res) => res?.data)
+      .catch((err) => {
+        throw err?.response?.data;
+      });
+  }
+
+  /**
+   * Gets all cycles in a workspace.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @returns {Promise<ICycle[]>} Array of cycle objects
+   * @throws {Error} If the request fails
+   */
+  async getWorkspaceCycles(workspaceSlug: string): Promise<ICycle[]> {
+    return this.get(`/api/workspaces/${workspaceSlug}/cycles/`)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Creates a new cycle in a project.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {any} data - The cycle creation data
+   * @returns {Promise<ICycle>} The created cycle object
+   * @throws {Error} If the request fails
+   */
+  async create(workspaceSlug: string, projectId: string, data: any): Promise<ICycle> {
+    return this.post(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/`, data)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Retrieves cycles with optional filtering parameters.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {"current"} [cycleType] - Optional filter for cycle type
+   * @returns {Promise<ICycle[]>} Array of filtered cycle objects
+   * @throws {Error} If the request fails
+   */
+  async getWithParams(workspaceSlug: string, projectId: string, cycleType?: "current"): Promise<ICycle[]> {
+    return this.get(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/`, {
+      params: {
+        cycle_view: cycleType,
+      },
+    })
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Retrieves detailed information for a specific cycle.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The cycle identifier
+   * @returns {Promise<ICycle>} The cycle details
+   * @throws {Error} If the request fails
+   */
+  async retrieve(workspaceSlug: string, projectId: string, cycleId: string): Promise<ICycle> {
+    return this.get(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/`)
+      .then((res) => res?.data)
+      .catch((err) => {
+        throw err?.response?.data;
+      });
+  }
+
+  /**
+   * Retrieves issues associated with a specific cycle.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The cycle identifier
+   * @param {any} [queries] - Optional query parameters
+   * @param {object} [config={}] - Optional request configuration
+   * @returns {Promise<TIssuesResponse>} The cycle issues data
+   * @throws {Error} If the request fails
+   */
+  async getCycleIssues(
+    workspaceSlug: string,
+    projectId: string,
+    cycleId: string,
+    queries?: any,
+    config = {}
+  ): Promise<TIssuesResponse> {
+    return this.get(
+      `/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/cycle-issues/`,
+      {
+        params: queries,
+      },
+      config
+    )
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Updates a cycle with partial data.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The cycle identifier
+   * @param {Partial<ICycle>} data - The partial cycle data to update
+   * @returns {Promise<any>} The update response
+   * @throws {Error} If the request fails
+   */
+  async update(workspaceSlug: string, projectId: string, cycleId: string, data: Partial<ICycle>): Promise<any> {
+    return this.patch(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/`, data)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Deletes a specific cycle.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {string} cycleId - The cycle identifier
+   * @returns {Promise<any>} The deletion response
+   * @throws {Error} If the request fails
+   */
+  async destroy(workspaceSlug: string, projectId: string, cycleId: string): Promise<any> {
+    return this.delete(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/${cycleId}/`)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+
+  /**
+   * Validates cycle dates.
+   * @param {string} workspaceSlug - The workspace identifier
+   * @param {string} projectId - The project identifier
+   * @param {CycleDateCheckData} data - The date check data
+   * @returns {Promise<any>} The validation response
+   * @throws {Error} If the request fails
+   */
+  async validateDates(workspaceSlug: string, projectId: string, data: CycleDateCheckData): Promise<any> {
+    return this.post(`/api/workspaces/${workspaceSlug}/projects/${projectId}/cycles/date-check/`, data)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+}

plane-src/packages/services/src/cycle/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+export * from "./cycle-analytics.service";
+export * from "./cycle-archive.service";
+export * from "./cycle-operations.service";
+export * from "./cycle.service";
+export * from "./sites-cycle.service";

plane-src/packages/services/src/cycle/sites-cycle.service.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2023-present Plane Software, Inc. and contributors
+ * SPDX-License-Identifier: AGPL-3.0-only
+ * See the LICENSE file for details.
+ */
+
+// plane imports
+import { API_BASE_URL } from "@plane/constants";
+import type { TPublicCycle } from "@plane/types";
+// api service
+import { APIService } from "../api.service";
+
+/**
+ * Service class for managing cycles within plane sites application.
+ * Extends APIService to handle HTTP requests to the cycle-related endpoints.
+ * @extends {APIService}
+ * @remarks This service is only available for plane sites
+ */
+export class SitesCycleService extends APIService {
+  constructor(BASE_URL?: string) {
+    super(BASE_URL || API_BASE_URL);
+  }
+
+  /**
+   * Retrieves list of cycles for a specific anchor.
+   * @param anchor - The anchor identifier for the published entity
+   * @returns {Promise<TPublicCycle[]>} The list of cycles
+   * @throws {Error} If the request fails
+   */
+  async list(anchor: string): Promise<TPublicCycle[]> {
+    return this.get(`/api/public/anchor/${anchor}/cycles/`)
+      .then((response) => response?.data)
+      .catch((error) => {
+        throw error?.response?.data;
+      });
+  }
+}