vatsense 0.1.0

data/lib/vatsense/models/vat_price.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Vatsense
+  module Models
+    class VatPrice < Vatsense::Internal::Type::BaseModel
+      # @!attribute object
+      #
+      #   @return [Symbol, Vatsense::Models::VatPrice::Object, nil]
+      optional :object, enum: -> { Vatsense::VatPrice::Object }
+
+      # @!attribute price
+      #   The price provided.
+      #
+      #   @return [Float, nil]
+      optional :price, Float
+
+      # @!attribute price_excl_vat
+      #   The calculated price exclusive of VAT.
+      #
+      #   @return [Float, nil]
+      optional :price_excl_vat, Float
+
+      # @!attribute price_incl_vat
+      #   The calculated price inclusive of VAT.
+      #
+      #   @return [Float, nil]
+      optional :price_incl_vat, Float
+
+      # @!attribute tax_type
+      #   Whether the price is inclusive or exclusive of VAT.
+      #
+      #   @return [Symbol, Vatsense::Models::VatPrice::TaxType, nil]
+      optional :tax_type, enum: -> { Vatsense::VatPrice::TaxType }
+
+      # @!attribute vat
+      #   The total VAT amount.
+      #
+      #   @return [Float, nil]
+      optional :vat, Float
+
+      # @!attribute vat_rate
+      #   The VAT rate percentage.
+      #
+      #   @return [Float, nil]
+      optional :vat_rate, Float
+
+      # @!method initialize(object: nil, price: nil, price_excl_vat: nil, price_incl_vat: nil, tax_type: nil, vat: nil, vat_rate: nil)
+      #   @param object [Symbol, Vatsense::Models::VatPrice::Object]
+      #
+      #   @param price [Float] The price provided.
+      #
+      #   @param price_excl_vat [Float] The calculated price exclusive of VAT.
+      #
+      #   @param price_incl_vat [Float] The calculated price inclusive of VAT.
+      #
+      #   @param tax_type [Symbol, Vatsense::Models::VatPrice::TaxType] Whether the price is inclusive or exclusive of VAT.
+      #
+      #   @param vat [Float] The total VAT amount.
+      #
+      #   @param vat_rate [Float] The VAT rate percentage.
+
+      # @see Vatsense::Models::VatPrice#object
+      module Object
+        extend Vatsense::Internal::Type::Enum
+
+        VAT_PRICE = :vat_price
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+
+      # Whether the price is inclusive or exclusive of VAT.
+      #
+      # @see Vatsense::Models::VatPrice#tax_type
+      module TaxType
+        extend Vatsense::Internal::Type::Enum
+
+        INCL = :incl
+        EXCL = :excl
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/vatsense/models.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Vatsense
+  [Vatsense::Internal::Type::BaseModel, *Vatsense::Internal::Type::BaseModel.subclasses].each do |cls|
+    cls.define_sorbet_constant!(:OrHash) { T.type_alias { T.any(cls, Vatsense::Internal::AnyHash) } }
+  end
+
+  Vatsense::Internal::Util.walk_namespaces(Vatsense::Models).each do |mod|
+    case mod
+    in Vatsense::Internal::Type::Enum | Vatsense::Internal::Type::Union
+      mod.constants.each do |name|
+        case mod.const_get(name)
+        in true | false
+          mod.define_sorbet_constant!(:TaggedBoolean) { T.type_alias { T::Boolean } }
+          mod.define_sorbet_constant!(:OrBoolean) { T.type_alias { T::Boolean } }
+        in Integer
+          mod.define_sorbet_constant!(:TaggedInteger) { T.type_alias { Integer } }
+          mod.define_sorbet_constant!(:OrInteger) { T.type_alias { Integer } }
+        in Float
+          mod.define_sorbet_constant!(:TaggedFloat) { T.type_alias { Float } }
+          mod.define_sorbet_constant!(:OrFloat) { T.type_alias { Float } }
+        in Symbol
+          mod.define_sorbet_constant!(:TaggedSymbol) { T.type_alias { Symbol } }
+          mod.define_sorbet_constant!(:OrSymbol) { T.type_alias { T.any(Symbol, String) } }
+        else
+        end
+      end
+    else
+    end
+  end
+
+  Vatsense::Internal::Util.walk_namespaces(Vatsense::Models)
+                          .lazy
+                          .grep(Vatsense::Internal::Type::Union)
+                          .each do |mod|
+    const = :Variants
+    next if mod.sorbet_constant_defined?(const)
+
+    mod.define_sorbet_constant!(const) { T.type_alias { mod.to_sorbet_type } }
+  end
+
+  Country = Vatsense::Models::Country
+
+  CountryListParams = Vatsense::Models::CountryListParams
+
+  CountryListProvincesParams = Vatsense::Models::CountryListProvincesParams
+
+  CreateInvoice = Vatsense::Models::CreateInvoice
+
+  CurrencyCalculateVatPriceParams = Vatsense::Models::CurrencyCalculateVatPriceParams
+
+  CurrencyConvertParams = Vatsense::Models::CurrencyConvertParams
+
+  CurrencyListParams = Vatsense::Models::CurrencyListParams
+
+  FindRate = Vatsense::Models::FindRate
+
+  Invoice = Vatsense::Models::Invoice
+
+  InvoiceAPI = Vatsense::Models::InvoiceAPI
+
+  InvoiceBusinessInput = Vatsense::Models::InvoiceBusinessInput
+
+  InvoiceConversionInput = Vatsense::Models::InvoiceConversionInput
+
+  InvoiceCreateParams = Vatsense::Models::InvoiceCreateParams
+
+  InvoiceCustomerInput = Vatsense::Models::InvoiceCustomerInput
+
+  InvoiceDeleteParams = Vatsense::Models::InvoiceDeleteParams
+
+  InvoiceListParams = Vatsense::Models::InvoiceListParams
+
+  InvoiceResponse = Vatsense::Models::InvoiceResponse
+
+  InvoiceRetrieveParams = Vatsense::Models::InvoiceRetrieveParams
+
+  InvoiceUpdateParams = Vatsense::Models::InvoiceUpdateParams
+
+  Rate = Vatsense::Models::Rate
+
+  RateCalculatePriceParams = Vatsense::Models::RateCalculatePriceParams
+
+  RateDetailsParams = Vatsense::Models::RateDetailsParams
+
+  RateFindParams = Vatsense::Models::RateFindParams
+
+  RateListParams = Vatsense::Models::RateListParams
+
+  RateListTypesParams = Vatsense::Models::RateListTypesParams
+
+  RateWithTaxRate = Vatsense::Models::RateWithTaxRate
+
+  SandboxGenerateKeyParams = Vatsense::Models::SandboxGenerateKeyParams
+
+  TaxRate = Vatsense::Models::TaxRate
+
+  UsageRetrieveParams = Vatsense::Models::UsageRetrieveParams
+
+  ValidateCheckParams = Vatsense::Models::ValidateCheckParams
+
+  VatPrice = Vatsense::Models::VatPrice
+end

data/lib/vatsense/request_options.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Vatsense
+  # Specify HTTP behaviour to use for a specific request. These options supplement
+  # or override those provided at the client level.
+  #
+  # When making a request, you can pass an actual {RequestOptions} instance, or
+  # simply pass a Hash with symbol keys matching the attributes on this class.
+  class RequestOptions < Vatsense::Internal::Type::BaseModel
+    # @api private
+    #
+    # @param opts [Vatsense::RequestOptions, Hash{Symbol=>Object}]
+    #
+    # @raise [ArgumentError]
+    def self.validate!(opts)
+      case opts
+      in Vatsense::RequestOptions | Hash
+        opts.to_h.each_key do |k|
+          unless fields.include?(k)
+            raise ArgumentError.new("Request `opts` keys must be one of #{fields.keys}, got #{k.inspect}")
+          end
+        end
+      else
+        raise ArgumentError.new("Request `opts` must be a Hash or RequestOptions, got #{opts.inspect}")
+      end
+    end
+
+    # @!attribute idempotency_key
+    #   Idempotency key to send with request and all associated retries. Will only be
+    #   sent for write requests.
+    #
+    #   @return [String, nil]
+    optional :idempotency_key, String
+
+    # @!attribute extra_query
+    #   Extra query params to send with the request. These are `.merge`’d into any
+    #   `query` given at the client level.
+    #
+    #   @return [Hash{String=>Array<String>, String, nil}, nil]
+    optional :extra_query, Vatsense::Internal::Type::HashOf[Vatsense::Internal::Type::ArrayOf[String]]
+
+    # @!attribute extra_headers
+    #   Extra headers to send with the request. These are `.merged`’d into any
+    #   `extra_headers` given at the client level.
+    #
+    #   @return [Hash{String=>String, nil}, nil]
+    optional :extra_headers, Vatsense::Internal::Type::HashOf[String, nil?: true]
+
+    # @!attribute extra_body
+    #   Extra data to send with the request. These are deep merged into any data
+    #   generated as part of the normal request.
+    #
+    #   @return [Object, nil]
+    optional :extra_body, Vatsense::Internal::Type::HashOf[Vatsense::Internal::Type::Unknown]
+
+    # @!attribute max_retries
+    #   Maximum number of retries to attempt after a failed initial request.
+    #
+    #   @return [Integer, nil]
+    optional :max_retries, Integer
+
+    # @!attribute timeout
+    #   Request timeout in seconds.
+    #
+    #   @return [Float, nil]
+    optional :timeout, Float
+
+    # @!method initialize(values = {})
+    #   Returns a new instance of RequestOptions.
+    #
+    #   @param values [Hash{Symbol=>Object}]
+
+    define_sorbet_constant!(:OrHash) do
+      T.type_alias { T.any(Vatsense::RequestOptions, Vatsense::Internal::AnyHash) }
+    end
+  end
+end

data/lib/vatsense/resources/countries.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Vatsense
+  module Resources
+    # Country and province information
+    class Countries
+      # Some parameter documentations has been truncated, see
+      # {Vatsense::Models::CountryListParams} for more details.
+      #
+      # Returns a list of all countries, including whether they are subject to VAT/GST
+      # and whether they are subject to EU VAT. Each country is returned as a country
+      # object.
+      #
+      # You can optionally filter by country code or IP address.
+      #
+      # @overload list(country_code: nil, ip_address: nil, request_options: {})
+      #
+      # @param country_code [String] A 2-character ISO 3166-1 alpha-2 country code (e.g. "GB", "FR").
+      #
+      # @param ip_address [String] An IPv4 or IPv6 address. If provided, the country will be determined from the IP
+      #
+      # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Vatsense::Models::CountryListResponse]
+      #
+      # @see Vatsense::Models::CountryListParams
+      def list(params = {})
+        parsed, options = Vatsense::CountryListParams.dump_request(params)
+        query = Vatsense::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "countries",
+          query: query,
+          model: Vatsense::Models::CountryListResponse,
+          options: options
+        )
+      end
+
+      # Retrieve a list of all provinces within a given country.
+      #
+      # @overload list_provinces(country_code:, request_options: {})
+      #
+      # @param country_code [String] A 2-character ISO 3166-1 alpha-2 country code (e.g. "CA").
+      #
+      # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Vatsense::Models::CountryListProvincesResponse]
+      #
+      # @see Vatsense::Models::CountryListProvincesParams
+      def list_provinces(params)
+        parsed, options = Vatsense::CountryListProvincesParams.dump_request(params)
+        query = Vatsense::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "countries/provinces",
+          query: query,
+          model: Vatsense::Models::CountryListProvincesResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Vatsense::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/vatsense/resources/currency.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Vatsense
+  module Resources
+    # Currency exchange rates and conversion
+    class Currency
+      # Some parameter documentations has been truncated, see
+      # {Vatsense::Models::CurrencyListParams} for more details.
+      #
+      # Returns a list of all currency conversion rates sourced from HMRC (GBP) and the
+      # European Central Bank (EUR).
+      #
+      # You can optionally filter by source and target currency.
+      #
+      # @overload list(from: nil, to: nil, request_options: {})
+      #
+      # @param from [String] The 3-character currency code(s) to convert from (e.g. "USD", "CAD").
+      #
+      # @param to [Symbol, Vatsense::Models::CurrencyListParams::To] The 3-character target currency code. Must be either "GBP" or "EUR".
+      #
+      # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Vatsense::Models::CurrencyListResponse]
+      #
+      # @see Vatsense::Models::CurrencyListParams
+      def list(params = {})
+        parsed, options = Vatsense::CurrencyListParams.dump_request(params)
+        query = Vatsense::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "currency",
+          query: query,
+          model: Vatsense::Models::CurrencyListResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Vatsense::Models::CurrencyCalculateVatPriceParams} for more details.
+      #
+      # Calculate the inclusive and exclusive VAT price on a given amount and VAT rate.
+      # This is a standalone calculation that does not look up rates by country.
+      #
+      # @overload calculate_vat_price(price:, tax_type:, vat_rate:, request_options: {})
+      #
+      # @param price [String] The price to calculate on. Must be a string with exactly 2 decimal places (e.g.
+      #
+      # @param tax_type [Symbol, Vatsense::Models::CurrencyCalculateVatPriceParams::TaxType] Whether the provided price is inclusive or exclusive of VAT.
+      #
+      # @param vat_rate [Float] A percentage VAT rate to use for the calculation.
+      #
+      # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Vatsense::Models::CurrencyCalculateVatPriceResponse]
+      #
+      # @see Vatsense::Models::CurrencyCalculateVatPriceParams
+      def calculate_vat_price(params)
+        parsed, options = Vatsense::CurrencyCalculateVatPriceParams.dump_request(params)
+        query = Vatsense::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "currency/price",
+          query: query,
+          model: Vatsense::Models::CurrencyCalculateVatPriceResponse,
+          options: options
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {Vatsense::Models::CurrencyConvertParams} for more details.
+      #
+      # Convert a foreign currency amount to either GBP or EUR using official exchange
+      # rates.
+      #
+      # GBP rates are from HMRC (updated on the 1st of every month). EUR rates are from
+      # the European Central Bank (updated around 16:00 CET on working days).
+      #
+      # @overload convert(amount:, from:, to:, request_options: {})
+      #
+      # @param amount [String] The amount to convert. Must be a string with exactly 2 decimal places (e.g. "39.
+      #
+      # @param from [String] The 3-character source currency code (e.g. "USD", "CAD").
+      #
+      # @param to [Symbol, Vatsense::Models::CurrencyConvertParams::To] The 3-character target currency code. Must be either "GBP" or "EUR".
+      #
+      # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Vatsense::Models::CurrencyConvertResponse]
+      #
+      # @see Vatsense::Models::CurrencyConvertParams
+      def convert(params)
+        parsed, options = Vatsense::CurrencyConvertParams.dump_request(params)
+        query = Vatsense::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: "currency/convert",
+          query: query,
+          model: Vatsense::Models::CurrencyConvertResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [Vatsense::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/vatsense/resources/invoice/item.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Vatsense
+  module Resources
+    class Invoice
+      # VAT-compliant invoice management
+      class Item
+        # Retrieve a specific line item from an invoice.
+        #
+        # @overload retrieve(item_id, invoice_id:, request_options: {})
+        #
+        # @param item_id [String] The unique identifier of the invoice item.
+        #
+        # @param invoice_id [String] The unique identifier of the invoice.
+        #
+        # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Vatsense::Models::Invoice::ItemRetrieveResponse]
+        #
+        # @see Vatsense::Models::Invoice::ItemRetrieveParams
+        def retrieve(item_id, params)
+          parsed, options = Vatsense::Invoice::ItemRetrieveParams.dump_request(params)
+          invoice_id =
+            parsed.delete(:invoice_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["invoice/%1$s/item/%2$s", invoice_id, item_id],
+            model: Vatsense::Models::Invoice::ItemRetrieveResponse,
+            options: options
+          )
+        end
+
+        # Update a specific line item on an invoice.
+        #
+        # @overload update(item_id, invoice_id:, item:, price_each:, quantity:, vat_rate:, discount_rate: nil, request_options: {})
+        #
+        # @param item_id [String] Path param: The unique identifier of the invoice item.
+        #
+        # @param invoice_id [String] Path param: The unique identifier of the invoice.
+        #
+        # @param item [String] Body param: The description of the line item.
+        #
+        # @param price_each [Float] Body param: The price per item. Must be a decimal with 2 decimal places.
+        #
+        # @param quantity [Float] Body param: The quantity of the item.
+        #
+        # @param vat_rate [Float] Body param: A percentage VAT rate for this item.
+        #
+        # @param discount_rate [Float] Body param: A percentage discount to apply to the price.
+        #
+        # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Vatsense::Models::InvoiceResponse]
+        #
+        # @see Vatsense::Models::Invoice::ItemUpdateParams
+        def update(item_id, params)
+          parsed, options = Vatsense::Invoice::ItemUpdateParams.dump_request(params)
+          invoice_id =
+            parsed.delete(:invoice_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :patch,
+            path: ["invoice/%1$s/item/%2$s", invoice_id, item_id],
+            body: parsed,
+            model: Vatsense::InvoiceResponse,
+            options: options
+          )
+        end
+
+        # Remove a specific line item from an invoice.
+        #
+        # @overload delete(item_id, invoice_id:, request_options: {})
+        #
+        # @param item_id [String] The unique identifier of the invoice item.
+        #
+        # @param invoice_id [String] The unique identifier of the invoice.
+        #
+        # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Vatsense::Models::InvoiceResponse]
+        #
+        # @see Vatsense::Models::Invoice::ItemDeleteParams
+        def delete(item_id, params)
+          parsed, options = Vatsense::Invoice::ItemDeleteParams.dump_request(params)
+          invoice_id =
+            parsed.delete(:invoice_id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :delete,
+            path: ["invoice/%1$s/item/%2$s", invoice_id, item_id],
+            model: Vatsense::InvoiceResponse,
+            options: options
+          )
+        end
+
+        # Add one or more line items to an existing invoice.
+        #
+        # @overload add(invoice_id, items:, request_options: {})
+        #
+        # @param invoice_id [String] The unique identifier of the invoice.
+        #
+        # @param items [Array<Vatsense::Models::Invoice::InvoiceItemInput>]
+        #
+        # @param request_options [Vatsense::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Vatsense::Models::InvoiceResponse]
+        #
+        # @see Vatsense::Models::Invoice::ItemAddParams
+        def add(invoice_id, params)
+          parsed, options = Vatsense::Invoice::ItemAddParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: ["invoice/%1$s/item", invoice_id],
+            body: parsed,
+            model: Vatsense::InvoiceResponse,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Vatsense::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end