[Feature]: Confluence versions support

[stropho]

Package

markdown-confluence-sync

Description

Hello everyone,
thanks for the effort. The features regarding the conversion markdown to confluence pages are great.
I've been trying it out for the last couple of days, and unfortunately I cannot use it as is. The main painful point is that some of the deprecated endpoints in use are not available in Atlassian Cloud anymore - namely ${this._config.url}/rest/api/content/${parentId}/child -

confluence-tools/components/confluence-sync/src/confluence/CustomConfluenceClient.ts

Line 61 in e0516d5

`${this._config.url}/rest/api/content/${parentId}/child`,

After a few tweaks, I made it work 🎉

diff --git a/node_modules/@telefonica/confluence-sync/dist/confluence/CustomConfluenceClient.js b/node_modules/@telefonica/confluence-sync/dist/confluence/CustomConfluenceClient.js
index a03b8f3..bb99509 100644
--- a/node_modules/@telefonica/confluence-sync/dist/confluence/CustomConfluenceClient.js
+++ b/node_modules/@telefonica/confluence-sync/dist/confluence/CustomConfluenceClient.js
@@ -16,6 +16,7 @@ const DeletePageError_1 = require("./errors/DeletePageError");
 const PageNotFoundError_1 = require("./errors/PageNotFoundError");
 const UpdatePageError_1 = require("./errors/UpdatePageError");
 const GET_CHILDREN_LIMIT = 100;
+const apiPrefix = "";
 const CustomConfluenceClient = class CustomConfluenceClient {
     _config;
     _client;
@@ -25,9 +26,12 @@ const CustomConfluenceClient = class CustomConfluenceClient {
         this._client = new confluence_js_1.ConfluenceClient({
             host: config.url,
             authentication: {
-                personalAccessToken: config.personalAccessToken,
+                basic: {
+                    email: 'email@example.com',
+                    apiToken: 'token...',
+                }
             },
-            apiPrefix: "/rest/",
+            apiPrefix,
         });
         this._logger = config.logger;
     }
@@ -38,7 +42,8 @@ const CustomConfluenceClient = class CustomConfluenceClient {
     async _getChildPages(parentId, start = 0, otherChildren = []) {
         try {
             this._logger.silly(`Getting child pages of parent with id ${parentId}`);
-            const response = await axios_1.default.get(`${this._config.url}/rest/api/content/${parentId}/child`, {
+            // const response = await axios_1.default.get(`${this._config.url}/rest/api/content/${parentId}/child`, {
+            const response = await axios_1.default.get(`${this._config.url}/${apiPrefix ? apiPrefix + '/' : ''}wiki/api/v2/pages/${parentId}/descendants`, {
                 params: {
                     start,
                     limit: GET_CHILDREN_LIMIT,
@@ -46,11 +51,11 @@ const CustomConfluenceClient = class CustomConfluenceClient {
                 },
                 headers: {
                     accept: "application/json",
-                    Authorization: `Bearer ${this._config.personalAccessToken}`,
+                    Authorization: `Basic BASE64encoded-name-and-token`,
                 },
             });
             this._logger.silly(`Get child pages response of page ${parentId}, starting at ${start}: ${JSON.stringify(response.data, null, 2)}`);
-            const childrenResults = response.data.page?.results || [];
+            const childrenResults = response.data.results || [];
             const size = response.data.page?.size || 0;
             const allChildren = [
                 ...otherChildren,

Suggested Solution

So now I'm thinking how to make some changes, so it's easy enough to do, and maybe improve the code for better maintenance. Let's discuss some options. It would be great to possibly use some parts of the confluence-tools with more confluence versions.

Option 1 - Separate markdown-to-confluence-content

The easiest option I can think of is to have a standalone package to convert markdown to the content to be uploaded (html, images,..). Possibly with the ability to add more rehype and reflow transforms...

Pros:

• anybody can generate the content, and upload it on his/her own.

Cons:

• confluence-sync logic cannot be reused as it uses irrelevant (based on confluence version) REST endpoints

Option 2 - Endpoints Provider

Another approach could be to introduce an Endpoints Provider abstraction. This would allow the core logic to remain the same, but the actual REST endpoints used could be swapped (~injected) by the user depending on the Confluence version and the endpoints available. As long as there is a clearly defined interface, this could work nicely.

Example

getConfluenceConnector = () => {
  return {
    getDescendantPages: (params) => {/* ... */}
    updatePage: (params) => {/* ... */}
    // ...
    // attachments ...
  }
}

Pros:

• support for multiple Confluence versions without duplicating logic.
• user can define such logic on their own
• possible to use additional authentication mechanisms.
• confluence-sync could still be used

Cons:

• probably not straight forward to add such configuration to text based configs like yaml or json.

Option 3 - More Configuration Options

..to support multiple confluence version..
No. That just crossed my mind. It's a nightmare to have too many configuration options. Both UX and maintenance.

---

Feel free to add more ideas to the discussions. I'm willing to contribute with some PRs.
Once again, great tools you have here :-)

Code of Conduct

• I agree to follow this project's Code of Conduct

[javierbrea]

Hi @stropho , and thanks a lot for your kind words about the library 🙏
Also, apologies for the late reply, and thanks for taking the time not only to open the issue but also to investigate and share your workaround.

Just to clarify: the synchronization logic with Confluence is already separated in a different package (confluence-sync). What you modified in your patch is indeed not part of markdown-confluence-sync itself, but rather confluence-sync, which is a standalone component inside this monorepo and also published separately to NPM.

That means one possible option could be to allow instantiating markdown-confluence-sync programmatically by passing a different synchronization class/constructor. As long as it implements the same interface than confluence-sync, this would make it possible to plug in an alternative implementation that talks to other Confluence versions (e.g. Cloud v2 APIs).

Regarding the change in the authentication headers: there’s already another issue about that (#56) and we’ll work on addressing it soon.

As for adding support for multiple Confluence versions through different connectors, contributions are more than welcome! 🙌 In the documentation you can already see how to use the library programmatically. I believe a reasonable path would be to allow passing a custom class compatible with confluence-sync. Potentially this could even be configurable when using a JS object as config.

Here’s the current programmatic usage example from the docs, with a highlighted line showing where a custom sync implementation could be injected:

import path from "path";
import { MarkdownConfluenceSync } from "@telefonica/markdown-confluence-sync";

const markdownConfluenceSync = new MarkdownConfluenceSync({
  docsDir: path.resolve(__dirname, "..", "docs"),
  confluence: {
    url: "https://my.confluence.es",
    personalAccessToken: "*******",
    // customSync: new MyCloudV2ConfluenceSync(...)   <-- for example
  },
});

await markdownConfluenceSync.sync();

So the idea would be to make that customSync (or similar) officially supported, and you could provide your own implementation.

If you’re interested in contributing with a first draft of such an alternative connector, that would be greatly appreciated 🚀

[javierbrea]

Hi again @stropho,

Yesterday, we published v2.2.0, which upgrades the confluence.js dependency to version 2.1.0. This update brings support for additional authentication methods and, importantly, allows us to remove the previous workaround for fetching child pages—confluence.js now provides native pagination support, and we rely directly on their method.

These changes may address the compatibility problems you were experiencing. When you have the chance, please update to v2.2.0 and let us know if it resolves your issue. Your feedback will help us confirm the fix or guide any further improvements.

Thanks again for your help and patience!

[stropho]

Hi, thanks for the update. I quickly tried to update the tool, change authentication, and unfortunatelly it didn't work. But it looks like this is on my end - the confluence client cannot find the requested root page, although it worked before with my patch. Sorry, the time is very limited now. I'll keep you posted 🔢

[javierbrea]

Sorry to hear you're experiencing issues @stropho . We haven't encountered any problems with the new version on our end. When you have time, could you please provide us with more details? Any additional information would help us assist you better.

[stropho]

Cool, I've manage to have look one more time this week 😸 The good news is that in my/our case, there is no need for a custom client 🎉 🎉 🎉
The new ways for authentication make eveything easier.
The only thing I need is an option to set a custom apiPrefix - empty for my case.
And that should imho be fairly easy to do
https://github.com/Telefonica/confluence-tools/blob/confluence-sync-v2.1.0/components/confluence-sync/src/confluence/CustomConfluenceClient.ts#L120

As the project is fairly large, any pointers will be appreciated. I'd say adding a default value (the current /rest/) somewhere around here https://github.com/Telefonica/confluence-tools/blob/markdown-confluence-sync-v2.2.0/components/markdown-confluence-sync/src/lib/confluence/ConfluenceSync.ts#L126 would make sense.

[javierbrea]

Thanks a lot for offering! You're on the right track, but, unfortunately, exposing new options in the configuration is a bit “tricky” for a first contribution, as it needs some specific typings and needs to be done across two packages (confluence-sync and markdown-confluence-sync). Also, it would be good to update the repository containing the GitHub Action to include the new option.

So no worries—I’ll take care of it myself, and it shouldn’t take too long. Of course, if you feel like giving it a go, we’d be more than happy to receive a PR! Otherwise, I’ll get to it as soon as possible.

Thanks again for your help!

[stropho]

Thanks a lot @javierbrea , I'll leave this one for you - so I can get some inspiration how it should be done. I plan to do some customisation options for remark and rehype transformers later :)