vatsense 0.1.0

data/rbi/vatsense/resources/invoice/item.rbi

@@ -0,0 +1,97 @@
+# typed: strong
+
+module Vatsense
+  module Resources
+    class Invoice
+      # VAT-compliant invoice management
+      class Item
+        # Retrieve a specific line item from an invoice.
+        sig do
+          params(
+            item_id: String,
+            invoice_id: String,
+            request_options: Vatsense::RequestOptions::OrHash
+          ).returns(Vatsense::Models::Invoice::ItemRetrieveResponse)
+        end
+        def retrieve(
+          # The unique identifier of the invoice item.
+          item_id,
+          # The unique identifier of the invoice.
+          invoice_id:,
+          request_options: {}
+        )
+        end
+
+        # Update a specific line item on an invoice.
+        sig do
+          params(
+            item_id: String,
+            invoice_id: String,
+            item: String,
+            price_each: Float,
+            quantity: Float,
+            vat_rate: Float,
+            discount_rate: Float,
+            request_options: Vatsense::RequestOptions::OrHash
+          ).returns(Vatsense::InvoiceResponse)
+        end
+        def update(
+          # Path param: The unique identifier of the invoice item.
+          item_id,
+          # Path param: The unique identifier of the invoice.
+          invoice_id:,
+          # Body param: The description of the line item.
+          item:,
+          # Body param: The price per item. Must be a decimal with 2 decimal places.
+          price_each:,
+          # Body param: The quantity of the item.
+          quantity:,
+          # Body param: A percentage VAT rate for this item.
+          vat_rate:,
+          # Body param: A percentage discount to apply to the price.
+          discount_rate: nil,
+          request_options: {}
+        )
+        end
+
+        # Remove a specific line item from an invoice.
+        sig do
+          params(
+            item_id: String,
+            invoice_id: String,
+            request_options: Vatsense::RequestOptions::OrHash
+          ).returns(Vatsense::InvoiceResponse)
+        end
+        def delete(
+          # The unique identifier of the invoice item.
+          item_id,
+          # The unique identifier of the invoice.
+          invoice_id:,
+          request_options: {}
+        )
+        end
+
+        # Add one or more line items to an existing invoice.
+        sig do
+          params(
+            invoice_id: String,
+            items: T::Array[Vatsense::Invoice::InvoiceItemInput::OrHash],
+            request_options: Vatsense::RequestOptions::OrHash
+          ).returns(Vatsense::InvoiceResponse)
+        end
+        def add(
+          # The unique identifier of the invoice.
+          invoice_id,
+          items:,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Vatsense::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/vatsense/resources/invoice.rbi

@@ -0,0 +1,191 @@
+# typed: strong
+
+module Vatsense
+  module Resources
+    # VAT-compliant invoice management
+    class Invoice
+      # VAT-compliant invoice management
+      sig { returns(Vatsense::Resources::Invoice::Item) }
+      attr_reader :item
+
+      # Create a new VAT-compliant invoice. VAT Sense will automatically calculate the
+      # totals based on the items provided.
+      #
+      # Not available with sandbox API keys.
+      sig do
+        params(
+          business: Vatsense::InvoiceBusinessInput::OrHash,
+          currency_code: String,
+          date: String,
+          items: T::Array[Vatsense::Invoice::InvoiceItemInput::OrHash],
+          tax_point: String,
+          conversion: Vatsense::InvoiceConversionInput::OrHash,
+          customer: Vatsense::InvoiceCustomerInput::OrHash,
+          has_vat: T::Boolean,
+          invoice_number: String,
+          is_copy: T::Boolean,
+          is_reverse_charge: T::Boolean,
+          notes: String,
+          pad_invoice_number: Integer,
+          serial: String,
+          tax_type: Vatsense::CreateInvoice::TaxType::OrSymbol,
+          type: Vatsense::CreateInvoice::Type::OrSymbol,
+          zero_rated: T::Boolean,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::InvoiceResponse)
+      end
+      def create(
+        business:,
+        # The 3-character currency code the invoice is billed in.
+        currency_code:,
+        # The date the invoice was issued (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS).
+        date:,
+        items:,
+        # The tax point or "time of supply" (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS).
+        tax_point:,
+        conversion: nil,
+        customer: nil,
+        # Whether the invoice is subject to VAT.
+        has_vat: nil,
+        # A unique invoice number. If not provided, defaults to an auto-incremented
+        # number.
+        invoice_number: nil,
+        # Whether the invoice is a copy of a primary invoice.
+        is_copy: nil,
+        # Whether the invoice is zero-rated due to reverse charge.
+        is_reverse_charge: nil,
+        # Any additional notes for the invoice.
+        notes: nil,
+        # Pad the auto-generated invoice number with leading zeros to this length.
+        pad_invoice_number: nil,
+        # A serial prepended to the auto-generated invoice number. Each unique serial has
+        # its own auto-increment range.
+        serial: nil,
+        # Whether item prices include or exclude VAT.
+        tax_type: nil,
+        # The type of invoice.
+        type: nil,
+        # Whether the invoice has been zero-rated.
+        zero_rated: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a specific invoice by its ID.
+      sig do
+        params(
+          invoice_id: String,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::InvoiceResponse)
+      end
+      def retrieve(
+        # The unique identifier of the invoice.
+        invoice_id,
+        request_options: {}
+      )
+      end
+
+      # Update an existing invoice. Only the fields provided will be updated.
+      sig do
+        params(
+          invoice_id: String,
+          business: Vatsense::InvoiceBusinessInput::OrHash,
+          currency_code: String,
+          date: String,
+          items: T::Array[Vatsense::Invoice::InvoiceItemInput::OrHash],
+          tax_point: String,
+          conversion: Vatsense::InvoiceConversionInput::OrHash,
+          customer: Vatsense::InvoiceCustomerInput::OrHash,
+          has_vat: T::Boolean,
+          invoice_number: String,
+          is_copy: T::Boolean,
+          is_reverse_charge: T::Boolean,
+          notes: String,
+          pad_invoice_number: Integer,
+          serial: String,
+          tax_type: Vatsense::CreateInvoice::TaxType::OrSymbol,
+          type: Vatsense::CreateInvoice::Type::OrSymbol,
+          zero_rated: T::Boolean,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::InvoiceResponse)
+      end
+      def update(
+        # The unique identifier of the invoice.
+        invoice_id,
+        business:,
+        # The 3-character currency code the invoice is billed in.
+        currency_code:,
+        # The date the invoice was issued (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS).
+        date:,
+        items:,
+        # The tax point or "time of supply" (YYYY-MM-DD or YYYY-MM-DD HH:MM:SS).
+        tax_point:,
+        conversion: nil,
+        customer: nil,
+        # Whether the invoice is subject to VAT.
+        has_vat: nil,
+        # A unique invoice number. If not provided, defaults to an auto-incremented
+        # number.
+        invoice_number: nil,
+        # Whether the invoice is a copy of a primary invoice.
+        is_copy: nil,
+        # Whether the invoice is zero-rated due to reverse charge.
+        is_reverse_charge: nil,
+        # Any additional notes for the invoice.
+        notes: nil,
+        # Pad the auto-generated invoice number with leading zeros to this length.
+        pad_invoice_number: nil,
+        # A serial prepended to the auto-generated invoice number. Each unique serial has
+        # its own auto-increment range.
+        serial: nil,
+        # Whether item prices include or exclude VAT.
+        tax_type: nil,
+        # The type of invoice.
+        type: nil,
+        # Whether the invoice has been zero-rated.
+        zero_rated: nil,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a paginated list of all invoices.
+      sig do
+        params(
+          limit: Integer,
+          offset: Integer,
+          search: String,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::Models::InvoiceListResponse)
+      end
+      def list(
+        # Number of invoices to return (default 10, max 100).
+        limit: nil,
+        # Number of invoices to skip (default 0).
+        offset: nil,
+        # Search query to filter invoices.
+        search: nil,
+        request_options: {}
+      )
+      end
+
+      # Permanently delete an invoice.
+      sig do
+        params(
+          invoice_id: String,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::Models::InvoiceDeleteResponse)
+      end
+      def delete(
+        # The unique identifier of the invoice.
+        invoice_id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Vatsense::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vatsense/resources/rates.rbi

@@ -0,0 +1,164 @@
+# typed: strong
+
+module Vatsense
+  module Resources
+    # VAT/GST rate lookups for countries worldwide
+    class Rates
+      # Returns a list of VAT/GST rates for all countries, sorted alphabetically by
+      # country code. Each rate is returned as a rate object containing the standard
+      # rate and any other applicable rates.
+      #
+      # You can optionally filter by country code, IP address, or EU membership.
+      sig do
+        params(
+          country_code: String,
+          eu: T::Boolean,
+          ip_address: String,
+          period: Time,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::Models::RateListResponse)
+      end
+      def list(
+        # A 2-character ISO 3166-1 alpha-2 country code (e.g. "GB", "FR").
+        country_code: nil,
+        # Filter results by EU membership. Use 1 for EU countries only, 0 for non-EU only.
+        eu: nil,
+        # An IPv4 or IPv6 address. If provided, the country will be determined from the IP
+        # address.
+        ip_address: nil,
+        # A historical date to retrieve rates for (format "YYYY-MM-DD HH:MM:SS"). Must be
+        # a past date.
+        period: nil,
+        request_options: {}
+      )
+      end
+
+      # Combines the functionality of the "Find a tax rate" and "VAT price calculation"
+      # endpoints to return the particular VAT price for an applicable VAT rate.
+      # Requires both a location (country_code or ip_address) and a price to calculate.
+      sig do
+        params(
+          price: String,
+          tax_type: Vatsense::RateCalculatePriceParams::TaxType::OrSymbol,
+          country_code: String,
+          eu: T::Boolean,
+          ip_address: String,
+          province_code: String,
+          type: String,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::Models::RateCalculatePriceResponse)
+      end
+      def calculate_price(
+        # The price to calculate on. Must be a string with exactly 2 decimal places (e.g.
+        # "30.00", "59.95").
+        price:,
+        # Whether the provided price is inclusive or exclusive of VAT.
+        tax_type:,
+        # A 2-character ISO 3166-1 alpha-2 country code (e.g. "GB", "FR").
+        country_code: nil,
+        # Filter results by EU membership. Use 1 for EU countries only, 0 for non-EU only.
+        eu: nil,
+        # An IPv4 or IPv6 address. If provided, the country will be determined from the IP
+        # address.
+        ip_address: nil,
+        # A 2-character province code (e.g. "NU", "NT"). If providing a province code, you
+        # must also provide the relevant country_code.
+        province_code: nil,
+        # The product type to find the applicable rate for. See the /rates/types endpoint
+        # for a full list of valid values.
+        type: nil,
+        request_options: {}
+      )
+      end
+
+      # Get detailed tax rate information for a location, including all applicable rate
+      # classes (standard, reduced, zero, etc.).
+      sig do
+        params(
+          country_code: String,
+          eu: T::Boolean,
+          ip_address: String,
+          period: Time,
+          province_code: String,
+          type: String,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::FindRate)
+      end
+      def details(
+        # A 2-character ISO 3166-1 alpha-2 country code (e.g. "GB", "FR").
+        country_code: nil,
+        # Filter results by EU membership. Use 1 for EU countries only, 0 for non-EU only.
+        eu: nil,
+        # An IPv4 or IPv6 address. If provided, the country will be determined from the IP
+        # address.
+        ip_address: nil,
+        # A historical date to retrieve rates for (format "YYYY-MM-DD HH:MM:SS"). Must be
+        # a past date.
+        period: nil,
+        # A 2-character province code (e.g. "NU", "NT"). If providing a province code, you
+        # must also provide the relevant country_code.
+        province_code: nil,
+        # The product type to find the applicable rate for. See the /rates/types endpoint
+        # for a full list of valid values.
+        type: nil,
+        request_options: {}
+      )
+      end
+
+      # A handy endpoint for finding a rate that applies to a particular country and
+      # optional product type, based on country code or IP address.
+      #
+      # If no type is provided, or no specific rate is applied to the given type, then
+      # the standard rate will be returned if the country is subject to tax.
+      #
+      # If the country is not subject to VAT/GST then an error response will be
+      # returned, indicating no tax applies.
+      sig do
+        params(
+          country_code: String,
+          eu: T::Boolean,
+          ip_address: String,
+          period: Time,
+          province_code: String,
+          type: String,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::FindRate)
+      end
+      def find(
+        # A 2-character ISO 3166-1 alpha-2 country code (e.g. "GB", "FR").
+        country_code: nil,
+        # Filter results by EU membership. Use 1 for EU countries only, 0 for non-EU only.
+        eu: nil,
+        # An IPv4 or IPv6 address. If provided, the country will be determined from the IP
+        # address.
+        ip_address: nil,
+        # A historical date to retrieve rates for (format "YYYY-MM-DD HH:MM:SS"). Must be
+        # a past date.
+        period: nil,
+        # A 2-character province code (e.g. "NU", "NT"). If providing a province code, you
+        # must also provide the relevant country_code.
+        province_code: nil,
+        # The product type to find the applicable rate for. See the /rates/types endpoint
+        # for a full list of valid values.
+        type: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns a list of all available product types that can be used to filter tax
+      # rates.
+      sig do
+        params(request_options: Vatsense::RequestOptions::OrHash).returns(
+          Vatsense::Models::RateListTypesResponse
+        )
+      end
+      def list_types(request_options: {})
+      end
+
+      # @api private
+      sig { params(client: Vatsense::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vatsense/resources/sandbox.rbi

@@ -0,0 +1,24 @@
+# typed: strong
+
+module Vatsense
+  module Resources
+    # Temporary sandbox API keys for testing
+    class Sandbox
+      # Generate a temporary sandbox API key for testing. Sandbox keys have limited
+      # request allowances and restricted endpoint access (no invoice endpoints). Rate
+      # limited to 1 key per IP address per 6 hours.
+      sig do
+        params(request_options: Vatsense::RequestOptions::OrHash).returns(
+          Vatsense::Models::SandboxGenerateKeyResponse
+        )
+      end
+      def generate_key(request_options: {})
+      end
+
+      # @api private
+      sig { params(client: Vatsense::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vatsense/resources/usage.rbi

@@ -0,0 +1,22 @@
+# typed: strong
+
+module Vatsense
+  module Resources
+    # API usage statistics
+    class Usage
+      # Check your used and remaining API requests.
+      sig do
+        params(request_options: Vatsense::RequestOptions::OrHash).returns(
+          Vatsense::Models::UsageRetrieveResponse
+        )
+      end
+      def retrieve(request_options: {})
+      end
+
+      # @api private
+      sig { params(client: Vatsense::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vatsense/resources/validate.rbi

@@ -0,0 +1,51 @@
+# typed: strong
+
+module Vatsense
+  module Resources
+    # VAT and EORI number validation
+    class Validate
+      # Check whether a given VAT number or EORI number is valid against live government
+      # records.
+      #
+      # **VAT validation** checks against UK (HMRC), EU (VIES), Australia, Norway,
+      # Switzerland, South Africa, and Brazil records.
+      #
+      # **EORI validation** checks against UK and EU records only.
+      #
+      # If the external validation service is temporarily unavailable, the API returns a
+      # `412` error and the request does not count against your usage quota.
+      #
+      # Provide either `vat_number` or `eori_number`, but not both.
+      sig do
+        params(
+          eori_number: String,
+          requester_vat_number: String,
+          vat_number: String,
+          request_options: Vatsense::RequestOptions::OrHash
+        ).returns(Vatsense::Models::ValidateCheckResponse)
+      end
+      def check(
+        # The EORI number to validate. Must include the leading 2-character country code
+        # (e.g. "GB123456789123"). UK and EU only.
+        eori_number: nil,
+        # Your own VAT number. If supplied, the response will include a unique
+        # consultation number issued by the relevant authority (VIES or HMRC). Must
+        # include the leading 2-character country code.
+        #
+        # Note: GB requester numbers only work for GB validations; EU requester numbers
+        # only work for EU validations. Cross-region is not supported.
+        requester_vat_number: nil,
+        # The VAT number to validate. Must include the leading 2-character country code
+        # (e.g. "GB288305674", "FR12345678901").
+        vat_number: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Vatsense::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/vatsense/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module Vatsense
+  VERSION = T.let(T.unsafe(nil), String)
+end

data/sig/vatsense/client.rbs

@@ -0,0 +1,45 @@
+module Vatsense
+  class Client < Vatsense::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    attr_reader username: String
+
+    attr_reader password: String
+
+    attr_reader rates: Vatsense::Resources::Rates
+
+    attr_reader countries: Vatsense::Resources::Countries
+
+    attr_reader validate: Vatsense::Resources::Validate
+
+    attr_reader currency: Vatsense::Resources::Currency
+
+    attr_reader invoice: Vatsense::Resources::Invoice
+
+    attr_reader usage: Vatsense::Resources::Usage
+
+    attr_reader sandbox: Vatsense::Resources::Sandbox
+
+    private def auth_headers: (
+      security: { basic_auth: bool }
+    ) -> ::Hash[String, String]
+
+    private def basic_auth: -> ::Hash[String, String]
+
+    def initialize: (
+      ?username: String?,
+      ?password: String?,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end