trycourier 1.0.2 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23f5a0957ead43adbaf9f97c33e6236149902be1df820f120214515d36a2d26b
-  data.tar.gz: 304eff5f123c7adf297bb6e4b1d3a2eb620295bc3a9c2e254e2f369ba194befe
+  metadata.gz: 2e2e7e6f4ad2900f3ad0d118062208c74492851e96976da6795c6309c95ad9ea
+  data.tar.gz: ce78409870df6608de59bc5ea4a628732b09f8d3ec7b304202f1721d07ff5836
 SHA512:
-  metadata.gz: 5423807878697faef75fd27e31aee0dd43ce669f176275d6b321d57f03b38736c5a96d1ad9a0baff93c6f83442b22f1fe80efce496de6e6c0f1dd3bbdb8cbae8
-  data.tar.gz: db0ad387345128716957853b682c0f6639e6a4f14978b7787383228ee76bcccbe97837b8503a840c68bdbe4e18d5d3e078920a21c2ded5a8125c1689031132a5
+  metadata.gz: 060ff6e98ab2a50557b9e54cf2e1fe2f13d02a4569e335f4ffe31c7bd8fa55c8bbcaef7df686c19c9c98ae0c032e024ba6bc705242bc4df5f26bd9c780174538
+  data.tar.gz: fd9c70f99624a1d82e3a0c6825b17cea6526a0d8c46e0a221c8740514e366851ba59854454919f723cd8a3b205ae8800462fe8965fe05aab9fb2dafe667b0333

data/.github/workflows/gem-push.yml

@@ -0,0 +1,51 @@
+name: Ruby Gem
+
+on:
+  push:
+    branches: [master]
+    tags:
+      - v*
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        ruby-version: ['2.7', '3.0', '3.1', 'head']
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+      - name: Run tests
+        # Skipping rubocop for now
+        # run: bundle exec rake
+        run: bundle exec rspec spec
+  build:
+    name: Build + Publish
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 2.7
+      - name: Publish to RubyGems
+        run: |
+          mkdir -p $HOME/.gem
+          touch $HOME/.gem/credentials
+          chmod 0600 $HOME/.gem/credentials
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > $HOME/.gem/credentials
+          gem build *.gemspec
+          gem push *.gem
+        env:
+          GEM_HOST_API_KEY: "${{secrets.RUBYGEMS_AUTH_TOKEN}}"

data/CHANGELOG.md

@@ -0,0 +1,100 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased][unreleased]
+
+## [v1.4.0] - 2022-01-31
+
+### Added
+
+- Support for enhanced Send API by @tk26
+
+## [v1.3.0] - 2022-01-26
+
+### Added
+
+- Support for Bulk API by @tk26
+
+## [v1.2.0] - 2021-04-08
+
+### Added
+
+- Support for [Automation API](https://docs.courier.com/reference/automation-api) by @tk26
+  - `POST /automations/invoke` with `client.automations.invoke` method
+  - `POST /automations/{template_id}/invoke` with `client.automations.invoke_template` method
+
+## [v1.1.0] - 2021-01-26
+
+### Added
+
+- Support for Basic Auth
+  - ENV variables `COURIER_AUTH_USERNAME` and `COURIER_AUTH_PASSWORD` OR set with params
+- Token Auth using ENV variables
+  - `COURIER_AUTH_TOKEN`
+- Base URL parameter (with default of api.courier.com)
+  - ENV variable `COURIER_BASE_URL`
+- Support for Lists API by @jrweingart
+
+  - `POST /send/list` with `client.lists.send` method
+  - `GET /lists` with `client.lists.list` method
+  - `GET /lists/{list_id}` with `client.lists.get` method
+  - `PUT /lists/{list_id}` with `client.lists.put` method
+  - `DELETE /lists/{list_id}` with `client.lists.delete` method
+  - `PUT /lists/{list_id}/restore` with `client.lists.restore` method
+  - `GET /lists/{list_id}/subscriptions` with `client.lists.get_subscriptions` method
+  - `PUT /lists/{list_id}/subscriptions` with `client.lists.put_subscriptions` method
+  - `PUT /lists/{list_id}/subscriptions/{recipient_id}` with `client.lists.subscribe` method
+  - `DELETE /lists/{list_id}/subscriptions/{recipient_id}` with `client.lists.unsubscribe` method
+
+- Support for Profiles API by @jrweingart
+
+  - `GET /profiles/{recipient_id}` with `client.profiles.get` method
+  - `GET /profiles/{recipient_id}/lists` with `client.profiles.get_subscriptions` method
+  - `PUT /profiles/{recipient_id}` with `client.profiles.replace` and `client.profiles.add` methods
+  - `PATCH /profiles/{recipient_id}` with `client.profiles.patch` method
+  - `POST /profiles/{recipient_id}` with `client.profiles.merge` method
+
+- Support for Messages API by @jrweingart
+
+  - `GET /messages` with `client.messages.list` method
+  - `GET /messages/{message_id}` with `client.messages.get` method
+  - `GET /messages/{message_id}/history` with `client.messages.get_history` method
+
+- Support for Events API by @jrweingart
+
+  - `GET /events` with `client.events.list` method
+  - `GET /events/{event_id}` with `client.event.get` method
+  - `PUT /events/{event_id}` with `client.events.replace` and `client.events.add` methods
+
+- Support for Brands API by @jrweingart
+  - `GET /brands` with `client.brands.list` method
+  - `GET /brands/brand_id` with `client.brands.get` method
+  - `POST /brands` with `client.brands.create` method
+  - `PUT /brands/brand_id` with `client.brands.replace` method
+  - `DELETE /brands/brand_id` with `client.brands.delete` method
+
+## [v1.0.2] - 2021-01-06
+
+### Added
+
+- Minor bug fixes to ensure proper SSL certification by @scarney81
+
+## [v1.0.1] - 2020-03-04
+
+### Added
+
+- Support for Send API by @troy
+
+## v1.0.0 - 2020-03-03
+
+Initial release by @troygoode
+
+[unreleased]: https://github.com/trycourier/courier-ruby/compare/v1.4.0...HEAD
+[v1.4.0]: https://github.com/trycourier/courier-ruby/compare/v1.3.0...v1.4.0
+[v1.3.0]: https://github.com/trycourier/courier-ruby/compare/v1.2.0...v1.3.0
+[v1.2.0]: https://github.com/trycourier/courier-ruby/compare/v1.1.0...v1.2.0
+[v1.1.0]: https://github.com/trycourier/courier-ruby/compare/v1.0.2...v1.1.0
+[v1.0.2]: https://github.com/trycourier/courier-ruby/compare/v1.0.1...v1.0.2
+[v1.0.1]: https://github.com/trycourier/courier-ruby/compare/v1.0.0...v1.0.1

data/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/trycourier/courier-ruby
+
+## Local development
+
+- Fork this repository
+- Clone your fork
+- Run `bundle install`
+- Write code!
+- Test your code using `bundle exec rspec spec`
+
+## Releasing New Versions
+
+To publish Courier Ruby to RUBYGEMS.ORG
+
+- Update the CHANGELOG.md
+- Bump the package version in `lib/trycourier/version.rb`
+- Submit a PR to merge changes into main
+- Create and push a new version tag
+
+  ```bash
+  git tag -a v<VERSION> -m v<VERSION>
+  git push origin v<VERSION>
+  ```
+
+- Wait for GitHub Action to test and deploy
+- Confirm you are able to successfully install the new version by running `gem install trycourier`

data/Gemfile

@@ -5,3 +5,4 @@ gemspec
 
 gem "rake", "~> 12.0"
 gem "rspec", "~> 3.0"
+gem "standard", group: [:development, :test]

data/Gemfile.lock

@@ -1,26 +1,62 @@
 PATH
   remote: .
   specs:
-    trycourier (1.0.2)
+    trycourier (1.4.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    diff-lcs (1.3)
+    addressable (2.8.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    ast (2.4.2)
+    crack (0.4.5)
+      rexml
+    diff-lcs (1.5.0)
+    hashdiff (1.0.1)
+    parallel (1.21.0)
+    parser (3.1.0.0)
+      ast (~> 2.4.1)
+    public_suffix (4.0.6)
+    rainbow (3.1.1)
     rake (12.3.3)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.1)
-      rspec-support (~> 3.9.1)
-    rspec-expectations (3.9.0)
+    regexp_parser (2.2.0)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.2)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.2)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.3)
+    rubocop (1.25.0)
+      parallel (~> 1.10)
+      parser (>= 3.1.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.15.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.15.1)
+      parser (>= 3.0.1.1)
+    rubocop-performance (1.13.2)
+      rubocop (>= 1.7.0, < 2.0)
+      rubocop-ast (>= 0.4.0)
+    ruby-progressbar (1.11.0)
+    standard (1.7.0)
+      rubocop (= 1.25.0)
+      rubocop-performance (= 1.13.2)
+    unicode-display_width (2.1.0)
+    webmock (3.14.0)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   ruby
@@ -28,7 +64,9 @@ PLATFORMS
 DEPENDENCIES
   rake (~> 12.0)
   rspec (~> 3.0)
+  standard
   trycourier!
+  webmock (>= 1.24.2)
 
 BUNDLED WITH
-   2.1.4
+   2.2.15

data/README.md

@@ -20,33 +20,405 @@ Or install it yourself as:
 
 ## Usage
 
+After installing, make sure to include this line at the top of your ruby file:
+
 ```ruby
 require "trycourier"
+```
+
+To create a Courier Ruby client, all you need to do is pass in your authentication information. Then, you can start sending!
+
+### Using token authentication (most secure)
+
+```ruby
+client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var (recommended)
+```
+
+### Using basic authentication
+
+```ruby
+client = Courier::Client.new(username: "USERNAME", password: "PASSWORD") # or set via COURIER_AUTH_USERNAME and COURIER_AUTH_PASSWORD env vars
+```
+
+### Sending a message to an individual recipient
 
-begin
-  client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
-  res = client.send({
+```ruby
+client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
+res = client.send({
     "event" => "your-event-id",
     "recipient" => "your-recipient-id",
 
-    "profile" => {
+    "profile" => { #optional (include any key-value pairs required by your chosen integrations. This information can also be stored in the recipient's profile in Courier)
       "email": "example@example.com",
       "phone_number": "555-867-5309"
     },
 
-    "data" => {
+    "data" => { #any data you want to pass to a message template
       "world" => "Ruby!"
     }
   })
+  puts res.code # the HTTP response code
+  puts res.message_id # if the code is 200, this will be the Courier message ID for this notification
+rescue Courier::CourierAPIError => re #error sent from from the API
+  puts re.message
+end
+```
+
+## Advanced Usage
 
+### Send API enhanced
+
+```ruby
+client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
+res = client.send_message({
+    message => {
+      template => "my-template",
+      to => {
+        email => "foo@bar.com"
+      }
+    }
+  })
   puts res.code # the HTTP response code
-  puts res.message_id # if 200, this will be the Courier message ID for this notification
-rescue Courier::ResponseError => re
+  puts res.request_id # if the code is 202, this will be the Courier request ID for this message
+rescue Courier::CourierAPIError => re #error sent from from the API
   puts re.message
-rescue Courier::InputError => ie
-  puts ie.message
 end
+```
+
+### Lists
+
+```ruby
+require "trycourier"
+client = Courier::Client.new "your-auth-token" # or set via COURIER_AUTH_TOKEN env var
+
+"""
+Creating a List
+"""
+res = client.lists.put(list_id, name)
+puts res
+
+"""
+Example: send a message to a list
+"""
+resp = client.lists.send(
+  event: "your-event-id",
+  list: "your.list.id",
+  brand: "your-brand-id", # optional
+  data: {}, # optional
+  override: {} # optional
+)
+puts resp['messageId'])
+
+"""
+Example: send a message to a list pattern
+"""
+resp = client.lists.send(
+  event: "your-event-id",
+  pattern: "your.list.*", #PATTERN (will send to all list ids that start with "your.list.")
+  brand: "your-brand-id", # optional
+  data: {}, # optional
+  override: {} # optional
+)
+puts resp['messageId'])
 
+"""
+Example: get all lists
+"""
+resp = client.lists.list(
+  cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
+)
+puts resp
+
+"""
+Example: get a specific list
+"""
+resp = client.lists.get(list_id: "your-list-id")
+puts resp
+
+
+"""
+Example: delete a list
+"""
+client.lists.delete(list_id: "your-list-id")
+
+"""
+Example: restore a list
+"""
+client.lists.restore(list_id: "your-list-id")
+
+"""
+Example: get a list's subscribptions
+"""
+resp = client.lists.get_subscriptions(list_id: "your-list-id",
+  cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
+)
+puts resp
+
+"""
+Example: replace many recipients to a new or existing list
+"""
+client.lists.put_subscriptions(list_id: "your-list-id", recipients: [
+  "RECIPIENT_ID_1",
+  "RECIPIENT_ID_2"
+])
+
+"""
+Example: Example: subscribe single recipient to a new or existing list
+"""
+client.lists.subscribe(list_id: "your-list-id", recipient_id: "your-recipient-id")
+
+"""
+Example: unsubscribe recipient from list
+"""
+client.lists.unsubscribe(list_id: "your-list-id", recipient_id: "your-recipient-id")
+```
+
+### Profiles
+
+```Ruby
+"""
+Example: create a recipient's profile
+"""
+resp = client.profiles.add(
+  recipient_id: "your-recipient-id",
+  profile: {
+    "email" => "example@example.com",
+    "name" => "Example Name"
+  }
+)
+
+"""
+Example: replace or create a recipient's profile
+"""
+resp = client.profiles.replace(
+  recipient_id: "your-recipient-id",
+  profile: {
+    "email" => "example@example.com"
+  }
+)
+puts resp['status']
+
+"""
+Example: merge or create a recipient's profile
+"""
+resp = client.profiles.merge(
+  recipient_id: "your-recipient-id",
+  profile: {
+    "phone_number" => "+15555555555"
+  }
+)
+puts resp['status']
+
+"""
+Example: get the subscribed lists of a recipient
+"""
+resp = client.profiles.get_subscriptions(
+  recipient_id: "your-recipient-id",
+  cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA" #optional
+)
+puts resp
+
+"""
+Example: edit the contents of a recipient's profile with a patch operation
+(follows JSON Patch conventions: RFC 6902).
+"""
+resp = client.profiles.patch(
+  recipient_id: "your-recipient-id",
+  operations: [
+    {
+      "op" => "add", #operation 1: add this email to profile
+      "path" => "/parent",
+      "value" => "example@example.com"
+    }
+    {
+      "op" => "replace", #operation 2: update with new email
+      "path" => "/parent",
+      "value" => "jane@doe.com"
+    }
+    {
+      "op" => "copy", #operation 3: copy that email to /emergency_contact
+      "from" => "/parent",
+      "path" => "/emergency_contact"
+    }
+    ...
+  ]
+)
+puts resp
+
+
+"""
+Example: get a recipient's profile
+"""
+resp = client.profiles.get(recipient_id: "your-recipient-id")
+puts resp
+```
+
+### Messages
+
+```Ruby
+"""
+Example: fetch the statuses of messages you've previously sent.
+"""
+resp = client.messages.list(
+  cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
+  event: "your-event-id", # optional
+  list: "your-list-id", #optional
+  message_id: "your-message-id" #optional
+  notification: ["message-status-1", "message-status-2",...] #optional
+  recipient: "recipient-id" # optional
+)
+puts resp
+
+"""
+Example: fetch the status of a message you've previously sent
+"""
+resp = client.messages.get(message_id: "your-message-id")
+puts resp
+
+"""
+Example: fetch the array of events of a message you've previously sent.
+"""
+resp = client.messages.get_history(
+message_id: "your-message-id",
+type: "list-type" #optional ("FILTERED", "RENDERED", "MAPPED", "PROFILE_LOADED")
+)
+puts resp
+```
+
+### Events
+
+```Ruby
+"""
+Example: fetch the list of events
+"""
+resp = client.events.list
+puts resp
+
+"""
+Example: fetch a specific event by event ID
+"""
+resp = client.events.get(event_id: "your-event-id")
+puts resp
+
+"""
+Example: create or replace an event
+"""
+resp = client.events.replace(
+  event_id: "your-event-id",
+  notification_id: "notification_id",
+  type: "notificaton" ## optional, defaults to notification
+)
+puts resp
+
+"""
+Example: get all brands
+"""
+resp = client.brands.list(
+  cursor: "MTU4OTQ5NTI1ODY4NywxLTVlYmRjNWRhLTEwODZlYWFjMWRmMjEwMTNjM2I0ZjVhMA", # optional
+)
+puts resp
+
+"""
+Example: get a specific brand
+"""
+resp = client.brands.get(brand_id: "brand_id")
+puts resp
+
+"""
+Example: create a brand
+"""
+resp = client.brands.create(
+  name: "brand-name",
+  settings: {
+    "color" => {
+      "primary" => "#0000FF",
+      "secondary" => "#FF0000",
+      "tertiary" => "#00FF00"
+    }
+  },
+  id: "my-brand-id", #optional
+  snippets: {}, #optional
+  idempotency_key: "my-idemp-key", #optional
+)
+puts resp
+
+"""
+Example: replace a brand
+"""
+resp = client.brands.replace(
+  brand_id: "your-brand-id",
+  name: "brand-name",
+  settings: {}
+    "color" => {
+      "primary" => "#FF0000",
+      "secondary" => "#00FF00",
+      "tertiary" => "#0000FF"
+    }
+  },
+  snippets: {} #optional
+)
+puts resp
+
+"""
+Example: delete a brand
+"""
+resp = client.brands.delete(brand_id: "your-brand-id")
+puts resp
+```
+
+### Automations
+
+````Ruby
+"""
+Example: invoke ad-hoc automation
+"""
+steps = [
+  {
+    "action" => "send"
+  }
+]
+automation = {
+  "steps" => steps
+}
+
+resp = client.automations.invoke(
+  automation: automation,
+  brand: "your-brand-id", # optional
+  data: {}, # optional
+  profile: {
+    "email" => "example@example.com",
+  }, # optional
+  recipient: "your-recipient-id", # optional
+  template: "your-notification-template-id" # optional
+)
+puts resp['runId']
+
+"""
+Example: invoke automation template
+"""
+resp = client.automations.invoke_template(
+  template_id: "your-automation-template-id",
+  brand: "your-brand-id", # optional
+  data: {}, # optional
+  profile: {
+    "email" => "example@example.com",
+  }, # optional
+  recipient: "your-recipient-id", # optional
+  template: "your-notification-template-id" # optional
+)
+puts resp['runId']
+
+### Notes on input and errors
+With the exception of passing an auth token to create a client, and ```client.send(body)```, every parameter (optional or required) is sent using keyword arguments.
+In the case of ```client.send(body)```, if the hash does not have the required components, it will throw an InputError exception, which can be caught with rescue blocks:
+```ruby
+rescue InputError
+````
+
+Any other errors from the API are thrown as a CourierAPIError. Catch these errors by putting this after your method calls:
+
+```ruby
+rescue CourierAPIError
 ```
 
 ## Development