- 
+ 
- JavaScript/TypeScript library for Node.js and browsers to interact with Atlassian Confluence API
+ Type-safe Confluence REST API client for Node.js and browsers
+
+
## About
-Confluence.js is a powerful Node.js and browser-compatible module that provides seamless interaction with:
-- [Confluence Cloud REST API](https://developer.atlassian.com/cloud/confluence/rest/)
+`confluence.js` covers both Confluence Cloud REST APIs from one package:
+
+- **[Cloud REST API v2](https://developer.atlassian.com/cloud/confluence/rest/v2/)** — 30 namespaces, 218 methods
+- **[Cloud REST API v1](https://developer.atlassian.com/cloud/confluence/rest/v1/)** — 28 namespaces, 130 methods
+
+Both are first-class. Atlassian has not deprecated v1, and the two cover
+different ground: v1 still owns what v2 has no equivalent for, and v2 owns
+everything Atlassian has moved forward.
+
+Every response is validated at runtime against a [Zod 4](https://zod.dev) schema
+derived from Atlassian's OpenAPI spec, so API drift surfaces as a `ZodError`
+rather than as `undefined` three call frames later.
-Designed for developer experience and performance, it offers full API coverage and stays updated with new Confluence features.
+- ESM-only, Node ≥ 22, no polyfills — the transport is the built-in `fetch`
+- Tree-shakable: only the endpoints you import reach your bundle
+- One runtime dependency: `zod`
## Table of Contents
- [Getting Started](#getting-started)
- - [Installation](#installation)
- - [Quick Example](#quick-example)
-- [Documentation](#documentation)
-- [Usage](#usage)
- - [Authentication](#authentication)
- - [Basic Auth](#basic-authentication)
- - [OAuth 2.0](#oauth-20)
- - [JWT](#jwt)
- - [First Request](#first-request)
- - [API Structure](#api-structure)
- - [Custom API Prefix](#custom-api-prefix)
-- [Tree Shaking](#tree-shaking)
+- [Authentication](#authentication)
+- [Two ways to use it](#two-ways-to-use-it)
+- [Choosing between v1 and v2](#choosing-between-v1-and-v2)
+- [Error handling](#error-handling)
+- [Retries](#retries)
+- [Migrating from 2.x](#migrating-from-2x)
- [Other Products](#other-products)
- [License](#license)
## Getting Started
-### Installation
-
-**Requires Node.js 20.0.0 or newer**
-
```bash
-# npm
npm install confluence.js
-
-# yarn
-yarn add confluence.js
-
-# pnpm
-pnpm add confluence.js
```
-### Quick Example
-
-Create a Confluence space in 3 steps:
-
```typescript
-import { ConfluenceClient } from 'confluence.js';
+import { createV2Client } from 'confluence.js';
-const client = new ConfluenceClient({
+const confluence = createV2Client({
host: 'https://your-domain.atlassian.net',
- authentication: {
- basic: {
- email: 'your@email.com',
- apiToken: 'YOUR_API_TOKEN', // Create one: https://id.atlassian.com/manage-profile/security/api-tokens
- },
+ auth: {
+ type: 'basic',
+ email: 'YOUR@EMAIL.ORG',
+ apiToken: 'YOUR_API_TOKEN',
},
});
-async function createSpace() {
- const space = await client.space.createSpace({
- name: 'Project Galaxy',
- key: 'GALAXY',
- });
- console.log(`Space created: ${space.key}`);
-}
+const page = await confluence.page.createPage({
+ spaceId: '123456',
+ title: 'Project Overview',
+ body: {
+ representation: 'storage',
+ value: '
+
- JavaScript/TypeScript library for Node.js and browsers to interact with Atlassian Confluence API
+ Type-safe Confluence REST API client for Node.js and browsers
+
+
Welcome to our project documentation
', + }, +}); -createSpace(); +console.log(`Page created: ${page.title}`); ``` -## Documentation - -Full API reference and guides available at: -[https://mrrefactoring.github.io/confluence.js/](https://mrrefactoring.github.io/confluence.js/) - -## Usage +`host` is your bare site URL. The API path (`/wiki/api/v2`, `/wiki/rest/api`) +belongs to the request, not to `host` — so one host serves both versions. -### Authentication +## Authentication -#### Basic Authentication +### Basic -1. Create an API token: [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens) -2. Configure the client: +Create an API token in +[Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens): ```typescript -const client = new ConfluenceClient({ +const confluence = createV2Client({ host: 'https://your-domain.atlassian.net', - authentication: { - basic: { - email: 'YOUR@EMAIL.ORG', - apiToken: 'YOUR_API_TOKEN', - }, - }, + auth: { type: 'basic', email: 'YOUR@EMAIL.ORG', apiToken: 'YOUR_API_TOKEN' }, }); ``` -#### OAuth 2.0 +### OAuth 2.0 (3LO) -Implement OAuth 2.0 flow using Atlassian's [documentation](https://developer.atlassian.com/cloud/confluence/oauth-2-3lo-apps/): +Hand over your app credentials and a refresh token. The client refreshes before +expiry, retries once on a 401, and resolves the cloud id itself: ```typescript -const client = new ConfluenceClient({ - host: 'https://your-domain.atlassian.net', - authentication: { - oauth2: { - accessToken: 'YOUR_ACCESS_TOKEN', - }, +const confluence = createV2Client({ + auth: { + type: 'oauth2', + clientId: 'YOUR_CLIENT_ID', + clientSecret: 'YOUR_CLIENT_SECRET', + refreshToken: 'YOUR_REFRESH_TOKEN', + // Atlassian rotates the refresh token on every refresh — persist the new one. + onTokenRefresh: ({ refreshToken }) => tokenStore.save(refreshToken), }, }); ``` -#### JWT +No `host`: 3LO tokens only work through `api.atlassian.com`, never on your site's +own domain, so the client builds that URL from the cloud id. Pass `cloudId` or +`siteUrl` if the token can reach more than one site. + +`confluence.js` also exports the flow itself — `generateAuthorizationUrl`, +`parseCallbackUrl`, `exchangeAuthorizationCode`, `refreshOAuth2Token` and +`getAccessibleResources`. See the [OAuth 2.0 guide](https://mrrefactoring.github.io/confluence.js/guide/oauth2) +— scopes differ between v1 and v2, and refresh tokens rotate. -For server-to-server integration: +For a bearer token from somewhere other than 3LO, hand over a resolver — called +per request — and a hook to re-derive auth after a 401: ```typescript -const client = new ConfluenceClient({ +const confluence = createV2Client({ host: 'https://your-domain.atlassian.net', - authentication: { - jwt: { - issuer: 'your-client-id', - secret: 'your-secret-key', - expiryTimeSeconds: 180, - }, - }, + auth: { type: 'bearer', getToken: () => tokenStore.current() }, + getAuthOn401: async () => ({ type: 'bearer', token: await refresh() }), }); ``` -### First Request +> **JWT (Atlassian Connect) is not supported in 3.x.** See +> [MIGRATION.md](./MIGRATION.md#jwt-authentication-is-gone). + +## Two ways to use it -Create a page in an existing space: +**A client object** — the whole API behind namespaces: ```typescript -const page = await client.content.createContent({ - title: 'Project Overview', - type: 'page', - space: { key: 'GALAXY' }, - body: { - storage: { - value: 'Welcome to our project documentation
', - representation: 'storage', - }, - }, -}); +import { createV2Client } from 'confluence.js'; -console.log(`Page created: ${page.title}`); -``` +const confluence = createV2Client({ host, auth }); -### API Structure +await confluence.page.getPages({ spaceId: ['123'] }); +await confluence.space.getSpaces({ limit: 25 }); +``` -Access endpoints using `client.
-
-
-### Custom API Prefix
-
-For custom API endpoints:
+One client drives both versions:
```typescript
-const client = new ConfluenceClient({
- host: 'https://custom-domain.com',
- apiPrefix: '/confluence-api', // Default: '/wiki/rest/api'
-});
+import { createClient } from 'confluence.js/core';
+import { getPages } from 'confluence.js/v2';
+import { getGroups } from 'confluence.js/v1';
+
+const client = createClient({ host, auth });
+
+await getPages(client, {}); // → /wiki/api/v2/pages
+await getGroups(client, {}); // → /wiki/rest/api/group
```
-## Tree Shaking
+### Entry points
+
+| Import | What it gives you |
+|---|---|
+| `confluence.js` | `createV1Client`, `createV2Client`, `ApiError`, config types |
+| `confluence.js/v2` | v2 flat functions, parameter and response types |
+| `confluence.js/v1` | v1 flat functions, parameter and response types |
+| `confluence.js/core` | `createClient`, transport types, OAuth helpers |
+
+`confluence.js/v1` and `confluence.js/v2` are not re-exported from the root: the
+two versions collide on a few names (`createSpace`, `getTasks`).
+
+## Choosing between v1 and v2
+
+Reach for **v2** by default — it is where Atlassian is investing. It covers
+pages, blog posts, custom content, whiteboards, databases, folders, comments,
+attachments, labels, tasks, versions, spaces, space permissions and space roles.
+
+Reach for **v1** only for what v2 has no equivalent for: attachment *upload* (v2
+reads attachments but cannot create them), content restrictions, watches,
+permission checks, content states, groups, relations, CQL search, templates,
+themes, settings, user properties, audit records and long-running tasks.
+
+v1 is a complement to v2, not the old API kept alive. This package tracks
+Atlassian's v1 spec as published, and that spec is shrinking: 37 operations that
+2.x exposed — `getContent`, `createContent`, `getSpace` among them — are already
+gone from it, and 33 of those have a v2 equivalent
+([the map](./MIGRATION.md#the-v1-surface-follows-atlassians-current-spec)).
+Expect it to narrow further, and treat a v1 call as something to move to v2 once
+v2 covers it.
+
+## Error handling
-Optimize bundle size by importing only needed modules:
+Every failure is one of this package's own error types — nothing leaks from
+`fetch`. Non-2xx responses throw an `ApiError` subclass carrying the status and
+the parsed body; transport faults throw a `NetworkError`; the OAuth flow throws
+an `OAuthError`.
```typescript
-// custom-client.ts
-import { BaseClient } from 'confluence.js';
-import { Content } from 'confluence.js/api/content';
-import { Space } from 'confluence.js/api/space';
-
-export class CustomClient extends BaseClient {
- content = new Content(this);
- space = new Space(this);
+import { isNotFoundError, isRateLimitError } from 'confluence.js';
+
+try {
+ await confluence.page.getPageById({ id: 42 });
+} catch (error) {
+ if (isNotFoundError(error)) return null;
+ if (isRateLimitError(error)) await sleep(error.retryAfterMs ?? 60_000);
+ throw error;
}
+```
+
+`AuthError` (401), `ForbiddenError` (403), `NotFoundError` (404),
+`RateLimitError` (429) and `ServerError` (5xx) all extend `ApiError`, so
+`instanceof` works — but prefer the `isXxx` predicates: they survive two copies
+of the package in one `node_modules`, where `instanceof` silently returns false.
+
+A response that does not match its schema throws a `ZodError` instead. That
+means Atlassian's API drifted from its own spec, and it is worth
+[an issue](https://github.com/MrRefactoring/confluence.js/issues).
+
+## Retries
-// Usage
-const client = new CustomClient({ /* config */ });
-await client.space.getSpace({ spaceKey: 'GALAXY' });
+Off by default. When enabled, retries cover transport-layer failures only —
+network errors and 502/503/504:
+
+```typescript
+const confluence = createV2Client({
+ host,
+ auth,
+ retry: { maxAttempts: 3, initialDelayMs: 500, backoffFactor: 2 },
+});
+```
+
+4xx is never retried, 429 included: rate limiting is a signal to slow down, not
+a transient fault to paper over.
+
+## Migrating from 2.x
+
+3.0 reworks the public surface — class clients became factories, `authentication`
+became `auth`, callbacks and middlewares are gone, and the v1 surface now follows
+Atlassian's current spec. See **[MIGRATION.md](./MIGRATION.md)** for the full map;
+a codemod handles the mechanical parts:
+
+```bash
+npx jscodeshift -t node_modules/confluence.js/tools/codemod/v2-to-v3.ts src/
```
## Other Products
-Explore our other Atlassian integration libraries:
-- [Jira.js](https://github.com/MrRefactoring/jira.js) - Jira API wrapper
-- [Trello.js](https://github.com/MrRefactoring/trello.js) - Trello API integration
+- [jira.js](https://github.com/MrRefactoring/jira.js) — Jira REST API client
+- [trello.js](https://github.com/MrRefactoring/trello.js) — Trello REST API client
## License
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
new file mode 100644
index 00000000..f45d86c8
--- /dev/null
+++ b/docs/.vitepress/config.ts
@@ -0,0 +1,205 @@
+import { defineConfig } from 'vitepress';
+import typedocSidebar from '../api/typedoc-sidebar.json' with { type: 'json' };
+import typedocSidebarRu from '../api/typedoc-sidebar.ru.json' with { type: 'json' };
+
+const SITE_URL = 'https://mrrefactoring.github.io/confluence.js';
+const SITE_TITLE = 'confluence.js';
+const SITE_TAGLINE = 'Type-safe Confluence Cloud REST API client';
+const SITE_DESCRIPTION_EN =
+ 'Type-safe Confluence Cloud REST API client for TypeScript and JavaScript. Both API versions — v1 and v2 — from one package. ESM-only, tree-shakable, validated by Zod 4.';
+const SITE_DESCRIPTION_RU =
+ 'Типобезопасный клиент Confluence Cloud REST API для TypeScript и JavaScript. Обе версии API — v1 и v2 — в одном пакете. Только ESM, tree-shaking, валидация через Zod 4.';
+const OG_IMAGE = `${SITE_URL}/og-image.png`;
+
+const guideSidebar = (ru = false) => {
+ const p = ru ? '/ru' : '';
+
+ return [
+ {
+ text: ru ? 'Руководство' : 'Guide',
+ items: [
+ { text: ru ? 'Быстрый старт' : 'Getting Started', link: `${p}/guide/getting-started` },
+ { text: ru ? 'Установка' : 'Installation', link: `${p}/guide/installation` },
+ { text: ru ? 'Аутентификация' : 'Authentication', link: `${p}/guide/authentication` },
+ { text: 'OAuth 2.0 (3LO)', link: `${p}/guide/oauth2` },
+ { text: ru ? 'Выбор версии API' : 'Choosing a version', link: `${p}/guide/choosing-a-version` },
+ { text: ru ? 'Обработка ошибок' : 'Error Handling', link: `${p}/guide/error-handling` },
+ { text: ru ? 'Повторы запросов' : 'Retries', link: `${p}/guide/retries` },
+ { text: ru ? 'Браузеры' : 'Browsers', link: `${p}/guide/browser` },
+ { text: 'Tree-Shaking', link: `${p}/guide/tree-shaking` },
+ { text: 'TypeScript', link: `${p}/guide/typescript` },
+ ],
+ },
+ {
+ text: ru ? 'Рецепты' : 'Recipes',
+ items: [
+ { text: ru ? 'Страницы' : 'Pages', link: `${p}/recipes/pages` },
+ { text: ru ? 'Пространства' : 'Spaces', link: `${p}/recipes/spaces` },
+ { text: ru ? 'Вложения' : 'Attachments', link: `${p}/recipes/attachments` },
+ { text: ru ? 'Поиск (CQL)' : 'Search (CQL)', link: `${p}/recipes/search` },
+ { text: ru ? 'Комментарии' : 'Comments', link: `${p}/recipes/comments` },
+ { text: ru ? 'Метки' : 'Labels', link: `${p}/recipes/labels` },
+ { text: ru ? 'Ограничения доступа' : 'Restrictions', link: `${p}/recipes/restrictions` },
+ ],
+ },
+ {
+ text: ru ? 'Миграция' : 'Migration',
+ items: [{ text: '2.x → 3.0', link: `${p}/migration/v2-to-v3` }],
+ },
+ ];
+};
+
+const apiSidebar = [{ text: 'API Reference', items: typedocSidebar }];
+const apiSidebarRu = [{ text: 'API Reference', items: typedocSidebarRu }];
+
+export default defineConfig({
+ title: SITE_TITLE,
+ description: SITE_DESCRIPTION_EN,
+ base: '/confluence.js/',
+ cleanUrls: true,
+ lastUpdated: false,
+
+ // Deliberately not ignoring anything under /api/: `docs:build` always rebuilds
+ // the reference first, so a dead link there is a real one worth failing on.
+ ignoreDeadLinks: ['localhostLinks'],
+
+ sitemap: { hostname: `${SITE_URL}/` },
+
+ head: [
+ // Locale auto-detection, inline so it runs before the first paint:
+ // - already under /ru/ → record the choice, do not redirect;
+ // - a Russian browser with no recorded choice → send to the RU twin of this
+ // exact path, preserving query and hash;
+ // - anything else → record 'en'.
+ // Once a choice is stored, this returns immediately: picking a language from
+ // the switcher is permanent, and a redirect must never override it.
+ [
+ 'script',
+ {},
+ `(function(){try{var K='confluence.js:locale',B='/confluence.js/',p=location.pathname,isRu=p.indexOf(B+'ru/')===0||p===B+'ru'||p===B+'ru/';var s=localStorage.getItem(K);if(s)return;if(isRu){localStorage.setItem(K,'ru');return;}var L=(navigator.language||'').toLowerCase();if(L.indexOf('ru')===0&&p.indexOf(B)===0){localStorage.setItem(K,'ru');location.replace(p.replace(B,B+'ru/')+location.search+location.hash);}else{localStorage.setItem(K,'en');}}catch(e){}})();`,
+ ],
+
+ ['link', { rel: 'icon', href: '/confluence.js/favicon.svg', type: 'image/svg+xml' }],
+ ['meta', { name: 'theme-color', content: '#0052cc' }],
+ ['meta', { name: 'author', content: 'Vladislav Tupikin' }],
+
+ ['meta', { property: 'og:type', content: 'website' }],
+ ['meta', { property: 'og:site_name', content: SITE_TITLE }],
+ ['meta', { property: 'og:title', content: `${SITE_TITLE} — ${SITE_TAGLINE}` }],
+ ['meta', { property: 'og:description', content: SITE_DESCRIPTION_EN }],
+ ['meta', { property: 'og:url', content: `${SITE_URL}/` }],
+ ['meta', { property: 'og:image', content: OG_IMAGE }],
+ ['meta', { property: 'og:image:width', content: '1200' }],
+ ['meta', { property: 'og:image:height', content: '630' }],
+ ['meta', { property: 'og:image:type', content: 'image/png' }],
+ ['meta', { property: 'og:image:alt', content: `${SITE_TITLE} — ${SITE_TAGLINE}` }],
+
+ ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+ ['meta', { name: 'twitter:title', content: `${SITE_TITLE} — ${SITE_TAGLINE}` }],
+ ['meta', { name: 'twitter:description', content: SITE_DESCRIPTION_EN }],
+ ['meta', { name: 'twitter:image', content: OG_IMAGE }],
+
+ [
+ 'script',
+ { type: 'application/ld+json' },
+ JSON.stringify({
+ '@context': 'https://schema.org',
+ '@type': 'SoftwareSourceCode',
+ name: SITE_TITLE,
+ description: SITE_DESCRIPTION_EN,
+ codeRepository: 'https://github.com/MrRefactoring/confluence.js',
+ programmingLanguage: 'TypeScript',
+ runtimePlatform: 'Node.js',
+ license: 'https://opensource.org/licenses/MIT',
+ author: { '@type': 'Person', name: 'Vladislav Tupikin' },
+ keywords: 'confluence, confluence-api, atlassian, typescript, esm, zod, tree-shaking, type-safe, wiki',
+ url: `${SITE_URL}/`,
+ }),
+ ],
+ ],
+
+ transformHead: ({ pageData }) => {
+ const head: [string, Record