🚀 [Feature]: Manage Atlassian Confluence Cloud from PowerShell (#17)

Confluence is now a working PowerShell module: connect to an Atlassian
Confluence Cloud site once and manage pages, spaces, blog posts,
folders, comments, labels, content properties, attachments, and
restrictions as first-class PowerShell commands. This first version
ports the generalized Confluence REST v2 client into the PSModule source
layout and wires it to the Process-PSModule build.

## New: 41 Confluence commands

Grouped by resource area:

- **Auth** — `Connect-Confluence`, `Disconnect-Confluence`,
`Get-ConfluenceContext`
- **Config** — `Get-ConfluenceConfig`, `Set-ConfluenceConfig`
- **API** — `Invoke-ConfluenceRestMethod` (the single generic REST entry
point every command wraps)
- **Spaces** — `Get-ConfluenceSpace`, `Get-ConfluenceSpacePermission`,
`Get-ConfluenceSpaceProperty`, plus space administration:
`New-ConfluenceSpace` (create), `Update-ConfluenceSpace` (partial
update), `Set-ConfluenceSpace` (declarative create-or-replace),
`Remove-ConfluenceSpace` (permanent, asynchronous delete)
- **Site / Pages / BlogPosts / Folders / Comments / Labels /
ContentProperties / Attachments / Restrictions / Users** — read/write
commands per area; page edits use `Update-ConfluencePage` (renamed from
`Set-ConfluencePage`, since it performs a partial update and the `Set`
verb is reserved for declarative create-or-replace as in
`Set-ConfluenceSpace`)

Each command documents its required OAuth granular scope in its help,
and errors surface Atlassian's `X-Failure-Category` (for example
`FAILURE_CLIENT_SCOPE_CHECK`) so permission/scope failures are easy to
spot. Every command's help links to its documentation page
(`https://psmodule.io/Confluence/Functions/<Area>/<Command>/`) followed
by the relevant Atlassian API reference.

## New: reusable connections via Context

Credentials and module configuration persist through the
[Context](https://github.com/PSModule/Context) module, declared via
`#Requires` so the build records it as a manifest dependency. Connect
once — the token is stored as a `SecureString`. Store multiple sites or
accounts as named contexts and target any of them with `-Context`.

```powershell
$token = Read-Host -AsSecureString
Connect-Confluence -Site 'msxorg' -Username 'you@example.com' -Token $token -SpaceKey 'DOCS'
$space = Get-ConfluenceSpace -Key 'DOCS'
New-ConfluencePage -SpaceId $space.id -Title 'Release notes' -Body '<p>Hello</p>'
```

## How it is built

- One function per file under `src/functions/{public,private}`, grouped
by resource area; module state in `src/variables/private`.
- No `header.ps1` and no source `manifest.psd1` — the build generates
the manifest, derives the module tags from the repository topics, and
reads the `#Requires` (PowerShell 7.0 and Context) from the source.
- Comment-based help follows the GitHub module style: indented sections,
fenced examples, and a documentation-page `.LINK` first.
- Examples (`Connecting`, `Pages`) and a credential-free surface test,
plus a skipped integration scaffold that reads `CONFLUENCE_*`
environment secrets. Tests require Pester 6.x.

## Tests and secrets

No tenant-specific data is included — examples use generic placeholders.
The integration tests are skipped unless connection details are provided
through the repository's Actions secret and variables
(`CONFLUENCE_SITE`, `CONFLUENCE_USERNAME`, `CONFLUENCE_API_TOKEN`,
`CONFLUENCE_SPACE_KEY`), which this PR wires into the Process-PSModule
workflow through `TestData`. Each public function also carries a
`#SkipTest:FunctionTest` marker so the framework's source-code test
suite passes while per-function tests are deferred.

## Technical details

- Merged `main`: kept the implemented-module README over the placeholder
(#15), adopted the Pester 6.x requirement (#16), and picked up the
Process-PSModule workflow bump to v5.5.7 (#14).
- Validated locally: 0 syntax parse errors, 0 PSScriptAnalyzer findings
(repo linter and framework build rules), every public command's first
`.LINK` resolves to its docs page, and the module assembles and imports
with all 41 public functions.
- Change type is **minor** (new functionality on a pre-1.0.0 module).
Repository topics set to supply the manifest tags;
`major`/`minor`/`patch`/`NoRelease` labels created for the release
automation.
- No linked issue — this work was driven directly; a tracking issue can
be added for traceability. Opened as a **draft** for review.

Author: MariusStorhaug

.github/workflows/Process-PSModule.yml

@@ -28,4 +28,16 @@ permissions:
 jobs:
   Process-PSModule:
     uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@da180bac16b13bfbcdf08b2e4e221b5b49e5ff28 # v6.1.4
-    secrets: inherit
+    secrets:
+      APIKey: ${{ secrets.APIKey }}
+      TestData: >-
+        {
+          "secrets": {
+            "CONFLUENCE_API_TOKEN": "${{ secrets.CONFLUENCE_API_TOKEN }}"
+          },
+          "variables": {
+            "CONFLUENCE_SITE": "${{ vars.CONFLUENCE_SITE }}",
+            "CONFLUENCE_USERNAME": "${{ vars.CONFLUENCE_USERNAME }}",
+            "CONFLUENCE_SPACE_KEY": "${{ vars.CONFLUENCE_SPACE_KEY }}"
+          }
+        }

README.md

@@ -1,15 +1,51 @@
 # Confluence
 
-Confluence is intended to be a PowerShell module for interacting with Atlassian Confluence.
+Confluence is a PowerShell module for interacting with the Atlassian Confluence Cloud REST API, both interactively and in automation.
 
-## Status
+It exposes pages, blog posts, folders, spaces, comments, labels, content properties, attachments, restrictions and more as PowerShell commands.
+Every command is a thin wrapper over a single generic REST entry point (`Invoke-ConfluenceRestMethod`). Credentials and module configuration
+are stored with the [Context](https://github.com/PSModule/Context) module, so you connect once and reuse the profile across sessions.
 
-This repository is currently a placeholder. The module source still contains scaffold code and examples, so there are no supported Confluence-specific commands or usage examples to document yet.
+## Installation
+
+Install the module from the PowerShell Gallery:
+
+```powershell
+Install-PSResource -Name Confluence
+Import-Module -Name Confluence
+```
+
+## Usage
+
+Connect with a scoped Atlassian API token, then call the resource commands. The token is kept as a `SecureString` in the Context vault.
+
+```powershell
+# Connect and store a reusable, named credential profile
+$token = Read-Host -AsSecureString   # a scoped Atlassian API token
+Connect-Confluence -Site 'yoursite' -Username 'you@example.com' -Token $token -SpaceKey 'DOCS'
+
+# Work with content
+$space = Get-ConfluenceSpace -Key 'DOCS'
+$page = New-ConfluencePage -SpaceId $space.id -Title 'Release notes' -Body '<p>Hello</p>'
+Update-ConfluencePage -PageId $page.id -Body '<p>Updated</p>'
+Get-ConfluencePageChild -PageId $page.id
+```
+
+See the [examples](examples) folder for more, including managing contexts and pages.
+
+The service-account token must be granted the module's required Confluence scopes — see [SCOPES.md](SCOPES.md).
 
 ## Documentation
 
-When this module is implemented, command details should live in PowerShell help and generated documentation rather than being duplicated in this README.
+Documentation is published at [psmodule.io/Confluence](https://psmodule.io/Confluence/).
+
+Use PowerShell help and command discovery for module details:
+
+```powershell
+Get-Command -Module Confluence
+Get-Help New-ConfluencePage -Examples
+```
 
 ## Contributing
 
-Issues and pull requests are welcome when implementation work begins.
+Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements.

SCOPES.md

@@ -0,0 +1,164 @@
+# Required Atlassian scopes
+
+`Confluence` authenticates with a **scoped** Atlassian API token (the `ATSTT…`
+prefix) used as HTTP Basic authentication (`<service-account-email>:<token>`)
+against the API-gateway host `https://api.atlassian.com/ex/confluence/<cloudId>`.
+
+When you create the token for the service account, select **granular** Confluence
+scopes (not the classic `*-confluence-*` scopes). Use this document when
+generating or rotating a token.
+
+> Note: cmdlet help lists scopes in a shortened form (for example `read:page`),
+> omitting the `:confluence` suffix for brevity. The canonical, fully-qualified
+> scope strings you grant on the token are the ones in this document (for example
+> `read:page:confluence`).
+
+## Configured scopes
+
+The token is currently configured with **48** granular Confluence scopes
+(**25 read**, **14 write**, **9 delete**). This is broader than the set the
+module's commands use today (see the tables below), leaving headroom for new
+commands.
+
+### Read (25)
+
+```text
+read:analytics.content:confluence
+read:attachment:confluence
+read:comment:confluence
+read:configuration:confluence
+read:content:confluence
+read:content-details:confluence
+read:content.metadata:confluence
+read:content.permission:confluence
+read:content.property:confluence
+read:content.restriction:confluence
+read:custom-content:confluence
+read:database:confluence
+read:email-address:confluence
+read:folder:confluence
+read:group:confluence
+read:hierarchical-content:confluence
+read:label:confluence
+read:page:confluence
+read:permission:confluence
+read:space:confluence
+read:space-details:confluence
+read:space.permission:confluence
+read:space.property:confluence
+read:space.setting:confluence
+read:user:confluence
+```
+
+### Write (14)
+
+```text
+write:attachment:confluence
+write:audit-log:confluence
+write:comment:confluence
+write:configuration:confluence
+write:content:confluence
+write:content.property:confluence
+write:content.restriction:confluence
+write:custom-content:confluence
+write:database:confluence
+write:embed:confluence
+write:folder:confluence
+write:group:confluence
+write:label:confluence
+write:page:confluence
+```
+
+### Delete (9)
+
+```text
+delete:attachment:confluence
+delete:comment:confluence
+delete:content:confluence
+delete:custom-content:confluence
+delete:database:confluence
+delete:embed:confluence
+delete:folder:confluence
+delete:page:confluence
+delete:whiteboard:confluence
+```
+
+## Scopes used by the current commands
+
+| Scope | Used by |
+| --- | --- |
+| `read:space:confluence` | `Get-ConfluenceSpace`, `Get-ConfluenceSiteInfo` |
+| `read:space.permission:confluence` | `Get-ConfluenceSpacePermission` |
+| `read:space.property:confluence` | `Get-ConfluenceSpaceProperty` |
+| `read:page:confluence` | `Get-ConfluencePage`, `Get-ConfluencePageChild`, `Get-ConfluencePageVersion`, `Update-ConfluencePage` (reads before updating) |
+| `read:folder:confluence` | `Get-ConfluenceFolder` |
+| `read:attachment:confluence` | `Get-ConfluenceAttachment` |
+| `read:comment:confluence` | `Get-ConfluenceComment` |
+| `read:label:confluence` | `Get-ConfluenceLabel` |
+| `read:content.property:confluence` | `Get-ConfluenceContentProperty` |
+| `read:hierarchical-content:confluence` | `Get-ConfluenceDescendant` |
+| `read:content-details:confluence` | `Get-ConfluenceRestriction`, `Get-ConfluenceCurrentUser`, `Add-ConfluenceAttachment` (upload) |
+| `write:page:confluence` | `New-ConfluencePage`, `Update-ConfluencePage` |
+| `write:folder:confluence` | `New-ConfluenceFolder` |
+| `write:attachment:confluence` | `Add-ConfluenceAttachment` |
+| `write:comment:confluence` | `Add-ConfluenceComment` |
+| `write:label:confluence` | `Add-ConfluenceLabel`, `Remove-ConfluenceLabel` |
+| `write:content.property:confluence` | `Set-ConfluenceContentProperty`, `Remove-ConfluenceContentProperty` |
+| `delete:page:confluence` | `Remove-ConfluencePage` |
+| `delete:folder:confluence` | `Remove-ConfluenceFolder` |
+| `delete:attachment:confluence` | `Remove-ConfluenceAttachment` |
+| `delete:comment:confluence` | `Remove-ConfluenceComment` |
+
+> Important: `Get-ConfluenceBlogPost` needs `read:blogpost:confluence`, which is
+> **not** in the configured set. Add that scope (or retire the command) — the
+> `/blogposts` endpoints will otherwise return 403. There is also no
+> `write:blogpost` / `delete:blogpost`, so blog posts cannot be created or removed.
+
+## Additional scopes available for new commands
+
+These scopes are configured but not yet backed by a command. Each row lists the
+candidate cmdlets it would enable (verbs in `{}` share one scope family):
+
+| Scope(s) | Candidate commands |
+| --- | --- |
+| `{read,write,delete}:custom-content:confluence` | Full custom-content CRUD: `Get-`, `New-`, `Set-`, `Remove-ConfluenceCustomContent` |
+| `{read,write,delete}:database:confluence` | Database CRUD: `Get-`, `New-`, `Set-`, `Remove-ConfluenceDatabase` |
+| `read:group:confluence` + `write:group:confluence` | `Get-ConfluenceGroup`, `Get-ConfluenceGroupMember`, `New-ConfluenceGroup`, `Add-`/`Remove-ConfluenceGroupMember` |
+| `read:user:confluence` + `read:email-address:confluence` | `Get-ConfluenceUser` (by accountId, incl. email); simplifies `Get-ConfluenceCurrentUser` |
+| `{read,write}:content.restriction:confluence` | `Add-`, `Set-`, `Remove-ConfluenceRestriction` (complements the existing `Get-ConfluenceRestriction`) |
+| `read:analytics.content:confluence` | `Get-ConfluenceContentAnalytics` (page/blog view + viewer counts) |
+| `write:comment:confluence` | `Set-ConfluenceComment` (update an existing comment) |
+| `read:permission:confluence` + `read:content.permission:confluence` | `Test-ConfluenceContentPermission` / `Get-ConfluenceOperationCheck` |
+| `{read,write}:configuration:confluence` | `Get-`/`Set-ConfluenceConfiguration` (look-and-feel / system settings; needs admin) |
+| `read:space.setting:confluence` + `read:space-details:confluence` | `Get-ConfluenceSpaceSetting`; richer `Get-ConfluenceSpace` details |
+| `{read,write,delete}:content:confluence`, `read:content.metadata:confluence` | Generic/classic content search & operations, e.g. `Find-ConfluenceContent` (CQL) |
+| `{write,delete}:embed:confluence` | `New-`/`Remove-ConfluenceEmbed` (Smart Links) — no `read:embed`, so read-back is unavailable |
+| `delete:whiteboard:confluence` | `Remove-ConfluenceWhiteboard` only — no `read:`/`write:whiteboard`, so create/read is unavailable |
+| `write:audit-log:confluence` | Audit-log export/write (admin) — no `read:audit-log`, so reading records is unavailable |
+
+## Notes
+
+- Scopes are only an **API ceiling**. Effective access is still bounded by the
+  service account's Confluence **permissions** (global and per-space), so grant it
+  the matching permissions on the spaces you target. Admin APIs (`configuration`,
+  `audit-log`, `group`) additionally need org/site admin rights.
+- **Asymmetric sets** worth noting: `whiteboard` is delete-only; `embed` has
+  write/delete but no read; `audit-log` is write-only. Commands for those can only
+  cover the granted verbs.
+- The module provides space-administration commands (`New-ConfluenceSpace`,
+  `Update-ConfluenceSpace`, `Set-ConfluenceSpace`, `Remove-ConfluenceSpace`), but
+  this token set has **no
+  space-administration write** scope (`write:space` / `delete:space`): the token
+  can read space settings, permissions and properties but cannot create, update
+  or delete spaces until `write:space:confluence` and `delete:space:confluence`
+  are added (space delete also needs `read:content.metadata:confluence`). Space
+  create/update/delete are v1-only operations, and delete is asynchronous (the
+  API returns HTTP 202 with a long-running task).
+- A few commands reach v1 endpoints that Atlassian maps to these granular scopes:
+  label add/remove (`write:label:confluence`), attachment upload
+  (`write:attachment:confluence` plus `read:content-details:confluence`), page
+  restriction reads and the current user (`read:content-details:confluence`).
+- Atlassian applies a soft cap of roughly **50 scopes** per token; at **48** this
+  set is near the cap, so adding the missing read scopes (blogpost, whiteboard,
+  embed) would leave little room and may require dropping unused ones.
+- Reference: [Confluence OAuth 2.0 scopes](https://developer.atlassian.com/cloud/confluence/scopes-for-oauth-2-3LO-and-forge-apps/).

examples/Connecting.ps1

@@ -0,0 +1,50 @@
+<#
+    .SYNOPSIS
+    Connect to Confluence and manage credential profiles (contexts).
+
+    .DESCRIPTION
+    Confluence stores each connection as a named context in the Context vault.
+    The token is kept as a SecureString. One context is the default; any command
+    can target a specific context with -Context.
+#>
+
+# Import the module
+Import-Module -Name 'Confluence'
+
+###
+### CONNECTING
+###
+
+# Connect with a scoped Atlassian API token and store a reusable default profile.
+# -Site takes a subdomain, host, or any URL on the site and resolves the cloud ID for you.
+$token = Read-Host -AsSecureString   # a scoped Atlassian API token
+Connect-Confluence -Site 'yoursite' -Username 'you@example.com' -Token $token -SpaceKey 'DOCS'
+
+# Store several sites/accounts under explicit names and select per call.
+# If you already know the cloud ID, pass it directly with -CloudId to skip the lookup.
+Connect-Confluence -CloudId '<cloudId>' -Username 'you@example.com' -Token $token -Name 'sandbox'
+Get-ConfluenceSpace -Key 'DOCS' -Context 'sandbox'
+
+###
+### CONTEXTS / PROFILES
+###
+
+# The default context
+Get-ConfluenceContext
+
+# All stored contexts
+Get-ConfluenceContext -ListAvailable
+
+###
+### MODULE CONFIGURATION
+###
+
+# Read and set module configuration (persisted in the same vault).
+Get-ConfluenceConfig
+Set-ConfluenceConfig -Name 'PerPage' -Value 50
+
+###
+### DISCONNECTING
+###
+
+Disconnect-Confluence -Name 'sandbox'

examples/General.ps1

@@ -0,0 +1,34 @@
+<#
+    .SYNOPSIS
+    Create, read, update and remove Confluence pages.
+
+    .DESCRIPTION
+    Assumes a default context is already connected (see Connecting.ps1).
+#>
+
+# Import the module
+Import-Module -Name 'Confluence'
+
+# Resolve the target space
+$space = Get-ConfluenceSpace -Key 'DOCS'
+
+# Create a page
+$page = New-ConfluencePage -SpaceId $space.id -Title 'Release notes' -Body '<p>First draft</p>'
+
+# Read it back (storage format by default)
+Get-ConfluencePage -PageId $page.id
+
+# Update the body (the version number is incremented automatically)
+Update-ConfluencePage -PageId $page.id -Body '<p>Updated content</p>'
+
+# Add a child page, then list children and descendants
+New-ConfluencePage -SpaceId $space.id -Title 'Details' -ParentId $page.id -Body '<p>Nested</p>'
+Get-ConfluencePageChild -PageId $page.id
+Get-ConfluenceDescendant -PageId $page.id
+
+# Labels and comments
+Add-ConfluenceLabel -PageId $page.id -Label 'release', 'published'
+Add-ConfluenceComment -PageId $page.id -Body '<p>Looks good.</p>'
+
+# Remove the whole subtree (moves the pages to trash)
+Remove-ConfluencePage -PageId $page.id -Recurse

examples/Pages.ps1

@@ -0,0 +1,39 @@
+function Resolve-ConfluenceContext {
+    <#
+        .SYNOPSIS
+        Resolve a context argument into a usable credential-context object.
+
+        .DESCRIPTION
+        Accepts a context object/hashtable (returned as-is), a context name
+        (looked up in the vault), or nothing (falls back to the default context
+        recorded in the module configuration).
+    #>
+    [CmdletBinding()]
+    param(
+        # A context object, a context name, or $null for the default context.
+        [object]$Context
+    )
+
+    if ($null -ne $Context -and $Context -isnot [string]) {
+        return $Context
+    }
+
+    Initialize-ConfluenceConfig
+    $id = if ([string]::IsNullOrEmpty([string]$Context)) { $script:Confluence.Config['DefaultContext'] } else { [string]$Context }
+
+    if ([string]::IsNullOrEmpty($id)) {
+        throw 'No Confluence context was specified and no default context is set. Run Connect-Confluence first.'
+    }
+
+    $resolved = $null
+    try {
+        $resolved = Get-Context -ID $id -Vault $script:Confluence.ContextVault -ErrorAction Stop
+    } catch {
+        $resolved = $null
+    }
+
+    if (-not $resolved) {
+        throw "Confluence context '$id' was not found in vault '$($script:Confluence.ContextVault)'."
+    }
+    return $resolved
+}