allow unmanage of Devices, add LastSeen field to managed devices (#17)

Add new field "LastSeenAt" to devices fetched via API
Add new function "Remove-TeamViewerManagedDeviceManagement" to allow unmanaging of devices

Build/New-TeamViewerPSPackage.ps1

@@ -18,7 +18,7 @@ New-Item -Type Directory "$BuildOutputPath/TeamViewerPS" | Out-Null
 
 # Compile all functions into a single psm file
 $targetFile = "$BuildOutputPath/TeamViewerPS/TeamViewerPS.psm1"
-Write-Verbose "Compiling single-file TeamViewer module."
+Write-Verbose 'Compiling single-file TeamViewer module.'
 $ModuleTypes = @(Get-ChildItem -Path "$repoPath/TeamViewerPS/TeamViewerPS.Types.ps1")
 $PrivateFunctions = @(Get-ChildItem `
         -Path "$repoPath/TeamViewerPS/Private/*.ps1" `
@@ -31,10 +31,10 @@ Write-Verbose "Found $($PublicFunctions.Count) public function files."
 @($ModuleTypes + $PrivateFunctions + $PublicFunctions) | `
     Get-Content -Raw | `
     ForEach-Object { $_; "`r`n" } | `
-    Set-Content -Path $targetFile -Encoding utf8NoBOM
+    Set-Content -Path $targetFile -Encoding UTF8
 
 # Create help from markdown
-Write-Verbose "Building help from Markdown"
+Write-Verbose 'Building help from Markdown'
 New-ExternalHelp `
     -Path "$repoPath/docs" `
     -OutputPath "$BuildOutputPath/TeamViewerPS/en-US" | `
@@ -45,7 +45,7 @@ New-ExternalHelp `
     Out-Null
 
 # Create module manifest
-Write-Verbose "Creating module manifest"
+Write-Verbose 'Creating module manifest'
 Copy-Item `
     -Path "$repoPath/TeamViewerPS/TeamViewerPS.psd1" `
     -Destination "$BuildOutputPath/TeamViewerPS/"
@@ -58,15 +58,15 @@ Update-Metadata `
     -Value $PublicFunctions.BaseName
 
 # Copy additional package files
-Write-Verbose "Copying additional files into the package"
+Write-Verbose 'Copying additional files into the package'
 Copy-Item `
     -Path `
     "$repoPath/LICENSE", `
     "$repoPath/CHANGELOG.md", `
     "$repoPath/README.md"`
     -Destination "$BuildOutputPath/TeamViewerPS/"
 
-Write-Verbose "Listing package files:"
+Write-Verbose 'Listing package files:'
 Push-Location $BuildOutputPath
 Get-ChildItem -Recurse "$BuildOutputPath/TeamViewerPS" | `
     Sort-Object -Property FullName | `

CHANGELOG.md

@@ -1,14 +1,16 @@
 # Change Log
 
-## 1.x.0 (2023-0x-xx)
+## 1.5.0 (2023-05-24)
 
 ### Added
 
 - Added `Remove-TeamViewerUser` cmdlet to remove user from TeamViewer company. (Thanks @OtterKring)
+- Added `Remove-TeamViewerManagedDeviceManagement` to unmanage a device.
 
 ### Changed
 
 - Extended `Add-TeamViewerManager` to add user group as manager. (Thanks @OtterKring)
+- Extended `TeamViewerManagedDevice` to have "LastSeenAt" available for managed devices
 
 ## 1.4.0 (2022-04-19)
 

TeamViewerPS/Private/ConvertTo-TeamViewerManagedDevice.ps1

@@ -12,8 +12,8 @@ function ConvertTo-TeamViewerManagedDevice {
             IsOnline     = $InputObject.isOnline
         }
 
-        if ($InputObject.pendingOperation) {
-            $properties["PendingOperation"] = $InputObject.pendingOperation
+        if ($InputObject.last_seen) {
+            $properties['LastSeenAt'] = Get-Date -Date $InputObject.last_seen
         }
 
         if ($InputObject.teamviewerPolicyId) {

TeamViewerPS/Public/Remove-TeamViewerManagedDeviceManagement.ps1

@@ -0,0 +1,28 @@
+function Remove-TeamViewerManagedDeviceManagement {
+    [CmdletBinding(SupportsShouldProcess = $true)]
+    param(
+        [Parameter(Mandatory = $true)]
+        [securestring]
+        $ApiToken,
+
+        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
+        [ValidateScript( { $_ | Resolve-TeamViewerManagedDeviceId } )]
+        [Alias('DeviceId')]
+        [object]
+        $Device
+    )
+    Process {
+        $deviceId = $Device | Resolve-TeamViewerManagedDeviceId
+
+        $resourceUri = "$(Get-TeamViewerApiUri)/managed/devices/$deviceId"
+
+        if ($PSCmdlet.ShouldProcess($deviceId, 'Remove Management from a device (clears all managers and groups)')) {
+            Invoke-TeamViewerRestMethod `
+                -ApiToken $ApiToken `
+                -Uri $resourceUri `
+                -Method Delete `
+                -WriteErrorTo $PSCmdlet | `
+                Out-Null
+        }
+    }
+}

TeamViewerPS/TeamViewerPS.psd1

@@ -3,7 +3,7 @@
     RootModule        = 'TeamViewerPS.psm1'
 
     # Version number of this module.
-    ModuleVersion     = '1.4.0'
+    ModuleVersion     = '1.5.0'
 
     # Supported PSEditions.
     # CompatiblePSEditions = @()
@@ -54,7 +54,7 @@
     # TypesToProcess = @()
 
     # Format files (.ps1xml) to be loaded when importing this module.
-    FormatsToProcess = @('TeamViewerPS.format.ps1xml')
+    FormatsToProcess  = @('TeamViewerPS.format.ps1xml')
 
     # Modules to import as nested modules of the module specified in RootModule/ModuleToProcess.
     # NestedModules = @()

Tests/Public/Get-TeamViewerManagedDevice.Tests.ps1

@@ -97,12 +97,14 @@ Describe 'Get-TeamViewerManagedDevice' {
                             name         = 'test device 1'
                             teamviewerId = 12345678
                             isOnline     = $false
+                            last_seen    = '2023-02-03T11:14:19Z'
                         },
                         @{
                             id           = 'bc76c466-50dc-4b1f-963d-9b3a10a40ec6'
                             name         = 'test device 2'
                             teamviewerId = 87654321
                             isOnline     = $true
+                            last_seen    = '2023-02-03T11:14:19Z'
                         }
                     )
                 } }
@@ -141,12 +143,14 @@ Describe 'Get-TeamViewerManagedDevice' {
                             name         = 'test device 1'
                             teamviewerId = 12345678
                             isOnline     = $false
+                            last_seen    = '2023-02-03T11:14:19Z'
                         },
                         @{
                             id           = 'bc76c466-50dc-4b1f-963d-9b3a10a40ec6'
                             name         = 'test device 2'
                             teamviewerId = 87654321
                             isOnline     = $true
+                            last_seen    = '2023-02-03T11:14:19Z'
                         }
                     )
                 } }
@@ -158,6 +162,7 @@ Describe 'Get-TeamViewerManagedDevice' {
                             name         = 'test device 3'
                             teamviewerId = 12345678
                             isOnline     = $false
+                            last_seen    = '2023-02-03T11:14:19Z'
                         }
                     )
                 } } -ParameterFilter { $Body -And $Body['paginationToken'] -eq 'abc' }

Tests/Public/Remove-TeamViewerManagedDeviceManagement.Tests.ps1

@@ -0,0 +1,45 @@
+BeforeAll {
+    . "$PSScriptRoot/../../TeamViewerPS/Public/Remove-TeamViewerManagedDeviceManagement.ps1"
+
+    @(Get-ChildItem -Path "$PSScriptRoot/../../TeamViewerPS/Private/*.ps1") | `
+        ForEach-Object { . $_.FullName }
+
+    $testApiToken = [securestring]@{}
+    $null = $testApiToken
+    $testDeviceId = 'c37e72b8-b78d-467f-923c-6083c13cf82f'
+    $null = $testDeviceId
+
+    Mock Get-TeamViewerApiUri { '//unit.test' }
+    Mock Invoke-TeamViewerRestMethod { }
+}
+
+Describe 'Remove-TeamViewerManagedDeviceManagement' {
+    It 'Should call the correct API endpoint' {
+        Remove-TeamViewerManagedDeviceManagement -ApiToken $testApiToken -DeviceId $testDeviceId
+
+        Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter {
+            $ApiToken -eq $testApiToken -And `
+                $Uri -eq "//unit.test/managed/devices/$testDeviceId" -And `
+                $Method -eq 'Delete' }
+    }
+
+    It 'Should accept ManagedDevice objects' {
+        $testDeviceObj = @{ id = $testDeviceId } | ConvertTo-TeamViewerManagedDevice
+        Remove-TeamViewerManagedDeviceManagement -ApiToken $testApiToken -Device $testDeviceObj
+
+        Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter {
+            $ApiToken -eq $testApiToken -And `
+                $Uri -eq "//unit.test/managed/devices/$testDeviceId" -And `
+                $Method -eq 'Delete' }
+    }
+
+    It 'Should accept pipeline input' {
+        $testDeviceObj = @{ id = $testDeviceId } | ConvertTo-TeamViewerManagedDevice
+        $testDeviceObj | Remove-TeamViewerManagedDeviceManagement -ApiToken $testApiToken
+
+        Assert-MockCalled Invoke-TeamViewerRestMethod -Times 1 -Scope It -ParameterFilter {
+            $ApiToken -eq $testApiToken -And `
+                $Uri -eq "//unit.test/managed/devices/$testDeviceId" -And `
+                $Method -eq 'Delete' }
+    }
+}

docs/about_TeamViewerPS.md

@@ -111,6 +111,8 @@ The following functions are available in this category:
 
 [`Remove-TeamViewerManagedDevice`](commands/Remove-TeamViewerManagedDevice.md)
 
+[`Remove-TeamViewerManagedDeviceManagement`](commands/Remove-TeamViewerManagedDeviceManagement.md)
+
 [`Remove-TeamViewerManagedGroup`](commands/Remove-TeamViewerManagedGroup.md)
 
 [`Remove-TeamViewerManager`](commands/Remove-TeamViewerManager.md)

docs/commands/Remove-TeamViewerManagedDeviceManagement.md

@@ -0,0 +1,116 @@
+---
+external help file: TeamViewerPS-help.xml
+Module Name: TeamViewerPS
+online version: https://github.com/teamviewer/TeamViewerPS/blob/main/docs/commands/Remove-TeamViewerManagedDeviceManagement.md
+schema: 2.0.0
+---
+
+# Remove-TeamViewerManagedDevice
+
+## SYNOPSIS
+
+Removes the management status from a managed device.
+
+## SYNTAX
+
+```powershell
+Remove-TeamViewerManagedDeviceManagement [-ApiToken] <SecureString> [-Device] <Object> [-WhatIf]
+ [-Confirm] [<CommonParameters>]
+```
+
+## DESCRIPTION
+
+Removes the management status from a managed device.
+This makes the device unmanaged removing it from all groups and removing all managers.
+The current account needs `ManagerAdministration` manager permissions on the device. 
+
+## EXAMPLES
+
+### Example 1
+
+```powershell
+PS /> Remove-TeamViewerManagedDeviceManagement -Device 'c0cb303a-8a85-4e54-b657-a4757c791aef'
+```
+
+## PARAMETERS
+
+### -ApiToken
+
+The TeamViewer API access token.
+
+```yaml
+Type: SecureString
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 0
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Confirm
+
+Prompts you for confirmation before running the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: cf
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Device
+
+Object that can be used to identify the managed device.
+This can either be the managed device ID (as string or GUID) or a managed device
+object that has been received using other module functions.
+
+```yaml
+Type: Object
+Parameter Sets: (All)
+Aliases: DeviceId
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: True (ByValue)
+Accept wildcard characters: False
+```
+
+### -WhatIf
+
+Shows what would happen if the cmdlet runs.
+The cmdlet is not run.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: wi
+
+Required: False
+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
+
+### System.Object
+
+## OUTPUTS
+
+## NOTES
+
+## RELATED LINKS