Merge pull request #48 from techthoughts2/Enhancements

Enhancements

Author: techthoughts2

.github/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0]
+
+- Adjusted error control and error return behavior - ***potential* breaking change**
+  - Previous behavior: any error (API error, validation error [size requirements, extension verification, etc.] would return a Boolean value: ```$false```)
+    - This behavior wasn't especially helpful and did not provide a lot of insight into what went wrong
+    - This behavior did not allow you to take any meaningful action if the API endpoint returned a certain error condition
+  - New behavior:
+    - Any validation error with ```throw``` for the failed validation
+    - Any API error will return as a PSObject containing the API exception
+      - Example 1:
+
+        ```powershell
+        ok      error_code description
+        --      ---------- -----------
+        False          401 Unauthorized
+        ```
+
+      - Example 2:
+
+        ```powershell
+        ok      error_code description                       parameters
+        --      ---------- -----------                       ----------
+        False          429 Too Many Requests: retry after 10 @{retry_after=10}
+        ```
+
+- General code style adjustments throughout the code-base
+- Build/dev improvements
+  - Bumped module versions to latest available
+  - Updated Pester tests from Pester 4 to Pester 5
+  - Updated CodeBuild to use latest version of PowerShell 7
+  - Added new functionality to ```tasks.json```
+  - Updated infra tests to have API back off capability
+
 ## [1.16.0]
 
 - String literals throughout PoshGram now use single quotes (') instead of double quotes (")
@@ -24,7 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Send-TelegramLocalAudio / Send-TelegramURLAudio
   - Audio now supports both MP3 and M4A file extensions
 - Send-TelegramDice
-  - Now supports soccer (footbal), and slot machine emoji
+  - Now supports soccer (football), and slot machine emoji
 - Send-TelegramLocalDocument / Send-TelegramURLDocument
   - Added DisableContentTypeDetection switch which disables automatic server-side content type detection
 - Send-TelegramPoll
@@ -33,9 +66,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Now supports both audio and document media group types
   - Restructured logic of this cmdlet to engage a new private function: Test-MediaGroupRequirements
 - Added more verbosity in verbose and warning outputs
-- Removed manifest releasenotes and linked changelog
+- Removed manifest release notes and linked changelog
 - Build Improvements
-  - Restructured private tests from one monolithic file to seperate private function tests
+  - Restructured private tests from one monolithic file to separate private function tests
   - Restructured test folder layout
   - Updated Windows CodeBuild container from 2016 to 2019
 
@@ -66,7 +99,7 @@ No Version Change
   - Bumped module versions to latest available
   - Replaced monolithic AWSPowerShell module with new AWS.Tools versions
   - Switched Windows Build container to use PowerShell 7 instead of PowerShell 7 preview
-  - Updated tasks.json to have better integration with InvokeBuild
+  - Updated ```tasks.json``` to have better integration with InvokeBuild
   - Switched Infra tests to use new AWS.Tools module
 
 ## [02/10/2020]
@@ -134,7 +167,7 @@ No Version Change
 
 No Version Change
 
-- Updated gitignore references
+- Updated ```.gitignore``` references
 - Updated README to reflect 6.1+ PowerShell version
 - Updated vscode settings for Stroustrup code formatting
 - Added Git community files

.gitignore

@@ -1,6 +1,7 @@
 Archive
 Artifacts
 cov.xml
+coverage.xml
 # OS generated files #
 ######################
 .DS_Store
@@ -9,4 +10,5 @@ cov.xml
 .Spotlight-V100
 .Trashes
 ehthumbs.db
-Thumbs.db
+Thumbs.db
+.pytest*

.vscode/tasks.json

@@ -4,9 +4,9 @@
 // ${workspaceRoot}: the root folder of the team
 // ${file}: the current opened file
 // ${relativeFile}: the current opened file relative to workspaceRoot
-// ${fileBasename}: the current opened file's basename
-// ${fileDirname}: the current opened file's dirname
-// ${fileExtname}: the current opened file's extension
+// ${fileBasename}: the current opened file\"s basename
+// ${fileDirname}: the current opened file\"s dirname
+// ${fileExtname}: the current opened file\"s extension
 // ${cwd}: the current working directory of the spawned process
 {
     "version": "2.0.0",
@@ -47,20 +47,26 @@
             }
         }
     },
+    "options": {
+        "env": {
+            // EDIT THE MODULE NAME FOR YOUR PROJECT
+            "MODULE_NAME": "PoshGram"
+        }
+    },
     "tasks": [
         {
             "label": "PesterTest",
             "type": "shell",
             "problemMatcher": [
                 "$pester"
             ],
-            "command": "Invoke-Pester '${workspaceFolder}/src/Tests/Unit' -PesterOption @{IncludeVSCodeMarker=$true}",
+            "command": "Invoke-Pester \"${workspaceFolder}/src/Tests/Unit\" -PesterOption @{IncludeVSCodeMarker=$true}",
         },
         {
             "label": ".",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "$PSVersionTable;Invoke-Build -Task . -File './src/PoshGram.build.ps1'",
+            "command": "$PSVersionTable;Invoke-Build -Task . -File ${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\"",
             "group": {
                 "kind": "build",
                 "isDefault": true
@@ -70,67 +76,98 @@
             "label": "TestLocal",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task TestLocal -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task TestLocal -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "HelpLocal",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task HelpLocal -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task HelpLocal -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "Clean",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task Clean -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task Clean -File \"${workspaceFolder}/src/$env:MODULE_NAME.build.ps1"
         },
         {
             "label": "ValidateRequirements",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task ValidateRequirements -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task ValidateRequirements -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "Analyze",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task Analyze -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task Analyze -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "AnalyzeTests",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task AnalyzeTests -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task AnalyzeTests -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "FormattingCheck",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task FormattingCheck -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task FormattingCheck -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "Test",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task Test -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task Test -File \"${workspaceFolder}/src/$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "DevCC",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task DevCC -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task DevCC -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "Build",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task Build -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task Build -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
+        },
+        {
+            "label": "BuildNoInfra",
+            "type": "shell",
+            "problemMatcher": "$msCompile",
+            "command": "Invoke-Build -Task BuildNoInfra -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
         },
         {
             "label": "InfraTest",
             "type": "shell",
             "problemMatcher": "$msCompile",
-            "command": "Invoke-Build -Task InfraTest -File './src/PoshGram.build.ps1'"
+            "command": "Invoke-Build -Task InfraTest -File \"${workspaceFolder}/src//$env:MODULE_NAME.build.ps1\""
+        },
+        {
+            "label": "Pester-Single-Coverage",
+            "type": "shell",
+            "command": "Import-Module -Name \"${workspaceFolder}\\src\\$env:MODULE_NAME\\$env:MODULE_NAME.psm1\";Invoke-Pester \"${workspaceFolder}\\src\\Tests\\Unit\\${input:functionName}.Tests.ps1\" -CodeCoverage \"${workspaceFolder}\\src\\$env:MODULE_NAME\\*\\${input:functionName}.ps1\"",
+            "problemMatcher": []
+        },
+        {
+            "label": "Pester-Single-Detailed",
+            "type": "shell",
+            "command": "Import-Module -Name \"${workspaceFolder}\\src\\$env:MODULE_NAME\\$env:MODULE_NAME.psm1\";Invoke-Pester \"${workspaceFolder}\\src\\Tests\\Unit\\${input:functionName}.Tests.ps1\" -Output Detailed",
+            "problemMatcher": []
+        },
+        {
+            "label": "DevCC-Single",
+            "type": "shell",
+            "problemMatcher": "$msCompile",
+            "command": "Import-Module -Name \"${workspaceFolder}\\src\\$env:MODULE_NAME\\$env:MODULE_NAME.psm1\";Invoke-Pester \"${workspaceFolder}\\src\\Tests\\Unit\\${input:functionName}.Tests.ps1\" -CodeCoverage \"${workspaceFolder}\\src\\$env:MODULE_NAME\\*\\${input:functionName}.ps1\" -CodeCoverageOutputFile \"${workspaceFolder}\\cov.xml\""
+        }
+    ],
+    "inputs": [
+        {
+            "type": "promptString",
+            "id": "functionName",
+            "description": "Name of PowerShell function you want to test"
         }
     ]
 }

README.md

@@ -50,7 +50,7 @@ PoshGram provides functionality to send various message types to a specified Tel
 
 ## Why
 
-The Telegram Bot API requires very specific formatting and criteria for Bot messaging. The goal of this project to abstract that complexity away in favor of simple and direct PowerShell commands.
+The Telegram Bot API requires very specific formatting and criteria for Bot messaging. The goal of this project is to abstract that complexity away in favor of simple and direct PowerShell commands.
 
 PoshGram also opens up several programmatic use cases:
 
@@ -176,7 +176,7 @@ $test = "I am a test"
 
 ## Author
 
-[Jake Morrison](https://twitter.com/JakeMorrison) - [https://techthoughts.info/](https://techthoughts.info/)
+[Jake Morrison](https://twitter.com/JakeMorrison) - [https://www.techthoughts.info/](https://www.techthoughts.info/)
 
 ## Contributors
 
@@ -187,7 +187,7 @@ $test = "I am a test"
 ## Notes
 
 * [PoshGram Video Demo](https://youtu.be/OfyRVl7YThw)
-* [PoshGram Blog Write-up](https://techthoughts.info/poshgram-powershell-module-for-telegram/)
+* [PoshGram Blog Write-up](https://www.techthoughts.info/poshgram-powershell-module-for-telegram/)
 
 For a description of the Bot API, see this page: [https://core.telegram.org/bots/api](https://core.telegram.org/bots/api)
 

actions_bootstrap.ps1

@@ -15,17 +15,17 @@ $modulesToInstall = [System.Collections.ArrayList]::new()
 # https://github.com/pester/Pester
 $null = $modulesToInstall.Add(([PSCustomObject]@{
             ModuleName    = 'Pester'
-            ModuleVersion = '4.10.1'
+            ModuleVersion = '5.3.1'
         }))
 # https://github.com/nightroman/Invoke-Build
 $null = $modulesToInstall.Add(([PSCustomObject]@{
             ModuleName    = 'InvokeBuild'
-            ModuleVersion = '5.6.1'
+            ModuleVersion = '5.8.4'
         }))
 # https://github.com/PowerShell/PSScriptAnalyzer
 $null = $modulesToInstall.Add(([PSCustomObject]@{
             ModuleName    = 'PSScriptAnalyzer'
-            ModuleVersion = '1.19.1'
+            ModuleVersion = '1.20.0'
         }))
 # https://github.com/PowerShell/platyPS
 # older version used due to: https://github.com/PowerShell/platyPS/issues/457

buildspec_windows.yml

@@ -8,8 +8,8 @@ phases:
   install:
     commands:
       - powershell -command '.\configure_aws_credential.ps1'
-      - aws s3 cp s3://ps-invoke-modules/PowerShell-7.1.0-win-x64.msi PowerShell-7.1.0-win-x64.msi --quiet
-      - powershell -command "Start-Process $env:CODEBUILD_SRC_DIR\PowerShell-7.1.0-win-x64.msi -ArgumentList '/qn /norestart' -Wait"
+      - aws s3 cp s3://ps-invoke-modules/PowerShell-7.1.4-win-x64.msi PowerShell-7.1.4-win-x64.msi --quiet
+      - powershell -command "Start-Process $env:CODEBUILD_SRC_DIR\PowerShell-7.1.4-win-x64.msi -ArgumentList '/qn /norestart' -Wait"
       - '& "C:\Program Files\PowerShell\7\pwsh.exe" -command ''.\install_modules.ps1'''
   pre_build:
     commands:

docs/Get-TelegramStickerPackInfo.md

@@ -69,13 +69,10 @@ For more information, see about_CommonParameters (http://go.microsoft.com/fwlink
 
 ## OUTPUTS
 
-### System.Management.Automation.PSCustomObject (if successful)
-### System.Boolean (on failure)
+### System.Management.Automation.PSCustomObject
 ## NOTES
-Author: Jake Morrison - @jakemorrison - https://techthoughts.info/
-This works with PowerShell Version: 6.1+
+Author: Jake Morrison - @jakemorrison - https://www.techthoughts.info/
 
-For a description of the Bot API, see this page: https://core.telegram.org/bots/api
 How do I get my channel ID?
 Use the getidsbot https://telegram.me/getidsbot  -or-  Use the Telegram web client and copy the channel ID in the address
 How do I set up a bot and get a token?
@@ -106,3 +103,5 @@ This will provide a link which contains the sticker pack name.
 
 [https://core.telegram.org/bots/api#sticker](https://core.telegram.org/bots/api#sticker)
 
+[https://core.telegram.org/bots/api](https://core.telegram.org/bots/api)
+

docs/PoshGram.md

@@ -2,7 +2,7 @@
 Module Name: PoshGram
 Module Guid: 277b92bc-0ea9-4659-8f6c-ed5a1dfdfda2
 Download Help Link: NA
-Help Version: 1.16.0
+Help Version: 2.0.0
 Locale: en-US
 ---
 

docs/Send-TelegramContact.md

@@ -155,13 +155,10 @@ For more information, see about_CommonParameters (http://go.microsoft.com/fwlink
 
 ## OUTPUTS
 
-### System.Management.Automation.PSCustomObject (if successful)
-### System.Boolean (on failure)
+### System.Management.Automation.PSCustomObject
 ## NOTES
-Author: Jake Morrison - @jakemorrison - https://techthoughts.info/
-This works with PowerShell Version: 6.1+
+Author: Jake Morrison - @jakemorrison - https://www.techthoughts.info/
 
-For a description of the Bot API, see this page: https://core.telegram.org/bots/api
 How do I get my channel ID?
 Use the getidsbot https://telegram.me/getidsbot  -or-  Use the Telegram web client and copy the channel ID in the address
 How do I set up a bot and get a token?
@@ -173,3 +170,5 @@ Use the BotFather https://t.me/BotFather
 
 [https://core.telegram.org/bots/api#sendcontact](https://core.telegram.org/bots/api#sendcontact)
 
+[https://core.telegram.org/bots/api](https://core.telegram.org/bots/api)
+

docs/Send-TelegramDice.md

@@ -120,13 +120,10 @@ For more information, see about_CommonParameters (http://go.microsoft.com/fwlink
 
 ## OUTPUTS
 
-### System.Management.Automation.PSCustomObject (if successful)
-### System.Boolean (on failure)
+### System.Management.Automation.PSCustomObject
 ## NOTES
-Author: Jake Morrison - @jakemorrison - https://techthoughts.info/
-This works with PowerShell Version: 6.1+
+Author: Jake Morrison - @jakemorrison - https://www.techthoughts.info/
 
-For a description of the Bot API, see this page: https://core.telegram.org/bots/api
 How do I get my channel ID?
 Use the getidsbot https://telegram.me/getidsbot  -or-  Use the Telegram web client and copy the channel ID in the address
 How do I set up a bot and get a token?
@@ -138,3 +135,5 @@ Use the BotFather https://t.me/BotFather
 
 [https://core.telegram.org/bots/api#senddice](https://core.telegram.org/bots/api#senddice)
 
+[https://core.telegram.org/bots/api](https://core.telegram.org/bots/api)
+