BaseApiBuilder

0.1.0-preview0001

BaseApiBuilder.psm1

#Region './prefix.ps1' -1

Add-Type -AssemblyName System.Web
Add-Type -AssemblyName System.Net.Http
#EndRegion './prefix.ps1' 3
#Region './Public/Close-ApiSession.ps1' -1

<#
.SYNOPSIS
Closes the current API session.

.DESCRIPTION
The Close-ApiSession function clears the current API session stored in a script-scoped variable, effectively ending the session. This is typically used to clean up session data after API interactions are complete.

.EXAMPLE
Close-ApiSession

This example demonstrates how to call the Close-ApiSession function to clear the current API session.

.NOTES
This function checks if the $script:apiSession variable is populated before attempting to clear it to prevent errors.

.LINK
Get-CurrentApiSession
Initialize-ApiSession

#>

function Close-ApiSession {
    if(-not $script:apiSession) {
        return
    }
    $script:apiSession.Clear()
}
#EndRegion './Public/Close-ApiSession.ps1' 28
#Region './Public/ConvertTo-PlainText.ps1' -1

<#
.SYNOPSIS
   Converts a PSCredential object's password to plain text.

.DESCRIPTION
   The ConvertTo-PlainText function takes a PSCredential object as input and converts the secure string password to plain text.

.PARAMETER Credential
   The PSCredential object whose password is to be converted to plain text. This is a mandatory parameter.

.EXAMPLE
   $cred = Get-Credential
   ConvertTo-PlainText -Credential $cred

   This example demonstrates how to use the ConvertTo-PlainText function. It first prompts the user for a username and password (Get-Credential), then converts the password to plain text.

.NOTES
   Be careful when using this function, as it can expose sensitive password information in plain text.
#>
function ConvertTo-PlainText {
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [System.Management.Automation.PSCredential]
        $Credential
    )

    try {
        $bstr = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($Credential.Password)
        $PlainTextPassword = [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($bstr)
    }
    finally {
        if ($null -ne $bstr) {
            [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($bstr)
        }
    }

    return $PlainTextPassword
}
#EndRegion './Public/ConvertTo-PlainText.ps1' 40
#Region './Public/Get-ApiWebSession.ps1' -1

<#
.SYNOPSIS
Retrieves the current API web session.

.DESCRIPTION
The Get-ApiWebSession function returns the web session object stored in a script-scoped variable. This session object can be used for making authenticated web requests to the API.

.EXAMPLE
$session = Get-ApiWebSession

This example demonstrates how to retrieve the current API web session and store it in a variable.

.NOTES
This function is part of the BaseApiBuilder module which provides a set of tools for interacting with RESTful APIs.

.LINK
Initialize-ApiSession - For initializing a new API session.
Close-ApiSession - For closing the current API session.
#>

Function Get-ApiWebSession {

    return $script:apiSession.WebSession

}
#EndRegion './Public/Get-ApiWebSession.ps1' 26
#Region './Public/Get-AuthHeaders.ps1' -1

<#
.SYNOPSIS
Retrieves the authentication headers for the current API session.

.DESCRIPTION
The Get-AuthHeaders function returns the authentication headers stored in a script-scoped variable. These headers are used for making authenticated requests to the API. If the authentication headers are not set, the function will throw an error instructing to initialize an authentication session.

.EXAMPLE
$headers = Get-AuthHeaders

This example demonstrates how to retrieve the authentication headers for the current API session.

.NOTES
This function is part of the BaseApiBuilder module which provides a set of tools for interacting with RESTful APIs. It requires an active authentication session initialized by calling Initialize-AuthSession.

.LINK
Initialize-AuthSession - For initializing the authentication session.
Close-ApiSession - For closing the current API session.

#>

function Get-AuthHeaders {
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseSingularNouns','')]
    [CmdletBinding()]
    param()
    if ($null -eq $script:apiSession.AuthHeaders) {
        Write-Error "Authentication is required. Please call Initialize-AuthSession."
        exit
    }
    return $script:apiSession.AuthHeaders
}
#EndRegion './Public/Get-AuthHeaders.ps1' 32
#Region './Public/Get-BaseUri.ps1' -1

<#
.SYNOPSIS
Retrieves the base URI for the current API session.

.DESCRIPTION
The Get-BaseUri function returns the base URI stored in a script-scoped variable if it has been set. If the base URI is not set, it throws an error instructing the user to initialize it using Set-BaseUri.

.EXAMPLE
$baseUri = Get-BaseUri

This example demonstrates how to retrieve the base URI for the current API session.

.NOTES
This function is part of the BaseApiBuilder module which provides a set of tools for interacting with RESTful APIs. It requires the base URI to be initialized before calling this function.

.LINK
Set-BaseUri - For initializing the base URI for the API session.

#>

function Get-BaseUri {
    [CmdletBinding()]
    param ()

    # Check if the apiSession is initialized and contains the BaseUrl
    if ($script:apiSession -and $script:apiSession.Contains("BaseUri") -and $null -ne $script:apiSession.BaseUri) {
        return $script:apiSession["BaseUri"]
    }
    else {
        Write-Error "BaseUri is not set. Please initialize it using Set-BaseUri."
        return $null
    }
}
#EndRegion './Public/Get-BaseUri.ps1' 34
#Region './Public/Get-CurrentApiSession.ps1' -1

<#
.SYNOPSIS
Retrieves the current API session.

.DESCRIPTION
The Get-CurrentApiSession function returns the current API session object stored in a script-scoped variable. This session object can be used to manage and maintain state across multiple API calls within the same session.

.EXAMPLE
$session = Get-CurrentApiSession

This example demonstrates how to retrieve the current API session and store it in a variable.

.NOTES
This function is part of the BaseApiBuilder module which provides a set of tools for interacting with RESTful APIs. It is essential for managing the lifecycle of an API session.

.LINK
Initialize-ApiSession - For initializing a new API session.
Close-ApiSession - For closing the current API session.
Get-ApiWebSession - For retrieving the web session object.
Get-AuthHeaders - For retrieving authentication headers for the current session.
#>

function Get-CurrentApiSession {
    return $script:apiSession
}
#EndRegion './Public/Get-CurrentApiSession.ps1' 26
#Region './Public/Initialize-ApiSession.ps1' -1

<#
.SYNOPSIS
    Initializes an API session by setting up web request headers, a user agent, and an optional base URI.

.DESCRIPTION
    The Initialize-ApiSession function sets up a session for interacting with APIs. It combines authentication and custom headers,
    sets a user agent, optionally configures a base URI, and initializes a web request session. It closes any existing API session
    before setting up a new one.

.PARAMETER BaseURI
    The base URI for the API. This is not mandatory but recommended if all requests will use the same base URI.

.PARAMETER AuthHeaders
    A hashtable of authentication headers. Default is an empty hashtable.

.PARAMETER CustomHeaders
    A hashtable of custom headers to be used in the API session. Default is an empty hashtable.

.PARAMETER UserAgent
    The user agent string to be used in the session. Defaults to "PowerShell API Client".

.PARAMETER WebSession
    An existing WebRequestSession object that can be reused. If not provided, a new session will be created.

.EXAMPLE
    $authHeaders = @{ "Authorization" = "Bearer your_token" }
    $session = Initialize-ApiSession -BaseURI "https://api.example.com" -AuthHeaders $authHeaders

.OUTPUTS
    Hashtable
    Returns a hashtable containing session details including time, base URI, authentication headers, and the web request session.
#>
function Initialize-ApiSession
{
    [CmdletBinding()]
    [OutputType([bool])]
    param (
        [Parameter(Mandatory = $false)]
        [string]$BaseURI,

        [Parameter()]
        [Hashtable]$AuthHeaders = @{},

        [Parameter()]
        [Hashtable]$CustomHeaders = @{},

        [Parameter()]
        [string]$UserAgent = "PowerShell API Client",

        [Parameter()]
        [Microsoft.PowerShell.Commands.WebRequestSession]$WebSession
    )

    Close-ApiSession

    $CombinedHeaders = $AuthHeaders + $CustomHeaders
    if ($UserAgent)
    {
        $CombinedHeaders["User-Agent"] = $UserAgent
    }

    if ($BaseURI)
    {
        #Set-BaseUri -Uri $BaseURI
    }

    if (-not $WebSession)
    {
        $WebSession = Initialize-WebRequestSession -Headers $CombinedHeaders
    }

    $hash = @{
        Time        = (Get-Date)
        BaseUri     = $BaseURI
        AuthHeaders = $AuthHeaders
        WebSession  = $WebSession
    }

    Set-CurrentApiSession -SessionHash $hash
    Write-Verbose "API session initialized successfully."

    return (Get-CurrentApiSession)
}
#EndRegion './Public/Initialize-ApiSession.ps1' 84
#Region './Public/Initialize-AuthSession.ps1' -1

<#
.SYNOPSIS
Initializes an authentication session for API calls.

.DESCRIPTION
The Initialize-AuthSession function is designed to create an authentication session using either an API key or user credentials. It returns a hashtable with the necessary authorization headers for making authenticated API requests. If an API key is provided, it uses Bearer authentication; otherwise, it uses Basic authentication with the provided credentials.

.PARAMETER ApiKey
The API key for Bearer authentication. This parameter is optional and mutually exclusive with the Credentials parameter.

.PARAMETER Credentials
The user credentials for Basic authentication. This parameter is optional and mutually exclusive with the ApiKey parameter.

.EXAMPLE
$authSession = Initialize-AuthSession -ApiKey 'your_api_key_here'
This example demonstrates how to initialize an authentication session using an API key.

.EXAMPLE
$creds = Get-Credential
$authSession = Initialize-AuthSession -Credentials $creds
This example demonstrates how to initialize an authentication session using user credentials.

.NOTES
This function requires either an ApiKey or Credentials parameter to be provided. If neither or both are provided, it will result in an error.

.LINK
Get-AuthHeaders - For retrieving authentication headers for the current session.
#>

function Initialize-AuthSession {
    [OutputType([hashtable])]
    [CmdletBinding()]
    param(
        [string]$ApiKey = $null,
        [PSCredential]$Credentials = $null
    )

    if ($ApiKey) {
        $authSession = @{ Authorization = "Bearer $ApiKey" }
        return $authSession
    }
    elseif ($Credentials) {
        if ($network) { $Pass = $($Credentials.GetNetworkCredential().Password) }
        else { $Pass = (ConvertTo-PlainText -Credential $Credentials) }
        $authSession = @{ Authorization = "Basic " + [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("$($Credentials.UserName):$($Pass)")) }
        return $authSession
    }
    else {
        Write-Error "No valid authentication method provided."
    }
}
#EndRegion './Public/Initialize-AuthSession.ps1' 52
#Region './Public/Initialize-WebRequestSession.ps1' -1

<#
.SYNOPSIS
    Initializes and returns a web request session object with custom headers and credentials.

.DESCRIPTION
    The Initialize-WebRequestSession function creates a new web request session, configuring it with optional headers,
    credentials, and a cookie container to manage cookies across requests. This session can be used with various
    cmdlets that require a WebRequestSession parameter.

.PARAMETER Headers
    A hashtable containing headers to be added to the web request session. Default is an empty hashtable.

.PARAMETER Credentials
    A PSCredential object containing user credentials for the web request session.

.EXAMPLE
    $headers = @{ "Authorization" = "Bearer token" }
    $creds = Get-Credential
    $session = Initialize-WebRequestSession -Headers $headers -Credentials $creds
    Invoke-WebRequest -Uri "https://example.com" -WebSession $session

.OUTPUTS
    Microsoft.PowerShell.Commands.WebRequestSession
    Returns a WebRequestSession object configured with headers, credentials, and cookie management.
#>
function Initialize-WebRequestSession
{
    [CmdletBinding()]
    param(
        [Parameter()]
        [hashtable]$Headers = @{},

        [Parameter()]
        [PSCredential]$Credentials
    )

    $session = New-Object Microsoft.PowerShell.Commands.WebRequestSession

    foreach ($key in $Headers.Keys)
    {
        $session.Headers.Add($key, $Headers[$key])
        Write-Verbose "Added header: $key with value: $($Headers[$key])"
    }

    if ($Credentials)
    {
        $session.Credentials = $Credentials
        Write-Verbose "Credentials set for the session."
    }

    $session.Cookies = New-Object System.Net.CookieContainer
    Write-Verbose "Cookie container initialized."

    # [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 | [Net.SecurityProtocolType]::Tls11 | [Net.SecurityProtocolType]::Tls
    Write-Verbose "Web request session object created."

    return $session
}
#EndRegion './Public/Initialize-WebRequestSession.ps1' 59
#Region './Public/New-ApiSession.ps1' -1

<#
.SYNOPSIS
Creates a new API session object.

.DESCRIPTION
The New-ApiSession function initializes a new, empty API session object as a script-scoped hashtable. This session object is used to store session-specific information such as authentication headers, base URI, and other relevant data for making API calls.

.EXAMPLE
New-ApiSession

This example demonstrates how to create a new API session object.

.NOTES
This function is part of the BaseApiBuilder module which provides a set of tools for interacting with RESTful APIs. It is the first step in establishing a session for API interactions.

#>

function New-ApiSession {
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param ()

    $script:apiSession = @{}

}
#EndRegion './Public/New-ApiSession.ps1' 26
#Region './Public/New-ApiUri.ps1' -1

<#
.SYNOPSIS
Creates a new API URI based on base URI, endpoint, and query parameters.

.DESCRIPTION
The New-ApiUri function constructs a complete URI for API calls. It takes a base URI, an endpoint, and an optional hashtable of query parameters, then returns the constructed URI. If query parameters include nested hashtables, they are converted into a filter string format.

.PARAMETER BaseUri
The base URI of the API.

.PARAMETER Endpoint
The specific endpoint to be appended to the base URI.

.PARAMETER QueryParams
An optional hashtable of query parameters to be appended to the URI. Supports nested hashtables for complex filters.

.EXAMPLE
$baseUri = "https://api.example.com"
$endpoint = "data"
$queryParams = @{ "filter" = "active"; "sort" = "name" }
$uri = New-ApiUri -BaseUri $baseUri -Endpoint $endpoint -QueryParams $queryParams

This example constructs a URI for the "data" endpoint on "https://api.example.com", with a filter for active items and sorting by name.

.NOTES
This function is part of a PowerShell module designed to simplify API interactions by generating URIs dynamically based on provided parameters.

.LINK
- Get-AuthHeaders - For retrieving authentication headers for API calls.
- Initialize-ApiSession - For initializing a new API session.
#>

function New-ApiUri
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param(
        [string]$BaseUri,
        [string]$Endpoint,
        [hashtable]$QueryParams
    )

    $uriBuilder = New-Object System.UriBuilder $BaseUri
    $uriBuilder.Path += $Endpoint

    # Build the query string from the hashtable
    $query = $QueryParams.GetEnumerator() | Where-Object {
        # Exclude null or empty values
        $null -ne $_.Value -and ($_.Value -isnot [string] -or -not [string]::IsNullOrEmpty($_.Value))
    } | ForEach-Object {
        $key = [Uri]::EscapeDataString($_.Key)
        $value = $_.Value

        # Handle complex filters stored in a nested hashtable
        if ($value -is [hashtable])
        {
            # Convert hashtable to a filter string (e.g., "key1='value1' and key2='value2'")
            $filterConditions = $value.GetEnumerator() | Where-Object {
                $null -ne $_.Value -and ($_.Value -isnot [string] -or -not [string]::IsNullOrEmpty($_.Value))
            } | ForEach-Object {
                $filterKey = $_.Key
                $filterValue = $_.Value
                "$filterKey='$filterValue'"
            }
            $value = $filterConditions -join ' and '
        }

        # Prepare the key-value pair for the query string if not empty
        if (-not [string]::IsNullOrEmpty($value))
        {
            $value = [Uri]::EscapeDataString($value)
            "$key=$value"
        }
    }

    # Only join non-empty entries
    $uriBuilder.Query = ($query | Where-Object { $_ }) -join '&'

    # Return the complete URI
    return $uriBuilder.Uri.AbsoluteUri
}
#EndRegion './Public/New-ApiUri.ps1' 82
#Region './Public/Set-BaseUri.ps1' -1

<#
.SYNOPSIS
Sets the base URI for API calls.

.DESCRIPTION
The Set-BaseUri function is used to set the base URI for subsequent API calls. It stores the base URI in a script-scoped variable for use by other functions in the module.

.PARAMETER Uri
The base URI to be used for API calls. This parameter is mandatory.

.EXAMPLE
Set-BaseUri -Uri "https://api.example.com"

This example sets the base URI to "https://api.example.com" for all subsequent API calls.

.NOTES
This function is part of a PowerShell module designed to simplify interactions with RESTful APIs by managing session state, including authentication and base URIs.

.LINK
- Initialize-AuthSession - For initializing the authentication session.
- New-ApiSession - For creating a new API session object.
#>

function Set-BaseUri {
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]$Uri
    )

    # Ensure the apiSession variable is initialized
    if (-not $script:apiSession) {
        $script:apiSession = @{}
    }

    # Set the BaseUrl in the apiSession
    $script:apiSession["BaseUri"] = $Uri
    Write-Verbose "BaseUri set to: $Uri"
}
#EndRegion './Public/Set-BaseUri.ps1' 41
#Region './Public/Set-CurrentApiSession.ps1' -1

<#
.SYNOPSIS
    Sets the current API session to a specified session hash.

.DESCRIPTION
    The Set-CurrentApiSession function updates the global variable $script:apiSession with a new session hash.
    This session hash typically includes session details such as the base URI, headers, and other configurations.

.PARAMETER SessionHash
    A hashtable containing the session details to be set as the current API session.

.EXAMPLE
    $sessionDetails = @{
        Time = (Get-Date)
        BaseUri = 'https://api.example.com'
        AuthHeaders = @{ Authorization = "Bearer your_token_here" }
    }
    Set-CurrentApiSession -SessionHash $sessionDetails
    This example sets the current API session to the specified session details.

.OUTPUTS
    None. This function updates a global variable and does not output directly.

.NOTES
    This function is typically used in scripts where API session details need to be maintained across multiple function calls.
#>
function Set-CurrentApiSession
{
    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $True)]
        [hashtable]$SessionHash
    )

    $script:apiSession = $SessionHash
    Write-Verbose "API session updated successfully."
}
#EndRegion './Public/Set-CurrentApiSession.ps1' 39
#Region './Public/Test-ApiSession.ps1' -1

<#
.SYNOPSIS
Tests the current API session for validity and throws an error if the session is invalid.

.DESCRIPTION
The Test-ApiSession function checks if the current API session is initialized and if the web session within it is valid. If either condition is not met, the function throws an error that stops execution, indicating that the API session is not valid. This behavior ensures that subsequent API operations are not attempted on an invalid session.

.EXAMPLE
try {
    Test-ApiSession
    # Additional code to run on a valid session
} catch {
    Write-Error "Session validation failed: $_"
}

This example demonstrates how to call the Test-ApiSession function within a try/catch block to handle possible errors from an invalid API session.

.NOTES
This function is part of a PowerShell module designed to manage API sessions. It is crucial to use this function to ensure that an API session is properly initialized and valid before attempting to make API calls. The function will halt script execution if the session is found to be invalid.

.LINK
- Get-CurrentApiSession - For retrieving the current API session.
- New-ApiSession - For creating a new API session.
#>

function Test-ApiSession {
    [CmdletBinding()]
    [OutputType([void])]
    param ()

    $functionName = $(($MyInvocation.MyCommand).Name)
    $VerbosePrefix = "[${functionName}] -"

    # Check if the API session is initialized
    $currentSession = Get-CurrentApiSession
    if (-not $currentSession) {
        Write-Verbose "$VerbosePrefix API session is not initialized."
        Throw "API session is not initialized."
    }

    # Check if the web session is valid
    if (-not $currentSession.WebSession) {
        Write-Verbose "$VerbosePrefix Web session is not valid."
        Throw "Web session is not valid."
    }

    Write-Verbose "API session is valid."
}
#EndRegion './Public/Test-ApiSession.ps1' 49