API updates (MrRefactoring#279)

* API updates

* docs warnings resolved

* type clarified

* version3 api updates

* version3 api updates

Author: MrRefactoring

package-lock.json

@@ -1,22 +1,22 @@
 {
   "name": "jira.js",
   "version": "2.19.1",
-  "description": "jira.js is a powerful Node.JS/Browser module that allows you to interact with the Jira API very easily",
+  "description": "A comprehensive JavaScript/TypeScript library designed for both Node.JS and browsers, facilitating seamless interaction with the Atlassian Jira API.",
   "main": "out/index.js",
   "types": "out/index.d.ts",
   "repository": "https://github.com/MrRefactoring/jira.js.git",
   "author": "Vladislav Tupikin <mrrefactoring@yandex.ru>",
   "license": "MIT",
   "keywords": [
-    "atlassian",
     "jira",
+    "javascript",
+    "typescript",
+    "nodejs",
+    "browser",
+    "atlassian",
     "api",
-    "agile",
-    "cloud",
-    "serviceDesk",
-    "wrapper",
     "client",
-    "rest"
+    "library"
   ],
   "scripts": {
     "build": "tsc",
@@ -62,32 +62,32 @@
     }
   },
   "devDependencies": {
-    "@swc-node/register": "1.6.6",
-    "@swc/helpers": "^0.5.1",
-    "@types/express": "^4.17.17",
-    "@types/node": "^20.5.9",
+    "@swc-node/register": "^1.6.8",
+    "@swc/helpers": "^0.5.2",
+    "@types/express": "^4.17.18",
+    "@types/node": "^20.8.0",
     "@types/oauth": "^0.9.2",
-    "@types/sinon": "^10.0.16",
-    "@typescript-eslint/eslint-plugin": "^6.6.0",
-    "@typescript-eslint/parser": "^6.6.0",
+    "@types/sinon": "^10.0.17",
+    "@typescript-eslint/eslint-plugin": "^6.7.3",
+    "@typescript-eslint/parser": "^6.7.3",
     "ava": "^5.3.1",
     "dotenv": "^16.3.1",
-    "eslint": "^8.48.0",
+    "eslint": "^8.50.0",
     "eslint-config-airbnb": "^19.0.4",
     "eslint-config-airbnb-typescript": "^17.1.0",
-    "eslint-import-resolver-typescript": "^3.6.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.28.1",
     "prettier": "^3.0.3",
-    "prettier-plugin-jsdoc": "^1.0.1",
-    "sinon": "^15.2.0",
+    "prettier-plugin-jsdoc": "^1.0.2",
+    "sinon": "^16.0.0",
     "ts-node": "^10.9.1",
     "typedoc": "^0.25.1",
     "typedoc-plugin-extras": "^3.0.0",
     "typescript": "^5.2.2"
   },
   "dependencies": {
     "atlassian-jwt": "^2.0.2",
-    "axios": "^1.5.0",
+    "axios": "^1.5.1",
     "form-data": "^4.0.0",
     "oauth": "^0.10.0",
     "tslib": "^2.6.2"

package.json

@@ -55,27 +55,68 @@ export class Dashboards {
    * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None.
    */
   async createDashboard<T = Models.Dashboard>(
-    parameters: Parameters.CreateDashboard | undefined,
+    parameters: Parameters.CreateDashboard,
     callback: Callback<T>,
   ): Promise<void>;
   /**
    * Creates a dashboard.
    *
    * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None.
    */
-  async createDashboard<T = Models.Dashboard>(parameters?: Parameters.CreateDashboard, callback?: never): Promise<T>;
+  async createDashboard<T = Models.Dashboard>(parameters: Parameters.CreateDashboard, callback?: never): Promise<T>;
   async createDashboard<T = Models.Dashboard>(
-    parameters?: Parameters.CreateDashboard,
+    parameters: Parameters.CreateDashboard,
     callback?: Callback<T>,
   ): Promise<void | T> {
     const config: RequestConfig = {
       url: '/rest/api/2/dashboard',
       method: 'POST',
       data: {
-        name: parameters?.name,
-        description: parameters?.description,
-        sharePermissions: parameters?.sharePermissions,
-        editPermissions: parameters?.editPermissions,
+        description: parameters.description,
+        editPermissions: parameters.editPermissions,
+        name: parameters.name,
+        sharePermissions: parameters.sharePermissions,
+      },
+    };
+
+    return this.client.sendRequest(config, callback);
+  }
+
+  /**
+   * Bulk edit dashboards. Maximum number of dashboards to be edited at the same time is 100.
+   *
+   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None
+   *
+   * The dashboards to be updated must be owned by the user, or the user must be an administrator.
+   */
+  async bulkEditDashboards<T = Models.BulkEditShareableEntity>(
+    parameters: Parameters.BulkEditDashboards,
+    callback: Callback<T>,
+  ): Promise<void>;
+  /**
+   * Bulk edit dashboards. Maximum number of dashboards to be edited at the same time is 100.
+   *
+   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None
+   *
+   * The dashboards to be updated must be owned by the user, or the user must be an administrator.
+   */
+  async bulkEditDashboards<T = Models.BulkEditShareableEntity>(
+    parameters: Parameters.BulkEditDashboards,
+    callback?: never,
+  ): Promise<T>;
+  async bulkEditDashboards<T = Models.BulkEditShareableEntity>(
+    parameters: Parameters.BulkEditDashboards,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: '/rest/api/2/dashboard/bulk/edit',
+      method: 'PUT',
+      data: {
+        action: parameters.action,
+        changeOwnerDetails: parameters.changeOwnerDetails,
+        entityIds: parameters.entityIds,
+        extendAdminPermissions: parameters.extendAdminPermissions,
+        permissionDetails: parameters.permissionDetails,
       },
     };
 
@@ -247,12 +288,12 @@ export class Dashboards {
       url: `/rest/api/2/dashboard/${parameters.dashboardId}/gadget`,
       method: 'POST',
       data: {
-        moduleKey: parameters.moduleKey,
-        uri: parameters.uri,
         color: parameters.color,
+        ignoreUriAndModuleKeyValidation: parameters.ignoreUriAndModuleKeyValidation,
+        moduleKey: parameters.moduleKey,
         position: parameters.position,
         title: parameters.title,
-        ignoreUriAndModuleKeyValidation: parameters.ignoreUriAndModuleKeyValidation,
+        uri: parameters.uri,
       },
     };
 
@@ -276,9 +317,9 @@ export class Dashboards {
       url: `/rest/api/2/dashboard/${parameters.dashboardId}/gadget/${parameters.gadgetId}`,
       method: 'PUT',
       data: {
-        title: parameters.title,
         color: parameters.color,
         position: parameters.position,
+        title: parameters.title,
       },
     };
 
@@ -608,10 +649,10 @@ export class Dashboards {
       url: `/rest/api/2/dashboard/${parameters.id}`,
       method: 'PUT',
       data: {
-        name: parameters.name,
         description: parameters.description,
-        sharePermissions: parameters.sharePermissions,
         editPermissions: parameters.editPermissions,
+        name: parameters.name,
+        sharePermissions: parameters.sharePermissions,
       },
     };
 
@@ -675,10 +716,10 @@ export class Dashboards {
       url: `/rest/api/2/dashboard/${parameters.id}/copy`,
       method: 'POST',
       data: {
-        name: parameters.name,
         description: parameters.description,
-        sharePermissions: parameters.sharePermissions,
         editPermissions: parameters.editPermissions,
+        name: parameters.name,
+        sharePermissions: parameters.sharePermissions,
       },
     };
 

src/version2/dashboards.ts

@@ -9,10 +9,7 @@ export class Filters {
 
   /**
    * @deprecated Returns all filters. Deprecated, use [Search for filters](#api-rest-api-2-filter-search-get) that
-   *   supports search and pagination.
-   *
-   *   This operation can be accessed anonymously.
-   *
+   *   supports search and pagination. This operation can be accessed anonymously.
    *   **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None,
    *   however, only the following filters are returned:
    *
@@ -29,10 +26,7 @@ export class Filters {
   ): Promise<void>;
   /**
    * @deprecated Returns all filters. Deprecated, use [ Search for filters](#api-rest-api-2-filter-search-get) that
-   *   supports search and pagination.
-   *
-   *   This operation can be accessed anonymously.
-   *
+   *   supports search and pagination. This operation can be accessed anonymously.
    *   **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None,
    *   however, only the following filters are returned:
    *
@@ -63,20 +57,17 @@ export class Filters {
    * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
    * Permission to access Jira.
    */
-  async createFilter<T = Models.Filter>(
-    parameters: Parameters.CreateFilter | undefined,
-    callback: Callback<T>,
-  ): Promise<void>;
+  async createFilter<T = Models.Filter>(parameters: Parameters.CreateFilter, callback: Callback<T>): Promise<void>;
   /**
    * Creates a filter. The filter is shared according to the [default share scope](#api-rest-api-2-filter-post). The
    * filter is not selected as a favorite.
    *
    * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
    * Permission to access Jira.
    */
-  async createFilter<T = Models.Filter>(parameters?: Parameters.CreateFilter, callback?: never): Promise<T>;
+  async createFilter<T = Models.Filter>(parameters: Parameters.CreateFilter, callback?: never): Promise<T>;
   async createFilter<T = Models.Filter>(
-    parameters?: Parameters.CreateFilter,
+    parameters: Parameters.CreateFilter,
     callback?: Callback<T>,
   ): Promise<void | T> {
     const config: RequestConfig = {
@@ -87,20 +78,20 @@ export class Filters {
         overrideSharePermissions: parameters?.overrideSharePermissions,
       },
       data: {
-        self: parameters?.self,
-        id: parameters?.id,
-        name: parameters?.name,
-        description: parameters?.description,
-        owner: parameters?.owner,
-        jql: parameters?.jql,
-        viewUrl: parameters?.viewUrl,
-        searchUrl: parameters?.searchUrl,
-        favourite: parameters?.favourite,
-        favouritedCount: parameters?.favouritedCount,
-        sharePermissions: parameters?.sharePermissions,
-        editPermissions: parameters?.editPermissions,
-        sharedUsers: parameters?.sharedUsers,
-        subscriptions: parameters?.subscriptions,
+        description: parameters.description,
+        editPermissions: parameters.editPermissions,
+        favourite: parameters.favourite,
+        favouritedCount: parameters.favouritedCount,
+        id: parameters.id,
+        jql: parameters.jql,
+        name: parameters.name,
+        owner: parameters.owner,
+        searchUrl: parameters.searchUrl,
+        self: parameters.self,
+        sharePermissions: parameters.sharePermissions,
+        sharedUsers: parameters.sharedUsers,
+        subscriptions: parameters.subscriptions,
+        viewUrl: parameters.viewUrl,
       },
     };
 

src/version2/filters.ts

@@ -10,19 +10,15 @@ export class Groups {
   /**
    * @deprecated This operation is deprecated, use
    *   [`group/member`](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-groups/#api-rest-api-2-group-member-get).
-   *
    *   Returns all users in a group.
-   *
    *   **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
    *   _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
    */
   async getGroup<T = Models.Group>(parameters: Parameters.GetGroup, callback: Callback<T>): Promise<void>;
   /**
    * @deprecated This operation is deprecated, use
    *   [`group/member`](https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-groups/#api-rest-api-2-group-member-get).
-   *
    *   Returns all users in a group.
-   *
    *   **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
    *   _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
    */

src/version2/groups.ts

@@ -3,19 +3,20 @@ import { Callback } from '../callback';
 import { Client } from '../clients';
 import { RequestConfig } from '../requestConfig';
 
+/** @deprecated Use {@link LicenseMetrics} */
 export class InstanceInformation {
   constructor(private client: Client) {}
 
   /**
-   * Returns licensing information about the Jira instance.
-   *
-   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None.
+   * @deprecated Use {@link LicenseMetrics.getLicense}. Returns licensing information about the Jira instance.
+   *   **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
+   *   None.
    */
   async getLicense<T = Models.License>(callback: Callback<T>): Promise<void>;
   /**
-   * Returns licensing information about the Jira instance.
-   *
-   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None.
+   * @deprecated Use {@link LicenseMetrics.getLicense}. Returns licensing information about the Jira instance.
+   *   **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
+   *   None.
    */
   async getLicense<T = Models.License>(callback?: never): Promise<T>;
   async getLicense<T = Models.License>(callback?: Callback<T>): Promise<void | T> {