pushover 3.0.2 → 4.0.0

data/lib/pushover/glances.rb

@@ -0,0 +1,86 @@
+require 'pushover/users'
+
+module Pushover
+  # Glances provides operations for the Glances API.
+  class Glances
+    DATA_FIELDS = %i[title text subtext count percent].freeze
+    SUPPORTED_FIELDS = ([:device] + DATA_FIELDS).freeze
+    TEXT_FIELDS = %i[title text subtext].freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Update one or more fields shown on a user's registered widgets.
+    # @return [Response] the Pushover API response
+    def update(user:, **params)
+      params = params.compact
+      validate_supported_fields!(params)
+      validate_user!(user)
+      validate_data_fields!(params)
+      validate_device!(params)
+      validate_text_fields!(params)
+      validate_count!(params)
+      validate_percent!(params)
+
+      body = { 'token' => @client.token, 'user' => user }.merge(params.transform_keys(&:to_s))
+      response = @client.connection.post(path: '/1/glances.json', body: Oj.dump(body))
+      Response.create_from_excon_response(response)
+    end
+
+    private
+
+    def validate_supported_fields!(params)
+      unknown = params.keys - SUPPORTED_FIELDS
+      raise ArgumentError, "unsupported glance parameter: #{unknown.first}" unless unknown.empty?
+    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_data_fields!(params)
+      return if DATA_FIELDS.any? { |field| params.key?(field) }
+
+      raise ArgumentError, 'at least one glance data field must be supplied'
+    end
+
+    def validate_device!(params)
+      return unless params.key?(:device)
+
+      device = params[:device]
+      return if device == '' || (device.is_a?(String) && device.match?(Users::DEVICE_PATTERN))
+
+      raise ArgumentError, 'device must be blank or 1 to 25 letters, numbers, underscores, or hyphens'
+    end
+
+    def validate_text_fields!(params)
+      TEXT_FIELDS.each do |field|
+        next unless params.key?(field)
+
+        value = params[field]
+        raise ArgumentError, "#{field} must be a String" unless value.is_a?(String)
+        raise ArgumentError, "#{field} must be at most 100 characters" if value.length > 100
+      end
+    end
+
+    def validate_count!(params)
+      return unless params.key?(:count)
+
+      count = params[:count]
+      return if count == '' || count.is_a?(Integer)
+
+      raise ArgumentError, 'count must be an Integer or blank'
+    end
+
+    def validate_percent!(params)
+      return unless params.key?(:percent)
+
+      percent = params[:percent]
+      return if percent == '' || (percent.is_a?(Integer) && percent.between?(0, 100))
+
+      raise ArgumentError, 'percent must be an Integer from 0 to 100 or blank'
+    end
+  end
+end

data/lib/pushover/groups.rb

@@ -0,0 +1,137 @@
+require 'pushover/users'
+
+module Pushover
+  # Groups provides operations for the Delivery Groups API.
+  class Groups
+    GROUP_PATTERN = /\A[A-Za-z0-9]{30}\z/
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Create an empty delivery group.
+    # @return [Response] the Pushover API response
+    def create(name:)
+      validate_name!(name)
+
+      response = @client.connection.post(
+        path: '/1/groups.json',
+        body: Oj.dump('token' => @client.token, 'name' => name)
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    # List delivery groups owned by the client's account or team.
+    # @return [Response] the Pushover API response
+    def list
+      response = @client.connection.get(
+        path:  '/1/groups.json',
+        query: { token: @client.token }
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    # Retrieve a delivery group's name and users.
+    # @return [Response] the Pushover API response
+    def get(group:)
+      validate_group!(group)
+
+      response = @client.connection.get(
+        path:  "/1/groups/#{group}.json",
+        query: { token: @client.token }
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    # Add a user membership to a delivery group.
+    # @return [Response] the Pushover API response
+    def add_user(group:, user:, device: nil, memo: nil)
+      validate_membership!(group, user, device)
+      validate_memo!(memo) unless memo.nil?
+
+      fields = membership_fields(user, device)
+      fields['memo'] = memo unless memo.nil?
+      post_group_action(group, 'add_user', fields)
+    end
+
+    # Remove a user's matching memberships from a delivery group.
+    # @return [Response] the Pushover API response
+    def remove_user(group:, user:, device: nil)
+      post_user_action('remove_user', group:, user:, device:)
+    end
+
+    # Temporarily disable a user's matching group memberships.
+    # @return [Response] the Pushover API response
+    def disable_user(group:, user:, device: nil)
+      post_user_action('disable_user', group:, user:, device:)
+    end
+
+    # Re-enable a user's matching group memberships.
+    # @return [Response] the Pushover API response
+    def enable_user(group:, user:, device: nil)
+      post_user_action('enable_user', group:, user:, device:)
+    end
+
+    # Rename a delivery group.
+    # @return [Response] the Pushover API response
+    def rename(group:, name:)
+      validate_group!(group)
+      validate_name!(name)
+      post_group_action(group, 'rename', 'name' => name)
+    end
+
+    private
+
+    def post_user_action(action, group:, user:, device:)
+      validate_membership!(group, user, device)
+      post_group_action(group, action, membership_fields(user, device))
+    end
+
+    def post_group_action(group, action, fields)
+      body = { 'token' => @client.token }.merge(fields)
+      response = @client.connection.post(
+        path: "/1/groups/#{group}/#{action}.json",
+        body: Oj.dump(body)
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    def membership_fields(user, device)
+      fields = { 'user' => user }
+      fields['device'] = device unless device.nil?
+      fields
+    end
+
+    def validate_membership!(group, user, device)
+      validate_group!(group)
+      validate_user!(user)
+      validate_device!(device) unless device.nil?
+    end
+
+    def validate_group!(group)
+      raise ArgumentError, 'group must be supplied' if group.nil? || group == ''
+      raise ArgumentError, 'group must be 30 alphanumeric characters' unless group.is_a?(String) && group.match?(GROUP_PATTERN)
+    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!(device)
+      return if device == '' || (device.is_a?(String) && device.match?(Users::DEVICE_PATTERN))
+
+      raise ArgumentError, 'device must be blank or 1 to 25 letters, numbers, underscores, or hyphens'
+    end
+
+    def validate_memo!(memo)
+      raise ArgumentError, 'memo must be a String' unless memo.is_a?(String)
+      raise ArgumentError, 'memo must be at most 200 characters' if memo.length > 200
+    end
+
+    def validate_name!(name)
+      raise ArgumentError, 'name must be supplied' if name.nil? || name == ''
+      raise ArgumentError, 'name must be a String' unless name.is_a?(String)
+    end
+  end
+end

data/lib/pushover/licenses.rb

@@ -0,0 +1,67 @@
+require 'pushover/users'
+
+module Pushover
+  # Licenses provides operations for the Licensing API.
+  class Licenses
+    OPERATING_SYSTEMS = ['Android', 'iOS', 'Desktop'].freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Retrieve the application's available prepaid license credits.
+    # @return [Response] the Pushover API response
+    def get
+      response = @client.connection.get(
+        path:  '/1/licenses.json',
+        query: { token: @client.token }
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    # Permanently assign one prepaid license credit to a user or e-mail address.
+    # @return [Response] the Pushover API response
+    def assign(user: nil, email: nil, os: nil)
+      validate_recipient!(user, email)
+      validate_os!(os) unless os.nil?
+
+      body = { 'token' => @client.token }
+      body['user'] = user unless user.nil?
+      body['email'] = email unless email.nil?
+      body['os'] = os unless os.nil?
+
+      response = @client.connection.post(
+        path:       '/1/licenses/assign.json',
+        body:       Oj.dump(body),
+        idempotent: false
+      )
+      Response.create_from_excon_response(response)
+    end
+
+    private
+
+    def validate_recipient!(user, email)
+      raise ArgumentError, 'user or email must be supplied' if user.nil? && email.nil?
+
+      validate_user!(user) unless user.nil?
+      validate_email!(email) unless email.nil?
+    end
+
+    def validate_user!(user)
+      raise ArgumentError, 'user must be supplied' if user == ''
+      raise ArgumentError, 'user must be 30 alphanumeric characters' unless user.is_a?(String) && user.match?(Users::USER_PATTERN)
+    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_os!(os)
+      return if os == '' || OPERATING_SYSTEMS.include?(os)
+
+      raise ArgumentError, 'os must be blank, Android, iOS, or Desktop'
+    end
+  end
+end

data/lib/pushover/limits.rb

@@ -0,0 +1,18 @@
+module Pushover
+  # Limits provides operations for the account and team usage limits API.
+  class Limits
+    def initialize(client)
+      @client = client
+    end
+
+    # Retrieve the current monthly message usage limits.
+    # @return [Response] the Pushover API response
+    def get
+      response = @client.connection.get(
+        path:  '/1/apps/limits.json',
+        query: { token: @client.token }
+      )
+      Response.create_from_excon_response(response)
+    end
+  end
+end

data/lib/pushover/message.rb

@@ -1,38 +1,35 @@
 module Pushover
-  # Message is a struct to send a message to pushover.
-  # @!attribute [rw] token
-  #   @return [String] application token
-  # @!attribute [rw] user
-  #   @return [String] user key
-  # @!attribute [rw] message
-  #   @return [String] message to transmit
-  # @!attribute [rw] device
-  #   @return [String] device to transmit too
-  # @!attribute [rw] title
-  #   @return [String] title of the message
-  # @!attribute [rw] url
-  #   @return [String] supplementary url
-  # @!attribute [rw] url_title
-  #   @return [String] title of the supplementary url
-  # @!attribute [rw] priority
-  #   @return [Numeric] numeric value for priority.
-  # @!attribute [rw] sound
-  #   @return [String] sound to play
-  # @!attribute [rw] timestamp
-  #   @return [Numeric] timestamp to expire, in epoch
-  # @!attribute [rw] expire
-  #   @return [Numeric] expire time until message expires
-  # @!attribute [rw] retry
-  #   @return [Numeric] how long to retry for, in seconds
-  # @!attribute [rw] callback
-  #   @return [String] callback url
-  Message = Struct.new(:token, :user, :message, :attachment, :device, :title, :url, :url_title, :priority, :sound, :timestamp, :expire, :retry, :callback, keyword_init: true) do
-    # push the configured message to pushover.
-    #   @return [Response] response for the receipt request
+  # Deprecated compatibility interface for sending messages.
+  class Message
+    ATTRIBUTES = %i[
+      token user message attachment device title url url_title priority sound timestamp expire retry callback
+    ].freeze
+    private_constant :ATTRIBUTES
+
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize(attributes = {}, **keywords)
+      raise ArgumentError, 'attributes must be supplied as a Hash' unless attributes.is_a?(Hash)
+
+      values = attributes.merge(keywords).transform_keys(&:to_sym)
+      unknown = values.keys - ATTRIBUTES
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      values.each { |attribute, value| public_send("#{attribute}=", value) }
+    end
+
+    # Send the configured message through the shared client.
+    # @return [Response] the Pushover API response
     def push
-      %i[token user message].each { |param| raise "#{param} must be supplied" unless send param }
+      require 'pushover' unless defined?(Pushover::Excon)
+      warn 'Pushover::Message#push is deprecated; use Pushover::Client.new(token: ...).messages.create(...)', uplevel: 1
+      %i[token user message].each { |param| raise "#{param} must be supplied" unless public_send(param) }
+      raise ArgumentError, 'raw attachment is unsupported; use attachment_base64 and attachment_type with Pushover::Client#messages.create' unless attachment.nil?
 
-      Response.create_from_excon_response Excon.post(path: '1/messages.json', query: to_h)
+      params = ATTRIBUTES.to_h { |attribute| [attribute, public_send(attribute)] }
+                         .except(:token, :attachment)
+                         .compact
+      Client.new(token: token).messages.create(**params)
     end
   end
 end

data/lib/pushover/message_encryption.rb

@@ -0,0 +1,48 @@
+require 'base64'
+require 'openssl'
+require 'securerandom'
+require 'stringio'
+require 'zlib'
+
+module Pushover
+  # MessageEncryption implements Pushover's end-to-end encryption wire format.
+  class MessageEncryption
+    FIELDS = %i[message title url url_title].freeze
+
+    def initialize(hexadecimal_key)
+      @key = [hexadecimal_key].pack('H*')
+    end
+
+    def encrypt(params)
+      params.merge(encrypted: 1).tap do |encrypted|
+        FIELDS.each { |field| encrypted[field] = encrypt_field(params[field]) if params.key?(field) }
+      end
+    end
+
+    private
+
+    def encrypt_field(plaintext)
+      iv = SecureRandom.random_bytes(16)
+      encryptor = cipher(iv)
+      ciphertext = encryptor.update(compress(plaintext)) + encryptor.final
+      hmac = OpenSSL::HMAC.digest('SHA256', @key, iv + ciphertext)
+      Base64.strict_encode64(iv + ciphertext + hmac)
+    end
+
+    def cipher(initialization_vector)
+      OpenSSL::Cipher.new('aes-256-cbc').encrypt.tap do |cipher|
+        cipher.key = @key
+        cipher.iv = initialization_vector
+      end
+    end
+
+    def compress(plaintext)
+      output = StringIO.new(''.b)
+      writer = Zlib::GzipWriter.new(output, Zlib::BEST_COMPRESSION)
+      writer.mtime = 0
+      writer.write(plaintext)
+      writer.close
+      output.string
+    end
+  end
+end

data/lib/pushover/message_validator.rb

@@ -0,0 +1,167 @@
+require 'base64'
+require 'uri'
+
+module Pushover
+  # MessageValidator enforces deterministic Message API request rules.
+  class MessageValidator
+    ATTACHMENT_LIMIT = 5_242_880
+    CHARACTER_LIMITS = { message: 1024, title: 250, url: 512, url_title: 100 }.freeze
+    EMERGENCY_FIELDS = %i[retry expire callback tags].freeze
+    FLAGS = %i[html monospace].freeze
+    PRIORITIES = [-2, -1, 0, 1, 2].freeze
+    STRING_FIELDS = %i[
+      user message attachment_base64 attachment_type device sound title url url_title callback tags
+    ].freeze
+    SUPPORTED_FIELDS = (STRING_FIELDS + FLAGS + %i[priority timestamp ttl retry expire encryption_key]).freeze
+
+    def initialize(**params)
+      @params = params.compact
+    end
+
+    def validate
+      validate_supported_fields
+      validate_required_fields
+      validate_string_fields
+      validate_character_limits
+      validate_users
+      validate_devices
+      validate_flags
+      validate_numbers
+      validate_emergency_fields
+      validate_callback
+      validate_attachment
+      validate_encryption_key
+      @params
+    end
+
+    private
+
+    def validate_supported_fields
+      unknown = @params.keys - SUPPORTED_FIELDS
+      raise ArgumentError, "unsupported message parameter: #{unknown.first}" unless unknown.empty?
+    end
+
+    def validate_required_fields
+      %i[user message].each do |field|
+        value = @params[field]
+        raise ArgumentError, "#{field} must be supplied" unless value.is_a?(String) && !value.empty?
+      end
+    end
+
+    def validate_string_fields
+      STRING_FIELDS.each do |field|
+        next unless @params.key?(field)
+
+        raise ArgumentError, "#{field} must be a String" unless @params[field].is_a?(String)
+      end
+    end
+
+    def validate_character_limits
+      CHARACTER_LIMITS.each do |field, maximum|
+        next unless @params.key?(field)
+        next if @params[field].length <= maximum
+
+        raise ArgumentError, "#{field} must be at most #{maximum} characters"
+      end
+    end
+
+    def validate_users
+      raise ArgumentError, 'user may contain at most 50 users' if @params[:user].split(',', -1).length > 50
+    end
+
+    def validate_devices
+      return unless @params.key?(:device)
+
+      valid = @params[:device].split(',', -1).all? { |device| device.match?(/\A[A-Za-z0-9_-]{1,25}\z/) }
+      raise ArgumentError, 'device contains an invalid name' unless valid
+    end
+
+    def validate_flags
+      FLAGS.each do |field|
+        next unless @params.key?(field)
+
+        value = @params[field]
+        raise ArgumentError, "#{field} must be true, false, 1, or 0" unless [true, false, 1, 0].include?(value)
+
+        @params[field] = [true, 1].include?(value) ? 1 : 0
+      end
+
+      return unless @params[:html] == 1 && @params[:monospace] == 1
+
+      raise ArgumentError, 'html and monospace cannot both be enabled'
+    end
+
+    def validate_numbers
+      validate_allowed_integer(:priority, PRIORITIES)
+      validate_minimum_integer(:timestamp, 0)
+      validate_minimum_integer(:ttl, 1, 'ttl must be a positive integer')
+      validate_minimum_integer(:retry, 30, 'retry must be at least 30 seconds')
+      validate_minimum_integer(:expire, 1)
+    end
+
+    def validate_allowed_integer(field, allowed)
+      return unless @params.key?(field)
+
+      value = @params[field]
+      return if value.is_a?(Integer) && allowed.include?(value)
+
+      raise ArgumentError, "#{field} must be one of #{allowed.join(', ')}"
+    end
+
+    def validate_minimum_integer(field, minimum, message = nil)
+      return unless @params.key?(field)
+      return if @params[field].is_a?(Integer) && @params[field] >= minimum
+
+      raise ArgumentError, message || "#{field} must be at least #{minimum}"
+    end
+
+    def validate_emergency_fields
+      if @params[:priority] == 2
+        raise ArgumentError, 'retry and expire must be supplied with priority 2' unless @params.key?(:retry) && @params.key?(:expire)
+        raise ArgumentError, 'expire must be at most 10800 seconds' if @params[:expire] > 10_800
+
+        return
+      end
+
+      field = EMERGENCY_FIELDS.find { |name| @params.key?(name) }
+      raise ArgumentError, "#{field} is only valid with priority 2" if field
+    end
+
+    def validate_attachment
+      data = @params[:attachment_base64]
+      type = @params[:attachment_type]
+      return unless data || type
+
+      raise ArgumentError, 'attachment_base64 must be supplied with attachment_type' unless data
+      raise ArgumentError, 'attachment_type must be supplied with attachment_base64' unless type
+      raise ArgumentError, 'attachment_type must be an image MIME type' unless type.match?(/\Aimage\/[A-Za-z0-9.+-]+\z/)
+
+      decoded = decode_attachment(data)
+      raise ArgumentError, 'attachment must not exceed 5242880 bytes' if decoded.bytesize > ATTACHMENT_LIMIT
+    end
+
+    def validate_callback
+      return unless @params.key?(:callback)
+
+      callback = URI.parse(@params[:callback])
+      return if callback.is_a?(URI::HTTP) && callback.host
+
+      raise ArgumentError, 'callback must be an HTTP or HTTPS URL'
+    rescue URI::InvalidURIError
+      raise ArgumentError, 'callback must be an HTTP or HTTPS URL'
+    end
+
+    def decode_attachment(data)
+      Base64.strict_decode64(data)
+    rescue ArgumentError
+      raise ArgumentError, 'attachment_base64 must be valid Base64'
+    end
+
+    def validate_encryption_key
+      return unless @params.key?(:encryption_key)
+      return if @params[:encryption_key].is_a?(String) && @params[:encryption_key].match?(/\A[0-9a-fA-F]{64}\z/)
+
+      raise ArgumentError, 'encryption_key must be 64 hexadecimal characters'
+    end
+  end
+end

data/lib/pushover/messages.rb

@@ -0,0 +1,20 @@
+module Pushover
+  # Messages provides operations for the Message API.
+  class Messages
+    def initialize(client)
+      @client = client
+    end
+
+    # Create and send a message.
+    # @return [Response] the Pushover API response
+    def create(user:, message:, **)
+      params = MessageValidator.new(user: user, message: message, **).validate
+      encryption_key = params.delete(:encryption_key)
+      params = MessageEncryption.new(encryption_key).encrypt(params) if encryption_key
+      body = { 'token' => @client.token }.merge(params.transform_keys(&:to_s))
+
+      response = @client.connection.post(path: '/1/messages.json', body: Oj.dump(body))
+      Response.create_from_excon_response(response)
+    end
+  end
+end

data/lib/pushover/receipt.rb

@@ -1,16 +1,29 @@
 module Pushover
-  # Receipt is a struct to interface with the receipt endpoint.
-  # @!attribute [rw] receipt
-  #   @return [String] id of the receipt to request
-  # @!attribute [rw] token
-  #   @return [String] application token to check for a receipt
-  Receipt = Struct.new(:receipt, :token, keyword_init: true) do
-    # Call pushover and return a response.
-    # @return [Response] response for the receipt request
+  # Deprecated compatibility interface for retrieving receipts.
+  class Receipt
+    ATTRIBUTES = %i[receipt token].freeze
+    private_constant :ATTRIBUTES
+
+    attr_accessor(*ATTRIBUTES)
+
+    def initialize(attributes = {}, **keywords)
+      raise ArgumentError, 'attributes must be supplied as a Hash' unless attributes.is_a?(Hash)
+
+      values = attributes.merge(keywords).transform_keys(&:to_sym)
+      unknown = values.keys - ATTRIBUTES
+      raise ArgumentError, "unknown keywords: #{unknown.join(', ')}" unless unknown.empty?
+
+      values.each { |attribute, value| public_send("#{attribute}=", value) }
+    end
+
+    # Retrieve the configured receipt through the shared client.
+    # @return [Response] the Pushover API response
     def get
-      %i[receipt token].each { |param| raise "#{param} must be supplied" unless send param }
+      require 'pushover' unless defined?(Pushover::Excon)
+      warn 'Pushover::Receipt#get is deprecated; use Pushover::Client.new(token: ...).receipts.get(receipt: ...)', uplevel: 1
+      %i[receipt token].each { |param| raise "#{param} must be supplied" unless public_send(param) }
 
-      Response.create_from_excon_response Excon.get(path: "1/receipts/#{receipt}.json", query: { token: token })
+      Client.new(token: token).receipts.get(receipt: receipt)
     end
   end
 end