ecf-dgii 1.0.2 → 1.1.0

data/lib/ecf_dgii/frontend_client.rb

@@ -0,0 +1,217 @@
+require "json"
+require_relative "exceptions"
+
+module EcfDgii
+  # A restricted, read-only client that only exposes GET endpoints.
+  # Suitable for use in frontend / browser code where write operations
+  # should not be available.
+  #
+  # Token lifecycle is handled automatically:
+  # 1. On each request, checks {get_cached_token}. If nil, calls {get_token}
+  #    then {cache_token}.
+  # 2. On 401 responses, calls {get_token} again, updates the cache, and
+  #    retries the request.
+  #
+  # Mirrors the TypeScript {EcfFrontendClient} 1:1.
+  #
+  # @example Basic usage
+  #   client = EcfDgii::FrontendClient.new(
+  #     get_token: -> { my_backend.fetch_token },
+  #     environment: :test
+  #   )
+  #   ecfs = client.query_ecf("131460941", "E310000051630")
+  class FrontendClient
+    ENVIRONMENT_URLS = {
+      test: "https://api.test.ecfx.ssd.com.do",
+      cert: "https://api.cert.ecfx.ssd.com.do",
+      prod: "https://api.prod.ecfx.ssd.com.do"
+    }.freeze
+
+    # @return [EcfDgii::Generated::ApiClient] The underlying generated API client.
+    attr_reader :api_client
+
+    # @return [Symbol] The configured environment.
+    attr_reader :environment
+
+    # Create a new frontend client.
+    #
+    # @param get_token [Proc] Function that fetches a fresh token
+    #   (e.g. calls your backend's GET /ecf-token). **Required**.
+    # @param cache_token [Proc, nil] Function to cache the token.
+    #   Defaults to file-based cache at +~/.ecf-dgii/token+.
+    # @param get_cached_token [Proc, nil] Function to retrieve a cached token.
+    #   Defaults to file-based cache.
+    # @param base_url [String, nil] Base URL override. Takes precedence over +environment+.
+    # @param environment [Symbol] Target environment (+:test+, +:cert+, +:prod+).
+    #   Defaults to +:test+.
+    # @param timeout [Integer] HTTP timeout in seconds. Defaults to 30.
+    def initialize(get_token:, cache_token: nil, get_cached_token: nil,
+                   base_url: nil, environment: :test, timeout: 30)
+      raise ArgumentError, "get_token is required for EcfDgii::FrontendClient" unless get_token
+
+      resolved_url = base_url || ENVIRONMENT_URLS[environment.to_sym]
+      raise ArgumentError, "Invalid environment or base URL" if resolved_url.nil? || resolved_url.empty?
+
+      @get_token = get_token
+      @cache_token = cache_token || method(:default_cache_token)
+      @get_cached_token = get_cached_token || method(:default_get_cached_token)
+
+      config = EcfDgii::Generated::Configuration.new
+      uri = URI.parse(resolved_url)
+
+      config.scheme = uri.scheme
+      config.host = uri.host
+      config.base_path = uri.path.empty? ? "" : uri.path
+      config.timeout = timeout
+
+      @api_client = EcfDgii::Generated::ApiClient.new(config)
+      @environment = environment.to_sym
+    end
+
+    # ---------------------------------------------------------------------------
+    # Base API clients (lazy-loaded)
+    # ---------------------------------------------------------------------------
+
+    def ecf_api
+      @ecf_api ||= EcfDgii::Generated::EcfApi.new(token_api_client)
+    end
+
+    def company_api
+      @company_api ||= EcfDgii::Generated::CompanyApi.new(token_api_client)
+    end
+
+    # ---------------------------------------------------------------------------
+    # ECF query operations (read-only GETs)
+    # ---------------------------------------------------------------------------
+
+    # Query ECFs by RNC and eNCF.
+    def query_ecf(rnc, encf, opts = {})
+      ecf_api.query_ecf(rnc, encf, opts)
+    end
+
+    # Search ECFs for a specific RNC.
+    def search_ecfs(rnc, opts = {})
+      ecf_api.search_ecfs(rnc, opts)
+    end
+
+    # Search all ECFs across all companies.
+    def search_all_ecfs(opts = {})
+      ecf_api.search_all_ecfs(opts)
+    end
+
+    # Get a specific ECF by message ID.
+    def get_ecf_by_id(rnc, id)
+      ecf_api.get_ecf_by_id(rnc, id)
+    end
+
+    # ---------------------------------------------------------------------------
+    # Company operations (read-only GETs)
+    # ---------------------------------------------------------------------------
+
+    # List companies with optional filters.
+    def get_companies(opts = {})
+      company_api.get_companies(opts)
+    end
+
+    # Get a company by RNC.
+    def get_company_by_rnc(rnc)
+      company_api.get_company_by_rnc(rnc)
+    end
+
+    private
+
+    # Creates an ApiClient that injects a Bearer token with cache + auto-refresh.
+    def token_api_client
+      return @token_api_client if @token_api_client
+
+      config = @api_client.config.dup
+      # We'll override the access_token via a custom middleware-like approach.
+      # Faraday supports request/response middleware via the builder.
+      # Instead of a fixed access_token, we inject it per-request with retry on 401.
+
+      client = EcfDgii::Generated::ApiClient.new(config)
+
+      # Store original call method
+      original_call = client.method(:call_api)
+
+      # Define the client's token lifecycle as a singleton method
+      client.define_singleton_method(:call_api) do |http_method, path, opts = {}|
+        # 1. Get token (from cache or fresh)
+        token = get_cached_token_proc.call
+        if token.nil? || token.empty?
+          token = get_token_proc.call
+          cache_token_proc.call(token)
+        end
+
+        # Set the token
+        opts[:header_params] ||= {}
+        opts[:header_params]["Authorization"] = "Bearer #{token}"
+
+        # Make the request
+        response = original_call.call(http_method, path, opts)
+
+        # 2. On 401, refresh and retry
+        if response.respond_to?(:code) && response.code == 401
+          token = get_token_proc.call
+          cache_token_proc.call(token)
+          opts[:header_params]["Authorization"] = "Bearer #{token}"
+          response = original_call.call(http_method, path, opts)
+        end
+
+        response
+      end
+
+      # Store procs for the singleton method closure
+      client.instance_variable_set(:@get_token_proc, @get_token)
+      client.instance_variable_set(:@cache_token_proc, @cache_token)
+      client.instance_variable_set(:@get_cached_token_proc, @get_cached_token)
+
+      # Define accessors for the closure
+      client.define_singleton_method(:get_token_proc) { @get_token_proc }
+      client.define_singleton_method(:cache_token_proc) { @cache_token_proc }
+      client.define_singleton_method(:get_cached_token_proc) { @get_cached_token_proc }
+
+      @token_api_client = client
+    end
+
+    # Default file-based token cache: ~/.ecf-dgii/token
+    def default_cache_dir
+      @default_cache_dir ||= begin
+        dir = File.expand_path("~/.ecf-dgii")
+        Dir.mkdir(dir) unless Dir.exist?(dir)
+        dir
+      end
+    end
+
+    def default_cache_token(token)
+      File.write(File.join(default_cache_dir, "token"), token)
+    end
+
+    def default_get_cached_token
+      path = File.join(default_cache_dir, "token")
+      File.exist?(path) ? File.read(path).strip : nil
+    end
+  end
+
+  # Factory that creates a restricted read-only client suitable for frontend use.
+  # Only GET endpoints are exposed.
+  #
+  # @param get_token [Proc] Function that fetches a fresh token.
+  # @param cache_token [Proc, nil] Function to cache the token.
+  # @param get_cached_token [Proc, nil] Function to retrieve a cached token.
+  # @param base_url [String, nil] Base URL override.
+  # @param environment [Symbol] Target environment.
+  #
+  # @return [EcfDgii::FrontendClient]
+  def self.create_frontend_client(get_token:, cache_token: nil, get_cached_token: nil,
+                                   base_url: nil, environment: :test, timeout: 30)
+    FrontendClient.new(
+      get_token: get_token,
+      cache_token: cache_token,
+      get_cached_token: get_cached_token,
+      base_url: base_url,
+      environment: environment,
+      timeout: timeout
+    )
+  end
+end

data/lib/ecf_dgii/polling.rb

@@ -1,23 +1,60 @@
-module EcfDgii
-  class PollingError < StandardError; end
-  class PollingTimeoutError < PollingError; end
-  class PollingMaxRetriesError < PollingError; end
+require_relative "exceptions"
 
+module EcfDgii
+  # Configuration options for polling with exponential backoff.
+  #
+  # Matches the TypeScript SDK's PollingOptions interface 1:1.
   class PollingOptions
-    attr_accessor :initial_delay, :max_delay, :max_retries, :backoff_multiplier, :timeout
+    # @return [Float] Initial delay between polls in seconds. Default: 1.0
+    attr_accessor :initial_delay
+
+    # @return [Float] Maximum delay between polls in seconds. Default: 30.0
+    attr_accessor :max_delay
+
+    # @return [Integer] Maximum number of retries. Default: 60
+    attr_accessor :max_retries
+
+    # @return [Float] Backoff multiplier. Default: 2.0
+    attr_accessor :backoff_multiplier
 
-    def initialize(initial_delay: 2.0, max_delay: 30.0, max_retries: 0, backoff_multiplier: 1.5, timeout: 300.0)
+    # @return [Float, nil] Total timeout in seconds. Optional (nil = no timeout).
+    attr_accessor :timeout
+
+    # @return [Proc, nil] Optional cancellation callable.
+    #   Called before each poll iteration. If it returns a truthy value,
+    #   polling is aborted with PollingTimeoutError.
+    attr_accessor :cancellation
+
+    def initialize(initial_delay: 1.0, max_delay: 30.0, max_retries: 60,
+                   backoff_multiplier: 2.0, timeout: nil, cancellation: nil)
       @initial_delay = initial_delay
       @max_delay = max_delay
       @max_retries = max_retries
       @backoff_multiplier = backoff_multiplier
       @timeout = timeout
+      @cancellation = cancellation
     end
   end
 
+  # Polling logic with exponential backoff.
+  #
+  # Usage:
+  #   EcfDgii::Polling.poll_until_complete do
+  #     client.query_ecf(rnc, encf)
+  #   end
   module Polling
-    TERMINAL_PROGRESS = %w[Completed Failed Rejected].freeze
+    # Terminal progress values matching the ECF API contract.
+    #   - "Finished" → ECF processing completed successfully
+    #   - "Error"    → ECF processing failed (throws EcfError in client)
+    TERMINAL_PROGRESS = %w[Finished Error].freeze
 
+    # Poll a block until its result indicates completion, using exponential backoff.
+    #
+    # @yieldreturn [Object] An object that responds to #progress
+    # @param options [PollingOptions, nil] Polling configuration
+    # @return [Object] The final result when progress is terminal
+    # @raise [PollingTimeoutError] If total timeout is exceeded
+    # @raise [PollingMaxRetriesError] If max retries is exceeded
     def self.poll_until_complete(options = nil)
       opts = options || PollingOptions.new
       delay = opts.initial_delay
@@ -25,32 +62,52 @@ module EcfDgii
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
       loop do
+        # Check cancellation before each iteration
+        if opts.cancellation && opts.cancellation.call
+          raise PollingTimeoutError, "Polling was cancelled"
+        end
+
         result = yield
 
-        progress = nil
-        if result.respond_to?(:progress)
-          progress = result.progress
-        elsif result.is_a?(Hash)
-          progress = result[:progress] || result["progress"]
-        end
+        progress = extract_progress(result)
 
-        progress_value = progress.respond_to?(:value) ? progress.value : progress.to_s
+        return result if TERMINAL_PROGRESS.include?(progress)
 
-        return result if TERMINAL_PROGRESS.include?(progress_value)
+        retries += 1
 
-        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
-        if opts.timeout && opts.timeout > 0 && elapsed >= opts.timeout
-          raise PollingTimeoutError, "El polling excedió el tiempo límite de #{opts.timeout}s (último progreso: #{progress_value})"
+        if opts.max_retries > 0 && retries >= opts.max_retries
+          raise PollingMaxRetriesError.new(opts.max_retries)
         end
 
-        retries += 1
-        if opts.max_retries && opts.max_retries > 0 && retries >= opts.max_retries
-          raise PollingMaxRetriesError, "El polling excedió el máximo de #{opts.max_retries} intentos (último progreso: #{progress_value})"
+        if opts.timeout && opts.timeout > 0
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+          if elapsed >= opts.timeout
+            raise PollingTimeoutError,
+                  "Polling timed out after #{opts.timeout}s (last progress: #{progress})"
+          end
         end
 
         sleep(delay)
         delay = [delay * opts.backoff_multiplier, opts.max_delay].min
       end
     end
+
+    # Extract the progress value from a result, regardless of its type.
+    #
+    # @param result [Object] An API model object, Hash, or anything responding to #progress
+    # @return [String] The progress value as a string
+    def self.extract_progress(result)
+      progress = nil
+      if result.respond_to?(:progress)
+        progress = result.progress
+      elsif result.is_a?(Hash)
+        progress = result[:progress] || result["progress"]
+      end
+
+      progress = progress.value if progress.respond_to?(:value)
+      progress.to_s
+    end
+
+    private_class_method :extract_progress
   end
 end

data/lib/ecf_dgii/railtie.rb

@@ -1,5 +1,8 @@
 module EcfDgii
   class Railtie < Rails::Railtie
-    # The integration works through initializers generated by the user.
+    # Make EcfDgii.client available in Rails console and controllers.
+    console do
+      EcfDgii.client
+    end
   end
 end

data/lib/ecf_dgii/version.rb

@@ -1,3 +1,4 @@
 module EcfDgii
-  VERSION = "1.0.2"
+  # SDK Version
+  VERSION = "1.1.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecf-dgii
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - SSD Smart Software Development SRL
@@ -143,6 +143,8 @@ files:
 - README.md
 - lib/ecf-dgii.rb
 - lib/ecf_dgii/client.rb
+- lib/ecf_dgii/exceptions.rb
+- lib/ecf_dgii/frontend_client.rb
 - lib/ecf_dgii/generated.rb
 - lib/ecf_dgii/generated/api/api_key_api.rb
 - lib/ecf_dgii/generated/api/aprobacion_comercial_api.rb