How do you restore items from the SharePoint recycling bin in a filtered manner?

# Import module locally for development
Import-Module "*.psm1" -ErrorAction Stop

# Connect to SharePoint
$SiteUrl = "https://tenant.sharepoint.com/sites/gtvar"
Connect-PnPOnline -Url $SiteUrl -Interactive

# Restore items from the recycle bin
$Result = Restore-RecycledItems -SiteUrl $SiteUrl -StartDate "2023-05-28" -DaysToRestore 1 -TargetUser "harry@tenant.io" #-WhatIf

# Output the results
If ($Result.RestoredFiles) {
    $Failed = $Result.RestoredFiles.Status | Where-Object { $_ -eq "Failed" }
    Write-Host "Processed: $($Result.RestoredFiles.Count)"
    Write-Host "Renamed: $($Result.RenamedFiles.Count)"
    Write-Host "Failed: $($Failed.Count)"

    # Output restored files to csv
    Export-Csv -Path "D:\RestoredFiles.csv" -InputObject $Result.RestoredFiles -NoTypeInformation
}

<#
.SYNOPSIS
Restores items from the SharePoint recycle bin based on provided parameters.
.DESCRIPTION
The Restore-RecycledItems PowerShell script restores items from the SharePoint recycle bin based on the provided parameters.
The script supports filtering by date range, number of days to restore, and target user.
It also handles restoring files with duplicate names by renaming them automatically.
.PARAMETER SiteUrl
The URL of the SharePoint site where the recycle bin is located.
.PARAMETER StartDate
The starting date (inclusive) for the items to be restored from the recycle bin.
.PARAMETER DaysToRestore
The number of days to restore, counting from the StartDate.
.PARAMETER TargetUser
The email address of the user whose items should be restored. If not specified, items from all users will be restored.
.EXAMPLE
$Result = Restore-RecycledItems -SiteUrl "https://example.sharepoint.com/sites/gtvar" -StartDate "2023-03-31" -DaysToRestore 1 -TargetUser "name@example.io"
Restores items from the recycle bin in the specified SharePoint site that were deleted on 2023-03-31 by the user with the email address specified.
#>

function Restore-RecycledItems {
    [CmdletBinding(SupportsShouldProcess = $True, ConfirmImpact = 'High')]
    param (
        [Parameter(Mandatory = $true)]
        [string]$SiteUrl,

        [Parameter(Mandatory = $true)]
        [DateTime]$StartDate,

        [Parameter(Mandatory = $true)]
        [int]$DaysToRestore,

        [Parameter(Mandatory = $false)]
        [string]$TargetUser
    )

    Begin {
        # Setup vars
        $EndDate = $StartDate.AddDays($DaysToRestore)
        $Result = @{
            RestoredFiles = @()
            RenamedFiles  = @()
        }

        # Attempt to retrieve the recycle bin items
        Try {
            $Recycling = Get-PnPRecycleBinItem |
            Where-Object {
                    ($_.DeletedDate.ToLocalTime() -ge $StartDate) -and
                    ($_.DeletedDate.ToLocalTime() -le $EndDate) -and
                    ($null -eq $TargetUser -or $_.DeletedByEmail -eq $TargetUser)
            }

            # Setup progress vars
            $current = 0
            $total = $Recycling.Count
        }
        Catch {
            New-Warning "Failed to get recycle bin items with error: $($_.Exception.Message)"
            Exit
        }

        # If no items were found, throw an error
        if ($Recycling.Count -eq 0) {
            New-Warning -Message "No items were found between $StartDate - $EndDate"
            Exit
        }
    }

    Process {
        if ($PSCmdlet.ShouldProcess(
            ("{0} item(s) have been found between {1} - {2}, deleted by {3}" -f $Recycling.Count, $StartDate, $EndDate, $TargetUser),
            ("Would you like to restore {0} items(s)?" -f $Recycling.Count),
                "Restore Recycled Items"
            )
        ) {
            New-Message -Message "Starting restore process..."

            # If whatif is not specified, restore the items
            ForEach ($Item in $Recycling) {
                # Setup file vars
                $Dir = $Item.DirName
                $Title = $Item.Title
                $Path = "$Dir/$Title"

                # Show progress with an item name
                $current += 1
                Show-Progress -Current $current -Total $total -ItemName $Title
    
                if (Get-PnPFile -Url "/$($Path)" -ErrorAction SilentlyContinue) {
                    $FileExists = $true
                    New-Warning -Message "File exists: $Path"
                }
                else { 
                    $FileExists = $false 
                }
    
                $RestoreResult = @{
                    Path       = $Path
                    Status     = ""
                    Message    = ""
                    DocumentID = $Item.Id
                }
    
                if ($FileExists) {
                    # Get the file name and extension
                    $NewFileName = "/$($Path)"
                    $FileName = [System.IO.Path]::GetFileNameWithoutExtension($item.LeafName)
                    $FileExtension = [System.IO.Path]::GetExtension($item.LeafName)
    
                    # If the file already exists, append a number to the end of the file name
                    $Number = 0
                    while (Get-PnPFile -Url $NewFileName -ErrorAction SilentlyContinue) {
                        $Number++
                        New-Message -Message "Attempting to rename conflict ($Number)"
                        $NewFileName = "/$Dir/${FileName}_${Number}${FileExtension}"
                    }
    
                    # Rename the file
                    Try {
                        Rename-PnPFile -ServerRelativeUrl "/$($Path)" -TargetFileName "$([System.IO.Path]::GetFileName($NewFileName))" -Force
                        New-Message -Message "Renamed to: $NewFileName"
                        $RenameResult = @{
                            OldPath    = $Path
                            NewPath    = $NewFileName
                            DocumentID = $Item.Id
                        }
                        $Result.RenamedFiles += $RenameResult
                    }
                    Catch {
                        New-Error -Message "Failed to rename: $Title"
                        New-Error -Message "Error: $($_.Exception.Message)"
                        $RestoreResult.Status = "Failed"
                        $RestoreResult.Message = $_.Exception.Message
                        $Result.RestoredFiles += $RestoreResult
                        Continue
                    }
                }
    
                # Restore the file
                Try {
                    New-Message -Message "Attempting restore: $Title"
                    $Item | Restore-PnpRecycleBinItem -Force
                    $RestoreResult.Status = "Restored"
                    $Result.RestoredFiles += $RestoreResult
                }
                Catch {
                    New-Error -Message "Failed to restore: $Title"
                    New-Error -Message "Error: $($_.Exception.Message)"
                    $RestoreResult.Status = "Failed"
                    $RestoreResult.Message = $_.Exception.Message
                    $Result.RestoredFiles += $RestoreResult
                }
            }

            New-Message -Message "Restore process complete"
        }
    }

    End {
        return $Result
    }

}

Export-ModuleMember -Function Restore-RecycledItems