unione 1.1.3

data/lib/unione/api/webhook/model/webhook_set_request.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Api
+    module Webhook
+      module Model
+        # WebhookSetRequest
+        class WebhookSetRequest
+          # URL that will receive the notification when an event occurs. The URL should be unique for a user or
+          # a project. Only ASCII characters are supported for now in URL, please convert to
+          # [Punycode](https://en.wikipedia.org/wiki/Punycode) if you need to use non-ASCII characters.
+          # @return [String, nil]
+          attr_accessor :url
+
+          # Webhook status, "active" by default. "disabled" means that webhook has been disabled by the user,
+          # "stopped" means that webhook has been stopped by the system after 24h of failed calls (with minimum
+          # of 10 distinct events).
+          # Default: `active`.
+          # @return [WebhookStatus, nil]
+          attr_accessor :status
+
+          # Notification format. "json_post"(default) or "json_post_gzip".
+          # Default: `json_post`.
+          # @return [WebhookEventFormat, nil]
+          attr_accessor :event_format
+
+          # Shall detailed delivery info be returned(1) or not(0). When it's 1, the information about SMTP
+          # response and internal delivery status is returned for "hard_bounced" and "soft_bounced" email
+          # statuses; the user agent, recipient IP address, detected geo fields, device info detected from the
+          # user agent (device type and brand, OS name, browser or email client name) and traffic_type (human,
+          # machine, protected or unknown) are returned for "opened" and "clicked" statuses; URL is returned for
+          # "clicked" status. For "delivered", "soft_bounced" and "hard_bounced" statuses UniOne may also return
+          # sender_ip, the IP address of the SMTP server that sent the message, if available.
+          # Allowed values: `0`, `1`.
+          # Default: `0`.
+          # @return [Integer, nil]
+          attr_accessor :delivery_info
+
+          # 0=several event notifications can be reported in single webhook call, 1=only single event can be
+          # reported in one call (not recommended).
+          # Allowed values: `0`, `1`.
+          # Default: `0`.
+          # @return [Integer, nil]
+          attr_accessor :single_event
+
+          # Maximum quantity of permitted parallel queries to your server. The more your server can handle - the
+          # better.
+          # Default: `10`.
+          # @return [Integer, nil]
+          attr_accessor :max_parallel
+
+          # Object containing events to notify of.
+          # @return [WebhookEventsObject, nil]
+          attr_accessor :events
+
+          def initialize(
+            url:,
+            status: nil,
+            event_format: nil,
+            delivery_info: nil,
+            single_event: nil,
+            max_parallel: nil,
+            events: nil
+          )
+            @url = url
+            @status = status
+            @event_format = event_format
+            @delivery_info = delivery_info
+            @single_event = single_event
+            @max_parallel = max_parallel
+            @events = events
+          end
+
+          # Builds the object from decoded JSON. Lenient: a missing field, nil or a value of another type
+          # gives nil (data that is not a Hash gives an empty object).
+          def self.from_h(data)
+            data = {} unless data.is_a?(Hash)
+            new(
+              url: data['url'],
+              status: data['status'],
+              event_format: data['event_format'],
+              delivery_info: data['delivery_info'],
+              single_event: data['single_event'],
+              max_parallel: data['max_parallel'],
+              events: ::UniOne::Client::Decode.model(::UniOne::Api::Webhook::Model::WebhookEventsObject, data['events'])
+            )
+          end
+
+          # JSON-ready hash, nil fields are omitted.
+          def to_h
+            {
+              'url' => @url,
+              'status' => @status,
+              'event_format' => @event_format,
+              'delivery_info' => @delivery_info,
+              'single_event' => @single_event,
+              'max_parallel' => @max_parallel,
+              'events' => @events.nil? ? nil : @events.to_h,
+            }.compact
+          end
+
+          def to_json(*args)
+            to_h.to_json(*args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unione/api/webhook/model/webhook_set_response.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Api
+    module Webhook
+      module Model
+        # WebhookSetResponse
+        class WebhookSetResponse
+          # "success" string
+          # Allowed values: `success`.
+          # @return [String, nil]
+          attr_accessor :status
+
+          # Object with all the webhook properties.
+          # @return [WebhookObject, nil]
+          attr_accessor :object
+
+          def initialize(
+            status: nil,
+            object: nil
+          )
+            @status = status
+            @object = object
+          end
+
+          # Builds the object from decoded JSON. Lenient: a missing field, nil or a value of another type
+          # gives nil (data that is not a Hash gives an empty object).
+          def self.from_h(data)
+            data = {} unless data.is_a?(Hash)
+            new(
+              status: data['status'],
+              object: ::UniOne::Client::Decode.model(::UniOne::Api::Webhook::Model::WebhookObject, data['object'])
+            )
+          end
+
+          # JSON-ready hash, nil fields are omitted.
+          def to_h
+            {
+              'status' => @status,
+              'object' => @object.nil? ? nil : @object.to_h,
+            }.compact
+          end
+
+          def to_json(*args)
+            to_h.to_json(*args)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unione/api/webhook/model/webhook_status.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Api
+    module Webhook
+      module Model
+        # Webhook status, "active" by default. "disabled" means that webhook has been disabled by the user,
+        # "stopped" means that webhook has been stopped by the system after 24h of failed calls (with minimum
+        # of 10 distinct events).
+        module WebhookStatus
+          ACTIVE = 'active'
+          DISABLED = 'disabled'
+          STOPPED = 'stopped'
+
+          # All values
+          ALL = [ACTIVE, DISABLED, STOPPED].freeze
+        end
+      end
+    end
+  end
+end

data/lib/unione/api/webhook/webhook_api.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module UniOne
+  module Api
+    module Webhook
+      # UniOne lets you recieve notifications about email status changes or spam blocks. You provide an URL
+      # and every time a watched event occurs we will notify you by submitting a request with JSON data to
+      # this URL.
+      #
+      # You can configure the format of webhook calls (JSON or gzipped JSON), which events you want to be
+      # notified of, whether or not you let us groups several events in one request, do you want to receive
+      # extra details like SMTP answer or recipient's user agent, etc.
+      #
+      # Please note that your webhook handler should be able to process at least 5 parallel requests, up to
+      # 100 events each (but you can configure the maximum number of parallel connections up to 100, which
+      # is recommended).
+      #
+      # If the URL of your webhook handler is not available (the response is not HTTP 200 OK within 3
+      # seconds timeout), the system will repeat requests each 10 minutes during 24 hours, passing extra
+      # parameter retry_count. If there were at least 10 events during last 24 hours and all the webhook
+      # requests about these events have failed then we consider webhook handler broken and change it's
+      # status to inactive automatically. A notification about that is sent to an email [configured in
+      # control panel](https://cp.unione.io/en/user/alerting/technical/).
+      #
+      # The format of webhook request and details of each event are described
+      # [here](https://docs.unione.io/en/web-api-ref#callback-format).
+      class WebhookApi
+        # @param client [::UniOne::Client::ApiClient]
+        def initialize(client)
+          @client = client
+        end
+
+        # Sets or edits a [webhook](https://docs.unione.io/en/web-api-ref#webhook), i.e. an event notification
+        # handler.
+        #
+        # Documentation: https://docs.unione.io/en/web-api-ref#webhook-set
+        # @param request [::UniOne::Api::Webhook::Model::WebhookSetRequest, Hash]
+        # @return [::UniOne::Api::Webhook::Model::WebhookSetResponse]
+        # @raise [::UniOne::Client::ApiError]
+        def set(request)
+          ::UniOne::Api::Webhook::Model::WebhookSetResponse.from_h(@client.call('/webhook/set.json', request.is_a?(Hash) ? request : request.to_h))
+        end
+
+        # Gets properties of a [webhook](https://docs.unione.io/en/web-api-ref#webhook).
+        #
+        # Documentation: https://docs.unione.io/en/web-api-ref#webhook-get
+        # @param request [::UniOne::Api::Webhook::Model::WebhookGetRequest, Hash]
+        # @return [::UniOne::Api::Webhook::Model::WebhookGetResponse]
+        # @raise [::UniOne::Client::ApiError]
+        def get(request)
+          ::UniOne::Api::Webhook::Model::WebhookGetResponse.from_h(@client.call('/webhook/get.json', request.is_a?(Hash) ? request : request.to_h))
+        end
+
+        # List all or some [webhooks](https://docs.unione.io/en/web-api-ref#webhook) (event notification
+        # handlers) of a user or a project.
+        #
+        # Documentation: https://docs.unione.io/en/web-api-ref#webhook-list
+        # @param request [::UniOne::Api::Webhook::Model::WebhookListRequest, Hash]
+        # @return [::UniOne::Api::Webhook::Model::WebhookListResponse]
+        # @raise [::UniOne::Client::ApiError]
+        def list(request)
+          ::UniOne::Api::Webhook::Model::WebhookListResponse.from_h(@client.call('/webhook/list.json', request.is_a?(Hash) ? request : request.to_h))
+        end
+
+        # Deletes an event notification handler
+        #
+        # You can also temporarily deactivate webhook without deleting it by setting it's status to "disabled"
+        # in [webhook/set](https://docs.unione.io/en/web-api-ref#webhook-set) method.
+        #
+        # Documentation: https://docs.unione.io/en/web-api-ref#webhook-delete
+        # @param request [::UniOne::Api::Webhook::Model::WebhookDeleteRequest, Hash]
+        # @return [::UniOne::Common::Model::SuccessResponse]
+        # @raise [::UniOne::Client::ApiError]
+        def delete(request)
+          ::UniOne::Common::Model::SuccessResponse.from_h(@client.call('/webhook/delete.json', request.is_a?(Hash) ? request : request.to_h))
+        end
+
+        # Webhook callback format description.
+        # @param body [String] raw body of the incoming request
+        # @return [::UniOne::Api::Webhook::Model::WebhookCallback]
+        def self.parse_callback(body)
+          ::UniOne::Api::Webhook::Model::WebhookCallback.from_h(JSON.parse(body))
+        end
+      end
+    end
+  end
+end

data/lib/unione/client/api_client.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module UniOne
+  module Client
+    # The SDK and its version in the "platform" query parameter of every request.
+    PLATFORM = 'ruby-sdk.1.1.3'
+
+    # Default transport (HTTP layer of ApiClient): Net::HTTP of the standard library.
+    #
+    # A transport is any object responding to call(method, uri, headers, body, timeout) -> [status, body]
+    # (a lambda works too): method 'POST', uri [URI::HTTP] with the query string, headers [Hash] with the API key,
+    # body [String] JSON, timeout [Numeric] seconds; it returns the HTTP status [Integer] and the raw response body
+    # [String]. HTTP error statuses are returned, not raised; any exception becomes an ApiError.
+    class NetHttpTransport
+      def call(method, uri, headers, body, timeout)
+        request = Net::HTTPGenericRequest.new(method, true, true, uri)
+        headers.each { |name, value| request[name] = value }
+        request.body = body
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                                       open_timeout: timeout, read_timeout: timeout) do |http|
+          http.request(request)
+        end
+        [response.code.to_i, response.body.to_s]
+      end
+    end
+
+    # Low level client: every API method is a POST request with a JSON body that returns JSON.
+    class ApiClient
+      # @return [Configuration]
+      attr_reader :config
+      # @return [#call] HTTP layer, see NetHttpTransport
+      attr_reader :transport
+
+      # @param config [Configuration]
+      # @param transport [#call, nil] call(method, uri, headers, body, timeout) -> [status, body]; nil: NetHttpTransport
+      def initialize(config, transport: nil)
+        @config = config
+        @transport = transport || NetHttpTransport.new
+      end
+
+      # Headers of every request: JSON, User-Agent, the API key, then Configuration#headers.
+      # @return [Hash{String => String}]
+      def headers
+        {
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json',
+          'User-Agent' => @config.user_agent,
+          'X-API-KEY' => @config.api_key
+        }.merge((@config.headers || {}).transform_keys(&:to_s))
+      end
+
+      # Calls an API method, e.g. call('/email/send.json', {...}), and returns the decoded response.
+      # @raise [ApiError]
+      def call(path, body = {})
+        uri = URI("#{@config.base_url}/#{path.sub(%r{\A/+}, '')}")
+        uri.query = URI.encode_www_form(platform: [@config.platform, PLATFORM].compact.reject(&:empty?).join(','))
+        status, raw = send_request(uri, JSON.generate(body || {}))
+        status = status.to_i
+        raw = raw.to_s
+        begin
+          data = JSON.parse(raw)
+        rescue JSON::ParserError => e
+          raise ApiError.new("Invalid JSON in response (HTTP #{status}): #{raw[0, 500]} (#{e.message})",
+                             http_status: status)
+        end
+        raise ApiError.new("Unexpected response (HTTP #{status}): #{raw[0, 500]}", http_status: status) unless data.is_a?(Hash)
+
+        if status >= 400 || data['status'] == 'error'
+          code = data['code']
+          raise ApiError.new((data['message'] || 'API error').to_s,
+                             http_status: status,
+                             error_code: code.to_s =~ /\A\d+\z/ ? code.to_i : nil,
+                             response_body: data)
+        end
+        data
+      end
+
+      private
+
+      def send_request(uri, body)
+        @transport.call('POST', uri, headers, body, @config.timeout)
+      rescue ApiError
+        raise
+      rescue StandardError => e
+        raise ApiError.new("HTTP request failed: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/lib/unione/client/api_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Client
+    # Raised when the API returns an error or the response can not be processed.
+    class ApiError < StandardError
+      # @return [Integer] HTTP status of the response, 0 when the request was not sent
+      attr_reader :http_status
+      # @return [Integer, nil] API error code (the "code" field of the error response)
+      attr_reader :error_code
+      # @return [Hash, nil] decoded error response
+      attr_reader :response_body
+
+      def initialize(message, http_status: 0, error_code: nil, response_body: nil)
+        super(message)
+        @http_status = http_status
+        @error_code = error_code
+        @response_body = response_body
+      end
+    end
+  end
+end

data/lib/unione/client/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Client
+    # API connection settings.
+    class Configuration
+      DEFAULT_BASE_URL = 'https://api.unione.io/en/transactional/api/v1'
+      # API host api.unione.io
+      HOST_API = 'api.unione.io'
+      # API host eu1.unione.io
+      HOST_EU1 = 'eu1.unione.io'
+      # API host us1.unione.io
+      HOST_US1 = 'us1.unione.io'
+      # Path of the API on every host
+      BASE_PATH = '/en/transactional/api/v1'
+
+      # Base URL for an API host: 'eu1.unione.io' -> 'https://eu1.unione.io' + BASE_PATH; a full URL is kept as is.
+      def self.base_url_for(host)
+        return host.sub(%r{/+\z}, '') if host.include?('://')
+
+        "https://#{host.gsub(%r{\A/+|/+\z}, '')}#{BASE_PATH}"
+      end
+
+      # @return [String] user or project API key, sent in the X-API-KEY header
+      attr_accessor :api_key
+      # @return [String] base URL of the API
+      attr_accessor :base_url
+      # @return [Integer] request timeout in seconds
+      attr_accessor :timeout
+      # @return [String]
+      attr_accessor :user_agent
+      # @return [String, nil] package that uses the SDK and its version (e.g. 'rails.1.0.0'), sent in the "platform" query
+      #   parameter before the SDK one (Client::PLATFORM)
+      attr_accessor :platform
+      # @return [Hash{String => String}] extra HTTP headers of every request (e.g. a tracing id); they override the
+      #   default ones of the same name
+      attr_accessor :headers
+
+      def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30, user_agent: 'unione-ruby-sdk/1.1.3', platform: nil, headers: {})
+        @api_key = api_key
+        @base_url = base_url.sub(%r{/+\z}, '')
+        @timeout = timeout
+        @user_agent = user_agent
+        @platform = platform
+        @headers = headers || {}
+      end
+    end
+  end
+end

data/lib/unione/client/decode.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Client
+    # Lenient decoding of responses for the models: a response that lacks a field, has null in it or a value of
+    # another type does not break from_h, the field is nil (a model is built only from a Hash, a list only from an
+    # Array).
+    module Decode
+      module_function
+
+      # klass.from_h(value) for a Hash, nil for anything else.
+      def model(klass, value)
+        value.is_a?(Hash) ? klass.from_h(value) : nil
+      end
+
+      # The array (each item through the block, if given), nil for anything else.
+      def list(value, &block)
+        return nil unless value.is_a?(Array)
+
+        block ? value.map(&block) : value
+      end
+
+      # The hash (each value through the block, if given; [] - an empty object encoded as an array - gives {}),
+      # nil for anything else.
+      def map(value, &block)
+        return {} if value.is_a?(Array) && value.empty?
+        return nil unless value.is_a?(Hash)
+
+        block ? value.transform_values(&block) : value
+      end
+    end
+  end
+end

data/lib/unione/common/model/attachments_array_item.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Common
+    module Model
+      # AttachmentsArrayItem
+      class AttachmentsArrayItem
+        # Attachment type, see [MIME](https://en.wikipedia.org/wiki/MIME). If unsure, use
+        # "application/octet-stream".
+        # @return [String, nil]
+        attr_accessor :type
+
+        # Attachment name in the format: "name.extension". When multiple attachments are passed, their names
+        # must be unique. The symbol ‘/’ is not allowed in attachment names.
+        # @return [String, nil]
+        attr_accessor :name
+
+        # File contents in [base64](https://en.wikipedia.org/wiki/Base64). Maximum file size 7MB (9786710
+        # bytes in base64).
+        # @return [String, nil]
+        attr_accessor :content
+
+        def initialize(
+          type:,
+          name:,
+          content:
+        )
+          @type = type
+          @name = name
+          @content = content
+        end
+
+        # Builds the object from decoded JSON. Lenient: a missing field, nil or a value of another type
+        # gives nil (data that is not a Hash gives an empty object).
+        def self.from_h(data)
+          data = {} unless data.is_a?(Hash)
+          new(
+            type: data['type'],
+            name: data['name'],
+            content: data['content']
+          )
+        end
+
+        # JSON-ready hash, nil fields are omitted.
+        def to_h
+          {
+            'type' => @type,
+            'name' => @name,
+            'content' => @content,
+          }.compact
+        end
+
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+      end
+    end
+  end
+end

data/lib/unione/common/model/body_object.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Common
+    module Model
+      # Contains HTML/plaintext/AMP parts of the email. Either html or plaintext part is required.
+      class BodyObject
+        # HTML part of the email body
+        # @return [String, nil]
+        attr_accessor :html
+
+        # Plaintext part of the email body.
+        # @return [String, nil]
+        attr_accessor :plaintext
+
+        # Optional [AMP](http://amp.dev/documentation/guides-and-tutorials/learn/email_fundamentals/) part of
+        # the email body.
+        # @return [String, nil]
+        attr_accessor :amp
+
+        def initialize(
+          html: nil,
+          plaintext: nil,
+          amp: nil
+        )
+          @html = html
+          @plaintext = plaintext
+          @amp = amp
+        end
+
+        # Builds the object from decoded JSON. Lenient: a missing field, nil or a value of another type
+        # gives nil (data that is not a Hash gives an empty object).
+        def self.from_h(data)
+          data = {} unless data.is_a?(Hash)
+          new(
+            html: data['html'],
+            plaintext: data['plaintext'],
+            amp: data['amp']
+          )
+        end
+
+        # JSON-ready hash, nil fields are omitted.
+        def to_h
+          {
+            'html' => @html,
+            'plaintext' => @plaintext,
+            'amp' => @amp,
+          }.compact
+        end
+
+        def to_json(*args)
+          to_h.to_json(*args)
+        end
+      end
+    end
+  end
+end

data/lib/unione/common/model/email_counter_mode.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Common
+    module Model
+      # Sets the email counter mode. It allows you to choose whether the counter should reset automatically,
+      # or remain permanent. The following values are acceptable: 'default' - the counter resets to zero
+      # automatically at the beginning of each accounting period, 'permanent' - the counter never resets
+      # automatically. The reset can be done only manually by the user in the request with the passes 0
+      # value in the email_counter field. If the request doesn't contain the field or contains a null value,
+      # the limit value doesn't change.
+      module EmailCounterMode
+        DEFAULT = 'default'
+        PERMANENT = 'permanent'
+
+        # All values
+        ALL = [DEFAULT, PERMANENT].freeze
+      end
+    end
+  end
+end

data/lib/unione/common/model/email_status.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module UniOne
+  module Common
+    module Model
+      # EmailStatus
+      module EmailStatus
+        SENT = 'sent'
+        DELIVERED = 'delivered'
+        OPENED = 'opened'
+        CLICKED = 'clicked'
+        UNSUBSCRIBED = 'unsubscribed'
+        SUBSCRIBED = 'subscribed'
+        SOFT_BOUNCED = 'soft_bounced'
+        HARD_BOUNCED = 'hard_bounced'
+        SPAM = 'spam'
+
+        # All values
+        ALL = [SENT, DELIVERED, OPENED, CLICKED, UNSUBSCRIBED, SUBSCRIBED, SOFT_BOUNCED, HARD_BOUNCED, SPAM].freeze
+      end
+    end
+  end
+end