Confluence.js - Cloud and Server API library

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.

Table of contents

• Installation
• Usage
  • Authentication
    • Basic
    • OAuth 2.0
    • JWT
  • Your first request and using algorithm
  • apiPrefix config parameter
• Decreasing Webpack bundle size
• Take a look at our other products
• License

Installation

Node.js 20.0.0 or newer is required.

Install with the npm:

npm install confluence.js
Copy

Install with the yarn:

yarn add confluence.js
Copy

Install with the pnpm

pnpm add confluence.js
Copy

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

// TODO refine Basic authentication allows you to log in with credentials. How to release API Token, read how to do it here, and use it together with email.

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',
    },
  },
});
Copy

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',
    },
  },
});
Copy

JWT

import { ConfluenceClient } from 'confluence.js';

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

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'
//   }
// }
Copy

The algorithm for using the library:

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

Available groups:

• analytics
• audit
• content
• contentAttachments
• contentBody
• contentChildrenAndDescendants
• contentComments
• contentLabels
• contentMacroBody
• contentPermissions
• contentProperties
• contentRestrictions
• contentStates
• contentVersions
• contentWatches
• dynamicModules
• experimental
• group
• inlineTasks
• labelInfo
• longRunningTask
• relation
• search
• settings
• space
• spacePermissions
• spaceProperties
• spaceSettings
• template
• themes
• users

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.

apiPrefix config parameter

The apiPrefix parameter is used to specify the prefix for the API. For example, if you use the custom domain https://mydomain.atlassian.net/api for API.

Example of use:

import { ConfluenceClient } from 'confluence.js';

const client = new ConfluenceClient({
  host: 'https://your-domain.atlassian.net',
  apiPrefix: '/api',
});
Copy

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 { Content } from 'confluence.js/api/content';
import { Space } from 'confluence.js/api/space';

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

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.