♻️ [Maintenance]: Rename ConvertTo-ConfluenceCloudId to Get-ConfluenceCloudId; record token scopes on connect

- Rename ConvertTo-ConfluenceCloudId to Get-ConfluenceCloudId: the function
  performs a GET against /_edge/tenant_info, so a Get- verb is accurate. Help,
  examples, the Connect-Confluence reference, and the surface test are updated.
- Connect-Confluence now collects the token's scopes from the accessible-resources
  endpoint and stores them on the context (Scopes), so callers can see what the
  token can do. Collection is best-effort and never fails the connection.

Author: MariusStorhaug

src/functions/public/Auth/Connect-Confluence.ps1

@@ -46,7 +46,7 @@ function Connect-Confluence {
         [string]$Site,
 
         # The Confluence Cloud ID - a faster alternative to -Site that skips the lookup.
-        # Find it with `ConvertTo-ConfluenceCloudId` or `Get-ConfluenceAccessibleResource`.
+        # Find it with `Get-ConfluenceCloudId` or `Get-ConfluenceAccessibleResource`.
         [Parameter(Mandatory, ParameterSetName = 'CloudId')]
         [string]$CloudId,
 
@@ -70,7 +70,7 @@ function Connect-Confluence {
 
     if ($PSCmdlet.ParameterSetName -eq 'Site') {
         # Resolve a site name/host/URL to its cloud ID via the public tenant_info endpoint.
-        $CloudId = ConvertTo-ConfluenceCloudId -Site $Site
+        $CloudId = Get-ConfluenceCloudId -Site $Site
     }
     # The scoped-token gateway base is always api.atlassian.com/ex/confluence/<cloudId>.
     $ApiBaseUri = 'https://api.atlassian.com/ex/confluence/{0}' -f $CloudId
@@ -100,6 +100,7 @@ function Connect-Confluence {
         Username   = $Username
         Token      = $Token
         SpaceKey   = $SpaceKey
+        Scopes     = @()
     }
 
     if (-not $PSCmdlet.ShouldProcess($Name, 'Connect to Confluence and store credential context')) {
@@ -118,6 +119,19 @@ function Connect-Confluence {
         Write-Warning "Token authenticated but lacks read:space; space listing is unavailable for context '$Name'."
     }
 
+    # Best-effort: record the scopes the token holds for this site (from the
+    # accessible-resources endpoint) so the stored context reflects what we can do.
+    # Never fail the connection if scope discovery is unavailable for this token.
+    try {
+        $resource = Get-ConfluenceAccessibleResource -Token $Token | Where-Object { $_.id -eq $CloudId } | Select-Object -First 1
+        if ($resource -and $resource.scopes) {
+            $context['Scopes'] = @($resource.scopes)
+            Write-Verbose "Recorded $($context['Scopes'].Count) scope(s) for context '$Name'."
+        }
+    } catch {
+        Write-Verbose "Could not resolve token scopes from accessible-resources: $($_.Exception.Message)"
+    }
+
     $stored = Set-Context -ID $Name -Context $context -Vault $script:Confluence.ContextVault -PassThru
     Set-ConfluenceConfig -Name 'DefaultContext' -Value $Name
 

…lic/Site/ConvertTo-ConfluenceCloudId.ps1 …ns/public/Site/Get-ConfluenceCloudId.ps1src/functions/public/Site/ConvertTo-ConfluenceCloudId.ps1 renamed to src/functions/public/Site/Get-ConfluenceCloudId.ps1 src/functions/public/Site/ConvertTo-ConfluenceCloudId.ps1 renamed to src/functions/public/Site/Get-ConfluenceCloudId.ps1

@@ -1,44 +1,42 @@
 #SkipTest:FunctionTest:Resolves the cloud ID from the public tenant_info endpoint; covered by integration tests.
-function ConvertTo-ConfluenceCloudId {
+function Get-ConfluenceCloudId {
     <#
         .SYNOPSIS
-        Resolve a Confluence Cloud site to its cloud ID.
+        Get the cloud ID for a Confluence Cloud site.
 
         .DESCRIPTION
         Looks up the cloud ID for an Atlassian Confluence Cloud site from the
-        public `/_edge/tenant_info` endpoint, so a caller can supply a site name or
-        URL instead of the cloud ID. Accepts a bare subdomain (`myorg`), a host
-        (`myorg.atlassian.net`), or any URL on the site
+        public `/_edge/tenant_info` endpoint (a GET request), so a caller can supply
+        a site name or URL instead of the cloud ID. Accepts a bare subdomain
+        (`myorg`), a host (`myorg.atlassian.net`), or any URL on the site
         (`https://myorg.atlassian.net/wiki/...`). No authentication is required.
 
         .EXAMPLE
         ```powershell
-        ConvertTo-ConfluenceCloudId -Site 'msxorg'
+        Get-ConfluenceCloudId -Site 'msxorg'
         ```
 
         Returns the cloud ID for `https://msxorg.atlassian.net`.
 
         .EXAMPLE
         ```powershell
-        'https://msxorg.atlassian.net/wiki/spaces/DOCS' | ConvertTo-ConfluenceCloudId
+        'https://msxorg.atlassian.net/wiki/spaces/DOCS' | Get-ConfluenceCloudId
         ```
 
         Resolves the cloud ID from a full site URL supplied through the pipeline.
 
         .EXAMPLE
         ```powershell
-        $cloudId = ConvertTo-ConfluenceCloudId -Site 'msxorg'
-        Connect-Confluence -ApiBaseUri "https://api.atlassian.com/ex/confluence/$cloudId" -Username $user -Token $token
+        Connect-Confluence -CloudId (Get-ConfluenceCloudId -Site 'msxorg') -Username $user -Token $token
         ```
 
-        Uses the resolved cloud ID to build the API-gateway base URI for `Connect-Confluence`,
-        so the caller only needs the site name.
+        Uses the resolved cloud ID to connect, so the caller only needs the site name.
 
         .OUTPUTS
         System.String
 
         .LINK
-        https://psmodule.io/Confluence/Functions/Site/ConvertTo-ConfluenceCloudId/
+        https://psmodule.io/Confluence/Functions/Site/Get-ConfluenceCloudId/
 
         .LINK
         https://developer.atlassian.com/cloud/confluence/rest/v2/intro/#about

tests/Confluence.Tests.ps1

@@ -39,7 +39,7 @@ Describe 'Confluence' {
                     'Invoke-ConfluenceRestMethod'
                     'Get-ConfluenceSpace'
                     'Get-ConfluenceSiteInfo'
-                    'ConvertTo-ConfluenceCloudId'
+                    'Get-ConfluenceCloudId'
                     'Get-ConfluenceAccessibleResource'
                     'New-ConfluencePage'
                     'Get-ConfluencePage'