feat: add Confluence page attachment commands (list, download, upload) (#35)

Hinne1 · web-flow · commit 5903ac855118 · 2026-03-10T05:41:36.000+01:00
* feat: add Confluence attachment structs and list API methods

Add ConfluenceAttachment, AttachmentVersion, and ConfluenceAttachmentsResponse
structs plus GetPageAttachments, GetPageAttachmentsAll, and GetConfluenceAttachment
methods to ConfluenceService, following existing pagination patterns.

* feat: add Confluence attachment download and upload API methods

Add DownloadConfluenceAttachment (via GetRaw) and UploadConfluenceAttachment
(via v1 POST multipart) with supporting response structs.

* feat: add Confluence page attachment command

Add the `atl confluence page attachment` command supporting list,
download, download-all, and upload operations for Confluence page
attachments. Register the new subcommand in the page command group.

* docs: add Confluence page attachment examples to AGENTS.md and README.md

* fix: address Gemini review findings

- Sanitize attachment filenames with filepath.Base() to prevent path traversal
- Use API-reported file size instead of len(content) in download outputs
- Show upload summary on single-file upload when there are errors
diff --git a/AGENTS.md b/AGENTS.md
@@ -186,6 +186,18 @@ atl confluence template create --space DOCS --name "Name" --body "<html>"
 atl confluence template update <id> --body "<html>"
 ```
 
+### Attachments
+
+```bash
+atl confluence page attachment <id> --list               # List attachments
+atl confluence page attachment <id> --list --json        # List as JSON
+atl confluence page attachment <id> --download --id <attID>  # Download specific
+atl confluence page attachment <id> --download-all       # Download all
+atl confluence page attachment <id> --download-all -o ./dir  # Download to directory
+atl confluence page attachment <id> --upload ./file.pdf  # Upload file
+atl confluence page attachment <id> --upload a.pdf --upload b.png  # Upload multiple
+```
+
 ## Formatting Guidelines
 
 ### Jira Formatting (Markdown to ADF)
diff --git a/README.md b/README.md
@@ -242,6 +242,14 @@ atl confluence page archive <id> --unarchive     # Restore archived page
 atl confluence page move <id> --target <parent-id>           # Move as child of target
 atl confluence page move <id> --target <sibling-id> --position before  # Move before sibling
 atl confluence page move <id> --space NEWSPACE               # Move to different space
+
+atl confluence page attachment <id> --list               # List attachments
+atl confluence page attachment <id> --list --json        # List as JSON
+atl confluence page attachment <id> --download --id <attID>  # Download specific
+atl confluence page attachment <id> --download-all       # Download all
+atl confluence page attachment <id> --download-all -o ./dir  # Download to directory
+atl confluence page attachment <id> --upload ./file.pdf  # Upload file
+atl confluence page attachment <id> --upload a.pdf --upload b.png  # Upload multiple
 ```
 
 ### Configuration
diff --git a/internal/api/confluence.go b/internal/api/confluence.go
@@ -885,3 +885,128 @@ func (s *ConfluenceService) UpdateTemplate(ctx context.Context, templateID, name
 
 	return &template, nil
 }
+
+// ConfluenceAttachment represents a file attachment on a Confluence page.
+type ConfluenceAttachment struct {
+	ID           string             `json:"id"`
+	Title        string             `json:"title"`
+	MediaType    string             `json:"mediaType"`
+	FileSize     int64              `json:"fileSize"`
+	Status       string             `json:"status"`
+	Version      *AttachmentVersion `json:"version,omitempty"`
+	DownloadLink string             `json:"downloadLink,omitempty"`
+}
+
+// AttachmentVersion represents version info for an attachment.
+type AttachmentVersion struct {
+	Number    int    `json:"number"`
+	CreatedAt string `json:"createdAt,omitempty"`
+	AuthorID  string `json:"authorId,omitempty"`
+}
+
+// ConfluenceAttachmentsResponse represents a paginated list of attachments.
+type ConfluenceAttachmentsResponse struct {
+	Results []*ConfluenceAttachment `json:"results"`
+	Links   *PaginationLinks        `json:"_links,omitempty"`
+}
+
+// GetPageAttachments lists attachments on a Confluence page.
+// Uses v2 API: GET /pages/{pageID}/attachments
+func (s *ConfluenceService) GetPageAttachments(ctx context.Context, pageID string, limit int, cursor string) (*ConfluenceAttachmentsResponse, error) {
+	path := fmt.Sprintf("%s/pages/%s/attachments", s.baseURL(), pageID)
+
+	params := url.Values{}
+	if limit > 0 {
+		params.Set("limit", strconv.Itoa(capLimit(limit, ConfluenceMaxLimit)))
+	}
+	if cursor != "" {
+		params.Set("cursor", cursor)
+	}
+
+	var result ConfluenceAttachmentsResponse
+	if err := s.client.Get(ctx, path+"?"+params.Encode(), &result); err != nil {
+		return nil, err
+	}
+
+	return &result, nil
+}
+
+// GetPageAttachmentsAll lists all attachments on a page by following pagination.
+func (s *ConfluenceService) GetPageAttachmentsAll(ctx context.Context, pageID string) ([]*ConfluenceAttachment, error) {
+	var all []*ConfluenceAttachment
+	cursor := ""
+
+	for {
+		result, err := s.GetPageAttachments(ctx, pageID, 100, cursor)
+		if err != nil {
+			return nil, err
+		}
+		all = append(all, result.Results...)
+
+		if result.Links == nil || result.Links.Next == "" {
+			break
+		}
+		cursor = extractCursor(result.Links.Next)
+		if cursor == "" {
+			break
+		}
+	}
+
+	return all, nil
+}
+
+// GetConfluenceAttachment gets a single attachment by ID.
+// Uses v2 API: GET /attachments/{id}
+func (s *ConfluenceService) GetConfluenceAttachment(ctx context.Context, attachmentID string) (*ConfluenceAttachment, error) {
+	path := fmt.Sprintf("%s/attachments/%s", s.baseURL(), attachmentID)
+
+	var attachment ConfluenceAttachment
+	if err := s.client.Get(ctx, path, &attachment); err != nil {
+		return nil, err
+	}
+
+	return &attachment, nil
+}
+
+// DownloadConfluenceAttachment downloads an attachment's content.
+// downloadLink is the relative link from the attachment's downloadLink field.
+// The full URL is constructed by prepending the Confluence site base.
+func (s *ConfluenceService) DownloadConfluenceAttachment(ctx context.Context, downloadLink string) ([]byte, string, error) {
+	// downloadLink is relative (e.g. "/download/attachments/123/file.pdf")
+	// Construct full URL via the Confluence site
+	fullURL := fmt.Sprintf("%s/ex/confluence/%s/wiki%s", AtlassianAPIURL, s.client.CloudID(), downloadLink)
+	return s.client.GetRaw(ctx, fullURL)
+}
+
+// UploadConfluenceAttachment uploads a file as an attachment to a Confluence page.
+// Uses v1 API: POST /content/{pageID}/child/attachment
+func (s *ConfluenceService) UploadConfluenceAttachment(ctx context.Context, pageID, filePath string) (*ConfluenceUploadResponse, error) {
+	path := fmt.Sprintf("%s/content/%s/child/attachment", s.baseURLV1(), pageID)
+
+	var result ConfluenceUploadResponse
+	if err := s.client.PostMultipart(ctx, path, "file", filePath, &result); err != nil {
+		return nil, err
+	}
+
+	return &result, nil
+}
+
+// ConfluenceUploadResponse represents the v1 response when uploading attachments.
+type ConfluenceUploadResponse struct {
+	Results []*ConfluenceUploadResult `json:"results"`
+}
+
+// ConfluenceUploadResult represents a single uploaded attachment in the v1 response.
+type ConfluenceUploadResult struct {
+	ID         string                    `json:"id"`
+	Title      string                    `json:"title"`
+	MediaType  string                    `json:"mediaType,omitempty"`
+	FileSize   int64                     `json:"fileSize,omitempty"`
+	Extensions *ConfluenceUploadMetadata `json:"extensions,omitempty"`
+}
+
+// ConfluenceUploadMetadata holds metadata from the v1 upload response.
+type ConfluenceUploadMetadata struct {
+	MediaType string `json:"mediaType,omitempty"`
+	FileSize  int64  `json:"fileSize,omitempty"`
+}
diff --git a/internal/api/confluence_test.go b/internal/api/confluence_test.go
@@ -349,6 +349,120 @@ func TestSpaceDescription(t *testing.T) {
 	}
 }
 
+// TestConfluenceAttachmentStructure tests the ConfluenceAttachment JSON serialization.
+func TestConfluenceAttachmentStructure(t *testing.T) {
+	att := &ConfluenceAttachment{
+		ID:        "att123",
+		Title:     "screenshot.png",
+		MediaType: "image/png",
+		FileSize:  12345,
+		Status:    "current",
+		Version: &AttachmentVersion{
+			Number:    1,
+			CreatedAt: "2026-01-15T10:00:00.000Z",
+		},
+		DownloadLink: "/download/attachments/456/screenshot.png",
+	}
+
+	data, err := json.Marshal(att)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+
+	var decoded ConfluenceAttachment
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+
+	if decoded.ID != "att123" {
+		t.Errorf("ID = %q, want %q", decoded.ID, "att123")
+	}
+	if decoded.Title != "screenshot.png" {
+		t.Errorf("Title = %q, want %q", decoded.Title, "screenshot.png")
+	}
+	if decoded.FileSize != 12345 {
+		t.Errorf("FileSize = %d, want 12345", decoded.FileSize)
+	}
+	if decoded.DownloadLink != "/download/attachments/456/screenshot.png" {
+		t.Errorf("DownloadLink = %q, want %q", decoded.DownloadLink, "/download/attachments/456/screenshot.png")
+	}
+}
+
+// TestGetPageAttachments tests listing attachments on a page.
+func TestGetPageAttachments(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodGet {
+			t.Errorf("Method = %s, want GET", r.Method)
+		}
+
+		response := ConfluenceAttachmentsResponse{
+			Results: []*ConfluenceAttachment{
+				{ID: "att1", Title: "file1.pdf", MediaType: "application/pdf", FileSize: 1000},
+				{ID: "att2", Title: "file2.png", MediaType: "image/png", FileSize: 2000},
+			},
+			Links: &PaginationLinks{},
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(response)
+	}))
+	defer server.Close()
+
+	client := &Client{
+		httpClient: server.Client(),
+		cloudID:    "test-cloud",
+		tokens: &auth.TokenSet{
+			AccessToken: "test-token",
+			ExpiresAt:   time.Now().Add(time.Hour),
+		},
+	}
+
+	ctx := context.Background()
+	var result ConfluenceAttachmentsResponse
+	err := client.Get(ctx, server.URL, &result)
+
+	if err != nil {
+		t.Fatalf("error = %v", err)
+	}
+	if len(result.Results) != 2 {
+		t.Errorf("got %d attachments, want 2", len(result.Results))
+	}
+	if result.Results[0].Title != "file1.pdf" {
+		t.Errorf("first attachment title = %q, want %q", result.Results[0].Title, "file1.pdf")
+	}
+}
+
+// TestConfluenceUploadResponseStructure tests the upload response JSON serialization.
+func TestConfluenceUploadResponseStructure(t *testing.T) {
+	jsonData := `{"results": [{"id": "att100", "title": "report.pdf", "extensions": {"mediaType": "application/pdf", "fileSize": 54321}}]}`
+
+	var response ConfluenceUploadResponse
+	if err := json.Unmarshal([]byte(jsonData), &response); err != nil {
+		t.Fatalf("json.Unmarshal() error = %v", err)
+	}
+
+	if len(response.Results) != 1 {
+		t.Fatalf("Results count = %d, want 1", len(response.Results))
+	}
+
+	r := response.Results[0]
+	if r.ID != "att100" {
+		t.Errorf("ID = %q, want %q", r.ID, "att100")
+	}
+	if r.Title != "report.pdf" {
+		t.Errorf("Title = %q, want %q", r.Title, "report.pdf")
+	}
+	if r.Extensions == nil {
+		t.Fatal("Extensions is nil")
+	}
+	if r.Extensions.MediaType != "application/pdf" {
+		t.Errorf("Extensions.MediaType = %q, want %q", r.Extensions.MediaType, "application/pdf")
+	}
+	if r.Extensions.FileSize != 54321 {
+		t.Errorf("Extensions.FileSize = %d, want 54321", r.Extensions.FileSize)
+	}
+}
+
 // TestPageBodyFormats tests the PageBody structure with different formats.
 func TestPageBodyFormats(t *testing.T) {
 	body := &PageBody{
@@ -369,3 +483,33 @@ func TestPageBodyFormats(t *testing.T) {
 		t.Errorf("PageBody.View.Representation = %q, want %q", body.View.Representation, "view")
 	}
 }
+
+// TestDownloadConfluenceAttachment tests downloading attachment content.
+func TestDownloadConfluenceAttachment(t *testing.T) {
+	fileContent := []byte("file content here")
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/pdf")
+		w.Write(fileContent)
+	}))
+	defer server.Close()
+
+	client := &Client{
+		httpClient: server.Client(),
+		cloudID:    "test-cloud",
+		tokens: &auth.TokenSet{
+			AccessToken: "test-token",
+			ExpiresAt:   time.Now().Add(time.Hour),
+		},
+	}
+
+	content, contentType, err := client.GetRaw(context.Background(), server.URL)
+	if err != nil {
+		t.Fatalf("error = %v", err)
+	}
+	if string(content) != "file content here" {
+		t.Errorf("content = %q, want %q", string(content), "file content here")
+	}
+	if contentType != "application/pdf" {
+		t.Errorf("contentType = %q, want %q", contentType, "application/pdf")
+	}
+}
diff --git a/internal/cmd/confluence/page/attachment.go b/internal/cmd/confluence/page/attachment.go
diff --git a/internal/cmd/confluence/page/page.go b/internal/cmd/confluence/page/page.go
