provider_kit 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba514d53e0d9f91bec62dbe6ff0687b73038ae223a19f266a6a11321fda19b54
+  data.tar.gz: 33ab21762119c6ca00ce6951fde0bedd45f6c9e719c4b175478592df47c7aadf
+SHA512:
+  metadata.gz: e16ff38a23a7cb98796299f1259f009d94fb5ae2b28cf6db850e38b3f58f6a0ab89eec170d25a1b537569842497694ba74fb0fd660d91df609fc3b573c578675
+  data.tar.gz: 00ed090c391619a04d47dc39ca56d42f9bbdef1742bfa4ced62e009624508224b71e7677f4cac17a1c33e9c16b36e544c1c75b6ad07d35d1610b0b92ce80d678

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 John D. Tornow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+# ProviderKit
+
+ProviderKit is a simple utility for creating an abstraction layer between various third-party services (usually via API) and your application's code.
+
+It contains some conventions and utilities for making this easier. Think of it as a way to create simple wrappers on top of third-party APIs, but also a way to make those consistent across 'providers' of the same type.
+
+For example, say you support payments from multiple third-party services like Stripe or PayPal. In each of those services we'll need to handle customers, subscriptions, and payments. Here's how we could interface with that using ProviderKit:
+
+```ruby
+# customer 1 uses Stripe
+user = User.create(provider: :stripe, ...)
+user.provider.customers.get(id: user.customer_key) # => { id: "cus_Nff" }
+
+# customer 2 uses PayPal
+user2 = User.create(provider: :paypal)
+user.provider.customers.get(id: user.customer_key) # => { id: "abc-123" }
+```
+
+Then anywhere in your code where you have business logic that requires a customer the code is consistent, but each individual provider contains its custom code to deal with that provider's details. Here's what the 'get customer' logic could look like inside of a provider's configuration:
+
+```ruby
+module StripeProvider
+  class Customers
+    def get(id:)
+      stripe_customer = Stripe::Customer.retrieve(id)
+
+      {
+        id: stripe_customer.id,
+        # ... etc
+      }
+    end
+  end
+end
+```
+
+This library was originally developed for this exact use case, but we use it for a bunch of different provider types including linking multiple CRM tools, ecommerce providers, and many more.
+
+## Generator
+
+Use the generator to create a new provider:
+
+```bash
+rails g provider my_provider_name
+```
+
+## Capabilities
+
+Providers have 'capabilities' to determine what types of things they can do. Each provider registers those capabilities within the provider setup itself. For example, the `Customers` class above would likely be registered within the `StripeProvider` like this:
+
+```ruby
+module StripeProvider
+  class Provider
+
+    include ProviderKit::Capable
+
+    capable_of :subscriptions, with: Customers
+
+  end
+end
+```
+
+This registration offers some nice reflection methods, so you can determine at runtime which features a particular provider allows. For example, Stripe has a customers [search endpoint](https://docs.stripe.com/api/customers/search) but PayPal does not. So we can build the search feature into `StripeProvider`:
+
+```ruby
+module StripeProvider
+  class Customers
+    def search(query:)
+      customers = Stripe::Customer.search(query:)
+
+      customers.map do |customer|
+        {
+          id: customer.id,
+          name: customer.name,
+          # ...
+        }
+      end
+    end
+  end
+end
+```
+
+Then we can check it at runtime to make sure the provider is capable of this action:
+
+```ruby
+if user.provider.capable_of?(:customers, :search)
+  user.customers.search(query: 'john@example.com')
+else
+  []
+end
+```
+
+This is a primitive example but it's a powerful concept!
+
+## Credentials
+
+Rails credentials can be used within the context of a provider's capability methods. By convention, store each provider's credentials in this format:
+
+```yaml
+# rails credentials:edit
+
+providers:
+  provider_name_here:
+    secret_key: abc123
+
+  stripe:
+    secret_key: sk_1234
+```
+
+Then they can be used anywhere in a provider:
+
+```ruby
+module StripeProvider
+  class Customers
+    def get(id:)
+      # you probably should put this in an initializer instead
+      # so it doesn't need to be in every method,
+      # but it does work!
+      Stripe.api_key = credentials.secret_key
+
+      # ...
+    end
+  end
+end
+```
+
+## A Work In Progress
+
+This gem has been in production since 2019, so it's battle tested, but not very well spec-tested. It's an ongoing work in progress. If you find it helpful, go for it, I'm very open to contributions. But it's presented as-is, and probably won't be very actively maintained other than ensuring it works with new versions of Ruby and Rails.
+

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/lib/generators/provider/USAGE

@@ -0,0 +1,10 @@
+Description:
+    generate a new providerkit provider
+
+Example:
+    bin/rails generate provider CustomerIo
+
+    This will create:
+        app/providers/customer_io.rb
+        app/providers/customer_io/provider.rb
+        spec/providers/customer_io.rb

data/lib/generators/provider/provider_generator.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class ProviderGenerator < Rails::Generators::NamedBase
+
+  source_root File.expand_path("templates", __dir__)
+
+  argument :attributes, type: :array, default: [], banner: "capabilities"
+
+  class_option :type, type: :string, desc: "Assign a type to this provider"
+  class_option :types, type: :array, desc: "Assign multiple types to this provider"
+
+  def add_provider_initializer
+    if types.any?
+      insert_into_file "config/initializers/providers.rb", %Q(\nProviderKit.register :#{ provider_name }, class_name: "#{ class_name }::Provider", types: [ #{ types.map(&:inspect).join(", ") } ]\n)
+    else
+      insert_into_file "config/initializers/providers.rb", %Q(\nProviderKit.register :#{ provider_name }, class_name: "#{ class_name }::Provider"\n)
+    end
+  end
+
+  def create_provider_files
+    template "context.rb", File.join("app/providers/#{ singular_name }.rb")
+    template "provider.rb", File.join("app/providers/#{ singular_name }/provider.rb")
+
+    capabilities.each do |capability|
+      @capability = capability
+      template "capability.rb", File.join("app/providers/#{ singular_name }/capabilities/#{ capability.underscore }.rb")
+    end
+  end
+
+  def create_spec_file
+    template "spec.rb", File.join("spec/providers/#{ singular_name }_spec.rb")
+  end
+
+  private
+
+    attr_reader :capability
+
+    def capabilities
+      @capabilities ||= attributes_names.map do |c|
+        c.to_s.classify.pluralize
+      end.sort
+    end
+
+    def provider_name
+      singular_name.to_s.gsub("_", "")
+    end
+
+    def types
+      @types ||= begin
+        types = options[:type].presence || options[:types].presence || []
+        types = Array(types).flatten.compact.map(&:to_sym)
+      end
+    end
+
+end

data/lib/generators/provider/templates/capability.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module <%= class_name %>
+  module Capabilities
+    class <%= capability %>
+
+      # capability methods here
+
+    end
+  end
+end

data/lib/generators/provider/templates/context.rb.tt

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module <%= class_name %>
+
+  include ProviderKit::Context
+
+  # Change this if you want the provider name to be something else
+  def self.provider_key
+    :<%= provider_name %>
+  end
+
+end

data/lib/generators/provider/templates/provider.rb.tt

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module <%= class_name %>
+  class Provider
+
+    include ProviderKit::Capable
+
+    # Use credentials for the Current.account when set
+    # include AccountCredentiable
+<% capabilities.each do |capability| %>
+    capable_of :<%= capability.underscore %>, with: Capabilities::<%= capability %><% end %>
+  end
+end

data/lib/generators/provider/templates/spec.rb.tt

@@ -0,0 +1,34 @@
+require "rails_helper"
+
+RSpec.describe <%= class_name %> do
+
+  describe ".provider" do
+    it "is the provider" do
+      expect(<%= class_name %>.provider).to be_kind_of(<%= class_name %>::Provider)
+    end
+  end
+
+  describe ".provider_key" do
+    it "is :<%= provider_name %>" do
+      expect(<%= class_name %>.provider_key).to eq(:<%= provider_name %>)
+    end
+  end<% if types.any? %>
+
+  describe ".provider_types" do<% types.each do |type| %>
+    it "includes <%= type %>" do
+      expect(<%= class_name %>.provider_types).to include(:<%= type %>)
+      expect(ProviderKit.providers(type: :<%= type %>)).to include(<%= class_name %>::Provider)
+    end
+<% end %>
+  end<% end %><% capabilities.each do |capability| %>
+
+  context ".<%= capability.underscore %>" do
+    it "is a capability" do
+      expect(<%= class_name %>.capable_of?(:<%= capability.underscore %>)).to eq(true)
+      expect(<%= class_name %>.<%= capability.underscore %>).to be_kind_of(ProviderKit::Capability)
+    end
+
+    pending "fill in <%= class_name %>.<%= capability.underscore %> methods here"
+  end<% end %>
+
+end

data/lib/provider_kit/buildable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ProviderKit
+  # Designed to add provider utility methods to module
+  module Buildable
+
+    # ProviderKit.with(:stripe).subscriptions.get(id: "123")
+    def with(key_or_record)
+      provider = ProviderKit::Provider.new(key_or_record)
+      return nil unless provider.present?
+
+      provider.provider_instance
+    end
+
+  end
+end

data/lib/provider_kit/callbacks.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "active_support/callbacks"
+
+module ProviderKit
+  # Add callback behavior to services for logging and lifecycle checks
+  module Callbacks
+
+    extend  ActiveSupport::Concern
+    include ActiveSupport::Callbacks
+
+    included do
+      define_callbacks :perform
+    end
+
+    module ClassMethods
+
+      def after_perform(*filters, &blk)
+        set_callback(:perform, :after, *filters, &blk)
+      end
+
+      def around_perform(*filters, &blk)
+        set_callback(:perform, :around, *filters, &blk)
+      end
+
+      def before_perform(*filters, &blk)
+        set_callback(:perform, :before, *filters, &blk)
+      end
+
+    end
+
+  end
+end

data/lib/provider_kit/capability.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ProviderKit
+  class Capability
+
+    attr_reader :key, :provider
+
+    def initialize(key, target_klass, provider: nil, **options)
+      @key          = key
+      @target_klass = target_klass.to_s
+      @options      = options || {}
+      @provider     = provider
+      @context      = options.delete(:context)
+    end
+
+    def callable?(method_name)
+      callable_methods.include?(method_name.to_s)
+    end
+
+    def method_missing(method_name, *args, **kwargs)
+      case method_name.to_s
+      when /(.+)\?$/
+        call($1, *args, **kwargs) == true
+      else
+        call(method_name, *args, **kwargs)
+      end
+    end
+
+    def with_context(provider: @provider, **context)
+      Capability.new(
+        key,
+        @target_klass,
+        provider: provider.with_context(**context),
+        **options.merge(context:)
+      )
+    end
+
+    private
+
+      attr_reader :context
+      attr_reader :options
+
+      def call(method_name, *args, **kwargs)
+        call_target = target
+        return nil unless call_target
+        return nil unless callable?(method_name)
+
+        raw_response = call_target.public_send(method_name, *args, **kwargs)
+
+        case raw_response
+        when Hash
+          format_response_hash(raw_response)
+        when Array
+          raw_response.map { |h| format_response_hash(h) }
+        else
+          raw_response
+        end
+      end
+
+      # Creates a safe list of methods that can be called on the target
+      # Only those methods that were defined in the class are valid
+      def callable_methods
+        @callable_methods ||= begin
+          blacklist = Object.public_instance_methods
+          whitelist = target.class.public_instance_methods - blacklist
+
+          Set.new(whitelist.map(&:to_s))
+        end
+      end
+
+      def format_response_hash(raw_response)
+        return raw_response unless raw_response.is_a?(Hash)
+
+        klass = ProviderKit.config.capability_response_format
+        klass = Settings if klass == :object
+
+        if klass.is_a?(Class)
+          klass.new(raw_response)
+        else
+          raw_response
+        end
+      end
+
+      def prepare_target
+        klass = @target_klass
+
+        if String === klass
+          klass = klass.safe_constantize
+        end
+
+        unless klass.respond_to?(:new)
+          raise ProviderKit::InvalidCapability.new("Invalid capability class: #{ @target_klass }")
+        end
+
+        klass
+      end
+
+      def target_class
+        @target = nil unless Rails.application.config.cache_classes
+        @target ||= prepare_target
+      end
+
+      def target
+        unless target_class.included_modules.include?(CapabilityExtension)
+          target_class.send(:include, CapabilityExtension)
+        end
+
+        instance = if options.present?
+          target_class.new(options)
+        else
+          target_class.new
+        end
+
+        instance.instance_variable_set("@context", context)
+        instance.instance_variable_set("@provider", provider)
+
+        instance
+      end
+
+  end
+end

data/lib/provider_kit/capability_extension.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ProviderKit
+  module CapabilityExtension
+
+    extend ActiveSupport::Concern
+
+    private
+
+      attr_reader :provider
+      attr_reader :context
+
+      def config
+        provider&.config
+      end
+
+      def credentials
+        provider&.credentials
+      end
+
+  end
+end

data/lib/provider_kit/capable.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module ProviderKit
+  # Mixin for a model to make it have the provider methods
+  module Capable
+
+    extend ActiveSupport::Concern
+
+    included do
+      attr_accessor :context
+
+      mattr_accessor :capabilities
+      mattr_accessor :key
+
+      self.capabilities ||= {}
+
+      delegate :capable_of?, :perform_capability, to: self
+    end
+
+    def config
+      registration&.config
+    end
+
+    def credentials
+      registration&.credentials
+    end
+
+    def display_key
+      registration&.display_key
+    end
+
+    def method_missing(method_name, *args, **kwargs)
+      if capable_of?(method_name)
+        if kwargs.present?
+          perform_capability(method_name).with_context(provider: self, **kwargs)
+        else
+          perform_capability(method_name).with_context(provider: self, **(context || {}))
+        end
+      else
+        super
+      end
+    end
+
+    def provider_key
+      key
+    end
+
+    def with_context(**context)
+      self.context = context
+      self
+    end
+
+    class_methods do
+
+      def capable_of(namespace, with:, **options)
+        self.capabilities[namespace.to_sym] = Capability.new(namespace, with, **options)
+      end
+
+      def capable_of?(thing, method_name = nil)
+        return false unless self.capabilities.has_key?(thing.to_sym)
+        return true unless method_name.present?
+
+        capability = capabilities[thing]
+        return false unless capability
+
+        capability.callable?(method_name)
+      end
+
+      def method_missing(method_name, *args, **kwargs)
+        if capable_of?(method_name)
+          perform_capability(method_name, *args, **kwargs)
+        else
+          super
+        end
+      end
+
+      def perform_capability(name, **kwargs)
+        capabilities[name].with_context(provider:, **kwargs)
+      end
+
+      def provider
+        provider_key = key.presence || module_parent&.provider_key
+        ProviderKit.with(provider_key)
+      end
+
+      def with_context(**context)
+        instance = new()
+        instance.context = context
+        instance
+      end
+
+    end
+
+    private
+
+      def registration
+        @registration ||= ProviderKit.registrations[key]
+      end
+
+  end
+end

data/lib/provider_kit/context.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ProviderKit
+  # Designed to add provider utility methods to module
+  module Context
+
+    extend ActiveSupport::Concern
+
+    class_methods do
+
+      def capabilities
+        provider.capabilities.keys
+      end
+
+      def capable_of?(thing, method_name = nil)
+        provider.capable_of?(thing, method_name)
+      end
+
+      def config
+        provider_registration.config
+      end
+
+      def credentials
+        provider_registration.credentials
+      end
+
+      def method_missing(method_name, **kwargs)
+        if capable_of?(method_name)
+          return provider.perform_capability(method_name, **kwargs)
+        end
+
+        super
+      end
+
+      def provider
+        @provider ||= ProviderKit.with(provider_key)
+      end
+
+      def provider_key
+        @provider_key ||= self.to_s.underscore.gsub(/_provider$/, "").to_sym
+      end
+
+      def provider_registration
+        ProviderKit.registrations[provider_key]
+      end
+
+      def provider_types
+        provider_registration.types
+      end
+
+      def with_context(**kwargs)
+        provider.with_context(**kwargs)
+      end
+
+    end
+
+  end
+end