confluence-datacenter-api-client

TypeScript client for Confluence Data Center REST API v1100 (/rest/api/latest). Node.js + browser. Fully typed. Zero runtime deps.

REST reference: https://developer.atlassian.com/server/confluence/rest/v1100/

Install

npm install confluence-datacenter-api-client

Quick Start

import { ConfluenceClient } from 'confluence-datacenter-api-client';

const confluence = new ConfluenceClient({
  apiUrl: 'https://confluence.example.com',
  user: 'your-username',
  token: 'your-personal-access-token',
});

const pages = await confluence.contents({ type: 'page', spaceKey: 'DOC', limit: 25 });
const space = await confluence.space('DOC');
const results = await confluence.search.cql({ cql: 'type=page and space=DOC' });
const user = await confluence.userByUsername('jsmith');
const activity = await confluence.userActivity('jsmith', { since: 'now("-30d")' });
const versions = await confluence.contentVersions('123', { expand: 'content' });
const labels = await confluence.contentLabels('123');
const owner = await confluence.contentProperty<{ team: string }>('123', 'owner');

Auth

const basic = new ConfluenceClient({
  apiUrl: 'https://confluence.example.com',
  user: 'user',
  token: 'password-or-pat',
});

const bearer = new ConfluenceClient({
  apiUrl: 'https://confluence.example.com',
  token: 'http-access-token',
  authType: 'bearer',
});

Content

const page = await confluence.contentById('123', { expand: 'body.storage,version' });

const created = await confluence.createContent({
  type: 'page',
  title: 'API Docs',
  space: { key: 'DOC' },
  body: {
    storage: {
      value: '<p>Hello Confluence</p>',
      representation: 'storage',
    },
  },
});

await confluence.updateContent(created.id, {
  type: 'page',
  title: 'API Docs',
  space: { key: 'DOC' },
  version: { number: 2, message: 'Update body' },
  body: {
    storage: {
      value: '<p>Updated</p>',
      representation: 'storage',
    },
  },
});

Content Versions

const versions = await confluence.contentVersions('123', {
  expand: 'content',
  limit: 25,
});

const version = await confluence.contentVersion('123', 2, {
  expand: 'content',
});

Content Labels

const labels = await confluence.contentLabels('123', {
  prefix: 'global',
  limit: 25,
});

await confluence.addContentLabels('123', [
  { prefix: 'global', name: 'team-docs' },
]);

await confluence.removeContentLabel('123', 'team-docs', 'global');

Content Properties

const properties = await confluence.contentProperties('123', {
  expand: 'version',
});

const owner = await confluence.contentProperty<{ team: string }>('123', 'owner');

await confluence.createContentProperty('123', {
  key: 'owner',
  value: { team: 'platform' },
});

await confluence.updateContentProperty('123', 'owner', {
  value: { team: 'platform' },
  version: { number: 2 },
});

User Activity

Use same user slug/username used in Atlassian Data Center.

const user = await confluence.userByUsername('jsmith');

const activity = await confluence.userActivity('jsmith', {
  since: 'now("-30d")',
  contentType: 'page',
  spaceKey: 'DOC',
  expand: 'content.version,content.space',
  limit: 50,
});

Generated CQL:

contributor = "jsmith" and lastmodified >= now("-30d") and type = page and space = DOC order by lastmodified desc

Users

const current = await confluence.currentUser();
const user = await confluence.userByUsername('jsmith');
const sameUser = await confluence.user({ username: 'jsmith', expand: 'operations' });

Pagination

import { paginate } from 'confluence-datacenter-api-client';

for await (const page of paginate((params) => confluence.contents({ ...params, type: 'page' }))) {
  console.log(page.title);
}

Scripts

npm test
npm run test:coverage
npm run test:contract
npm run build
npm run llms:generate
npm run docs
npm run check
npm run quality

Quality Gates

npm run quality

Runs lint, format check, coverage thresholds, build, and llms.txt generation.

Contract tests are opt-in because they need a live Confluence Data Center instance:

CONFLUENCE_BASE_URL=https://confluence.example.com \
CONFLUENCE_USER=user \
CONFLUENCE_TOKEN=token \
npm run test:contract

Bearer token:

CONFLUENCE_BASE_URL=https://confluence.example.com \
CONFLUENCE_AUTH_TYPE=bearer \
CONFLUENCE_TOKEN=token \
npm run test:contract

Release

Publishing follows base project: GitHub Actions + semantic-release + npm provenance.

Required secret: NPM_TOKEN.