ibanchecker 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5959a043f0fe0044a65aa74d7203b57aeeafd050934efa28b7776dd938f3026b
-  data.tar.gz: 891de691976d13de1c3e5a3a9bb50f4a79ffdbae62f3f2d4f45b445ca03ea125
+  metadata.gz: 703ae63dc085318f0be9dbea66816f2b2798fef508d2a3f3f6fe16d158c3834a
+  data.tar.gz: 8f11660e9baa9c337dea6e73ad88e014199a4e3abe5c25b63f3ec15aab6e127e
 SHA512:
-  metadata.gz: bce4770bafedfb4fc03437f602200ecc469d8bc7ed2c85615797ad8a743ef98d4ce14510035b55785ab72f79514bdacca6b951772e1fa68715d6ced637188384
-  data.tar.gz: 6b6186281e8edb97df2a3fb7b7ea6677df6a7850262265a518a0e06ac1f199d2d1798bf93184e146b66b313b11f20f5f4d91b13c5f649c8fc934d501ff3d7114
+  metadata.gz: 6ffeb4593b42dc8d1b25aeb889c529046490d33779681816feca20dd3ff636337f25f805cb2e2e521b444a202517e4ac5d2c149a5d5281d560d5c7cc41697e8b
+  data.tar.gz: '08d302dbe4737762672566fbc543e9bdd88bbcc1e5d63bef974747b772acc190d31e6f92f1083ca1ebd732791f7e24f606f1c5630a4679dc0864a88bf253e2a7'

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.1
+
+Documentation only; the client's behaviour is unchanged.
+
+- The API now requires a key for `validate`, `validate_bulk` and `extract`:
+  without one it answers 401 and the client raises `AuthenticationError`. The
+  free key covers 100 requests a month
+- `country_format` and `lookup_bic` still work without a key, limited to 100
+  requests an hour per IP
+- README, examples and doc comments construct the client with a key and say
+  which calls need it
+
 ## 0.1.0
 
 First release.

data/README.md

@@ -20,10 +20,12 @@ Requires Ruby 2.7 or newer. There are no runtime dependencies: the client is bui
 
 ## Quick start
 
+Validation, bulk validation and extraction need an API key. A free key covers 100 requests a month and arrives by email in seconds from [ibanchecker.cash/api-docs](https://ibanchecker.cash/api-docs).
+
 ```ruby
 require "ibanchecker"
 
-client = IbanChecker::Client.new   # no API key needed for light use (100 requests/hour per IP)
+client = IbanChecker::Client.new(ENV["IBANCHECKER_API_KEY"])   # or .new("iban_your_api_key")
 
 result = client.validate("DE89 3704 0044 0532 0130 00")
 
@@ -39,22 +41,26 @@ end
 
 ## Authentication
 
-An API key is optional. Without one, requests are limited to 100 per hour per IP. With a key, requests count against your plan quota. Get a free key at [ibanchecker.cash/api-docs](https://ibanchecker.cash/api-docs).
+`validate`, `validate_bulk` and `extract` need an API key. Without one the API answers HTTP 401 and the client raises `IbanChecker::AuthenticationError`. The free key from [ibanchecker.cash/api-docs](https://ibanchecker.cash/api-docs) covers 100 requests a month; paid plans are at [ibanchecker.cash/pricing](https://ibanchecker.cash/pricing).
+
+`country_format` and `lookup_bic` work without a key, limited to 100 requests an hour per IP.
 
 ```ruby
 client = IbanChecker::Client.new("iban_your_api_key")
 client = IbanChecker::Client.new(ENV["IBANCHECKER_API_KEY"])
+
+lookups = IbanChecker::Client.new   # country_format and lookup_bic only
 ```
 
 ## Methods
 
-| Method | Description |
-| --- | --- |
-| `validate(iban)` | Validate a single IBAN. Returns a `ValidationResult`. |
-| `validate_bulk(ibans)` | Validate up to 100 IBANs. Returns a `BatchResult`. |
-| `extract(text)` | Find and validate IBANs in free text (up to 50,000 chars). Returns a `BatchResult`. |
-| `country_format(country)` | IBAN format spec for an ISO country code. Returns a `FormatSpec`. |
-| `lookup_bic(bic)` | Resolve an 8 or 11 character BIC. Returns a `BankRecord`. |
+| Method | API key | Description |
+| --- | --- | --- |
+| `validate(iban)` | required | Validate a single IBAN. Returns a `ValidationResult`. |
+| `validate_bulk(ibans)` | required | Validate up to 100 IBANs. Returns a `BatchResult`. |
+| `extract(text)` | required | Find and validate IBANs in free text (up to 50,000 chars). Returns a `BatchResult`. |
+| `country_format(country)` | optional | IBAN format spec for an ISO country code. Returns a `FormatSpec`. |
+| `lookup_bic(bic)` | optional | Resolve an 8 or 11 character BIC. Returns a `BankRecord`. |
 
 `country_format` is the one name that differs from the other ibanchecker clients, where it is `getFormat`. `format` is `Kernel#format`, Ruby's `sprintf`, so a method by that name on this class would shadow it for every line inside the class.
 
@@ -138,7 +144,7 @@ end
 | `IbanChecker::BadRequestError` | HTTP 400, the request was malformed |
 | `IbanChecker::AuthenticationError` | HTTP 401, the API key is missing, invalid or inactive |
 | `IbanChecker::NotFoundError` | HTTP 404, no such country code or BIC |
-| `IbanChecker::RateLimitError` | HTTP 429, hourly limit or monthly quota exceeded |
+| `IbanChecker::RateLimitError` | HTTP 429, the key's monthly quota (`error_code` `"QUOTA_EXCEEDED"`) or the hourly limit for requests without a key (`"RATE_LIMIT_EXCEEDED"`) was exceeded |
 | `IbanChecker::APIError` | any other error status, or a body that could not be read |
 | `IbanChecker::TransportError` | the request never reached the API: DNS, TLS, connection, timeout |
 
@@ -147,7 +153,7 @@ All of them inherit from `IbanChecker::Error`, so one `rescue IbanChecker::Error
 ## Timeouts
 
 ```ruby
-client = IbanChecker::Client.new(timeout: 3.0)   # seconds, applied to connect and read
+client = IbanChecker::Client.new(ENV["IBANCHECKER_API_KEY"], timeout: 3.0)   # seconds, applied to connect and read
 ```
 
 ## Using your own HTTP stack

data/lib/ibanchecker/client.rb

@@ -9,10 +9,13 @@ module IbanChecker
   # extract IBANs from free text, look up country format specifications and
   # resolve SWIFT/BIC codes.
   #
-  # An API key is optional. Without one, requests are limited to 100 per hour
-  # per IP. Get a free key at https://ibanchecker.cash/api-docs.
+  # validate, validate_bulk and extract need an API key; without one the API
+  # answers 401 and AuthenticationError is raised. The free key from
+  # https://ibanchecker.cash/api-docs covers 100 requests a month.
+  # country_format and lookup_bic work without a key, limited to 100 requests
+  # an hour per IP.
   #
-  #   client = IbanChecker::Client.new          # or .new("iban_your_key")
+  #   client = IbanChecker::Client.new(ENV["IBANCHECKER_API_KEY"])   # or .new("iban_your_key")
   #   result = client.validate("DE89 3704 0044 0532 0130 00")
   #   puts "#{result.bank_name} #{result.bic}" if result.valid?
   class Client
@@ -42,12 +45,16 @@ module IbanChecker
     #
     # A malformed IBAN is not an error: the result comes back with +valid?+
     # false and an +error+ plus +error_code+ explaining why.
+    #
+    # Needs an API key.
     def validate(iban)
       ValidationResult.from_api(request("POST", "/validate", "iban" => iban.to_s))
     end
 
     # Validate up to 100 IBANs in one request. Results come back in the same
     # order as the input.
+    #
+    # Needs an API key.
     def validate_bulk(ibans)
       BatchResult.from_api(
         request("POST", "/validate/bulk", "ibans" => Array(ibans).map(&:to_s))
@@ -56,6 +63,8 @@ module IbanChecker
 
     # Scan free text (emails, invoices) for IBAN-shaped strings and validate
     # each candidate. Up to 50,000 characters per request.
+    #
+    # Needs an API key.
     def extract(text)
       BatchResult.from_api(request("POST", "/extract", "text" => text.to_s))
     end

data/lib/ibanchecker/errors.rb

@@ -33,7 +33,8 @@ module IbanChecker
   # The requested country code or BIC was not found (HTTP 404).
   class NotFoundError < Error; end
 
-  # The hourly rate limit or the monthly quota was exceeded (HTTP 429).
+  # The key's monthly quota ("QUOTA_EXCEEDED") or the hourly limit for requests
+  # without a key ("RATE_LIMIT_EXCEEDED") was exceeded (HTTP 429).
   class RateLimitError < Error; end
 
   # An unexpected server-side error, or a body that could not be read.

data/lib/ibanchecker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IbanChecker
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/ibanchecker.rb

@@ -10,7 +10,7 @@ require_relative "ibanchecker/client"
 #
 #   require "ibanchecker"
 #
-#   client = IbanChecker::Client.new
+#   client = IbanChecker::Client.new(ENV["IBANCHECKER_API_KEY"])
 #   result = client.validate("DE89370400440532013000")
 #   result.valid?      # => true
 #   result.bank_name   # => "Commerzbank AG Cologne"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ibanchecker
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - ibanchecker.cash
@@ -52,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Official Ruby client for the ibanchecker.cash IBAN validation API
 test_files: []