frame_payments 0.1.0

data/lib/frame/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Frame
+  # Configuration management for the Frame SDK.
+  #
+  # Handles API keys, base URLs, timeouts, and other SDK settings.
+  # Typically accessed through the Frame module methods like Frame.api_key.
+  class Configuration
+    DEFAULT_API_BASE = "https://api.framepayments.com"
+    DEFAULT_OPEN_TIMEOUT = 30
+    DEFAULT_READ_TIMEOUT = 80
+    DEFAULT_VERIFY_SSL_CERTS = true
+
+    attr_accessor :api_key, :api_base, :open_timeout, :read_timeout, :verify_ssl_certs, :log_level, :logger
+
+    def self.setup
+      new.tap do |config|
+        config.api_base = DEFAULT_API_BASE
+        config.open_timeout = DEFAULT_OPEN_TIMEOUT
+        config.read_timeout = DEFAULT_READ_TIMEOUT
+        config.verify_ssl_certs = DEFAULT_VERIFY_SSL_CERTS
+        config.log_level = nil
+        config.logger = nil
+      end
+    end
+  end
+end

data/lib/frame/error.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Frame
+  # Base error class for all Frame-related errors
+  class Error < StandardError; end
+
+  # API Error class for handling API responses
+  class APIError < Error
+    attr_reader :message
+    attr_reader :http_status
+    attr_reader :http_body
+    attr_reader :json_body
+    attr_reader :code
+
+    def initialize(message = nil, http_status: nil, http_body: nil, json_body: nil, code: nil)
+      @message = message
+      @http_status = http_status
+      @http_body = http_body
+      @json_body = json_body
+      @code = code
+      super(message)
+    end
+
+    def to_s
+      status_string = @http_status.nil? ? "" : "(Status #{@http_status}) "
+      code_string = @code.nil? ? "" : "(Code #{@code}) "
+      "#{status_string}#{code_string}#{@message}"
+    end
+  end
+
+  # Authentication error
+  class AuthenticationError < APIError; end
+
+  # Invalid request error
+  class InvalidRequestError < APIError; end
+
+  # API connection error
+  class APIConnectionError < APIError; end
+
+  # Rate limit error
+  class RateLimitError < APIError; end
+
+  # Resource not found error
+  class ResourceNotFoundError < APIError; end
+
+  # Invalid parameters error
+  class InvalidParameterError < APIError; end
+end

data/lib/frame/frame_client.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Frame
+  # HTTP client for making requests to the Frame Payments API.
+  #
+  # Handles connection management, request execution, and response processing.
+  # Automatically handles authentication, error parsing, and response formatting.
+  class FrameClient
+    attr_accessor :conn, :config
+
+    @default_client_mutex = Mutex.new
+
+    def self.active_client
+      Thread.current[:frame_client] || default_client
+    end
+
+    def self.default_client
+      return @default_client if @default_client
+
+      @default_client_mutex.synchronize do
+        @default_client ||= FrameClient.new(
+          api_key: Frame.api_key,
+          api_base: Frame.api_base,
+          open_timeout: Frame.open_timeout,
+          read_timeout: Frame.read_timeout,
+          verify_ssl_certs: Frame.verify_ssl_certs,
+          logger: Frame.logger,
+          log_level: Frame.log_level
+        )
+      end
+    end
+
+    def initialize(api_key: nil, api_base: nil, open_timeout: nil, read_timeout: nil, verify_ssl_certs: nil, logger: nil, log_level: nil)
+      @config = {
+        api_key: api_key || Frame.api_key,
+        api_base: api_base || Frame.api_base,
+        open_timeout: open_timeout || Frame.open_timeout,
+        read_timeout: read_timeout || Frame.read_timeout,
+        verify_ssl_certs: verify_ssl_certs.nil? ? Frame.verify_ssl_certs : verify_ssl_certs,
+        logger: logger || Frame.logger,
+        log_level: log_level || Frame.log_level
+      }
+
+      @conn = create_connection
+    end
+
+    def request(method, path, params = {}, opts = {})
+      response = execute_request(method, path, params, opts)
+      process_response(response)
+    rescue Faraday::ConnectionFailed => e
+      raise APIConnectionError.new("Connection failed: #{e.message}")
+    rescue Faraday::TimeoutError => e
+      raise APIConnectionError.new("Request timed out: #{e.message}")
+    rescue Faraday::ClientError => e
+      raise APIConnectionError.new("Client error: #{e.message}")
+    end
+
+    private
+
+    def create_connection
+      Faraday.new(url: @config[:api_base]) do |faraday|
+        faraday.request :json
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+
+        # SSL verification setting
+        faraday.ssl.verify = @config[:verify_ssl_certs]
+
+        faraday.options.timeout = @config[:read_timeout]
+        faraday.options.open_timeout = @config[:open_timeout]
+      end
+    end
+
+    def execute_request(method, path, params, opts)
+      unless @config[:api_key]
+        raise AuthenticationError.new(
+          "API key is required. Set Frame.api_key before making requests.",
+          http_status: nil
+        )
+      end
+
+      headers = {
+        "Authorization" => "Bearer #{@config[:api_key]}",
+        "Content-Type" => "application/json",
+        "User-Agent" => "FrameRuby/#{Frame::VERSION}"
+      }
+
+      log_request(method, path, params, headers) if should_log?
+
+      response = case method.to_s.downcase.to_sym
+      when :get
+        @conn.get(path) do |req|
+          req.params = params
+          req.headers = headers
+        end
+      when :post
+        @conn.post(path) do |req|
+          req.body = params.to_json
+          req.headers = headers
+        end
+      when :patch
+        @conn.patch(path) do |req|
+          req.body = params.to_json
+          req.headers = headers
+        end
+      when :delete
+        @conn.delete(path) do |req|
+          req.params = params
+          req.headers = headers
+        end
+      else
+        raise APIConnectionError.new("Unrecognized HTTP method: #{method}")
+      end
+
+      log_response(response) if should_log?
+
+      response
+    end
+
+    def process_response(response)
+      case response.status
+      when 200, 201, 202
+        parsed_response = Util.symbolize_names(response.body)
+      when 204
+        parsed_response = {}
+      when 400, 404
+        error = Util.symbolize_names(response.body)
+        raise InvalidRequestError.new(
+          error[:error],
+          http_status: response.status,
+          http_body: response.body,
+          json_body: error
+        )
+      when 401
+        error = Util.symbolize_names(response.body)
+        raise AuthenticationError.new(
+          error[:error],
+          http_status: response.status,
+          http_body: response.body,
+          json_body: error
+        )
+      when 429
+        error = Util.symbolize_names(response.body)
+        raise RateLimitError.new(
+          error[:error],
+          http_status: response.status,
+          http_body: response.body,
+          json_body: error
+        )
+      else
+        error = Util.symbolize_names(response.body)
+        raise APIError.new(
+          error[:error] || "Unknown error",
+          http_status: response.status,
+          http_body: response.body,
+          json_body: error
+        )
+      end
+
+      parsed_response
+    end
+
+    def should_log?
+      @config[:logger] && @config[:log_level]
+    end
+
+    def log_request(method, path, params, headers)
+      return unless should_log?
+
+      sanitized_headers = headers.dup
+      sanitized_headers["Authorization"] = "Bearer [REDACTED]" if sanitized_headers["Authorization"]
+
+      sanitized_params = sanitize_sensitive_data(params)
+
+      @config[:logger].public_send(@config[:log_level], "[Frame] #{method.to_s.upcase} #{path}")
+      @config[:logger].public_send(@config[:log_level], "[Frame] Headers: #{sanitized_headers.inspect}")
+      @config[:logger].public_send(@config[:log_level], "[Frame] Params: #{sanitized_params.inspect}") unless sanitized_params.empty?
+    end
+
+    def log_response(response)
+      return unless should_log?
+
+      @config[:logger].public_send(@config[:log_level], "[Frame] Response: #{response.status} #{response.reason_phrase}")
+      if response.body&.is_a?(Hash)
+        sanitized_body = sanitize_sensitive_data(response.body)
+        @config[:logger].public_send(@config[:log_level], "[Frame] Body: #{sanitized_body.inspect}")
+      end
+    end
+
+    def sanitize_sensitive_data(data)
+      return data unless data.is_a?(Hash)
+
+      sensitive_keys = %w[api_key secret key password card_number cvc cvv number]
+      data.each_with_object({}) do |(key, value), sanitized|
+        key_str = key.to_s.downcase
+        sanitized[key] = if sensitive_keys.any? { |sensitive| key_str.include?(sensitive) }
+          "[REDACTED]"
+        elsif value.is_a?(Hash)
+          sanitize_sensitive_data(value)
+        elsif value.is_a?(Array)
+          value.map { |v| v.is_a?(Hash) ? sanitize_sensitive_data(v) : v }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/frame/frame_object.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Frame
+  # Base object class for all Frame API responses.
+  #
+  # FrameObject provides dynamic attribute access and JSON serialization
+  # for API responses. All API resources inherit from this class.
+  #
+  # Attributes are dynamically created based on the API response, allowing
+  # for flexible access to all fields:
+  #
+  #   customer.name  # => "John Doe"
+  #   customer["name"]  # => "John Doe"
+  #   customer[:name]  # => "John Doe"
+  #
+  class FrameObject
+    include Enumerable
+
+    attr_reader :id, :original_values
+
+    def initialize(id = nil, opts = {})
+      @id = id
+      @values = {}
+      @original_values = {}
+      @unsaved_values = Set.new
+    end
+
+    def self.construct_from(values, opts = {})
+      obj = new(values[:id])
+      obj.initialize_from(values, opts)
+      obj
+    end
+
+    def initialize_from(values, opts = {})
+      @original_values = values.dup
+      @values = values.dup
+
+      # Make sure all keys are symbols
+      @values.keys.each do |k|
+        @values[k.to_sym] = @values.delete(k) unless k.is_a?(Symbol)
+      end
+
+      # Add accessors for all keys
+      remove_accessors(@values.keys)
+      add_accessors(@values.keys)
+
+      self
+    end
+
+    def update_attributes(values)
+      values.each do |k, v|
+        @values[k] = Util.convert_to_frame_object(v)
+      end
+    end
+
+    def [](key)
+      @values[key.to_sym]
+    end
+
+    def []=(key, value)
+      send(:"#{key}=", value)
+    end
+
+    def keys
+      @values.keys
+    end
+
+    def values
+      @values.values
+    end
+
+    def to_s(*_args)
+      JSON.pretty_generate(@values)
+    end
+
+    def inspect
+      id_string = @id.nil? ? "" : " id=#{@id}"
+      "#<#{self.class}:0x#{object_id.to_s(16)}#{id_string}> JSON: " + JSON.pretty_generate(@values)
+    end
+
+    def to_hash
+      @values.each_with_object({}) do |(key, value), hash|
+        hash[key] = case value
+        when FrameObject
+          value.to_hash
+        when Array
+          value.map { |v| v.respond_to?(:to_hash) ? v.to_hash : v }
+        else
+          value
+        end
+      end
+    end
+
+    def each(&blk)
+      @values.each(&blk)
+    end
+
+    def serialize_params(obj)
+      params = {}
+
+      obj.instance_variable_get(:@values).each do |key, value|
+        params[key] = if value.is_a?(FrameObject)
+          value.serialize_params(value)
+        elsif value.is_a?(Array)
+          value.map { |v| v.is_a?(FrameObject) ? v.serialize_params(v) : v }
+        else
+          value
+        end
+      end
+
+      params
+    end
+
+    protected
+
+    def metaclass
+      class << self; self; end
+    end
+
+    def remove_accessors(keys)
+      # Skip keys that should be ignored when adding/removing accessors
+      ignored_keys = [:id, :data]
+
+      metaclass.instance_eval do
+        keys.each do |k|
+          # Skip certain keys that have special handling
+          next if ignored_keys.include?(k.to_sym)
+
+          # Remove reader method if it exists
+          remove_method(k.to_sym) if method_defined?(k.to_sym)
+
+          # Remove writer method if it exists
+          remove_method(:"#{k}=") if method_defined?(:"#{k}=")
+        end
+      end
+    end
+
+    def add_accessors(keys)
+      # Skip keys that should be ignored when adding/removing accessors
+      ignored_keys = [:id, :data]
+
+      metaclass.instance_eval do
+        keys.each do |k|
+          # Skip certain keys that have special handling
+          next if ignored_keys.include?(k.to_sym)
+
+          define_method(k) { @values[k] }
+          define_method(:"#{k}=") do |v|
+            @values[k] = v
+          end
+        end
+      end
+    end
+  end
+end

data/lib/frame/list_object.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Frame
+  class ListObject < FrameObject
+    include Enumerable
+    include Frame::APIOperations::Request
+
+    attr_accessor :filters
+    attr_reader :resource_url, :data
+
+    def initialize(data = {}, opts = {})
+      super(nil, opts)
+      @data = data[:data] || []
+      @filters = {}
+      @resource_url = opts[:resource_url]
+      @has_more = data[:meta] && data[:meta][:has_more]
+      @page = data[:meta] && data[:meta][:page] || 1
+
+      # Extract per_page from URL if available
+      @per_page = if data.dig(:meta, :url)&.include?("per_page=")
+        begin
+          data[:meta][:url].match(/per_page=(\d+)/)[1].to_i
+        rescue
+          10
+        end
+      else
+        10
+      end
+    end
+
+    def self.construct_from(values, opts = {})
+      data = values || {}
+
+      # Initialize from the values - excluding the :data key to avoid accessor conflicts
+      # We'll handle data manually since it's declared as an attribute
+      obj = new(data, opts)
+
+      # Store original values except data
+      values_without_data = values.dup
+      data_array = values_without_data.delete(:data)
+
+      # Initialize from values without data first
+      obj.initialize_from(values_without_data, opts)
+
+      # Then process the data array
+      if data_array&.is_a?(Array)
+        converted_data = data_array.map { |item| Util.convert_to_frame_object(item, opts) }
+        obj.instance_variable_set(:@data, converted_data)
+      end
+
+      obj
+    end
+
+    def self.empty_list(opts = {})
+      construct_from({data: [], meta: {has_more: false, page: 1}}, opts)
+    end
+
+    def [](index)
+      @data[index]
+    end
+
+    def each(&blk)
+      @data.each(&blk)
+    end
+
+    def empty?
+      @data.empty?
+    end
+
+    def first
+      @data.first
+    end
+
+    def last
+      @data.last
+    end
+
+    def retrieve(id, opts = {})
+      resource_class = object_class_for_data
+      return resource_class.retrieve(id, opts) if resource_class
+      nil
+    end
+
+    def next_page(params = {}, opts = {})
+      return self.class.empty_list(opts) unless has_more?
+
+      params = filters.merge(params || {})
+      next_page_num = @page + 1 if @page
+      params[:page] = next_page_num
+      params[:per_page] = @per_page if @per_page
+
+      # Get the resource URL - try all possible fallbacks
+      url = resource_url ||
+        (self.class.respond_to?(:resource_url) ? self.class.resource_url : nil) ||
+        "/v1/customers" # Default if we can't determine it
+
+      response = request(:get, url, params, opts)
+      result = Util.convert_to_frame_object(response, opts)
+
+      # Update this object's state with the next page's data
+      if result && !result.empty?
+        @page = next_page_num
+        @data = result.data
+        @has_more = result.has_more?
+
+        self
+      else
+        result
+      end
+    end
+
+    def has_more?
+      !!@has_more
+    end
+
+    def total_count
+      @data.size
+    end
+
+    def to_hash
+      {
+        data: @data.map { |i| i.is_a?(FrameObject) ? i.to_hash : i },
+        meta: {
+          has_more: has_more?,
+          page: @page,
+          per_page: @per_page
+        }
+      }
+    end
+
+    def inspect
+      meta_info = "#<#{self.class.name}:0x#{object_id.to_s(16)} @page=#{@page} @per_page=#{@per_page} @has_more=#{@has_more} items=#{@data.size}>"
+
+      # If data is empty, just return meta info
+      return meta_info if @data.empty?
+
+      # Format each item in the data array
+      data_strings = @data.map do |item|
+        if item.is_a?(FrameObject) && item.respond_to?(:id) && item.id
+          obj_name = item.class.name.split("::").last
+          "  #<#{obj_name}:#{item.id} #{item.inspect}>"
+        else
+          "  #{item.inspect}"
+        end
+      end
+
+      "#{meta_info}\ndata=[\n#{data_strings.join(",\n")}\n]"
+    end
+
+    private
+
+    def object_class_for_data
+      return nil if @data.empty?
+
+      # Get first item's object type, whether it's already a FrameObject or still a Hash
+      first_item = @data.first
+      object_name = if first_item.is_a?(FrameObject)
+        first_item[:object]
+      elsif first_item.is_a?(Hash)
+        first_item[:object]
+      end
+
+      Util.object_classes_to_constants[object_name] if object_name
+    end
+  end
+end

data/lib/frame/resources/charge_intent.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Frame
+  class ChargeIntent < APIResource
+    extend Frame::APIOperations::Create
+    extend Frame::APIOperations::List
+    include Frame::APIOperations::Save
+
+    OBJECT_NAME = "charge_intent"
+
+    def self.object_name
+      OBJECT_NAME
+    end
+
+    def self.create(params = {}, opts = {})
+      request_object(
+        :post,
+        "/v1/charge_intents",
+        params,
+        opts
+      )
+    end
+
+    def self.list(params = {}, opts = {})
+      request_object(
+        :get,
+        "/v1/charge_intents",
+        params,
+        opts
+      )
+    end
+
+    def self.retrieve(id, opts = {})
+      id = Util.normalize_id(id)
+      request_object(
+        :get,
+        "/v1/charge_intents/#{CGI.escape(id)}",
+        {},
+        opts
+      )
+    end
+
+    def authorize(params = {}, opts = {})
+      request_object(
+        :post,
+        "/v1/charge_intents/#{CGI.escape(self["id"])}/authorize",
+        params,
+        opts
+      )
+    end
+
+    def self.authorize(id, params = {}, opts = {})
+      request_object(
+        :post,
+        "/v1/charge_intents/#{CGI.escape(id)}/authorize",
+        params,
+        opts
+      )
+    end
+
+    def capture(params = {}, opts = {})
+      request_object(
+        :post,
+        "/v1/charge_intents/#{CGI.escape(self["id"])}/capture",
+        params,
+        opts
+      )
+    end
+
+    def self.capture(id, params = {}, opts = {})
+      request_object(
+        :post,
+        "/v1/charge_intents/#{CGI.escape(id)}/capture",
+        params,
+        opts
+      )
+    end
+
+    def cancel(params = {}, opts = {})
+      request_object(
+        :post,
+        "/v1/charge_intents/#{CGI.escape(self["id"])}/cancel",
+        params,
+        opts
+      )
+    end
+
+    def self.cancel(id, params = {}, opts = {})
+      request_object(
+        :post,
+        "/v1/charge_intents/#{CGI.escape(id)}/cancel",
+        params,
+        opts
+      )
+    end
+
+    def save(params = {}, opts = {})
+      values = serialize_params(self).merge(params)
+
+      if values.empty?
+        return self
+      end
+
+      updated = request_object(
+        :patch,
+        "/v1/charge_intents/#{CGI.escape(self["id"])}",
+        values,
+        opts
+      )
+
+      initialize_from(updated)
+      self
+    end
+  end
+end