pushover 3.0.2 → 4.0.0

data/lib/pushover/receipts.rb

@@ -0,0 +1,60 @@
+require 'uri'
+
+module Pushover
+  # Receipts provides operations for the Receipt API.
+  class Receipts
+    RECEIPT_PATTERN = /\A[A-Za-z0-9]{30}\z/
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Retrieve the current status of an emergency message receipt.
+    # @return [Response] the Pushover API response
+    def get(receipt:)
+      validate_receipt!(receipt)
+
+      response = @client.connection.get(
+        path:  "/1/receipts/#{receipt}.json",
+        query: { token: @client.token }
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    # Cancel future retries for an emergency message receipt.
+    # @return [Response] the Pushover API response
+    def cancel(receipt:)
+      validate_receipt!(receipt)
+
+      response = @client.connection.post(
+        path: "/1/receipts/#{receipt}/cancel.json",
+        body: Oj.dump('token' => @client.token)
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    # Cancel future retries for all emergency messages with a tag.
+    # @return [Response] the Pushover API response
+    def cancel_by_tag(tag:)
+      validate_tag!(tag)
+      encoded_tag = URI.encode_uri_component(tag)
+
+      response = @client.connection.post(
+        path: "/1/receipts/cancel_by_tag/#{encoded_tag}.json",
+        body: Oj.dump('token' => @client.token)
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    private
+
+    def validate_receipt!(receipt)
+      raise ArgumentError, 'receipt must be supplied' unless receipt.is_a?(String) && !receipt.empty?
+      raise ArgumentError, 'receipt must be 30 alphanumeric characters' unless receipt.match?(RECEIPT_PATTERN)
+    end
+
+    def validate_tag!(tag)
+      raise ArgumentError, 'tag must be supplied' unless tag.is_a?(String) && !tag.empty?
+    end
+  end
+end

data/lib/pushover/response.rb

@@ -6,7 +6,7 @@ module Pushover
   # @attribute request
   #   @return [String] request is a UUID representing the specific call
   # @attribute errors
-  #   @return [Array] errors includes any errors made
+  #   @return [Array, Hash] errors includes any errors made
   # @attribute receipt
   #   @return [String] receipt returns a receipt if requested
   # @attribute headers
@@ -27,12 +27,16 @@ module Pushover
 
     # purty.
     def to_s
-      "#{errors ? 'errors: ' + errors.join("\n") : 'status: ok'}, #{limits}"
+      "#{errors ? "errors: #{formatted_errors}" : 'status: ok'}, #{limits}"
     end
 
     private
 
-    # :nocov:
+    def formatted_errors
+      errors.respond_to?(:join) ? errors.join("\n") : errors
+    end
+
+    # simplecov:disable
     # Application limits
     # @return [Array] 0: Remaining Calls, 1: Total Limit, 2: Limit Reset
     def limits
@@ -42,5 +46,6 @@ module Pushover
       output.define_singleton_method(:to_s) { "requests #{self[0]} of #{self[1]}, reset on #{Time.at(self[2].to_f)}" }
       output
     end
+    # simplecov:enable
   end
 end

data/lib/pushover/sounds.rb

@@ -0,0 +1,18 @@
+module Pushover
+  # Sounds provides operations for the Sounds API.
+  class Sounds
+    def initialize(client)
+      @client = client
+    end
+
+    # Retrieve built-in and application-account custom sounds.
+    # @return [Response] the Pushover API response
+    def get
+      response = @client.connection.get(
+        path:  '/1/sounds.json',
+        query: { token: @client.token }
+      )
+      Response.create_from_excon_response(response)
+    end
+  end
+end

data/lib/pushover/subscriptions.rb

@@ -0,0 +1,48 @@
+require 'pushover/users'
+
+module Pushover
+  # Subscriptions provides operations for the Subscription API.
+  class Subscriptions
+    def initialize(client)
+      @client = client
+    end
+
+    # Migrate an existing user key to an application subscription.
+    # @return [Response] the Pushover API response
+    def migrate(subscription:, user:, device_name: nil, sound: nil)
+      validate_subscription!(subscription)
+      validate_user!(user)
+      validate_device_name!(device_name) unless device_name.nil?
+      validate_sound!(sound) unless sound.nil?
+
+      body = { 'token' => @client.token, 'subscription' => subscription, 'user' => user }
+      body['device_name'] = device_name unless device_name.nil?
+      body['sound'] = sound unless sound.nil?
+
+      response = @client.connection.post(path: '/1/subscriptions/migrate.json', body: Oj.dump(body))
+      Response.create_from_excon_response(response)
+    end
+
+    private
+
+    def validate_subscription!(subscription)
+      raise ArgumentError, 'subscription must be supplied' if subscription.nil? || subscription == ''
+      raise ArgumentError, 'subscription must be a String' unless subscription.is_a?(String)
+    end
+
+    def validate_user!(user)
+      raise ArgumentError, 'user must be supplied' if user.nil? || user == ''
+      raise ArgumentError, 'user must be 30 alphanumeric characters' unless user.is_a?(String) && user.match?(Users::USER_PATTERN)
+    end
+
+    def validate_device_name!(device_name)
+      return if device_name.is_a?(String) && device_name.match?(Users::DEVICE_PATTERN)
+
+      raise ArgumentError, 'device_name must be 1 to 25 letters, numbers, underscores, or hyphens'
+    end
+
+    def validate_sound!(sound)
+      raise ArgumentError, 'sound must be a String' unless sound.is_a?(String)
+    end
+  end
+end

data/lib/pushover/teams.rb

@@ -0,0 +1,93 @@
+module Pushover
+  # Teams provides operations for the Pushover for Teams API.
+  class Teams
+    TEXT_FIELDS = %i[name password group].freeze
+    FLAGS = %i[instant admin].freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Retrieve the team and its users and devices.
+    # @return [Response] the Pushover API response
+    def get
+      response = @client.connection.get(
+        path:  '/1/teams.json',
+        query: { token: @client.token }
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    # Add a user or send an invitation to the team.
+    # @return [Response] the Pushover API response
+    def add_user(email:, **fields)
+      validate_email!(email)
+      validate_add_user_fields!(fields)
+
+      body = { 'email' => email }.merge(fields.slice(*TEXT_FIELDS).compact.transform_keys(&:to_s))
+      add_flags!(body, **fields.slice(*FLAGS))
+      post_action('add_user', body)
+    end
+
+    # Revoke a pending team invitation.
+    # @return [Response] the Pushover API response
+    def revoke_invitation(email:)
+      post_email_action('revoke_invitation', email)
+    end
+
+    # Remove a user from the team and its delivery groups.
+    # @return [Response] the Pushover API response
+    def remove_user(email:)
+      post_email_action('remove_user', email)
+    end
+
+    private
+
+    def post_email_action(action, email)
+      validate_email!(email)
+      post_action(action, 'email' => email)
+    end
+
+    def post_action(action, fields)
+      body = { 'token' => @client.token }.merge(fields)
+      response = @client.connection.post(
+        path: "/1/teams/#{action}.json",
+        body: Oj.dump(body)
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    def add_flags!(body, **flags)
+      flags.each do |field, value|
+        next if value.nil?
+
+        validate_flag!(field, value)
+        body[field.to_s] = 'true' if value
+      end
+    end
+
+    def validate_email!(email)
+      return if email.is_a?(String) && !email.strip.empty?
+
+      raise ArgumentError, 'email must be a nonblank String'
+    end
+
+    def validate_text_fields!(fields)
+      invalid = TEXT_FIELDS.find { |field| fields.key?(field) && !fields[field].is_a?(String) }
+      raise ArgumentError, "#{invalid} must be a String" if invalid
+    end
+
+    def validate_add_user_fields!(fields)
+      unknown = fields.keys - (TEXT_FIELDS + FLAGS)
+      raise ArgumentError, "unsupported team user parameter: #{unknown.first}" unless unknown.empty?
+
+      validate_text_fields!(fields.compact)
+    end
+
+    def validate_flag!(field, value)
+      return if [true, false].include?(value)
+
+      raise ArgumentError, "#{field} must be true or false"
+    end
+  end
+end

data/lib/pushover/users.rb

@@ -0,0 +1,37 @@
+module Pushover
+  # Users provides operations for the User/Group Validation API.
+  class Users
+    USER_PATTERN = /\A[A-Za-z0-9]{30}\z/
+    DEVICE_PATTERN = /\A[A-Za-z0-9_-]{1,25}\z/
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Validate a user or group identifier and optional device.
+    # @return [Response] the Pushover API response
+    def validate(user:, device: nil)
+      validate_user!(user)
+      validate_device!(device) unless device.nil?
+
+      body = { 'token' => @client.token, 'user' => user }
+      body['device'] = device if device
+
+      response = @client.connection.post(path: '/1/users/validate.json', body: Oj.dump(body))
+      Response.create_from_excon_response(response)
+    end
+
+    private
+
+    def validate_user!(user)
+      raise ArgumentError, 'user must be supplied' if user.nil? || user == ''
+      raise ArgumentError, 'user must be 30 alphanumeric characters' unless user.is_a?(String) && user.match?(USER_PATTERN)
+    end
+
+    def validate_device!(device)
+      return if device.is_a?(String) && device.match?(DEVICE_PATTERN)
+
+      raise ArgumentError, 'device must be 1 to 25 letters, numbers, underscores, or hyphens'
+    end
+  end
+end

data/lib/pushover/version.rb

@@ -1,3 +1,3 @@
 module Pushover
-  VERSION = "3.0.2".freeze # The current version of Pushover.
+  VERSION = "4.0.0".freeze # The current version of Pushover.
 end

data/lib/pushover.rb

@@ -1,9 +1,22 @@
 require 'oj'
 require 'excon'
 
+require 'pushover/client'
+require 'pushover/glances'
+require 'pushover/groups'
+require 'pushover/licenses'
+require 'pushover/limits'
+require 'pushover/message_encryption'
+require 'pushover/message_validator'
+require 'pushover/messages'
 require 'pushover/message'
 require 'pushover/response'
+require 'pushover/receipts'
 require 'pushover/receipt'
+require 'pushover/sounds'
+require 'pushover/subscriptions'
+require 'pushover/teams'
+require 'pushover/users'
 require 'pushover/version'
 
 # pushover interface for ruby
@@ -11,5 +24,5 @@ module Pushover
   # headers to include in every request.
   HEADERS = { 'Content-Type' => 'application/json', 'User-Agent' => "pushover (ruby gem) v#{VERSION}" }.freeze
   # excon connection to use for every request.
-  Excon = Excon.new('https://api.pushover.net', headers: HEADERS).freeze
+  Excon = Excon.new('https://api.pushover.net', headers: HEADERS)
 end

data/pushover.gemspec

@@ -3,9 +3,9 @@ Gem::Specification.new do |spec|
   spec.name = 'pushover'
   spec.authors       = ['Ernie Brodeur']
   spec.email         = ['ebrodeur@ujami.net']
-  spec.date          = Time.now.strftime('%Y-%m-%d')
   spec.version       = Pushover::VERSION
   spec.platform      = Gem::Platform::RUBY
+  spec.required_ruby_version = '>= 3.3.0'
   spec.license       = 'MIT'
 
   # descriptions
@@ -14,13 +14,15 @@ Gem::Specification.new do |spec|
   spec.homepage      = 'https://github.com/erniebrodeur/pushover'
 
   # files
-  spec.files         = `git ls-files`.split($OUTPUT_RECORD_SEPARATOR)
-  spec.executables   = spec.files.grep(%r{^bin/}).map { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.files         = `git ls-files -z --cached --others --exclude-standard`.split("\0").select { |file| File.file?(file) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |file| File.basename(file) }
   spec.require_paths = ['lib']
 
   # dependencies.
-  spec.add_runtime_dependency 'excon'
-  spec.add_runtime_dependency 'gli'
-  spec.add_runtime_dependency 'oj'
+  spec.add_dependency 'base64'
+  spec.add_dependency 'excon'
+  spec.add_dependency 'gli'
+  spec.add_dependency 'oj'
+  spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/spec/gem/specification_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+RSpec.describe Gem::Specification do
+  subject(:specification) do
+    described_class.load(File.expand_path('../../pushover.gemspec', __dir__))
+  end
+
+  it 'uses exe as the executable directory' do
+    expect(specification.bindir).to eq('exe')
+  end
+
+  it 'installs only the public pushover CLI' do
+    expect(specification.executables).to eq(['pushover'])
+  end
+
+  it 'packages the public CLI' do
+    expect(specification.files).to include('exe/pushover')
+  end
+end

data/spec/pushover/client_spec.rb

@@ -0,0 +1,149 @@
+require 'spec_helper'
+
+describe Pushover::Client do
+  describe '#initialize' do
+    it 'requires an application token' do
+      expect { described_class.new(token: '') }.to raise_error ArgumentError, /token must be supplied/
+    end
+  end
+
+  describe '#messages' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a message resource' do
+      expect(client.messages).to be_a Pushover::Messages
+    end
+
+    it 'reuses the message resource' do
+      messages = client.messages
+
+      expect(client.messages).to equal messages
+    end
+  end
+
+  describe '#receipts' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a receipt resource' do
+      expect(client.receipts).to be_a Pushover::Receipts
+    end
+
+    it 'reuses the receipt resource' do
+      receipts = client.receipts
+
+      expect(client.receipts).to equal receipts
+    end
+  end
+
+  describe '#users' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a user resource' do
+      expect(client.users).to be_a Pushover::Users
+    end
+
+    it 'reuses the user resource' do
+      users = client.users
+
+      expect(client.users).to equal users
+    end
+  end
+
+  describe '#sounds' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a sounds resource' do
+      expect(client.sounds).to be_a Pushover::Sounds
+    end
+
+    it 'reuses the sounds resource' do
+      sounds = client.sounds
+
+      expect(client.sounds).to equal sounds
+    end
+  end
+
+  describe '#limits' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a limits resource' do
+      expect(client.limits).to be_a Pushover::Limits
+    end
+
+    it 'reuses the limits resource' do
+      limits = client.limits
+
+      expect(client.limits).to equal limits
+    end
+  end
+
+  describe '#glances' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a glances resource' do
+      expect(client.glances).to be_a Pushover::Glances
+    end
+
+    it 'reuses the glances resource' do
+      glances = client.glances
+
+      expect(client.glances).to equal glances
+    end
+  end
+
+  describe '#groups' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a groups resource' do
+      expect(client.groups).to be_a Pushover::Groups
+    end
+
+    it 'reuses the groups resource' do
+      groups = client.groups
+
+      expect(client.groups).to equal groups
+    end
+  end
+
+  describe '#subscriptions' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a subscriptions resource' do
+      expect(client.subscriptions).to be_a Pushover::Subscriptions
+    end
+
+    it 'reuses the subscriptions resource' do
+      subscriptions = client.subscriptions
+
+      expect(client.subscriptions).to equal subscriptions
+    end
+  end
+
+  describe '#licenses' do
+    subject(:client) { described_class.new(token: 'token') }
+
+    it 'returns a licenses resource' do
+      expect(client.licenses).to be_a Pushover::Licenses
+    end
+
+    it 'reuses the licenses resource' do
+      licenses = client.licenses
+
+      expect(client.licenses).to equal licenses
+    end
+  end
+
+  describe '#teams' do
+    subject(:client) { described_class.new(token: 'team-token') }
+
+    it 'returns a teams resource' do
+      expect(client.teams).to be_a Pushover::Teams
+    end
+
+    it 'reuses the teams resource' do
+      teams = client.teams
+
+      expect(client.teams).to equal teams
+    end
+  end
+end