wavix-sdk-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7109971ce5978d84427cf88468e30e1d579f237f8100643bd1b1b1555512ce6d
+  data.tar.gz: a10cec01767eecd0254cca6364247f201643a6a7b887adf6727c51f82d5fc941
+SHA512:
+  metadata.gz: 6e6712f8ade79a0d43a2dc6c376cda0ecf20b946ddf8623ad15c7fcebad5dad28748924b4c4409cf4e15995ce02971fd59db7a256d53628795373e925cbc1e6f
+  data.tar.gz: 336d67bc2673dabf399def966dcd1ed66e8080da77e9de7953d1a3ce48a0603f1d176b126b8570f8824dc810439f8374bbb8f29ab963e7af138b1d1c1b93372b

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Wavix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,124 @@
+# Wavix Backend Public API Ruby SDK
+
+Welcome to the Wavix Ruby SDK documentation. This guide will walk you through installing, configuring, and using the Wavix Ruby SDK to interact seamlessly with the Wavix Backend Public API.
+
+## Installing the SDK
+
+To include the Wavix Ruby SDK in your application, add the following line to your Gemfile:
+  
+    gem 'wavix-sdk-ruby'
+
+Then, run `bundle install` to install the gem.
+
+## Configuration
+  
+First, obtain your token for connecting to the API (more information [here](https://wavix.com/api#/rest/getting-started/api-key-management)). Then, configure the `WavixApi` class with the necessary variables to enable future requests:
+```
+  WavixApi.host = 'api.wavix.com'
+  WavixApi.api_key = 'your_token'
+```
+Replace `your_token` with the token you received.
+
+## Overview
+
+The Wavix Ruby SDK uses the [Faraday](https://github.com/lostisland/faraday) gem for making HTTP requests and returns service results using [Struct](https://ruby-doc.org/core-2.5.1/Struct.html).
+
+Response attributes:
+
+Attribute  | Description  | Example
+------------- | ------------- | -------------
+status  | Response status code  | 200
+status_str  | String value of response status code  | OK
+body  | Response JSON body  | `"{\"success\":true}"`
+parsed_body | Parsed response body | `{ "success" => true }`
+success? | Boolean state of response status | `true`
+
+The Wavix Ruby SDK uses the [json-schema](https://github.com/voxpupuli/json-schema) for body and parameter validation. Errors related to invalid data in arguments will follow the logic of `json-schema`. These errors are raised as `WavixApi::ValidationError`, allowing you to handle them using `rescue`.
+
+    "The property '#/a' of type String did not match the following type: integer"
+
+## Examples
+
+Once you have set your credentials, you can use the SDK to interact with the [Wavix Public API](https://wavix.com/api).
+
+### Getting profile data
+```
+> WavixApi::V1::Profile::Find.new.call
+=> #<struct status=200, status_str="OK", body="{\"id\":1,\"additional_info\":\"dev\",\"attn_contact_name\":\"wavix\",\"billing_address\":\"wavix in the house\",\"company_name\":\"wavix\",\"contact_email\":\"some@email.com\",\"default_destinations\":[],\"default_short_link_endpoint\":null,\"email\":\"some@email.com\",\"first_name\":\"First\",\"last_name\":\"Last\",\"phone\":\"1234567890\",\"timezone\":\"Europe/Berlin\"}", parsed_body={"id"=>1, "additional_info"=>"dev", "attn_contact_name"=>"wavix", "billing_address"=>"wavix in the house", "company_name"=>"wavix", "contact_email"=>"some@email.com", "default_destinations"=>[{"transport"=>"sip", "value"=>"Default SIP URI"}, {"transport"=>"pstn", "value"=>"Default PSTN"}], "default_short_link_endpoint"=>nil, "phone"=>"79231234567", "timezone"=>"Europe/Berlin"}, success?=true>
+```
+
+Alternatively, you can use a more concise version to achieve identical results.
+```
+> WavixApi::V1::Profile::Find.call
+=> #<struct status=200, status_str="OK", body="{\"id\":1,\"additional_info\":\"dev\",\"attn_contact_name\":\"wavix\",\"billing_address\":\"wavix in the house\",\"company_name\":\"wavix\",\"contact_email\":\"some@email.com\",\"default_destinations\":[],\"default_short_link_endpoint\":null,\"email\":\"some@email.com\",\"first_name\":\"First\",\"last_name\":\"Last\",\"phone\":\"1234567890\",\"timezone\":\"Europe/Berlin\"}", parsed_body={"id"=>1, "additional_info"=>"dev", "attn_contact_name"=>"wavix", "billing_address"=>"wavix in the house", "company_name"=>"wavix", "contact_email"=>"some@email.com", "default_destinations"=>[{"transport"=>"sip", "value"=>"Default SIP URI"}, {"transport"=>"pstn", "value"=>"Default PSTN"}], "default_short_link_endpoint"=>nil, "phone"=>"79231234567", "timezone"=>"Europe/Berlin"}, success?=true>
+```
+
+
+### Searching Available DID Numbers for Purchase with Parameters
+```
+> WavixApi::V1::Buy::Dids::Search.new(type_filter: '', text_enabled_only: false, country_id: 1, city_id: 2}).call
+=> #<struct status=200, status_str="OK", body="{\"dids\":[],\"pagination\":{\"total\":0,\"total_pages\":1,\"current_page\":1,\"per_page\":50}}", parsed_body={"dids"=>[], "pagination"=>{"total"=>0, "total_pages"=>1, "current_page"=>1, "per_page"=>50}}, success?=true>
+```
+
+Or short version
+```
+> WavixApi::V1::Buy::Dids::Search.call(type_filter: '', text_enabled_only: false, country_id: 1, city_id: 2)
+```
+
+
+### Destroy call recording by ID
+```
+> WavixApi::V1::Call::Recordings::Destroy.new(id: 123).call
+=> #<struct status=400, status_str="Bad Request", body="{\"error\":true,\"message\":\"deleted due to the retention policy settings\",\"deleted_at\":\"2023-12-17T00:01:08.000Z\"}", parsed_body={"error"=>true, "message"=>"deleted due to the retention policy settings", "deleted_at"=>"2023-12-17T00:01:08.000Z"}, success?=false>
+```
+
+### Create message with body
+```
+> WavixApi::V2::Messages::Create.new(
+  from: '12345678901', 
+  to: '12345678902', 
+  message_body: { 
+    text: 'Test ruby sdk' 
+  }
+).call
+=> #<struct status=201, status_str=“Created”, body="{\"charge\":\"0.0\",\"delivered_at\":null,\"error_message\":null,\"from\":\"+12345678901\",\"mcc\":\"310\",\"message_body\":{\"text\":\"Test ruby sdk\",\"media\":[]},\"message_id\":\"27b6ed5b-3536-412e-b0e3-4f421ba54212\",\"message_type\":\"sms\",\"mnc\":\"000\",\"segments\":1,\"sent_at\":null,\"status\":\"accepted\",\"submitted_at\":\"2024-06-26T14:02:08\",\"tag\":null,\"to\":\"+12345678902\"}", parsed_body={"charge"=>"0.0", "delivered_at"=>nil, "error_message"=>nil, "from"=>"+12345678901", "mcc"=>"310", "message_body"=>{"text"=>"Test ruby sdk", "media"=>[]}, "message_id"=>"27b6ed5b-3536-412e-b0e3-4f421ba54212", "message_type"=>"sms", "mnc"=>"000", "segments"=>1, "sent_at"=>nil, "status"=>"accepted", "submitted_at"=>"2024-06-26T14:02:08", "tag"=>nil, "to"=>"+12345678902"}, success?=true>
+```
+
+Or short version
+
+```
+> WavixApi::V2::Messages::Create.call(
+  from: '12345678901', 
+  to: '12345678902', 
+  message_body: { 
+    text: 'Test ruby sdk' 
+  }
+)
+```
+
+### Update Sub-organizations with ID and body
+```
+> WavixApi::V1::SubOrganizations::Update.new(name: 'Test ruby SDK', id: 123).call
+=> #<struct status=200, status_str="OK", body="{\"api_key\":\"key\",\"created_at\":\"2024-03-12T15:32:49.000Z\",\"default_destinations\":{\"sms_endpoint\":\"\",\"dlr_endpoint\":\"\"},\"id\":123,\"master_organization\":100000,\"name\":\"Test ruby SDK\",\"status\":\"enabled\"}", parsed_body={"api_key"=>"key", "created_at"=>"2024-03-12T15:32:49.000Z", "default_destinations"=>{"sms_endpoint"=>"", "dlr_endpoint"=>""}, "id"=>123, "master_organization"=>100000, "name"=>"Test ruby SDK", "status"=>"enabled"}, success?=true>
+```
+
+Or short version
+```
+> WavixApi::V1::SubOrganizations::Update.call(name: 'Test ruby SDK', id: 123)
+```
+
+## Download billing invoice PDF
+
+You can specify the path to save the file
+
+```
+WavixApi::V1::Billing::Invoices::Find.new(id: 1, save_path: 'path/to/file.pdf').call
+```
+
+## Create papers with File
+
+To upload a file, use `File.open(path)`.
+
+```
+WavixApi::V1::Papers::Create.new(did_ids: '1,2', doc_id: 3, doc_attachment: File.open('file.jpg')}).call
+```

data/lib/middleware/follow_redirects_middleware.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'faraday'
+class FollowRedirectsMiddleware < Faraday::Middleware
+  REDIRECT_CODES = [301, 302, 303, 307, 308].freeze
+
+  def call(env)
+    @app.call(env).on_complete do |response_env|
+      if REDIRECT_CODES.include?(response_env.status)
+        env.url = URI.parse(response_env[:response_headers]['location'])
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/services/fields_validator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'json-schema'
+
+module Services
+  class FieldsValidator
+    attr_accessor :fields, :schema
+    attr_reader :error
+
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def call
+      JSON::Validator.validate!(schema, fields)
+    rescue JSON::Schema::ValidationError => e
+      @error = e.message
+    end
+
+    def valid?
+      @error.nil?
+    end
+  end
+end

data/lib/wavix-sdk-ruby.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'wavix_api'
+
+Dir[File.join(__dir__, 'wavix_api/**/*.rb')].sort.each { |file| require file }

data/lib/wavix_api/base_methods.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require 'services/fields_validator'
+
+module WavixApi
+  class ValidationError < StandardError; end
+
+  module BaseMethods
+    attr_reader :params, :id, :client
+
+    DEFAULT_HEADERS = { 'Content-Type' => 'application/json' }.freeze
+    PAGINATION_SCHEMA = {
+      page: { type: 'integer' },
+      per_page: { type: 'integer' }
+    }.freeze
+    ONLY_ID_SCHEMA = {
+      type: 'object',
+      properties: {
+        id: { type: 'integer' }.freeze
+      }.freeze,
+      required: %i[id].freeze
+    }.freeze
+    ONLY_UUID_SCHEMA = {
+      type: 'object',
+      properties: {
+        id: { type: 'string' }.freeze
+      }.freeze,
+      required: %i[id].freeze
+    }.freeze
+    AVAILABLE_TRANSCRIPTION_LANGUAGES = %w[en de es fr it].freeze
+    BASE_DATE_FORMAT = '%Y-%m-%d'
+    ONLY_DIGITS_REGEXP = /^\d+$/.freeze
+    IP_REGEXP = /^\d(\.\d)*$/.freeze
+    LIST_OF_DIGITS_REGEXP = /^\d+(,\d+)*$/.freeze
+
+    class << self
+      attr_accessor :params_schema
+    end
+
+    def initialize(params = {})
+      @params = deep_symbolize_keys(params)
+      @id = @params[:id]
+      @client = ::WavixApi.client
+    end
+
+    def validate!
+      validate_params! unless self.class.instance_variable_get('@params_schema').nil?
+      validate_appid!
+    end
+
+    def validate_dates!(fields, step_params: params)
+      invalid_fields = fields.select do |field|
+        value = step_params[field.to_sym]
+        nested = field.to_s.split('.')
+        # INFO: in case of nested key. For example: item.date_from, item.nested_item.date_from
+        if nested.count > 1
+          validate_dates!(nested[1..-1], step_params: step_params[nested.first.to_i])
+        else
+          !value.is_a?(::DateTime) && (!value.nil? && !value.empty?)
+        end
+      end
+      return true if invalid_fields.empty?
+
+      raise_error("Fields #{invalid_fields} must be a DateTime")
+    end
+
+    def stringify_dates!(params, fields:, format: BASE_DATE_FORMAT)
+      fields.each do |field|
+        nested = field.to_s.split('.')
+        # INFO: in case of nested key. For example: item.date_from, item.nested_item.date_from
+        if nested.count > 1
+          key = nested.first.to_sym
+          stringify_dates!(params[key], fields: nested[1..-1].join('.'), format: format)
+        else
+          value = params[field.to_sym]
+          next if !value.is_a?(::DateTime) && (value.nil? || value.empty?)
+
+          params[field.to_sym] = value.strftime(format)
+        end
+      end
+    end
+
+    def get(path, headers: {})
+      client.get(
+        path,
+        params: params.merge(additional_params),
+        headers: DEFAULT_HEADERS.merge(headers)
+      )
+    end
+
+    def download(path, headers: {}, save_path: nil)
+      client.download(
+        path,
+        params: params.merge(additional_params),
+        headers: DEFAULT_HEADERS.merge(headers),
+        save_path: save_path
+      )
+    end
+
+    def post(path, with_file: false, headers: {})
+      client.post(
+        path,
+        params: additional_params,
+        headers: DEFAULT_HEADERS.merge(headers),
+        body: params.except(:id),
+        with_file: with_file
+      )
+    end
+
+    def put(path)
+      client.put(path, body: params.except(:id), params: additional_params)
+    end
+
+    def patch(path)
+      client.patch(path, body: params.except(:id), params: additional_params)
+    end
+
+    def delete(path)
+      client.delete(path, params: params.merge(additional_params))
+    end
+
+    def raise_error(error)
+      raise ValidationError, error
+    end
+
+    def format_file(file, content_type: 'multipart/form-data')
+      Faraday::Multipart::FilePart.new(file.path, content_type)
+    end
+
+    def file_extention(file)
+      File.extname(file.path).to_s[1..-1]
+    end
+
+    def call
+      self.class.call(params)
+    end
+
+    private
+
+    def deep_transform_keys_in_object(object, &block)
+      case object
+      when Hash
+        object.each_with_object({}) do |(key, value), result|
+          result[yield(key)] = deep_transform_keys_in_object(value, &block)
+        end
+      when Array
+        object.map { |e| deep_transform_keys_in_object(e, &block) }
+      else
+        object
+      end
+    end
+
+    def deep_symbolize_keys(object)
+      deep_transform_keys_in_object(object) do |key|
+        key.to_sym
+      rescue StandardError
+        key
+      end
+    end
+
+    def validate_appid!
+      raise_error('api_key is required') if WavixApi.api_key.nil? || WavixApi.api_key.empty?
+    end
+
+    def validate_params!
+      service = ::Services::FieldsValidator.new(
+        fields: params,
+        schema: self.class.instance_variable_get('@params_schema')
+      )
+      service.call
+      raise_error(service.error) unless service.valid?
+    end
+
+    def additional_params
+      { appid: WavixApi.api_key }.tap do |res|
+        res[:id] = id if !id.nil? && (id.is_a?(Integer) || id.empty?)
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/base_destroy.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'wavix_api'
+
+module WavixApi
+  module V1
+    class BaseDestroy
+      include ::WavixApi::BaseMethods
+
+      class << self
+        def call(id = nil)
+          instance = new({ id: id })
+
+          instance.validate!
+
+          instance.delete([path, instance.id].join('/'))
+        end
+
+        private
+
+        def path
+          raise NoMethodError
+        end
+      end
+
+      def call
+        self.class.call(id)
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/base_find.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'wavix_api'
+
+module WavixApi
+  module V1
+    class BaseFind
+      include WavixApi::BaseMethods
+
+      class << self
+        def call(id = nil)
+          instance = new({ id: id })
+
+          instance.validate!
+
+          instance.get([path, instance.id].join('/'))
+        end
+
+        private
+
+        def path
+          raise NoMethodError
+        end
+      end
+
+      def call
+        self.class.call(id)
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/base_search.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'wavix_api'
+
+module WavixApi
+  module V1
+    class BaseSearch
+      include WavixApi::BaseMethods
+
+      class << self
+        def call(params = {})
+          instance = new(params)
+
+          instance.validate!
+
+          instance.get(path)
+        end
+
+        private
+
+        def path
+          raise NoMethodError
+        end
+      end
+
+      def call
+        self.class.call(@params)
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/billing/invoices/find.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'wavix_api'
+
+module WavixApi
+  module V1
+    module Billing
+      module Invoices
+        class Find
+          include WavixApi::BaseMethods
+
+          @params_schema = ::WavixApi::BaseMethods::ONLY_ID_SCHEMA
+
+          class << self
+            def call(id = nil, save_path: nil)
+              instance = new({ id: id })
+
+              instance.validate!
+
+              instance.download(
+                ['v1/billing/invoices', instance.id].join('/'),
+                headers: {
+                  'Content-Disposition' => 'attachment; filename="invoice.pdf"',
+                  'Content-Type' => 'application/octet-stream',
+                  'Content-Transfer-Encoding' => 'binary'
+                },
+                save_path: save_path
+              )
+            end
+          end
+
+          def initialize(params = {})
+            super(params)
+            @save_path = @params[:save_path]
+          end
+
+          def call
+            self.class.call(id, save_path: @save_path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/billing/invoices/search.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'wavix_api'
+
+module WavixApi
+  module V1
+    module Billing
+      module Invoices
+        class Search < ::WavixApi::V1::BaseSearch
+          class << self
+            private
+
+            def path
+              'v1/billing/invoices'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/billing/transactions/search.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'wavix_api'
+
+module WavixApi
+  module V1
+    module Billing
+      module Transactions
+        class Search
+          include WavixApi::BaseMethods
+
+          DATE_FIELDS = %i[from_date to_date].freeze
+
+          @params_schema = {
+            type: 'object',
+            properties: {
+              type: { type: 'integer' }.freeze,
+              payments: { type: 'boolean' }.freeze,
+              details_contains: { type: 'string' }.freeze,
+              **::WavixApi::BaseMethods::PAGINATION_SCHEMA
+            },
+            required: DATE_FIELDS
+          }.freeze
+
+          class << self
+            def call(params = {})
+              instance = new(params)
+
+              instance.validate!
+              instance.validate_dates!(DATE_FIELDS)
+              instance.stringify_dates!(instance.params, fields: DATE_FIELDS)
+              instance.get('v1/billing/transactions')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/buy/carts/checkout.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module WavixApi
+  module V1
+    module Buy
+      module Carts
+        class Checkout
+          include WavixApi::BaseMethods
+
+          class << self
+            def call(params = {})
+              instance = new(params)
+
+              instance.validate!
+
+              instance.post('v1/buy/cart/checkout')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/buy/carts/find.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module WavixApi
+  module V1
+    module Buy
+      module Carts
+        class Find
+          include WavixApi::BaseMethods
+
+          class << self
+            def call(params = {})
+              instance = new(params)
+
+              instance.validate!
+
+              instance.get('v1/buy/cart')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/wavix_api/v1/buy/carts/update.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module WavixApi
+  module V1
+    module Buy
+      module Carts
+        class Update
+          include WavixApi::BaseMethods
+
+          @params_schema = {
+            type: 'object',
+            properties: {
+              ids: {
+                type: 'string',
+                pattern: ::WavixApi::BaseMethods::LIST_OF_DIGITS_REGEXP
+              }.freeze
+            }.freeze,
+            required: %i[ids].freeze
+          }.freeze
+
+          class << self
+            def call(params = {})
+              instance = new(params)
+
+              instance.validate!
+
+              instance.patch('v1/buy/cart')
+            end
+          end
+        end
+      end
+    end
+  end
+end