confluence-md-sync 0.1.1

package/dist/client/client.js

@@ -0,0 +1,311 @@
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { authHeader } from './config.js';
+export class ConfluenceApiError extends Error {
+    status;
+    statusText;
+    detail;
+    constructor(message, status, statusText, detail) {
+        super(message);
+        this.status = status;
+        this.statusText = statusText;
+        this.detail = detail;
+        this.name = 'ConfluenceApiError';
+    }
+}
+export class ConfluenceClient {
+    auth;
+    baseUrl;
+    constructor(cfg) {
+        if (!cfg.baseUrl)
+            throw new Error('ConfluenceClient: baseUrl is required');
+        if (!cfg.token)
+            throw new Error('ConfluenceClient: token is required');
+        this.baseUrl = cfg.baseUrl.replace(/\/+$/, '');
+        this.auth = authHeader(cfg);
+    }
+    /** Превращает относительный путь из API (`/download/...`) в абсолютный URL. */
+    absoluteUrl(path) {
+        if (/^https?:\/\//i.test(path))
+            return path;
+        return `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    }
+    url(path) {
+        return `${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`;
+    }
+    headers(extra = {}) {
+        return {
+            Authorization: this.auth,
+            Accept: 'application/json',
+            ...extra,
+        };
+    }
+    async parseError(res, label) {
+        let detail = '';
+        try {
+            detail = await res.text();
+        }
+        catch {
+            detail = '<no body>';
+        }
+        throw new ConfluenceApiError(`${label}: ${res.status} ${res.statusText} — ${detail.slice(0, 500)}`, res.status, res.statusText, detail);
+    }
+    // ── Pages ────────────────────────────────────────────────────────────
+    async getPage(pageId) {
+        const res = await fetch(this.url(`/rest/api/content/${pageId}?expand=version`), { headers: this.headers() });
+        if (!res.ok)
+            await this.parseError(res, `getPage(${pageId})`);
+        return (await res.json());
+    }
+    async getPageStorage(pageId) {
+        const res = await fetch(this.url(`/rest/api/content/${pageId}?expand=body.storage,version`), { headers: this.headers() });
+        if (!res.ok)
+            await this.parseError(res, `getPageStorage(${pageId})`);
+        const data = (await res.json());
+        return {
+            title: data.title ?? '',
+            storage: data.body?.storage?.value ?? '',
+            version: data.version?.number ?? 0,
+        };
+    }
+    /** Finds a page by space key and exact title. Returns null if not found. */
+    async getPageByTitle(spaceKey, title) {
+        const params = new URLSearchParams({ spaceKey, title, expand: 'version' });
+        const res = await fetch(this.url(`/rest/api/content?${params}`), {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            await this.parseError(res, `getPageByTitle(${spaceKey}, ${title})`);
+        const data = (await res.json());
+        return data.results?.[0] ?? null;
+    }
+    async createPage(opts) {
+        const body = {
+            type: 'page',
+            title: opts.title,
+            space: { key: opts.spaceKey },
+            body: {
+                storage: { value: opts.storage ?? '', representation: 'storage' },
+            },
+        };
+        if (opts.parentId)
+            body.ancestors = [{ id: opts.parentId }];
+        const res = await fetch(this.url('/rest/api/content'), {
+            method: 'POST',
+            headers: this.headers({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            await this.parseError(res, `createPage(${opts.spaceKey}/${opts.title})`);
+        return (await res.json());
+    }
+    async updatePage(pageId, body) {
+        const version = { number: body.version };
+        if (body.versionMessage)
+            version.message = body.versionMessage;
+        const res = await fetch(this.url(`/rest/api/content/${pageId}`), {
+            method: 'PUT',
+            headers: this.headers({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify({
+                id: pageId,
+                type: 'page',
+                title: body.title,
+                version,
+                body: {
+                    storage: { value: body.storage, representation: 'storage' },
+                },
+            }),
+        });
+        if (!res.ok)
+            await this.parseError(res, `updatePage(${pageId})`);
+    }
+    async deletePage(pageId) {
+        const res = await fetch(this.url(`/rest/api/content/${pageId}`), {
+            method: 'DELETE',
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            await this.parseError(res, `deletePage(${pageId})`);
+    }
+    /** Direct child pages of a page. */
+    async getChildPages(pageId, limit = 200) {
+        const res = await fetch(this.url(`/rest/api/content/${pageId}/child/page?limit=${limit}&expand=version`), { headers: this.headers() });
+        if (!res.ok)
+            await this.parseError(res, `getChildPages(${pageId})`);
+        const data = (await res.json());
+        return data.results ?? [];
+    }
+    /** CQL content search (e.g. `space = DOCS and type = page and title ~ "Report*"`). */
+    async search(cql, limit = 50) {
+        const params = new URLSearchParams({ cql, limit: String(limit), expand: 'version' });
+        const res = await fetch(this.url(`/rest/api/content/search?${params}`), {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            await this.parseError(res, `search(${cql})`);
+        const data = (await res.json());
+        return data.results ?? [];
+    }
+    // ── Labels ───────────────────────────────────────────────────────────
+    async getLabels(pageId) {
+        const res = await fetch(this.url(`/rest/api/content/${pageId}/label`), {
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            await this.parseError(res, `getLabels(${pageId})`);
+        const data = (await res.json());
+        return data.results ?? [];
+    }
+    async addLabels(pageId, labels) {
+        if (labels.length === 0)
+            return;
+        const res = await fetch(this.url(`/rest/api/content/${pageId}/label`), {
+            method: 'POST',
+            headers: this.headers({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(labels.map((name) => ({ prefix: 'global', name }))),
+        });
+        if (!res.ok)
+            await this.parseError(res, `addLabels(${pageId})`);
+    }
+    async removeLabel(pageId, label) {
+        const res = await fetch(this.url(`/rest/api/content/${pageId}/label/${encodeURIComponent(label)}`), { method: 'DELETE', headers: this.headers() });
+        if (!res.ok)
+            await this.parseError(res, `removeLabel(${pageId}, ${label})`);
+    }
+    // ── Content properties ───────────────────────────────────────────────
+    /**
+     * Content Property — произвольные key/value на странице вне body.
+     * Используется для content-hash (см. publish.ts): попытка хранить
+     * hash в body как HTML-comment не пережила нормализацию storage Confluence.
+     * Возвращает null, если property с таким ключом нет.
+     */
+    async getContentProperty(pageId, key) {
+        const res = await fetch(this.url(`/rest/api/content/${pageId}/property/${encodeURIComponent(key)}`), { headers: this.headers() });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            await this.parseError(res, `getContentProperty(${pageId}, ${key})`);
+        const data = (await res.json());
+        return { value: data.value, version: data.version?.number ?? 1 };
+    }
+    /**
+     * Создаёт (если version null) или обновляет content property.
+     * При update Confluence требует следующий version-номер.
+     */
+    async setContentProperty(pageId, key, value, currentVersion) {
+        const isUpdate = currentVersion !== null;
+        const url = isUpdate
+            ? this.url(`/rest/api/content/${pageId}/property/${encodeURIComponent(key)}`)
+            : this.url(`/rest/api/content/${pageId}/property`);
+        const body = { key, value };
+        if (isUpdate)
+            body.version = { number: currentVersion + 1 };
+        const res = await fetch(url, {
+            method: isUpdate ? 'PUT' : 'POST',
+            headers: this.headers({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(body),
+        });
+        if (!res.ok)
+            await this.parseError(res, `setContentProperty(${pageId}, ${key})`);
+    }
+    // ── Attachments ──────────────────────────────────────────────────────
+    async listAttachments(pageId, filename) {
+        // expand=version нужен для дедупа по version.message (sha256-тегу).
+        // _links возвращается по умолчанию, явный expand не требуется.
+        const params = new URLSearchParams({ expand: 'version', limit: '200' });
+        if (filename)
+            params.set('filename', filename);
+        const res = await fetch(this.url(`/rest/api/content/${pageId}/child/attachment?${params}`), { headers: this.headers() });
+        if (!res.ok)
+            await this.parseError(res, `listAttachments(${pageId})`);
+        const data = (await res.json());
+        return data.results ?? [];
+    }
+    async createAttachment(pageId, filePath, comment) {
+        const filename = basename(filePath);
+        const buf = readFileSync(filePath);
+        const form = new FormData();
+        form.append('file', new Blob([buf]), filename);
+        form.append('minorEdit', 'true');
+        if (comment)
+            form.append('comment', comment);
+        const res = await fetch(this.url(`/rest/api/content/${pageId}/child/attachment`), {
+            method: 'POST',
+            headers: this.headers({ 'X-Atlassian-Token': 'nocheck' }),
+            body: form,
+        });
+        if (!res.ok)
+            await this.parseError(res, `createAttachment(${filename})`);
+        const data = (await res.json());
+        return 'results' in data ? data.results[0] : data;
+    }
+    /**
+     * Скачивает содержимое аттача по download-пути из `_links.download`
+     * (или абсолютному URL). Возвращает сырые байты — текстовая
+     * декодировка лежит на caller'е.
+     */
+    async downloadAttachment(downloadPath) {
+        const res = await fetch(this.absoluteUrl(downloadPath), {
+            headers: { Authorization: this.auth },
+        });
+        if (!res.ok)
+            await this.parseError(res, `downloadAttachment(${downloadPath})`);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    async updateAttachmentData(pageId, attachmentId, filePath, comment) {
+        const filename = basename(filePath);
+        const buf = readFileSync(filePath);
+        const form = new FormData();
+        form.append('file', new Blob([buf]), filename);
+        form.append('minorEdit', 'true');
+        if (comment)
+            form.append('comment', comment);
+        const res = await fetch(this.url(`/rest/api/content/${pageId}/child/attachment/${attachmentId}/data`), {
+            method: 'POST',
+            headers: this.headers({ 'X-Atlassian-Token': 'nocheck' }),
+            body: form,
+        });
+        if (!res.ok)
+            await this.parseError(res, `updateAttachmentData(${filename})`);
+        return (await res.json());
+    }
+    /**
+     * Список версий аттача через Confluence Files API (Data Center only).
+     * Структура ответа гибкая — номер версии нормализуется потребителем
+     * (поле versionNumber / version / number).
+     */
+    async getAttachmentVersions(attachmentId) {
+        const res = await fetch(this.url(`/rest/files/1.0/files/${attachmentId}/versions`), { headers: this.headers() });
+        if (!res.ok)
+            await this.parseError(res, `getAttachmentVersions(${attachmentId})`);
+        const data = (await res.json());
+        return Array.isArray(data) ? data : (data.versions ?? []);
+    }
+    /**
+     * Удаляет конкретную версию аттача (Data Center only). REST-аналога нет,
+     * идём через legacy-action; XSRF обходим заголовком X-Atlassian-Token:
+     * no-check (тот же приём работает для createAttachment).
+     */
+    async removeAttachmentVersion(pageId, fileName, version) {
+        const params = new URLSearchParams({ pageId, fileName, version: String(version) });
+        const res = await fetch(this.url(`/json/removeattachmentversion.action?${params}`), {
+            method: 'POST',
+            headers: this.headers({
+                'X-Atlassian-Token': 'no-check',
+                'Content-Type': 'application/x-www-form-urlencoded; charset=UTF-8',
+            }),
+            body: '',
+        });
+        if (!res.ok)
+            await this.parseError(res, `removeAttachmentVersion(${fileName} v${version})`);
+    }
+    /** Удаляет аттач целиком (все версии). */
+    async deleteAttachment(attachmentId) {
+        const res = await fetch(this.url(`/rest/api/content/${attachmentId}`), {
+            method: 'DELETE',
+            headers: this.headers(),
+        });
+        if (!res.ok)
+            await this.parseError(res, `deleteAttachment(${attachmentId})`);
+    }
+}

package/dist/client/config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Configuration and authentication for the Confluence REST client.
+ *
+ * Supports both deployment flavours:
+ *  - Data Center / Server: Personal Access Token via `Authorization: Bearer`.
+ *  - Cloud: email + API token via `Authorization: Basic`.
+ */
+export type ConfluenceAuthType = 'bearer' | 'basic';
+export interface ConfluenceConfig {
+    /** Base URL of the Confluence instance, e.g. `https://confluence.example.com` or `https://your.atlassian.net/wiki`. */
+    baseUrl: string;
+    /** Personal Access Token (Data Center) or API token (Cloud). */
+    token: string;
+    /**
+     * Username / e-mail. Required for `basic` auth (Cloud); for `bearer`
+     * it is optional and used only for logging.
+     */
+    username?: string;
+    /**
+     * Authentication scheme. Defaults to `bearer` (Data Center PAT).
+     * Set to `basic` for Confluence Cloud (username = Atlassian account e-mail).
+     */
+    authType?: ConfluenceAuthType;
+}
+/** Builds the `Authorization` header value for the given config. */
+export declare function authHeader(cfg: ConfluenceConfig): string;
+export interface LoadConfigOptions {
+    /**
+     * Extra env var names to try for the token, before the standard ones.
+     * Useful for legacy CI setups with non-standard variable names.
+     */
+    tokenEnvVars?: string[];
+}
+/**
+ * Loads Confluence config from environment variables:
+ *
+ *  - `CONFLUENCE_BASE_URL` (required)
+ *  - `CONFLUENCE_TOKEN` or `CONFLUENCE_PAT` (required)
+ *  - `CONFLUENCE_USERNAME` (optional; required for basic auth)
+ *  - `CONFLUENCE_AUTH_TYPE` (`bearer` | `basic`, optional, default `bearer`)
+ */
+export declare function loadConfigFromEnv(opts?: LoadConfigOptions): ConfluenceConfig;

package/dist/client/config.js

@@ -0,0 +1,54 @@
+/**
+ * Configuration and authentication for the Confluence REST client.
+ *
+ * Supports both deployment flavours:
+ *  - Data Center / Server: Personal Access Token via `Authorization: Bearer`.
+ *  - Cloud: email + API token via `Authorization: Basic`.
+ */
+/** Builds the `Authorization` header value for the given config. */
+export function authHeader(cfg) {
+    const authType = cfg.authType ?? 'bearer';
+    if (authType === 'basic') {
+        if (!cfg.username) {
+            throw new Error("ConfluenceConfig: username is required for authType 'basic'");
+        }
+        return `Basic ${Buffer.from(`${cfg.username}:${cfg.token}`).toString('base64')}`;
+    }
+    // Confluence DC принимает Personal Access Token через Bearer-схему.
+    // Basic с username:PAT тоже формально поддерживается, но требует точного
+    // совпадения логина (LDAP/AD), что капризно — Bearer этим не страдает.
+    return `Bearer ${cfg.token}`;
+}
+/**
+ * Loads Confluence config from environment variables:
+ *
+ *  - `CONFLUENCE_BASE_URL` (required)
+ *  - `CONFLUENCE_TOKEN` or `CONFLUENCE_PAT` (required)
+ *  - `CONFLUENCE_USERNAME` (optional; required for basic auth)
+ *  - `CONFLUENCE_AUTH_TYPE` (`bearer` | `basic`, optional, default `bearer`)
+ */
+export function loadConfigFromEnv(opts = {}) {
+    const tokenVars = [...(opts.tokenEnvVars ?? []), 'CONFLUENCE_TOKEN', 'CONFLUENCE_PAT'];
+    let token;
+    for (const name of tokenVars) {
+        token = process.env[name];
+        if (token)
+            break;
+    }
+    if (!token) {
+        throw new Error(`Required env var for Confluence token is not set (tried: ${tokenVars.join(', ')})`);
+    }
+    const baseUrl = process.env.CONFLUENCE_BASE_URL;
+    if (!baseUrl)
+        throw new Error("Required env var 'CONFLUENCE_BASE_URL' is not set");
+    const authType = process.env.CONFLUENCE_AUTH_TYPE;
+    if (authType && authType !== 'bearer' && authType !== 'basic') {
+        throw new Error(`CONFLUENCE_AUTH_TYPE must be 'bearer' or 'basic', got '${authType}'`);
+    }
+    return {
+        baseUrl,
+        token,
+        username: process.env.CONFLUENCE_USERNAME,
+        authType,
+    };
+}

package/dist/csv.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Авто-декод текстового файла: UTF-8/UTF-16 BOM → соответствующая UTF;
+ * без BOM пробуем strict UTF-8 (fatal: true), если падает на невалидной
+ * последовательности — fallback на Windows-1251 (типичная кодировка
+ * для русских CSV из Excel/1С).
+ */
+export declare function decodeText(buf: Buffer): string;
+/**
+ * Парсит CSV (RFC 4180): кавычки, экранирование `""`, CRLF/LF. Разделитель
+ * определяется по первой строке — если `;` больше `,`, то `;`, иначе `,`.
+ */
+export declare function readCsv(text: string): string[][];
+/**
+ * Пишет CSV с `;`-разделителем (русский Excel), CRLF, кавычками вокруг полей
+ * с `;` / `"` / переносом и экранированием `"` → `""`. BOM в начале — чтобы
+ * Excel сразу распознал UTF-8 кириллицу.
+ */
+export declare function writeCsv(path: string, rows: string[][]): void;

package/dist/csv.js

@@ -0,0 +1,86 @@
+import { writeFileSync } from 'node:fs';
+/**
+ * Авто-декод текстового файла: UTF-8/UTF-16 BOM → соответствующая UTF;
+ * без BOM пробуем strict UTF-8 (fatal: true), если падает на невалидной
+ * последовательности — fallback на Windows-1251 (типичная кодировка
+ * для русских CSV из Excel/1С).
+ */
+export function decodeText(buf) {
+    if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+        return new TextDecoder('utf-8').decode(buf.subarray(3));
+    }
+    if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+        return new TextDecoder('utf-16le').decode(buf.subarray(2));
+    }
+    if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) {
+        return new TextDecoder('utf-16be').decode(buf.subarray(2));
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+    }
+    catch {
+        return new TextDecoder('windows-1251').decode(buf);
+    }
+}
+/**
+ * Парсит CSV (RFC 4180): кавычки, экранирование `""`, CRLF/LF. Разделитель
+ * определяется по первой строке — если `;` больше `,`, то `;`, иначе `,`.
+ */
+export function readCsv(text) {
+    const firstLine = text.split(/\r?\n/, 1)[0] ?? '';
+    const sep = (firstLine.match(/;/g) ?? []).length > (firstLine.match(/,/g) ?? []).length ? ';' : ',';
+    const rows = [];
+    let cur = [];
+    let field = '';
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === '"' && text[i + 1] === '"') {
+                field += '"';
+                i++;
+                continue;
+            }
+            if (c === '"') {
+                inQuotes = false;
+                continue;
+            }
+            field += c;
+            continue;
+        }
+        if (c === '"') {
+            inQuotes = true;
+            continue;
+        }
+        if (c === sep) {
+            cur.push(field);
+            field = '';
+            continue;
+        }
+        if (c === '\r')
+            continue;
+        if (c === '\n') {
+            cur.push(field);
+            rows.push(cur);
+            cur = [];
+            field = '';
+            continue;
+        }
+        field += c;
+    }
+    if (field !== '' || cur.length > 0) {
+        cur.push(field);
+        rows.push(cur);
+    }
+    return rows;
+}
+/**
+ * Пишет CSV с `;`-разделителем (русский Excel), CRLF, кавычками вокруг полей
+ * с `;` / `"` / переносом и экранированием `"` → `""`. BOM в начале — чтобы
+ * Excel сразу распознал UTF-8 кириллицу.
+ */
+export function writeCsv(path, rows) {
+    const esc = (s) => (/[";\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s);
+    const text = '' + rows.map((r) => r.map((c) => esc(c ?? '')).join(';')).join('\r\n') + '\r\n';
+    writeFileSync(path, text, 'utf-8');
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { ConfluenceClient, ConfluenceApiError, type ConfluencePage, type ConfluencePageStorage, type ConfluenceAttachment, type ConfluenceLabel, type AttachmentVersionData, type CreatePageOptions, } from './client/client.js';
+export { authHeader, loadConfigFromEnv, type ConfluenceAuthType, type ConfluenceConfig, type LoadConfigOptions, } from './client/config.js';
+export { Markdown } from './markdown/markdown.js';
+export { renderToStorage, extractPlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, type AttachmentUrls, type ExtractedPlaceholders, } from './markdown/render.js';
+export { validateMarkdown, MarkdownValidationError, type ValidateOptions } from './markdown/validate.js';
+export * from './macros/index.js';
+export { fileSha256, HASH_TAG_PREFIX } from './attachments/hash.js';
+export { Attachment, AttachmentService, toAttachmentVersion, SRC_SHA_SIDECAR_SUFFIX, type AttachmentVersion, type EnsuredAttachment, } from './attachments/attachment.js';
+export { Page, Table } from './pages/page.js';
+export { readTableFromConfluence, findTable, findTableInMacro, parseHtmlTable, decodeHtmlCell, renderMarkdownTable, escapeMdTableCell, readAndMapTable, type ColumnAlign, type TableColumn, } from './pages/tables.js';
+export { publishPage, computeContentHash, DEFAULT_HASH_PROPERTY_KEY, type PublishPageOptions, type PublishPageResult, type TableData, } from './publish/publish.js';
+export { runPublish, type Here, type Build, type PublishPlan, type RunPublishOptions, } from './publish/runner.js';
+export { confluence, ConfluenceWrapper } from './wrapper.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+// Client
+export { ConfluenceClient, ConfluenceApiError, } from './client/client.js';
+export { authHeader, loadConfigFromEnv, } from './client/config.js';
+// Markdown
+export { Markdown } from './markdown/markdown.js';
+export { renderToStorage, extractPlaceholders, MissingAttachmentUrlError, PLACEHOLDER_RE, } from './markdown/render.js';
+export { validateMarkdown, MarkdownValidationError } from './markdown/validate.js';
+// Macros (pluggable)
+export * from './macros/index.js';
+// Attachments
+export { fileSha256, HASH_TAG_PREFIX } from './attachments/hash.js';
+export { Attachment, AttachmentService, toAttachmentVersion, SRC_SHA_SIDECAR_SUFFIX, } from './attachments/attachment.js';
+// Pages & tables
+export { Page, Table } from './pages/page.js';
+export { readTableFromConfluence, findTable, findTableInMacro, parseHtmlTable, decodeHtmlCell, renderMarkdownTable, escapeMdTableCell, readAndMapTable, } from './pages/tables.js';
+// Publish
+export { publishPage, computeContentHash, DEFAULT_HASH_PROPERTY_KEY, } from './publish/publish.js';
+export { runPublish, } from './publish/runner.js';
+// Facade
+export { confluence, ConfluenceWrapper } from './wrapper.js';

package/dist/macros/builder.d.ts

@@ -0,0 +1,30 @@
+import { Markdown } from '../markdown/markdown.js';
+/**
+ * Построитель макроса для использования в markdown.
+ *
+ * @example
+ *   const md = macro('table-excerpt')
+ *     .param('name', 'jira_fact')
+ *     .param('hide', 'true')
+ *     .body(tableMarkdown)
+ *     .toMarkdown();
+ */
+export declare class MacroBuilder {
+    private macroName;
+    private macroParams;
+    private bodyContent;
+    constructor(macroName: string);
+    param(name: string, value: string): this;
+    withParams(obj: Record<string, string | undefined>): this;
+    body(content: Markdown | string): this;
+    toMarkdown(): Markdown;
+}
+/**
+ * Создаёт построитель макроса.
+ *
+ * @example
+ *   macro('table-excerpt').param('name', 'data').body(md).toMarkdown()
+ */
+export declare function macro(name: string): MacroBuilder;
+export declare function escapeParamValue(s: string): string;
+export declare function unescapeParamValue(s: string): string;

package/dist/macros/builder.js

@@ -0,0 +1,58 @@
+import { Markdown } from '../markdown/markdown.js';
+/**
+ * Построитель макроса для использования в markdown.
+ *
+ * @example
+ *   const md = macro('table-excerpt')
+ *     .param('name', 'jira_fact')
+ *     .param('hide', 'true')
+ *     .body(tableMarkdown)
+ *     .toMarkdown();
+ */
+export class MacroBuilder {
+    macroName;
+    macroParams = [];
+    bodyContent = '';
+    constructor(macroName) {
+        this.macroName = macroName;
+    }
+    param(name, value) {
+        this.macroParams.push({ name, value });
+        return this;
+    }
+    withParams(obj) {
+        for (const [k, v] of Object.entries(obj)) {
+            if (v !== undefined)
+                this.param(k, v);
+        }
+        return this;
+    }
+    body(content) {
+        this.bodyContent = content instanceof Markdown ? content.toString() : content;
+        return this;
+    }
+    toMarkdown() {
+        const paramStr = this.macroParams.length > 0
+            ? ':' + this.macroParams.map((p) => `${escapeParamValue(p.name)}=${escapeParamValue(p.value)}`).join(':')
+            : '';
+        const content = `<!-- MACRO:start:${this.macroName}${paramStr} -->\n` +
+            this.bodyContent +
+            `\n<!-- MACRO:end:${this.macroName} -->`;
+        return new Markdown(content);
+    }
+}
+/**
+ * Создаёт построитель макроса.
+ *
+ * @example
+ *   macro('table-excerpt').param('name', 'data').body(md).toMarkdown()
+ */
+export function macro(name) {
+    return new MacroBuilder(name);
+}
+export function escapeParamValue(s) {
+    return s.replace(/[=:]/g, (c) => (c === '=' ? '%3D' : '%3A'));
+}
+export function unescapeParamValue(s) {
+    return s.replace(/%3D/g, '=').replace(/%3A/g, ':');
+}