Merge pull request #77 from teamviewer/TEAM-60324_add_Get-TeamViewerC…

…ompanyManagedDevice

Added Get-TeamViewerCompanyManagedDevice cmdlet

CHANGELOG.md

@@ -1,6 +1,12 @@
 # Change Log
 
-## 2.0.1 (2024-11-14)
+## 2.1.0 (2024-11-15)
+
+### Added
+
+- Adds `Get-TeamViewerCompanyManagedDevice` to return all company-managed devices.
+
+## 2.0.2 (2024-11-14)
 
 ### Added
 - Add-TeamViewerSsoInclusion command to add SSO Inclusion list items.

Cmdlets/Public/Get-TeamViewerCompanyManagedDevice.ps1

@@ -0,0 +1,23 @@
+function Get-TeamViewerCompanyManagedDevice {
+    param(
+        [Parameter(Mandatory = $true)]
+        [securestring]
+        $ApiToken
+    )
+
+    $resourceUri = "$(Get-TeamViewerApiUri)/managed/devices/company"
+    $parameters = @{}
+
+    do {
+        $response = Invoke-TeamViewerRestMethod `
+            -ApiToken $ApiToken `
+            -Uri $resourceUri `
+            -Method Get `
+            -Body $parameters `
+            -WriteErrorTo $PSCmdlet `
+            -ErrorAction Stop
+
+        $parameters.paginationToken = $response.nextPaginationToken
+        Write-Output ($response.resources | ConvertTo-TeamViewerManagedDevice)
+    } while ($parameters.paginationToken)
+}

Cmdlets/TeamViewerPS.psd1

@@ -3,7 +3,7 @@
     RootModule        = 'TeamViewerPS.psm1'
 
     # Version number of this module.
-    ModuleVersion     = '2.0.2'
+    ModuleVersion     = '2.1.0'
 
     # Supported PSEditions.
     # CompatiblePSEditions = @()

Docs/Help/Get-TeamViewerCompanyManagedDevice.md

@@ -0,0 +1,73 @@
+---
+external help file: TeamViewerPS-help.xml
+Module Name: TeamViewerPS
+online version: https://github.com/teamviewer/TeamViewerPS/blob/main/Docs/Help/Get-TeamViewerCompanyManagedDevice.md
+schema: 2.0.0
+---
+
+# Get-TeamViewerCompanyManagedDevice
+
+## SYNOPSIS
+
+Retrieves TeamViewer company-managed devices. Requires an API Token with company admin permissions.
+
+## SYNTAX
+
+### List (Default)
+
+```powershell
+Get-TeamViewerCompanyManagedDevice -ApiToken <SecureString> [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+Retrieves company-managed devices of the company that is associated with the API access token.
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+
+PS /> Get-TeamViewerCompanyManagedDevice
+```
+
+List all company-managed devices of this company.
+
+## PARAMETERS
+
+### -ApiToken
+
+The TeamViewer API access token. Needs to have company admin permissions to successfully retrieve the devices.
+
+```yaml
+Type: SecureString
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### None
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS
+
+[Get-TeamViewerManagedDevice](Get-TeamViewerManagedDevice.md)
+
+[Get-TeamViewerManagedGroup](Get-TeamViewerManagedGroup.md)
+
+[Get-TeamViewerManagementId](Get-TeamViewerManagementId.md)

Docs/TeamViewerPS.md

@@ -133,6 +133,8 @@ The following functions are available in this category:
 
 [`Get-TeamViewerManagedGroup`](Help/Get-TeamViewerManagedGroup.md)
 
+[`Get-TeamViewerCompanyManagedDevice`](Help/Get-TeamViewerCompanyManagedDevice.md)
+
 [`Get-TeamViewerManagementId`](Help/Get-TeamViewerManagementId.md)
 
 [`Get-TeamViewerManager`](Help/Get-TeamViewerManager.md)

Tests/Public/Get-TeamViewerCompanyManagedDevice.Tests.ps1

@@ -0,0 +1,66 @@
+BeforeAll {
+    . "$PSScriptRoot\..\..\Cmdlets\Public\Get-TeamViewerCompanyManagedDevice.ps1"
+
+    @(Get-ChildItem -Path "$PSScriptRoot\..\..\Cmdlets\Private\*.ps1") | `
+        ForEach-Object { . $_.FullName }
+
+    $testApiToken = [securestring]@{}
+    $null = $testApiToken
+
+    Mock Get-TeamViewerApiUri { '//unit.test' }
+}
+
+Describe 'Get-TeamViewerCompanyManagedDevice' {
+    Context 'AllDevices' {
+        BeforeAll {
+            Mock Invoke-TeamViewerRestMethod { @{
+                    nextPaginationToken = $null
+                    resources           = @(
+                        @{ id = 'ae222e9d-a665-4cea-85b7-d4a3a08a5e35'; name = 'test company-managed device 1' },
+                        @{ id = '6cbfcfb2-a929-4987-a91b-89e2945412cf'; name = 'test company-managed device 2' },
+                        @{ id = '99a87bed-3d60-46f2-a869-b7e67a6bf2c8'; name = 'test company-managed device 3' }
+                    )
+                } }
+        }
+
+        It 'Should call the correct API endpoint to list company-managed devices' {
+            Get-TeamViewerCompanyManagedDevice -ApiToken $testApiToken
+
+            $base_test_path = '//unit.test'
+            $desired_endpoint = 'managed/devices/company'
+
+            Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter {
+                $ApiToken -eq $testApiToken -And `
+                    $Uri -eq "$base_test_path/$desired_endpoint" -And `
+                    $Method -eq 'Get' }
+        }
+
+        It 'Should return ManagedDevice objects' {
+            $result = Get-TeamViewerCompanyManagedDevice -ApiToken $testApiToken
+            $result | Should -HaveCount 3
+            $result[0].PSObject.TypeNames | Should -Contain 'TeamViewerPS.ManagedDevice'
+        }
+
+        It 'Should fetch consecutive pages' {
+            Mock Invoke-TeamViewerRestMethod { @{
+                    nextPaginationToken = 'abc'
+                    resources           = @(
+                        @{ id = 'ae222e9d-a665-4cea-85b7-d4a3a08a5e35'; name = 'test company-managed device 1' },
+                        @{ id = '6cbfcfb2-a929-4987-a91b-89e2945412cf'; name = 'test company-managed device 2' },
+                        @{ id = '99a87bed-3d60-46f2-a869-b7e67a6bf2c8'; name = 'test company-managed device 3' }
+                    )
+                } }
+            Mock Invoke-TeamViewerRestMethod { @{
+                    nextPaginationToken = $null
+                    resources           = @(
+                        @{ id = '76e699b7-2559-4202-bf7b-c6af6929aa15'; name = 'test company-managed device 4' }
+                    )
+                } } -ParameterFilter { $Body -And $Body['paginationToken'] -eq 'abc' }
+
+            $result = Get-TeamViewerCompanyManagedDevice -ApiToken $testApiToken
+            $result | Should -HaveCount 4
+
+            Assert-MockCalled Invoke-TeamViewerRestMethod -Times 2 -Scope It
+        }
+    }
+}