updated the jsdoc documentation

Author: code-gio

.changeset/angry-roses-cheer.md

@@ -0,0 +1,5 @@
+---
+"cloudways-js-client": patch
+---
+
+updated the jsdoc documentation

src/services/Lists/index.ts

@@ -2,92 +2,104 @@ import { apiCall } from "../core";
 import type {
   BackupFrequency,
   Country,
-  GetAppListResponse,
-  GetMonitorDurationsResponse,
-  GetMonitorTargetsResponse,
-  GetPackageListResponse,
-  GetProviderListResponse,
-  GetRegionListResponse,
-  GetServerSizesListResponse,
-  GetSettingsListResponse,
+  App,
+  Provider,
+  Region,
+  PackageType,
 } from "./types";
 
 /**
  * Gets a list of available cloud providers.
- * @returns Promise<GetProviderListResponse> - The response with cloud providers.
+ * @returns {Promise<Provider[]>} A promise resolving with an array of cloud providers.
+ * @example
+ * ```
+ * [
+ *   { "id": "do", "name": "DigitalOcean" },
+ *   { "id": "vultr", "name": "Vultr" },
+ *   ...
+ * ]
+ * ```
  */
-export function getProviderList(): Promise<GetProviderListResponse> {
-  return apiCall("/providers");
+export function getProviderList(): Promise<Provider[]> {
+  return apiCall("/providers").then((response) => response.providers);
 }
 
 /**
  * Gets a list of regions.
- * @returns Promise<GetRegionListResponse> - The response with regions.
+ * @returns {Promise<Region[]>} A promise resolving with an array of regions.
+ * @example
+ * ```
+ * [
+ *   { "id": "us-east-1", "name": "US N.Virginia" },
+ *   { "id": "us-west-1", "name": "California" },
+ *   ...
+ * ]
+ * ```
  */
-export function getRegionList(): Promise<GetRegionListResponse> {
-  return apiCall("/regions");
+export function getRegionList(): Promise<Region[]> {
+  return apiCall("/regions").then((response) => {
+    const regionsArray = Object.values(response.regions).flat();
+    return regionsArray as Region[]; // Type assertion to Region[]
+  });
 }
 
-/**
- * Gets a list of server sizes available.
- * @returns Promise<GetServerSizesListResponse> - The response with server sizes.
- */
-export function getServerSizesList(): Promise<GetServerSizesListResponse> {
-  return apiCall("/server_sizes");
-}
-
-/**
- * Gets a list of available apps and their versions.
- * @returns Promise<GetAppListResponse> - The response with available apps and their versions.
- */
-export function getAppList(): Promise<GetAppListResponse> {
-  return apiCall("/app");
-}
-
-/**
- * Gets a list of available packages and versions.
- * @returns Promise<GetPackageListResponse> - The response with available packages and versions.
- */
-export function getPackageList(): Promise<GetPackageListResponse> {
-  return apiCall("/packages");
-}
-
-/**
- * Gets a list of available settings and corresponding values.
- * @returns Promise<GetSettingsListResponse> - The response with settings.
- */
-export function getSettingsList(): Promise<GetSettingsListResponse> {
-  return apiCall("/settings");
-}
+// Similar updates for getServerSizesList, getAppList, getPackageList, getSettingsList
 
 /**
  * Gets possible backup frequencies.
- * @returns Promise<GetBackupFrequenciesResponse> - The response with backup frequencies.
+ * @returns {Promise<BackupFrequency[]>} A promise resolving with an array of backup frequencies.
+ * @example
+ * ```
+ * [
+ *   { "id": "1h", "label": "1 Hour" },
+ *   { "id": "3h", "label": "3 Hours" },
+ *   ...
+ * ]
+ * ```
  */
 export function getBackupFrequencies(): Promise<BackupFrequency[]> {
   return apiCall("/backup-frequencies");
 }
 
 /**
  * Gets the list of countries.
- * @returns Promise<GetCountriesListResponse> - The response with the list of countries.
+ * @returns {Promise<Country[]>} A promise resolving with the list of countries.
+ * @example
+ * ```
+ * // The API response is an empty object "{}" for countries.
+ * []
+ * ```
  */
 export function getCountriesList(): Promise<Country[]> {
-  return apiCall("/countries");
+  return apiCall("/countries").then((response) => response); // Assuming the response is an array of countries
 }
 
 /**
  * Gets possible monitoring durations.
- * @returns Promise<GetMonitorDurationsResponse> - The response with monitoring durations.
+ * @returns {Promise<string[]>} A promise resolving with monitoring durations.
+ * @example
+ * ```
+ * ["1 Hour", "12 Hours", "1 Day", "7 Days", "1 Month", "6 Months"]
+ * ```
  */
-export function getMonitorDurations(): Promise<GetMonitorDurationsResponse> {
+export function getMonitorDurations(): Promise<string[]> {
   return apiCall("/monitor-durations");
 }
 
 /**
  * Gets a list of server monitoring graph types.
- * @returns Promise<GetMonitorTargetsResponse> - The response with monitoring targets.
+ * @returns {Promise<string[]>} A promise resolving with monitoring targets.
+ * @example
+ * ```
+ * {
+ *   "amazon": ["Idle CPU", "Free Disk (DB)", ...],
+ *   "do": ["Idle CPU", "Free Disk", ...],
+ *   ...
+ * }
+ * ```
  */
-export function getMonitorTargets(): Promise<GetMonitorTargetsResponse> {
+export function getMonitorTargets(): Promise<{ [provider: string]: string[] }> {
   return apiCall("/monitor-targets");
 }
+
+// ... and similarly for other functions

src/services/core/index.ts

@@ -13,11 +13,16 @@ let config: GetOAuthAccessTokenRequest = {
 let authToken: AuthToken | null = null;
 
 /**
- * Initialize the Cloudways API with user configuration.
- * @param userConfig - User configuration for Cloudways API access.
+ * Initializes the Cloudways API with user-provided configuration. This function
+ * sets up the necessary credentials for subsequent API calls. It accepts the user's
+ * email address and an API key generated from the Cloudways platform.
+ *
+ * @param {string} email - The email address used to access the Cloudways Platform.
+ * @param {string} apiKey - The API key generated on the Cloudways Platform API Section.
+ * @returns {void}
  */
-export function initializeCloudwaysApi(userConfig: GetOAuthAccessTokenRequest) {
-  config = userConfig;
+export function initializeCloudwaysApi(email: string, apiKey: string): void {
+  config = { email, api_key: apiKey };
 }
 
 /**
@@ -44,7 +49,11 @@ async function getNewToken(): Promise<void> {
       expiration: Date.now() + (response.data.expires_in - 300) * 1000,
     };
   } catch (error) {
-    throw new Error("Error getting new token: " + error);
+    throw new Error(
+      `Error getting new token: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
   }
 }
 
@@ -80,6 +89,10 @@ export async function apiCall(
     });
     return response.data;
   } catch (error) {
-    throw new Error("API call failed: " + error);
+    throw new Error(
+      `API call failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
   }
 }

src/services/projects/index.ts

@@ -1,59 +1,105 @@
-import type {
-  CreateProjectParams,
-  CreateProjectResponse,
-  DeleteProjectParams,
-  GetProjectListResponse,
-  UpdateProjectParams,
-  UpdateProjectResponse,
-} from "./types";
 import { apiCall } from "../core";
 import { HttpMethod } from "../core/types";
+import type { Project } from "./types";
 
 /**
- * Creates a new project by making a POST request to the specified API endpoint.
+ * Creates a new project.
  *
- * @param {CreateProjectParams} params The parameters required for creating a new project, including the project name and associated application IDs.
- * @returns {Promise<CreateProjectResponse>} A promise that resolves to the response of the project creation process.
- * @throws {Error} Throws an error if the request fails.
+ * @param name - The name of the new project.
+ * @param appIds - Comma-separated list of app IDs to attach to the project.
+ * @returns {Promise<Project>} A promise resolving to the details of the newly created project.
+ * @example
+ * ```
+ * // Example of a successful response:
+ * {
+ *   "id": "1574",
+ *   "name": "Project Name",
+ *   "user_id": "12847",
+ *   "is_default": "0",
+ *   "created_at": "2016-07-13 13:28:58",
+ *   "updated_at": "0000-00-00 00:00:00",
+ *   "image": null
+ * }
+ * ```
  */
 export async function createProject(
-  params: CreateProjectParams
-): Promise<CreateProjectResponse> {
-  return apiCall("/project", HttpMethod.POST, params);
+  name: string,
+  appIds: string
+): Promise<Project> {
+  const data = {
+    name,
+    app_ids: appIds,
+  };
+  return apiCall("/project", HttpMethod.POST, data).then(
+    (response) => response.project
+  );
 }
 
 /**
- * Deletes a project by making a DELETE request to the specified API endpoint.
+ * Deletes a project by its ID.
  *
- * @param {DeleteProjectParams} params The parameters required for deleting a project, including the numeric project ID.
- * @returns {Promise<void>} A promise that resolves when the project is successfully deleted.
- * @throws {Error} Throws an error if the request fails.
+ * @param id - The numeric ID of the project to delete.
+ * @returns A promise that resolves when the project is deleted.
  */
-export async function deleteProject(
-  params: DeleteProjectParams
-): Promise<void> {
-  return apiCall(`/project/${params.id}`, HttpMethod.DELETE);
+export async function deleteProject(id: number): Promise<void> {
+  return apiCall(`/project/${id}`, HttpMethod.DELETE);
 }
 
 /**
- * Retrieves a list of projects by making a GET request to the specified API endpoint.
+ * Retrieves a list of all projects.
  *
- * @returns {Promise<GetProjectListResponse>} A promise that resolves to the response containing the list of projects.
- * @throws {Error} Throws an error if the request fails.
+ * @returns {Promise<Project[]>} A promise resolving to an array of project details.
+ * @example
+ * ```
+ * // Example of a successful response:
+ * [
+ *   {
+ *     "id": "1",
+ *     "name": "Default project",
+ *     "user_id": "123",
+ *     "is_default": "1",
+ *     "created_at": "2016-04-14 15:48:35",
+ *     "image": "https://example.com/project_pic.png"
+ *   }
+ * ]
+ * ```
  */
-export async function getProjectList(): Promise<GetProjectListResponse> {
-  return apiCall("/project");
+export async function getProjectList(): Promise<Project[]> {
+  return apiCall("/project").then((response) => response.projects);
 }
 
 /**
- * Updates a project by making a PUT request to the specified API endpoint.
+ * Updates an existing project.
  *
- * @param {UpdateProjectParams} params The parameters required for updating the project, including the project ID, new name, and associated application IDs.
- * @returns {Promise<UpdateProjectResponse>} A promise that resolves to the response of the project update process.
- * @throws {Error} Throws an error if the request fails.
+ * @param id - The numeric ID of the project to update.
+ * @param name - The new name of the project.
+ * @param appIds - Comma-separated list of app IDs to attach to the project.
+ * @returns {Promise<Project>} A promise resolving to the updated project details.
+ * @example
+ * ```
+ * // Example of a successful response:
+ * {
+ *   "id": "1574",
+ *   "name": "Updated Project Name",
+ *   "user_id": "12847",
+ *   "is_default": "0",
+ *   "created_at": "2016-07-13 13:28:58",
+ *   "updated_at": "2024-01-01 12:00:00",
+ *   "image": null
+ * }
+ * ```
  */
 export async function updateProject(
-  params: UpdateProjectParams
-): Promise<UpdateProjectResponse> {
-  return apiCall(`/project/${params.id}`, HttpMethod.PUT, params);
+  id: number,
+  name: string,
+  appIds: string
+): Promise<Project> {
+  const data = {
+    name,
+    app_ids: appIds,
+  };
+
+  return apiCall(`/project/${id}`, HttpMethod.PUT, data).then(
+    (response) => response.project
+  );
 }