RubyGems - sanwo - Versions diffs - 0.1.0 - Mend

sanwo 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2372fbf0134b38a2c9714b59a26767a1cae3f2464866cc0a5f5bf5069716285a
+  data.tar.gz: df0a25fbfac2b94d6d5db1177c44e6b8e7501c0d71fd3ddf224df38dfc55a1b0
+SHA512:
+  metadata.gz: 1f4c77a24307b071a8b1158ece4ded02a608a477f25e25d21b70d9c7167fdb9758255876919729484447e33599d0a0b2df9958379fc2e4631183872dd96f817f
+  data.tar.gz: 39cebb9e678e27f15c14884dacd2fa4cf0ae59f6cd8b8056805debe61d46ba1503652117edd2dcdc4b4266dde78283da348dc15901234ffa395612972901dd68

data/README.md ADDED Viewed

@@ -0,0 +1,99 @@
+# Sanwo Ruby SDK
+Add [Sanwo](https://sanwohq.com) payments to your Ruby application — Rails or standalone.
+> **Full documentation at [docs.sanwo.dev](https://docs.sanwo.dev/server/ruby/)** — guides, examples, and API reference for every SDK and provider.
+## Install
+```bash
+gem install sanwo
+```
+Or add to your Gemfile:
+```ruby
+gem "sanwo"
+```
+## Standalone Usage
+```ruby
+require "sanwo"
+client = Sanwo::Client.new(
+  provider: "paystack",
+  public_key: "pk_test_xxx"
+)
+# Include the CDN script tag in your <head>
+client.render_script
+# => '<script src="https://cdn.jsdelivr.net/npm/@sanwohq/embed/dist/sanwo.global.js"></script>'
+# Render a checkout button (amount in minor units)
+client.render_checkout(
+  amount: 50000,
+  email: "user@example.com",
+  description: "Premium plan",
+  button_text: "Subscribe"
+)
+```
+## Rails Setup
+Add the gem to your Gemfile and configure an initializer:
+```ruby
+# config/initializers/sanwo.rb
+Rails.application.config.sanwo_client = Sanwo::Client.new(
+  provider: "paystack",
+  public_key: ENV["PAYSTACK_PUBLIC_KEY"],
+  currency: "NGN"
+)
+```
+Then use the view helpers in your templates:
+```erb
+<head>
+  <%= sanwo_scripts %>
+</head>
+<body>
+  <%= sanwo_checkout(amount: 50000, email: current_user.email) %>
+</body>
+```
+### Custom Amount Input
+```erb
+<%= sanwo_custom_amount(
+  email: current_user.email,
+  min_amount: 10000,
+  max_amount: 1000000,
+  placeholder: "Enter donation amount"
+) %>
+```
+## Custom Provider Template
+```ruby
+client = Sanwo::Client.new(
+  provider: "custom",
+  public_key: "pk_xxx",
+  template_url: "https://example.com/my-template.html"
+)
+```
+Or with an inline template:
+```ruby
+client = Sanwo::Client.new(
+  provider: "custom",
+  public_key: "pk_xxx",
+  template: "<div>Your custom checkout HTML</div>"
+)
+```
+## License
+Apache 2.0 — see [LICENSE](LICENSE) for details.

data/lib/sanwo/client.rb ADDED Viewed

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+require "erb"
+require "json"
+require "securerandom"
+module Sanwo
+  # Server-side HTML generator for Sanwo checkout.
+  #
+  # This class does NOT make any HTTP requests. It produces front-end markup
+  # that delegates to the Sanwo embed script loaded from the CDN.
+  class Client
+    CDN_URL = "https://cdn.jsdelivr.net/npm/@sanwohq/embed/dist/sanwo.global.js"
+    attr_reader :provider, :public_key, :currency, :debug, :template_url, :template
+    # @param provider [String] payment provider identifier (see {Sanwo::Providers})
+    # @param public_key [String] your provider's public / publishable key
+    # @param currency [String] ISO 4217 currency code (default: "NGN")
+    # @param debug [Boolean] enable browser console logging (default: false)
+    # @param template_url [String, nil] URL to fetch a custom template from
+    # @param template [String, nil] inline HTML template string
+    # @raise [ArgumentError] if public_key is blank or custom provider lacks template
+    def initialize(provider:, public_key:, currency: "NGN", debug: false, template_url: nil, template: nil)
+      raise ArgumentError, "public_key is required" if public_key.nil? || public_key.to_s.strip.empty?
+      @provider     = Providers.resolve(provider)
+      @public_key   = public_key
+      @currency     = currency
+      @debug        = debug
+      @template_url = template_url
+      @template     = template
+      if @provider == Providers::CUSTOM && @template.nil? && @template_url.nil?
+        raise ArgumentError, 'Custom provider requires a "template" or "template_url"'
+      end
+    end
+    # Return a <script> tag that loads the Sanwo embed script from the CDN.
+    #
+    # @return [String] HTML script tag
+    def render_script
+      html = %(<script src="#{h(CDN_URL)}"></script>)
+      mark_safe(html)
+    end
+    # Render a complete checkout button with inline JavaScript.
+    #
+    # The returned HTML contains a <button> element and an inline <script>
+    # that uses Sanwo.create() and .checkout() to initiate payment on click.
+    #
+    # All amounts are in minor units (kobo / cents).
+    #
+    # @param amount [Integer] amount in minor units
+    # @param email [String] customer email address
+    # @param description [String, nil] human-readable payment description
+    # @param reference [String, nil] unique transaction reference (auto-generated if omitted)
+    # @param currency [String, nil] override the default currency
+    # @param button_text [String] label displayed on the button
+    # @param button_class [String] CSS class(es) applied to the button
+    # @param first_name [String, nil] customer first name
+    # @param last_name [String, nil] customer last name
+    # @param phone [String, nil] customer phone number
+    # @param callback [String, nil] name of a global JS function to call on completion
+    # @return [String] HTML string
+    def render_checkout(amount:, email:, description: nil, reference: nil, currency: nil,
+                        button_text: "Pay Now", button_class: "sanwo-button",
+                        first_name: nil, last_name: nil, phone: nil, callback: nil)
+      validate_checkout(amount, email)
+      ref    = reference || "sanwo_#{SecureRandom.hex(8)}"
+      cur    = currency || @currency
+      btn_id = "sanwo-btn-#{SecureRandom.hex(4)}"
+      customer = { "email" => email }
+      customer["firstName"] = first_name if first_name
+      customer["lastName"]  = last_name  if last_name
+      customer["phone"]     = phone      if phone
+      checkout_opts = {
+        "amount"    => amount,
+        "currency"  => cur,
+        "reference" => ref,
+        "customer"  => customer,
+      }
+      checkout_opts["description"] = description if description
+      config_json = JSON.generate(build_create_config)
+      opts_json   = JSON.generate(checkout_opts)
+      debug_flag  = @debug ? "true" : "false"
+      callback_js = ""
+      if callback
+        cb = h(callback)
+        callback_js = "if (typeof window['#{cb}'] === 'function') { window['#{cb}'](result); }"
+      end
+      html = <<~HTML
+        <button type="button" class="#{h(button_class)}" id="#{btn_id}">#{h(button_text)}</button>
+        <script>
+        (function() {
+          var btn = document.getElementById('#{btn_id}');
+          btn.addEventListener('click', function() {
+            if (btn.disabled) return;
+            btn.disabled = true;
+            var sanwo = Sanwo.create(#{config_json});
+            if (#{debug_flag}) console.log('[Sanwo] Starting checkout', #{opts_json});
+            sanwo.checkout(#{opts_json}).then(function(result) {
+              btn.disabled = false;
+              if (#{debug_flag}) console.log('[Sanwo] Result', result);
+              #{callback_js}
+            }).catch(function(err) {
+              btn.disabled = false;
+              console.error('[Sanwo] Checkout error:', err);
+            });
+          });
+        })();
+        </script>
+      HTML
+      mark_safe(html)
+    end
+    # Render a custom-amount checkout widget.
+    #
+    # Produces an <input> for the amount (displayed in major units) and a pay
+    # button. When submitted, the value is converted to minor units automatically.
+    #
+    # @param email [String, nil] customer email (if omitted, the widget prompts the user)
+    # @param currency [String, nil] override the default currency
+    # @param button_text [String] label for the pay button
+    # @param placeholder [String] placeholder text for the amount input
+    # @param min_amount [Integer, nil] minimum amount in minor units
+    # @param max_amount [Integer, nil] maximum amount in minor units
+    # @param description [String, nil] human-readable payment description
+    # @param first_name [String, nil] customer first name
+    # @param last_name [String, nil] customer last name
+    # @param phone [String, nil] customer phone number
+    # @param callback [String, nil] name of a global JS function to call on completion
+    # @return [String] HTML string
+    def render_custom_amount(email: nil, currency: nil, button_text: "Pay Now",
+                             placeholder: "Enter amount", min_amount: nil, max_amount: nil,
+                             description: nil, first_name: nil, last_name: nil,
+                             phone: nil, callback: nil)
+      cur       = currency || @currency
+      widget_id = "sanwo-custom-#{SecureRandom.hex(4)}"
+      config_json = JSON.generate(build_create_config)
+      debug_flag  = @debug ? "true" : "false"
+      # Build data attributes
+      attrs = [
+        %(data-sanwo-provider="#{h(@provider)}"),
+        %(data-sanwo-key="#{h(@public_key)}"),
+        %(data-sanwo-currency="#{h(cur)}"),
+        %(data-sanwo-custom-amount="true"),
+        %(data-sanwo-button-text="#{h(button_text)}"),
+        %(data-sanwo-placeholder="#{h(placeholder)}"),
+      ]
+      attrs << %(data-sanwo-debug="true") if @debug
+      attrs << %(data-sanwo-template-url="#{h(@template_url)}") if @template_url
+      attrs << %(data-sanwo-template="#{h(@template)}") if @template
+      attrs << %(data-sanwo-email="#{h(email)}") if email
+      attrs << %(data-sanwo-min-amount="#{min_amount}") unless min_amount.nil?
+      attrs << %(data-sanwo-max-amount="#{max_amount}") unless max_amount.nil?
+      attrs << %(data-sanwo-description="#{h(description)}") if description
+      attrs << %(data-sanwo-first-name="#{h(first_name)}") if first_name
+      attrs << %(data-sanwo-last-name="#{h(last_name)}") if last_name
+      attrs << %(data-sanwo-phone="#{h(phone)}") if phone
+      attrs << %(data-sanwo-callback="#{h(callback)}") if callback
+      attrs_str = attrs.join(" ")
+      # Build customer JS object
+      customer_fields = []
+      customer_fields << "email: #{JSON.generate(email)}" if email
+      customer_fields << "firstName: #{JSON.generate(first_name)}" if first_name
+      customer_fields << "lastName: #{JSON.generate(last_name)}" if last_name
+      customer_fields << "phone: #{JSON.generate(phone)}" if phone
+      customer_js = if customer_fields.any?
+                      "{ #{customer_fields.join(', ')} }"
+                    else
+                      "{ email: emailInput.value }"
+                    end
+      callback_js = ""
+      if callback
+        cb = h(callback)
+        callback_js = "if (typeof window['#{cb}'] === 'function') { window['#{cb}'](result); }"
+      end
+      min_check = ""
+      unless min_amount.nil?
+        min_major = min_amount / 100.0
+        min_check = "if (amountMinor < #{min_amount}) { alert('Minimum amount is #{format('%.2f', min_major)}'); return; }\n      "
+      end
+      max_check = ""
+      unless max_amount.nil?
+        max_major = max_amount / 100.0
+        max_check = "if (amountMinor > #{max_amount}) { alert('Maximum amount is #{format('%.2f', max_major)}'); return; }\n      "
+      end
+      email_input_html = ""
+      email_input_js   = ""
+      unless email
+        email_input_html = %(\n  <input type="email" id="#{widget_id}-email" placeholder="Email address" required style="display:block;margin-bottom:8px;padding:8px;width:100%;box-sizing:border-box;" />)
+        email_input_js = "var emailInput = document.getElementById('#{widget_id}-email');\n      "
+      end
+      description_js = ""
+      description_js = "    opts.description = #{JSON.generate(description)};\n" if description
+      html = <<~HTML.chomp
+        <div id="#{widget_id}" #{attrs_str}>#{email_input_html}
+          <input type="number" id="#{widget_id}-amount" placeholder="#{h(placeholder)}" step="0.01" min="0" required style="display:block;margin-bottom:8px;padding:8px;width:100%;box-sizing:border-box;" />
+          <button type="button" id="#{widget_id}-btn" class="sanwo-button">#{h(button_text)}</button>
+        </div>
+        <script>
+        (function() {
+          var btn = document.getElementById('#{widget_id}-btn');
+          var amountInput = document.getElementById('#{widget_id}-amount');
+          #{email_input_js}  btn.addEventListener('click', function() {
+            var amountMajor = parseFloat(amountInput.value);
+            if (isNaN(amountMajor) || amountMajor <= 0) { alert('Please enter a valid amount.'); return; }
+            var amountMinor = Math.round(amountMajor * 100);
+            #{min_check}#{max_check}    btn.disabled = true;
+            var sanwo = Sanwo.create(#{config_json});
+            var opts = {
+              amount: amountMinor,
+              currency: #{JSON.generate(cur)},
+              customer: #{customer_js}
+            };
+        #{description_js}    if (#{debug_flag}) console.log('[Sanwo] Starting checkout', opts);
+            sanwo.checkout(opts).then(function(result) {
+              btn.disabled = false;
+              if (#{debug_flag}) console.log('[Sanwo] Result', result);
+              #{callback_js}
+            }).catch(function(err) {
+              btn.disabled = false;
+              console.error('[Sanwo] Checkout error:', err);
+            });
+          });
+        })();
+        </script>
+      HTML
+      mark_safe(html)
+    end
+    # Return the current configuration as a plain hash.
+    #
+    # @return [Hash]
+    def config
+      cfg = {
+        provider: @provider,
+        public_key: @public_key,
+        currency: @currency,
+        debug: @debug,
+        script_url: CDN_URL,
+      }
+      cfg[:template_url] = @template_url if @template_url
+      cfg[:template]     = @template     if @template
+      cfg
+    end
+    private
+    # Build the config hash passed to Sanwo.create() in JavaScript.
+    #
+    # @return [Hash]
+    def build_create_config
+      cfg = {
+        "provider"  => @provider,
+        "publicKey" => @public_key,
+      }
+      cfg["templateUrl"] = @template_url if @template_url
+      cfg["template"]    = @template     if @template
+      cfg
+    end
+    # Validate checkout parameters.
+    #
+    # @raise [ArgumentError] if amount or email are invalid
+    def validate_checkout(amount, email)
+      unless amount.is_a?(Integer) && amount.positive?
+        raise ArgumentError, "amount must be a positive integer (in minor units)"
+      end
+      if email.nil? || !email.include?("@")
+        raise ArgumentError, "A valid email address is required"
+      end
+    end
+    # HTML-escape a string.
+    #
+    # @param value [String]
+    # @return [String]
+    def h(value)
+      ERB::Util.html_escape(value.to_s)
+    end
+    # Mark a string as HTML-safe if ActiveSupport is available.
+    #
+    # @param html [String]
+    # @return [String]
+    def mark_safe(html)
+      if html.respond_to?(:html_safe)
+        html.html_safe
+      else
+        html
+      end
+    end
+  end
+end

data/lib/sanwo/providers.rb ADDED Viewed

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Sanwo
+  module Providers
+    PAYSTACK     = "paystack"
+    FLUTTERWAVE  = "flutterwave"
+    RAZORPAY     = "razorpay"
+    MONNIFY      = "monnify"
+    INTERSWITCH  = "interswitch"
+    CUSTOM       = "custom"
+    VALID_PROVIDERS = [
+      PAYSTACK,
+      FLUTTERWAVE,
+      RAZORPAY,
+      MONNIFY,
+      INTERSWITCH,
+      CUSTOM,
+    ].freeze
+    # Resolve and validate a provider string.
+    #
+    # @param provider [String] the provider identifier
+    # @return [String] the downcased, validated provider ID
+    # @raise [ArgumentError] if the provider is not recognized
+    def self.resolve(provider)
+      key = provider.to_s.downcase.strip
+      unless VALID_PROVIDERS.include?(key)
+        raise ArgumentError, "Unknown provider #{provider.inspect}. Valid providers: #{VALID_PROVIDERS.join(', ')}"
+      end
+      key
+    end
+  end
+end

data/lib/sanwo/rails/engine.rb ADDED Viewed

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+require_relative "helper"
+module Sanwo
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Sanwo
+      initializer "sanwo.view_helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Sanwo::Rails::Helper
+        end
+      end
+    end
+  end
+end

data/lib/sanwo/rails/helper.rb ADDED Viewed

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+module Sanwo
+  module Rails
+    # View helpers for rendering Sanwo checkout components in Rails templates.
+    #
+    # The helpers delegate to the {Sanwo::Client} instance stored in
+    # +Rails.application.config.sanwo_client+.
+    #
+    # @example In an initializer (config/initializers/sanwo.rb)
+    #   Rails.application.config.sanwo_client = Sanwo::Client.new(
+    #     provider: "paystack",
+    #     public_key: ENV["PAYSTACK_PUBLIC_KEY"],
+    #   )
+    #
+    # @example In a view
+    #   <%= sanwo_scripts %>
+    #   <%= sanwo_checkout(amount: 50000, email: "user@example.com") %>
+    module Helper
+      # Render the <script> tag that loads the Sanwo embed script.
+      #
+      # @return [String] HTML script tag
+      def sanwo_scripts
+        sanwo_client.render_script
+      end
+      # Render a checkout button with inline JavaScript.
+      #
+      # @param opts [Hash] checkout options (see {Sanwo::Client#render_checkout})
+      # @return [String] HTML string
+      def sanwo_checkout(**opts)
+        sanwo_client.render_checkout(**opts)
+      end
+      # Render a custom-amount checkout widget.
+      #
+      # @param opts [Hash] widget options (see {Sanwo::Client#render_custom_amount})
+      # @return [String] HTML string
+      def sanwo_custom_amount(**opts)
+        sanwo_client.render_custom_amount(**opts)
+      end
+      private
+      def sanwo_client
+        ::Rails.application.config.sanwo_client
+      end
+    end
+  end
+end

data/lib/sanwo/version.rb ADDED Viewed

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+module Sanwo
+  VERSION = "0.1.0"
+end

data/lib/sanwo.rb ADDED Viewed

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+require_relative "sanwo/version"
+require_relative "sanwo/providers"
+require_relative "sanwo/client"
+if defined?(Rails)
+  require_relative "sanwo/rails/engine"
+end

metadata ADDED Viewed

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: sanwo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SanwoHQ
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: erb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Server-side HTML generator for Sanwo checkout — generates HTML/JS that
+  loads the Sanwo embed script from CDN and calls Sanwo.create() + .checkout().
+email:
+- hello@sanwohq.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/sanwo.rb
+- lib/sanwo/client.rb
+- lib/sanwo/providers.rb
+- lib/sanwo/rails/engine.rb
+- lib/sanwo/rails/helper.rb
+- lib/sanwo/version.rb
+homepage: https://sanwohq.com
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://sanwohq.com
+  source_code_uri: https://github.com/Sanwohq/ruby
+  changelog_uri: https://github.com/Sanwohq/ruby/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key:
+specification_version: 4
+summary: Universal payment SDK for Ruby
+test_files: []