# encoding: ascii
# api: powershell
# title: Send-HipChat
# description: Send a notification message to a HipChat room via a RESTful Call to the HipChat API V2 Atlassian requires a separate token for each room within HipChat!
# version: 6.1
# type: function
# author: Joerg Hochwald
# license: CC0
# x-poshcode-id: 6432
# x-archived: 2016-07-04T03:05:15
# x-published: 2016-07-01T04:38:00
#
# So please note, that the Room and the Token parameter must match.
#
#requires -Version 3

#region Info

<#
		#################################################
		# modified by     : Joerg Hochwald
		# last modified   : 2016-06-09
		#################################################

		Support: https://github.com/jhochwald/NETX/issues
#>

#endregion Info

#region License

<#
		Copyright (c) 2012-2016, NET-Experts <http:/www.net-experts.net>.
		All rights reserved.

		Redistribution and use in source and binary forms, with or without
		modification, are permitted provided that the following conditions are met:

		1. Redistributions of source code must retain the above copyright notice,
		this list of conditions and the following disclaimer.

		2. Redistributions in binary form must reproduce the above copyright notice,
		this list of conditions and the following disclaimer in the documentation
		and/or other materials provided with the distribution.

		3. Neither the name of the copyright holder nor the names of its
		contributors may be used to endorse or promote products derived from
		this software without specific prior written permission.

		THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
		AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
		IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
		ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
		LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
		CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
		SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
		INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
		CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
		ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
		THE POSSIBILITY OF SUCH DAMAGE.

		By using the Software, you agree to the License, Terms and Conditions above!
#>

#endregion License

function global:Send-HipChat {
	<#
			.SYNOPSIS
			Send a notification message to a HipChat room.

			.DESCRIPTION
			Send a notification message to a HipChat room via a RESTful Call to
			the HipChat API V2 Atlassian requires a separate token for each room
			within HipChat!

			So please note, that the Room and the Token parameter must match.

			.PARAMETER Token
			HipChat Auth Token

			.PARAMETER Room
			HipChat Room Name that get the notification.
			The Token has to fit to the Room!

			.PARAMETER notify
			Whether this message should trigger a user notification
			(change the tab color, play a sound, notify mobile phones, etc).
			Each recipient's notification preferences are taken into account.

			.PARAMETER color
			Background color for message.

			Valid is
			- yellow
			- green
			- red
			- purple
			- gray
			-random

			.PARAMETER Message
			The message body itself. Please see the HipChat API V2 documentation

			.PARAMETER Format
			Determines how the message is treated by our server and rendered
			inside HipChat applications

			.EXAMPLE
			PS C:\> Send-HipChat -Message "This is just a BuildServer Test" -color "gray" -Room "Testing" -notify $true

			Description
			-----------
			Sent a HipChat Room notification "This is just a BuildServer Test" to
			the Room "Testing".
			It uses the Color "gray", and it sends a notification to all users
			in the room.
			It uses a default Token to do so!

			.EXAMPLE
			PS C:\> Send-HipChat -Message "Hello @JoergHochwald" -color "Red" -Room "DevOps" -Token "1234567890" -notify $false

			Description
			-----------
			Sent a HipChat Room notification "Hello @JoergHochwald" to the
			Room "DevOps".
			The @ indicates a user mention, this is supported like in a regular
			chat from user 2 User.
			It uses the Color "red", and it sends no notification to users in
			the room.
			It uses a Token "1234567890" to do so! The Token must match the Room!

			.NOTES
			We use the API V2 now ;-)

			.LINK
			API: https://www.hipchat.com/docs/apiv2

			.LINK
			Docs: https://www.hipchat.com/docs/apiv2/method/send_room_notification

			.LINK
			NET-Experts http://www.net-experts.net

			.LINK
			Support https://github.com/jhochwald/NETX/issues
	#>

	[CmdletBinding()]
	param
	(
		[Parameter(HelpMessage = 'HipChat Auth Token')]
		[Alias('AUTH_TOKEN')]
		[System.String]$Token = '8EWA77eidxEJG5IFluWjD9794ft8WSzfKhjBCKpv',
		[Parameter(HelpMessage = 'HipChat Room Name that get the notification')]
		[Alias('ROOM_ID')]
		[System.String]$Room = 'Testing',
		[Parameter(HelpMessage = 'Whether this message should trigger a user notification.')]
		[boolean]$notify = $false,
		[Parameter(HelpMessage = 'Background color for message.')]
		[ValidateSet('yellow', 'green', 'red', 'purple', 'gray', 'random', IgnoreCase = $true)]
		[System.String]$color = 'gray',
		[Parameter(HelpMessage = 'The message body')]
		[ValidateNotNullOrEmpty()]
		[System.String]$Message,
		[Parameter(HelpMessage = 'Determines how the message is treated by our server and rendered inside HipChat applications')]
		[ValidateSet('html', 'text', IgnoreCase = $true)]
		[Alias('message_format')]
		[System.String]$Format = 'text'
	)

	BEGIN {
		# Cleanup all variables...
		Remove-Variable -Name 'headers' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name 'body' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name 'myBody' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name 'uri' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name 'myMethod' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		Remove-Variable -Name 'post' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
	}

	PROCESS {
		# Set the Header Variable
		Set-Variable -Name 'headers' -Value $(@{
				'Authorization' = "Bearer $($Token)"
				'Content-type' = 'application/json'
		})

		# Make the content of the Variable all lower case
		$color = $color.ToLower()
		$Format = $Format.ToLower()

		# Set the Body Variable, will be converted to JSON then
		Set-Variable -Name 'body' -Value $(@{
				'color'        = "$color"
				'message_format' = "$Format"
				'message'      = "$Message"
				'notify'       = "$notify"
		})

		# Convert the Body Variable to JSON Check if the Server understands Compression, could reduce bandwidth
		# Be careful with the Depth Parameter, bigger values means less performance
		Set-Variable -Name 'myBody' -Value $(ConvertTo-Json -InputObject $body -Depth 2 -Compress:$false)

		# Set the URI Variable based on the Atlassian HipChat API V2 documentation
		Set-Variable -Name 'uri' -Value $('https://api.hipchat.com/v2/room/' + $Room + '/notification')

		# Method to use for the RESTful Call
		Set-Variable -Name 'myMethod' -Value $('POST' -as ([System.String] -as [type]))

		# Use the API via RESTful call
		try {
			# We fake the User Agent here!
			(Invoke-RestMethod -Uri $uri -Method $myMethod -Headers $headers -Body $myBody -UserAgent "Mozilla/5.0 (Windows NT; Windows NT 6.1; en-US) NET-Experts WindowsPowerShell Service $CoreVersion" -ErrorAction:Stop -WarningAction:SilentlyContinue)
		} catch [System.Exception] {
			<#
					Argh! Catched an Exception...
			#>

			Write-Error -Message "Error: $($_.Exception.Message) - Line Number: $($_.InvocationInfo.ScriptLineNumber)"
		} catch {
			# Whoopsie!
			# That should not happen...
			Write-Warning -Message "Could not send notification to your HipChat Room $Room"
			<#
					I use Send-HipChat a lot within automated tasks.
					I post updates from my build server and info from customers Mobile Device Management systems.
					So I decided to use a warning instead of an error here.

					You might want to change this to fit you needs.

					Remember: If you throw an terminating error, you might want to add a "finally" block to this try/catch Block here.
			#>
		} finally {
			# Cleanup all variables...
			Remove-Variable -Name 'headers' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
			Remove-Variable -Name 'body' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
			Remove-Variable -Name 'myBody' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
			Remove-Variable -Name 'uri' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
			Remove-Variable -Name 'myMethod' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
			Remove-Variable -Name 'post' -Force -Confirm:$false -ErrorAction:SilentlyContinue -WarningAction:SilentlyContinue
		}
	}
}
