provider_kit 0.2.0

data/lib/provider_kit/registerable.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ProviderKit
+  # Designed to add registration methods to the core namespace
+  module Registerable
+
+    def deregister(key)
+      if registration = registrations[key]
+        config.registered_providers.delete(key)
+      end
+    end
+
+    def for(type)
+      if env_key = ENV["PROVIDER_FOR_#{ type.upcase }"].presence
+        registrations[env_key.to_clean_sym].klass
+      elsif default_key = config.type_defaults[type].presence
+        registrations[default_key].klass
+      else
+        providers(type:).last
+      end
+    end
+
+    def providers(type: nil)
+      registrations(type:).values.map(&:klass)
+    end
+
+    # ProviderKit.register :stripe
+    def register(key, **options)
+      registration = Registration.new(key, **options)
+      return false unless registration.valid?
+
+      deregister(key)
+
+      config.registered_providers[key] = registration
+    end
+
+    def registrations(type: nil)
+      if type.present?
+        config.registered_providers.select { |_, reg| reg.types.include?(type) }
+      else
+        config.registered_providers
+      end
+    end
+
+    def use(key, **options)
+      type = options[:for] || options[:type]
+
+      config.type_defaults[type] = key
+    end
+
+  end
+end

data/lib/provider_kit/registration.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module ProviderKit
+  class Registration
+
+    attr_reader :key
+    attr_reader :options
+
+    def initialize(key, **options)
+      @key      = key
+
+      if options[:type]
+        @types = Array(options.delete(:type)).flatten.compact.presence
+      end
+
+      if options[:types]
+        @types = Array(options.delete(:types)).flatten.compact.presence
+      end
+
+      @options  = options
+    end
+
+    def class_name
+      options[:class_name].presence || "#{ key.to_s.classify }::Provider"
+    end
+
+    def config
+      @config ||= Settings.load(options)
+    end
+
+    def credentials
+      @credentials ||= Settings.load(Rails.application.credentials.dig(:providers, key)&.to_h)
+    end
+
+    def display_key
+      config.short_key.presence || key
+    end
+
+    def disallow_in_test_env?
+      options[:test] == false
+    end
+
+    def klass
+      if Rails.application.config.cache_classes
+        @klass ||= build_klass_from_name
+      else
+        build_klass_from_name
+      end
+    end
+
+    # generic? => (types.include?(:generic))
+    def method_missing(method_name)
+      if match = method_name.to_s.match(/^(?<attribute>[a-z0-9_]+)\?$/)
+        types.include?(match[:attribute].to_sym)
+      end
+    end
+
+    def name
+      options[:name].presence || key.to_s.titleize
+    end
+
+    def provider
+      ProviderKit::Provider.new(key).provider_instance
+    end
+
+    def types
+      @types ||= [ :generic ]
+    end
+
+    def valid?
+      if disallow_in_test_env? && Rails.env.test?
+        return false
+      end
+
+      true
+    end
+
+    private
+
+      def build_klass_from_name
+        if klass = class_name.to_s.safe_constantize
+          klass.key = key if klass.respond_to?(:key=)
+          klass
+        end
+      end
+
+  end
+end

data/lib/provider_kit/settings.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module ProviderKit
+  # Serializable object to read/write from account settings fields
+  class Settings
+
+    attr_reader :data
+
+    def initialize(raw_data)
+      @data = build_data(raw_data)&.symbolize_keys || {}
+    end
+
+    def [](key)
+      data[key]
+    end
+
+    def []=(key, value)
+      data[key] = value
+    end
+
+    def include?(key)
+      data.include?(key)
+    end
+
+    def inspect
+      @data.inspect
+    end
+
+    def method_missing(method_name, *args)
+      super if data.nil?
+
+      # some_key => :value
+      if match = method_name.to_s.match(/^(?<attribute>[a-z0-9_]+)$/)
+        key = match[:attribute].to_sym
+
+        if Hash === data[key]
+          self.class.new(data[key])
+        else
+          data[key]
+        end
+
+      # some_key = "value"
+      elsif match = method_name.to_s.match(/^(?<attribute>[a-z0-9_]+)=$/)
+        key = match[:attribute].to_sym
+
+        data[key] = args.first
+
+      # some_key? => true/false
+      elsif match = method_name.to_s.match(/^(?<attribute>[a-z0-9_]+)\?$/)
+        key = match[:attribute].to_sym
+
+        data.has_key?(key) && (data[key] == true || data[key] == "1")
+      end
+    end
+
+    # always yes so this gets picked up by `method_missing`
+    def respond_to?(_)
+      true
+    end
+
+    def update(value = {})
+      existing = (data.presence || {}).symbolize_keys
+      value = value.try(:to_h) if value.respond_to?(:to_h)
+      value = nil unless value.is_a?(Hash)
+      value = {} unless value.present?
+      value = value.symbolize_keys
+
+      updated = existing.merge(value)
+
+      @data = build_data(updated)
+    end
+
+    def to_h
+      data.presence || {}
+    end
+
+    def to_json
+      if data.present?
+        data.to_json
+      end
+    end
+
+    def self.dump(data)
+      case data
+      when self
+        data.to_json
+      else
+        new(data).to_json
+      end
+    end
+
+    def self.load(data = nil)
+      new(data.presence || {})
+    end
+
+    class Jsonb < self
+
+      def to_json
+        if data.present?
+          data
+        end
+      end
+
+    end
+
+    private
+
+      def build_data(data)
+        hash = if Settings === data
+          data.data
+        elsif Hash === data
+          data
+        else
+          JSON.parse(data)
+        end
+
+        clean_values(hash)
+      rescue StandardError => e
+        Rails.logger.error "Error loading Settings #{ e.message }"
+
+        {}
+      end
+
+      def clean_array_value(value)
+        value.map do |item|
+          if String === item && item =~ /^{(.*?)}$/
+            JSON.parse(item).symbolize_keys rescue item
+          else
+            item
+          end
+        end
+      end
+
+      def clean_hash_value(key, value)
+        if value.nil?
+          nil
+        elsif key.to_s.ends_with?("_id") && value.to_s.strip =~ /^\d*$/
+          value.to_i
+        elsif value.to_s.strip =~ /^\d+$/ && value.to_s.strip.size < 8
+          value.to_i
+        elsif value.is_a?(String)
+          value.to_s.strip.presence
+
+        # Money duck type without requiring Money gem here
+        elsif value.respond_to?(:cents) && value.respond_to?(:currency)
+          value
+        elsif value.to_s.strip =~ /^\d+\.\d+$/
+          BigDecimal(value)
+        elsif value == "1" || value == "true"
+          true
+        elsif value == "0" || value == "false"
+          false
+        elsif Array === value
+          clean_array_value(value)
+        else
+          value
+        end
+      end
+
+      # make true/false values consistent from forms
+      def clean_values(hash)
+        hash.reduce({}) do |result, (key, value)|
+          result[key] = clean_hash_value(key, value)
+          result
+        end
+      end
+
+  end
+end

data/lib/provider_kit/version.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module ProviderKit
+
+  VERSION = "0.2.0"
+
+  module Version
+
+    def self.to_s
+      ProviderKit::VERSION
+    end
+
+  end
+
+end

data/lib/provider_kit.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "provider_kit/engine"
+require "provider_kit/exceptions"
+require "provider_kit/version"
+require "active_support/dependencies/autoload"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.new
+path = File.expand_path(File.join(File.dirname(__FILE__), "provider_kit"))
+
+loader.push_dir(path)
+loader.ignore(File.expand_path(path, "generators"))
+loader.setup
+
+module ProviderKit
+
+  extend ActiveSupport::Autoload
+  include ActiveSupport::Configurable
+
+  ## Config
+  configure do |config|
+    config.registered_providers = {}
+
+    # Set to :hash to just return a plain hash
+    config.capability_response_format = :object
+
+    # Default provider for given type
+    config.type_defaults = {}
+  end
+
+  eager_autoload do
+    autoload :Buildable
+    autoload :Registerable
+  end
+
+  ## Core
+  autoload :Callbacks
+  autoload :EncryptedSettings
+  autoload :Encryptor
+  autoload :Execution
+  autoload :JsonClient
+  autoload :JsonRequest
+  autoload :Logging
+  autoload :Provideable
+  autoload :Provider
+  autoload :ProviderAttribute
+  autoload :Settings
+
+  ## Third-party API setup
+  autoload :Capability
+  autoload :CapabilityExtension
+  autoload :Capable
+  autoload :Context
+  autoload :Registration
+
+  ## Set up extensions for this module
+  extend Registerable
+  extend Buildable
+
+end

metadata

@@ -0,0 +1,205 @@
+--- !ruby/object:Gem::Specification
+name: provider_kit
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- John D. Tornow
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: annotaterb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.15'
+- !ruby/object:Gem::Dependency
+  name: factory_bot_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.76'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.76'
+- !ruby/object:Gem::Dependency
+  name: shoulda-matchers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.5'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A generic interface and abstraction layer for dealing with third-party
+  data providers and APIs in Rails. ProviderKit helps you to add a layer between your
+  third-party APIs and internal code.
+email:
+- john@johntornow.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- Rakefile
+- lib/generators/provider/USAGE
+- lib/generators/provider/provider_generator.rb
+- lib/generators/provider/templates/capability.rb.tt
+- lib/generators/provider/templates/context.rb.tt
+- lib/generators/provider/templates/provider.rb.tt
+- lib/generators/provider/templates/spec.rb.tt
+- lib/provider_kit.rb
+- lib/provider_kit/buildable.rb
+- lib/provider_kit/callbacks.rb
+- lib/provider_kit/capability.rb
+- lib/provider_kit/capability_extension.rb
+- lib/provider_kit/capable.rb
+- lib/provider_kit/context.rb
+- lib/provider_kit/encrypted_settings.rb
+- lib/provider_kit/encryptor.rb
+- lib/provider_kit/engine.rb
+- lib/provider_kit/exceptions.rb
+- lib/provider_kit/execution.rb
+- lib/provider_kit/json_client.rb
+- lib/provider_kit/json_request.rb
+- lib/provider_kit/logging.rb
+- lib/provider_kit/provideable.rb
+- lib/provider_kit/provider.rb
+- lib/provider_kit/provider_attribute.rb
+- lib/provider_kit/registerable.rb
+- lib/provider_kit/registration.rb
+- lib/provider_kit/settings.rb
+- lib/provider_kit/version.rb
+homepage: https://github.com/jdtornow/provider_kit
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/jdtornow/provider_kit/issues
+  changelog_uri: https://github.com/jdtornow/provider_kit/releases
+  homepage_uri: https://github.com/jdtornow/provider_kit
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.8.11
+requirements: []
+rubygems_version: 3.5.5
+signing_key:
+specification_version: 4
+summary: A generic interface for dealing with third-party data providers and APIs.
+test_files: []