Feature/#354 deprecation of jql search and evaluate expression endpoi…

…nts (#355)

* chore: Vulnerability fix

`npm fix audit`

* chore: fix error when running vitest

RangeError: options.minThreads and options.maxThreads must not conflict

Fixed by adding `--minWorkers=8` to `test:unit` in package.json

* test: define unit test for v3 enhanced search

* feat: implement v3 enhanced search

* chore: fix broken anchor

* test: define unit test for v2 enhanced search

* feat: implement v2 enhanced search

* chore: fix typo in v2

* chore: fix wrong interface name

* test: define unit test for v3 jiraExpressions

Only implemented unit test for the newly added function evaluateJiraExpressionUsingEnhancedSearch()

* feat: implement v3 jiraExpressions

Implemented new function evaluateJiraExpressionUsingEnhancedSearch()

* test: define unit test for v2 jiraExpressions

Only implemented unit test for the newly added function evaluateJiraExpressionUsingEnhancedSearch()

* feat: implement v2 jiraExpressions

Implemented new function evaluateJiraExpressionUsingEnhancedSearch()

* chore: change minWorkers to 1 for vitest

---------

Co-authored-by: Vladislav Tupikin <MrRefactoring@yandex.ru>

package.json

@@ -35,7 +35,7 @@
     "lint:fix": "npm run lint:tests -- --fix && npm run lint:examples -- --fix && npm run lint:src:agile -- --fix && npm run lint:src:clients -- --fix && npm run lint:src:services -- --fix && npm run lint:src:version2 -- --fix && npm run lint:src:version3 -- --fix && npm run lint:src:serviceDesk -- --fix && npm run lint:src:files -- --fix",
     "doc": "typedoc --name \"Jira.js - Jira Cloud API library\" --out docs ./src/index.ts --favicon ./assets/favicon.svg",
     "test": "npm run test:unit && npm run test:integration",
-    "test:unit": "vitest run tests/unit --maxWorkers=8 --sequence.concurrent",
+    "test:unit": "vitest run tests/unit --minWorkers=1 --maxWorkers=8 --sequence.concurrent",
     "test:integration": "vitest run tests/integration --bail=1 --no-file-parallelism --max-concurrency 1 -c vitest.config.mts --hookTimeout 100000 --testTimeout 100000",
     "replace:all": "npm run replace:permissions:version2 && npm run replace:permissions:version3 && npm run replace:pagination:version2 && npm run replace:pagination:version3 && npm run replace:async:version2 && npm run replace:async:version3 && npm run replace:expansion:version2 && npm run replace:expansion:version3 && npm run replace:ordering:version2 && npm run replace:ordering:version3 && npm run replace:groupMember:version2 && npm run replace:workflowPaginated:version2 && npm run replace:attachment:serviceDesk && npm run replace:priority:version3 && npm run replace:projectAvatar:version3 && npm run replace:issueType:version3",
     "replace:permissions:version2": "grep -rl \"(#permissions)\" ./src/version2 | xargs sed -i '' 's/(#permissions)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v2\\/intro\\/#permissions)/g'",

src/version2/issueSearch.ts

@@ -231,4 +231,144 @@ export class IssueSearch {
 
     return this.client.sendRequest(config, callback);
   }
+
+  /**
+   * Searches for issues using [JQL](https://confluence.atlassian.com/x/egORLQ). Recent updates might not be immediately
+   * visible in the returned search results.
+   *
+   * If you need [read-after-write](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/) consistency,
+   * you can utilize the `reconcileIssues` parameter to ensure stronger consistency assurances.
+   *
+   * If the JQL query expression is too large to be encoded as a query parameter, use the
+   * [POST](#searchforissuesusingjqlenhancedsearchpost) version of this resource.
+   *
+   * This operation can be accessed anonymously.
+   *
+   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** Issues
+   * are included in the response where the user has:
+   *
+   * - _Browse projects_ [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the
+   *   issue.
+   * - If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission
+   *   to view the issue.
+   */
+  async searchForIssuesUsingJqlEnhancedSearch<T = Models.SearchAndReconcileResults>(
+    parameters: Parameters.SearchForIssuesUsingJqlEnhancedSearch | undefined,
+    callback: Callback<T>,
+  ): Promise<void>;
+  /**
+   * Searches for issues using [JQL](https://confluence.atlassian.com/x/egORLQ). Recent updates might not be immediately
+   * visible in the returned search results.
+   *
+   * If you need [read-after-write](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/) consistency,
+   * you can utilize the `reconcileIssues` parameter to ensure stronger consistency assurances.
+   *
+   * If the JQL query expression is too large to be encoded as a query parameter, use the
+   * [POST](#searchforissuesusingjqlenhancedsearchpost) version of this resource.
+   *
+   * This operation can be accessed anonymously.
+   *
+   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** Issues
+   * are included in the response where the user has:
+   *
+   * - _Browse projects_ [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the
+   *   issue.
+   * - If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission
+   *   to view the issue.
+   */
+  async searchForIssuesUsingJqlEnhancedSearch<T = Models.SearchAndReconcileResults>(
+    parameters?: Parameters.SearchForIssuesUsingJqlEnhancedSearch,
+    callback?: never,
+  ): Promise<T>;
+  async searchForIssuesUsingJqlEnhancedSearch<T = Models.SearchAndReconcileResults>(
+    parameters?: Parameters.SearchForIssuesUsingJqlEnhancedSearch,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: '/rest/api/2/search/jql',
+      method: 'GET',
+      params: {
+        jql: parameters?.jql,
+        nextPageToken: parameters?.nextPageToken,
+        maxResults: parameters?.maxResults,
+        fields: parameters?.fields,
+        expand: parameters?.expand,
+        properties: parameters?.properties,
+        fieldsByKeys: parameters?.fieldsByKeys,
+        failFast: parameters?.failFast,
+        reconcileIssues: parameters?.reconcileIssues,
+      },
+    };
+
+    return this.client.sendRequest(config, callback);
+  }
+
+  /**
+   * Searches for issues using [JQL](https://confluence.atlassian.com/x/egORLQ).
+   *
+   * If you need [read-after-write](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/) consistency,
+   * you can utilize the `reconcileIssues` parameter to ensure stronger consistency assurances.
+   *
+   * There is a [GET](#searchforissuesusingjqlenhancedsearch) version of this resource that can be used for smaller JQL query
+   * expressions.
+   *
+   * This operation can be accessed anonymously.
+   *
+   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** Issues
+   * are included in the response where the user has:
+   *
+   * - _Browse projects_ [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the
+   *   issue.
+   * - If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission
+   *   to view the issue.
+   */
+  async searchForIssuesUsingJqlEnhancedSearchPost<T = Models.SearchAndReconcileResults>(
+    parameters: Parameters.SearchForIssuesUsingJqlEnhancedSearchPost | undefined,
+    callback: Callback<T>,
+  ): Promise<void>;
+  /**
+   * Searches for issues using [JQL](https://confluence.atlassian.com/x/egORLQ).
+   *
+   * If you need [read-after-write](https://developer.atlassian.com/cloud/jira/platform/search-and-reconcile/) consistency,
+   * you can utilize the `reconcileIssues` parameter to ensure stronger consistency assurances.
+   *
+   * There is a [GET](#searchforissuesusingjqlenhancedsearch) version of this resource that can be used for smaller JQL query
+   * expressions.
+   *
+   * This operation can be accessed anonymously.
+   *
+   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** Issues
+   * are included in the response where the user has:
+   *
+   * - _Browse projects_ [project permission](https://confluence.atlassian.com/x/yodKLg) for the project containing the
+   *   issue.
+   * - If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission
+   *   to view the issue.
+   */
+  async searchForIssuesUsingJqlEnhancedSearchPost<T = Models.SearchAndReconcileResults>(
+    parameters?: Parameters.SearchForIssuesUsingJqlEnhancedSearchPost,
+    callback?: never,
+  ): Promise<T>;
+  async searchForIssuesUsingJqlEnhancedSearchPost<T = Models.SearchAndReconcileResults>(
+    parameters?: Parameters.SearchForIssuesUsingJqlEnhancedSearchPost,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: '/rest/api/2/search',
+      method: 'POST',
+      data: {
+        jql: parameters?.jql,
+        nextPageToken: parameters?.nextPageToken,
+        maxResults: parameters?.maxResults,
+        fields: parameters?.fields,
+        expand: parameters?.expand,
+        properties: parameters?.properties,
+        fieldsByKeys: parameters?.fieldsByKeys,
+        failFast: parameters?.failFast,
+        reconcileIssues: parameters?.reconcileIssues,
+      },
+    };
+
+    return this.client.sendRequest(config, callback);
+  }
 }

src/version2/jiraExpressions.ts

@@ -190,4 +190,149 @@ export class JiraExpressions {
 
     return this.client.sendRequest(config, callback);
   }
+
+  /**
+   * Evaluates a Jira expression and returns its value. The difference between this and `eval` is that this endpoint
+   * uses the enhanced search API when evaluating JQL queries. This API is eventually consistent, unlike the strongly
+   * consistent `eval` API. This allows for better performance and scalability. In addition, this API's response for
+   * JQL evaluation is based on a scrolling view (backed by a `nextPageToken`) instead of a paginated view
+   * (backed by `startAt` and `totalCount`).
+   *
+   * This resource can be used to test Jira expressions that you plan to use elsewhere, or to fetch data in a flexible
+   * way. Consult the [Jira expressions
+   * documentation](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/) for more details.
+   *
+   * #### Context variables
+   *
+   * The following context variables are available to Jira expressions evaluated by this resource. Their presence
+   * depends on various factors; usually you need to manually request them in the context object sent in the payload,
+   * but some of them are added automatically under certain conditions.
+   *
+   * - `user` ([User](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)): The
+   *   current user. Always available and equal to `null` if the request is anonymous.
+   * - `app` ([App](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#app)): The
+   *   [Connect app](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps) that made the request.
+   *   Available only for authenticated requests made by Connect Apps (read more here: [Authentication for Connect
+   *   apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)).
+   * - `issue` ([Issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): The
+   *   current issue. Available only when the issue is provided in the request context object.
+   * - `issues` ([List](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#list) of
+   *   [Issues](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): A
+   *   collection of issues matching a JQL query. Available only when JQL is provided in the request context object.
+   * - `project` ([Project](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#project)):
+   *   The current project. Available only when the project is provided in the request context object.
+   * - `sprint` ([Sprint](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#sprint)):
+   *   The current sprint. Available only when the sprint is provided in the request context object.
+   * - `board` ([Board](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#board)): The
+   *   current board. Available only when the board is provided in the request context object.
+   * - `serviceDesk`
+   *   ([ServiceDesk](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#servicedesk)):
+   *   The current service desk. Available only when the service desk is provided in the request context object.
+   * - `customerRequest`
+   *   ([CustomerRequest](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#customerrequest)):
+   *   The current customer request. Available only when the customer request is provided in the request context
+   *   object.
+   *
+   * In addition, you can pass custom context variables along with their types. You can then access them from
+   * the Jira expression by key. You can use the following variables in a custom context:
+   *
+   * - `user`: A [user](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)
+   *   specified as an Atlassian account ID.
+   * - `issue`: An [issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)
+   *   specified by ID or key. All the fields of the issue object are available in the Jira expression.
+   * - `json`: A JSON object containing custom content.
+   * - `list`: A JSON list of `user`, `issue`, or `json` variable types.
+   *
+   * This operation can be accessed anonymously.
+   *
+   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required**: None.
+   * However, an expression may return different results for different users depending on their permissions. For
+   * example, different users may see different comments on the same issue. Permission to access Jira Software is
+   * required to access Jira Software context variables (`board` and `sprint`) or fields (for example, `issue.sprint`).
+   */
+  async evaluateJiraExpressionUsingEnhancedSearch<T = Models.JExpEvaluateJiraExpressionResult>(
+    parameters: Parameters.EvaluateJiraExpressionUsingEnhancedSearch | undefined,
+    callback: Callback<T>,
+  ): Promise<void>;
+  /**
+   * Evaluates a Jira expression and returns its value. The difference between this and `eval` is that this endpoint
+   * uses the enhanced search API when evaluating JQL queries. This API is eventually consistent, unlike the strongly
+   * consistent `eval` API. This allows for better performance and scalability. In addition, this API's response for
+   * JQL evaluation is based on a scrolling view (backed by a `nextPageToken`) instead of a paginated view
+   * (backed by `startAt` and `totalCount`).
+   *
+   * This resource can be used to test Jira expressions that you plan to use elsewhere, or to fetch data in a flexible
+   * way. Consult the [Jira expressions
+   * documentation](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/) for more details.
+   *
+   * #### Context variables
+   *
+   * The following context variables are available to Jira expressions evaluated by this resource. Their presence
+   * depends on various factors; usually you need to manually request them in the context object sent in the payload,
+   * but some of them are added automatically under certain conditions.
+   *
+   * - `user` ([User](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)): The
+   *   current user. Always available and equal to `null` if the request is anonymous.
+   * - `app` ([App](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#app)): The
+   *   [Connect app](https://developer.atlassian.com/cloud/jira/platform/index/#connect-apps) that made the request.
+   *   Available only for authenticated requests made by Connect Apps (read more here: [Authentication for Connect
+   *   apps](https://developer.atlassian.com/cloud/jira/platform/security-for-connect-apps/)).
+   * - `issue` ([Issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): The
+   *   current issue. Available only when the issue is provided in the request context object.
+   * - `issues` ([List](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#list) of
+   *   [Issues](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)): A
+   *   collection of issues matching a JQL query. Available only when JQL is provided in the request context object.
+   * - `project` ([Project](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#project)):
+   *   The current project. Available only when the project is provided in the request context object.
+   * - `sprint` ([Sprint](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#sprint)):
+   *   The current sprint. Available only when the sprint is provided in the request context object.
+   * - `board` ([Board](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#board)): The
+   *   current board. Available only when the board is provided in the request context object.
+   * - `serviceDesk`
+   *   ([ServiceDesk](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#servicedesk)):
+   *   The current service desk. Available only when the service desk is provided in the request context object.
+   * - `customerRequest`
+   *   ([CustomerRequest](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#customerrequest)):
+   *   The current customer request. Available only when the customer request is provided in the request context
+   *   object.
+   *
+   * In addition, you can pass custom context variables along with their types. You can then access them from
+   * the Jira expression by key. You can use the following variables in a custom context:
+   *
+   * - `user`: A [user](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#user)
+   *   specified as an Atlassian account ID.
+   * - `issue`: An [issue](https://developer.atlassian.com/cloud/jira/platform/jira-expressions-type-reference#issue)
+   *   specified by ID or key. All the fields of the issue object are available in the Jira expression.
+   * - `json`: A JSON object containing custom content.
+   * - `list`: A JSON list of `user`, `issue`, or `json` variable types.
+   *
+   * This operation can be accessed anonymously.
+   *
+   * **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required**: None.
+   * However, an expression may return different results for different users depending on their permissions. For
+   * example, different users may see different comments on the same issue. Permission to access Jira Software is
+   * required to access Jira Software context variables (`board` and `sprint`) or fields (for example, `issue.sprint`).
+   */
+  async evaluateJiraExpressionUsingEnhancedSearch<T = Models.JExpEvaluateJiraExpressionResult>(
+    parameters?: Parameters.EvaluateJiraExpressionUsingEnhancedSearch,
+    callback?: never,
+  ): Promise<T>;
+  async evaluateJiraExpressionUsingEnhancedSearch<T = Models.JExpEvaluateJiraExpressionResult>(
+    parameters?: Parameters.EvaluateJiraExpressionUsingEnhancedSearch,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: '/rest/api/2/expression/evaluate',
+      method: 'POST',
+      params: {
+        expand: parameters?.expand,
+      },
+      data: {
+        expression: parameters?.expression,
+        context: parameters?.context,
+      },
+    };
+
+    return this.client.sendRequest(config, callback);
+  }
 }