ibanchecker 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 703ae63dc085318f0be9dbea66816f2b2798fef508d2a3f3f6fe16d158c3834a
-  data.tar.gz: 8f11660e9baa9c337dea6e73ad88e014199a4e3abe5c25b63f3ec15aab6e127e
+  metadata.gz: bf9e74cb7e1a343e35c3bdd80928cbbf38872341b2c3b0f51959fde4bec0d96a
+  data.tar.gz: f83727602f144aa5e9da5f6e33b96e25ae6dda5b45e01bdc0c3af90222f716b4
 SHA512:
-  metadata.gz: 6ffeb4593b42dc8d1b25aeb889c529046490d33779681816feca20dd3ff636337f25f805cb2e2e521b444a202517e4ac5d2c149a5d5281d560d5c7cc41697e8b
-  data.tar.gz: '08d302dbe4737762672566fbc543e9bdd88bbcc1e5d63bef974747b772acc190d31e6f92f1083ca1ebd732791f7e24f606f1c5630a4679dc0864a88bf253e2a7'
+  metadata.gz: 7eeb15b1513861115327946aabc8825a9c28cc985aca96edc69b9f9e1bb523e23911ed90eb51243f241ec7ca19159435d16c13ab96f9d12512fd196c3edb7ad8
+  data.tar.gz: 9f64287aa482efb5ab341ce5416280d17f3469b8d0e1a8136cb223472ca8257e813105e16afa293f67feed2cf719a55b5e485bdb19f29fb5d32ea5293c3fd2d2

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # 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.

data/README.md

@@ -20,7 +20,7 @@ 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).
+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"
@@ -41,31 +41,51 @@ end
 
 ## Authentication
 
-`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).
+`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` and `lookup_bic` work without a key, limited to 100 requests an hour per IP.
+`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"])
 
-lookups = IbanChecker::Client.new   # country_format and lookup_bic only
+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 | 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`. |
+| `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)` | optional | Resolve an 8 or 11 character BIC. Returns a `BankRecord`. |
+| `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",
@@ -86,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.")
 
@@ -95,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
@@ -136,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, 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::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`.

data/lib/ibanchecker/client.rb

@@ -9,11 +9,20 @@ module IbanChecker
   # extract IBANs from free text, look up country format specifications and
   # resolve SWIFT/BIC codes.
   #
-  # 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.
+  # 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.
+  #
+  # 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")
@@ -46,7 +55,7 @@ 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.
+    # 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
@@ -54,7 +63,8 @@ module IbanChecker
     # Validate up to 100 IBANs in one request. Results come back in the same
     # order as the input.
     #
-    # Needs an API key.
+    # 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))
@@ -64,7 +74,9 @@ 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.
+    # 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
@@ -74,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,20 +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 key's monthly quota ("QUOTA_EXCEEDED") or the hourly limit for requests
-  # without a key ("RATE_LIMIT_EXCEEDED") 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.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ibanchecker
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - ibanchecker.cash