ibanchecker 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5959a043f0fe0044a65aa74d7203b57aeeafd050934efa28b7776dd938f3026b
-  data.tar.gz: 891de691976d13de1c3e5a3a9bb50f4a79ffdbae62f3f2d4f45b445ca03ea125
+  metadata.gz: bf9e74cb7e1a343e35c3bdd80928cbbf38872341b2c3b0f51959fde4bec0d96a
+  data.tar.gz: f83727602f144aa5e9da5f6e33b96e25ae6dda5b45e01bdc0c3af90222f716b4
 SHA512:
-  metadata.gz: bce4770bafedfb4fc03437f602200ecc469d8bc7ed2c85615797ad8a743ef98d4ce14510035b55785ab72f79514bdacca6b951772e1fa68715d6ced637188384
-  data.tar.gz: 6b6186281e8edb97df2a3fb7b7ea6677df6a7850262265a518a0e06ac1f199d2d1798bf93184e146b66b313b11f20f5f4d91b13c5f649c8fc934d501ff3d7114
+  metadata.gz: 7eeb15b1513861115327946aabc8825a9c28cc985aca96edc69b9f9e1bb523e23911ed90eb51243f241ec7ca19159435d16c13ab96f9d12512fd196c3edb7ad8
+  data.tar.gz: 9f64287aa482efb5ab341ce5416280d17f3469b8d0e1a8136cb223472ca8257e813105e16afa293f67feed2cf719a55b5e485bdb19f29fb5d32ea5293c3fd2d2

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.1.2
+
+Documentation only.
+
+- The API now requires a key for every call except `country_format`:
+  `lookup_bic` without one gets a 401 and the client raises
+  `AuthenticationError`. The hourly limit for requests without a key (100 an
+  hour per IP) now covers `country_format` only
+- What a key can call follows its plan. The free key covers `validate`, 100
+  requests a month; `validate_bulk` and `lookup_bic` need Basic or above;
+  `extract` needs Growth or above. A key with a verified account can try the
+  calls its plan lacks, with up to 10 IBANs per bulk call and 5,000
+  characters per extraction; a trial call over that size gets a 400
+  (`TOO_MANY_IBANS` or `TEXT_TOO_LONG`)
+- A call outside the key's plan gets a 403 with `error_code`
+  `PLAN_REQUIRED`, which the client raises as `APIError`; `#response` carries
+  `required_plan` and `upgrade_url`
+- `validate_bulk` counts one request per IBAN and `extract` one per IBAN
+  found, at least one per call. A call that costs more than the requests left
+  this month gets a 429 `QUOTA_EXCEEDED`, raised as `RateLimitError`
+- README and doc comments say which plan each call needs
+
+The client's behaviour does not change.
+
+## 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
 
+Every call except `country_format` needs an API key. A free key covers single IBAN validation, 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,27 +41,51 @@ 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`, `extract` and `lookup_bic` need an API key. Without one the API answers HTTP 401 and the client raises `IbanChecker::AuthenticationError`. `lookup_bic` used to work without a key; it no longer does. The free key from [ibanchecker.cash/api-docs](https://ibanchecker.cash/api-docs) covers `validate` only, 100 requests a month; paid plans are at [ibanchecker.cash/pricing](https://ibanchecker.cash/pricing).
+
+`country_format` is the only call that works without a key, limited to 100 requests an hour per IP. Beyond that the API answers HTTP 429 with `error_code` `"RATE_LIMIT_EXCEEDED"`. This hourly limit applies to `country_format` only.
 
 ```ruby
 client = IbanChecker::Client.new("iban_your_api_key")
 client = IbanChecker::Client.new(ENV["IBANCHECKER_API_KEY"])
+
+formats = IbanChecker::Client.new   # country_format only
 ```
 
+### What each plan can call
+
+| Method | Plan | Largest call |
+| --- | --- | --- |
+| `validate` | any key, including the free key | one IBAN |
+| `validate_bulk` | Basic or above (Basic, Starter, Growth, Enterprise) | 100 IBANs |
+| `lookup_bic` | Basic or above (Basic, Starter, Growth, Enterprise) | one BIC |
+| `extract` | Growth or above (Growth, Enterprise) | 50,000 characters |
+| `country_format` | no key needed | one country |
+
+A key whose email address has a verified account at [ibanchecker.cash/dashboard](https://ibanchecker.cash/dashboard) can try the calls its plan lacks: `validate_bulk` with up to 10 IBANs per call, `lookup_bic`, and `extract` with up to 5,000 characters per call. This applies to any plan that lacks the call, so a Basic key with a verified account can try `extract` as well. A trial call over that size gets HTTP 400 with `error_code` `"TOO_MANY_IBANS"` (bulk) or `"TEXT_TOO_LONG"` (extraction), which the client raises as `IbanChecker::BadRequestError`.
+
+A call outside the key's plan gets HTTP 403 with `error_code` `"PLAN_REQUIRED"`. The client has no class of its own for 403, so it raises `IbanChecker::APIError`; the decoded body on `#response` also carries `required_plan` (`"basic"` or `"growth"`) and `upgrade_url`. See [Error handling](#error-handling).
+
+### How requests are counted
+
+`validate` and `lookup_bic` count one request each. `validate_bulk` counts one request per IBAN in the call, and `extract` counts one per IBAN found, with at least one per call. A call that costs more than the requests left this month gets HTTP 429 with `error_code` `"QUOTA_EXCEEDED"`, raised as `IbanChecker::RateLimitError`.
+
 ## 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, any plan | Validate a single IBAN. Returns a `ValidationResult`. |
+| `validate_bulk(ibans)` | required, Basic or above | Validate up to 100 IBANs (10 on a trial). Returns a `BatchResult`. |
+| `extract(text)` | required, Growth or above | Find and validate IBANs in free text (up to 50,000 chars, 5,000 on a trial). Returns a `BatchResult`. |
+| `country_format(country)` | optional | IBAN format spec for an ISO country code. Returns a `FormatSpec`. |
+| `lookup_bic(bic)` | required, Basic or above | 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.
 
 ### Bulk validation
 
+Needs a key on the Basic plan or above, or a trial (see [What each plan can call](#what-each-plan-can-call)). Each IBAN in the call counts as one request.
+
 ```ruby
 batch = client.validate_bulk([
   "DE89370400440532013000",
@@ -80,6 +106,8 @@ end
 
 ### Extract from text
 
+Needs a key on the Growth plan or above, or a trial. Each IBAN found counts as one request, with at least one per call.
+
 ```ruby
 batch = client.extract("Please wire to DE89 3704 0044 0532 0130 00 by Friday.")
 
@@ -89,6 +117,8 @@ batch.map { |r| [r.iban, r.bank_name] }
 
 ### Country format and BIC lookup
 
+`country_format` works without a key. `lookup_bic` needs a key on the Basic plan or above, or a trial.
+
 ```ruby
 format = client.country_format("DE")
 format.length    # => 22
@@ -130,16 +160,20 @@ rescue IbanChecker::RateLimitError => e
   puts "Slow down: #{e.message}"
 rescue IbanChecker::AuthenticationError
   puts "Check your API key"
+rescue IbanChecker::APIError => e
+  raise unless e.error_code == "PLAN_REQUIRED"
+
+  puts "Needs the #{e.response["required_plan"]} plan: #{e.response["upgrade_url"]}"
 end
 ```
 
 | Class | Raised when |
 | --- | --- |
-| `IbanChecker::BadRequestError` | HTTP 400, the request was malformed |
-| `IbanChecker::AuthenticationError` | HTTP 401, the API key is missing, invalid or inactive |
+| `IbanChecker::BadRequestError` | HTTP 400, the request was malformed, or a trial call was over the trial size (`error_code` `"TOO_MANY_IBANS"` or `"TEXT_TOO_LONG"`) |
+| `IbanChecker::AuthenticationError` | HTTP 401, the API key is missing, invalid or inactive; every call except `country_format` gets this without a key |
 | `IbanChecker::NotFoundError` | HTTP 404, no such country code or BIC |
-| `IbanChecker::RateLimitError` | HTTP 429, hourly limit or monthly quota exceeded |
-| `IbanChecker::APIError` | any other error status, or a body that could not be read |
+| `IbanChecker::RateLimitError` | HTTP 429, the key's monthly quota was exceeded or the call costs more than the requests left (`error_code` `"QUOTA_EXCEEDED"`), or `country_format` without a key went over 100 requests an hour (`"RATE_LIMIT_EXCEEDED"`) |
+| `IbanChecker::APIError` | any other error status, including HTTP 403 for a call outside the key's plan (`error_code` `"PLAN_REQUIRED"`), or a body that could not be read |
 | `IbanChecker::TransportError` | the request never reached the API: DNS, TLS, connection, timeout |
 
 All of them inherit from `IbanChecker::Error`, so one `rescue IbanChecker::Error` catches everything this gem raises. Each carries `#status`, `#error_code` and `#response`.
@@ -147,7 +181,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,22 @@ 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.
+  # Every call except country_format needs an API key; without one the API
+  # answers 401 and AuthenticationError is raised. That includes lookup_bic,
+  # which used to work without a key. The free key from
+  # https://ibanchecker.cash/api-docs covers validate only, 100 requests a
+  # month. validate_bulk and lookup_bic need the Basic plan or above, and
+  # extract the Growth plan or above. A key whose email address has a verified
+  # account at https://ibanchecker.cash/dashboard can try the calls its plan
+  # lacks (validate_bulk up to 10 IBANs, extract up to 5,000 characters per
+  # call). A call outside the key's plan gets a 403 with error_code
+  # "PLAN_REQUIRED", raised as APIError; its #response carries required_plan
+  # and upgrade_url.
   #
-  #   client = IbanChecker::Client.new          # or .new("iban_your_key")
+  # country_format works without a key, limited to 100 requests an hour per
+  # IP. That hourly limit applies to country_format only.
+  #
+  #   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 +54,17 @@ 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; the free key covers it. Counts one request.
     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 on the Basic plan or above, or a trial of up to 10 IBANs
+    # per call for a key with a verified account. Counts one request per IBAN.
     def validate_bulk(ibans)
       BatchResult.from_api(
         request("POST", "/validate/bulk", "ibans" => Array(ibans).map(&:to_s))
@@ -56,6 +73,10 @@ 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 on the Growth plan or above, or a trial of up to 5,000
+    # characters per call for a key with a verified account. Counts one request
+    # per IBAN found, with at least one per call.
     def extract(text)
       BatchResult.from_api(request("POST", "/extract", "text" => text.to_s))
     end
@@ -65,11 +86,19 @@ module IbanChecker
     #
     # Named country_format rather than format because Kernel#format is
     # sprintf, and shadowing it inside this class would be a trap.
+    #
+    # The only call that works without a key, limited to 100 requests an hour
+    # per IP.
     def country_format(country)
       FormatSpec.from_api(request("GET", "/formats/#{escape(country.to_s.downcase)}"))
     end
 
     # Resolve an 8 or 11 character ISO 9362 BIC to a bank record.
+    #
+    # Needs an API key on the Basic plan or above, or a trial for a key with a
+    # verified account. Without a key the API answers 401 and
+    # AuthenticationError is raised; it no longer works keyless. Counts one
+    # request.
     def lookup_bic(bic)
       BankRecord.from_api(request("GET", "/swift/#{escape(bic.to_s.upcase)}"))
     end

data/lib/ibanchecker/errors.rb

@@ -24,19 +24,32 @@ module IbanChecker
     end
   end
 
-  # The request was malformed (HTTP 400).
+  # The request was malformed, or a trial call was over the trial size
+  # ("TOO_MANY_IBANS" for bulk, "TEXT_TOO_LONG" for extraction) (HTTP 400).
   class BadRequestError < Error; end
 
   # The API key is missing, invalid or inactive (HTTP 401).
+  #
+  # Every call except Client#country_format needs a key, so a call without
+  # one, a Client#lookup_bic included, gets this from the API's 401.
   class AuthenticationError < Error; end
 
   # 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 was exceeded, or the call costs more than the
+  # requests left this month ("QUOTA_EXCEEDED"), or Client#country_format
+  # without a key went over 100 requests an hour ("RATE_LIMIT_EXCEEDED")
+  # (HTTP 429). Bulk validation counts one request per IBAN and extraction one
+  # per IBAN found.
   class RateLimitError < Error; end
 
-  # An unexpected server-side error, or a body that could not be read.
+  # Any error status without a class of its own, or a body that could not be
+  # read.
+  #
+  # This includes HTTP 403 for a call outside the key's plan: error_code is
+  # "PLAN_REQUIRED" and #response carries "required_plan" ("basic" or
+  # "growth") and "upgrade_url".
   class APIError < Error; end
 
   # The request never reached the API: DNS, TLS, connection or timeout.

data/lib/ibanchecker/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module IbanChecker
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 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.2
 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: []