vatsense 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41320914ca748d7abab0a4baa5c65b59f1131a9c16a2e0a0ed1f79014f343765
-  data.tar.gz: 2700b3a5120dbf857f342a585791240977997c9645e569e2e8089f06ec7db6f2
+  metadata.gz: a6cbb8615a5f3366f1abe2d7ccd2c4eae2dbcc4ef9b85f72f2ea990e9aafd3d5
+  data.tar.gz: 97a498b7db5317fda34e1e4bcd508fc85a0654a1b64f4b1eac5d777b0cb2ab54
 SHA512:
-  metadata.gz: 252a750b1486d10ceda68cbf607dff22fa9429ea65c12fceee157f231e3b24c62ebd71fc1b9c13a57b25aa81fa7a90937d61d2dd19d40f539ac23a156b04d948
-  data.tar.gz: 8701628a0b041007aef2be237944a01332e528f4558dc117b36242ff60c8eecd72e641108be767ffb66a0a97da17af2265dbe58b73ada82ac3a73f13d8f5ea25
+  metadata.gz: 4ad0aaec6739477762e8d267919cf07fd3c863577c2394d982d99805804e7231fc318b09406d2e8cdef0d04c2fc432d14d0ab31bd7f267d15b6ae6f7318c7af2
+  data.tar.gz: 510b64b88384f3440a3f811588f428f0f8cb808c284ce4f2e419cad596d73a007e733984aa3ac1cd0db659870b96af0a51e967e192bddcf6e80b3c55870c70d4

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.1.1 (2026-04-01)
+
+Full Changelog: [v0.1.0...v0.1.1](https://github.com/VAT-Sense/vatsense-ruby/compare/v0.1.0...v0.1.1)
+
+### Bug Fixes
+
+* align path encoding with RFC 3986 section 3.3 ([876d20f](https://github.com/VAT-Sense/vatsense-ruby/commit/876d20f7d38dea0d3e1ce1d9320b583833576b84))
+* **internal:** correct multipart form field name encoding ([96c7cdd](https://github.com/VAT-Sense/vatsense-ruby/commit/96c7cdd5632efd1eb3904179312b2d21ac476439))
+* variable name typo ([6328709](https://github.com/VAT-Sense/vatsense-ruby/commit/63287096c06e8cb992946441e932177c07f2f456))
+
+
+### Chores
+
+* **ci:** skip lint on metadata-only changes ([e4e8c73](https://github.com/VAT-Sense/vatsense-ruby/commit/e4e8c73343b5045afbe01653e23301d9a43d194c))
+* **ci:** support opting out of skipping builds on metadata-only commits ([9db0960](https://github.com/VAT-Sense/vatsense-ruby/commit/9db09605215e8727e05cffeea18b91005424b590))
+* **internal:** update gitignore ([6122de9](https://github.com/VAT-Sense/vatsense-ruby/commit/6122de9f488047ff89c3df016886700ed802c335))
+
+
+### Documentation
+
+* **readme:** tailor README to VAT Sense use cases ([2b4823e](https://github.com/VAT-Sense/vatsense-ruby/commit/2b4823e2c9bc31eae4c073461defa8b2029f9be0))
+
 ## 0.1.0 (2026-03-18)
 
 Full Changelog: [v0.0.1...v0.1.0](https://github.com/VAT-Sense/vatsense-ruby/compare/v0.0.1...v0.1.0)

data/README.md

@@ -1,234 +1,204 @@
-# Vat Sense Ruby API library
+# VAT Sense Ruby SDK
 
-The Vat Sense Ruby library provides convenient access to the Vat Sense REST API from any Ruby 3.2.0+ application. It ships with comprehensive types & docstrings in Yard, RBS, and RBI – [see below](https://github.com/VAT-Sense/vatsense-ruby#Sorbet) for usage with Sorbet. The standard library's `net/http` is used as the HTTP transport, with connection pooling via the `connection_pool` gem.
-
-It is generated with [Stainless](https://www.stainless.com/).
-
-## Documentation
-
-Documentation for releases of this gem can be found [on RubyDoc](https://gemdocs.org/gems/vatsense).
-
-The REST API documentation can be found on [vatsense.com](https://vatsense.com).
+The official Ruby library for the [VAT Sense](https://vatsense.com) REST API. Validate VAT/EORI numbers, look up VAT/GST rates, calculate prices, convert currencies, and generate VAT-compliant invoices.
 
 ## Installation
 
-To use this gem, install via Bundler by adding the following to your application's `Gemfile`:
+```sh
+gem install vatsense
+```
 
-<!-- x-release-please-start-version -->
+Or add to your Gemfile:
 
 ```ruby
-gem "vatsense", "~> 0.1.0"
+gem "vatsense"
 ```
 
-<!-- x-release-please-end -->
+Requires Ruby 3.2.0+.
 
-## Usage
+## Quick start
+
+Create a client using your API key from the [VAT Sense dashboard](https://vatsense.com/dashboard). The API uses HTTP Basic Auth with `user` as the username and your API key as the password.
 
 ```ruby
-require "bundler/setup"
 require "vatsense"
 
-vat_sense = Vatsense::Client.new(
-  username: ENV["VAT_SENSE_USERNAME"], # This is the default and can be omitted
-  password: ENV["VAT_SENSE_PASSWORD"] # This is the default and can be omitted
+client = Vatsense::Client.new(
+  username: "user",
+  password: "your_api_key",
 )
-
-rates = vat_sense.rates.list
-
-puts(rates.code)
 ```
 
-### Handling errors
+You can also set the `VAT_SENSE_USERNAME` and `VAT_SENSE_PASSWORD` environment variables and the client will pick them up automatically.
 
-When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of `Vatsense::Errors::APIError` will be thrown:
+### Validate a VAT number
 
 ```ruby
-begin
-  rate = vat_sense.rates.list
-rescue Vatsense::Errors::APIConnectionError => e
-  puts("The server could not be reached")
-  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
-rescue Vatsense::Errors::RateLimitError => e
-  puts("A 429 status code was received; we should back off a bit.")
-rescue Vatsense::Errors::APIStatusError => e
-  puts("Another non-200-range status code was received")
-  puts(e.status)
+response = client.validate.check(vat_number: "GB288305674")
+
+if response.data.valid
+  puts response.data.company.company_name     # "BRITISH BROADCASTING CORPORATION"
+  puts response.data.company.company_address
+  puts response.data.company.country_code      # "GB"
 end
 ```
 
-Error codes are as follows:
-
-| Cause            | Error Type                 |
-| ---------------- | -------------------------- |
-| HTTP 400         | `BadRequestError`          |
-| HTTP 401         | `AuthenticationError`      |
-| HTTP 403         | `PermissionDeniedError`    |
-| HTTP 404         | `NotFoundError`            |
-| HTTP 409         | `ConflictError`            |
-| HTTP 422         | `UnprocessableEntityError` |
-| HTTP 429         | `RateLimitError`           |
-| HTTP >= 500      | `InternalServerError`      |
-| Other HTTP error | `APIStatusError`           |
-| Timeout          | `APITimeoutError`          |
-| Network error    | `APIConnectionError`       |
+VAT validation works for the UK, EU, Australia, Norway, Switzerland, South Africa, and Brazil.
 
-### Retries
-
-Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
-
-Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
-
-You can use the `max_retries` option to configure or disable this:
+### Validate an EORI number
 
 ```ruby
-# Configure the default for all requests:
-vat_sense = Vatsense::Client.new(
-  max_retries: 0 # default is 2
-)
+response = client.validate.check(eori_number: "GB123456789000")
 
-# Or, configure per-request:
-vat_sense.rates.list(request_options: {max_retries: 5})
+if response.data.valid
+  puts response.data.company.company_name
+end
 ```
 
-### Timeouts
+EORI validation is available for UK and EU numbers only.
+
+### Get a consultation number
 
-By default, requests will time out after 60 seconds. You can use the timeout option to configure or disable this:
+If you need an official consultation number from VIES (EU) or HMRC (UK), provide your own VAT number as the requester:
 
 ```ruby
-# Configure the default for all requests:
-vat_sense = Vatsense::Client.new(
-  timeout: nil # default is 60
+response = client.validate.check(
+  vat_number: "FR12345678901",
+  requester_vat_number: "FR98765432101",
 )
 
-# Or, configure per-request:
-vat_sense.rates.list(request_options: {timeout: 5})
+puts response.data.consultation_number
 ```
 
-On timeout, `Vatsense::Errors::APITimeoutError` is raised.
-
-Note that requests that time out are retried by default.
+> **Note:** GB requester numbers only work for GB validations, and EU requester numbers only work for EU validations. Cross-region requests are not supported.
 
-## Advanced concepts
+### Find the VAT rate for a country
 
-### BaseModel
-
-All parameter and response objects inherit from `Vatsense::Internal::Type::BaseModel`, which provides several conveniences, including:
-
-1. All fields, including unknown ones, are accessible with `obj[:prop]` syntax, and can be destructured with `obj => {prop: prop}` or pattern-matching syntax.
-
-2. Structural equivalence for equality; if two API calls return the same values, comparing the responses with == will return true.
+```ruby
+rate = client.rates.find(country_code: "DE")
 
-3. Both instances and the classes themselves can be pretty-printed.
+puts rate.data.country_name       # "Germany"
+puts rate.data.tax_rate.rate      # 19.0
+puts rate.data.tax_rate.class_    # "standard"
+```
 
-4. Helpers such as `#to_h`, `#deep_to_h`, `#to_json`, and `#to_yaml`.
+### Find a rate for a specific product type
 
-### Making custom or undocumented requests
+```ruby
+rate = client.rates.find(country_code: "DE", type: "ebooks")
 
-#### Undocumented properties
+puts rate.data.tax_rate.rate      # 7.0
+puts rate.data.tax_rate.class_    # "reduced"
+```
 
-You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
+### Find a rate by IP address
 
-Note: the `extra_` parameters of the same name overrides the documented parameters.
+Useful for determining the correct rate based on your customer's location:
 
 ```ruby
-rates =
-  vat_sense.rates.list(
-    request_options: {
-      extra_query: {my_query_parameter: value},
-      extra_body: {my_body_parameter: value},
-      extra_headers: {"my-header": value}
-    }
-  )
-
-puts(rates[:my_undocumented_property])
-```
-
-#### Undocumented request params
+rate = client.rates.find(ip_address: "185.86.151.11")
 
-If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` under the `request_options:` parameter when making a request, as seen in the examples above.
-
-#### Undocumented endpoints
+puts rate.data.country_code       # "GB"
+puts rate.data.tax_rate.rate      # 20.0
+```
 
-To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using `client.request`, like so:
+### Calculate a VAT-inclusive price
 
 ```ruby
-response = client.request(
-  method: :post,
-  path: '/undocumented/endpoint',
-  query: {"dog": "woof"},
-  headers: {"useful-header": "interesting-value"},
-  body: {"hello": "world"}
+result = client.rates.calculate_price(
+  price: "100.00",
+  tax_type: "excl",
+  country_code: "FR",
 )
-```
-
-### Concurrency & connection pooling
-
-The `Vatsense::Client` instances are threadsafe, but are only are fork-safe when there are no in-flight HTTP requests.
-
-Each instance of `Vatsense::Client` has its own HTTP connection pool with a default size of 99. As such, we recommend instantiating the client once per application in most settings.
 
-When all available connections from the pool are checked out, requests wait for a new connection to become available, with queue time counting towards the request timeout.
-
-Unless otherwise specified, other classes in the SDK do not have locks protecting their underlying data structure.
+puts result.data.vat_price.price_incl_vat  # Price including VAT
+puts result.data.vat_price.price_excl_vat  # Price excluding VAT
+puts result.data.vat_price.vat_rate        # VAT rate applied
+puts result.data.vat_price.vat             # VAT amount
+```
 
-## Sorbet
+### List all VAT rates
 
-This library provides comprehensive [RBI](https://sorbet.org/docs/rbi) definitions, and has no dependency on sorbet-runtime.
+```ruby
+rates = client.rates.list
 
-You can provide typesafe request parameters like so:
+rates.data.each do |rate|
+  puts "#{rate.country_code}: #{rate.country_name}"
+end
 
-```ruby
-vat_sense.rates.list
+# Filter to EU countries only
+eu_rates = client.rates.list(eu: true)
 ```
 
-Or, equivalently:
+## Handling errors
 
-```ruby
-# Hashes work, but are not typesafe:
-vat_sense.rates.list
+When the API returns an error, the library raises a typed exception:
 
-# You can also splat a full Params class:
-params = Vatsense::RateListParams.new
-vat_sense.rates.list(**params)
+```ruby
+begin
+  response = client.validate.check(vat_number: "GB288305674")
+rescue Vatsense::Errors::APIConnectionError => e
+  # Network issue, could not reach the API
+  puts e.message
+rescue Vatsense::Errors::RateLimitError => e
+  # 429: Too many requests (300/min general limit, 3/sec for UK validation)
+  puts "Rate limited, try again shortly"
+rescue Vatsense::Errors::APIStatusError => e
+  # Covers all other HTTP errors
+  puts e.status
+  puts e.message
+end
 ```
 
-### Enums
-
-Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
+A `412` error means the upstream validation service (VIES, HMRC, etc.) is temporarily unavailable. These requests do not count against your usage quota.
 
-```ruby
-# :incl
-puts(Vatsense::RateCalculatePriceParams::TaxType::INCL)
+| Status Code | Error Type                                  |
+| ----------- | ------------------------------------------- |
+| 400         | `Vatsense::Errors::BadRequestError`         |
+| 401         | `Vatsense::Errors::AuthenticationError`     |
+| 404         | `Vatsense::Errors::NotFoundError`           |
+| 409         | `Vatsense::Errors::ConflictError`           |
+| 429         | `Vatsense::Errors::RateLimitError`          |
+| >= 500      | `Vatsense::Errors::InternalServerError`     |
+| N/A         | `Vatsense::Errors::APIConnectionError`      |
 
-# Revealed type: `T.all(Vatsense::RateCalculatePriceParams::TaxType, Symbol)`
-T.reveal_type(Vatsense::RateCalculatePriceParams::TaxType::INCL)
-```
+## Retries
 
-Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
+Failed requests are automatically retried up to 2 times with exponential backoff. This includes connection errors, timeouts, 429, and 5xx responses.
 
 ```ruby
-# Using the enum constants preserves the tagged type information:
-vat_sense.rates.calculate_price(
-  tax_type: Vatsense::RateCalculatePriceParams::TaxType::INCL,
-  # …
+# Disable retries
+client = Vatsense::Client.new(
+  username: "user",
+  password: "your_api_key",
+  max_retries: 0,
 )
 
-# Literal values are also permissible:
-vat_sense.rates.calculate_price(
-  tax_type: :incl,
-  # …
+# Or configure per request
+response = client.validate.check(
+  vat_number: "GB288305674",
+  request_options: { max_retries: 5 },
 )
 ```
 
-## Versioning
+## Available services
 
-This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
+| Service               | Description                                     |
+| --------------------- | ----------------------------------------------- |
+| `client.validate`     | Validate VAT and EORI numbers                   |
+| `client.rates`        | VAT/GST rate lookups, price calculations         |
+| `client.countries`    | Country data and province lookups                |
+| `client.currency`     | Exchange rates and currency conversion           |
+| `client.invoice`      | Create and manage VAT-compliant invoices         |
+| `client.usage`        | Check your API usage                             |
 
-This package considers improvements to the (non-runtime) `*.rbi` and `*.rbs` type definitions to be non-breaking changes.
+## Documentation
 
-## Requirements
+Full API documentation is available at [vatsense.com/documentation](https://vatsense.com/documentation).
 
-Ruby 3.2.0 or higher.
+## Versioning
+
+This package follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions. As the library is in initial development and has a major version of `0`, APIs may change at any time.
 
 ## Contributing
 

data/lib/vatsense/internal/util.rb

@@ -157,7 +157,7 @@ module Vatsense
           in Hash | nil => coerced
             coerced
           else
-            message = "Expected a #{Hash} or #{Vatsense::Internal::Type::BaseModel}, got #{data.inspect}"
+            message = "Expected a #{Hash} or #{Vatsense::Internal::Type::BaseModel}, got #{input.inspect}"
             raise ArgumentError.new(message)
           end
         end
@@ -237,6 +237,11 @@ module Vatsense
         end
       end
 
+      # @type [Regexp]
+      #
+      # https://www.rfc-editor.org/rfc/rfc3986.html#section-3.3
+      RFC_3986_NOT_PCHARS = /[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/
+
       class << self
         # @api private
         #
@@ -247,6 +252,15 @@ module Vatsense
           "#{uri.scheme}://#{uri.host}#{":#{uri.port}" unless uri.port == uri.default_port}"
         end
 
+        # @api private
+        #
+        # @param path [String, Integer]
+        #
+        # @return [String]
+        def encode_path(path)
+          path.to_s.gsub(Vatsense::Internal::Util::RFC_3986_NOT_PCHARS) { ERB::Util.url_encode(_1) }
+        end
+
         # @api private
         #
         # @param path [String, Array<String>]
@@ -259,7 +273,7 @@ module Vatsense
           in []
             ""
           in [String => p, *interpolations]
-            encoded = interpolations.map { ERB::Util.url_encode(_1) }
+            encoded = interpolations.map { encode_path(_1) }
             format(p, *encoded)
           end
         end
@@ -571,16 +585,15 @@ module Vatsense
           y << "Content-Disposition: form-data"
 
           unless key.nil?
-            name = ERB::Util.url_encode(key.to_s)
-            y << "; name=\"#{name}\""
+            y << "; name=\"#{key}\""
           end
 
           case val
           in Vatsense::FilePart unless val.filename.nil?
-            filename = ERB::Util.url_encode(val.filename)
+            filename = encode_path(val.filename)
             y << "; filename=\"#{filename}\""
           in Pathname | IO
-            filename = ERB::Util.url_encode(::File.basename(val.to_path))
+            filename = encode_path(::File.basename(val.to_path))
             y << "; filename=\"#{filename}\""
           else
           end

data/lib/vatsense/version.rb

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

data/rbi/vatsense/internal/util.rbi

@@ -148,12 +148,20 @@ module Vatsense
         end
       end
 
+      # https://www.rfc-editor.org/rfc/rfc3986.html#section-3.3
+      RFC_3986_NOT_PCHARS = T.let(/[^A-Za-z0-9\-._~!$&'()*+,;=:@]+/, Regexp)
+
       class << self
         # @api private
         sig { params(uri: URI::Generic).returns(String) }
         def uri_origin(uri)
         end
 
+        # @api private
+        sig { params(path: T.any(String, Integer)).returns(String) }
+        def encode_path(path)
+        end
+
         # @api private
         sig { params(path: T.any(String, T::Array[String])).returns(String) }
         def interpolate_path(path)

data/sig/vatsense/internal/util.rbs

@@ -45,8 +45,12 @@ module Vatsense
         -> top?
       } -> top?
 
+      RFC_3986_NOT_PCHARS: Regexp
+
       def self?.uri_origin: (URI::Generic uri) -> String
 
+      def self?.encode_path: (String | Integer path) -> String
+
       def self?.interpolate_path: (String | ::Array[String] path) -> String
 
       def self?.decode_query: (String? query) -> ::Hash[String, ::Array[String]]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vatsense
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Vat Sense
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-18 00:00:00.000000000 Z
+date: 2026-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi