confluence-md-sync 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hexstyle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,247 @@
+# confluence-md-sync
+
+[![npm version](https://img.shields.io/npm/v/confluence-md-sync)](https://www.npmjs.com/package/confluence-md-sync)
+[![CI](https://github.com/hexstyle/confluence-md-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/hexstyle/confluence-md-sync/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![node >= 20.11](https://img.shields.io/badge/node-%E2%89%A5%2020.11-brightgreen)](package.json)
+
+Docs-as-code for Confluence (Data Center & Cloud): publish Markdown, read
+typed tables back, attach files — idempotently, with a **pluggable macro
+system**. ESM-only, zero-config CI.
+
+```bash
+npm install confluence-md-sync
+```
+
+## Highlights
+
+- **No history spam** — rendered content is SHA-256-hashed into a content
+  property; identical re-publish skips the update, page version doesn't grow.
+- **Attachment dedup** — uploads are tagged `sha256:<hash>`; unchanged files
+  are reused. `<file>.src-sha256` sidecars pin dedup to the *source* of
+  non-deterministic artifacts (e.g. PNGs rendered by a headless browser).
+- **Fail before write** — placeholders, files and macro markers are validated
+  up front; Confluence is never touched on a broken input.
+- **Pluggable macros** — built-in `core` + `table-filter` plugins, extend
+  with your own in a few lines.
+
+## Configuration
+
+| Env var | Meaning |
+| --- | --- |
+| `CONFLUENCE_BASE_URL` | e.g. `https://confluence.example.com` |
+| `CONFLUENCE_TOKEN` | PAT (Data Center) or API token (Cloud); `CONFLUENCE_PAT` also accepted |
+| `CONFLUENCE_USERNAME` | required for `basic` auth (Cloud e-mail) |
+| `CONFLUENCE_AUTH_TYPE` | `bearer` (default, DC) \| `basic` (Cloud) |
+
+```ts
+import { loadConfigFromEnv } from 'confluence-md-sync';
+const cfg = loadConfigFromEnv();
+// or explicitly:
+// const cfg = { baseUrl, token, username: 'me@example.com', authType: 'basic' };
+```
+
+## Publish a page
+
+Markdown + three placeholder kinds:
+
+```markdown
+# Отчёт за месяц
+
+{{img:flow.png}}          <!-- inline image from images[] -->
+Исходник: {{file:data.csv}}  <!-- attachment link from files[] -->
+
+{{table:summary}}         <!-- table injected from tables[] -->
+```
+
+```ts
+import { publishPage, macros, renderMarkdownTable } from 'confluence-md-sync';
+
+const summary = renderMarkdownTable(rows, [
+  { header: 'Проект',    cell: (r) => r.name },
+  { header: 'Часы',      cell: (r) => r.hours.toFixed(2), align: 'right' },
+  { header: 'Статус',    cell: (r) => r.status },
+]);
+
+await publishPage({
+  pageId: '123456789',
+  markdownPath: 'docs/report.md',
+  images: ['build/flow.png'],
+  files: ['build/data.csv'],
+  tables: [{
+    name: 'summary',
+    // sortable/filterable table with a totals row
+    markdown: macros.tableFilter(
+      macros.tableExcerpt(summary, 'summary'),
+      { totalrow: ',Sum,' },
+    ),
+  }],
+  labels: ['report', 'auto'],
+  versionMessage: 'automated publish',
+}, cfg);
+```
+
+More cases:
+
+```ts
+// By space + title — page is looked up and created when missing
+await publishPage({ spaceKey: 'DOCS', title: 'Monthly Report',
+                    parentPageId: '123', markdown: reportMd }, cfg);
+
+// Dry run — full render + validation, nothing written (great for PR checks)
+const { storage } = await publishPage({ pageId, markdownPath, dryRun: true }, cfg);
+
+// Inline content instead of a file
+await publishPage({ pageId, markdown: '# Generated\n\ntext' }, cfg);
+```
+
+## Read pages and tables
+
+```ts
+import { confluence } from 'confluence-md-sync';
+
+const page = await confluence(cfg).readPage('987654321');
+
+// by index (0 = first) or by table-excerpt macro name
+const employees = page.getTable('employees').toType<Employee>((row, e) => {
+  e.fio   = row['ФИО'];
+  e.email = row['Почта'];
+});
+
+const csv = await page.getAttachmentText('timesheet.csv');
+await page.removeOldAttachmentVersions();   // keep latest version only
+await page.addLabels(['hr']);
+```
+
+CSV helpers (BOM detection, Windows-1251 fallback, `;`/`,` auto-detect):
+
+```ts
+import { decodeText, readCsv, writeCsv } from 'confluence-md-sync/csv';
+const rows = readCsv(decodeText(await page.getAttachment('data.csv')));
+```
+
+## Macros
+
+Builders return `Markdown` with comment markers; markers become
+`<ac:structured-macro>` after rendering (nested macros resolve inner-first):
+
+```ts
+// containers
+macros.expand(body, 'Details');
+macros.note(body, 'Внимание');            // also: info, warning, tip
+macros.panel(body, { title: 'Panel' });
+macros.codeBlock(src, { language: 'sql', title: 'Query' });
+macros.excerpt(body);
+
+// bodyless
+macros.toc({ maxLevel: '3' });
+macros.status('Green', 'ON TRACK');
+macros.jiraIssue('PROJ-123');
+macros.anchor('section-1');
+macros.children({ depth: '2' });
+
+// cross-page includes
+macros.includePage('Page Title', 'DOCS');
+macros.excerptInclude('Source Page');
+macros.tableExcerptInclude('name', 'Source Page');
+
+// Table Filter and Charts app
+macros.tableExcerpt(md, 'name', /* hide */ true);
+macros.tableFilter(md, { totalrow: ',,Sum' });
+```
+
+Or write markers by hand right in Markdown:
+
+```markdown
+<!-- MACRO:start:expand:title=Детали -->
+Any **markdown**, including nested macros.
+<!-- MACRO:end:expand -->
+```
+
+### Custom macro plugin
+
+```ts
+import { MacroRegistry, coreMacrosPlugin, tableFilterPlugin,
+         structuredMacro } from 'confluence-md-sync';
+
+const registry = new MacroRegistry()
+  .use(coreMacrosPlugin)
+  .use(tableFilterPlugin)
+  .register('roadmap', (ctx) =>
+    structuredMacro('roadmap', ctx.macroId, { params: ctx.params, richBody: ctx.body }));
+
+await publishPage({ pageId, markdownPath, registry }, cfg);
+```
+
+`structuredMacro()` handles escaping, rich vs plain (CDATA) bodies and `]]>`
+splitting; `pageLinkValue()` builds `<ac:link><ri:page/>` parameter values.
+
+## CLI
+
+```bash
+npx confluence-md-sync publish docs/page.md --page-id 123456789 \
+  --image build/flow.png --file build/data.csv --label docs
+
+npx confluence-md-sync publish docs/page.md --space DOCS --title "Моя страница" --dry-run
+```
+
+## CI publish plans
+
+```ts
+// docs/dev-process/publish.ts — run with `npx tsx`
+import { runPublish } from 'confluence-md-sync';
+
+await runPublish(import.meta.dirname, (here, build) => [
+  { pageId: '111', markdownPath: here('process.md'), images: [build('flow.png')] },
+  { pageId: '222', markdownPath: here('release.md') },
+]);
+```
+
+```yaml
+# .github/workflows/docs.yml
+- run: npx tsx docs/dev-process/publish.ts
+  env:
+    CONFLUENCE_BASE_URL: ${{ vars.CONFLUENCE_BASE_URL }}
+    CONFLUENCE_TOKEN: ${{ secrets.CONFLUENCE_TOKEN }}
+```
+
+`here()` resolves next to the script, `build()` inside the artifacts dir; the
+process exits 1 before any write on error.
+
+## Architecture
+
+```
+src/
+├── client/        REST client + auth: pages, properties, attachments, labels, CQL
+├── markdown/      Markdown type, markdown-it → storage renderer, validation
+├── macros/        registry, builder, plugins (core, table-filter)
+├── attachments/   sha256 dedup, sidecar source hashes, version history
+├── pages/         Page/Table object model, table parse & render
+├── publish/       idempotent publish pipeline, runPublish plans
+├── wrapper.ts     confluence() facade
+├── csv.ts         CSV helpers (subpath export ./csv)
+└── cli.ts         confluence-md-sync CLI
+```
+
+## Roadmap
+
+Cloud API v2 backend · page-tree sync from a directory · storage→Markdown
+reverse conversion · Mermaid/PlantUML fences → images · fenced code →
+`code` macro · HTTP retry/backoff · comments API · dry-run diff preview.
+
+Issues and PRs welcome.
+
+## Development
+
+```bash
+npm ci
+npm run typecheck && npm test && npm run build
+```
+
+Releasing (maintainers): `npm version minor && git push --follow-tags` —
+the `v*` tag triggers the npm publish workflow (tag must match
+`package.json` version).
+
+## License
+
+[MIT](LICENSE)

package/dist/attachments/attachment.d.ts

@@ -0,0 +1,39 @@
+import { ConfluenceClient, type AttachmentVersionData } from '../client/client.js';
+export declare const SRC_SHA_SIDECAR_SUFFIX = ".src-sha256";
+export interface EnsuredAttachment {
+    id: string;
+    filename: string;
+    reused: boolean;
+    hash: string;
+    /** Абсолютный URL скачивания аттача — подставляется в `<img>` / `<a>`. */
+    downloadUrl: string;
+}
+export interface AttachmentVersion {
+    version: number;
+    fileSize?: number;
+    author?: string;
+}
+/** Rich-объект аттача страницы Confluence с историей версий. */
+export declare class Attachment {
+    readonly id: string;
+    readonly pageId: string;
+    readonly title: string;
+    readonly version: number;
+    readonly downloadUrl: string;
+    readonly versions: AttachmentVersion[];
+    constructor(id: string, pageId: string, title: string, version: number, downloadUrl: string, versions?: AttachmentVersion[]);
+}
+export declare function toAttachmentVersion(v: AttachmentVersionData): AttachmentVersion;
+export declare class AttachmentService {
+    private client;
+    constructor(client: ConfluenceClient);
+    /**
+     * Загружает аттач (или переиспользует по SHA-256). Дедуп по тегу
+     * version.message = sha256:<hash>, чтобы повторные прогоны CI не плодили
+     * версии одинакового файла.
+     */
+    ensure(pageId: string, filePath: string): Promise<EnsuredAttachment>;
+    download(att: Attachment): Promise<Buffer>;
+    delete(att: Attachment): Promise<void>;
+    private downloadUrlOf;
+}

package/dist/attachments/attachment.js

@@ -0,0 +1,83 @@
+import { basename } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileSha256, HASH_TAG_PREFIX } from './hash.js';
+// Sidecar с SHA-256 исходного файла (например, BPMN), из которого
+// сгенерирован публикуемый аттач (PNG). Если рядом с filePath лежит
+// `<filePath>.src-sha256`, используем содержимое sidecar как dedup-tag
+// вместо SHA самого аттача. Это критично для PNG'шек от Chromium
+// (anti-aliasing/fonts нестабильны между CI runs — SHA PNG скачет даже
+// при том же исходнике), благодаря sidecar attachment не пересоздаётся
+// повторно и Confluence не плодит лишние версии.
+export const SRC_SHA_SIDECAR_SUFFIX = '.src-sha256';
+function readDedupHash(filePath) {
+    const sidecar = filePath + SRC_SHA_SIDECAR_SUFFIX;
+    if (existsSync(sidecar)) {
+        return readFileSync(sidecar, 'utf-8').trim();
+    }
+    return fileSha256(filePath);
+}
+/** Rich-объект аттача страницы Confluence с историей версий. */
+export class Attachment {
+    id;
+    pageId;
+    title;
+    version;
+    downloadUrl;
+    versions;
+    constructor(id, pageId, title, version, downloadUrl, versions = []) {
+        this.id = id;
+        this.pageId = pageId;
+        this.title = title;
+        this.version = version;
+        this.downloadUrl = downloadUrl;
+        this.versions = versions;
+    }
+}
+function versionNumberOf(v) {
+    return v.versionNumber ?? v.version ?? v.number ?? 0;
+}
+export function toAttachmentVersion(v) {
+    return { version: versionNumberOf(v), fileSize: v.fileSize, author: v.author?.fullName };
+}
+export class AttachmentService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Загружает аттач (или переиспользует по SHA-256). Дедуп по тегу
+     * version.message = sha256:<hash>, чтобы повторные прогоны CI не плодили
+     * версии одинакового файла.
+     */
+    async ensure(pageId, filePath) {
+        const filename = basename(filePath);
+        // dedup-tag: SHA исходника из sidecar если есть, иначе SHA самого файла.
+        // См. readDedupHash наверху и SRC_SHA_SIDECAR_SUFFIX.
+        const hash = readDedupHash(filePath);
+        const tag = `${HASH_TAG_PREFIX}${hash}`;
+        const existing = await this.client.listAttachments(pageId, filename);
+        const matched = existing.find((a) => a.version?.message === tag);
+        if (matched) {
+            return { id: matched.id, filename, reused: true, hash, downloadUrl: this.downloadUrlOf(pageId, matched) };
+        }
+        const sameName = existing[0];
+        if (sameName) {
+            const updated = await this.client.updateAttachmentData(pageId, sameName.id, filePath, tag);
+            return { id: updated.id ?? sameName.id, filename, reused: false, hash, downloadUrl: this.downloadUrlOf(pageId, updated) };
+        }
+        const created = await this.client.createAttachment(pageId, filePath, tag);
+        return { id: created.id, filename, reused: false, hash, downloadUrl: this.downloadUrlOf(pageId, created) };
+    }
+    async download(att) {
+        return this.client.downloadAttachment(att.downloadUrl);
+    }
+    async delete(att) {
+        await this.client.deleteAttachment(att.id);
+    }
+    downloadUrlOf(pageId, attachment) {
+        const link = attachment._links?.download;
+        if (link)
+            return this.client.absoluteUrl(link);
+        return this.client.absoluteUrl(`/download/attachments/${pageId}/${encodeURIComponent(attachment.title)}`);
+    }
+}

package/dist/attachments/hash.d.ts

@@ -0,0 +1,2 @@
+export declare const HASH_TAG_PREFIX = "sha256:";
+export declare function fileSha256(filePath: string): string;

package/dist/attachments/hash.js

@@ -0,0 +1,6 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+export const HASH_TAG_PREFIX = 'sha256:';
+export function fileSha256(filePath) {
+    return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+}

package/dist/cli.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Минимальный CLI:
+ *
+ *   confluence-md-sync publish page.md --page-id 12345 \
+ *     --image build/p1.png --file data.csv --label docs --dry-run
+ *
+ *   confluence-md-sync publish page.md --space DOCS --title "My Page" --parent-id 777
+ *
+ * Конфиг — из env: CONFLUENCE_BASE_URL, CONFLUENCE_TOKEN (или CONFLUENCE_PAT),
+ * CONFLUENCE_USERNAME, CONFLUENCE_AUTH_TYPE (bearer|basic).
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Минимальный CLI:
+ *
+ *   confluence-md-sync publish page.md --page-id 12345 \
+ *     --image build/p1.png --file data.csv --label docs --dry-run
+ *
+ *   confluence-md-sync publish page.md --space DOCS --title "My Page" --parent-id 777
+ *
+ * Конфиг — из env: CONFLUENCE_BASE_URL, CONFLUENCE_TOKEN (или CONFLUENCE_PAT),
+ * CONFLUENCE_USERNAME, CONFLUENCE_AUTH_TYPE (bearer|basic).
+ */
+import { parseArgs } from 'node:util';
+import { loadConfigFromEnv } from './client/config.js';
+import { publishPage } from './publish/publish.js';
+const HELP = `confluence-md-sync — publish Markdown to Confluence
+
+Usage:
+  confluence-md-sync publish <markdown-file> [options]
+
+Options:
+  --page-id <id>        Target page ID
+  --space <key>         Space key (with --title, when page ID is unknown)
+  --title <title>       Page title (rename, or lookup/create key with --space)
+  --parent-id <id>      Parent page for page creation
+  --image <path>        Attach an image (repeatable), referenced as {{img:name.png}}
+  --file <path>         Attach a file (repeatable), referenced as {{file:name.csv}}
+  --label <name>        Ensure label on the page (repeatable)
+  --message <text>      Page version comment
+  --no-create           Fail instead of creating a missing page
+  --dry-run             Render and validate without writing to Confluence
+  --help                Show this help
+
+Environment:
+  CONFLUENCE_BASE_URL   e.g. https://confluence.example.com
+  CONFLUENCE_TOKEN      PAT (Data Center) or API token (Cloud); CONFLUENCE_PAT also works
+  CONFLUENCE_USERNAME   required for basic auth (Cloud e-mail)
+  CONFLUENCE_AUTH_TYPE  bearer (default) | basic
+`;
+async function main() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            'page-id': { type: 'string' },
+            space: { type: 'string' },
+            title: { type: 'string' },
+            'parent-id': { type: 'string' },
+            image: { type: 'string', multiple: true },
+            file: { type: 'string', multiple: true },
+            label: { type: 'string', multiple: true },
+            message: { type: 'string' },
+            'no-create': { type: 'boolean' },
+            'dry-run': { type: 'boolean' },
+            help: { type: 'boolean' },
+        },
+    });
+    if (values.help || positionals.length === 0) {
+        console.log(HELP);
+        process.exit(values.help ? 0 : 1);
+    }
+    const [command, markdownPath] = positionals;
+    if (command !== 'publish' || !markdownPath) {
+        console.error(`Unknown command or missing file. See --help.`);
+        process.exit(1);
+    }
+    const cfg = loadConfigFromEnv();
+    const result = await publishPage({
+        pageId: values['page-id'],
+        spaceKey: values.space,
+        title: values.title,
+        parentPageId: values['parent-id'],
+        markdownPath,
+        images: values.image ?? [],
+        files: values.file ?? [],
+        labels: values.label,
+        versionMessage: values.message,
+        createIfMissing: values['no-create'] ? false : undefined,
+        dryRun: values['dry-run'],
+    }, cfg);
+    console.log(`[cli] ${result.updated ? 'published' : 'unchanged'}: page ${result.pageId} v${result.version}`);
+}
+main().catch((err) => {
+    console.error(`[cli] failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/client/client.d.ts

@@ -0,0 +1,128 @@
+import { type ConfluenceConfig } from './config.js';
+export interface ConfluencePage {
+    id: string;
+    title: string;
+    version: {
+        number: number;
+    };
+}
+export interface ConfluencePageStorage {
+    title: string;
+    storage: string;
+    version: number;
+}
+export interface ConfluenceAttachment {
+    id: string;
+    title: string;
+    version: {
+        number: number;
+        message?: string;
+    };
+    extensions?: {
+        fileSize?: number;
+    };
+    /**
+     * `_links.download` — относительный путь скачивания, который Confluence
+     * возвращает в ответе и который нужно подставлять в `<img src>` / `<a href>`
+     * после аплоада. Абсолютизируется через `client.absoluteUrl(...)`.
+     */
+    _links?: {
+        download?: string;
+        webui?: string;
+    };
+}
+/** Версия аттача из /rest/files/1.0/files/{id}/versions (поля гибкие). */
+export interface AttachmentVersionData {
+    versionNumber?: number;
+    version?: number;
+    number?: number;
+    fileName?: string;
+    fileSize?: number;
+    author?: {
+        fullName?: string;
+    };
+}
+export interface ConfluenceLabel {
+    prefix: string;
+    name: string;
+}
+export interface CreatePageOptions {
+    spaceKey: string;
+    title: string;
+    parentId?: string;
+    /** Initial body in storage format. Defaults to an empty page. */
+    storage?: string;
+}
+export declare class ConfluenceApiError extends Error {
+    readonly status: number;
+    readonly statusText: string;
+    readonly detail: string;
+    constructor(message: string, status: number, statusText: string, detail: string);
+}
+export declare class ConfluenceClient {
+    private readonly auth;
+    readonly baseUrl: string;
+    constructor(cfg: ConfluenceConfig);
+    /** Превращает относительный путь из API (`/download/...`) в абсолютный URL. */
+    absoluteUrl(path: string): string;
+    private url;
+    private headers;
+    private parseError;
+    getPage(pageId: string): Promise<ConfluencePage>;
+    getPageStorage(pageId: string): Promise<ConfluencePageStorage>;
+    /** Finds a page by space key and exact title. Returns null if not found. */
+    getPageByTitle(spaceKey: string, title: string): Promise<ConfluencePage | null>;
+    createPage(opts: CreatePageOptions): Promise<ConfluencePage>;
+    updatePage(pageId: string, body: {
+        title: string;
+        version: number;
+        storage: string;
+        versionMessage?: string;
+    }): Promise<void>;
+    deletePage(pageId: string): Promise<void>;
+    /** Direct child pages of a page. */
+    getChildPages(pageId: string, limit?: number): Promise<ConfluencePage[]>;
+    /** CQL content search (e.g. `space = DOCS and type = page and title ~ "Report*"`). */
+    search(cql: string, limit?: number): Promise<ConfluencePage[]>;
+    getLabels(pageId: string): Promise<ConfluenceLabel[]>;
+    addLabels(pageId: string, labels: string[]): Promise<void>;
+    removeLabel(pageId: string, label: string): Promise<void>;
+    /**
+     * Content Property — произвольные key/value на странице вне body.
+     * Используется для content-hash (см. publish.ts): попытка хранить
+     * hash в body как HTML-comment не пережила нормализацию storage Confluence.
+     * Возвращает null, если property с таким ключом нет.
+     */
+    getContentProperty(pageId: string, key: string): Promise<{
+        value: unknown;
+        version: number;
+    } | null>;
+    /**
+     * Создаёт (если version null) или обновляет content property.
+     * При update Confluence требует следующий version-номер.
+     */
+    setContentProperty(pageId: string, key: string, value: unknown, currentVersion: number | null): Promise<void>;
+    listAttachments(pageId: string, filename?: string): Promise<ConfluenceAttachment[]>;
+    createAttachment(pageId: string, filePath: string, comment?: string): Promise<ConfluenceAttachment>;
+    /**
+     * Скачивает содержимое аттача по download-пути из `_links.download`
+     * (или абсолютному URL). Возвращает сырые байты — текстовая
+     * декодировка лежит на caller'е.
+     */
+    downloadAttachment(downloadPath: string): Promise<Buffer>;
+    updateAttachmentData(pageId: string, attachmentId: string, filePath: string, comment?: string): Promise<ConfluenceAttachment>;
+    /**
+     * Список версий аттача через Confluence Files API (Data Center only).
+     * Структура ответа гибкая — номер версии нормализуется потребителем
+     * (поле versionNumber / version / number).
+     */
+    getAttachmentVersions(attachmentId: string): Promise<AttachmentVersionData[]>;
+    /**
+     * Удаляет конкретную версию аттача (Data Center only). REST-аналога нет,
+     * идём через legacy-action; XSRF обходим заголовком X-Atlassian-Token:
+     * no-check (тот же приём работает для createAttachment).
+     */
+    removeAttachmentVersion(pageId: string, fileName: string, version: number): Promise<void>;
+    /** Удаляет аттач целиком (все версии). */
+    deleteAttachment(attachmentId: string): Promise<void>;
+}