smartbill-sdk 1.0.0

data/lib/smartbill/sdk/models/storno_response.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Models
+      # Response for +POST /invoice/reverse+.
+      class StornoResponse < BaseResponse
+        attribute :document_url, Types::Strict::String.optional.default(nil)
+        attribute :document_id, Types::StrOrInt.optional.default(nil)
+        attribute :document_view_url, Types::Strict::String.optional.default(nil)
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/models/struct.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "dry-struct"
+
+module Smartbill
+  module Sdk
+    module Models
+      # Base class for every SmartBill request/response model.
+      #
+      # A thin adapter over `Dry::Struct` that gives the SDK:
+      #
+      # * snake_case Ruby attributes aliased to camelCase JSON keys — both
+      #   `company_vat_code` and `"companyVatCode"` are accepted on input,
+      #   and {#to_h} emits camelCase keys (matching the SmartBill API);
+      # * type coercion of scalars and nested structs / arrays of structs;
+      # * required-attribute presence (a missing required attribute raises
+      #   {ValidationError}, translated from `Dry::Struct::Error`);
+      # * permissive parsing — unknown input keys are ignored so new API
+      #   fields don't break parsing;
+      # * {#to_attributes} returning the snake_case hash (with nils) used by
+      #   the dry-validation contracts.
+      #
+      # Subclasses declare attributes with the dry-struct `attribute` DSL:
+      #
+      #   class MyThing < Struct
+      #     attribute :company_vat_code, Types::Strict::String
+      #     attribute :client, Client.optional.default(nil)
+      #     attribute :products, Types::Array.of(Product).default([].freeze)
+      #   end
+      class Struct < Dry::Struct
+        # Accept snake_case and camelCase input keys (String or Symbol),
+        # normalising to the snake_case Symbol keys dry-struct expects.
+        transform_keys { |key| INFLECTOR.underscore(key.to_s).to_sym }
+
+        class << self
+          # Construct a struct, translating dry-struct type errors (e.g. a
+          # missing required attribute) into the SDK's {ValidationError}.
+          def new(attrs = Dry::Core::Constants::EMPTY_HASH, &)
+            super
+          rescue Dry::Struct::Error => e
+            raise ValidationError, e.message
+          end
+        end
+
+        # Serialize to a camelCase-keyed Hash matching the SmartBill API,
+        # omitting nil values by default. Nested structs and arrays of
+        # structs are serialized recursively.
+        #
+        # @param exclude_none [Boolean] skip nil values (default true).
+        def to_h(exclude_none: true)
+          self.class.schema.keys.each_with_object({}) do |key, hash|
+            value = public_send(key.name)
+            next if exclude_none && value.nil?
+
+            hash[camelize_key(key.name)] = serialize_value(value, exclude_none)
+          end
+        end
+
+        def to_json(*)
+          to_h.to_json(*)
+        end
+
+        # Return a snake_case Symbol-keyed Hash (including nils) reflecting
+        # the Ruby attributes, with nested structs and arrays of structs
+        # recursively converted to hashes. Used as input to the validation
+        # contracts (which operate on hashes, not struct instances).
+        def to_attributes
+          self.class.schema.keys.to_h do |key|
+            [key.name, attribute_value(public_send(key.name))]
+          end
+        end
+
+        private
+
+        def attribute_value(value)
+          if value.is_a?(Struct)
+            value.to_attributes
+          elsif value.is_a?(Array)
+            value.map { |element| attribute_value(element) }
+          else
+            value
+          end
+        end
+
+        def camelize_key(name)
+          camelized = INFLECTOR.camelize(name.to_s)
+          "#{camelized[0].downcase}#{camelized[1..]}"
+        end
+
+        def serialize_value(value, exclude_none)
+          if value.is_a?(Struct)
+            value.to_h(exclude_none: exclude_none)
+          elsif value.is_a?(Array)
+            value.map { |element| serialize_value(element, exclude_none) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/models/tax.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Models
+      # A VAT rate entry from +GET /tax+.
+      class Tax < Struct
+        attribute :name, Types::Strict::String.optional.default(nil)
+        attribute :percentage, Types::Coercible::Float.optional.default(nil)
+        attribute :id, Types::StrOrInt.optional.default(nil)
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/models/taxes_response.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Models
+      # Parsed response of +GET /tax+.
+      class TaxesResponse < Struct
+        attribute :error_text, Types::Strict::String.optional.default(nil)
+        attribute :message, Types::Strict::String.optional.default(nil)
+        attribute :taxes, Types::Array.of(Tax).default([].freeze)
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/models.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "dry-inflector"
+
+module Smartbill
+  module Sdk
+    # Typed request/response models for the SmartBill Cloud REST API.
+    #
+    # Each model is a {Models::Struct} (a `Dry::Struct` subclass) and lives
+    # in its own file (e.g. `models/invoice.rb` defines `Invoice`),
+    # autoloaded by Zeitwerk.
+    module Models
+      # Shared inflector for snake_case ⇄ camelCase key mapping.
+      INFLECTOR = Dry::Inflector.new
+    end
+  end
+end

data/lib/smartbill/sdk/net_http_adapter.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Smartbill
+  module Sdk
+    # Default HTTP adapter backed by stdlib +Net::HTTP+.
+    #
+    # The SDK talks to the adapter through a single method, {#call}, which
+    # receives a {Transport::Request} and returns a {Response}. This keeps
+    # the transport logic decoupled from the HTTP library and makes it
+    # trivial to swap in another adapter (or stub one in tests).
+    class NetHttpAdapter
+      METHOD_CLASSES = {
+        "GET" => Net::HTTP::Get,
+        "POST" => Net::HTTP::Post,
+        "PUT" => Net::HTTP::Put,
+        "DELETE" => Net::HTTP::Delete,
+        "PATCH" => Net::HTTP::Patch
+      }.freeze
+
+      def initialize(timeout: 30)
+        @timeout = timeout
+      end
+
+      def call(req)
+        uri = build_uri(req)
+        request = build_request(req, uri)
+        response = perform(uri, request)
+        Response.new(status: response.code.to_i, body: response.body,
+                     content_type: response["content-type"])
+      rescue ArgumentError, Net::HTTPError => e
+        raise TransportError, "Transport error: #{e.message}"
+      end
+
+      private
+
+      def build_uri(req)
+        uri = URI(req.url)
+        uri.query = URI.encode_www_form(req.query) if req.query && !req.query.empty?
+        uri
+      end
+
+      def build_request(req, uri)
+        klass = METHOD_CLASSES[req.http_method] ||
+                raise(TransportError, "Unsupported HTTP method: #{req.http_method}")
+        request = klass.new(uri.request_uri)
+        req.headers.each { |key, value| request[key] = value }
+        request.body = req.body if req.body
+        request
+      end
+
+      def perform(uri, request)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                            read_timeout: @timeout, open_timeout: @timeout) do |http|
+          http.request(request)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/rate_limit_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    # Raised on HTTP 403 — SmartBill blocks access for 10 minutes after
+    # more than 30 calls / 10 seconds.
+    class RateLimitError < Error; end
+  end
+end

data/lib/smartbill/sdk/response.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    # A simple HTTP response value object returned by adapters.
+    #
+    # @!attribute [r] status  HTTP status code (Integer).
+    # @!attribute [r] body    Raw response body (String, possibly binary).
+    # @!attribute [r] content_type  Value of the +Content-Type+ header.
+    Response = Struct.new(:status, :body, :content_type, keyword_init: true)
+  end
+end

data/lib/smartbill/sdk/services/base_service.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Services
+      # Base class for all services.
+      class BaseService
+        def initialize(client)
+          @client = client
+        end
+
+        private
+
+        # Run +contract+.validate! on +struct+, raising {ValidationError}
+        # on failure. No-op contract-wise if +contract+ is nil.
+        def validate(struct, contract)
+          contract.validate!(struct)
+          struct
+        end
+
+        def build_request(...)
+          Transport.build_request(...)
+        end
+
+        def execute(request, binary: false)
+          @client.execute(request, binary: binary)
+        end
+
+        def dump(model, envelope_key: nil)
+          Services.dump_model(model, envelope_key: envelope_key)
+        end
+
+        def parse(payload, model_class)
+          Services.parse(payload, model_class)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/services/configuration_service.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Services
+      # +/tax+ and +/series+ endpoints.
+      #
+      # Note: on a {Client}, both +client.taxes+ and +client.series+ are the
+      # same +ConfigurationService+ instance.
+      class ConfigurationService < BaseService
+        def taxes(cif)
+          parse(execute(build_request(
+                          method: "GET", base_url: @client.base_url, path: "tax",
+                          params: { "cif" => cif }, auth_header: @client.auth_header
+                        )), Models::TaxesResponse)
+        end
+
+        def series(cif, type: nil)
+          params = { "cif" => cif }
+          params["type"] = type unless type.nil?
+          parse(execute(build_request(
+                          method: "GET", base_url: @client.base_url, path: "series",
+                          params: params, auth_header: @client.auth_header
+                        )), Models::SeriesListResponse)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/services/email_service.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Services
+      # +/document/send+ endpoint.
+      class EmailService < BaseService
+        def send(email)
+          validate(email, Contracts::EmailContract)
+          parse(execute(build_request(
+                          method: "POST", base_url: @client.base_url, path: "document/send",
+                          json_body: dump(email), auth_header: @client.auth_header
+                        )), Models::EmailResponse)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/services/estimates_service.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Services
+      # +/estimate+ endpoints.
+      class EstimatesService < BaseService
+        def create(estimate)
+          validate(estimate, Contracts::EstimateContract)
+          parse(execute(build_request(
+                          method: "POST", base_url: @client.base_url, path: "estimate",
+                          json_body: dump(estimate), auth_header: @client.auth_header
+                        )), Models::InvoiceCreateResponse)
+        end
+
+        def delete(cif, series_name, number)
+          parse(execute(build_request(
+                          method: "DELETE", base_url: @client.base_url, path: "estimate",
+                          params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                          auth_header: @client.auth_header
+                        )), Models::BaseResponse)
+        end
+
+        def cancel(cif, series_name, number)
+          cancel_restore("cancel", cif, series_name, number)
+        end
+
+        def restore(cif, series_name, number)
+          cancel_restore("restore", cif, series_name, number)
+        end
+
+        def pdf(cif, series_name, number)
+          execute(build_request(
+                    method: "GET", base_url: @client.base_url, path: "estimate/pdf",
+                    params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                    accept: "application/octet-stream", auth_header: @client.auth_header
+                  ), binary: true)
+        end
+
+        def invoices_status(cif, series_name, number)
+          parse(execute(build_request(
+                          method: "GET", base_url: @client.base_url, path: "estimate/invoices",
+                          params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                          auth_header: @client.auth_header
+                        )), Models::ProformaInvoicesResponse)
+        end
+
+        private
+
+        def cancel_restore(op, cif, series_name, number)
+          parse(execute(build_request(
+                          method: "PUT", base_url: @client.base_url, path: "estimate/#{op}",
+                          params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                          auth_header: @client.auth_header
+                        )), Models::BaseResponse)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/services/invoices_service.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Services
+      # +/invoice+ endpoints.
+      class InvoicesService < BaseService
+        def create(invoice)
+          validate(invoice, Contracts::InvoiceContract)
+          parse(execute(build_request(
+                          method: "POST", base_url: @client.base_url, path: "invoice",
+                          json_body: dump(invoice), auth_header: @client.auth_header
+                        )), Models::InvoiceCreateResponse)
+        end
+
+        def delete(cif, series_name, number)
+          parse(execute(build_request(
+                          method: "DELETE", base_url: @client.base_url, path: "invoice",
+                          params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                          auth_header: @client.auth_header
+                        )), Models::BaseResponse)
+        end
+
+        def reverse(storno)
+          validate(storno, Contracts::StornoContract)
+          parse(execute(build_request(
+                          method: "POST", base_url: @client.base_url, path: "invoice/reverse",
+                          json_body: dump(storno), auth_header: @client.auth_header
+                        )), Models::StornoResponse)
+        end
+
+        def cancel(cif, series_name, number)
+          cancel_restore("cancel", cif, series_name, number)
+        end
+
+        def restore(cif, series_name, number)
+          cancel_restore("restore", cif, series_name, number)
+        end
+
+        def payment_status(cif, series_name, number)
+          parse(execute(build_request(
+                          method: "GET", base_url: @client.base_url, path: "invoice/paymentstatus",
+                          params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                          auth_header: @client.auth_header
+                        )), Models::PaymentStatusResponse)
+        end
+
+        # Returns the raw PDF body as a binary String.
+        def pdf(cif, series_name, number)
+          execute(build_request(
+                    method: "GET", base_url: @client.base_url, path: "invoice/pdf",
+                    params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                    accept: "application/octet-stream", auth_header: @client.auth_header
+                  ), binary: true)
+        end
+
+        private
+
+        def cancel_restore(op, cif, series_name, number)
+          parse(execute(build_request(
+                          method: "PUT", base_url: @client.base_url, path: "invoice/#{op}",
+                          params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                          auth_header: @client.auth_header
+                        )), Models::BaseResponse)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/services/payments_service.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Services
+      # +/payment+ endpoints.
+      class PaymentsService < BaseService
+        def create(payment)
+          validate(payment, Contracts::PaymentContract)
+          parse(execute(build_request(
+                          method: "POST", base_url: @client.base_url, path: "payment",
+                          json_body: dump(payment), auth_header: @client.auth_header
+                        )), Models::FiscalReceiptResponse)
+        end
+
+        # Delete a non-chitanta payment via +DELETE /payment/v2+.
+        def delete_other(cif, payment_type:, payment_date: nil, payment_value: nil,
+                         client_name: nil, client_cif: nil, invoice_series: nil,
+                         invoice_number: nil)
+          params = { "cif" => cif, "paymentType" => payment_type }
+          params["paymentDate"]   = payment_date   unless payment_date.nil?
+          params["paymentValue"]  = payment_value  unless payment_value.nil?
+          params["clientName"]    = client_name    unless client_name.nil?
+          params["clientCif"]     = client_cif     unless client_cif.nil?
+          params["invoiceSeries"] = invoice_series unless invoice_series.nil?
+          params["invoiceNumber"] = invoice_number unless invoice_number.nil?
+          parse(execute(build_request(
+                          method: "DELETE", base_url: @client.base_url, path: "payment/v2",
+                          params: params, auth_header: @client.auth_header
+                        )), Models::BaseResponse)
+        end
+
+        def delete_chitanta(cif, series_name, number)
+          parse(execute(build_request(
+                          method: "DELETE", base_url: @client.base_url, path: "payment/chitanta",
+                          params: { "cif" => cif, "seriesName" => series_name, "number" => number },
+                          auth_header: @client.auth_header
+                        )), Models::BaseResponse)
+        end
+
+        def fiscal_receipt_text(cif, id)
+          parse(execute(build_request(
+                          method: "GET", base_url: @client.base_url, path: "payment/text",
+                          params: { "cif" => cif, "id" => id }, auth_header: @client.auth_header
+                        )), Models::FiscalReceiptResponse)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/services/stocks_service.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Services
+      # +/stocks+ endpoint.
+      class StocksService < BaseService
+        def get(cif, date, warehouse_name: nil, product_name: nil, product_code: nil)
+          params = { "cif" => cif, "date" => date }
+          params["warehouseName"] = warehouse_name unless warehouse_name.nil?
+          params["productName"]   = product_name   unless product_name.nil?
+          params["productCode"]   = product_code   unless product_code.nil?
+          parse(execute(build_request(
+                          method: "GET", base_url: @client.base_url, path: "stocks",
+                          params: params, auth_header: @client.auth_header
+                        )), Models::StocksResponse)
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/services.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    # Per-resource endpoint logic.
+    #
+    # Each service builds a {Transport::Request} for an endpoint and parses
+    # the response into a model. Services are instantiated by {Client} with a
+    # reference to the client (the "executor") which provides +base_url+,
+    # +auth_header+ and +#execute+.
+    #
+    # Each service lives in its own file (e.g. `services/invoices_service.rb`
+    # defines `InvoicesService`) and is autoloaded by Zeitwerk.
+    module Services
+      # Serialize a model, optionally wrapping it in an envelope.
+      def self.dump_model(model, envelope_key: nil)
+        data = model.to_h
+        envelope_key ? { envelope_key => data } : data
+      end
+
+      # Parse a payload into a model instance.
+      def self.parse(payload, model_class)
+        return model_class.new if payload.nil?
+        return model_class.new(payload) if payload.is_a?(Hash)
+
+        model_class.new(message: payload.to_s)
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/transport/rate_limiter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Transport
+      # Simple token-bucket limiter: +max_calls+ per +window_seconds+.
+      #
+      # Optionally enabled by clients to preempt the server's 403.
+      class RateLimiter
+        attr_reader :max_calls, :window_seconds
+
+        def initialize(max_calls: 30, window_seconds: 10.0)
+          @max_calls = max_calls
+          @window_seconds = window_seconds
+          @timestamps = []
+          @blocked_until = 0.0
+        end
+
+        # Raise {RateLimitError} if calling now would exceed the limit.
+        def acquire
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          if now < @blocked_until
+            wait = @blocked_until - now
+            raise RateLimitError, format("Client-side rate limit: would block for %.1fs.", wait)
+          end
+          prune(now)
+          if @timestamps.size >= @max_calls
+            @blocked_until = @timestamps.first + @window_seconds
+            wait = @blocked_until - now
+            raise RateLimitError, format("Client-side rate limit exceeded: would block for %.1fs.", wait)
+          end
+          @timestamps << now
+        end
+
+        # Record a server-side 403 so the limiter backs off for 10 minutes.
+        def notify_403
+          @blocked_until = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 600.0
+        end
+
+        private
+
+        def prune(now)
+          cutoff = now - @window_seconds
+          @timestamps.select! { |t| t >= cutoff }
+        end
+      end
+    end
+  end
+end

data/lib/smartbill/sdk/transport/request.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Smartbill
+  module Sdk
+    module Transport
+      # A request value object built by {Transport.build_request} and sent
+      # by an adapter.
+      #
+      # @!attribute [r] http_method HTTP method ("GET", "POST", ...).
+      # @!attribute [r] url        Full URL (without query string).
+      # @!attribute [r] headers    Hash of HTTP headers.
+      # @!attribute [r] query      Hash of query parameters (may be nil).
+      # @!attribute [r] body       Serialized request body (may be nil).
+      Request = Struct.new(:http_method, :url, :headers, :query, :body, keyword_init: true)
+    end
+  end
+end