parameters types improvements

examples/src/addFixVersion.ts

@@ -1,6 +1,6 @@
+import { createIssue } from './utils';
 import { Version3Client } from 'jira.js';
-import { apiToken, email, host } from "./credentials";
-import { createIssue } from "./utils";
+import { apiToken, email, host } from './credentials';
 
 async function addFixVersion() {
   const client = new Version3Client({
@@ -14,9 +14,9 @@ async function addFixVersion() {
 
   const fix = await client.issueProperties.setIssueProperty({
     issueIdOrKey,
-    propertyKey: "fixVersion",
+    propertyKey: 'fixVersion',
     // @ts-ignore
-    propertyValue: "N/a",
+    propertyValue: 'N/a',
   });
 
   console.log(fix);

examples/src/addWorklog.ts

@@ -1,6 +1,6 @@
-import { createIssue } from "./utils";
-import { Version3Client } from "jira.js";
-import { apiToken, email, host } from "./credentials";
+import { createIssue } from './utils';
+import { Version3Client } from 'jira.js';
+import { apiToken, email, host } from './credentials';
 
 async function addWorklog() {
   const client = new Version3Client({
@@ -20,7 +20,7 @@ async function addWorklog() {
     timeSpentSeconds: 60, // Required one of `timeSpentSeconds` or `timeSpent`
   });
 
-  console.log(`Worklog successfully added for Issue Id: ${worklog.issueId}`)
+  console.log(`Worklog successfully added for Issue Id: ${worklog.issueId}`);
 }
 
 addWorklog().catch(e => {

examples/src/basic.ts

@@ -1,5 +1,5 @@
 import { Version3Client } from 'jira.js';
-import { host, email, apiToken } from './credentials';
+import { apiToken, email, host } from './credentials';
 
 const client = new Version3Client({
   host,
@@ -18,12 +18,12 @@ async function main() {
       fields: {
         summary: 'My first issue',
         issuetype: {
-          name: 'Task'
+          name: 'Task',
         },
         project: {
           key: project.key,
         },
-      }
+      },
     });
 
     const issue = await client.issues.getIssue({ issueIdOrKey: id });
@@ -34,7 +34,7 @@ async function main() {
 
     const { id } = await client.projects.createProject({
       key: 'PROJECT',
-      name: "My Project",
+      name: 'My Project',
       leadAccountId: myself.accountId,
       projectTypeKey: 'software',
     });

examples/src/getAllWorklogs.ts

@@ -1,12 +1,12 @@
-import { Version3Client } from "jira.js";
-import { addWorklog, createIssue } from "./utils";
-import { apiToken, email, host } from "./credentials";
+import { Version3Client } from 'jira.js';
+import { addWorklog, createIssue } from './utils';
+import { apiToken, email, host } from './credentials';
 
 async function getAllWorklogs() {
   const client = new Version3Client({
     host,
     authentication: {
-      basic: { email, apiToken }
+      basic: { email, apiToken },
     },
   });
 

examples/src/utils/addWorklog.ts

@@ -1,9 +1,9 @@
-import { Version3Client, Version3Models } from "jira.js";
+import { Version3Client, Version3Models } from 'jira.js';
 
 export const addWorklog = async (client: Version3Client, issue: Version3Models.Issue) => {
   await client.issueWorklogs.addWorklog({
     issueIdOrKey: issue.id,
     comment: 'My first worklog',
     timeSpentSeconds: 60,
-  })
+  });
 };

examples/src/utils/createIssue.ts

@@ -1,4 +1,4 @@
-import { Version3Client } from "jira.js";
+import { Version3Client } from 'jira.js';
 
 export const createIssue = async (client: Version3Client) => {
   const projects = await client.projects.getAllProjects();
@@ -10,12 +10,12 @@ export const createIssue = async (client: Version3Client) => {
       fields: {
         summary: 'My first issue',
         issuetype: {
-          name: 'Task'
+          name: 'Task',
         },
         project: {
           key,
         },
-      }
+      },
     });
 
     return client.issues.getIssue({ issueIdOrKey: id });

package.json

@@ -21,8 +21,9 @@
   "scripts": {
     "build": "tsc",
     "prettier": "prettier --write src",
-    "lint": "npm run lint:tests && npm run lint:src:agile && npm run lint:src:clients && npm run lint:src:services && npm run lint:src:version2 && npm run lint:src:version3 && npm run lint:src:files",
+    "lint": "npm run lint:tests && npm run lint:examples && npm run lint:src:agile && npm run lint:src:clients && npm run lint:src:services && npm run lint:src:version2 && npm run lint:src:version3 && npm run lint:src:files",
     "lint:tests": "npm run lint:base -- tests",
+    "lint:examples": "npm run lint:base -- examples",
     "lint:src:agile": "npm run lint:base -- src/agile",
     "lint:src:clients": "npm run lint:base -- src/clients",
     "lint:src:services": "npm run lint:base -- src/services",
@@ -31,12 +32,12 @@
     "lint:src:serviceDesk": "npm run lint:base -- src/serviceDesk",
     "lint:src:files": "npm run lint:base -- src/*.ts",
     "lint:base": "eslint --ext .ts",
-    "lint:fix": "npm run lint:tests -- --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",
+    "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 --plugin typedoc-plugin-extras --footerDate --footerTime --footerTypedocVersion --favicon https://svgshare.com/i/bHF.svg",
     "test": "npm run test:unit && npm run test:integration",
     "test:unit": "ava tests/unit --timeout=2m -с 8",
     "test:integration": "ava --timeout=2m --fail-fast --no-worker-threads -c 1 -s tests/integration/**/*.test.ts",
-    "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:groupMember:version2 && npm run replace:workflowPaginated:version2",
+    "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",
     "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'",
     "replace:permissions:version3": "grep -rl \"(#permissions)\" ./src/version3 | xargs sed -i '' 's/(#permissions)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v3\\/intro\\/#permissions)/g'",
     "replace:pagination:version2": "grep -rl \"(#pagination)\" ./src/version2 | xargs sed -i '' 's/(#pagination)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v2\\/intro\\/#pagination)/g'",
@@ -46,6 +47,7 @@
     "replace:expansion:version2": "grep -rl \"(#expansion)\" ./src/version2 | xargs sed -i '' 's/(#expansion)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v2\\/intro\\/#expansion)/g'",
     "replace:expansion:version3": "grep -rl \"(#expansion)\" ./src/version3 | xargs sed -i '' 's/(#expansion)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v3\\/intro\\/#expansion)/g'",
     "replace:ordering:version2": "grep -rl \"(#ordering)\" ./src/version2 | xargs sed -i '' 's/(#ordering)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v2\\/intro\\/#ordering)/g'",
+    "replace:ordering:version3": "grep -rl \"(#ordering)\" ./src/version3 | xargs sed -i '' 's/(#ordering)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v3\\/intro\\/#ordering)/g'",
     "replace:groupMember:version2": "grep -rl \"(#api-rest-api-2-group-member-get)\" ./src/version2 | xargs sed -i '' 's/(#api-rest-api-2-group-member-get)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v2\\/api-group-groups\\/#api-rest-api-2-group-member-get)/g'",
     "replace:workflowPaginated:version2": "grep -rl \"(#api-rest-api-2-workflow-search-get)\" ./src/version2 | xargs sed -i '' 's/(#api-rest-api-2-workflow-search-get)/(https:\\/\\/developer.atlassian.com\\/cloud\\/jira\\/platform\\/rest\\/v2\\/api-group-workflows\\/#api-rest-api-2-workflow-search-get)/g'",
     "code:formatting": "npm run replace:all && npm run prettier && npm run lint:fix"

src/version2/issueComments.ts

@@ -155,7 +155,7 @@ export class IssueComments {
         self: parameters.self,
         id: parameters.id,
         author: parameters.author,
-        body: parameters.body,
+        body: parameters.comment,
         renderedBody: parameters.renderedBody,
         updateAuthor: parameters.updateAuthor,
         created: parameters.created,
@@ -259,7 +259,7 @@ export class IssueComments {
         expand: parameters.expand,
       },
       data: {
-        body: parameters.body,
+        body: parameters.comment,
         visibility: parameters.visibility,
         properties: parameters.properties,
       },

src/version2/models/comment.ts

@@ -6,7 +6,7 @@ import { Visibility } from './visibility';
 export interface Comment {
   author?: UserDetails;
   /** The comment text. */
-  body?: string;
+  comment?: string;
   /** The date and time at which the comment was created. */
   created?: string;
   /** The ID of the comment. */

src/version3/dashboards.ts

@@ -537,7 +537,7 @@ export class Dashboards {
       headers: {
         'Content-Type': 'application/json',
       },
-      data: parameters.body,
+      data: parameters.propertyValue,
     };
 
     return this.client.sendRequest(config, callback);

src/version3/issueComments.ts

@@ -146,18 +146,18 @@ export class IssueComments {
   async addComment<T = Models.Comment>(parameters: Parameters.AddComment, callback?: never): Promise<T>;
   async addComment<T = Models.Comment>(parameters: Parameters.AddComment, callback?: Callback<T>): Promise<void | T> {
     const body =
-      typeof parameters.body === 'string'
+      typeof parameters.comment === 'string'
         ? {
           type: 'doc',
           version: 1,
           content: [
             {
               type: 'paragraph',
-              content: [{ type: 'text', text: parameters.body }],
+              content: [{ type: 'text', text: parameters.comment }],
             },
           ],
         }
-        : parameters.body;
+        : parameters.comment;
 
     const config: RequestConfig = {
       url: `/rest/api/3/issue/${parameters.issueIdOrKey}/comment`,

src/version3/parameters/addActorUsers.ts

@@ -1,7 +1,7 @@
 import { ActorsMap } from '../models';
 
 export interface AddActorUsers extends ActorsMap {
-  /** The project ID or project key (case-sensitive). */
+  /** The project ID or project key (case sensitive). */
   projectIdOrKey: string;
   /**
    * The ID of the project role. Use [Get all project roles](#api-rest-api-3-role-get) to get a list of project role

src/version3/parameters/addComment.ts

@@ -13,5 +13,5 @@ export interface AddComment extends Omit<Comment, 'body'> {
    * The comment text in [Atlassian Document
    * Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
    */
-  body?: string | Document;
+  comment?: string | Document;
 }

src/version3/parameters/addWorklog.ts

@@ -8,11 +8,12 @@ export interface AddWorklog extends Omit<Worklog, 'comment'> {
   /**
    * Defines how to update the issue's time estimate, the options are:
    *
-   * `new` Sets the estimate to a specific value, defined in `newEstimate`. `leave` Leaves the estimate unchanged.
-   * `manual` Reduces the estimate by amount specified in `reduceBy`. `auto` Reduces the estimate by the value of
-   * `timeSpent` in the worklog.
+   * - `new` Sets the estimate to a specific value, defined in `newEstimate`.
+   * - `leave` Leaves the estimate unchanged.
+   * - `manual` Reduces the estimate by amount specified in `reduceBy`.
+   * - `auto` Reduces the estimate by the value of `timeSpent` in the worklog.
    */
-  adjustEstimate?: string;
+  adjustEstimate?: 'new' | 'leave' | 'manual' | 'auto' | string;
   /**
    * A comment about the worklog in [Atlassian Document
    * Format](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/). Optional when creating or
@@ -34,11 +35,11 @@ export interface AddWorklog extends Omit<Worklog, 'comment'> {
    * information about work logs in the response. This parameter accepts `properties`, which returns worklog
    * properties.
    */
-  expand?: string | string[];
+  expand?: 'properties' | 'properties'[] | string | string[];
   /**
    * Whether the worklog entry should be added to the issue even if the issue is not editable, because
-   * jira.issue.editable set to false or missing. For example, the issue is closed. Connect app users with admin
-   * permission and Forge app users with the `manage:jira-configuration` scope can use this flag.
+   * jira.issue.editable set to false or missing. For example, the issue is closed. Connect and Forge app users with
+   * _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg) can use this flag.
    */
   overrideEditableFlag?: boolean;
 }

src/version3/parameters/analyseExpression.ts

@@ -4,13 +4,14 @@ export interface AnalyseExpression extends JiraExpressionForAnalysis {
   /**
    * The check to perform:
    *
-   * `syntax` Each expression's syntax is checked to ensure the expression can be parsed. Also, syntactic limits are
-   * validated. For example, the expression's length. `type` EXPERIMENTAL. Each expression is type checked and the final
-   * type of the expression inferred. Any type errors that would result in the expression failure at runtime are
-   * reported. For example, accessing properties that don't exist or passing the wrong number of arguments to functions.
-   * Also performs the syntax check. `complexity` EXPERIMENTAL. Determines the formulae for how many [expensive
-   * operations](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#expensive-operations) each
-   * expression may execute.
+   * - `syntax` Each expression's syntax is checked to ensure the expression can be parsed. Also, syntactic limits are
+   *   validated. For example, the expression's length.
+   * - `type` EXPERIMENTAL. Each expression is type checked and the final type of the expression inferred. Any type errors
+   *   that would result in the expression failure at runtime are reported. For example, accessing properties that don't
+   *   exist or passing the wrong number of arguments to functions. Also performs the syntax check.
+   * - `complexity` EXPERIMENTAL. Determines the formulae for how many [expensive
+   *   operations](https://developer.atlassian.com/cloud/jira/platform/jira-expressions/#expensive-operations) each
+   *   expression may execute.
    */
-  check?: string;
+  check?: 'syntax' | 'type' | 'complexity' | string;
 }

src/version3/parameters/assignPermissionScheme.ts

@@ -8,10 +8,21 @@ export interface AssignPermissionScheme extends Id {
    * information in the response. This parameter accepts a comma-separated list. Note that permissions are included when
    * you specify any value. Expand options include:
    *
-   * `all` Returns all expandable information. `field` Returns information about the custom field granted the
-   * permission. `group` Returns information about the group that is granted the permission. `permissions` Returns all
-   * permission grants for each permission scheme. `projectRole` Returns information about the project role granted the
-   * permission. `user` Returns information about the user who is granted the permission.
+   * - `all` Returns all expandable information.
+   * - `field` Returns information about the custom field granted the permission.
+   * - `group` Returns information about the group that is granted the permission.
+   * - `permissions` Returns all permission grants for each permission scheme.
+   * - `projectRole` Returns information about the project role granted the permission.
+   * - `user` Returns information about the user who is granted the permission.
    */
-  expand?: string;
+  expand?:
+  | 'all'
+  | 'field'
+  | 'group'
+  | 'permissions'
+  | 'projectRole'
+  | 'user'
+  | ('all' | 'field' | 'group' | 'permissions' | 'projectRole' | 'user')[]
+  | string
+  | string[];
 }

src/version3/parameters/createIssue.ts

@@ -3,7 +3,8 @@ import { Document, IssueUpdateDetails, Project, TimeTrackingDetails } from '../m
 export interface CreateIssue extends Omit<IssueUpdateDetails, 'fields'> {
   /**
    * Whether the project in which the issue is created is added to the user's **Recently viewed** project list, as shown
-   * under **Projects** in Jira.
+   * under **Projects** in Jira. When provided, the issue type and request type are added to the user's history for a
+   * project. These values are then used to provide defaults on the issue create screen.
    */
   updateHistory?: boolean;
 

src/version3/parameters/createWorkflowTransitionProperty.ts

@@ -17,5 +17,5 @@ export interface CreateWorkflowTransitionProperty extends WorkflowTransitionProp
    * The workflow status. Set to _live_ for inactive workflows or _draft_ for draft workflows. Active workflows cannot
    * be edited.
    */
-  workflowMode?: string;
+  workflowMode?: 'live' | 'draft' | string;
 }

src/version3/parameters/deleteActor.ts

@@ -1,5 +1,5 @@
 export interface DeleteActor {
-  /** The project ID or project key (case-sensitive). */
+  /** The project ID or project key (case sensitive). */
   projectIdOrKey: string;
   /**
    * The ID of the project role. Use [Get all project roles](#api-rest-api-3-role-get) to get a list of project role

src/version3/parameters/deleteAvatar.ts

@@ -1,6 +1,6 @@
 export interface DeleteAvatar {
   /** The avatar type. */
-  type: string;
+  type: 'project' | 'issuetype' | string;
   /** The ID of the item the avatar is associated with. */
   owningObjectId: string;
   /** The ID of the avatar. */

src/version3/parameters/deleteIssue.ts

@@ -2,5 +2,5 @@ export interface DeleteIssue {
   /** The ID or key of the issue. */
   issueIdOrKey: string;
   /** Whether the issue's subtasks are deleted when the issue is deleted. */
-  deleteSubtasks?: string;
+  deleteSubtasks?: boolean;
 }

src/version3/parameters/deleteStatusesById.ts

@@ -3,7 +3,7 @@ export interface DeleteStatusesById {
    * The list of status IDs. To include multiple IDs, provide an ampersand-separated list. For example,
    * id=10000&id=10001.
    *
-   *     Min items `1`, Max items `50`
+   * Min items `1`, Max items `50`
    */
   id?: string[];
 }

src/version3/parameters/deleteWorkflowTransitionProperty.ts

@@ -12,5 +12,5 @@ export interface DeleteWorkflowTransitionProperty {
    * The workflow status. Set to `live` for inactive workflows or `draft` for draft workflows. Active workflows cannot
    * be edited.
    */
-  workflowMode?: string;
+  workflowMode?: 'live' | 'draft' | string;
 }

src/version3/parameters/deleteWorklog.ts

@@ -8,11 +8,12 @@ export interface DeleteWorklog {
   /**
    * Defines how to update the issue's time estimate, the options are:
    *
-   * `new` Sets the estimate to a specific value, defined in `newEstimate`. `leave` Leaves the estimate unchanged.
-   * `manual` Increases the estimate by amount specified in `increaseBy`. `auto` Reduces the estimate by the value of
-   * `timeSpent` in the worklog.
+   * - `new` Sets the estimate to a specific value, defined in `newEstimate`.
+   * - `leave` Leaves the estimate unchanged.
+   * - `manual` Increases the estimate by amount specified in `increaseBy`.
+   * - `auto` Reduces the estimate by the value of `timeSpent` in the worklog.
    */
-  adjustEstimate?: string;
+  adjustEstimate?: 'new' | 'leave' | 'manual' | 'auto' | string;
   /**
    * The value to set as the issue's remaining time estimate, as days (#d), hours (#h), or minutes (#m or #). For
    * example, _2d_. Required when `adjustEstimate` is `new`.
@@ -25,8 +26,8 @@ export interface DeleteWorklog {
   increaseBy?: string;
   /**
    * Whether the work log entry should be added to the issue even if the issue is not editable, because
-   * jira.issue.editable set to false or missing. For example, the issue is closed. Connect app users with admin
-   * permission and Forge app users with the `manage:jira-configuration` scope can use this flag.
+   * jira.issue.editable set to false or missing. For example, the issue is closed. Connect and Forge app users with
+   * admin permission can use this flag.
    */
   overrideEditableFlag?: boolean;
 }