diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..f5726aa --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,59 @@ +name: Deploy + +on: + push: + branches: + - master + +jobs: + test: + runs-on: ubuntu-latest + strategy: + matrix: + ruby-version: ['2.7', '3.0', '3.1', '3.2'] + steps: + - uses: actions/checkout@v2 + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby-version }} + bundler-cache: true + - name: Install dependencies + run: bundle install + - name: Run RSpec + run: bundle exec rspec + + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.2' + bundler-cache: true + - name: Install dependencies + run: bundle install + - name: Run RuboCop + run: bundle exec rubocop + + deploy: + needs: [test, lint] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.2' + bundler-cache: true + - name: Install dependencies + run: bundle install + - name: Build gem + run: gem build *.gemspec + - name: Push to RubyGems + run: | + mkdir -p $HOME/.gem + echo ":rubygems_api_key: ${{ secrets.RUBY_GEMS_TOKEN }}" > $HOME/.gem/credentials + chmod 0600 $HOME/.gem/credentials + gem push *.gem diff --git a/.gitignore b/.gitignore index b8bc553..595af0f 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ Gemfile.lock .DS_Store pkg vendor/bundle +.yardoc +doc diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..a74005a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,66 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0]. + +[homepage]: https://www.contributor-covenant.org +[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html diff --git a/README.md b/README.md index 6200c95..5f5ef28 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,21 @@ -# Zadarma API Ruby Client +# Zadarma SDK Ruby Client A modern, robust, and fully-featured Ruby client for the Zadarma API. This gem has been updated to support the latest Zadarma API, providing a clean and intuitive interface for all available endpoints. -## Installation +## Getting Started + +### Prerequisites + +- Ruby 2.7 or later +- A Zadarma account +- Your Zadarma API key and secret + +### Installation Add this line to your application's Gemfile: ```ruby -gem 'zadarma' +gem 'zadarma_sdk' ``` And then execute: @@ -16,83 +24,27 @@ And then execute: Or install it yourself as: - $ gem install zadarma + $ gem install zadarma_sdk -## Usage +## Configuration First, configure the client with your API key and secret. You can find these in your Zadarma personal account. ```ruby -require 'zadarma' - -client = Zadarma::Client.new(api_key: 'YOUR_API_KEY', api_secret: 'YOUR_API_SECRET') -``` - -Now you can call any of the available API methods: - -### Get Your Balance - -```ruby -response = client.balance -puts "Your balance is #{response['balance']} #{response['currency']}." -``` - -### Get Call Price - -```ruby -response = client.price(number: '1234567890') -puts "The price to call 1234567890 is #{response['info']['price']} per minute." -``` +require 'zadarma_sdk' -### Request a Callback - -```ruby -response = client.callback(from: 'YOUR_NUMBER', to: 'DESTINATION_NUMBER') -puts "Callback initiated from #{response['from']} to #{response['to']}." +client = ZadarmaSdk::Client.new(api_key: 'YOUR_API_KEY', api_secret: 'YOUR_API_SECRET') ``` -### Send an SMS +## Usage -```ruby -response = client.send_sms(number: 'DESTINATION_NUMBER', message: 'Hello from Zadarma!') -puts "SMS sent. Cost: #{response['cost']} #{response['currency']}." -``` +Now you can call any of the available API methods. -### Get Call Statistics +## API Resources -```ruby -response = client.statistics(start: '2023-01-01', end_date: '2023-01-31') -response['stats'].each do |call| - puts "Call from #{call['from']} to #{call['to']} on #{call['callstart']}." -end -``` +This client is organized into resources, mirroring the Zadarma API structure. For a detailed list of methods and parameters, please see the [developer documentation](mkdocs/index.md). -## Available Methods - -This client is organized into resources, mirroring the Zadarma API structure. - -* **Info** - * `balance`: Get your current account balance. - * `price(number:, caller_id: nil)`: Get the price for a call to a specific number. -* **PBX** - * `internal_numbers`: Get a list of your internal PBX numbers. - * `set_call_recording(id:, status:, email: nil, speech_recognition: nil)`: Enable or disable call recording for a PBX extension. -* **Direct Numbers (Virtual Numbers)** - * `direct_numbers`: Get a list of your virtual numbers. -* **Request** - * `callback(from:, to:, sip: nil, predicted: nil)`: Initiate a callback between two numbers. -* **SIP** - * `sips`: Get a list of your SIP numbers. - * `set_sip_caller_id(id:, number:)`: Set the CallerID for a SIP number. - * `redirection(id: nil)`: Get call forwarding information for a SIP number. - * `set_redirection(id:, status:, type: nil, number: nil, condition: nil)`: Set call forwarding for a SIP number. -* **SMS** - * `send_sms(number:, message:, sender: nil)`: Send an SMS message. -* **Statistics** - * `statistics(start:, end_date:, sip: nil, cost_only: nil, type: nil, skip: nil, limit: nil)`: Get overall call statistics. - * `pbx_statistics(start:, end_date:, version: nil, skip: nil, limit: nil, call_type: nil)`: Get PBX call statistics. - -## Development & Testing +## Development To work on this gem locally, clone the repository and then run `bundle install` to install the dependencies. @@ -104,8 +56,16 @@ The test suite is configured to use `webmock` to stub out all API requests, so y ## Contributing -1. Fork it ( https://github.com/SamyRai/zadarma-ruby/fork ) +1. Fork it 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create a new Pull Request + +## License + +The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). + +## Code of Conduct + +Everyone interacting in the ZadarmaSdk project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md). diff --git a/lib/zadarma/client.rb b/lib/zadarma/client.rb index 53b0237..2e4043b 100644 --- a/lib/zadarma/client.rb +++ b/lib/zadarma/client.rb @@ -27,140 +27,333 @@ class Client API_URL = 'https://api.zadarma.com' + # Initializes a new Client object. + # + # @param api_key [String] The Zadarma API key. + # @param api_secret [String] The Zadarma API secret. def initialize(api_key:, api_secret:) @api_key = api_key @api_secret = api_secret end + # Get the current account balance. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_balance def balance info.balance end + # Get the price for a call to a specific number. + # + # @param number [String] The destination number. + # @param caller_id [String] The caller ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_price def price(number:, caller_id: nil) info.price(number: number, caller_id: caller_id) end + # Get a list of internal PBX numbers. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_pbx_internal def internal_numbers pbx.internal end + # Enable or disable call recording for a PBX extension. + # + # @param id [String] The PBX extension ID. + # @param status [String] The recording status. + # @param email [String] The email address to send the recording to. + # @param speech_recognition [String] The speech recognition status. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_pbx_record def set_call_recording(id:, status:, email: nil, speech_recognition: nil) pbx.set_call_recording(id: id, status: status, email: email, speech_recognition: speech_recognition) end + # Request a call recording from the PBX. + # + # @param call_id [String] The call ID. + # @param pbx_call_id [String] The PBX call ID. + # @param lifetime [String] The lifetime of the recording. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_pbx_record_request def pbx_record_request(call_id: nil, pbx_call_id: nil, lifetime: nil) pbx.pbx_record_request(call_id: call_id, pbx_call_id: pbx_call_id, lifetime: lifetime) end + # Get a list of direct numbers. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_direct_numbers def direct_numbers direct_numbers_resource.all end + # Get a list of countries for direct numbers. + # + # @param language [String] The language of the response. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_direct_number_countries def direct_number_countries(language: nil) direct_numbers_resource.countries(language: language) end + # Get a list of direct numbers for a specific country. + # + # @param country [String] The country code. + # @param language [String] The language of the response. + # @param direction_id [String] The direction ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_direct_number_country def direct_number_country(country:, language: nil, direction_id: nil) direct_numbers_resource.country(country: country, language: language, direction_id: direction_id) end + # Get a list of available direct numbers. + # + # @param direction_id [String] The direction ID. + # @param mask [String] The number mask. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_available_direct_numbers def available_direct_numbers(direction_id:, mask: nil) direct_numbers_resource.available(direction_id: direction_id, mask: mask) end + # Order a direct number. + # + # @param params [Hash] The order parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_order_direct_number def order_direct_number(params) direct_numbers_resource.order(params) end + # Prolong a direct number. + # + # @param number [String] The direct number. + # @param months [String] The number of months to prolong the number for. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_prolong_direct_number def prolong_direct_number(number:, months:) direct_numbers_resource.prolong(number: number, months: months) end + # Initiate a callback between two numbers. + # + # @param from [String] The source number. + # @param to [String] The destination number. + # @param sip [String] The SIP number. + # @param predicted [String] The predicted status. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_callback def callback(from:, to:, sip: nil, predicted: nil) request_resource.callback(from: from, to: to, sip: sip, predicted: predicted) end + # Get a list of SIP numbers. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_sips def sips sip.all end + # Get the status of a SIP number. + # + # @param sip [String] The SIP number. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_sip_status def sip_status(sip:) self.sip.status(sip: sip) end + # Create a SIP number. + # + # @param name [String] The SIP number name. + # @param password [String] The SIP number password. + # @param callerid [String] The SIP number caller ID. + # @param redirect_to_phone [String] The phone number to redirect to. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_create_sip def create_sip(name:, password: nil, callerid: nil, redirect_to_phone: nil) sip.create(name: name, password: password, callerid: callerid, redirect_to_phone: redirect_to_phone) end + # Set the password for a SIP number. + # + # @param sip [String] The SIP number. + # @param value [String] The new password. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_set_sip_password def set_sip_password(sip:, value:) self.sip.password(sip: sip, value: value) end + # Set the caller ID for a SIP number. + # + # @param id [String] The SIP number ID. + # @param number [String] The new caller ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_set_sip_caller_id def set_sip_caller_id(id:, number:) sip.set_caller_id(id: id, number: number) end + # Get call forwarding information for a SIP number. + # + # @param id [String] The SIP number ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_redirection def redirection(id: nil) sip.redirection(id: id) end + # Set call forwarding for a SIP number. + # + # @param id [String] The SIP number ID. + # @param status [String] The forwarding status. + # @param type [String] The forwarding type. + # @param number [String] The forwarding number. + # @param condition [String] The forwarding condition. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_set_redirection def set_redirection(id:, status:, type: nil, number: nil, condition: nil) sip.set_redirection(id: id, status: status, type: type, number: number, condition: condition) end + # Send an SMS message. + # + # @param number [String] The destination number. + # @param message [String] The message text. + # @param sender [String] The sender ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_send_sms def send_sms(number:, message:, sender: nil) sms.send_sms(number: number, message: message, sender: sender) end + # Get overall call statistics. + # + # @param params [Hash] The statistics parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_statistics def statistics(params) statistics_resource.statistics(params) end + # Get PBX call statistics. + # + # @param params [Hash] The statistics parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_pbx_statistics def pbx_statistics(params) statistics_resource.pbx_statistics(params) end + # Get speech recognition results. + # + # @param call_id [String] The call ID. + # @param lang [String] The language of the speech. + # @param return_results [String] Whether to return the results. + # @param alternatives [String] Whether to return alternative results. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_get_speech_recognition def get_speech_recognition(call_id:, lang: nil, return_results: nil, alternatives: nil) speech_recognition_resource.get(call_id: call_id, lang: lang, return_results: return_results, alternatives: alternatives) end + # Initiate speech recognition. + # + # @param call_id [String] The call ID. + # @param lang [String] The language of the speech. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_initiate_speech_recognition def initiate_speech_recognition(call_id:, lang: nil) speech_recognition_resource.initiate(call_id: call_id, lang: lang) end + # Get a list of document files. + # + # @param group_id [String] The group ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_document_files def document_files(group_id: nil) groups_of_documents_resource.files(group_id: group_id) end + # Get a list of document groups. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_document_groups def document_groups groups_of_documents_resource.list end + # Get a document group. + # + # @param id [String] The group ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_get_document_group def get_document_group(id:) groups_of_documents_resource.get(id: id) end + # Create a document group. + # + # @param params [Hash] The group parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_create_document_group def create_document_group(params:) groups_of_documents_resource.create(params: params) end + # Update a document group. + # + # @param id [String] The group ID. + # @param params [Hash] The group parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_update_document_group def update_document_group(id:, params:) groups_of_documents_resource.update(id: id, params: params) end + # Make a GET request to the Zadarma API. + # + # @param path [String] The API endpoint path. + # @param params [Hash] The request parameters. + # @return [Hash] The API response. def get(path, params = {}) request(:get, path, params) end + # Make a POST request to the Zadarma API. + # + # @param path [String] The API endpoint path. + # @param params [Hash] The request parameters. + # @return [Hash] The API response. def post(path, params = {}) request(:post, path, params) end + # Make a PUT request to the Zadarma API. + # + # @param path [String] The API endpoint path. + # @param params [Hash] The request parameters. + # @return [Hash] The API response. def put(path, params = {}) request(:put, path, params) end + # Make a DELETE request to the Zadarma API. + # + # @param path [String] The API endpoint path. + # @param params [Hash] The request parameters. + # @return [Hash] The API response. def delete(path, params = {}) request(:delete, path, params) end diff --git a/lib/zadarma_sdk.rb b/lib/zadarma_sdk.rb new file mode 100644 index 0000000..d9e9b74 --- /dev/null +++ b/lib/zadarma_sdk.rb @@ -0,0 +1,9 @@ +# frozen_string_literal: true + +require 'zadarma_sdk/version' +require 'zadarma_sdk/client' +require 'zadarma_sdk/error' + +# The ZadarmaSdk module contains all the classes and methods for the Zadarma API client. +module ZadarmaSdk +end diff --git a/lib/zadarma_sdk/client.rb b/lib/zadarma_sdk/client.rb new file mode 100644 index 0000000..31e6414 --- /dev/null +++ b/lib/zadarma_sdk/client.rb @@ -0,0 +1,361 @@ +# frozen_string_literal: true + +require 'json' +require 'faraday' +require 'openssl' +require 'base64' +require 'digest/md5' +require 'cgi' + +require_relative 'resources/info' +require_relative 'resources/pbx' +require_relative 'resources/direct_numbers' +require_relative 'resources/request' +require_relative 'resources/sip' +require_relative 'resources/sms' +require_relative 'resources/statistics' +require_relative 'resources/speech_recognition' +require_relative 'resources/groups_of_documents' +require_relative 'client/resources' +require_relative 'client/http' + +module ZadarmaSdk + # The Client class is the main entry point for interacting with the Zadarma API. + class Client + include Resources + include Http + + API_URL = 'https://api.zadarma.com' + + # Initializes a new Client object. + # + # @param api_key [String] The Zadarma API key. + # @param api_secret [String] The Zadarma API secret. + def initialize(api_key:, api_secret:) + @api_key = api_key + @api_secret = api_secret + end + + # Get the current account balance. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_balance + def balance + info.balance + end + + # Get the price for a call to a specific number. + # + # @param number [String] The destination number. + # @param caller_id [String] The caller ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_price + def price(number:, caller_id: nil) + info.price(number: number, caller_id: caller_id) + end + + # Get a list of internal PBX numbers. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_pbx_internal + def internal_numbers + pbx.internal + end + + # Enable or disable call recording for a PBX extension. + # + # @param id [String] The PBX extension ID. + # @param status [String] The recording status. + # @param email [String] The email address to send the recording to. + # @param speech_recognition [String] The speech recognition status. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_pbx_record + def set_call_recording(id:, status:, email: nil, speech_recognition: nil) + pbx.set_call_recording(id: id, status: status, email: email, speech_recognition: speech_recognition) + end + + # Request a call recording from the PBX. + # + # @param call_id [String] The call ID. + # @param pbx_call_id [String] The PBX call ID. + # @param lifetime [String] The lifetime of the recording. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_pbx_record_request + def pbx_record_request(call_id: nil, pbx_call_id: nil, lifetime: nil) + pbx.pbx_record_request(call_id: call_id, pbx_call_id: pbx_call_id, lifetime: lifetime) + end + + # Get a list of direct numbers. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_direct_numbers + def direct_numbers + direct_numbers_resource.all + end + + # Get a list of countries for direct numbers. + # + # @param language [String] The language of the response. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_direct_number_countries + def direct_number_countries(language: nil) + direct_numbers_resource.countries(language: language) + end + + # Get a list of direct numbers for a specific country. + # + # @param country [String] The country code. + # @param language [String] The language of the response. + # @param direction_id [String] The direction ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_direct_number_country + def direct_number_country(country:, language: nil, direction_id: nil) + direct_numbers_resource.country(country: country, language: language, direction_id: direction_id) + end + + # Get a list of available direct numbers. + # + # @param direction_id [String] The direction ID. + # @param mask [String] The number mask. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_available_direct_numbers + def available_direct_numbers(direction_id:, mask: nil) + direct_numbers_resource.available(direction_id: direction_id, mask: mask) + end + + # Order a direct number. + # + # @param params [Hash] The order parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_order_direct_number + def order_direct_number(params) + direct_numbers_resource.order(params) + end + + # Prolong a direct number. + # + # @param number [String] The direct number. + # @param months [String] The number of months to prolong the number for. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_prolong_direct_number + def prolong_direct_number(number:, months:) + direct_numbers_resource.prolong(number: number, months: months) + end + + # Initiate a callback between two numbers. + # + # @param from [String] The source number. + # @param to [String] The destination number. + # @param sip [String] The SIP number. + # @param predicted [String] The predicted status. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_callback + def callback(from:, to:, sip: nil, predicted: nil) + request_resource.callback(from: from, to: to, sip: sip, predicted: predicted) + end + + # Get a list of SIP numbers. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_sips + def sips + sip.all + end + + # Get the status of a SIP number. + # + # @param sip [String] The SIP number. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_sip_status + def sip_status(sip:) + self.sip.status(sip: sip) + end + + # Create a SIP number. + # + # @param name [String] The SIP number name. + # @param password [String] The SIP number password. + # @param callerid [String] The SIP number caller ID. + # @param redirect_to_phone [String] The phone number to redirect to. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_create_sip + def create_sip(name:, password: nil, callerid: nil, redirect_to_phone: nil) + sip.create(name: name, password: password, callerid: callerid, redirect_to_phone: redirect_to_phone) + end + + # Set the password for a SIP number. + # + # @param sip [String] The SIP number. + # @param value [String] The new password. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_set_sip_password + def set_sip_password(sip:, value:) + self.sip.password(sip: sip, value: value) + end + + # Set the caller ID for a SIP number. + # + # @param id [String] The SIP number ID. + # @param number [String] The new caller ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_set_sip_caller_id + def set_sip_caller_id(id:, number:) + sip.set_caller_id(id: id, number: number) + end + + # Get call forwarding information for a SIP number. + # + # @param id [String] The SIP number ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_redirection + def redirection(id: nil) + sip.redirection(id: id) + end + + # Set call forwarding for a SIP number. + # + # @param id [String] The SIP number ID. + # @param status [String] The forwarding status. + # @param type [String] The forwarding type. + # @param number [String] The forwarding number. + # @param condition [String] The forwarding condition. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_set_redirection + def set_redirection(id:, status:, type: nil, number: nil, condition: nil) + sip.set_redirection(id: id, status: status, type: type, number: number, condition: condition) + end + + # Send an SMS message. + # + # @param number [String] The destination number. + # @param message [String] The message text. + # @param sender [String] The sender ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_send_sms + def send_sms(number:, message:, sender: nil) + sms.send_sms(number: number, message: message, sender: sender) + end + + # Get overall call statistics. + # + # @param params [Hash] The statistics parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_statistics + def statistics(params) + statistics_resource.statistics(params) + end + + # Get PBX call statistics. + # + # @param params [Hash] The statistics parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_pbx_statistics + def pbx_statistics(params) + statistics_resource.pbx_statistics(params) + end + + # Get speech recognition results. + # + # @param call_id [String] The call ID. + # @param lang [String] The language of the speech. + # @param return_results [String] Whether to return the results. + # @param alternatives [String] Whether to return alternative results. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_get_speech_recognition + def get_speech_recognition(call_id:, lang: nil, return_results: nil, alternatives: nil) + speech_recognition_resource.get(call_id: call_id, lang: lang, return_results: return_results, + alternatives: alternatives) + end + + # Initiate speech recognition. + # + # @param call_id [String] The call ID. + # @param lang [String] The language of the speech. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_initiate_speech_recognition + def initiate_speech_recognition(call_id:, lang: nil) + speech_recognition_resource.initiate(call_id: call_id, lang: lang) + end + + # Get a list of document files. + # + # @param group_id [String] The group ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_document_files + def document_files(group_id: nil) + groups_of_documents_resource.files(group_id: group_id) + end + + # Get a list of document groups. + # + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_document_groups + def document_groups + groups_of_documents_resource.list + end + + # Get a document group. + # + # @param id [String] The group ID. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_get_document_group + def get_document_group(id:) + groups_of_documents_resource.get(id: id) + end + + # Create a document group. + # + # @param params [Hash] The group parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_create_document_group + def create_document_group(params:) + groups_of_documents_resource.create(params: params) + end + + # Update a document group. + # + # @param id [String] The group ID. + # @param params [Hash] The group parameters. + # @return [Hash] The API response. + # @see https://zadarma.com/en/support/api/#api_update_document_group + def update_document_group(id:, params:) + groups_of_documents_resource.update(id: id, params: params) + end + + # Make a GET request to the Zadarma API. + # + # @param path [String] The API endpoint path. + # @param params [Hash] The request parameters. + # @return [Hash] The API response. + def get(path, params = {}) + request(:get, path, params) + end + + # Make a POST request to the Zadarma API. + # + # @param path [String] The API endpoint path. + # @param params [Hash] The request parameters. + # @return [Hash] The API response. + def post(path, params = {}) + request(:post, path, params) + end + + # Make a PUT request to the Zadarma API. + # + # @param path [String] The API endpoint path. + # @param params [Hash] The request parameters. + # @return [Hash] The API response. + def put(path, params = {}) + request(:put, path, params) + end + + # Make a DELETE request to the Zadarma API. + # + # @param path [String] The API endpoint path. + # @param params [Hash] The request parameters. + # @return [Hash] The API response. + def delete(path, params = {}) + request(:delete, path, params) + end + end +end diff --git a/lib/zadarma_sdk/client/http.rb b/lib/zadarma_sdk/client/http.rb new file mode 100644 index 0000000..48ff95a --- /dev/null +++ b/lib/zadarma_sdk/client/http.rb @@ -0,0 +1,42 @@ +# frozen_string_literal: true + +require 'digest/md5' +require 'openssl' +require 'base64' + +module ZadarmaSdk + class Client + # A module for handling HTTP requests to the Zadarma API. + module Http + private + + def request(method, path, params = {}) + params.merge!(format: 'json') + + response = connection.public_send(method, "/v1#{path}", params) do |request| + request.headers['Authorization'] = "#{@api_key}:#{signature("/v1#{path}", params)}" + end + + raise ZadarmaSdk::Error, "API Error: #{response.status} - #{response.body}" unless response.success? + + body = JSON.parse(response.body) + raise ZadarmaSdk::Error, "API Error: #{body['message']}" if body['status'] == 'error' + + body + end + + def signature(url, params) + query = URI.encode_www_form(params.sort) + sign_str = url + query + Digest::MD5.hexdigest(query) + Base64.encode64(OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), @api_secret, sign_str)).strip + end + + def connection + @connection ||= Faraday.new(url: API_URL) do |faraday| + faraday.request :url_encoded + faraday.adapter Faraday.default_adapter + end + end + end + end +end diff --git a/lib/zadarma_sdk/client/resources.rb b/lib/zadarma_sdk/client/resources.rb new file mode 100644 index 0000000..af212fe --- /dev/null +++ b/lib/zadarma_sdk/client/resources.rb @@ -0,0 +1,67 @@ +# frozen_string_literal: true + +module ZadarmaSdk + class Client + # A module for accessing the various resources of the Zadarma API. + module Resources + # Define methods for accessing each resource. + # + # @!method info + # @return [ZadarmaSdk::Resources::Info] the Info resource + # @!method pbx + # @return [ZadarmaSdk::Resources::Pbx] the Pbx resource + # @!method direct_numbers_resource + # @return [ZadarmaSdk::Resources::DirectNumbers] the DirectNumbers resource + # @!method request_resource + # @return [ZadarmaSdk::Resources::Request] the Request resource + # @!method sip + # @return [ZadarmaSdk::Resources::Sip] the Sip resource + # @!method sms + # @return [ZadarmaSdk::Resources::Sms] the Sms resource + # @!method statistics_resource + # @return [ZadarmaSdk::Resources::Statistics] the Statistics resource + # @!method speech_recognition_resource + # @return [ZadarmaSdk::Resources::SpeechRecognition] the SpeechRecognition resource + # @!method groups_of_documents_resource + # @return [ZadarmaSdk::Resources::GroupsOfDocuments] the GroupsOfDocuments resource + %i[ + info + pbx + direct_numbers_resource + request_resource + sip + sms + statistics_resource + speech_recognition_resource + groups_of_documents_resource + ].each do |resource| + define_method(resource) do + instance_variable_get("@#{resource}") || + instance_variable_set( + "@#{resource}", + case resource + when :info + ::ZadarmaSdk::Resources::Info.new(client: self) + when :pbx + ::ZadarmaSdk::Resources::Pbx.new(client: self) + when :direct_numbers_resource + ::ZadarmaSdk::Resources::DirectNumbers.new(client: self) + when :request_resource + ::ZadarmaSdk::Resources::Request.new(client: self) + when :sip + ::ZadarmaSdk::Resources::Sip.new(client: self) + when :sms + ::ZadarmaSdk::Resources::Sms.new(client: self) + when :statistics_resource + ::ZadarmaSdk::Resources::Statistics.new(client: self) + when :speech_recognition_resource + ::ZadarmaSdk::Resources::SpeechRecognition.new(client: self) + when :groups_of_documents_resource + ::ZadarmaSdk::Resources::GroupsOfDocuments.new(client: self) + end + ) + end + end + end + end +end diff --git a/lib/zadarma_sdk/error.rb b/lib/zadarma_sdk/error.rb new file mode 100644 index 0000000..7c2a86a --- /dev/null +++ b/lib/zadarma_sdk/error.rb @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +module ZadarmaSdk + class Error < StandardError; end +end diff --git a/lib/zadarma_sdk/resources/direct_numbers.rb b/lib/zadarma_sdk/resources/direct_numbers.rb new file mode 100644 index 0000000..ae3c5b7 --- /dev/null +++ b/lib/zadarma_sdk/resources/direct_numbers.rb @@ -0,0 +1,71 @@ +# frozen_string_literal: true + +module ZadarmaSdk + module Resources + # The DirectNumbers resource allows you to manage virtual numbers. + class DirectNumbers + def initialize(client:) + @client = client + end + + # Get information about the user's virtual numbers + # @return [Hash] + def all + @client.get('/direct_numbers/') + end + + # Get a list of countries where numbers can be ordered + # @param language [String] The language for the country names + # @return [Hash] + def countries(language: nil) + params = {} + params[:language] = language if language + @client.get('/direct_numbers/countries/', params) + end + + # Get a list of destinations in a country where a number can be ordered + # @param country [String] The ISO country code + # @param language [String] The language for the destination names + # @param direction_id [String] The direction ID + # @return [Hash] + def country(country:, language: nil, direction_id: nil) + params = { country: country } + params[:language] = language if language + params[:direction_id] = direction_id if direction_id + @client.get('/direct_numbers/country/', params) + end + + # Get a list of available numbers for a given direction + # @param direction_id [String] The direction ID + # @param mask [String] A mask for searching number matches + # @return [Hash] + def available(direction_id:, mask: nil) + params = {} + params[:mask] = mask if mask + @client.get("/direct_numbers/available/#{direction_id}/", params) + end + + # Order a virtual number + # @param params [Hash] The parameters for ordering a number + # @option params [String] :direction_id The direction/city ID + # @option params [String] :number_id The ID of the number to be connected + # @option params [String] :documents_group_id The ID of the group of user documents + # @option params [String] :purpose A text description of the purpose of number use + # @option params [String] :receive_sms '1' to enable SMS reception + # @option params [String] :period 'month' or '3month' + # @option params [String] :autorenew_period 'year' or 'month' + # @return [Hash] + def order(params) + @client.post('/direct_numbers/order/', params) + end + + # Prepay the number for the specified number of months + # @param number [String] The number to be prolonged + # @param months [Integer] The number of months + # @return [Hash] + def prolong(number:, months:) + @client.post('/direct_numbers/prolong/', number: number, months: months) + end + end + end +end diff --git a/lib/zadarma_sdk/resources/groups_of_documents.rb b/lib/zadarma_sdk/resources/groups_of_documents.rb new file mode 100644 index 0000000..72db05d --- /dev/null +++ b/lib/zadarma_sdk/resources/groups_of_documents.rb @@ -0,0 +1,49 @@ +# frozen_string_literal: true + +module ZadarmaSdk + module Resources + # The GroupsOfDocuments resource allows you to manage groups of documents. + class GroupsOfDocuments + def initialize(client:) + @client = client + end + + # Get the list of files/documents in the group of documents + # @param group_id [String] The group of documents ID + # @return [Hash] + def files(group_id: nil) + params = {} + params[:group_id] = group_id if group_id + @client.get('/documents/files/', params) + end + + # Get the list of groups of documents + # @return [Hash] + def list + @client.get('/documents/groups/list/') + end + + # Get information on a certain group + # @param id [String] The group ID + # @return [Hash] + def get(id:) + @client.get("/documents/groups/get/#{id}/") + end + + # Create a new group of documents + # @param params [Hash] The parameters for creating a new group of documents + # @return [Hash] + def create(params:) + @client.post('/documents/groups/create/', params) + end + + # Update a group of documents + # @param id [String] The group ID + # @param params [Hash] The parameters for updating a group of documents + # @return [Hash] + def update(id:, params:) + @client.put("/documents/groups/update/#{id}/", params) + end + end + end +end diff --git a/lib/zadarma_sdk/resources/info.rb b/lib/zadarma_sdk/resources/info.rb new file mode 100644 index 0000000..3b1546f --- /dev/null +++ b/lib/zadarma_sdk/resources/info.rb @@ -0,0 +1,28 @@ +# frozen_string_literal: true + +module ZadarmaSdk + module Resources + # The Info resource provides access to user information, such as balance and call rates. + class Info + def initialize(client:) + @client = client + end + + # Get the user's balance + # @return [Hash] + def balance + @client.get('/info/balance/') + end + + # Get the call rate for a given number + # @param number [String] The phone number + # @param caller_id [String] The CallerID to be used for the call + # @return [Hash] + def price(number:, caller_id: nil) + params = { number: number } + params[:caller_id] = caller_id if caller_id + @client.get('/info/price/', params) + end + end + end +end diff --git a/lib/zadarma_sdk/resources/pbx.rb b/lib/zadarma_sdk/resources/pbx.rb new file mode 100644 index 0000000..b29ca09 --- /dev/null +++ b/lib/zadarma_sdk/resources/pbx.rb @@ -0,0 +1,44 @@ +# frozen_string_literal: true + +module ZadarmaSdk + module Resources + # The Pbx resource allows you to manage your Zadarma PBX. + class Pbx + def initialize(client:) + @client = client + end + + # Get the list of PBX internal numbers + # @return [Hash] + def internal + @client.get('/pbx/internal/') + end + + # Set the call recording for a PBX extension + # @param id [String] The PBX extension ID + # @param status [String] The call recording status ('on', 'off', etc.) + # @param email [String] The email address to send recordings to + # @param speech_recognition [String] The speech recognition settings + # @return [Hash] + def set_call_recording(id:, status:, email: nil, speech_recognition: nil) + params = { id: id, status: status } + params[:email] = email if email + params[:speech_recognition] = speech_recognition if speech_recognition + @client.put('/pbx/internal/recording/', params) + end + + # Request a call recording file + # @param call_id [String] The unique call ID + # @param pbx_call_id [String] The permanent ID of the external call to the PBX + # @param lifetime [Integer] The link's lifetime in seconds + # @return [Hash] + def pbx_record_request(call_id: nil, pbx_call_id: nil, lifetime: nil) + params = {} + params[:call_id] = call_id if call_id + params[:pbx_call_id] = pbx_call_id if pbx_call_id + params[:lifetime] = lifetime if lifetime + @client.get('/pbx/record/request/', params) + end + end + end +end diff --git a/lib/zadarma_sdk/resources/request.rb b/lib/zadarma_sdk/resources/request.rb new file mode 100644 index 0000000..8492793 --- /dev/null +++ b/lib/zadarma_sdk/resources/request.rb @@ -0,0 +1,25 @@ +# frozen_string_literal: true + +module ZadarmaSdk + module Resources + # The Request resource allows you to initiate callbacks. + class Request + def initialize(client:) + @client = client + end + + # Request a callback + # @param from [String] Your phone/SIP number, the PBX extension or the PBX scenario + # @param to [String] The phone or SIP number that is being called + # @param sip [String] The SIP user's number or the PBX extension + # @param predicted [String] If specified, the request is predicted + # @return [Hash] + def callback(from:, to:, sip: nil, predicted: nil) + params = { from: from, to: to } + params[:sip] = sip if sip + params[:predicted] = predicted if predicted + @client.get('/request/callback/', params) + end + end + end +end diff --git a/lib/zadarma_sdk/resources/sip.rb b/lib/zadarma_sdk/resources/sip.rb new file mode 100644 index 0000000..755252c --- /dev/null +++ b/lib/zadarma_sdk/resources/sip.rb @@ -0,0 +1,79 @@ +# frozen_string_literal: true + +module ZadarmaSdk + module Resources + # The Sip resource allows you to manage your SIP numbers. + class Sip + def initialize(client:) + @client = client + end + + # Get the list of user's SIP-numbers + # @return [Hash] + def all + @client.get('/sip/') + end + + # Set the CallerID for a SIP number + # @param id [String] The SIP ID + # @param number [String] The new CallerID + # @return [Hash] + def set_caller_id(id:, number:) + @client.put('/sip/callerid/', id: id, number: number) + end + + # Get call forwarding information for a SIP number + # @param id [String] The SIP ID + # @return [Hash] + def redirection(id: nil) + params = {} + params[:id] = id if id + @client.get('/sip/redirection/', params) + end + + # Set call forwarding for a SIP number + # @param id [String] The SIP ID + # @param status [String] The call forwarding status ('on' or 'off') + # @param type [String] The call forwarding type ('phone', 'voicemail', etc.) + # @param number [String] The destination number for call forwarding + # @param condition [String] The call forwarding condition ('always', 'noanswer', etc.) + # @return [Hash] + def set_redirection(id:, status:, type: nil, number: nil, condition: nil) + params = { id: id, status: status } + params[:type] = type if type + params[:number] = number if number + params[:condition] = condition if condition + @client.put('/sip/redirection/', params) + end + + # Get the online status of a SIP number + # @param sip [String] The SIP number + # @return [Hash] + def status(sip:) + @client.get("/sip/#{sip}/status/") + end + + # Create a new SIP number + # @param name [String] The displayed name for the new SIP number + # @param password [String] The password for the new SIP number + # @param callerid [String] The CallerID for the new SIP number + # @param redirect_to_phone [String] The phone number to redirect calls to + # @return [Hash] + def create(name:, password: nil, callerid: nil, redirect_to_phone: nil) + params = { name: name } + params[:password] = password if password + params[:callerid] = callerid if callerid + params[:redirect_to_phone] = redirect_to_phone if redirect_to_phone + @client.post('/sip/create/', params) + end + + # Change the password for a SIP number + # @param sip [String] The SIP number + # @param value [String] The new password + # @return [Hash] + def password(sip:, value:) + @client.put("/sip/#{sip}/password/", value: value) + end + end + end +end diff --git a/lib/zadarma_sdk/resources/sms.rb b/lib/zadarma_sdk/resources/sms.rb new file mode 100644 index 0000000..c2ec5bc --- /dev/null +++ b/lib/zadarma_sdk/resources/sms.rb @@ -0,0 +1,23 @@ +# frozen_string_literal: true + +module ZadarmaSdk + module Resources + # The Sms resource allows you to send SMS messages. + class Sms + def initialize(client:) + @client = client + end + + # Send an SMS message + # @param number [String] The destination phone number + # @param message [String] The SMS message text + # @param sender [String] The SMS sender (virtual number or text) + # @return [Hash] + def send_sms(number:, message:, sender: nil) + params = { number: number, message: message } + params[:sender] = sender if sender + @client.post('/sms/send/', params) + end + end + end +end diff --git a/lib/zadarma_sdk/resources/speech_recognition.rb b/lib/zadarma_sdk/resources/speech_recognition.rb new file mode 100644 index 0000000..6f741c6 --- /dev/null +++ b/lib/zadarma_sdk/resources/speech_recognition.rb @@ -0,0 +1,36 @@ +# frozen_string_literal: true + +module ZadarmaSdk + module Resources + # The SpeechRecognition resource allows you to manage speech recognition. + class SpeechRecognition + def initialize(client:) + @client = client + end + + # Get recognition results + # @param call_id [String] The unique call ID + # @param lang [String] The recognition language + # @param return_results [String] The returned result ('words' or 'phrases') + # @param alternatives [String] Return alternative results ('0' or '1') + # @return [Hash] + def get(call_id:, lang: nil, return_results: nil, alternatives: nil) + params = { call_id: call_id } + params[:lang] = lang if lang + params[:return] = return_results if return_results + params[:alternatives] = alternatives if alternatives + @client.get('/speech_recognition/', params) + end + + # Initiate call recognition + # @param call_id [String] The unique call ID + # @param lang [String] The recognition language + # @return [Hash] + def initiate(call_id:, lang: nil) + params = { call_id: call_id } + params[:lang] = lang if lang + @client.put('/speech_recognition/', params) + end + end + end +end diff --git a/lib/zadarma_sdk/resources/statistics.rb b/lib/zadarma_sdk/resources/statistics.rb new file mode 100644 index 0000000..d12d51e --- /dev/null +++ b/lib/zadarma_sdk/resources/statistics.rb @@ -0,0 +1,49 @@ +# frozen_string_literal: true + +require 'time' + +module ZadarmaSdk + module Resources + # The Statistics resource provides access to call statistics. + class Statistics + def initialize(client:) + @client = client + end + + # Get overall call statistics + # @param params [Hash] The parameters for the statistics request + # @option params [String] :start The start date of the statistics display + # @option params [String] :end The end date of the statistics display + # @option params [String] :sip Filter based on a specific SIP number + # @option params [String] :cost_only Display only the amount of funds spent + # @option params [String] :type Request type ('overall' or 'toll-free') + # @option params [Integer] :skip Number of lines to be skipped in the sample + # @option params [Integer] :limit The limit on the number of input lines + # @return [Hash] + def statistics(params) + response = @client.get('/statistics/', params) + response['stats']&.each do |stat| + stat['callstart'] = Time.parse(stat['callstart']) if stat['callstart'] + end + response + end + + # Get PBX call statistics + # @param params [Hash] The parameters for the PBX statistics request + # @option params [String] :start The start date of the statistics display + # @option params [String] :end The end date of the statistics display + # @option params [String] :version Format of the statistics result ('1' or '2') + # @option params [Integer] :skip Number of lines to be skipped in the sample + # @option params [Integer] :limit The limit on the number of input lines + # @option params [String] :call_type Call destination ('in' or 'out') + # @return [Hash] + def pbx_statistics(params) + response = @client.get('/statistics/pbx/', params) + response['stats']&.each do |stat| + stat['callstart'] = Time.parse(stat['callstart']) if stat['callstart'] + end + response + end + end + end +end diff --git a/lib/zadarma_sdk/version.rb b/lib/zadarma_sdk/version.rb new file mode 100644 index 0000000..3f77048 --- /dev/null +++ b/lib/zadarma_sdk/version.rb @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +module ZadarmaSdk + VERSION = '2.0.0' +end diff --git a/mkdocs/direct_numbers.md b/mkdocs/direct_numbers.md new file mode 100644 index 0000000..d922384 --- /dev/null +++ b/mkdocs/direct_numbers.md @@ -0,0 +1,111 @@ +# Direct Numbers Resource + +The Direct Numbers resource allows you to manage virtual numbers. + +## `all()` + +Get information about the user's virtual numbers. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.direct_numbers +``` + +## `countries(language: nil)` + +Get a list of countries where numbers can be ordered. + +**Parameters:** + +* `language` (String): The language for the country names. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.direct_number_countries(language: 'en') +``` + +## `country(country:, language: nil, direction_id: nil)` + +Get a list of destinations in a country where a number can be ordered. + +**Parameters:** + +* `country` (String): The ISO country code. +* `language` (String): The language for the destination names. +* `direction_id` (String): The direction ID. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.direct_number_country(country: 'US') +``` + +## `available(direction_id:, mask: nil)` + +Get a list of available numbers for a given direction. + +**Parameters:** + +* `direction_id` (String): The direction ID. +* `mask` (String): A mask for searching number matches. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.available_direct_numbers(direction_id: '123') +``` + +## `order(params)` + +Order a virtual number. + +**Parameters:** + +* `params` (Hash): The parameters for ordering a number. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.order_direct_number(direction_id: '123', number_id: '456') +``` + +## `prolong(number:, months:)` + +Prepay the number for the specified number of months. + +**Parameters:** + +* `number` (String): The number to be prolonged. +* `months` (Integer): The number of months. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.prolong_direct_number(number: '1234567890', months: 3) +``` diff --git a/mkdocs/groups_of_documents.md b/mkdocs/groups_of_documents.md new file mode 100644 index 0000000..6cfb9ed --- /dev/null +++ b/mkdocs/groups_of_documents.md @@ -0,0 +1,90 @@ +# Groups of Documents Resource + +The Groups of Documents resource allows you to manage groups of documents. + +## `files(group_id: nil)` + +Get the list of files/documents in the group of documents. + +**Parameters:** + +* `group_id` (String): The group of documents ID. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.document_files(group_id: '123') +``` + +## `list()` + +Get the list of groups of documents. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.document_groups +``` + +## `get(id:)` + +Get information on a certain group. + +**Parameters:** + +* `id` (String): The group ID. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.get_document_group(id: '123') +``` + +## `create(params:)` + +Create a new group of documents. + +**Parameters:** + +* `params` (Hash): The parameters for creating a new group of documents. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.create_document_group(params: { name: 'My Group' }) +``` + +## `update(id:, params:)` + +Update a group of documents. + +**Parameters:** + +* `id` (String): The group ID. +* `params` (Hash): The parameters for updating a group of documents. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.update_document_group(id: '123', params: { name: 'My New Group' }) +``` diff --git a/mkdocs/index.md b/mkdocs/index.md new file mode 100644 index 0000000..9aeec44 --- /dev/null +++ b/mkdocs/index.md @@ -0,0 +1,45 @@ +# Zadarma SDK Ruby Client Documentation + +Welcome to the developer documentation for the Zadarma SDK Ruby Client. This guide provides detailed information about every aspect of the gem, from installation and configuration to a complete reference of all available API methods. + +## Getting Started + +### Installation + +Add this line to your application's Gemfile: + +```ruby +gem 'zadarma_sdk' +``` + +And then execute: + + $ bundle + +Or install it yourself as: + + $ gem install zadarma_sdk + +### Configuration + +First, configure the client with your API key and secret. You can find these in your Zadarma personal account. + +```ruby +require 'zadarma_sdk' + +client = ZadarmaSdk::Client.new(api_key: 'YOUR_API_KEY', api_secret: 'YOUR_API_SECRET') +``` + +## API Resources + +This client is organized into resources, mirroring the Zadarma API structure. Click on a resource below for a detailed list of its methods and parameters. + +* [Info](info.md) +* [PBX](pbx.md) +* [Direct Numbers](direct_numbers.md) +* [Request](request.md) +* [SIP](sip.md) +* [SMS](sms.md) +* [Statistics](statistics.md) +* [Speech Recognition](speech_recognition.md) +* [Groups of Documents](groups_of_documents.md) diff --git a/mkdocs/info.md b/mkdocs/info.md new file mode 100644 index 0000000..01f9e6c --- /dev/null +++ b/mkdocs/info.md @@ -0,0 +1,36 @@ +# Info Resource + +The Info resource provides access to user information, such as balance and call rates. + +## `balance()` + +Get the user's balance. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.balance +``` + +## `price(number:, caller_id: nil)` + +Get the call rate for a given number. + +**Parameters:** + +* `number` (String): The phone number. +* `caller_id` (String): The CallerID to be used for the call. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.price(number: '1234567890') +``` diff --git a/mkdocs/pbx.md b/mkdocs/pbx.md new file mode 100644 index 0000000..450312c --- /dev/null +++ b/mkdocs/pbx.md @@ -0,0 +1,58 @@ +# PBX Resource + +The PBX resource allows you to manage your Zadarma PBX. + +## `internal()` + +Get the list of PBX internal numbers. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.internal_numbers +``` + +## `set_call_recording(id:, status:, email: nil, speech_recognition: nil)` + +Set the call recording for a PBX extension. + +**Parameters:** + +* `id` (String): The PBX extension ID. +* `status` (String): The call recording status ('on', 'off', etc.). +* `email` (String): The email address to send recordings to. +* `speech_recognition` (String): The speech recognition settings. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.set_call_recording(id: '123', status: 'on') +``` + +## `pbx_record_request(call_id: nil, pbx_call_id: nil, lifetime: nil)` + +Request a call recording file. + +**Parameters:** + +* `call_id` (String): The unique call ID. +* `pbx_call_id` (String): The permanent ID of the external call to the PBX. +* `lifetime` (Integer): The link's lifetime in seconds. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.pbx_record_request(call_id: '12345') +``` diff --git a/mkdocs/request.md b/mkdocs/request.md new file mode 100644 index 0000000..44cf9f5 --- /dev/null +++ b/mkdocs/request.md @@ -0,0 +1,24 @@ +# Request Resource + +The Request resource allows you to initiate callbacks. + +## `callback(from:, to:, sip: nil, predicted: nil)` + +Request a callback. + +**Parameters:** + +* `from` (String): Your phone/SIP number, the PBX extension or the PBX scenario. +* `to` (String): The phone or SIP number that is being called. +* `sip` (String): The SIP user's number or the PBX extension. +* `predicted` (String): If specified, the request is predicted. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.callback(from: '1234567890', to: '0987654321') +``` diff --git a/mkdocs/sip.md b/mkdocs/sip.md new file mode 100644 index 0000000..5366c7a --- /dev/null +++ b/mkdocs/sip.md @@ -0,0 +1,134 @@ +# SIP Resource + +The SIP resource allows you to manage your SIP numbers. + +## `all()` + +Get the list of user's SIP-numbers. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.sips +``` + +## `set_caller_id(id:, number:)` + +Set the CallerID for a SIP number. + +**Parameters:** + +* `id` (String): The SIP ID. +* `number` (String): The new CallerID. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.set_sip_caller_id(id: '123', number: '1234567890') +``` + +## `redirection(id: nil)` + +Get call forwarding information for a SIP number. + +**Parameters:** + +* `id` (String): The SIP ID. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.redirection(id: '123') +``` + +## `set_redirection(id:, status:, type: nil, number: nil, condition: nil)` + +Set call forwarding for a SIP number. + +**Parameters:** + +* `id` (String): The SIP ID. +* `status` (String): The call forwarding status ('on' or 'off'). +* `type` (String): The call forwarding type ('phone', 'voicemail', etc.). +* `number` (String): The destination number for call forwarding. +* `condition` (String): The call forwarding condition ('always', 'noanswer', etc.). + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.set_redirection(id: '123', status: 'on', type: 'phone', number: '1234567890') +``` + +## `status(sip:)` + +Get the online status of a SIP number. + +**Parameters:** + +* `sip` (String): The SIP number. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.sip_status(sip: '123') +``` + +## `create(name:, password: nil, callerid: nil, redirect_to_phone: nil)` + +Create a new SIP number. + +**Parameters:** + +* `name` (String): The displayed name for the new SIP number. +* `password` (String): The password for the new SIP number. +* `callerid` (String): The CallerID for the new SIP number. +* `redirect_to_phone` (String): The phone number to redirect calls to. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.create_sip(name: 'My SIP') +``` + +## `password(sip:, value:)` + +Change the password for a SIP number. + +**Parameters:** + +* `sip` (String): The SIP number. +* `value` (String): The new password. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.set_sip_password(sip: '123', value: 'new_password') +``` diff --git a/mkdocs/sms.md b/mkdocs/sms.md new file mode 100644 index 0000000..dad4fc4 --- /dev/null +++ b/mkdocs/sms.md @@ -0,0 +1,23 @@ +# SMS Resource + +The SMS resource allows you to send SMS messages. + +## `send_sms(number:, message:, sender: nil)` + +Send an SMS message. + +**Parameters:** + +* `number` (String): The destination phone number. +* `message` (String): The SMS message text. +* `sender` (String): The SMS sender (virtual number or text). + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.send_sms(number: '1234567890', message: 'Hello, world!') +``` diff --git a/mkdocs/speech_recognition.md b/mkdocs/speech_recognition.md new file mode 100644 index 0000000..667b9b3 --- /dev/null +++ b/mkdocs/speech_recognition.md @@ -0,0 +1,43 @@ +# Speech Recognition Resource + +The Speech Recognition resource allows you to manage speech recognition. + +## `get(call_id:, lang: nil, return_results: nil, alternatives: nil)` + +Get recognition results. + +**Parameters:** + +* `call_id` (String): The unique call ID. +* `lang` (String): The recognition language. +* `return_results` (String): The returned result ('words' or 'phrases'). +* `alternatives` (String): Return alternative results ('0' or '1'). + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.get_speech_recognition(call_id: '12345') +``` + +## `initiate(call_id:, lang: nil)` + +Initiate call recognition. + +**Parameters:** + +* `call_id` (String): The unique call ID. +* `lang` (String): The recognition language. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.initiate_speech_recognition(call_id: '12345') +``` diff --git a/mkdocs/statistics.md b/mkdocs/statistics.md new file mode 100644 index 0000000..427bda4 --- /dev/null +++ b/mkdocs/statistics.md @@ -0,0 +1,39 @@ +# Statistics Resource + +The Statistics resource provides access to call statistics. + +## `statistics(params)` + +Get overall call statistics. + +**Parameters:** + +* `params` (Hash): The parameters for the statistics request. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.statistics(start: '2023-01-01', end: '2023-01-31') +``` + +## `pbx_statistics(params)` + +Get PBX call statistics. + +**Parameters:** + +* `params` (Hash): The parameters for the PBX statistics request. + +**Returns:** + +A `Hash` containing the API response. + +**Example:** + +```ruby +client.pbx_statistics(start: '2023-01-01', end: '2023-01-31') +``` diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index 1aa9c67..d504b68 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +require 'zadarma_sdk' require 'webmock/rspec' WebMock.disable_net_connect!(allow_localhost: true) diff --git a/spec/zadarma_sdk/client_spec.rb b/spec/zadarma_sdk/client_spec.rb new file mode 100644 index 0000000..b5acc57 --- /dev/null +++ b/spec/zadarma_sdk/client_spec.rb @@ -0,0 +1,11 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Client do + let(:client) { described_class.new(api_key: 'test_key', api_secret: 'test_secret') } + + describe '#initialize' do + it 'creates a new client' do + expect(client).to be_a(described_class) + end + end +end diff --git a/spec/zadarma_sdk/resources/direct_numbers_spec.rb b/spec/zadarma_sdk/resources/direct_numbers_spec.rb new file mode 100644 index 0000000..b16e5e6 --- /dev/null +++ b/spec/zadarma_sdk/resources/direct_numbers_spec.rb @@ -0,0 +1,16 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::DirectNumbers do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:direct_numbers) { described_class.new(client: client) } + + describe '#all' do + it 'gets all direct numbers' do + stub_request(:get, /api.zadarma.com\/v1\/direct_numbers\//) + .to_return(body: { status: 'success', numbers: [] }.to_json) + + response = direct_numbers.all + expect(response['status']).to eq('success') + end + end +end diff --git a/spec/zadarma_sdk/resources/groups_of_documents_spec.rb b/spec/zadarma_sdk/resources/groups_of_documents_spec.rb new file mode 100644 index 0000000..9d80987 --- /dev/null +++ b/spec/zadarma_sdk/resources/groups_of_documents_spec.rb @@ -0,0 +1,16 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::GroupsOfDocuments do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:groups_of_documents) { described_class.new(client: client) } + + describe '#list' do + it 'gets a list of groups of documents' do + stub_request(:get, /api.zadarma.com\/v1\/documents\/groups\/list\//) + .to_return(body: { status: 'success', groups: [] }.to_json) + + response = groups_of_documents.list + expect(response['status']).to eq('success') + end + end +end diff --git a/spec/zadarma_sdk/resources/info_spec.rb b/spec/zadarma_sdk/resources/info_spec.rb new file mode 100644 index 0000000..e40e006 --- /dev/null +++ b/spec/zadarma_sdk/resources/info_spec.rb @@ -0,0 +1,26 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::Info do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:info) { described_class.new(client: client) } + + describe '#balance' do + it 'gets the balance' do + stub_request(:get, /api.zadarma.com\/v1\/info\/balance\//) + .to_return(body: { status: 'success', balance: 100 }.to_json) + + response = info.balance + expect(response['status']).to eq('success') + end + end + + describe '#price' do + it 'gets the price' do + stub_request(:get, /api.zadarma.com\/v1\/info\/price\//) + .to_return(body: { status: 'success', price: 0.1 }.to_json) + + response = info.price(number: '1234567890') + expect(response['status']).to eq('success') + end + end +end diff --git a/spec/zadarma_sdk/resources/pbx_spec.rb b/spec/zadarma_sdk/resources/pbx_spec.rb new file mode 100644 index 0000000..d07e441 --- /dev/null +++ b/spec/zadarma_sdk/resources/pbx_spec.rb @@ -0,0 +1,16 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::Pbx do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:pbx) { described_class.new(client: client) } + + describe '#internal' do + it 'gets internal numbers' do + stub_request(:get, /api.zadarma.com\/v1\/pbx\/internal\//) + .to_return(body: { status: 'success', numbers: [] }.to_json) + + response = pbx.internal + expect(response['status']).to eq('success') + end + end +end diff --git a/spec/zadarma_sdk/resources/request_spec.rb b/spec/zadarma_sdk/resources/request_spec.rb new file mode 100644 index 0000000..2776b4c --- /dev/null +++ b/spec/zadarma_sdk/resources/request_spec.rb @@ -0,0 +1,16 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::Request do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:request) { described_class.new(client: client) } + + describe '#callback' do + it 'requests a callback' do + stub_request(:get, /api.zadarma.com\/v1\/request\/callback\//) + .to_return(body: { status: 'success' }.to_json) + + response = request.callback(from: '123', to: '456') + expect(response['status']).to eq('success') + end + end +end diff --git a/spec/zadarma_sdk/resources/sip_spec.rb b/spec/zadarma_sdk/resources/sip_spec.rb new file mode 100644 index 0000000..ef537e6 --- /dev/null +++ b/spec/zadarma_sdk/resources/sip_spec.rb @@ -0,0 +1,16 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::Sip do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:sip) { described_class.new(client: client) } + + describe '#all' do + it 'gets all sips' do + stub_request(:get, /api.zadarma.com\/v1\/sip\//) + .to_return(body: { status: 'success', sips: [] }.to_json) + + response = sip.all + expect(response['status']).to eq('success') + end + end +end diff --git a/spec/zadarma_sdk/resources/sms_spec.rb b/spec/zadarma_sdk/resources/sms_spec.rb new file mode 100644 index 0000000..d821ad8 --- /dev/null +++ b/spec/zadarma_sdk/resources/sms_spec.rb @@ -0,0 +1,16 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::Sms do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:sms) { described_class.new(client: client) } + + describe '#send_sms' do + it 'sends an SMS' do + stub_request(:post, /api.zadarma.com\/v1\/sms\/send\//) + .to_return(body: { status: 'success' }.to_json) + + response = sms.send_sms(number: '1234567890', message: 'Hello') + expect(response['status']).to eq('success') + end + end +end diff --git a/spec/zadarma_sdk/resources/speech_recognition_spec.rb b/spec/zadarma_sdk/resources/speech_recognition_spec.rb new file mode 100644 index 0000000..5568949 --- /dev/null +++ b/spec/zadarma_sdk/resources/speech_recognition_spec.rb @@ -0,0 +1,26 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::SpeechRecognition do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:speech_recognition) { described_class.new(client: client) } + + describe '#get' do + it 'gets speech recognition' do + stub_request(:get, /api.zadarma.com\/v1\/speech_recognition\//) + .to_return(body: { status: 'success' }.to_json) + + response = speech_recognition.get(call_id: '123') + expect(response['status']).to eq('success') + end + end + + describe '#initiate' do + it 'initiates speech recognition' do + stub_request(:put, /api.zadarma.com\/v1\/speech_recognition\//) + .to_return(body: { status: 'success' }.to_json) + + response = speech_recognition.initiate(call_id: '123') + expect(response['status']).to eq('success') + end + end +end diff --git a/spec/zadarma_sdk/resources/statistics_spec.rb b/spec/zadarma_sdk/resources/statistics_spec.rb new file mode 100644 index 0000000..dc9d833 --- /dev/null +++ b/spec/zadarma_sdk/resources/statistics_spec.rb @@ -0,0 +1,26 @@ +# frozen_string_literal: true + +RSpec.describe ZadarmaSdk::Resources::Statistics do + let(:client) { ZadarmaSdk::Client.new(api_key: 'test_key', api_secret: 'test_secret') } + let(:statistics) { described_class.new(client: client) } + + describe '#statistics' do + it 'gets statistics' do + stub_request(:get, /api.zadarma.com\/v1\/statistics\//) + .to_return(body: { status: 'success', stats: [] }.to_json) + + response = statistics.statistics(start: '2023-01-01', end_date: '2023-01-31') + expect(response['status']).to eq('success') + end + end + + describe '#pbx_statistics' do + it 'gets pbx statistics' do + stub_request(:get, /api.zadarma.com\/v1\/statistics\/pbx\//) + .to_return(body: { status: 'success', stats: [] }.to_json) + + response = statistics.pbx_statistics(start: '2023-01-01', end_date: '2023-01-31') + expect(response['status']).to eq('success') + end + end +end diff --git a/zadarma.gemspec b/zadarma_sdk.gemspec similarity index 91% rename from zadarma.gemspec rename to zadarma_sdk.gemspec index d071dee..82add21 100644 --- a/zadarma.gemspec +++ b/zadarma_sdk.gemspec @@ -1,7 +1,7 @@ # frozen_string_literal: true Gem::Specification.new do |s| - s.name = 'zadarma' + s.name = 'zadarma_sdk' s.version = '2.0.0' s.summary = 'A modern, robust, and tested Ruby client for the Zadarma API' s.description = 'A modern, robust, and fully-featured Ruby client for the Zadarma API.' @@ -23,4 +23,5 @@ Gem::Specification.new do |s| s.add_development_dependency 'rubocop', '~> 1.0' s.add_development_dependency 'rubocop-rspec', '~> 2.0' s.add_development_dependency 'webmock', '~> 3.0' + s.add_development_dependency 'yard', '~> 0.9' end