🩹 [Patch]: Preserve page status on update; trash-then-purge for Remove-ConfluencePage -Purge

Author: MariusStorhaug

src/functions/public/Pages/Remove-ConfluencePage.ps1

@@ -7,7 +7,9 @@ function Remove-ConfluencePage {
         .DESCRIPTION
         Moves a page to the trash. With -Recurse, direct and nested child pages
         are removed first so that a whole subtree can be deleted. With -Purge the
-        page is permanently deleted (only valid for already-trashed pages).
+        page is permanently deleted: because Confluence requires a page to be in
+        the trash before it can be purged, the page is trashed first and then
+        purged in a second call.
 
         .EXAMPLE
         ```powershell
@@ -31,7 +33,8 @@ function Remove-ConfluencePage {
         # Remove child pages before removing the page itself.
         [switch]$Recurse,
 
-        # Permanently delete instead of moving to trash.
+        # Permanently delete the page. It is moved to the trash first (as the API
+        # requires) and then purged.
         [switch]$Purge,
 
         # The context to use: an object, a context name, or $null for the default.
@@ -45,12 +48,21 @@ function Remove-ConfluencePage {
         }
     }
 
-    $endpoint = "/wiki/api/v2/pages/$PageId"
-    if ($Purge) {
-        $endpoint = '{0}?purge=true' -f $endpoint
-    }
+    $base = "/wiki/api/v2/pages/$PageId"
+    $action = if ($Purge) { 'Permanently delete Confluence page' } else { 'Delete Confluence page' }
 
-    if ($PSCmdlet.ShouldProcess($PageId, 'Delete Confluence page')) {
-        Invoke-ConfluenceRestMethod -ApiEndpoint $endpoint -Method 'DELETE' -Context $Context
+    if ($PSCmdlet.ShouldProcess($PageId, $action)) {
+        if ($Purge) {
+            # A page must be in the trash before it can be purged. Trash first
+            # (ignoring failures, e.g. when it is already trashed), then purge.
+            try {
+                Invoke-ConfluenceRestMethod -ApiEndpoint $base -Method 'DELETE' -Context $Context
+            } catch {
+                Write-Verbose "Trash step before purge failed (the page may already be trashed): $($_.Exception.Message)"
+            }
+            Invoke-ConfluenceRestMethod -ApiEndpoint ('{0}?purge=true' -f $base) -Method 'DELETE' -Context $Context
+        } else {
+            Invoke-ConfluenceRestMethod -ApiEndpoint $base -Method 'DELETE' -Context $Context
+        }
     }
 }

src/functions/public/Pages/Set-ConfluencePage.ps1

@@ -39,8 +39,8 @@ function Set-ConfluencePage {
         [ValidateSet('storage', 'atlas_doc_format', 'wiki')]
         [string]$Representation = 'storage',
 
-        # The page status. Defaults to 'current'.
-        [string]$Status = 'current',
+        # The page status. Defaults to the page's current status.
+        [string]$Status,
 
         # The context to use: an object, a context name, or $null for the default.
         [object]$Context
@@ -50,10 +50,11 @@ function Set-ConfluencePage {
 
     $newTitle = if ($PSBoundParameters.ContainsKey('Title')) { $Title } else { $current.title }
     $newBody = if ($PSBoundParameters.ContainsKey('Body')) { $Body } else { $current.body.$Representation.value }
+    $newStatus = if ($PSBoundParameters.ContainsKey('Status')) { $Status } else { $current.status }
 
     $payload = @{
         id      = $PageId
-        status  = $Status
+        status  = $newStatus
         title   = $newTitle
         version = @{
             number = [int]$current.version.number + 1