onlinesim 1.0.12 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: dc609c7fa536bec1b39a92a5d72f970b01670914c22bc9fbd39e1f8d5a2d4370
4
- data.tar.gz: 4f3b5c50ddc9e8bcf61c98e5d4baddac9abacdc242663d9cac6c3d1db38fee30
3
+ metadata.gz: 6e0b71a52a66215988199f175be20382ccfa1f0dbb18632f5720fa159d0fcf4a
4
+ data.tar.gz: 9512addf2dcc16873bac27043fc08a8e5e7e31ae690c424c988c6c8b0624332e
5
5
  SHA512:
6
- metadata.gz: 906b569f8269e12de1a036d7dced1f08bdb776230c97fd6e2884b5fca5232c6e85112540860a46e660c7dde58fce85d11ed2d52a7bf329c8e2ed23c12143d32a
7
- data.tar.gz: 97b36badfc2a693deac34fe0494b1714f6027cdf7d4c1d93a2b412f15ccd82b1b12ef2b956c2f0aac2f9d0452f497f1d68e7c29e8ddf411adae147a116f72af5
6
+ metadata.gz: ae411b2fd9db2ee029bf376fa707f0f2605fb7fe1102b424d2a8d7de9db9d71d11ddd24d6d83ed3bcdff0ff1c9f6e3ae78e9545538519b6bf68666757495696d
7
+ data.tar.gz: d97360f0ba0940dad8322235ea558a92e3ef639ec8610f72cf155b52a0b3bfd35423f552fc6dfffefc0897bc9dcc6bdaea05269715a291aacac948e7438b9d2e
data/CHANGELOG.md CHANGED
@@ -4,6 +4,66 @@ All notable changes to this project will be documented in this file.
4
4
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
5
5
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [2.1.0] - 2026-11-19
8
+
9
+ ### Added
10
+
11
+ - `OnlineSim::MockOnlineSim`: a built-in, in-process fake of the OnlineSim API for testing integrations offline — no network, key, money or clock. `mock.client` returns a normal `OnlineSim::Client` wired to it (`mock.transport` is the mock itself, a transport with `call(method, url, headers, body, timeout)`). It answers every endpoint the SDK calls like the real backend (HTTP 456 for a wrong key, string/int `response`, decimal-string money, `[]` for empty maps) and keeps balance, operations and rents. Test helpers: `add_sms`, `add_sms_after` (lets `wait_code` run with `interval: 0`), `fail_next`, `fail_next_transport`, `set_balance`, `balance`, `operations`, `rents`, `requests`, `reset`. Autoloaded by `require "onlinesim"` (nothing is loaded until first use); `require "onlinesim/mock"` works too. See the [testing guide](https://s00d.github.io/onlinesim-ruby-api/testing).
12
+ - Packaging checks in CI: `gem build --strict` (warnings fail the build) and a smoke test that builds the gem, installs it with `--install-dir` into an empty directory and runs the README "Testing" example on Ruby 3.0 and the latest Ruby.
13
+ - `.github/workflows/release.yml`: a version tag runs CI, checks the tag against `OnlineSim::VERSION`, publishes to RubyGems with trusted publishing (OIDC, no API key) and creates the GitHub release from this file.
14
+
15
+ ### Changed
16
+
17
+ - Gemspec `source_code_uri` points to the release tag's tree, so it no longer repeats `homepage` (RubyGems warned about the duplicate).
18
+
19
+ ## [2.0.0] - 2026-11-19
20
+
21
+ A rewrite. The public API changed; see the [docs](https://s00d.github.io/onlinesim-ruby-api/).
22
+
23
+ ### Removed
24
+
25
+ - Runtime dependencies `faraday`, `oj`, `thor`; the `onlinesim` CLI (`cli.rb`).
26
+ - The global `Faraday::Connection` monkeypatch that disabled TLS verification for every Faraday client in the process, and `Faraday.ignore_env_proxy`.
27
+ - The proxy API (`driver.proxy`) and the forward API (`driver.forward`, `getForward`).
28
+ - `numbers.service` (getService), `numbers.servicenumber` (getServiceNumber), `forward.repeat` (getNumRepeat): no backend route.
29
+ - `free.countries`, `free.numbers`, `free.messages`: the backend returns empty data for them; use `free.list`.
30
+ - `OnlineSim::Driver`, `Onlinesim::VERSION` (now `OnlineSim::VERSION`), `ServerError`, `BaseError`.
31
+ - `tester.rb`, `.travis.yml`, `bin/`, the committed `Gemfile.lock` and the `bundler ~> 2.2.27` dev pin.
32
+
33
+ ### Changed
34
+
35
+ - One client: `OnlineSim::Client.new(api_key:, base_url:, lang:, dev_id:, timeout:, transport:)`; sections are readers (`client.numbers`, `client.rent`, `client.user`, `client.free`).
36
+ - The API key is sent as `Authorization: Bearer <key>`, never in the query string.
37
+ - Errors: `OnlineSim::Error` → `ApiError` (`code`, `message`), `NoNumberError` (subclass of `ApiError`), `TransportError` (`status`, `body`), `TimeoutError`.
38
+ - Method names are snake_case: `get_with_number`, `state_one`, `tariffs_one`, `payment_history`, `wait_code`.
39
+ - `numbers.get(service, country = 7, reject: [...])`; `state(message_to_code:, order_by:, msg_list:)` / `state_one(tzid, ...)` take booleans; `order_by` is lowercase.
40
+ - `numbers.wait_code(tzid, interval: 5, timeout: 600, keep_open: false, full_message: false, since: nil)`, seconds, injectable `sleep:` / `now:`.
41
+ - `rent.get(country = 7, days = 1, extension: true)`: `extension` defaults to `true` (the server default; `false` makes the rent non-extendable for good).
42
+ - Results keep the server's string keys; money parsed to `Float`: `user.balance["balance"]`, rent `sum`.
43
+ - Ruby >= 3.0; gemspec license matches LICENSE (Apache-2.0); `Gemfile.lock` is not committed (library).
44
+
45
+ ### Fixed
46
+
47
+ - TLS certificates are verified (v1 disabled verification globally); the environment proxy is honoured.
48
+ - The host was hardcoded; `base_url` is configurable. No more double slashes (`/api//rent/...`).
49
+ - `dev_id` was always sent (empty); now only when set. Booleans are sent as `1`/`0`; unset parameters are omitted.
50
+ - `reject: {}` default and the stray `&&` in its encoding; `reject` is now a comma list.
51
+ - Error mapping was dead code (the check was a method defined inside the request but never called), so error codes came back as data. They now raise `ApiError`; an HTTP 456 wrong-key answer is an `ApiError`, non-JSON answers raise `TransportError`.
52
+ - `wait_code` closed the operation on the first poll, before any SMS (`nil != ""`), and gave up after 10 polls; it now returns only a real code, then closes.
53
+ - `rent.extend` sent no `days`; it now takes `days` (default 1).
54
+ - `state` sent `orderby=ASC`; the server accepts only lowercase. `state` returns `[]` instead of raising when there are no operations.
55
+ - Empty maps sent by PHP as `[]` (rent `extend`, `paylist`, free `numbers`, country `services`) are returned as `{}`.
56
+ - Rent requests always send `pagination=0`, so `messages` is a flat list.
57
+
58
+ ### Added
59
+
60
+ - `user.set_webhook_url(url)`, `user.clear_webhook_url`, `user.webhook_logs(page)`, `user.payment_history(page)`.
61
+ - `free.list(country:, number:, page:, count:)`.
62
+ - `OnlineSim.parse_webhook(payload)` for inbound `receiving_sms` / `rent_sms` webhooks.
63
+ - Injectable transport (`OnlineSim::NetHttpTransport` by default) and per-request `timeout`.
64
+ - Offline test suite (minitest, fake transport), opt-in integration test, RuboCop, CI on Ruby 3.0 and latest.
65
+ - Documentation site (Nuxt Content).
66
+
7
67
  ## [1.0.6] - 2019-08-12
8
68
  ### Changed
9
69
  - fix proxy
data/README.md CHANGED
@@ -1,31 +1,43 @@
1
- # Onlinesim Ruby API
1
+ # onlinesim
2
2
 
3
+ [![Gem Version](https://badge.fury.io/rb/onlinesim.svg)](https://rubygems.org/gems/onlinesim)
4
+ [![CI](https://github.com/s00d/onlinesim-ruby-api/actions/workflows/ci.yml/badge.svg)](https://github.com/s00d/onlinesim-ruby-api/actions/workflows/ci.yml)
3
5
 
4
- Wrapper for automatic reception of SMS-messages by onlinesim.ru
6
+ Ruby client for the [OnlineSim](https://onlinesim.io) API: SMS numbers, rent, account and free numbers.
7
+ Zero runtime dependencies (`Net::HTTP` + `JSON` from the standard library), Ruby 3.0+.
5
8
 
6
- [![Gem Version](https://badge.fury.io/rb/onlinesim.svg)](https://badge.fury.io/rb/onlinesim)
7
-
8
- ### Installation
9
- You can install or upgrade package with:
10
9
  ```bash
11
- $ gem install onlinesim
10
+ bundle add onlinesim
12
11
  ```
13
- ### Example
12
+
14
13
  ```ruby
15
- require 'onlinesim'
14
+ require "onlinesim"
16
15
 
17
- # ...
16
+ client = OnlineSim::Client.new(api_key: ENV["ONLINESIM_KEY"])
18
17
 
19
- driver = OnlineSim::Driver.new(:apikey => 'TOKEN').numbers
20
- tzid = driver.get('vkcom')
21
- puts driver.stateone(tzid)['number']
22
- puts driver.close(tzid)
18
+ b = client.user.balance
19
+ puts "available: #{b['balance'] - b['zbalance']} USD"
20
+
21
+ order = client.numbers.get_with_number("google", 44)
22
+ puts "enter #{order['number']} in the app"
23
+ puts "code: #{client.numbers.wait_code(order['tzid'])}"
23
24
  ```
24
25
 
25
- ## Documentation
26
+ ## Testing
26
27
 
27
- All documentation is in the wiki of this project - **[Documentation](https://github.com/s00d/onlinesim-ruby-api/wiki)**
28
+ `OnlineSim::MockOnlineSim` is a built-in offline fake of the API: test your integration without network, key or money.
29
+ More in the [testing guide](https://s00d.github.io/onlinesim-ruby-api/testing).
28
30
 
29
- ## Bugs
31
+ ```ruby
32
+ require "onlinesim"
33
+
34
+ mock = OnlineSim::MockOnlineSim.new(balance: 10)
35
+ client = mock.client
36
+
37
+ tzid = client.numbers.get("google", 44)
38
+ mock.add_sms_after(tzid, "Your code: 123-456", 2) # arrives on the third poll
39
+ raise "wrong code" unless client.numbers.wait_code(tzid, interval: 0) == "123456"
40
+ raise "wrong balance" unless mock.balance == 9.8
41
+ ```
30
42
 
31
- If you have any problems, please create Issues [here](https://github.com/s00d/onlinesim-ruby-api/issues)
43
+ Documentation: **https://s00d.github.io/onlinesim-ruby-api/** · Changes: [CHANGELOG.md](CHANGELOG.md) · License: Apache-2.0
@@ -0,0 +1,119 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "uri"
5
+ require "timeout"
6
+
7
+ module OnlineSim
8
+ DEFAULT_BASE_URL = "https://onlinesim.host/api/"
9
+
10
+ # OnlineSim API client.
11
+ #
12
+ # client = OnlineSim::Client.new(api_key: ENV["ONLINESIM_KEY"])
13
+ # client.user.balance["balance"]
14
+ class Client
15
+ DEFAULT_TIMEOUT = 30
16
+ BODY_EXCERPT = 500
17
+
18
+ attr_reader :numbers, :rent, :user, :free
19
+
20
+ # api_key - sent as "Authorization: Bearer <api_key>"; not needed for tariffs and free numbers.
21
+ # base_url - full API base, trailing slash optional.
22
+ # lang - `lang` query parameter.
23
+ # dev_id - `dev_id` query parameter, sent only when set.
24
+ # timeout - per-request timeout, seconds (Numeric).
25
+ # transport - object with `call(method, url, headers, body, timeout)`; see NetHttpTransport.
26
+ def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, lang: "en", dev_id: nil, timeout: DEFAULT_TIMEOUT,
27
+ transport: NetHttpTransport.new)
28
+ @api_key = blank?(api_key) ? nil : api_key.to_s
29
+ @base_url = base_url.end_with?("/") ? base_url : "#{base_url}/"
30
+ @lang = lang
31
+ @dev_id = blank?(dev_id) ? nil : dev_id.to_s
32
+ @timeout = timeout
33
+ @transport = transport
34
+
35
+ request = method(:request)
36
+ @numbers = Numbers.new(request)
37
+ @rent = Rent.new(request)
38
+ @user = User.new(request)
39
+ @free = Free.new(request)
40
+ end
41
+
42
+ def inspect
43
+ "#<#{self.class.name} base_url=#{@base_url.inspect} lang=#{@lang.inspect}>"
44
+ end
45
+
46
+ private
47
+
48
+ # The one request function the sections call. `endpoint` is relative to `base_url`, suffix included
49
+ # ("getNum.php"). Query values: nil/""/[] omitted, booleans 1/0, arrays a comma list. `body` switches to POST.
50
+ def request(endpoint, query: {}, body: nil)
51
+ url = "#{@base_url}#{endpoint}"
52
+ params = encode_query(query.merge(lang: @lang, dev_id: @dev_id))
53
+ url = "#{url}?#{params}" unless params.empty?
54
+ headers = { "Accept" => "application/json" }
55
+ headers["Authorization"] = "Bearer #{@api_key}" if @api_key
56
+ method = "GET"
57
+ unless body.nil?
58
+ method = "POST"
59
+ headers["Content-Type"] = "application/json"
60
+ body = JSON.generate(body)
61
+ end
62
+
63
+ status, text = send_request(method, url, headers, body)
64
+ begin
65
+ data = JSON.parse(text)
66
+ rescue JSON::ParserError
67
+ raise TransportError.new("HTTP #{status}: response is not JSON", status: status, body: text[0, BODY_EXCERPT])
68
+ end
69
+ # The body is checked before the status: a wrong key is HTTP 456 with {"response":"ERROR_WRONG_KEY"}.
70
+ return unwrap(data) if data.is_a?(Hash) && data.key?("response")
71
+ raise TransportError.new("HTTP #{status}", status: status, body: text[0, BODY_EXCERPT]) unless (200..299).cover?(status)
72
+
73
+ data
74
+ end
75
+
76
+ def send_request(method, url, headers, body)
77
+ @transport.call(method, url, headers, body, @timeout)
78
+ rescue ::Timeout::Error
79
+ raise TransportError, "Request timed out after #{@timeout} s"
80
+ rescue StandardError => e
81
+ raise TransportError, "Network error: #{e.message}"
82
+ end
83
+
84
+ # Success: strip `response`, return the rest. Error code: raise.
85
+ def unwrap(data)
86
+ response = data["response"]
87
+ rest = data.except("response")
88
+ return rest if [1, "1"].include?(response)
89
+
90
+ if response.is_a?(Hash)
91
+ # profile.php validation errors: {"response":{"webhook_url":["The webhook url must be a valid URL."]}}
92
+ raise ApiError.new("VALIDATION_ERROR", response.values.flatten.join("; "))
93
+ end
94
+
95
+ code = response.to_s
96
+ # Debug backends echo the code as `message`; prefer the readable fallback then.
97
+ message = rest["message"].is_a?(String) && rest["message"] != code ? rest["message"] : nil
98
+ raise NoNumberError.new(code, message) if %w[NO_NUMBER NO_NUMBER_FOR_FORWARD].include?(code)
99
+
100
+ raise ApiError.new(code, message)
101
+ end
102
+
103
+ def encode_query(query)
104
+ pairs = query.filter_map do |key, value|
105
+ value = value.join(",") if value.is_a?(Array)
106
+ next if blank?(value)
107
+
108
+ value = 1 if value == true
109
+ value = 0 if value == false
110
+ [key.to_s, value.to_s]
111
+ end
112
+ URI.encode_www_form(pairs)
113
+ end
114
+
115
+ def blank?(value)
116
+ value.nil? || value == ""
117
+ end
118
+ end
119
+ end
@@ -0,0 +1,67 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OnlineSim
4
+ # Base class of every error raised by the SDK.
5
+ class Error < StandardError; end
6
+
7
+ # The API answered with an error code in `response`.
8
+ class ApiError < Error
9
+ # Raw error code, e.g. "ERROR_WRONG_KEY".
10
+ attr_reader :code
11
+
12
+ def initialize(code, message = nil)
13
+ @code = code
14
+ super(message.nil? || message.empty? ? ERROR_MESSAGES.fetch(code, code) : message)
15
+ end
16
+ end
17
+
18
+ # No number is available right now (NO_NUMBER, NO_NUMBER_FOR_FORWARD). Retry later or pick another country.
19
+ class NoNumberError < ApiError; end
20
+
21
+ # Network failure, request timeout, or a response that is not JSON.
22
+ class TransportError < Error
23
+ # HTTP status, or nil when no response arrived (network error, timeout).
24
+ attr_reader :status
25
+ # Start of the response body (up to 500 chars), empty when none.
26
+ attr_reader :body
27
+
28
+ def initialize(message, status: nil, body: "")
29
+ super(message)
30
+ @status = status
31
+ @body = body
32
+ end
33
+ end
34
+
35
+ # `wait_code` gave up: no code arrived within its `timeout`.
36
+ class TimeoutError < Error; end
37
+
38
+ # Fallback messages for error codes the server sends without a `message`.
39
+ ERROR_MESSAGES = {
40
+ "ACCOUNT_BLOCKED" => "Account is blocked",
41
+ "ERROR_WRONG_KEY" => "Wrong API key",
42
+ "ERROR_NO_KEY" => "API key is missing",
43
+ "ERROR_NO_SERVICE" => "Service is not specified",
44
+ "API_ACCESS_DISABLED" => "API access is disabled in the profile",
45
+ "API_ACCESS_IP" => "API access from this IP is not allowed in the profile",
46
+ "ERROR_NO_TZID" => "tzid is not specified",
47
+ "ERROR_WRONG_TZID" => "Wrong tzid",
48
+ "ERROR_NO_OPERATIONS" => "No operations",
49
+ "NO_NUMBER" => "No numbers available for this service right now",
50
+ "NO_NUMBER_FOR_FORWARD" => "No numbers available for forwarding",
51
+ "NO_COUNTRY" => "Country not found",
52
+ "UNDEFINED_COUNTRY" => "Unknown country",
53
+ "WARNING_LOW_BALANCE" => "Not enough balance",
54
+ "EXCEEDED_CONCURRENT_OPERATIONS" => "Too many concurrent operations for this account",
55
+ "INTERVAL_CONCURRENT_REQUESTS_ERROR" => "Too many concurrent requests, try again in a few seconds",
56
+ "TRY_AGAIN_LATER" => "Temporarily unable to perform the request, try again later",
57
+ "ACCOUNT_IDENTIFICATION_REQUIRED" => "Account identification is required",
58
+ "ERROR_PARAMS" => "Wrong parameters",
59
+ "API_DISABLED" => "API is disabled",
60
+ "NO_COMPLETE_TZID" => "The operation cannot be closed yet",
61
+ "NO_CLOSE_RENT_US" => "US rent numbers cannot be closed early",
62
+ "UNDEFINED_DAYS" => "Unknown rent period",
63
+ "VALIDATION_ERROR" => "Validation failed",
64
+ "TZ_OVER_OK" => "Operation finished without a new code",
65
+ "ERROR_NO_ITEMS" => "Operation failed"
66
+ }.freeze
67
+ end
@@ -0,0 +1,17 @@
1
+ # frozen_string_literal: true
2
+
3
+ module OnlineSim
4
+ # Public free numbers: `client.free`. No key needed.
5
+ class Free
6
+ def initialize(request)
7
+ @request = request
8
+ end
9
+
10
+ # Countries, the numbers of the selected country and the SMS of the selected number.
11
+ # `number` is the number without its country code, as the keys of "numbers".
12
+ def list(country: nil, number: nil, page: nil, count: nil)
13
+ res = @request.call("getFreeList", query: { country: country, number: number, page: page, count: count })
14
+ { "countries" => res["countries"], "numbers" => Normalize.map(res["numbers"]), "messages" => res["messages"] }
15
+ end
16
+ end
17
+ end