feat: implement v3 jiraExpressions

Implemented new function evaluateJiraExpressionUsingEnhancedSearch()

src/version3/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/v3/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/v3/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/3/expression/evaluate',
+      method: 'POST',
+      params: {
+        expand: parameters?.expand,
+      },
+      data: {
+        expression: parameters?.expression,
+        context: parameters?.context,
+      },
+    };
+
+    return this.client.sendRequest(config, callback);
+  }
 }

src/version3/models/index.ts

@@ -161,6 +161,7 @@ export * from './issueArchivalSync';
 export * from './issueArchivalSyncRequest';
 export * from './issueChangelogIds';
 export * from './issueCommentListRequest';
+export * from './issueContextVariable';
 export * from './issueCreateMetadata';
 export * from './issueEntityProperties';
 export * from './issueEntityPropertiesForMultiUpdate';
@@ -215,13 +216,21 @@ export * from './issueTypeWithStatus';
 export * from './issueTypeWorkflowMapping';
 export * from './issueUpdateDetails';
 export * from './issueUpdateMetadata';
+export * from './jexpEvaluateCtxIssues';
+export * from './jexpEvaluateCtxJqlIssues';
+export * from './jExpEvaluateIssuesJqlMetaData';
+export * from './jExpEvaluateIssuesMeta';
+export * from './jExpEvaluateJiraExpressionResult';
+export * from './jExpEvaluateMetaData';
+export * from './jiraExpressionEvaluateContext';
 export * from './jexpIssues';
 export * from './jexpJqlIssues';
 export * from './jiraExpressionAnalysis';
 export * from './jiraExpressionComplexity';
 export * from './jiraExpressionEvalContext';
 export * from './jiraExpressionEvalRequest';
 export * from './jiraExpressionEvaluationMetaData';
+export * from './jiraExpressionEvalUsingEnhancedSearchRequest';
 export * from './jiraExpressionForAnalysis';
 export * from './jiraExpressionResult';
 export * from './jiraExpressionsAnalysis';
@@ -244,6 +253,7 @@ export * from './jqlQueryOrderByClauseElement';
 export * from './jqlQueryToSanitize';
 export * from './jQLQueryWithUnknownUsers';
 export * from './jQLReferenceData';
+export * from './jsonContextVariable';
 export * from './jsonType';
 export * from './license';
 export * from './licensedApplication';
@@ -468,6 +478,7 @@ export * from './updateUiModificationDetails';
 export * from './updateUserToGroup';
 export * from './user';
 export * from './userAvatarUrls';
+export * from './userContextVariable';
 export * from './userDetails';
 export * from './userKey';
 export * from './userList';

src/version3/models/issueContextVariable.ts

@@ -0,0 +1,8 @@
+export interface IssueContextVariable {
+  /** The issue ID. */
+  id?: number;
+  /** The issue key. */
+  key?: string;
+  /** Type of custom context variable. */
+  type: string;
+}

src/version3/models/jExpEvaluateIssuesJqlMetaData.ts

@@ -0,0 +1,5 @@
+/** The description of the page of issues loaded by the provided JQL query. */
+export interface JExpEvaluateIssuesJqlMetaData {
+  /** Next Page token for the next page of issues. */
+  nextPageToken?: string;
+}

src/version3/models/jExpEvaluateIssuesMeta.ts

@@ -0,0 +1,10 @@
+import { JExpEvaluateIssuesJqlMetaData } from './jExpEvaluateIssuesJqlMetaData';
+
+/** Meta data describing the `issues` context variable. */
+export interface JExpEvaluateIssuesMeta {
+  /**
+   * The description of the page of issues loaded by the provided JQL query.
+   * This bean will be replacing IssuesJqlMetaDataBean bean as part of new `evaluate` endpoint
+   */
+  jql?: JExpEvaluateIssuesJqlMetaData;
+}

src/version3/models/jExpEvaluateJiraExpressionResult.ts

@@ -0,0 +1,13 @@
+import { JExpEvaluateMetaData } from './jExpEvaluateMetaData';
+
+/** The result of evaluating a Jira expression. */
+export interface JExpEvaluateJiraExpressionResult {
+  /**
+   * The value of the evaluated expression. It may be a primitive JSON value or a Jira REST API object. (Some
+   * expressions do not produce any meaningful results—for example, an expression that returns a lambda function—if
+   * that's the case a simple string representation is returned. These string representations should not be relied upon
+   * and may change without notice.)
+   */
+  value: any;
+  meta?: JExpEvaluateMetaData;
+}

src/version3/models/jExpEvaluateMetaData.ts

@@ -0,0 +1,15 @@
+import { JExpEvaluateIssuesMeta } from './jExpEvaluateIssuesMeta';
+import { JiraExpressionsComplexity } from './jiraExpressionsComplexity';
+
+export interface JExpEvaluateMetaData {
+  /**
+   * Contains information about the expression complexity. For example, the number of steps it took to
+   * evaluate the expression.
+   */
+  complexity?: JiraExpressionsComplexity;
+  /**
+   * Contains information about the `issues` variable in the context. For example, is the issues were loaded
+   * with JQL, information about the page will be included here.
+   */
+  issues?: JExpEvaluateIssuesMeta;
+}

src/version3/models/jexpEvaluateCtxIssues.ts

@@ -0,0 +1,6 @@
+import { JexpEvaluateCtxJqlIssues } from './jexpEvaluateCtxJqlIssues';
+
+/** The JQL specifying the issues available in the evaluated Jira expression under the `issues` context variable. */
+export interface JexpEvaluateCtxIssues {
+  jql?: JexpEvaluateCtxJqlIssues;
+}

src/version3/models/jexpEvaluateCtxJqlIssues.ts

@@ -0,0 +1,17 @@
+/**
+ * The JQL query that specifies the set of issues available in the Jira expression.
+ */
+export interface JexpEvaluateCtxJqlIssues {
+  /**
+   * The maximum number of issues to return from the JQL query. Inspect `meta.issues.jql.maxResults` in the response to
+   * ensure the maximum value has not been exceeded.
+   */
+  maxResults?: number;
+  /**
+   * The token for a page to fetch that is not the first page. The first page has a `nextPageToken` of `null`.
+   * Use the `nextPageToken` to fetch the next page of issues.
+   */
+  nextPageToken?: string;
+  /** The JQL query, required to be bounded. Additionally, `orderBy` clause can contain a maximum of 7 fields */
+  query?: string;
+}

src/version3/models/jiraExpressionEvalUsingEnhancedSearchRequest.ts

@@ -0,0 +1,8 @@
+import { JiraExpressionEvaluateContext } from './jiraExpressionEvaluateContext';
+
+export interface JiraExpressionEvalUsingEnhancedSearchRequest {
+  /** The Jira expression to evaluate. */
+  expression: string;
+  /** The context in which the Jira expression is evaluated. */
+  context?: JiraExpressionEvaluateContext;
+}

src/version3/models/jiraExpressionEvaluateContext.ts

@@ -0,0 +1,37 @@
+import { IssueContextVariable } from './issueContextVariable';
+import { JsonContextVariable } from './jsonContextVariable';
+import { UserContextVariable } from './userContextVariable';
+import { IdOrKey } from './idOrKey';
+import { JexpEvaluateCtxIssues } from './jexpEvaluateCtxIssues';
+
+export interface JiraExpressionEvaluateContext {
+  issue?: IdOrKey;
+  issues?: JexpEvaluateCtxIssues;
+  project?: IdOrKey;
+  /** The ID of the sprint that is available under the `sprint` variable when evaluating the expression. */
+  sprint?: number;
+  /** The ID of the board that is available under the `board` variable when evaluating the expression. */
+  board?: number;
+  /** The ID of the service desk that is available under the `serviceDesk` variable when evaluating the expression. */
+  serviceDesk?: number;
+  /**
+   * The ID of the customer request that is available under the `customerRequest` variable when evaluating the
+   * expression. This is the same as the ID of the underlying Jira issue, but the customer request context variable will
+   * have a different type.
+   */
+  customerRequest?: number;
+  /**
+   * Custom context variables and their types. These variable types are available for use 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.
+   */
+  custom?: (
+    | UserContextVariable
+    | IssueContextVariable
+    | JsonContextVariable
+  )[];
+}

src/version3/models/jsonContextVariable.ts

@@ -0,0 +1,6 @@
+export interface JsonContextVariable {
+  /** Type of custom context variable. */
+  type: string;
+  /** A JSON object containing custom content. */
+  value?: any;
+}

src/version3/models/userContextVariable.ts

@@ -0,0 +1,6 @@
+export interface UserContextVariable {
+  /** The account ID of the user. */
+  accountId: string;
+  /** Type of custom context variable. */
+  type: string;
+}

src/version3/parameters/evaluateJiraExpressionUsingEnhancedSearch.ts

@@ -0,0 +1,13 @@
+import { JiraExpressionEvalUsingEnhancedSearchRequest } from '../models';
+
+export interface EvaluateJiraExpressionUsingEnhancedSearch extends JiraExpressionEvalUsingEnhancedSearchRequest {
+  /**
+   * Use [expand](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#expansion) to include additional
+   * information in the response. This parameter accepts `meta.complexity` that returns information about the expression
+   * complexity. For example, the number of expensive operations used by the expression and how close the expression is
+   * to reaching the [complexity
+   * limit](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#restrictions). Useful when designing
+   * and debugging your expressions.
+   */
+  expand?: string;
+}

src/version3/parameters/index.ts

@@ -140,6 +140,7 @@ export * from './deleteWorklogProperty';
 export * from './doTransition';
 export * from './editIssue';
 export * from './evaluateJiraExpression';
+export * from './evaluateJiraExpressionUsingEnhancedSearch';
 export * from './expandAttachmentForHumans';
 export * from './expandAttachmentForMachines';
 export * from './exportArchivedIssues';