BluebirdPS: A Twitter Automation Client for PowerShell 7
Welcome to the online documentation for BluebirdPS, a Twitter automation client for PowerShell 7.
Work in Progress
Please consider this a work in progress. At this point, anything and everything could be changed.
Also, expect errors, though I have tried to keep those at minimum.
Community Project
This project is very much developed for the community and will gladly accept feedback from the community to make this module do what you need it to do, while adhering to the Twitter API design and PowerShell best practices.
What's New
The v0.6.1 release of BluebirdPS adds the following new features.
- Import-TwitterAuthentication will attempt to import authentication data from environment variables first before importing from the encrypted credentials file.
- Invoke-TwitterRequest progress bar for paged requests
- Added InvocationInfo to ResponseData and TotalVotes to Poll classes.
The v0.5.0 release of BluebirdPS packs a lot of new features and breaking changes from the previous release.
- Support for Twitter API v2: Early Access
- Complete management for:
- Saved searches
- List, list membership, and list subscriptions
- User friends (following) and followers
- User blocks, mutes, and spam reporting
- Tweet retweets, likes, and hiding individual replies
- A new configuration framework
- An updated command session history
- C# classes for most API responses, and for request generation and authentication
- Parameter consistency has been enforced, for example all references to the UserName instead of ScreenName and Id for the numerical identifier regardless of object type.
- Nearly 20 more commands than the previous release.
Examples
Search-Tweet -SearchString "(from:thedavecarroll)"
Get-Tweet -Id 1398279333823791104
Publish-Tweet -TweetText "A new release of #BluebirdPS will soon be released. BluebirdPS is #PowerShell 7 Twitter automation client. Check it out! https://bit.ly/BluebirdPS"
Get-TwitterList -Id 1397040831777984512 | Add-TwitterListMember -UserName thedavecarroll,BluebirdPS
BluebirdPS Technical Overview
BluebirdPS was written to provide simple commands to work with the Twitter API while adhering to PowerShell best practices. It largely obfuscates the endpoints from the user, though they certainly can take a peek under the hood with a few commands.
A framework consisting of configuration, request, authentication, and output objects allows commands to be easily crafted and updated.
Configuration
BluebirdPS configuration is created on module import, and updated through setting authentication or manual changes. It is exported to disk and imported on all future module imports.
The configuration provides instructions to commands on how to handle rate limits and whether the raw API response should be returned. It stores the authenticating user's Id and username which are required by some endpoints. Additionally, it contains the save locations for the configuration and credential files, as well as the last time authentication was verified and exported.
Building a Twitter Request
A Twitter API request has many parameters: the HTTP method/verb, the endpoint, a query, the authentication type, and potentially, body or form data.
BluebirdPS collects the values for all of these parameters into a [BluebirdPS.TwitterRequest]
class object and sends this to the Invoke-TwitterRequest
command.
Authentication
Connections to the Twitter API require authentication, which is provided by the [BluebirdPS.Authentication]
class object.
Depending on the endpoint, the request may require OAuth 1.0a, OAuth2 Bearer Token, or Basic authentication.
The request object contains the authentication type required for the particular endpoint.
When the authentication object is created, the request and appropriate credentials for the authentication type are used.
The authentication object is used to generate the authentication header, final URL, and HTTP method.
Sending the Twitter Request
Invoke-TwitterRequest
uses the authentication and request objects to generate the web request.
It then uses the PowerShell command Invoke-RestMethod
to make the API call.
The returned response, including response headers, the status code, and the request and authentication objects are used to created a new [BluebirdPS.ResponseData]
class object.
Response Data, History, Output Streams, and Exceptions
The response data object is sent to the Write-TwitterResponse
command.
This command performs the rate limit action when the threshold is reached, both based on configuration values.
Next, the command adds the response data to the module's session history table and writes the same data to the Information Stream.
If the configuration value for RawOutput is true, it returns the raw API output, which is a [PSCustomObject]
created by Invoke-RestMethod
's automatic conversion of JSON.
If the value is false, the api response is parsed based on the API version.
The command returns rich objects of various C# classes, simple string objects, or, when the parsing rules do not match the response, the raw response [PSCustomObject]
.
If there were errors returned, they are parsed and specific exceptions are thrown.
Rich Objects, C# Classes
The object model from both API versions was used as the basis for creating new C# classes.
All BluebirdPS classes use PascalCase
, instead of snake_case
which the API returns.
Most classes include a GetOriginalObject()
method which returns the original object received.
Pagination
The Invoke-TwitterRequest
command handles pagination for API v2 endpoints, and for API v1.1 endpoints that support the cursor
/next_cursor
pattern.
Command Verbs
The following table defines the command verbs that will be used by commands in this module.
Verb | Usage | Example |
---|---|---|
Get | Get a resource | Get-TwitterUser |
Set | Like, unlike, update, and others | Set-Tweet -Id 12345567896321478 -Like |
Add | Adding a new resource | Add-TwitterList -Name 'MyListName' -Description 'A cool description' -Mode Private |
Remove | Removing a resource | Remove-TwitterList -Id 1399719470894100485 |
Search | Text search for a user or Tweet | Search-Tweet -SearchString '#PSTweetChat' |
Publish | Tweet or Direct Message | Publish-Tweet -TweetText 'Check out this pic of #Snoopy' -MediaId $UploadedPic.media_id |
Unpublish | Delete Tweet or Direct Message | Unpublish-Tweet -Id 1399711831015428097 |
Send | Send media | Send-TwitterMedia -Path $PathToImage -Category TweetImage -AltImageText 'A bowl of froot loops' |
Submit | Submit a user as spam | Submit-TwitterUserAsSpam -User ASpammyAccount |
Export | Export config or credentials | Export-BluebirdPSConfiguration |
Import | Import config or credentials | Import-TwitterAuthentication |
Test | Test credentials and others | Test-TwitterAuthentication |
ConvertFrom | Convert from other time formats | ConvertFrom-EpochTime -UnixTime 1622554869 |
Invoke | Acts on the Twitter API | Invoke-TwitterRequest -RequestParameters $Request |
Things to Do
- Rate limit based waiting period per endpoint
- Once a rate limit has been reached for a given endpoint, validate current time against rate limit reset time before making the call.
- Configuration value to enable/disable.
- Expand build scripts
- Pester tests
- TweetText processor (currently there no check for length)
- Exploration of PIN-OAuth