payflow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 97e6993b930178e108e6b1b805433af2216373def14db6abc037f44eab831b7d
+  data.tar.gz: 2de44cf55db703c4da5475a09d4bb872f35ac3745fe4bedf82b6813b5a90bb53
+SHA512:
+  metadata.gz: 3392f52cb1c7e66a99da3d003987e9750070dd6b8653ee807a74f277f55570d56a6e2f35504646b62df6d13f38e97e53296fb21539f60499c8c80207a81c4b88
+  data.tar.gz: 7d071c31cb70af1b1157c49c87c208ffab0f10ae2ad23563859eb20a87e8440e8f47af56517b605e5bc267ad4b63fc2e61202be0194519c88ba121aaacd90dc7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conexus Systems
+
+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,116 @@
+# Payflow
+
+Unified billing engine for Rails applications. Payflow abstracts subscription management and payment webhooks behind a provider-agnostic API.
+
+**MVP 0.1.0 providers:** Asaas (functional), Stripe (basic).
+
+Mercado Pago and Pagar.me are on the [roadmap](ROADMAP.md) — not included in this release.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "payflow"
+```
+
+Then run:
+
+```bash
+bundle install
+rails generate payflow:install
+rails db:migrate
+```
+
+Alternatively, copy engine migrations without the generator:
+
+```bash
+rails payflow:install:migrations
+rails db:migrate
+```
+
+## Setup
+
+Create `config/initializers/payflow.rb` (or use the generator output):
+
+```ruby
+Payflow.configure do |config|
+  config.provider = :asaas
+
+  config.asaas_api_key = ENV["ASAAS_API_KEY"]
+  config.asaas_webhook_token = ENV["ASAAS_WEBHOOK_TOKEN"]
+
+  config.stripe_api_key = ENV["STRIPE_API_KEY"]
+  config.stripe_webhook_secret = ENV["STRIPE_WEBHOOK_SECRET"]
+end
+```
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+mount Payflow::Engine => "/payflow"
+```
+
+## Usage
+
+Include `Payflow::Billable` in your host model:
+
+```ruby
+class Organization < ApplicationRecord
+  include Payflow::Billable
+end
+```
+
+Subscribe and manage billing:
+
+```ruby
+organization.subscribe!(plan: "premium", provider: Payflow.config.provider)
+organization.cancel_subscription!
+organization.active_subscription?
+organization.can_access_system?  # active and not overdue
+```
+
+## Webhooks
+
+Configure your payment providers to send webhooks to:
+
+| Provider | Endpoint |
+|----------|----------|
+| Asaas    | `POST /payflow/webhooks/asaas` |
+| Stripe   | `POST /payflow/webhooks/stripe` |
+
+Webhooks are verified, persisted as `Payflow::WebhookEvent` records, and processed asynchronously via `Payflow::WebhookJob` and Sidekiq (`:payflow` queue).
+
+## Architecture
+
+```
+Host App
+  └── Payflow::Engine (mounted at /payflow)
+        ├── Payflow::Billable concern
+        ├── Models: Subscription, Invoice, WebhookEvent
+        ├── Jobs: WebhookJob, OverdueAccountsJob
+        ├── Payflow::ProviderResolver
+        │     ├── Providers::Asaas::Provider
+        │     └── Providers::Stripe::Provider
+        └── Webhooks::Dispatcher
+```
+
+- **Billable** — polymorphic `billable` association on subscriptions
+- **ProviderResolver** — `Payflow::ProviderResolver.for(:asaas)` returns the provider client
+- **WebhookJob** — receives `provider` + `payload`, dispatches to update subscription/invoice state
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## Releasing
+
+See [RELEASE.md](RELEASE.md) for the RubyGems publishing checklist.
+
+## License
+
+MIT — Copyright (c) Conexus Systems. See [LICENSE](LICENSE).

data/app/controllers/payflow/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Payflow
+  class ApplicationController < ActionController::API
+  end
+end

data/app/controllers/payflow/webhooks/asaas_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Payflow
+  module Webhooks
+    class AsaasController < ApplicationController
+      def receive
+        verifier = SignatureVerifier.new(provider: :asaas, request: request)
+        return head :unauthorized unless verifier.valid?
+
+        payload = JSON.parse(request.raw_post)
+        WebhookJob.perform_later(provider: :asaas, payload: payload)
+        head :ok
+      rescue JSON::ParserError
+        head :bad_request
+      end
+    end
+  end
+end

data/app/controllers/payflow/webhooks/stripe_controller.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Payflow
+  module Webhooks
+    class StripeController < ApplicationController
+      def receive
+        verifier = SignatureVerifier.new(provider: :stripe, request: request)
+        return head :unauthorized unless verifier.valid?
+
+        payload = JSON.parse(request.raw_post)
+        WebhookJob.perform_later(provider: :stripe, payload: payload)
+        head :ok
+      rescue JSON::ParserError
+        head :bad_request
+      end
+    end
+  end
+end

data/app/jobs/payflow/application_job.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Payflow
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/payflow/overdue_accounts_job.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Payflow
+  class OverdueAccountsJob < ApplicationJob
+    queue_as :payflow
+
+    def perform
+      Subscription.active.find_each do |subscription|
+        latest_invoice = subscription.invoices.order(created_at: :desc).first
+        next unless latest_invoice&.overdue?
+
+        subscription.update!(status: :overdue)
+      end
+    end
+  end
+end

data/app/jobs/payflow/webhook_job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Payflow
+  class WebhookJob < ApplicationJob
+    queue_as :payflow
+
+    def perform(provider:, payload:)
+      event = WebhookEvent.create!(
+        provider: provider.to_s,
+        payload: payload,
+        status: :pending
+      )
+
+      Webhooks::Dispatcher.new(webhook_event: event).dispatch!
+      event.update!(status: :processed, processed_at: Time.current)
+    rescue StandardError
+      event&.update!(status: :failed)
+      raise
+    end
+  end
+end

data/app/models/payflow/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Payflow
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/payflow/invoice.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Payflow
+  class Invoice < ApplicationRecord
+    self.table_name = "payflow_invoices"
+
+    belongs_to :subscription, class_name: "Payflow::Subscription"
+
+    enum :status, {
+      pending: "pending",
+      paid: "paid",
+      overdue: "overdue",
+      cancelled: "cancelled"
+    }
+
+    validates :external_id, presence: true
+  end
+end

data/app/models/payflow/subscription.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Payflow
+  class Subscription < ApplicationRecord
+    self.table_name = "payflow_subscriptions"
+
+    belongs_to :billable, polymorphic: true
+    has_many :invoices, class_name: "Payflow::Invoice", dependent: :destroy
+
+    enum :status, {
+      pending: "pending",
+      active: "active",
+      overdue: "overdue",
+      cancelled: "cancelled",
+      expired: "expired"
+    }
+
+    validates :plan, :provider, :external_id, presence: true
+
+    def active?
+      status == "active"
+    end
+
+    def overdue?
+      status == "overdue"
+    end
+
+    def cancelled?
+      status == "cancelled"
+    end
+  end
+end

data/app/models/payflow/webhook_event.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Payflow
+  class WebhookEvent < ApplicationRecord
+    self.table_name = "payflow_webhook_events"
+
+    enum :status, {
+      pending: "pending",
+      processed: "processed",
+      failed: "failed"
+    }
+
+    validates :provider, :payload, presence: true
+
+    def processed?
+      status == "processed"
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+Payflow::Engine.routes.draw do
+  namespace :webhooks do
+    post "/asaas", to: "asaas#receive"
+    post "/stripe", to: "stripe#receive"
+  end
+end

data/db/migrate/20260617180001_create_payflow_subscriptions.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreatePayflowSubscriptions < ActiveRecord::Migration[7.0]
+  def change
+    create_table :payflow_subscriptions do |t|
+      t.references :billable, polymorphic: true, null: false, index: true
+      t.string :plan, null: false
+      t.string :provider, null: false
+      t.string :external_id, null: false
+      t.string :status, null: false, default: "pending"
+      t.datetime :cancelled_at
+
+      t.timestamps
+    end
+
+    add_index :payflow_subscriptions, :external_id, unique: true
+    add_index :payflow_subscriptions, :status
+  end
+end

data/db/migrate/20260617180002_create_payflow_invoices.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class CreatePayflowInvoices < ActiveRecord::Migration[7.0]
+  def change
+    create_table :payflow_invoices do |t|
+      t.references :subscription, null: false, foreign_key: { to_table: :payflow_subscriptions }
+      t.string :external_id, null: false
+      t.string :status, null: false, default: "pending"
+      t.decimal :amount, precision: 10, scale: 2
+      t.datetime :due_date
+
+      t.timestamps
+    end
+
+    add_index :payflow_invoices, :external_id, unique: true
+    add_index :payflow_invoices, :status
+  end
+end

data/db/migrate/20260617180003_create_payflow_webhook_events.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class CreatePayflowWebhookEvents < ActiveRecord::Migration[7.0]
+  def change
+    create_table :payflow_webhook_events do |t|
+      t.string :provider, null: false
+      t.json :payload, null: false, default: {}
+      t.string :status, null: false, default: "pending"
+      t.datetime :processed_at
+
+      t.timestamps
+    end
+
+    add_index :payflow_webhook_events, :status
+    add_index :payflow_webhook_events, :provider
+  end
+end

data/lib/generators/payflow/install_generator.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Payflow
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates Payflow initializer and database migrations"
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/payflow.rb"
+      end
+
+      def create_migrations
+        migration_template "migration_subscription.rb", "db/migrate/create_payflow_subscriptions.rb"
+        migration_template "migration_invoice.rb", "db/migrate/create_payflow_invoices.rb"
+        migration_template "migration_webhook_event.rb", "db/migrate/create_payflow_webhook_events.rb"
+      end
+
+      def show_readme
+        return unless behavior == :invoke
+
+        say "\nPayflow installed successfully!", :green
+        say "  Run `rails db:migrate` to apply the migrations."
+        say ""
+        say "Note: Payflow::Engine also appends engine migrations when the gem is loaded."
+        say "Use either this generator OR `rails payflow:install:migrations` — not both."
+      end
+
+      def self.next_migration_number(_dirname)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+    end
+  end
+end

data/lib/generators/payflow/templates/initializer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+Payflow.configure do |config|
+  config.default_provider = :asaas
+
+  config.asaas_api_key = ENV.fetch("ASAAS_API_KEY", nil)
+  config.asaas_webhook_token = ENV.fetch("ASAAS_WEBHOOK_TOKEN", nil)
+
+  config.stripe_api_key = ENV.fetch("STRIPE_API_KEY", nil)
+  config.stripe_webhook_secret = ENV.fetch("STRIPE_WEBHOOK_SECRET", nil)
+
+  # config.billable_class_name = "Organization"
+end

data/lib/generators/payflow/templates/migration_invoice.rb

@@ -0,0 +1,16 @@
+class CreatePayflowInvoices < ActiveRecord::Migration[7.0]
+  def change
+    create_table :payflow_invoices do |t|
+      t.references :subscription, null: false, foreign_key: { to_table: :payflow_subscriptions }
+      t.string :external_id, null: false
+      t.string :status, null: false, default: "pending"
+      t.decimal :amount, precision: 10, scale: 2
+      t.datetime :due_date
+
+      t.timestamps
+    end
+
+    add_index :payflow_invoices, :external_id, unique: true
+    add_index :payflow_invoices, :status
+  end
+end

data/lib/generators/payflow/templates/migration_subscription.rb

@@ -0,0 +1,17 @@
+class CreatePayflowSubscriptions < ActiveRecord::Migration[7.0]
+  def change
+    create_table :payflow_subscriptions do |t|
+      t.references :billable, polymorphic: true, null: false, index: true
+      t.string :plan, null: false
+      t.string :provider, null: false
+      t.string :external_id, null: false
+      t.string :status, null: false, default: "pending"
+      t.datetime :cancelled_at
+
+      t.timestamps
+    end
+
+    add_index :payflow_subscriptions, :external_id, unique: true
+    add_index :payflow_subscriptions, :status
+  end
+end

data/lib/generators/payflow/templates/migration_webhook_event.rb

@@ -0,0 +1,15 @@
+class CreatePayflowWebhookEvents < ActiveRecord::Migration[7.0]
+  def change
+    create_table :payflow_webhook_events do |t|
+      t.string :provider, null: false
+      t.json :payload, null: false, default: {}
+      t.string :status, null: false, default: "pending"
+      t.datetime :processed_at
+
+      t.timestamps
+    end
+
+    add_index :payflow_webhook_events, :status
+    add_index :payflow_webhook_events, :provider
+  end
+end

data/lib/payflow/billable.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Payflow
+  module Billable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :payflow_subscriptions,
+               as: :billable,
+               class_name: "Payflow::Subscription",
+               dependent: :destroy
+    end
+
+    def subscribe!(plan:, provider: Payflow.config.provider)
+      SubscriptionService.new(billable: self).subscribe!(plan: plan, provider: provider)
+    end
+
+    def cancel_subscription!
+      SubscriptionService.new(billable: self).cancel!
+    end
+
+    def subscription
+      payflow_subscriptions.order(created_at: :desc).first
+    end
+
+    def active_subscription?
+      subscription&.active?
+    end
+
+    def can_access_system?
+      active_subscription? && !subscription&.overdue?
+    end
+  end
+end

data/lib/payflow/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Payflow
+  class Configuration
+    attr_accessor :provider,
+                  :asaas_api_key,
+                  :asaas_webhook_token,
+                  :stripe_api_key,
+                  :stripe_webhook_secret,
+                  :billable_class_name
+
+    alias default_provider provider
+    alias default_provider= provider=
+
+    def initialize
+      @provider = :asaas
+      @billable_class_name = nil
+    end
+
+    def provider_credentials(provider_name)
+      case provider_name.to_sym
+      when :asaas
+        { api_key: asaas_api_key, webhook_token: asaas_webhook_token }
+      when :stripe
+        { api_key: stripe_api_key, webhook_secret: stripe_webhook_secret }
+      else
+        raise ProviderNotFoundError, "Unknown provider: #{provider_name}"
+      end
+    end
+  end
+end

data/lib/payflow/engine.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Payflow
+  class Engine < ::Rails::Engine
+    isolate_namespace Payflow
+
+    config.generators do |generator|
+      generator.test_framework :rspec
+    end
+
+    initializer "payflow.migrations" do |app|
+      unless app.root.to_s.match?(root.to_s)
+        config.paths["db/migrate"].expanded.each do |path|
+          app.config.paths["db/migrate"] << path
+        end
+      end
+    end
+
+    rake_tasks do
+      load root.join("lib/tasks/payflow_tasks.rake")
+    end
+  end
+end

data/lib/payflow/errors.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Payflow
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class ProviderError < Error; end
+  class ProviderNotFoundError < ProviderError; end
+  class InvalidWebhookError < Error; end
+  class SignatureVerificationError < InvalidWebhookError; end
+  class RecordNotFoundError < Error; end
+  class SubscriptionError < Error; end
+end

data/lib/payflow/events.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Payflow
+  module Events
+    SUBSCRIPTION_CREATED = "subscription.created"
+    INVOICE_PAID = "invoice.paid"
+    SUBSCRIPTION_CANCELED = "subscription.canceled"
+  end
+end

data/lib/payflow/provider_resolver.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Payflow
+  class ProviderResolver
+    REGISTRY = {
+      asaas: Providers::Asaas::Provider,
+      stripe: Providers::Stripe::Provider
+    }.freeze
+
+    def self.for(name)
+      key = name.to_sym
+      klass = REGISTRY[key]
+      raise ProviderNotFoundError, "Unknown provider: #{key}" unless klass
+
+      klass.new
+    end
+  end
+end

data/lib/payflow/providers/asaas/customer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Payflow
+  module Providers
+    module Asaas
+      class Customer
+        def initialize(client)
+          @client = client
+        end
+
+        def create(attrs)
+          { id: "cus_asaas_stub_#{SecureRandom.hex(4)}", provider: :asaas, email: attrs[:email], name: attrs[:name] }
+        end
+      end
+    end
+  end
+end