JSPM – confluence.js@1.1.0

Package Exports

confluence.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (confluence.js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

JavaScript / TypeScript library for Node.JS and browsers to easily interact with Atlassian Confluence API

About

confluence.js is a powerful Node.JS / Browser module that allows you to interact with the Confluence API very easily.

Usability, consistency, and performance are key focuses of confluence.js, and it also has nearly 100% coverage of the Confluence API. It receives new Confluence features shortly after they arrive in the API.

Installation
Telemetry information collection agreement
- Customizing telemetry collection data example
- Disabling telemetry collection example
Usage
- Authentication
  - Basic
  - OAuth 2.0
  - JWT
- Your first request and using algorithm
Decreasing Webpack bundle size
Take a look at our other products
License

Installation

Node.js 10.0.0 or newer is required.

Install with the npm:

npm install confluence.js

Install with the yarn:

yarn add confluence.js

Telemetry information collecting agreement

The use of this library may collect, record and transmit data about the operation of the library and related data, as well as potentially personal data, including ip address from which the request is made, user agent from the device from which the request is made, version of the library used, version of the telemetry sending library, name of the invoked method, authorization type information (can be configured), base configuration request usage information, callback information, onResponse middleware usage information, onError middleware usage information, queries usage information, body usage information in request, headers usage information in request, HTTP response code (can be configured), request start date and time and response receipt date and time (can be configured), No check atlassian token flag enabling information.

The type and amount of data may vary with the version of the libraries and can be changed at any time without notice.

Telemetry data collection is enabled by default.

The following tracking parameters can be configured:

Authentication type
Request status code
Request timings

Customizing telemetry collecting data example

import { Config } from 'confluence.js';

const config: Config = {
  host: 'https://your-domain.atlassian.net',
  telemetry: {
    allowedToPassAuthenticationType: false,  // true by default
    allowedToPassRequestStatusCode: true,  // true by default
    allowedToPassRequestTimings: false,  // true by default
  },
};

If you want to disable telemetry, set the telemetry field to false.

Disabling telemetry collection example

import { Config } from 'confluence.js';

const config: Config = {
  host: 'https://your-domain.atlassian.net',
  telemetry: false, // Telemetry will not be collected
};

Usage

Authentication

There are several types of authentication to gain access to the Confluence API. Let's take a look at a few of them below

Basic authentication

Basic authentication allows you to log in with credentials. You can use username and password, but this login method is not supported in the online version, and most standalone versions, so it's better to release API Token, read how to do it here, and use it together with email.

Username and password example:

import { ConfluenceClient } from 'confluence.js';

const client = new ConfluenceClient({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      username: 'YOUR_USERNAME',
      password: 'YOUR_PASSWORD',
    },
  },
});

Email and API Token example:

import { ConfluenceClient } from 'confluence.js';

const client = new ConfluenceClient({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'YOUR@EMAIL.ORG',
      apiToken: 'YOUR_API_TOKEN',
    },
  },
});

OAuth 2.0

Only the authorization token is currently supported. To release it, you need to read the documentation and write your own code to get the token.

Example of usage

import { ConfluenceClient } from 'confluence.js';

const client = new ConfluenceClient({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    oauth2: {
      accessToken: 'YOUR_ACCESS_TOKEN',
    },
  },
});

JWT

import { ConfluenceClient } from 'confluence.js';

const client = new ConfluenceClient({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    jwt: {
      issuer: 'ISSUER',
      secret: 'shhhh',
      expiryTimeSeconds: 180,
    },
  },
});

Your first request and using algorithm

import { ConfluenceClient } from 'confluence.js'; // Or import ServerClient if using standalone (Server) API

const client = new ConfluenceClient({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'YOUR_EMAIL',
      apiToken: 'YOUR_API_TOKEN',
    },
  },
});

async function main() {
  const space = await client.space.createSpace({
    name: 'My new space',
    key: 'SPACENAME',
  });

  console.log(space);
}

main();

// Expected output:
// {
//   id: 558714,
//   key: 'SPACENAME',
//   name: 'My new space',
//   description: {
//     plain: {
//       value: '',
//       representation: 'plain',
//       embeddedContent: []
//     },
//     _expandable: {view: ''}
//   },
//   homepage: {
//     id: '555312',
//     type: 'page',
//     status: 'current',
//     title: 'My new space Home',
//     macroRenderedOutput: {},
//     extensions: {position: 581},
//     _expandable: {
//       container: '/rest/api/space/SPACENAME',
//       metadata: '',
//       restrictions: '/rest/api/content/555312/restriction/byOperation',
//       history: '/rest/api/content/555312/history',
//       body: '',
//       version: '',
//       descendants: '/rest/api/content/555312/descendant',
//       space: '/rest/api/space/SPACENAME',
//       childTypes: '',
//       operations: '',
//       schedulePublishDate: '',
//       children: '/rest/api/content/555312/child',
//       ancestors: ''
//     },
//     _links: {
//       self: 'https://xxx.atlassian.net/wiki/rest/api/content/555312',
//       tinyui: '/x/qIoI',
//       editui: '/pages/resumedraft.action?draftId=555312',
//       webui: '/spaces/SPACENAME/overview'
//     }
//   },
//   type: 'global',
//   permissions: [...],
//   status: 'current',
//   _expandable: {
//     settings: '/rest/api/space/SPACENAME/settings',
//     metadata: '',
//     operations: '',
//     lookAndFeel: '/rest/api/settings/lookandfeel?spaceKey=SPACENAME',
//     identifiers: '',
//     icon: '',
//     theme: '/rest/api/space/SPACENAME/theme',
//     history: ''
//   },
//   _links: {
//     context: '/wiki',
//     self: 'https://xxx.atlassian.net/wiki/rest/api/space/SPACENAME',
//     collection: '/rest/api/space',
//     webui: '/spaces/SPACENAME',
//     base: 'https://xxx.atlassian.net/wiki'
//   }
// }

The algorithm for using the library:

client.<group>.<methodName>(parametersObject);

Available groups:

The name of the methods is the name of the endpoint in the group without spaces and in camelCase.

The parameters depend on the specific endpoint. For more information, see here.

Decreasing Webpack bundle size

If you use Webpack and need to reduce the size of the assembly, you can create your client with only the groups you use.

import { BaseClient } from 'confluence.js';
import { Api } from 'confluence.js';

export class CustomConfluenceClient extends BaseClient {
  content = new Api.Content(this);
  space = new Api.Space(this);
}

Take a look at our other products

Jira.js - A JavaScript / TypeScript wrapper for the JIRA REST API
Trello.js - JavaScript / TypeScript library for Node.JS and browsers to easily interact with Atlassian Trello API

License

Distributed under the MIT License. See LICENSE for more information.

confluence.js