confluence-cli 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [1.9.0](https://github.com/pchuri/confluence-cli/compare/v1.8.0...v1.9.0) (2025-12-04)
+
+
+### Features
+
+* add attachments list and download command ([#17](https://github.com/pchuri/confluence-cli/issues/17)) ([fb3d4f8](https://github.com/pchuri/confluence-cli/commit/fb3d4f81a3926fec832a39c78f4eda3b4a22130a))
+
+# [1.8.0](https://github.com/pchuri/confluence-cli/compare/v1.7.0...v1.8.0) (2025-09-28)
+
+
+### Features
+
+* make Confluence API path configurable ([#14](https://github.com/pchuri/confluence-cli/issues/14)) ([be000e0](https://github.com/pchuri/confluence-cli/commit/be000e0d92881d65329b84bad6555dcad0bbb455)), closes [#13](https://github.com/pchuri/confluence-cli/issues/13)
+
+## [Unreleased]
+
+### Added
+- Make the Confluence REST base path configurable to support both `/rest/api` and `/wiki/rest/api`.
+
 # [1.7.0](https://github.com/pchuri/confluence-cli/compare/v1.6.0...v1.7.0) (2025-09-28)
 
 

package/README.md

@@ -10,6 +10,7 @@ A powerful command-line interface for Atlassian Confluence that allows you to re
 - 🏠 **List spaces** - View all available Confluence spaces
 - ✏️ **Create pages** - Create new pages with support for Markdown, HTML, or Storage format
 - 📝 **Update pages** - Update existing page content and titles
+- 📎 **Attachments** - List or download page attachments
 - 🛠️ **Edit workflow** - Export page content for editing and re-import
 - 🔧 **Easy setup** - Simple configuration with environment variables or interactive setup
 
@@ -58,18 +59,19 @@ npx confluence-cli
 confluence init
 ```
 
-The wizard now asks for your authentication method. Choose **Basic** to supply your Atlassian email and API token, or switch to **Bearer** when working with self-hosted/Data Center environments.
+The wizard now helps you choose the right API endpoint and authentication method. It recommends `/wiki/rest/api` for Atlassian Cloud domains (e.g., `*.atlassian.net`) and `/rest/api` for self-hosted/Data Center instances, then prompts for Basic (email + token) or Bearer authentication.
 
 ### Option 2: Environment Variables
 ```bash
 export CONFLUENCE_DOMAIN="your-domain.atlassian.net"
 export CONFLUENCE_API_TOKEN="your-api-token"
 export CONFLUENCE_EMAIL="your.email@example.com"  # required when using Atlassian Cloud
+export CONFLUENCE_API_PATH="/wiki/rest/api"         # Cloud default; use /rest/api for Server/DC
 # Optional: set to 'bearer' for self-hosted/Data Center instances
 export CONFLUENCE_AUTH_TYPE="basic"
 ```
 
-`CONFLUENCE_AUTH_TYPE` defaults to `basic` when an email is present and falls back to `bearer` otherwise. Provide an email for Atlassian Cloud (Basic auth) or set `CONFLUENCE_AUTH_TYPE=bearer` to keep bearer-token flows for on-premises installations.
+`CONFLUENCE_API_PATH` defaults to `/wiki/rest/api` for Atlassian Cloud domains and `/rest/api` otherwise. Override it when your site lives under a custom reverse proxy or on-premises path. `CONFLUENCE_AUTH_TYPE` defaults to `basic` when an email is present and falls back to `bearer` otherwise.
 
 ### Getting Your API Token
 
@@ -106,6 +108,18 @@ confluence search "search term"
 confluence search "search term" --limit 5
 ```
 
+### List or Download Attachments
+```bash
+# List all attachments on a page
+confluence attachments 123456789
+
+# Filter by filename and limit the number returned
+confluence attachments 123456789 --pattern "*.png" --limit 5
+
+# Download matching attachments to a directory
+confluence attachments 123456789 --pattern "*.png" --download --dest ./downloads
+```
+
 ### List Spaces
 ```bash
 confluence spaces

package/bin/confluence.js

@@ -337,6 +337,90 @@ program
     }
   });
 
+// Attachments command
+program
+  .command('attachments <pageId>')
+  .description('List or download attachments for a page')
+  .option('-l, --limit <limit>', 'Maximum number of attachments to fetch (default: all)')
+  .option('-p, --pattern <glob>', 'Filter attachments by filename (e.g., "*.png")')
+  .option('-d, --download', 'Download matching attachments')
+  .option('--dest <directory>', 'Directory to save downloads (default: current directory)', '.')
+  .action(async (pageId, options) => {
+    const analytics = new Analytics();
+    try {
+      const config = getConfig();
+      const client = new ConfluenceClient(config);
+      const maxResults = options.limit ? parseInt(options.limit, 10) : null;
+      const pattern = options.pattern ? options.pattern.trim() : null;
+
+      if (options.limit && (Number.isNaN(maxResults) || maxResults <= 0)) {
+        throw new Error('Limit must be a positive number.');
+      }
+
+      const attachments = await client.getAllAttachments(pageId, { maxResults });
+      const filtered = pattern ? attachments.filter(att => client.matchesPattern(att.title, pattern)) : attachments;
+
+      if (filtered.length === 0) {
+        console.log(chalk.yellow('No attachments found.'));
+        analytics.track('attachments', true);
+        return;
+      }
+
+      console.log(chalk.blue(`Found ${filtered.length} attachment${filtered.length === 1 ? '' : 's'}:`));
+      filtered.forEach((att, index) => {
+        const sizeKb = att.fileSize ? `${Math.max(1, Math.round(att.fileSize / 1024))} KB` : 'unknown size';
+        const typeLabel = att.mediaType || 'unknown';
+        console.log(`${index + 1}. ${chalk.green(att.title)} (ID: ${att.id})`);
+        console.log(`   Type: ${chalk.gray(typeLabel)} • Size: ${chalk.gray(sizeKb)} • Version: ${chalk.gray(att.version)}`);
+      });
+
+      if (options.download) {
+        const fs = require('fs');
+        const path = require('path');
+        const destDir = path.resolve(options.dest || '.');
+        fs.mkdirSync(destDir, { recursive: true });
+
+        const uniquePathFor = (dir, filename) => {
+          const parsed = path.parse(filename);
+          let attempt = path.join(dir, filename);
+          let counter = 1;
+          while (fs.existsSync(attempt)) {
+            const suffix = ` (${counter})`;
+            const nextName = `${parsed.name}${suffix}${parsed.ext}`;
+            attempt = path.join(dir, nextName);
+            counter += 1;
+          }
+          return attempt;
+        };
+
+        const writeStream = (stream, targetPath) => new Promise((resolve, reject) => {
+          const writer = fs.createWriteStream(targetPath);
+          stream.pipe(writer);
+          stream.on('error', reject);
+          writer.on('error', reject);
+          writer.on('finish', resolve);
+        });
+
+        let downloaded = 0;
+        for (const attachment of filtered) {
+          const targetPath = uniquePathFor(destDir, attachment.title);
+          const dataStream = await client.downloadAttachment(pageId, attachment.id);
+          await writeStream(dataStream, targetPath);
+          downloaded += 1;
+          console.log(`⬇️  ${chalk.green(attachment.title)} -> ${chalk.gray(targetPath)}`);
+        }
+
+        console.log(chalk.green(`Downloaded ${downloaded} attachment${downloaded === 1 ? '' : 's'} to ${destDir}`));
+      }
+
+      analytics.track('attachments', true);
+    } catch (error) {
+      analytics.track('attachments', false);
+      console.error(chalk.red('Error:'), error.message);
+      process.exit(1);
+    }
+  });
+
 // Copy page tree command
 program
   .command('copy-tree <sourcePageId> <targetParentId> [newTitle]')

package/lib/config.js

@@ -27,6 +27,34 @@ const normalizeAuthType = (rawValue, hasEmail) => {
   return hasEmail ? 'basic' : 'bearer';
 };
 
+const inferApiPath = (domain) => {
+  if (!domain) {
+    return '/rest/api';
+  }
+
+  const normalizedDomain = domain.trim().toLowerCase();
+  if (normalizedDomain.endsWith('.atlassian.net')) {
+    return '/wiki/rest/api';
+  }
+
+  return '/rest/api';
+};
+
+const normalizeApiPath = (rawValue, domain) => {
+  const trimmed = (rawValue || '').trim();
+
+  if (!trimmed) {
+    return inferApiPath(domain);
+  }
+
+  if (!trimmed.startsWith('/')) {
+    throw new Error('Confluence API path must start with "/".');
+  }
+
+  const withoutTrailing = trimmed.replace(/\/+$/, '');
+  return withoutTrailing || inferApiPath(domain);
+};
+
 async function initConfig() {
   console.log(chalk.blue('🚀 Confluence CLI Configuration'));
   console.log('Please provide your Confluence connection details:\n');
@@ -38,6 +66,27 @@ async function initConfig() {
       message: 'Confluence domain (e.g., yourcompany.atlassian.net):',
       validate: requiredInput('Domain')
     },
+    {
+      type: 'input',
+      name: 'apiPath',
+      message: 'REST API path (Cloud: /wiki/rest/api, Server: /rest/api):',
+      default: (responses) => inferApiPath(responses.domain),
+      validate: (input, responses) => {
+        const value = (input || '').trim();
+        if (!value) {
+          return true;
+        }
+        if (!value.startsWith('/')) {
+          return 'API path must start with "/"';
+        }
+        try {
+          normalizeApiPath(value, responses.domain);
+          return true;
+        } catch (error) {
+          return error.message;
+        }
+      }
+    },
     {
       type: 'list',
       name: 'authType',
@@ -66,6 +115,7 @@ async function initConfig() {
 
   const config = {
     domain: answers.domain.trim(),
+    apiPath: normalizeApiPath(answers.apiPath, answers.domain),
     token: answers.token.trim(),
     authType: answers.authType,
     email: answers.authType === 'basic' ? answers.email.trim() : undefined
@@ -83,9 +133,18 @@ function getConfig() {
   const envToken = process.env.CONFLUENCE_API_TOKEN;
   const envEmail = process.env.CONFLUENCE_EMAIL;
   const envAuthType = process.env.CONFLUENCE_AUTH_TYPE;
+  const envApiPath = process.env.CONFLUENCE_API_PATH;
 
   if (envDomain && envToken) {
     const authType = normalizeAuthType(envAuthType, Boolean(envEmail));
+    let apiPath;
+
+    try {
+      apiPath = normalizeApiPath(envApiPath, envDomain);
+    } catch (error) {
+      console.error(chalk.red(`❌ ${error.message}`));
+      process.exit(1);
+    }
 
     if (authType === 'basic' && !envEmail) {
       console.error(chalk.red('❌ Basic authentication requires CONFLUENCE_EMAIL.'));
@@ -95,6 +154,7 @@ function getConfig() {
 
     return {
       domain: envDomain.trim(),
+      apiPath,
       token: envToken.trim(),
       email: envEmail ? envEmail.trim() : undefined,
       authType
@@ -104,7 +164,7 @@ function getConfig() {
   if (!fs.existsSync(CONFIG_FILE)) {
     console.error(chalk.red('❌ No configuration found!'));
     console.log(chalk.yellow('Please run "confluence init" to set up your configuration.'));
-    console.log(chalk.gray('Or set environment variables: CONFLUENCE_DOMAIN, CONFLUENCE_API_TOKEN, and CONFLUENCE_EMAIL.'));
+    console.log(chalk.gray('Or set environment variables: CONFLUENCE_DOMAIN, CONFLUENCE_API_TOKEN, CONFLUENCE_EMAIL, and optionally CONFLUENCE_API_PATH.'));
     process.exit(1);
   }
 
@@ -114,6 +174,7 @@ function getConfig() {
     const trimmedToken = (storedConfig.token || '').trim();
     const trimmedEmail = storedConfig.email ? storedConfig.email.trim() : undefined;
     const authType = normalizeAuthType(storedConfig.authType, Boolean(trimmedEmail));
+    let apiPath;
 
     if (!trimmedDomain || !trimmedToken) {
       console.error(chalk.red('❌ Configuration file is missing required values.'));
@@ -127,8 +188,17 @@ function getConfig() {
       process.exit(1);
     }
 
+    try {
+      apiPath = normalizeApiPath(storedConfig.apiPath, trimmedDomain);
+    } catch (error) {
+      console.error(chalk.red(`❌ ${error.message}`));
+      console.log(chalk.yellow('Please rerun "confluence init" to update your API path.'));
+      process.exit(1);
+    }
+
     return {
       domain: trimmedDomain,
+      apiPath,
       token: trimmedToken,
       email: trimmedEmail,
       authType

package/lib/confluence-client.js

@@ -8,7 +8,8 @@ class ConfluenceClient {
     this.token = config.token;
     this.email = config.email;
     this.authType = (config.authType || (this.email ? 'basic' : 'bearer')).toLowerCase();
-    this.baseURL = `https://${this.domain}/rest/api`;
+    this.apiPath = this.sanitizeApiPath(config.apiPath);
+    this.baseURL = `https://${this.domain}${this.apiPath}`;
     this.markdown = new MarkdownIt();
     this.setupConfluenceMarkdownExtensions();
 
@@ -23,6 +24,19 @@ class ConfluenceClient {
     });
   }
 
+  sanitizeApiPath(rawPath) {
+    const fallback = '/rest/api';
+    const value = (rawPath || '').trim();
+
+    if (!value) {
+      return fallback;
+    }
+
+    const withoutLeading = value.replace(/^\/+/, '');
+    const normalized = `/${withoutLeading}`.replace(/\/+$/, '');
+    return normalized || fallback;
+  }
+
   buildBasicAuthHeader() {
     if (!this.email) {
       throw new Error('Basic authentication requires an email address.');
@@ -153,6 +167,76 @@ class ConfluenceClient {
     }));
   }
 
+  /**
+   * List attachments for a page with pagination support
+   */
+  async listAttachments(pageIdOrUrl, options = {}) {
+    const pageId = this.extractPageId(pageIdOrUrl);
+    const limit = this.parsePositiveInt(options.limit, 50);
+    const start = this.parsePositiveInt(options.start, 0);
+    const params = {
+      limit,
+      start
+    };
+
+    if (options.filename) {
+      params.filename = options.filename;
+    }
+
+    const response = await this.client.get(`/content/${pageId}/child/attachment`, { params });
+    const results = Array.isArray(response.data.results)
+      ? response.data.results.map((item) => this.normalizeAttachment(item))
+      : [];
+
+    return {
+      results,
+      nextStart: this.parseNextStart(response.data?._links?.next)
+    };
+  }
+
+  /**
+   * Fetch all attachments for a page, honoring an optional maxResults cap
+   */
+  async getAllAttachments(pageIdOrUrl, options = {}) {
+    const pageSize = this.parsePositiveInt(options.pageSize || options.limit, 50);
+    const maxResults = this.parsePositiveInt(options.maxResults, null);
+    const filename = options.filename;
+    let start = this.parsePositiveInt(options.start, 0);
+    const attachments = [];
+
+    let hasNext = true;
+    while (hasNext) {
+      const page = await this.listAttachments(pageIdOrUrl, {
+        limit: pageSize,
+        start,
+        filename
+      });
+      attachments.push(...page.results);
+
+      if (maxResults && attachments.length >= maxResults) {
+        return attachments.slice(0, maxResults);
+      }
+
+      hasNext = page.nextStart !== null && page.nextStart !== undefined;
+      if (hasNext) {
+        start = page.nextStart;
+      }
+    }
+
+    return attachments;
+  }
+
+  /**
+   * Download an attachment's data stream
+   */
+  async downloadAttachment(pageIdOrUrl, attachmentId, options = {}) {
+    const pageId = this.extractPageId(pageIdOrUrl);
+    const response = await this.client.get(`/content/${pageId}/child/attachment/${attachmentId}/data`, {
+      responseType: options.responseType || 'stream'
+    });
+    return response.data;
+  }
+
   /**
    * Convert markdown to Confluence storage format
    */
@@ -901,6 +985,65 @@ class ConfluenceClient {
       return this.globToRegExp(pattern).test(title);
     });
   }
+
+  matchesPattern(value, patterns) {
+    if (!patterns) {
+      return true;
+    }
+
+    const list = Array.isArray(patterns) ? patterns.filter(Boolean) : [patterns];
+    if (list.length === 0) {
+      return true;
+    }
+
+    return list.some((pattern) => this.globToRegExp(pattern).test(value));
+  }
+
+  normalizeAttachment(raw) {
+    return {
+      id: raw.id,
+      title: raw.title,
+      mediaType: raw.metadata?.mediaType || raw.type || '',
+      fileSize: raw.extensions?.fileSize || 0,
+      version: raw.version?.number || 1,
+      downloadLink: this.toAbsoluteUrl(raw._links?.download)
+    };
+  }
+
+  toAbsoluteUrl(pathOrUrl) {
+    if (!pathOrUrl) {
+      return null;
+    }
+
+    if (pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://')) {
+      return pathOrUrl;
+    }
+
+    const normalized = pathOrUrl.startsWith('/') ? pathOrUrl : `/${pathOrUrl}`;
+    return `https://${this.domain}${normalized}`;
+  }
+
+  parseNextStart(nextLink) {
+    if (!nextLink) {
+      return null;
+    }
+
+    const match = nextLink.match(/[?&]start=(\d+)/);
+    if (!match) {
+      return null;
+    }
+
+    const value = parseInt(match[1], 10);
+    return Number.isNaN(value) ? null : value;
+  }
+
+  parsePositiveInt(value, fallback) {
+    const parsed = parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed < 0) {
+      return fallback;
+    }
+    return parsed;
+  }
 }
 
 module.exports = ConfluenceClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "confluence-cli",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "A command-line interface for Atlassian Confluence with page creation and editing capabilities",
   "main": "index.js",
   "bin": {
@@ -35,6 +35,12 @@
     "eslint": "^8.55.0",
     "jest": "^29.7.0"
   },
+  "overrides": {
+    "js-yaml": "^4.1.1",
+    "@istanbuljs/load-nyc-config": {
+      "js-yaml": "^3.14.2"
+    }
+  },
   "engines": {
     "node": ">=14.0.0"
   },

package/tests/confluence-client.test.js

@@ -10,6 +10,27 @@ describe('ConfluenceClient', () => {
     });
   });
 
+  describe('api path handling', () => {
+    test('defaults to /rest/api when path is not provided', () => {
+      const defaultClient = new ConfluenceClient({
+        domain: 'example.com',
+        token: 'no-path-token'
+      });
+
+      expect(defaultClient.baseURL).toBe('https://example.com/rest/api');
+    });
+
+    test('normalizes custom api paths', () => {
+      const customClient = new ConfluenceClient({
+        domain: 'cloud.example',
+        token: 'custom-path',
+        apiPath: 'wiki/rest/api/'
+      });
+
+      expect(customClient.baseURL).toBe('https://cloud.example/wiki/rest/api');
+    });
+  });
+
   describe('authentication setup', () => {
     test('uses bearer token headers by default', () => {
       const bearerClient = new ConfluenceClient({
@@ -253,4 +274,26 @@ describe('ConfluenceClient', () => {
       expect(client.shouldExcludePage('production', patterns)).toBe(false);
     });
   });
+
+  describe('attachments', () => {
+    test('should have required methods for attachment handling', () => {
+      expect(typeof client.listAttachments).toBe('function');
+      expect(typeof client.getAllAttachments).toBe('function');
+      expect(typeof client.downloadAttachment).toBe('function');
+    });
+
+    test('matchesPattern should respect glob patterns', () => {
+      expect(client.matchesPattern('report.png', '*.png')).toBe(true);
+      expect(client.matchesPattern('report.png', '*.jpg')).toBe(false);
+      expect(client.matchesPattern('report.png', ['*.jpg', 'report.*'])).toBe(true);
+      expect(client.matchesPattern('report.png', null)).toBe(true);
+      expect(client.matchesPattern('report.png', [])).toBe(true);
+    });
+
+    test('parseNextStart should read start query param when present', () => {
+      expect(client.parseNextStart('/rest/api/content/1/child/attachment?start=25')).toBe(25);
+      expect(client.parseNextStart('/rest/api/content/1/child/attachment?limit=50')).toBeNull();
+      expect(client.parseNextStart(null)).toBeNull();
+    });
+  });
 });