diff --git a/CHANGELOG.md b/CHANGELOG.md index 63ed2b3..3579c69 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Removed +## [0.0.4] - 2026-03-31 + + - Added the following functions; Get-BoxCollaboration, Set-Box Collaboration, Remove-BoxCollaboration. + Get-BoxCollaboration: Returns information about a specific collaborator + Set-BoxCollaboration: Changes an existing role for a collaborator + Remove-BoxCollaboration: Removes an existing Collaborator + ## [0.0.3] - 2026-03-25 -README Fixes, updated functions list to reflect proper available functions diff --git a/src/UofIBox/UofIBox.psd1 b/src/UofIBox/UofIBox.psd1 index c82fc18..59a27eb 100644 --- a/src/UofIBox/UofIBox.psd1 +++ b/src/UofIBox/UofIBox.psd1 @@ -10,7 +10,7 @@ RootModule = 'UofIBox.psm1' # Version number of this module. -ModuleVersion = '1.0.0' +ModuleVersion = '1.0.1' # Supported PSEditions # CompatiblePSEditions = @() @@ -78,7 +78,10 @@ FunctionsToExport = @( 'Receive-BoxFolder', 'Remove-BoxFolder', 'Remove-BoxFile', - 'Send-BoxFile' + 'Send-BoxFile', + 'Get-BoxCollaboration', + 'Set-BoxCollaboration', + 'Remove-BoxCollaboration' ) diff --git a/src/UofIBox/functions/public/Get-BoxCollaboration.ps1 b/src/UofIBox/functions/public/Get-BoxCollaboration.ps1 new file mode 100644 index 0000000..94d2c2e --- /dev/null +++ b/src/UofIBox/functions/public/Get-BoxCollaboration.ps1 @@ -0,0 +1,60 @@ +<# +.SYNOPSIS +Retrieves collaborators for a Box folder. + +.DESCRIPTION +Gets all collaborators assigned to a folder, including their roles and status. +Supports pagination to return all collaborators. + +.PARAMETER FolderId +ID of the folder. + +.EXAMPLE +Get-BoxCollaboration -FolderId 123456 + +.EXAMPLE +Get-BoxCollaboration -FolderId 123456 | Select-Object login, role +#> + +function Get-BoxCollaboration { + + [CmdletBinding()] + param( + [Parameter(Mandatory)] + [string]$FolderId + ) + + $Limit = 100 + $Offset = 0 + $Results = @() + + do { + + $Call = @{ + RelativeURI = "folders/$FolderId/collaborations?limit=$Limit&offset=$Offset" + Method = "GET" + } + + $Response = Invoke-BoxRestCall @Call + + if ($Response.entries) { + $Results += $Response.entries + } + + $Offset += $Limit + + } while ($Response.entries.Count -eq $Limit) + + # Clean output + $Results | ForEach-Object { + [PSCustomObject]@{ + Id = $_.id + Login = $_.accessible_by.login + Name = $_.accessible_by.name + Role = $_.role + Status = $_.status + CreatedAt = $_.created_at + ModifiedAt = $_.modified_at + } + } +} diff --git a/src/UofIBox/functions/public/Remove-BoxCollaboration.ps1 b/src/UofIBox/functions/public/Remove-BoxCollaboration.ps1 new file mode 100644 index 0000000..601b781 --- /dev/null +++ b/src/UofIBox/functions/public/Remove-BoxCollaboration.ps1 @@ -0,0 +1,51 @@ +<# +.SYNOPSIS +Removes a collaborator from a Box folder. + +.DESCRIPTION +Deletes a collaboration by Collaboration ID. Supports pipeline input +from Get-BoxCollaboration. + +.PARAMETER CollaborationId +ID of the collaboration to remove. + +.EXAMPLE +Remove-BoxCollaboration -FolderId 123456 -CollaborationId 123456 + +.EXAMPLE +Get-BoxCollaboration -FolderId 123456 | + Where-Object Role -eq "viewer" | + Remove-BoxCollaboration -WhatIf +#> + +function Remove-BoxCollaboration { + + [CmdletBinding(SupportsShouldProcess)] + param( + [Parameter( + Mandatory, + ValueFromPipelineByPropertyName + )] + [Alias("Id")] + [string]$CollaborationId + ) + + process { + + if (-not $CollaborationId) { + throw "CollaborationId cannot be null or empty." + } + + $Target = "Collaboration ID: $CollaborationId" + + if ($PSCmdlet.ShouldProcess($Target, "Remove collaborator")) { + + $Call = @{ + RelativeURI = "collaborations/$CollaborationId" + Method = "DELETE" + } + + Invoke-BoxRestCall @Call + } + } +} diff --git a/src/UofIBox/functions/public/Set-BoxCollaboration.ps1 b/src/UofIBox/functions/public/Set-BoxCollaboration.ps1 new file mode 100644 index 0000000..43eb3cc --- /dev/null +++ b/src/UofIBox/functions/public/Set-BoxCollaboration.ps1 @@ -0,0 +1,68 @@ +<# +.SYNOPSIS +Updates a Box collaboration role. + +.DESCRIPTION +Modifies an existing collaboration, typically to change the user's role. + +.PARAMETER CollaborationId +ID of the collaboration. + +.PARAMETER Role +New role to assign. + +.EXAMPLE +Get-BoxCollaboration -FolderId 123456 | + Where-Object Login -eq "user@company.com" | + Set-BoxCollaboration -Role co-owner +#> + +function Set-BoxCollaboration { + + [CmdletBinding(SupportsShouldProcess)] + param( + [Parameter( + Mandatory, + ValueFromPipelineByPropertyName + )] + [Alias("Id")] + [string]$CollaborationId, + + [Parameter(Mandatory)] + [ValidateSet( + "editor", + "viewer", + "previewer", + "uploader", + "previewer uploader", + "viewer uploader", + "co-owner", + "owner" + )] + [string]$Role + ) + + process { + + if (-not $CollaborationId) { + throw "CollaborationId cannot be null or empty." + } + + $Target = "Collaboration ID: $CollaborationId" + + if ($PSCmdlet.ShouldProcess($Target, "Update role to '$Role'")) { + + $Body = @{ + role = $Role + } + + $Call = @{ + RelativeURI = "collaborations/$CollaborationId" + Method = "PUT" + Body = $Body + } + + Invoke-BoxRestCall @Call + } + } +}