Skip to content

Commit 2ae447c

Browse files
MrRefactoringMrRefactoring
authored
API updates (MrRefactoring#228)
* Version 2 API updates * Version 3 API updates
1 parent a117dea commit 2ae447c

23 files changed

+457
-266
lines changed

‎CHANGELOG.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# Jira.js changelog
22

3+
### 2.15.8
4+
5+
- JSDoc improvements.
6+
- Version 2, 3:
7+
- `getTrashedFieldsPaginated` method added to `IssueFields` API.
8+
- `statusCategory` property added to `search` method in `Status` API.
9+
310
### 2.15.7
411

512
Version 2, 3: Added additional properties for `IssueComments.updateComment` method. Thanks to [chandler05](https://github.com/chandler05) for reporting the issue.

‎package-lock.json

Lines changed: 178 additions & 108 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "jira.js",
3-
"version": "2.15.7",
3+
"version": "2.15.8",
44
"description": "jira.js is a powerful Node.JS/Browser module that allows you to interact with the Jira API very easily",
55
"main": "out/index.js",
66
"types": "out/index.d.ts",
@@ -53,7 +53,7 @@
5353
"devDependencies": {
5454
"@swc-node/register": "^1.5.1",
5555
"@types/express": "^4.17.13",
56-
"@types/node": "^18.6.3",
56+
"@types/node": "^18.6.4",
5757
"@types/oauth": "^0.9.1",
5858
"@types/sinon": "^10.0.13",
5959
"@typescript-eslint/eslint-plugin": "^5.32.0",

‎src/version2/issueFields.ts

Lines changed: 63 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -90,10 +90,10 @@ export class IssueFields {
9090
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#pagination) list of fields
9191
* for Classic Jira projects. The list can include:
9292
*
93-
* - All fields.
94-
* - Specific fields, by defining `id`.
95-
* - Fields that contain a string in the field name or description, by defining `query`.
96-
* - Specific fields that contain a string in the field name or description, by defining `id` and `query`.
93+
* - All fields
94+
* - Specific fields, by defining `id`
95+
* - Fields that contain a string in the field name or description, by defining `query`
96+
* - Specific fields that contain a string in the field name or description, by defining `id` and `query`
9797
*
9898
* Only custom fields can be queried, `type` must be set to `custom`.
9999
*
@@ -108,10 +108,10 @@ export class IssueFields {
108108
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#pagination) list of fields
109109
* for Classic Jira projects. The list can include:
110110
*
111-
* - All fields.
112-
* - Specific fields, by defining `id`.
113-
* - Fields that contain a string in the field name or description, by defining `query`.
114-
* - Specific fields that contain a string in the field name or description, by defining `id` and `query`.
111+
* - All fields
112+
* - Specific fields, by defining `id`
113+
* - Fields that contain a string in the field name or description, by defining `query`
114+
* - Specific fields that contain a string in the field name or description, by defining `id` and `query`
115115
*
116116
* Only custom fields can be queried, `type` must be set to `custom`.
117117
*
@@ -143,6 +143,51 @@ export class IssueFields {
143143
return this.client.sendRequest(config, callback);
144144
}
145145

146+
/**
147+
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#pagination) list of fields
148+
* in the trash. The list may be restricted to fields whose field name or description partially match a string.
149+
*
150+
* Only custom fields can be queried, `type` must be set to `custom`.
151+
*
152+
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
153+
* _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
154+
*/
155+
async getTrashedFieldsPaginated<T = Models.PageField>(
156+
parameters: Parameters.GetTrashedFieldsPaginated | undefined,
157+
callback: Callback<T>
158+
): Promise<void>;
159+
/**
160+
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#pagination) list of fields
161+
* in the trash. The list may be restricted to fields whose field name or description partially match a string.
162+
*
163+
* Only custom fields can be queried, `type` must be set to `custom`.
164+
*
165+
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
166+
* _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
167+
*/
168+
async getTrashedFieldsPaginated<T = Models.PageField>(
169+
parameters?: Parameters.GetTrashedFieldsPaginated,
170+
callback?: never
171+
): Promise<T>;
172+
async getTrashedFieldsPaginated<T = Models.PageField>(
173+
parameters?: Parameters.GetTrashedFieldsPaginated,
174+
callback?: Callback<T>,
175+
): Promise<void | T> {
176+
const config: RequestConfig = {
177+
url: '/rest/api/2/field/search/trashed',
178+
method: 'GET',
179+
params: {
180+
startAt: parameters?.startAt,
181+
maxResults: parameters?.maxResults,
182+
id: parameters?.id,
183+
query: parameters?.query,
184+
orderBy: parameters?.orderBy,
185+
},
186+
};
187+
188+
return this.client.sendRequest(config, callback);
189+
}
190+
146191
/**
147192
* Updates a custom field.
148193
*
@@ -175,22 +220,24 @@ export class IssueFields {
175220
}
176221

177222
/**
178-
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#pagination) list of the
179-
* contexts a field is used in. Deprecated, use [ Get custom field contexts](#api-rest-api-2-field-fieldId-context-get).
223+
* @deprecated Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#pagination)
224+
* list of the contexts a field is used in. Deprecated, use [ Get custom field
225+
* contexts](#api-rest-api-2-field-fieldId-context-get).
180226
*
181-
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
182-
* _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
227+
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
228+
* _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
183229
*/
184230
async getContextsForFieldDeprecated<T = Models.PageContext>(
185231
parameters: Parameters.GetContextsForFieldDeprecated,
186232
callback: Callback<T>
187233
): Promise<void>;
188234
/**
189-
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#pagination) list of the
190-
* contexts a field is used in. Deprecated, use [ Get custom field contexts](#api-rest-api-2-field-fieldId-context-get).
235+
* @deprecated Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#pagination)
236+
* list of the contexts a field is used in. Deprecated, use [ Get custom field
237+
* contexts](#api-rest-api-2-field-fieldId-context-get).
191238
*
192-
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
193-
* _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
239+
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
240+
* _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
194241
*/
195242
async getContextsForFieldDeprecated<T = Models.PageContext>(
196243
parameters: Parameters.GetContextsForFieldDeprecated,

‎src/version2/jiraSettings.ts

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -215,19 +215,17 @@ export class JiraSettings {
215215
* optional features (for example, subtasks, time tracking, and others) are enabled. If time tracking is enabled, this
216216
* operation also returns the time tracking configuration.
217217
*
218-
* This operation can be accessed anonymously.
219-
*
220-
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None.
218+
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
219+
* Permission to access Jira.
221220
*/
222221
async getConfiguration<T = Models.Configuration>(callback: Callback<T>): Promise<void>;
223222
/**
224223
* Returns the [global settings](https://confluence.atlassian.com/x/qYXKM) in Jira. These settings determine whether
225224
* optional features (for example, subtasks, time tracking, and others) are enabled. If time tracking is enabled, this
226225
* operation also returns the time tracking configuration.
227226
*
228-
* This operation can be accessed anonymously.
229-
*
230-
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:** None.
227+
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
228+
* Permission to access Jira.
231229
*/
232230
async getConfiguration<T = Models.Configuration>(callback?: never): Promise<T>;
233231
async getConfiguration<T = Models.Configuration>(callback?: Callback<T>): Promise<void | T> {

‎src/version2/models/updateUiModificationDetails.ts

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,6 @@ export interface UpdateUiModificationDetails {
88
description?: string;
99
/** The data of the UI modification. The maximum size of the data is 50000 characters. */
1010
data?: string;
11-
/**
12-
* List of contexts of the UI modification. The maximum number of contexts is 1000. If provided, replaces all
13-
* existing contexts.
14-
*/
11+
/** List of contexts of the UI modification. The maximum number of contexts is 1000. If provided, replaces all existing contexts. */
1512
contexts?: UiModificationContextDetails[];
1613
}

‎src/version2/parameters/getTrashedFieldsPaginated.ts

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
export interface GetTrashedFieldsPaginated {
2+
/** The index of the first item to return in a page of results (page offset). */
3+
startAt?: number;
4+
/** The maximum number of items to return per page. */
5+
maxResults?: number;
6+
id?: string[];
7+
/** String used to perform a case-insensitive partial match with field names or descriptions. */
8+
query?: string;
9+
/**
10+
* [Order](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#ordering) the results by a field:
11+
*
12+
* - `name` sorts by the field name
13+
* - `trashDate` sorts by the date the field was moved to the trash
14+
* - `plannedDeletionDate` sorts by the planned deletion date
15+
*/
16+
orderBy?:
17+
| 'name'
18+
| 'trashDate'
19+
| 'plannedDeletionDate'
20+
| '+name'
21+
| '+trashDate'
22+
| '+plannedDeletionDate'
23+
| '-name'
24+
| '-trashDate'
25+
| '-plannedDeletionDate'
26+
| string;
27+
}

‎src/version2/parameters/index.ts

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -294,6 +294,7 @@ export * from './getStatusCategory';
294294
export * from './getStatusesById';
295295
export * from './getTask';
296296
export * from './getTransitions';
297+
export * from './getTrashedFieldsPaginated';
297298
export * from './getUiModifications';
298299
export * from './getUser';
299300
export * from './getUserDefaultColumns';

‎src/version2/parameters/search.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,6 @@ export interface Search {
1414
maxResults?: number;
1515
/** Term to match status names against or null to search for all statuses in the search scope. */
1616
searchString?: string;
17+
/** Category of the status to filter by. The supported values are: `TODO`, `IN_PROGRESS`, and `DONE`. */
18+
statusCategory?: 'TODO' | 'IN_PROGRESS' | 'DONE' | string;
1719
}

‎src/version2/status.ts

Lines changed: 1 addition & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,7 @@ export class Status {
1313
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
1414
*
1515
* - _Administer projects_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
16-
* - _Browse projects_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
1716
* - _Administer Jira_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
18-
* - If set up, _View (read-only) workflow_ [project permission](https://confluence.atlassian.com/x/yodKLg) for any
19-
* workflows the statuses are used on.
2017
*/
2118
async getStatusesById<T = Models.JiraStatus[]>(
2219
parameters: Parameters.GetStatusesById | undefined,
@@ -28,10 +25,7 @@ export class Status {
2825
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
2926
*
3027
* - _Administer projects_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
31-
* - _Browse projects_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
3228
* - _Administer Jira_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
33-
* - If set up, _View (read-only) workflow_ [project permission](https://confluence.atlassian.com/x/yodKLg) for any
34-
* workflows the statuses are used on.
3529
*/
3630
async getStatusesById<T = Models.JiraStatus[]>(parameters?: Parameters.GetStatusesById, callback?: never): Promise<T>;
3731
async getStatusesById<T = Models.JiraStatus[]>(
@@ -163,10 +157,7 @@ export class Status {
163157
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
164158
*
165159
* - _Administer projects_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
166-
* - _Browse projects_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
167160
* - _Administer Jira_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
168-
* - If set up, _View (read-only) workflow_ [project permission](https://confluence.atlassian.com/x/yodKLg) for any
169-
* workflows the statuses are used on.
170161
*/
171162
async search<T = Models.PageOfStatuses>(
172163
parameters: Parameters.Search | undefined,
@@ -179,10 +170,7 @@ export class Status {
179170
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v2/intro/#permissions) required:**
180171
*
181172
* - _Administer projects_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
182-
* - _Browse projects_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
183173
* - _Administer Jira_ [project permission.](https://confluence.atlassian.com/x/yodKLg)
184-
* - If set up, _View (read-only) workflow_ [project permission](https://confluence.atlassian.com/x/yodKLg) for any
185-
* workflows the statuses are used on.
186174
*/
187175
async search<T = Models.PageOfStatuses>(parameters?: Parameters.Search, callback?: never): Promise<T>;
188176
async search<T = Models.PageOfStatuses>(parameters?: Parameters.Search, callback?: Callback<T>): Promise<void | T> {
@@ -195,6 +183,7 @@ export class Status {
195183
startAt: parameters?.startAt,
196184
maxResults: parameters?.maxResults,
197185
searchString: parameters?.searchString,
186+
statusCategory: parameters?.statusCategory,
198187
},
199188
};
200189

‎src/version2/userSearch.ts

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -305,10 +305,9 @@ export class UserSearch {
305305
/**
306306
* Returns a list of users that match the search string and property.
307307
*
308-
* This operation takes the users in the range defined by `startAt` and `maxResults`, up to the thousandth user, and
309-
* then returns only the users from that range that match the search string and property. This means the operation
310-
* usually returns fewer users than specified in `maxResults`. To get all the users who match the search string and
311-
* property, use [Get all users](#api-rest-api-2-users-search-get) and filter the records in your code.
308+
* This operation first applies a filter to match the search string and property, and then takes the filtered users in
309+
* the range defined by `startAt` and `maxResults`, up to the thousandth user. To get all the users who match the
310+
* search string and property, use [Get all users](#api-rest-api-2-users-search-get) and filter the records in your code.
312311
*
313312
* This operation can be accessed anonymously.
314313
*
@@ -327,10 +326,9 @@ export class UserSearch {
327326
/**
328327
* Returns a list of users that match the search string and property.
329328
*
330-
* This operation takes the users in the range defined by `startAt` and `maxResults`, up to the thousandth user, and
331-
* then returns only the users from that range that match the search string and property. This means the operation
332-
* usually returns fewer users than specified in `maxResults`. To get all the users who match the search string and
333-
* property, use [Get all users](#api-rest-api-2-users-search-get) and filter the records in your code.
329+
* This operation first applies a filter to match the search string and property, and then takes the filtered users in
330+
* the range defined by `startAt` and `maxResults`, up to the thousandth user. To get all the users who match the
331+
* search string and property, use [Get all users](#api-rest-api-2-users-search-get) and filter the records in your code.
334332
*
335333
* This operation can be accessed anonymously.
336334
*

‎src/version3/issueAttachments.ts

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -124,10 +124,7 @@ export class IssueAttachments {
124124
* - If [issue-level security](https://confluence.atlassian.com/x/J4lKLg) is configured, issue-level security permission
125125
* to view the issue.
126126
*/
127-
async getAttachmentThumbnail<T = Buffer>(
128-
parameters: Parameters.GetAttachmentThumbnail,
129-
callback?: never
130-
): Promise<T>;
127+
async getAttachmentThumbnail<T = Buffer>(parameters: Parameters.GetAttachmentThumbnail, callback?: never): Promise<T>;
131128
async getAttachmentThumbnail<T = Buffer>(
132129
parameters: Parameters.GetAttachmentThumbnail,
133130
callback?: Callback<T>,

‎src/version3/issueFields.ts

Lines changed: 53 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -90,10 +90,10 @@ export class IssueFields {
9090
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#pagination) list of fields
9191
* for Classic Jira projects. The list can include:
9292
*
93-
* - All fields.
94-
* - Specific fields, by defining `id`.
95-
* - Fields that contain a string in the field name or description, by defining `query`.
96-
* - Specific fields that contain a string in the field name or description, by defining `id` and `query`.
93+
* - All fields
94+
* - Specific fields, by defining `id`
95+
* - Fields that contain a string in the field name or description, by defining `query`
96+
* - Specific fields that contain a string in the field name or description, by defining `id` and `query`
9797
*
9898
* Only custom fields can be queried, `type` must be set to `custom`.
9999
*
@@ -108,10 +108,10 @@ export class IssueFields {
108108
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#pagination) list of fields
109109
* for Classic Jira projects. The list can include:
110110
*
111-
* - All fields.
112-
* - Specific fields, by defining `id`.
113-
* - Fields that contain a string in the field name or description, by defining `query`.
114-
* - Specific fields that contain a string in the field name or description, by defining `id` and `query`.
111+
* - All fields
112+
* - Specific fields, by defining `id`
113+
* - Fields that contain a string in the field name or description, by defining `query`
114+
* - Specific fields that contain a string in the field name or description, by defining `id` and `query`
115115
*
116116
* Only custom fields can be queried, `type` must be set to `custom`.
117117
*
@@ -143,6 +143,51 @@ export class IssueFields {
143143
return this.client.sendRequest(config, callback);
144144
}
145145

146+
/**
147+
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#pagination) list of fields
148+
* in the trash. The list may be restricted to fields whose field name or description partially match a string.
149+
*
150+
* Only custom fields can be queried, `type` must be set to `custom`.
151+
*
152+
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#permissions) required:**
153+
* _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
154+
*/
155+
async getTrashedFieldsPaginated<T = Models.PageField>(
156+
parameters: Parameters.GetTrashedFieldsPaginated | undefined,
157+
callback: Callback<T>
158+
): Promise<void>;
159+
/**
160+
* Returns a [paginated](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#pagination) list of fields
161+
* in the trash. The list may be restricted to fields whose field name or description partially match a string.
162+
*
163+
* Only custom fields can be queried, `type` must be set to `custom`.
164+
*
165+
* **[Permissions](https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/#permissions) required:**
166+
* _Administer Jira_ [global permission](https://confluence.atlassian.com/x/x4dKLg).
167+
*/
168+
async getTrashedFieldsPaginated<T = Models.PageField>(
169+
parameters?: Parameters.GetTrashedFieldsPaginated,
170+
callback?: never
171+
): Promise<T>;
172+
async getTrashedFieldsPaginated<T = Models.PageField>(
173+
parameters?: Parameters.GetTrashedFieldsPaginated,
174+
callback?: Callback<T>,
175+
): Promise<void | T> {
176+
const config: RequestConfig = {
177+
url: '/rest/api/3/field/search/trashed',
178+
method: 'GET',
179+
params: {
180+
startAt: parameters?.startAt,
181+
maxResults: parameters?.maxResults,
182+
id: parameters?.id,
183+
query: parameters?.query,
184+
orderBy: parameters?.orderBy,
185+
},
186+
};
187+
188+
return this.client.sendRequest(config, callback);
189+
}
190+
146191
/**
147192
* Updates a custom field.
148193
*

0 commit comments

Comments
 (0)