Remove-TeamViewerOutdatedDevice.ps1

<#
 .SYNOPSIS
    Removes TeamViewer devices that didn't appear online for a given time.

 .DESCRIPTION
    The script fetches a list of TeamViewer devices of the TeamViewer company
    that corresponds to a given API token. The list will be filtered by
    devices being offline for a certain amount of time. These devices will
    be removed.
    The expiration can either be specified by a specific date or by interval.

 .PARAMETER ApiToken
    The TeamViewer API token to use.
    Must be a user access token.
    The token requires the following access permissions:
        - `Computer & Contacts > View entries, add entries, edit entries, remove entries`

 .PARAMETER ExpiryDate
    A specific expiry date. All devices that haven't been online since that
    date are considered being removed.

 .PARAMETER ExpiryInterval
    Switch that enables interval-based calculation of the expiration date.
    Should be used in combination with the `Days`, `Hours`, `Minutes` and/or
    `Seconds` parameter.

 .PARAMETER Days
    Days of the expiration interval.
    Must be used in combination with the `ExpiryInterval` parameter.

 .PARAMETER Hours
    Hours of the expiration interval.
    Must be used in combination with the `ExpiryInterval` parameter.

 .PARAMETER Minutes
    Minutes of the expiration interval.
    Must be used in combination with the `ExpiryInterval` parameter.

 .PARAMETER Seconds
    Seconds of the expiration interval.
    Must be used in combination with the `ExpiryInterval` parameter.

 .PARAMETER Force
    If set, the script will NOT ask the user for confirmation of the
    removal. This parameter only has effect in combination with the
    `Remove` parameter.
    The default value is `false`, causing the script to ask the user
    one more time before starting to remove devices.

 .EXAMPLE
    .\Remove-TeamViewerOutdatedDevice -ExpiryDate '2018-12-17T17:00:00'

 .EXAMPLE
    .\Remove-TeamViewerOutdatedDevice -ExpiryDate 2018-12-31 -WhatIf

 .EXAMPLE
    .\Remove-TeamViewerOutdatedDevice -ExpiryInterval -Days 10

 .EXAMPLE
    .\Remove-TeamViewerOutdatedDevice -ExpiryInterval -Hours 12 -Force

 .NOTES
     This script requires the TeamViewerPS module to be installed.
    This can be done using the following command:

    ```
    Install-Module TeamViewerPS
    ```

    Copyright (c) 2019-2021 TeamViewer GmbH
    See file LICENSE.txt
    Version 2.0
#>

[CmdletBinding(DefaultParameterSetName = "ExactDate", SupportsShouldProcess = $true)]
param(
    [Parameter(Mandatory = $true)]
    [securestring] $ApiToken,

    [Parameter(ParameterSetName = "ExactDate", Mandatory = $true)]
    [DateTime] $ExpiryDate,

    [Parameter(ParameterSetName = "DateInterval", Mandatory = $true)]
    [switch] $ExpiryInterval,

    [Parameter(ParameterSetName = "DateInterval", Mandatory = $false)]
    [int] $Days,

    [Parameter(ParameterSetName = "DateInterval", Mandatory = $false)]
    [int] $Hours,

    [Parameter(ParameterSetName = "DateInterval", Mandatory = $false)]
    [int] $Minutes,

    [Parameter(ParameterSetName = "DateInterval", Mandatory = $false)]
    [int] $Seconds,

    [Switch] $Force = $false
)

if (-Not $MyInvocation.BoundParameters.ContainsKey('ErrorAction')) { $script:ErrorActionPreference = 'Stop' }
if (-Not $MyInvocation.BoundParameters.ContainsKey('InformationAction')) { $script:InformationPreference = 'Continue' }

function Install-TeamViewerModule { if (!(Get-Module TeamViewerPS)) { Install-Module TeamViewerPS } }

function Remove-TeamViewerOutdatedDevice {
    [CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]
    param($expiryDate, [bool]$force)

    $devices = @((Get-TeamViewerDevice -ApiToken $ApiToken -FilterOnlineState 'Offline') | `
            Where-Object { $_.LastSeenAt -And $_.LastSeenAt -le $expiryDate })

    Write-Information "Found $($devices.Count) devices that have been offline since $expiryDate"

    if ($devices.Count -gt 0 -And -Not $WhatIfPreference -And -Not $force -And
        -Not $PSCmdlet.ShouldContinue("Do you really want to remove those devices?", $devices)) {
        Write-Information "Aborting..."
        exit
    }

    ForEach ($device in $devices) {
        $status = 'Unchanged'
        if ($force -Or $PSCmdlet.ShouldProcess($device.Name)) {
            try {
                Remove-TeamViewerDevice -ApiToken $ApiToken -Device $device
                $status = 'Removed'
            }
            catch {
                Write-Warning "Failed to remove device '$($device.Name)': $_"
                $status = 'Failed'
            }
        }
        Write-Output ([pscustomobject]@{
                Name     = $device.Name
                DeviceId = $device.Id
                LastSeen = $device.LastSeenAt
                Status   = $status
            })
    }
}

if ($MyInvocation.InvocationName -ne '.') {
    Install-TeamViewerModule
    $now = (Get-Date)
    if ($ExpiryInterval) {
        $ExpiryDate = $now.AddDays(-1 * $Days).AddHours(-1 * $Hours).AddMinutes(-1 * $Minutes).AddSeconds(-1 * $Seconds)
    }
    if ($ExpiryDate -ge $now) {
        Throw "Invalid expiry date specified: $ExpiryDate"
    }
    Remove-TeamViewerOutdatedDevice -expiryDate $ExpiryDate -force $Force
}