@docsxai/plugin-confluence
docsxai publisher plugin for Confluence Cloud. Registers confluence:push, which takes the engine's ADF projection (docsxai export adf / projectDocPackToAdf) and publishes it to Confluence Cloud, idempotently. Pages, properties and attachment listing use the REST v2 API; attachment upload uses the v1 child/attachment resource, the only upload endpoint Cloud offers.
The engine emits projections only and performs no wiki egress; this plugin is the Confluence egress path, declared in its manifest as egress:*.atlassian.net and gated by the workspace's plugin_capabilities opt-in. All HTTP uses the built-in fetch.
Wiring
Section titled “Wiring”Repo-only.
@docsxai/plugin-confluenceis not published to npm (private: true). Build it from a checkout (pnpm -r build) and wire it by path instead:{ "path": "<checkout>/packages/plugin-confluence" }(relative paths resolve from the workspace directory). The{ "package": ... }form below only resolves once the plugin is installed in the workspace'snode_modules.
.docsxai.json:
{ "plugins": [{ "package": "@docsxai/plugin-confluence" }], "plugin_capabilities": ["egress:*.atlassian.net"]}Secrets come from the environment, never from config: CONFLUENCE_TOKEN (API token) and CONFLUENCE_EMAIL (the Atlassian account the token belongs to). The token is masked as <CONFLUENCE_TOKEN> (raw and Basic-auth-encoded forms) in every error and log line.
Publish config
Section titled “Publish config”Passed as the publisher's config:
| Key | Required | Meaning |
|---|---|---|
base_url | yes | Site origin, e.g. https://acme.atlassian.net. |
space_id | yes | Target space id (v2 numeric id, as a string). |
mode | no | Informational mirror of the projection's mode (single default, page-tree opt-in); the projection drives. |
page_map | no | Page identity: { section → pageId }. Sections present here are updated in place; absent ones created. |
parent_page_id | no | Existing page to nest under (the single page, or the page-tree parent). |
title_prefix | no | Prepended to every page title, e.g. "[Docs] ". |
The result's pages[] entries each carry section, id, url, and action (created / updated / unchanged). Merge { [section]: id } over your stored page_map to persist identity for the next publish.
Projection sections: single mode publishes one consolidated page (section project, flows as anchored H2 sections). page-tree mode publishes a parent overview (section project) plus one child page per flow (section = flow name).
Idempotency
Section titled “Idempotency”Every published page carries a docsxai-content-sha content-property: the sha256 of the page's projected content (title + ADF + attachment shas). On publish:
- property matches →
unchanged, zero HTTP mutations (no version bump, no uploads); - property differs → attachments whose same-name remote copy carries a matching
docsxai-sha256:<hex>comment are skipped, the rest re-uploaded; then exactly one version-bump page update and a property bump; - no
page_mapentry → page created, attachments uploaded, media nodes patched with the uploaded file ids, property set.
Caveats
Section titled “Caveats”- Attachment upload posts multipart (
file,comment=docsxai-sha256:<hex>,minorEdit=true, headerX-Atlassian-Token: no-check) toPOST /wiki/rest/api/content/{pageId}/child/attachment. The v2 attachments resource is read-only on Cloud (a POST answers 405), so v2 is only used to list existing attachments. Replacing an attachment of the same name posts to…/child/attachment/{attachmentId}/data, because v1 refuses a second attachment with the same file name. The media file id patched into the page body isextensions.fileIdfrom the upload response. - A failed publish throws a
ConfluencePublishErrorwhosepartial.pageslists the pages written before the failure (same shape aspages[]:id,url,action,section), and logs them as apage_mapfragment. If a page was created and an upload then failed, merge{ [section]: id }intopage_mapand publish again: the retry finds the page without itsdocsxai-content-shaproperty, updates it in place (uploading only the missing attachments) and creates no duplicate. - The plugin is in-process and unsandboxed, like every docsxai plugin:
trust: "<publisher>"is a review signal, not a boundary.
pnpm test (after pnpm -r build, since the runtime-load test resolves the built package through the engine's real resolvePlugins). The suite runs an in-process fake Confluence server on loopback (v2 attachment POST answers 405, uploads go to v1 child/attachment) that counts mutations: same projection published 3× → run 1 creates, runs 2 and 3 all unchanged with zero mutations; a prose change → exactly one page update; an upload failure after page creation leaves a retryable page_map; token-masking asserted against an error body that echoes the credential.