Add icon

ABMPS.psd1

@@ -12,7 +12,7 @@
     RootModule        = 'AppleBusinessManager.psm1'
 
     # Version number of this module.
-ModuleVersion = '1.1'
+    ModuleVersion     = '1.2'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()
@@ -51,7 +51,13 @@ PowerShellVersion = '7.0.0'
     # ProcessorArchitecture = ''
 
     # Modules that must be imported into the global environment prior to importing this module
-# RequiredModules = @()
+    RequiredModules   = @(
+        @{
+            ModuleName    = "jwtPS"
+            ModuleVersion = "1.1.3"
+            GUID          = "f89e3407-8e14-4fe5-80b9-64b1479e7142" 
+        }
+    )
 
     # Assemblies that must be loaded prior to importing this module
     # RequiredAssemblies = @()
@@ -98,13 +104,13 @@ PrivateData = @{
             Tags       = @('api', 'apple', 'applebusinessmanager')
 
             # A URL to the license for this module.
-        LicenseUri = 'https://scm.gruezi.net/buckbanzai/abmps/src/branch/main/LICENSE'
+            LicenseUri = 'https://scm.gruezi.net/buckbanzai/ABMPS/src/branch/main/LICENSE'
 
             # A URL to the main website for this project.
-        ProjectUri = 'https://scm.gruezi.net/buckbanzai/abmps'
+            ProjectUri = 'https://scm.gruezi.net/buckbanzai/ABMPS'
 
             # A URL to an icon representing this module.
-        # IconUri = ''
+            IconUri = 'https://scm.gruezi.net/buckbanzai/ABMPS/raw/branch/main/icon.png'
 
             # ReleaseNotes of this module
             # ReleaseNotes = ''

AppleBusinessManager.psm1

@@ -7,6 +7,12 @@ function Connect-AppleBusinessManager {
         [string][Parameter(ParameterSetName = 'PrivateKeyAsString', Mandatory)]$PrivateKey,
         [string][Parameter(ParameterSetName = 'PrivateKeyAsString', Mandatory)]$PrivateKeyId
     )
+
+    if ($PSBoundParameters.Count -eq 0) {
+        # Parameters were not bound, check to see if they're already set before attempting to authenticate
+        Write-Verbose "Checking to see if existing credentials were set at a script scope that can be re-used"
+        if (-not $Script:ClientId -or -not $Script:PrivateKey -or -not $Script:PrivateKeyId) {
+            Write-Verbose "Existing credentials not loaded, checking for environment variables"
             if ($PSCmdlet.ParameterSetName -eq 'EnvironmentVariable') {
                 if (-not $Env:AppleBusinessManagerClientId -or -not $Env:AppleBusinessManagerPrivateKeyId -or -not $Env:AppleBusinessManagerPrivateKey) {
                     throw "Client ID, Private Key ID and Private Key environment variables were not set for Apple Business Manager"
@@ -15,6 +21,16 @@ function Connect-AppleBusinessManager {
                 $Script:PrivateKey = $Env:AppleBusinessManagerPrivateKey
                 $Script:PrivateKeyId = $Env:AppleBusinessManagerPrivateKeyId
             }
+        }
+    }
+    
+    if ($PSCmdlet.ParameterSetName -eq 'PrivateKeyAsString') {
+        # Assign the parameters to script scope so we can reuse them later
+        $Script:ClientId = $ClientId
+        $Script:PrivateKey = $PrivateKey
+        $Script:PrivateKeyId = $PrivateKeyId
+    }
+
     $Header = @{
         'kid' = $Script:PrivateKeyId
     }
@@ -72,17 +88,93 @@ function Invoke-AppleBusinessManagerPagedApiRequest {
     )
     $Results = New-Object System.Collections.ArrayList
     while ($Uri) {
+        Write-Verbose "Making request to $Uri"
         $Result = Invoke-RestMethod $Uri -Authentication Bearer -Token (Get-AppleBusinessManagerBearerToken) -ErrorAction Stop
         $Uri = $Result.links.next
-        $Results.AddRange($Result.data) | Out-Null
+        $Results.AddRange(@($Result.data)) | Out-Null
     }
     return $Results
 }
 
-function Get-AppleBusinessManagerOrgDevices {
-    return Invoke-AppleBusinessManagerPagedApiRequest -Uri "https://api-business.apple.com/v1/orgDevices"
+function Get-AppleBusinessManagerOrgDevice {
+    [Alias('Get-AppleBusinessManagerOrgDevices')]
+    param (
+        [Parameter(Mandatory, ParameterSetName = 'Read')][string] $OrgDeviceId,
+        [Parameter(ParameterSetName = 'Read')]
+        [Parameter(ParameterSetName = 'List')]
+        [string[]] $Fields,
+        [Parameter( ParameterSetName = 'Read')]
+        [Parameter(ParameterSetName = 'List')]
+        [int] $Limit
+    )
+    $Uri = switch ($PSCmdlet.ParameterSetName) {
+        'Read' { "https://api-business.apple.com/v1/orgDevices/$([System.Web.HttpUtility]::UrlEncode($OrgDeviceId))" }
+        Default { "https://api-business.apple.com/v1/orgDevices" }
+    }
+    $UriBuilder = [System.UriBuilder]::new($Uri)
+    $QueryString = [System.Web.HttpUtility]::ParseQueryString($UriBuilder.Query)
+    if ($PSBoundParameters.ContainsKey('Fields')) {
+        $QueryString.Set('fields[orgDevices]', $Fields -join ',')
+    }
+    if ($PSBoundParameters.ContainsKey('Limit')) {
+        $QueryString.Set('limit', $Limit)
+    }
+    $UriBuilder.Query = $QueryString.ToString()
+    return Invoke-AppleBusinessManagerPagedApiRequest -Uri $UriBuilder.Uri
 }
 
-function Get-AppleBusinessManagerMdmServers {
-    return Invoke-AppleBusinessManagerPagedApiRequest -Uri "https://api-business.apple.com/v1/mdmServers"
+function Get-AppleBusinessManagerOrgDeviceMdmServerId {
+    param (
+        [Parameter(Mandatory)]
+        [string] $OrgDeviceId
+    )
+    return Invoke-AppleBusinessManagerPagedApiRequest -Uri "https://api-business.apple.com/v1/orgDevices/$([System.Web.HttpUtility]::UrlEncode($OrgDeviceId))/relationships/assignedServer"
+}
+
+function Get-AppleBusinessManagerOrgDeviceMdmServer {
+    param (
+        [Parameter(Mandatory)]
+        [string] $OrgDeviceId,
+        [string[]] $Fields
+    )
+    $UriBuilder = [System.UriBuilder]::new("https://api-business.apple.com/v1/orgDevices/$([System.Web.HttpUtility]::UrlEncode($OrgDeviceId))/assignedServer")
+    $QueryString = [System.Web.HttpUtility]::ParseQueryString($UriBuilder.Query)
+    if ($PSBoundParameters.ContainsKey('Fields')) {
+        $QueryString.Set('fields[mdmServers]', $Fields -join ',')
+    }
+    $UriBuilder.Query = $QueryString.ToString()
+    return Invoke-AppleBusinessManagerPagedApiRequest -Uri $UriBuilder.Uri
+}
+
+function Get-AppleBusinessManagerMdmServer {
+    [Alias('Get-AppleBusinessManagerMdmServers')]
+    param (
+        [string[]] $Fields,
+        [int] $Limit
+    )
+    $UriBuilder = [System.UriBuilder]::new("https://api-business.apple.com/v1/mdmServers")
+    $QueryString = [System.Web.HttpUtility]::ParseQueryString($UriBuilder.Query)
+    if ($PSBoundParameters.ContainsKey('Fields')) {
+        $QueryString.Set('fields[mdmServers]', $Fields -join ',')
+    }
+    if ($PSBoundParameters.ContainsKey('Limit')) {
+        $QueryString.Set('limit', $Limit)
+    }
+    $UriBuilder.Query = $QueryString.ToString()
+    return Invoke-AppleBusinessManagerPagedApiRequest -Uri $UriBuilder.Uri
+}
+
+function Get-AppleBusinessManagerMdmServerDevice {
+    param (
+        [Parameter(Mandatory)]
+        [string] $MdmServerId,
+        [int] $Limit
+    )
+    $UriBuilder = [System.UriBuilder]::new("https://api-business.apple.com/v1/mdmServers/$([System.Web.HttpUtility]::UrlEncode($MdmServerId))/relationships/devices")
+    $QueryString = [System.Web.HttpUtility]::ParseQueryString($UriBuilder.Query)
+    if ($PSBoundParameters.ContainsKey('Limit')) {
+        $QueryString.Set('limit', $Limit)
+    }
+    $UriBuilder.Query = $QueryString.ToString()
+    return Invoke-AppleBusinessManagerPagedApiRequest -Uri $UriBuilder.Uri
 }

README.md

@@ -1,4 +1,4 @@
-# Apple Business Manager API Module for PowerShell
+# <img src="icon.png" alt="A terminal caret with a prompt line, with a briefcase in a squircle" width="32"/> Apple Business Manager API Module for PowerShell
 PowerShell Module that authenticates and gets data from the Apple Business Manager APIs
 ## Installing the module
 This module can be installed [from the PowerShell Gallery][powershell-gallery] using the following command: