pay-lago 0.1.0

data/app/models/concerns/pay/lago/pay_extensions.rb

@@ -0,0 +1,15 @@
+module Pay
+  module Lago
+    module PayExtensions
+      extend ActiveSupport::Concern
+
+      included do
+        scope :lago, -> { joins(:customer).where(pay_customers: {processor: "lago"}) }
+      end
+
+      def lago?
+        customer.processor == "lago"
+      end
+    end
+  end
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "pay/lago"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/rails

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# This command will automatically be run when you run "rails" with Rails gems
+# installed from the root of your application.
+
+ENV["RAILS_ENV"] ||= "test"
+
+ENGINE_ROOT = File.expand_path('..', __dir__)
+ENGINE_PATH = File.expand_path('../lib/pay/lago/engine', __dir__)
+APP_PATH = File.expand_path('../test/dummy/config/application', __dir__)
+
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+
+require 'rails/all'
+require 'rails/engine/commands'

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Pay::Engine.routes.draw do
+  post "webhooks/lago", to: "pay/webhooks/lago#create" if Pay::Lago.enabled?
+end

data/docs/1_customers.md

@@ -0,0 +1,18 @@
+# Customers
+
+## Adding a Customer to Lago
+Calling the `customer` method on an existing Pay::Customer with the Lago processor will automatically create a Lago customer,
+with the external_id of the Pay::Customer's processor_id.
+
+If a processor_id is not set, it will use the [GlobalID](https://github.com/rails/globalid) of the Pay::Customer object
+as the external_id, and update processor_id to match.
+
+## Adding a Customer from Lago
+Creating a Pay::Customer with a matching processor_id to a Lago Customer's external_id, and giving them the Lago processor,
+will sync the two records when the `customer` method is called.
+
+## Updating a Lago Customer
+Lago Customers can be updated by calling `update_customer!` on the Pay::Customer object. The method takes a Hash of attributes to be
+changed, and returns a Lago Customer [OpenStruct](https://ruby-doc.org/current/stdlibs/ostruct/OpenStruct.html).
+
+See [Lago Customer API](https://docs.getlago.com/api-reference/customers/update) for valid attributes.

data/docs/2_charges.md

@@ -0,0 +1,72 @@
+# Charges
+
+Lago itself does not create charges. Rather, it creates invoices, and triggers a charge through another service if configured.
+
+Lago invoices will sync to Pay::Charges however, if the webhook is configured.
+
+## Charging a Customer
+Even though Lago doesn't necessarily support arbitrary charges, Pay implements somewhat of a workaround to maintain consistency.
+
+Using the `charge` method on the Pay::Customer will function as a normal charge, taking an amount, then "charging" the customer
+said amount.
+
+This creates a [One-off Invoice](https://docs.getlago.com/guide/one-off-invoices/create-one-off-invoices) on Lago.
+
+One-off Invoices require an add-on on Lago. Pay will automatically create a "default" add-on, and use that if no add-on is provided
+to the `charge` method.
+
+### Using your Own Add-ons
+While not explicitly necessary, **it is best practise to use your own add-ons**.
+
+Add-ons should provide meaningful information about the service to the invoice. Creating your own allows you to give it a nice name, and a description.
+
+Create add-ons through the [API](https://docs.getlago.com/api-reference/add-ons/create), or by using the Lago UI.
+
+You can provide your addon code to the `charge` method, for it to use that add-on instead.
+
+```ruby
+# Using an add-on with the charge method
+customer = Pay::Customer.find(1234)
+customer.charge(10_00, addon: "my-addon-code")
+```
+
+```ruby
+# If you would like to add some attributes, pass an options hash.
+# Note: currency must match the customer's currency.
+customer = Pay::Customer.find(1234)
+customer.charge(10_00, addon: "my-addon-code", options: { currency: "AUD" })
+```
+
+```ruby
+# If you would like to use the amount defined in the add-on instead,
+# set the charge amount to a falsey value.
+customer = Pay::Customer.find(1234)
+customer.charge(nil, addon: "my-addon-code")
+```
+
+## Updating a Lago Invoice
+Lago Invoices can be updated by calling `update_charge!` on the Pay::Charge object. The method takes a Hash of attributes to be
+changed, and returns a Lago Invoice [OpenStruct](https://ruby-doc.org/current/stdlibs/ostruct/OpenStruct.html).
+
+See [Lago Invoice API](https://docs.getlago.com/api-reference/invoices/update) for valid attributes.
+
+## Issuing a Refund
+**Refunding charges requires [Lago Premium!](https://www.getlago.com/pricing)**
+
+If you are self hosting Lago, its fairly trivial to override the premium license check. However, if you are using the cloud service, you will have to purchase Lago Premium. If your organisation has the means, please consider purchasing Lago Premium to support
+their open source development. Keep in mind: any changes to the source you make must be released as per the terms of AGPL.
+
+Lago creates refunds by issuing a [Credit Note](https://docs.getlago.com/guide/credit-notes).
+
+The `refund!` method on Pay::Charge will create a credit note automatically for the provided amount. If Lago Premium is not
+enabled, this method will raise Pay::Lago::Error.
+
+```ruby
+# Refund $10 of a charge, and provide a reason
+charge = Pay::Charge.find(1234)
+charge.refund!(10_00, reason: "order_cancellation")
+```
+
+You can pass a hash of attributes optionally to configure the credit note further.
+
+See [Lago Credit Note API](https://docs.getlago.com/api-reference/credit-notes/create) for valid attributes.

data/docs/3_subscriptions.md

@@ -0,0 +1,67 @@
+# Subscriptions
+
+## Adding a Subscription to a Customer
+
+Customers can be subscribed to a plan using the `subscribe` method on Pay::Customer. Subscriptions should be given a name,
+and must tie to an existing plan in Lago.
+
+Plans can be created using the [Lago API](https://docs.getlago.com/api-reference/plans/create), or through the UI.
+
+```ruby
+# Subscribe a customer to the plan with code "my-plan"
+customer = Pay::Customer.find(1234)
+customer.subscribe(name: "My Subscription", plan: "my-plan")
+```
+
+```ruby
+# Subscribe a customer to the plan, and provide additional attributes
+customer = Pay::Customer.find(1234)
+customer.subscribe(name: "My Subscription", plan: "my-plan", status: "active", billing_time: "calendar")
+```
+
+See [Lago Subscription API](https://docs.getlago.com/api-reference/subscriptions/assign-plan) for valid attributes.
+
+## Cancelling a Subscription
+
+Subscriptions can be cancelled using the `cancel` method on Pay::Subscription.
+
+This will terminate the subscription in Lago, and a credit note will automatically be issued by Lago refunding the customer
+for their remaining time on the subscription. See [Terminate a subscription](https://docs.getlago.com/guide/subscriptions/terminate-subscription).
+
+```ruby
+# Cancel a Subscription
+subscription = Pay::Subscription.find(1234)
+subscription.cancel
+```
+
+```ruby
+# Cancel a Pending Subscription
+subscription = Pay::Subscription.find(1234)
+subscription.cancel(status: "pending")
+```
+
+## Changing a Subscription's Plan
+
+You can change the plan of a subscription using the `swap` method on Pay::Subscription.
+
+Given a plan code, this method will switch the plan over at time of the next invoice.
+
+```ruby
+# Switch a Subscription to "my-second-plan"
+subscription = Pay::Subscription.find(1234)
+subscription.swap("my-second-plan")
+```
+
+```ruby
+# Switch a Subscription to "my-second-plan", and update some attributes
+subscription = Pay::Subscription.find(1234)
+subscription.swap("my-second-plan", name: "My Updated Subscription")
+```
+
+See [Lago Subscription API](https://docs.getlago.com/api-reference/subscriptions/assign-plan) for valid attributes.
+
+## Trials, Pausing, Quantity etc.
+
+Lago does not implement trial periods, pause/resume, quantities etc.
+
+Pay will raise Pay::Lago::Error when attempting to use methods that would usually perform these functions.

data/docs/4_webhooks.md

@@ -0,0 +1,66 @@
+# Webhooks
+
+In order for Pay to automatically sync charges and subscriptions, Lago must be configured to point to Pay's Lago endpoint.
+
+## Adding the Webhook to Lago
+You can add webhooks using the [Lago UI](https://docs.getlago.com/guide/webhooks). Pay's default webhook endpoint for Lago
+is `/pay/webhooks/lago` (`/pay` is replaced by the mountpoint of the Pay engine). Webhooks should use JWT.
+
+Alternatively you can use the helper method to add the webhook to Lago.
+
+```ruby
+# Create a webhook endpoint in Lago for the Pay gem.
+Pay::Lago.create_webhook!("https://mypayinstance.example")
+```
+
+```ruby
+# Create a webhook endpoint, where you have mounted Pay at a different path (eg. "admin/pay").
+# Not necessary unless you have disabled "automount_routes".
+Pay::Lago.create_webhook!("https://mypayinstance.example", "/admin/pay")
+```
+
+Please note: the given string must be a valid HTTP/S URL. Pay will automatically set the path of the URL to be the correct path,
+so you only need to provide the root URL.
+
+## List of Events Pay Implements
+
+Pay doesn't listen to every event, because not all are relevant to the operation of the gem. You can find a full list
+of events [here](https://docs.getlago.com/api-reference/webhooks/messages).
+
+### Customer Payment Provider Created
+`customer.payment_provider_created`
+
+When this event is triggered, Pay updates the respective Pay::Customer with the new payment provider information.
+
+### Invoice Created
+`invoice.created`
+
+When this event is triggered, Pay creates or updates a Pay::Charge for the given Invoice, and sends a reciept if so configured.
+
+### Invoice Drafted
+`invoice.drafted`
+
+When this event is triggered, Pay creates or updates a Pay::Charge for the given Invoice, but doesn't send a reciept.
+
+### Invoice One Off Created
+`invoice.one_off_created`
+
+Currently handles the same as [Invoice Created](#invoice-created).
+
+### Invoice Payment Status Updated
+`invoice.payment_status_updated`
+
+When this event is triggered, it will update the payment status in the corresponding charge's data.
+
+Does nothing if no matching charge is found.
+
+### Subscription Started
+`subscription.started`
+
+Creates or updates a Pay::Subscription with the recieved information.
+
+### Subscription Terminated
+`subscription.terminated`
+
+Currently handles the same as [Subscription Started](#subscription-started). However, the information provided by Lago will
+cause the subscription to be considered terminated.

data/lib/pay/lago/attributes.rb

@@ -0,0 +1,24 @@
+module Pay
+  module Lago
+    module Attributes
+      extend ActiveSupport::Concern
+
+      module CustomerExtension
+        extend ActiveSupport::Concern
+
+        included do
+          cattr_accessor :pay_lago_customer_attributes
+        end
+      end
+
+      class_methods do
+        def pay_customer(options = {})
+          include CustomerExtension
+
+          self.pay_lago_customer_attributes = options[:lago_attributes]
+          super
+        end
+      end
+    end
+  end
+end

data/lib/pay/lago/billable.rb

@@ -0,0 +1,148 @@
+module Pay
+  module Lago
+    class Billable
+      require "uri"
+
+      attr_reader :pay_customer
+
+      delegate :processor_id,
+        :processor_id?,
+        :email,
+        :customer_name,
+        :card_token,
+        to: :pay_customer
+
+      def initialize(pay_customer)
+        @pay_customer = pay_customer
+      end
+
+      def pay_external_id
+        processor_id || pay_customer.to_gid.to_s
+      end
+
+      # Returns a hash of attributes for the Lago::Customer object
+      def customer_attributes(external_id)
+        owner = pay_customer.owner
+
+        attributes = case owner.class.pay_lago_customer_attributes
+        when Symbol
+          owner.send(owner.class.pay_lago_customer_attributes, pay_customer)
+        when Proc
+          owner.class.pay_lago_customer_attributes.call(pay_customer)
+        end
+
+        # Guard against attributes being returned nil
+        attributes ||= {}
+
+        {external_id: external_id, email: email, name: customer_name}.merge(attributes)
+      end
+
+      def customer
+        begin
+          lago_customer = Lago.client.customers.get(uri_escape(pay_external_id))
+        rescue ::Lago::Api::HttpError
+          lago_customer = Lago.client.customers.create(customer_attributes(pay_external_id))
+        end
+        pay_customer.update!(processor_id: lago_customer.external_id) unless processor_id == lago_customer.external_id
+        lago_customer
+      rescue ::Lago::Api::HttpError => e
+        raise Pay::Lago::Error, e
+      end
+
+      def update_customer!(**attributes)
+        new_attributes = Lago.openstruct_to_h(customer).except(:lago_id)
+        Lago.client.customers.create(
+          new_attributes.merge(attributes.except(:external_id))
+        )
+      end
+
+      def charge(amount = nil, addon: nil, options: {})
+        lago_customer = customer
+        lago_addon = addon.is_a?(String) ? Lago.client.add_ons.get(addon) : pay_default_addon
+        amount ||= lago_addon.amount_cents
+
+        attributes = {
+          external_customer_id: processor_id,
+          currency: options[:currency] || lago_customer.currency,
+          fees: [
+            {
+              add_on_code: lago_addon.code,
+              unit_amount_cents: amount
+            }.merge(options.except(:amount_cents, :add_on_code, :currency))
+          ]
+        }
+
+        invoice = Lago.client.invoices.create(attributes)
+        Pay::Lago::Charge.sync(invoice.lago_id, object: invoice)
+      rescue ::Lago::Api::HttpError => e
+        raise Pay::Lago::Error, e
+      end
+
+      def subscribe(name: Pay.default_product_name, plan: Pay.default_plan_name, **options)
+        # Make to generate a processor_id
+        lago_customer = customer
+        pay_subscription = create_placeholder_subscription(name, plan)
+        external_id = pay_subscription.to_gid.to_s
+
+        attributes = options.merge(
+          external_customer_id: lago_customer.external_id,
+          name: name, external_id: external_id, plan_code: plan
+        )
+
+        begin
+          subscription = Lago.client.subscriptions.create(attributes)
+        rescue ::Lago::Api::HttpError
+          pay_subscription.destroy!
+          raise Pay::Lago::Error, e
+        end
+
+        pay_subscription.update!(processor_id: external_id)
+        Pay::Lago::Subscription.sync(lago_customer.external_id, external_id, object: subscription)
+      end
+
+      def add_payment_method(_token = nil, default: true)
+        Pay::Lago::PaymentMethod.sync(pay_customer: pay_customer)
+      end
+
+      def processor_subscription(subscription_id, options = {})
+        Pay::Lago::Subscription.get_subscription(processor_id, subscription_id)
+      end
+
+      def trial_end_date(subscription)
+        raise Pay::Lago::Error.new("Lago subscriptions do not implement trials.")
+      end
+
+      private
+
+      def create_placeholder_subscription(name, plan)
+        pay_customer.subscriptions.create!(
+          processor_id: NanoId.generate,
+          name: name,
+          processor_plan: plan,
+          quantity: 0,
+          status: "incomplete"
+        )
+      end
+
+      def pay_default_addon
+        begin
+          Lago.client.add_ons.get("pay_default_addon")
+        rescue ::Lago::Api::HttpError
+          Lago.client.add_ons.create(
+            name: "Default Charge",
+            code: "pay_default_addon",
+            amount_cents: 100,
+            amount_currency: "USD"
+          )
+        end
+      rescue ::Lago::Api::HttpError => e
+        raise Pay::Lago::Error, e
+      end
+
+      def uri_escape(uri)
+        return "" unless uri.is_a? String
+        URI.encode_www_form_component uri
+      end
+    end
+  end
+end

data/lib/pay/lago/charge.rb

@@ -0,0 +1,82 @@
+module Pay
+  module Lago
+    class Charge
+      attr_reader :pay_charge
+
+      delegate :processor_id, :owner, to: :pay_charge
+
+      def self.sync(charge_id, object: nil, try: 0, retries: 1)
+        object ||= Lago.client.invoices.get(charge_id)
+
+        pay_customer = Pay::Customer.find_by(processor: :lago, processor_id: object.customer.external_id)
+        if pay_customer.blank?
+          Rails.logger.debug "Pay::Customer #{object.customer} is not in the database while syncing Lago Invoice #{object.lago_id}"
+          return
+        end
+
+        attrs = {
+          processor_id: object.lago_id,
+          amount: object.total_amount_cents,
+          data: Lago.openstruct_to_h(object)
+        }
+
+        if object.subscriptions.present?
+          subscription = object.subscriptions.first
+          attrs[:subscription] = pay_customer.subscriptions.find_by(processor_id: subscription.try(:lago_id))
+        end
+
+        # Update or create the charge
+        if (pay_charge = pay_customer.charges.find_by(processor_id: charge_id))
+          pay_charge.with_lock do
+            pay_charge.update!(attrs)
+          end
+          pay_charge
+        else
+          pay_customer.charges.create!(attrs)
+        end
+      rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique
+        try += 1
+        if try <= retries
+          sleep 0.1
+          retry
+        else
+          raise
+        end
+      end
+
+      def initialize(pay_charge)
+        @pay_charge = pay_charge
+      end
+
+      def charge
+        Lago.client.invoices.get(processor_id)
+      rescue ::Lago::Api::HttpError => e
+        raise Pay::Lago::Error, e
+      end
+
+      def update_charge!(**attributes)
+        Lago.client.invoices.update({metadata: []}.merge(attributes), charge.lago_id)
+      rescue ::Lago::Api::HttpError => e
+        raise Pay::Lago::Error, e
+      end
+
+      def refund!(amount_to_refund, **options)
+        attributes = {
+          refund_amount_cents: amount_to_refund,
+          invoice_id: processor_id,
+          items: [{fee_id: charge.fees.first.try(:lago_id), amount_cents: amount_to_refund}]
+        }
+        begin
+          Lago.client.credit_notes.create(options.merge(attributes))
+        rescue ::Lago::Api::HttpError => e
+          if e.error_code == 403
+            raise Pay::Lago::Error.new("Creating a credit note requires Lago Premium.")
+          else
+            raise Pay::Lago::Error, e
+          end
+        end
+        pay_charge.update!(amount_refunded: pay_charge.amount_refunded.to_i + amount_to_refund)
+      end
+    end
+  end
+end

data/lib/pay/lago/engine.rb

@@ -0,0 +1,27 @@
+module Pay
+  module Lago
+    class Engine < ::Rails::Engine
+      engine_name "pay_lago"
+
+      initializer "pay_lago.processors" do |app|
+        ActiveSupport.on_load(:active_record) do
+          include Pay::Lago::Attributes
+        end
+      end
+
+      config.before_initialize do
+        Pay::Lago.configure_webhooks if Pay::Lago.enabled?
+      end
+
+      config.to_prepare do
+        # Include Concerns
+        Pay::Customer.include Pay::Lago::PayCustomerExtensions
+        Pay::Charge.include Pay::Lago::PayExtensions
+        Pay::Subscription.include Pay::Lago::PayExtensions
+
+        # Prepend Pay::Lago extensions
+        Pay::Webhook.prepend Pay::Lago::WebhookExtensions
+      end
+    end
+  end
+end

data/lib/pay/lago/error.rb

@@ -0,0 +1,9 @@
+module Pay
+  module Lago
+    class Error < Pay::Error
+      def message
+        cause.try(:message) || to_s
+      end
+    end
+  end
+end

data/lib/pay/lago/payment_method.rb

@@ -0,0 +1,37 @@
+module Pay
+  module Lago
+    class PaymentMethod
+      attr_reader :pay_payment_method
+
+      delegate :customer, :processor_id, to: :pay_payment_method
+
+      # Lago doesn't provide PaymentMethod IDs, so we have to lookup via the Customer
+      def self.sync(pay_customer:)
+        payment_method = pay_customer.default_payment_method || pay_customer.build_default_payment_method
+        lago_customer = pay_customer.customer
+        payment_data = lago_customer.billing_configuration
+
+        payment_method_attr = {
+          processor_id: payment_data.provider_customer_id || NanoId.generate,
+          type: "card",
+          data: Lago.openstruct_to_h(payment_data)
+        }
+
+        payment_method.update!(payment_method_attr)
+        payment_method
+      rescue ::Lago::Api::HttpError => e
+        raise Pay::Lago::Error, e
+      end
+
+      def initialize(pay_payment_method)
+        @pay_payment_method = pay_payment_method
+      end
+
+      def make_default!
+      end
+
+      def detach
+      end
+    end
+  end
+end