New experimental endpoints

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+### 1.2.2
+
+- JSDOC improvements
+- New experimental endpoints
+- Small improvements
+
 ### 1.2.1
 
 - Vulnerabilities fixes.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence.js",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "confluence.js is a powerful Node.JS/Browser module that allows you to interact with the Confluence API very easily",
   "author": "Vladislav Tupikin <mrrefactoring@yandex.ru>",
   "license": "MIT",
@@ -34,25 +34,25 @@
   ],
   "devDependencies": {
     "@types/express": "^4.17.13",
-    "@types/jest": "^27.0.2",
+    "@types/jest": "^27.0.3",
     "@types/oauth": "^0.9.1",
     "@types/sinon": "^10.0.6",
-    "@typescript-eslint/eslint-plugin": "^5.2.0",
-    "@typescript-eslint/parser": "^5.2.0",
+    "@typescript-eslint/eslint-plugin": "^5.4.0",
+    "@typescript-eslint/parser": "^5.4.0",
     "dotenv": "^10.0.0",
-    "eslint": "^8.1.0",
-    "eslint-config-airbnb": "^18.2.1",
-    "eslint-config-airbnb-typescript": "^14.0.1",
+    "eslint": "^8.2.0",
+    "eslint-config-airbnb": "^19.0.0",
+    "eslint-config-airbnb-typescript": "^16.0.0",
     "eslint-import-resolver-typescript": "^2.5.0",
-    "eslint-plugin-import": "^2.25.2",
+    "eslint-plugin-import": "^2.25.3",
     "jest": "^27.3.1",
     "prettier": "^2.4.1",
-    "prettier-plugin-jsdoc": "^0.3.24",
-    "sinon": "^11.1.2",
+    "prettier-plugin-jsdoc": "^0.3.30",
+    "sinon": "^12.0.1",
     "ts-jest": "^27.0.7",
-    "typedoc": "^0.22.7",
+    "typedoc": "^0.22.9",
     "typedoc-plugin-extras": "^2.2.1",
-    "typescript": "^4.4.4"
+    "typescript": "^4.5.2"
   },
   "dependencies": {
     "atlassian-jwt": "^2.0.2",

src/api/contentProperties.ts

@@ -126,6 +126,7 @@ export class ContentProperties {
       method: 'GET',
       params: {
         expand: parameters.expand,
+        status: parameters.status,
       },
     };
 

src/api/experimental.ts

@@ -7,6 +7,99 @@ import { RequestConfig } from '../requestConfig';
 export class Experimental {
   constructor(private client: Client) {}
 
+  /**
+   * Returns a list of labels associated with a space. Can provide a prefix as well as other filters to select different
+   * types of labels.
+   */
+  async getLabelsForSpace<T = Models.LabelArray>(
+    parameters: Parameters.GetLabelsForSpace,
+    callback: Callback<T>
+  ): Promise<void>;
+  /**
+   * Returns a list of labels associated with a space. Can provide a prefix as well as other filters to select different
+   * types of labels.
+   */
+  async getLabelsForSpace<T = Models.LabelArray>(
+    parameters: Parameters.GetLabelsForSpace,
+    callback?: never
+  ): Promise<T>;
+  async getLabelsForSpace<T = Models.LabelArray>(
+    parameters: Parameters.GetLabelsForSpace,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: `/api/space/${parameters.spaceKey}/label`,
+      method: 'GET',
+      params: {
+        prefix: parameters.prefix,
+        start: parameters.start,
+        limit: parameters.limit,
+      },
+    };
+
+    return this.client.sendRequest(config, callback, { methodName: 'getLabelsForSpace' });
+  }
+
+  /**
+   * Adds labels to a piece of content. Does not modify the existing labels.
+   *
+   * Notes:
+   *
+   * - Labels can also be added when creating content ([Create content](#api-content-post)).
+   * - Labels can be updated when updating content ([Update content](#api-content-id-put)). This will delete the existing
+   *   labels and replace them with the labels in the request.
+   *
+   * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to update the content.
+   */
+  async addLabelsToSpace<T = Models.LabelArray>(
+    parameters: Parameters.AddLabelsToSpace,
+    callback: Callback<T>
+  ): Promise<void>;
+  /**
+   * Adds labels to a piece of content. Does not modify the existing labels.
+   *
+   * Notes:
+   *
+   * - Labels can also be added when creating content ([Create content](#api-content-post)).
+   * - Labels can be updated when updating content ([Update content](#api-content-id-put)). This will delete the existing
+   *   labels and replace them with the labels in the request.
+   *
+   * **[Permissions](https://confluence.atlassian.com/x/_AozKw) required**: Permission to update the content.
+   */
+  async addLabelsToSpace<T = Models.LabelArray>(parameters: Parameters.AddLabelsToSpace, callback?: never): Promise<T>;
+  async addLabelsToSpace<T = Models.LabelArray>(
+    parameters: Parameters.AddLabelsToSpace,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: `/api/space/${parameters.spaceKey}/label`,
+      method: 'POST',
+    };
+
+    return this.client.sendRequest(config, callback, { methodName: 'addLabelsToSpace' });
+  }
+
+  async deleteLabelFromSpace<T = void>(
+    parameters: Parameters.DeleteLabelFromSpace,
+    callback: Callback<T>
+  ): Promise<void>;
+  async deleteLabelFromSpace<T = void>(parameters: Parameters.DeleteLabelFromSpace, callback?: never): Promise<T>;
+  async deleteLabelFromSpace<T = void>(
+    parameters: Parameters.DeleteLabelFromSpace,
+    callback?: Callback<T>,
+  ): Promise<void | T> {
+    const config: RequestConfig = {
+      url: `/api/space/${parameters.spaceKey}/label`,
+      method: 'DELETE',
+      params: {
+        name: parameters.name,
+        prefix: parameters.prefix,
+      },
+    };
+
+    return this.client.sendRequest(config, callback, { methodName: 'deleteLabelFromSpace' });
+  }
+
   /** Get the total number of views a piece of content has. */
   async getViews<T = Models.GetViews>(parameters: Parameters.GetViews, callback: Callback<T>): Promise<void>;
   /** Get the total number of views a piece of content has. */

src/api/parameters/addLabelsToSpace.ts

@@ -0,0 +1,4 @@
+export interface AddLabelsToSpace {
+  /** The key of the space to add labels to. */
+  spaceKey: string;
+}

src/api/parameters/deleteLabelFromSpace.ts

@@ -0,0 +1,8 @@
+export interface DeleteLabelFromSpace {
+  /** The key of the space to remove a labels from. */
+  spaceKey: string;
+  /** The name of the label to remove */
+  name: string;
+  /** The prefix of the label to remove. If not provided defaults to global. */
+  prefix?: string;
+}

src/api/parameters/getBulkUserLookup.ts

@@ -5,12 +5,6 @@ export interface GetBulkUserLookup {
    * A multi-value parameter indicating which properties of the user to expand.
    *
    * - `operations` returns the operations that the user is allowed to do.
-   * - `details.personal` returns the 'Personal' details in the user's profile, like the 'Email' and 'Phone'. Note that
-   *   these fields have been deprecated due to privacy changes. See the [migration
-   *   guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/) for details.
-   * - `details.business` returns the 'Company' details in the user's profile, like the 'Position' and 'Department'. Note
-   *   that these fields have been deprecated due to privacy changes. See the [migration
-   *   guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/) for details.
    * - PersonalSpace returns the user's personal space, if it exists.
    */
   expand?: string[];

src/api/parameters/getContentById.ts

@@ -19,10 +19,95 @@ export interface GetContentById {
    */
   embeddedContentRender?: string;
   /** A multi-value parameter indicating which properties of the content to expand. */
-  expand?: string[];
+  expand?: string | string[] | GetContentById.Expand | GetContentById.Expand[];
   /**
    * If set to `viewed`, the request will trigger a 'viewed' event for the content. When this event is triggered, the
    * page/blogpost will appear on the 'Recently visited' tab of the user's Confluence dashboard.
    */
   trigger?: string;
 }
+
+export namespace GetContentById {
+  export enum Expand {
+    /**
+     * Returns whether the content has attachments, comments, or child pages. Use this if you only need to check whether
+     * the content has children of a particular type.
+     */
+    AllChildTypes = 'childTypes.all',
+    /** Returns whether the content has attachments. */
+    AttachmentChildType = 'childTypes.attachment',
+    /** Returns whether the content has comments. */
+    CommentChildType = 'childTypes.comment',
+    /** Returns whether the content has child pages. */
+    PageChildType = 'childTypes.page',
+    /**
+     * Returns the space that the content is in. This is the same as the information returned by [Get
+     * space](https://developer.atlassian.com/cloud/confluence/rest/api-group-content---attachments/).
+     */
+    Container = 'container',
+    /**
+     * Returns information about the current user in relation to the content, including when they last viewed it,
+     * modified it, contributed to it, or added it as a favorite.
+     */
+    CurrentUserMetadata = 'metadata.currentuser',
+    /** Returns content properties that have been set via the Confluence REST API. */
+    PropertiesMetadata = 'metadata.properties',
+    /** Returns the labels that have been added to the content. */
+    LabelsMetadata = 'metadata.labels',
+    /** This property is only used by Atlassian. */
+    FrontendMetadata = 'metadata.frontend',
+    /** Returns the operations for the content, which are used when setting permissions. */
+    Operations = 'operations',
+    /** Returns pages that are descendants at the level immediately below the content. */
+    PageChildren = 'children.page',
+    /** Returns all attachments for the content. */
+    AttachmentChildren = 'children.attachment',
+    /** Returns all comments on the content. */
+    CommentChildren = 'children.comment',
+    /** Returns the users that have permission to read the content. */
+    ReadUserRestriction = 'restrictions.read.restrictions.user',
+    /**
+     * Returns the groups that have permission to read the content. Note that this may return deleted groups, because
+     * deleting a group doesn't remove associated restrictions.
+     */
+    ReadGroupRestriction = 'restrictions.read.restrictions.group',
+    /** Returns the users that have permission to update the content. */
+    UpdateUserRestriction = 'restrictions.update.restrictions.user',
+    /**
+     * Returns the groups that have permission to update the content. Note that this may return deleted groups because
+     * deleting a group doesn't remove associated restrictions.
+     */
+    UpdateGroupRestriction = 'restrictions.update.restrictions.group',
+    /** Returns the history of the content, including the date it was created. */
+    History = 'history',
+    /** Returns information about the most recent update of the content, including who updated it and when it was updated. */
+    LastUpdated = 'history.lastUpdated',
+    /** Returns information about the update prior to the current content update. */
+    PreviousVersion = 'history.previousVersion',
+    /** Returns all of the users who have contributed to the content. */
+    Contributors = 'history.contributors',
+    /** Returns information about the update after to the current content update. */
+    NextVersion = 'history.nextVersion',
+    /** Returns the parent page, if the content is a page. */
+    Ancestors = 'ancestors',
+    /** Returns the body of the content in different formats, including the editor format, view format, and export format. */
+    Body = 'body',
+    /** Returns information about the most recent update of the content, including who updated it and when it was updated. */
+    Version = 'version',
+    /** Returns pages that are descendants at any level below the content. */
+    PageDescendant = 'descendants.page',
+    /** Returns all attachments for the content, same as `children.attachment`. */
+    AttachmentDescendant = 'descendants.attachment',
+    /** Returns all comments on the content, same as `children.comment`. */
+    CommentDescendant = 'descendants.comment',
+    /**
+     * Returns the space that the content is in. This is the same as the information returned by [Get
+     * space](https://developer.atlassian.com/cloud/confluence/rest/api-group-content---attachments/).
+     */
+    Space = 'space',
+    /** Returns inline comment-specific properties. */
+    InlineProperties = 'extensions.inlineProperties',
+    /** Returns the resolution status of each comment. */
+    Resolution = 'extensions.resolution',
+  }
+}

src/api/parameters/getContentChildren.ts

@@ -7,6 +7,7 @@ export interface GetContentChildren {
    * - `attachment` returns all attachments for the content.
    * - `comments` returns all comments for the content.
    * - `page` returns all child pages of the content.
+   * - Custom content types that are provided by apps are also supported.
    */
   expand?: string[];
   /** The version of the parent content to retrieve children for. Currently, this only works for the latest version. */

src/api/parameters/getContentProperties.ts

@@ -1,7 +1,7 @@
 export interface GetContentProperties {
   /** The ID of the content to be queried for its properties. */
   id: string;
-  /**The key of the content property.*/
+  /** The key of the content property. */
   key?: string[];
   /**
    * A multi-value parameter indicating which properties of the content to expand. By default, the `version` object is expanded.

src/api/parameters/getContentProperty.ts

@@ -10,4 +10,16 @@ export interface GetContentProperty {
    * - `version` returns information about the version of the property, such as the version number, when it was created, etc.
    */
   expand?: string[];
+  /**
+   * Filter the results to a set of content based on their status. If set to `any`, content with any status is returned.
+   * By default it will fetch current and archived statuses `?status=current&status=archived`. All supported statuses
+   *
+   * - any
+   * - archived
+   * - current
+   * - deleted
+   * - draft
+   * - trashed
+   */
+  status?: string[];
 }

src/api/parameters/getContentVersions.ts

@@ -6,7 +6,7 @@ export interface GetContentVersions {
   /** The maximum number of versions to return per page. Note, this may be restricted by fixed system limits. */
   limit?: number;
   /**
-   * A multi-value parameter indicating which properties of the content to expand.
+   * A multi-value parameter indicating which properties of the content to expand. By default, the `content` object is expanded.
    *
    * - `collaborators` returns the users that collaborated on the version.
    * - `content` returns the content for the version.

src/api/parameters/getCurrentUser.ts

@@ -3,13 +3,8 @@ export interface GetCurrentUser {
    * A multi-value parameter indicating which properties of the user to expand.
    *
    * - `operations` returns the operations that the user is allowed to do.
-   * - `details.personal` returns the 'Personal' details in the user's profile, like the 'Email' and 'Phone'. Note that
-   *   these fields have been deprecated due to privacy changes. See the [migration
-   *   guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/) for details.
-   * - `details.business` returns the 'Company' details in the user's profile, like the 'Position' and 'Department'. Note
-   *   that these fields have been deprecated due to privacy changes. See the [migration
-   *   guide](https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/) for details.
    * - PersonalSpace returns the user's personal space, if it exists.
+   * - `isExternalCollaborator` returns whether the user is an external collaborator user
    */
   expand?: string[];
 }

src/api/parameters/getHistoryForContent.ts

@@ -2,7 +2,7 @@ export interface GetHistoryForContent {
   /** The ID of the content to be queried for its history. */
   id: string;
   /**
-   * A multi-value parameter indicating which properties of the content history to expand.
+   * A multi-value parameter indicating which properties of the content history to expand. Maximum sub-expansions allowed is `8`.
    *
    * - `lastUpdated` returns information about the most recent update of the content, including who updated it and when it
    *   was updated.

src/api/parameters/getLabelsForSpace.ts

@@ -0,0 +1,18 @@
+export interface GetLabelsForSpace {
+  /** The key of the space to get labels for. */
+  spaceKey: string;
+  /**
+   * Filters the results to labels with the specified prefix. If this parameter is not specified, then labels with any
+   * prefix will be returned.
+   *
+   *     - `global` prefix is used by labels that are on content within the provided space.
+   *     - `my` prefix can be explicitly added by a user when adding a label
+   *     via the UI, e.g. 'my:example-label'.
+   *     - `team` prefix is used for labels applied to the space.
+   */
+  prefix?: string;
+  /** The starting index of the returned labels. */
+  start?: number;
+  /** The maximum number of labels to return per page. Note, this may be restricted by fixed system limits. */
+  limit?: number;
+}

src/api/parameters/index.ts

@@ -3,6 +3,7 @@ export * from './addCustomContentPermissions';
 export * from './addGroupToContentRestriction';
 export * from './addGroupToContentRestrictionByGroupId';
 export * from './addLabelsToContent';
+export * from './addLabelsToSpace';
 export * from './addLabelWatcher';
 export * from './addPermission';
 export * from './addPermissionToSpace';
@@ -33,6 +34,7 @@ export * from './delete';
 export * from './deleteContent';
 export * from './deleteContentProperty';
 export * from './deleteContentVersion';
+export * from './deleteLabelFromSpace';
 export * from './deleteRelationship';
 export * from './deleteRestrictions';
 export * from './deleteSpace';
@@ -81,6 +83,7 @@ export * from './getGroupsSearch';
 export * from './getHistoryForContent';
 export * from './getIndividualGroupRestrictionStatusByGroupId';
 export * from './getLabelsForContent';
+export * from './getLabelsForSpace';
 export * from './getLookAndFeelSettings';
 export * from './getMacroBodyByMacroId';
 export * from './getMembersByQueryParam';