api

package
v0.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 16, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package api provides a client for the Confluence REST API.

Package api provides the Confluence Cloud REST API client.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Attachment

type Attachment struct {
	ID                   string   `json:"id"`
	Status               string   `json:"status"`
	Title                string   `json:"title"`
	MediaType            string   `json:"mediaType"`
	MediaTypeDescription string   `json:"mediaTypeDescription,omitempty"`
	Comment              string   `json:"comment,omitempty"`
	FileSize             int64    `json:"fileSize"`
	WebuiLink            string   `json:"webuiLink,omitempty"`
	DownloadLink         string   `json:"downloadLink,omitempty"`
	Version              *Version `json:"version,omitempty"`
	Links                Links    `json:"_links,omitempty"`
}

Attachment represents a file attachment.

type Body

type Body struct {
	Storage        *BodyRepresentation `json:"storage,omitempty"`
	AtlasDocFormat *BodyRepresentation `json:"atlas_doc_format,omitempty"`
	View           *BodyRepresentation `json:"view,omitempty"`
}

Body contains page content in various representations.

type BodyRepresentation

type BodyRepresentation struct {
	Representation string `json:"representation"`
	Value          string `json:"value"`
}

BodyRepresentation holds content in a specific format.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the Confluence Cloud API client.

func NewClient

func NewClient(baseURL, email, apiToken string) *Client

NewClient creates a new Confluence API client.

func (*Client) CopyPage

func (c *Client) CopyPage(ctx context.Context, pageID string, opts *CopyPageOptions) (*Page, error)

CopyPage duplicates a page with a new title. Uses the v1 REST API: POST /rest/api/content/{id}/copy

Note: Callers must explicitly set all copy flags. If not set, they default to false (Go zero value). The command layer handles default-to-true semantics via --no-* flags.

func (*Client) CreatePage

func (c *Client) CreatePage(ctx context.Context, req *CreatePageRequest) (*Page, error)

CreatePage creates a new page.

func (*Client) Delete

func (c *Client) Delete(ctx context.Context, path string) ([]byte, error)

Delete performs a DELETE request.

func (*Client) DeleteAttachment

func (c *Client) DeleteAttachment(ctx context.Context, attachmentID string) error

DeleteAttachment deletes an attachment by ID.

func (*Client) DeletePage

func (c *Client) DeletePage(ctx context.Context, pageID string) error

DeletePage deletes a page.

func (*Client) DownloadAttachment

func (c *Client) DownloadAttachment(ctx context.Context, attachmentID string) (io.ReadCloser, error)

DownloadAttachment downloads an attachment and returns a reader.

func (*Client) Get

func (c *Client) Get(ctx context.Context, path string) ([]byte, error)

Get performs a GET request.

func (*Client) GetAttachment

func (c *Client) GetAttachment(ctx context.Context, attachmentID string) (*Attachment, error)

GetAttachment returns a single attachment by ID.

func (*Client) GetPage

func (c *Client) GetPage(ctx context.Context, pageID string, opts *GetPageOptions) (*Page, error)

GetPage returns a single page by ID.

func (*Client) GetSpace

func (c *Client) GetSpace(ctx context.Context, spaceID string) (*Space, error)

GetSpace returns a single space by ID.

func (*Client) GetSpaceByKey

func (c *Client) GetSpaceByKey(ctx context.Context, key string) (*Space, error)

GetSpaceByKey returns a space by its key.

func (*Client) ListAttachments

func (c *Client) ListAttachments(ctx context.Context, pageID string, opts *ListAttachmentsOptions) (*PaginatedResponse[Attachment], error)

ListAttachments returns attachments for a page.

func (*Client) ListPages

func (c *Client) ListPages(ctx context.Context, spaceID string, opts *ListPagesOptions) (*PaginatedResponse[Page], error)

ListPages returns a list of pages in a space.

func (*Client) ListSpaces

func (c *Client) ListSpaces(ctx context.Context, opts *ListSpacesOptions) (*PaginatedResponse[Space], error)

ListSpaces returns a list of spaces.

func (*Client) MovePage

func (c *Client) MovePage(ctx context.Context, pageID, targetParentID string) error

MovePage moves a page to be a child of the target parent page. Uses the v1 REST API as v2 doesn't support page moves.

func (*Client) Post

func (c *Client) Post(ctx context.Context, path string, body interface{}) ([]byte, error)

Post performs a POST request.

func (*Client) Put

func (c *Client) Put(ctx context.Context, path string, body interface{}) ([]byte, error)

Put performs a PUT request.

func (*Client) Search

func (c *Client) Search(ctx context.Context, opts *SearchOptions) (*SearchResponse, error)

Search performs a Confluence search using CQL. Uses the v1 REST API: GET /rest/api/search

func (*Client) UpdatePage

func (c *Client) UpdatePage(ctx context.Context, pageID string, req *UpdatePageRequest) (*Page, error)

UpdatePage updates an existing page.

func (*Client) UploadAttachment

func (c *Client) UploadAttachment(ctx context.Context, pageID, filename string, content io.Reader, comment string) (*Attachment, error)

UploadAttachment uploads a file as an attachment to a page. Note: This uses the v1 API as v2 doesn't support uploads yet.

type CopyPageOptions

type CopyPageOptions struct {
	Title              string // Required: new page title
	DestinationSpace   string // Optional: target space key (defaults to same space)
	CopyAttachments    bool   // Default: true
	CopyPermissions    bool   // Default: true
	CopyProperties     bool   // Default: true
	CopyLabels         bool   // Default: true
	CopyCustomContents bool   // Default: true
}

CopyPageOptions configures page copy behavior.

type CreatePageRequest

type CreatePageRequest struct {
	SpaceID  string `json:"spaceId"`
	Status   string `json:"status,omitempty"`
	Title    string `json:"title"`
	ParentID string `json:"parentId,omitempty"`
	Body     *Body  `json:"body"`
}

CreatePageRequest is the request body for creating a page.

type DescriptionValue

type DescriptionValue struct {
	Value string `json:"value"`
}

DescriptionValue holds the actual description text.

type ErrorResponse

type ErrorResponse struct {
	StatusCode int      `json:"statusCode"`
	Message    string   `json:"message"`
	Errors     []string `json:"errors,omitempty"`
}

ErrorResponse represents an API error.

func (*ErrorResponse) Error

func (e *ErrorResponse) Error() string

type GetPageOptions

type GetPageOptions struct {
	BodyFormat string // storage, atlas_doc_format, view
}

GetPageOptions contains options for getting a page.

type Links struct {
	Next   string `json:"next,omitempty"`
	Base   string `json:"base,omitempty"`
	WebUI  string `json:"webui,omitempty"`
	EditUI string `json:"editui,omitempty"`
}

Links contains pagination and navigation links.

type ListAttachmentsOptions

type ListAttachmentsOptions struct {
	Limit     int
	Cursor    string
	MediaType string
	Filename  string
}

ListAttachmentsOptions contains options for listing attachments.

type ListPagesOptions

type ListPagesOptions struct {
	Limit      int
	Cursor     string
	Status     string // current, archived, trashed, deleted
	Sort       string // title, -title, created-date, -created-date, modified-date, -modified-date
	Title      string // Filter by title (contains)
	BodyFormat string // storage, atlas_doc_format, view
}

ListPagesOptions contains options for listing pages.

type ListSpacesOptions

type ListSpacesOptions struct {
	Limit  int
	Cursor string
	Type   string   // global, personal
	Status string   // current, archived
	Keys   []string // Filter by space keys
}

ListSpacesOptions contains options for listing spaces.

type Page

type Page struct {
	ID         string   `json:"id"`
	Status     string   `json:"status"`
	Title      string   `json:"title"`
	SpaceID    string   `json:"spaceId"`
	ParentID   string   `json:"parentId,omitempty"`
	ParentType string   `json:"parentType,omitempty"`
	Position   int      `json:"position,omitempty"`
	AuthorID   string   `json:"authorId,omitempty"`
	OwnerID    string   `json:"ownerId,omitempty"`
	CreatedAt  Time     `json:"createdAt,omitempty"`
	Version    *Version `json:"version,omitempty"`
	Body       *Body    `json:"body,omitempty"`
	Links      Links    `json:"_links,omitempty"`
}

Page represents a Confluence page.

type PaginatedResponse

type PaginatedResponse[T any] struct {
	Results []T   `json:"results"`
	Links   Links `json:"_links,omitempty"`
}

PaginatedResponse wraps paginated API responses.

func (*PaginatedResponse[T]) HasMore

func (p *PaginatedResponse[T]) HasMore() bool

HasMore returns true if there are more results available.

type SearchContainer

type SearchContainer struct {
	Title      string `json:"title"`
	DisplayURL string `json:"displayUrl"`
}

SearchContainer represents the space/container of a search result.

type SearchContent

type SearchContent struct {
	ID     string `json:"id"`
	Type   string `json:"type"`
	Status string `json:"status"`
	Title  string `json:"title"`
}

SearchContent contains the content details in a search result.

type SearchOptions

type SearchOptions struct {
	CQL   string // Raw CQL query (takes precedence if set)
	Text  string // Full-text search term
	Space string // Space key to filter results
	Type  string // Content type: page, blogpost, attachment, comment
	Title string // Title contains filter
	Label string // Label filter
	Limit int    // Max results (default 25, max 200)
}

SearchOptions contains options for searching Confluence content.

type SearchResponse

type SearchResponse struct {
	Results        []SearchResult `json:"results"`
	Start          int            `json:"start"`
	Limit          int            `json:"limit"`
	Size           int            `json:"size"`
	TotalSize      int            `json:"totalSize"`
	CQLQuery       string         `json:"cqlQuery"`
	SearchDuration int            `json:"searchDuration"`
}

SearchResponse represents the v1 search API response.

func (*SearchResponse) HasMore

func (r *SearchResponse) HasMore() bool

HasMore returns true if there are more results available.

type SearchResult

type SearchResult struct {
	Content               SearchContent   `json:"content"`
	Title                 string          `json:"title"`
	Excerpt               string          `json:"excerpt"`
	URL                   string          `json:"url"`
	ResultGlobalContainer SearchContainer `json:"resultGlobalContainer"`
	LastModified          string          `json:"lastModified"`
	FriendlyLastModified  string          `json:"friendlyLastModified"`
}

SearchResult represents a single search result from the v1 API.

type Space

type Space struct {
	ID          string            `json:"id"`
	Key         string            `json:"key"`
	Name        string            `json:"name"`
	Type        string            `json:"type"`
	Status      string            `json:"status"`
	Description *SpaceDescription `json:"description,omitempty"`
	Links       Links             `json:"_links,omitempty"`
}

Space represents a Confluence space.

type SpaceDescription

type SpaceDescription struct {
	Plain *DescriptionValue `json:"plain,omitempty"`
	View  *DescriptionValue `json:"view,omitempty"`
}

SpaceDescription contains space description in various formats.

type Time

type Time struct {
	time.Time
}

Time is a wrapper around time.Time for custom JSON parsing.

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON formats time in ISO 8601 format.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(data []byte) error

UnmarshalJSON parses Confluence's ISO 8601 date format.

type UpdatePageRequest

type UpdatePageRequest struct {
	ID      string   `json:"id"`
	Status  string   `json:"status"`
	Title   string   `json:"title"`
	Body    *Body    `json:"body"`
	Version *Version `json:"version"`
}

UpdatePageRequest is the request body for updating a page.

type Version

type Version struct {
	Number    int    `json:"number"`
	Message   string `json:"message,omitempty"`
	MinorEdit bool   `json:"minorEdit,omitempty"`
	AuthorID  string `json:"authorId,omitempty"`
	CreatedAt Time   `json:"createdAt,omitempty"`
}

Version contains page version information.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL