refactor(Page): add pipeline support

src/Page.psm1

@@ -10,6 +10,19 @@ function New-Page
 
         .DESCRIPTION
 
+            This function is unaware of the publishing status of ancestors and
+            assumes that ancestral hierarchy is maintained through the
+            manifest's item order.
+
+            If a page's metadata does not include a reference, it will be
+            treated as a publishing failure and therefore not output the
+            original metadata.
+
+        .OUTPUTS
+
+            When no $Title is provided and the $Manifest array only contains 1
+            page metadata, the ``Count`` attribute is faulty. Why? Don't know.
+
         .EXAMPLE
             Add-ConfluencePage `
                 -Host 'confluence.contoso.com' `
@@ -19,69 +32,142 @@ function New-Page
     #>
     Param(
         # confluence instance hostname
-        [Parameter(Mandatory)] [string] $Host,
+        [Parameter(Mandatory)] [string]$Host,
         # name of the Confluence space to publish to
-        [Parameter(Mandatory)] [string] $Space,
+        [Parameter(Mandatory)] [string]$Space,
         # title of page to be published
-        [Parameter(Mandatory)] [string] $Title,
+        [Parameter()] [string]$Title,
         # pages manifest
-        [Parameter(Mandatory)] [Array] $Manifest,
-        # pages manifest index
-        [Parameter()] [Collections.Hashtable] $Index
+        [Parameter(Mandatory, ValueFromPipeline)] 
+            [Collections.Hashtable[]]$Manifest,
+        # pages manifest index, mandatory for ancestor lookup
+        [Parameter(Mandatory)] [Collections.Hashtable]$Index,
+        # flag on whether to fail hard, or just continue
+        [Parameter()] [Switch]$Strict
     )
 
+    Begin
+    {
+        $pat = Get-PersonalAccessToken $Host
+    }
+
     Process
     {
-        $pageMeta = Get-PageMeta `
-            -Host $Host `
-            -Space $Space `
-            -Title $Title `
-            -Manifest $Manifest `
-            -Index $Index
-
-        if (-Not $pageMeta.Ref)
+        If ($Title -And $Manifest[$Index.$Title])
         {
-            throw "no reference to local content for page `$Title`."
+            $Manifest = @(
+                $Manifest[$Index.$Title]
+            )
         }
 
-        $content = Get-Content -Path $pageMeta.Ref
+        ForEach($pageMeta in $Manifest)
+        {
+            If ($Title -And $pageMeta.Title -ne $Title) {continue}
 
-        $transportBody = @{
-            'type' = 'page'
-            'title' = $Title
-            'space' = @{
-                'key' = $Space
+            ElseIf (-Not $pageMeta.Ref)
+            {
+                $errMsg = "no reference to local content for page ``$Title``."
+
+                If ($Strict) {throw $errMsg}
+
+                Write-Host $errMsg
+
+                continue
             }
-            'body' = @{
-                'storage' = @{
-                    'value' = $content
-                    'representation' = 'storage'
+
+            ElseIf ($pageMeta.Id)
+            {
+
+                Write-Debug "skipping, page already published: $($pageMeta.Id)"
+
+                $pageMeta
+
+                continue
+            }
+
+            Else
+            {
+                $content = Get-Content -Path $pageMeta.Ref
+
+                $contentHash = (Get-StringHash $content).Hash
+
+                $transportBody = @{
+                    'type' = 'page'
+                    'title' = $Title
+                    'space' = @{
+                        'key' = $Space
+                    }
+                    'body' = @{
+                        'storage' = @{
+                            'value' = $content
+                            'representation' = 'storage'
+                        }
+                    }
+                } | ConvertTo-JSON
+
+                Try
+                {
+                    Invoke-WebRequest `
+                        -Uri "https://${Host}/rest/api/content" `
+                        -Method 'Post' `
+                        -Headers @{
+                            'Authorization' = "Bearer $pat"
+                        } `
+                        -ContentType "application/json" `
+                        -Body $transportBody `
+                        -OutVariable rawResponse | Out-Null
+                }
+
+                Catch
+                {
+                    $errMsg = "skipping ``$pageMeta.Title``: $_"
+
+                    If ($Strict)
+                    {
+                        throw $errMsg
+                    }
+
+                    Write-Host $errMsg
+
+                    continue
+                }
+
+                $response = ($rawResponse.Content | ConvertFrom-JSON)
+
+                $pageMeta | Add-Member `
+                                -NotePropertyName 'Id' `
+                                -NotePropertyValue $response.id `
+                                -Force
+
+                $pageMeta | Add-Member `
+                                -NotePropertyName 'Version' `
+                                -NotePropertyValue $response.version.number `
+                                -Force
+
+                $pageMeta | Add-Member `
+                                -NotePropertyName 'Hash' `
+                                -NotePropertyValue $contentHash `
+                                -Force
+
+                If (
+                    ($Title -And $pageMeta.Title -eq $Title) -Or 
+                    $Manifest.Count -eq 1
+                )
+                {
+                    # TODO: further research mechanism of expanding single item
+                    # array pipelines. For now we have to apply the unary
+                    # operator, otherwise we get a wrong count on the output
+                    ,@($pageMeta)
+
+                    break
+                }
+
+                Else
+                {
+                    $pageMeta
                 }
             }
-        } | ConvertTo-JSON
-
-        Invoke-WebRequest `
-            -Uri "https://${Host}/rest/api/content" `
-            -Method 'Post' `
-            -Headers @{
-                'Authorization' = "Bearer $(Get-PersonalAccessToken $Host)"
-            } `
-            -ContentType "application/json" `
-            -Body $transportBody `
-            -OutVariable rawResponse | Out-Null
-    }
-
-    End
-    {
-        $response = ($rawResponse.Content | ConvertFrom-JSON)
-
-        Update-PageMeta `
-            -Title $Title `
-            -Id $response.Id `
-            -Version $response.version.number `
-            -Hash (Get-StringHash $content).Hash `
-            -Manifest $Manifest `
-            -Index $Index
+        }
     }
 }