speed_lightning 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d495358c9ef893d5c40687eea21f711202f0eaf44d8df04d01542558587169e
-  data.tar.gz: c9296ec50d68213968a7b5c7c3f475e89710d62e5ff07cd3b9b145bb59001517
+  metadata.gz: 9034ae11f5f106f8cc3e21fcef837d9dba63cb76a9ea97d44a0b4a7e38456b51
+  data.tar.gz: 14aa426f9f97f9cf73c172f5ae0da7abc40adf0567338bf583e3fc9b7e80c92b
 SHA512:
-  metadata.gz: 6fbed22ee55ca5bc121685ddf5e062591fe181bc632906d41682092233e57c6c7cde8cdf81d0686805966ca9d5ccdd40d3c529268702fb246690d0aaac25538c
-  data.tar.gz: b1a6b1174aaaa8752f10795812545d469c9934cc691a5aec0d91ed2bc069d92732c04fd9c4ead727530d9828787bcd00e8c112c53b73f09f8168fbb774208db2
+  metadata.gz: b1da6165b682e214932c86956b9958a0f48fb7ff1e169f243c229dca4a3331286ff2e87320eb0cb3139711abf00ca84dcae78b014dceb8e7ba08765c32a7a465
+  data.tar.gz: 6a217f61ca76f1356e3cccfa713d88a15e24cc4b195f6e47262320d2aa1bf7c7621f6a7d562edffec519c1799df790b0af663697e606cdb3c6af8827aa4179b6

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.2.0] - 2023-10-24
+
+### Added
+- Added support for named parameters in client initialization and method calls for better readability and flexibility.
+- Introduced `Retryable` module for retrying failed requests.
+- Introduced error handling with `SpeedLightning::Error`.
+- Added convenience paid? method to check if payment has been completed.
+
+### Changed
+- Improved the file structure.
+- Renamed methods for creating and retrieving checkout links.
+- Modified client initialization to use named parameter `secret_key`.
+- Refactored `CheckoutLink` class to handle raw API attributes and conversion to Ruby time objects.
+
+## [0.1.1] - 2023-10-23
+
+- Minor updates for publishing to RubyGems
+
 ## [0.1.0] - 2023-10-22
 
 - Initial release

data/DOCUMENTATION.md

@@ -0,0 +1,134 @@
+# Speed Lightning Documentation
+
+## Introduction
+This gem makes the Speed Lightning service easier to access from within your Ruby project.
+
+It's a "lightly opinionated" gem making a few assumptions about how you will use the API in order to both harden it against failures, and to simplify the operation:
+* By default requests are in livemode: false, meaning it's test mode
+* A successful payment always returns to a success url within your app, instead of displaying a success message within the Speed interface
+* If requests fail, the gem will retry once, before raising an error
+* Target currency is hardcoded as Bitcoin Satoshis "SATS"
+* Created and modified times are converted to Ruby time objects as created_at and updated_at to follow conventions
+* Default metadata includes `client: "ruby"`, so override it with an empty or your own hash if you want to remove this default
+* success_message, cashback, statement_descriptor, object, target_currency, payment_id array are only available within raw_attribute
+
+## Table of Contents
+- [Initialization](#initialization)
+- [Checkout Link](#checkout-link-object)
+- [Error Handling](#error-handling)
+
+## Initialization
+```
+require 'speed_lightning'
+client = SpeedLightning::Client.new(secret_key: ENV["SPEED_API_SECRET"])
+```
+## Checkout Link Object
+
+### Available Parameters
+
+* id: speed payment id
+* amount: payment amount in satoshis 
+* currency: "SATS" by default
+* url: payment url to be presented to users
+* success_url: url the user is forwarded to after successful payment
+* status: payment status
+* metadata: metadata to link speed payment with ruby application data
+* is_email_enabled: true if user needs to provide email to pay
+* is_phone_enabled: true if user needs to provide phone to pay
+* is_billing_address_enabled: true if user needs to provide billing address to pay
+* is_shipping_address_enabled: true if user needs to provide shipping address to pay
+* livemode: default is false for test mode, true is live
+* created_at: ruby time object
+* updated_at: ruby time object
+* raw_attributes: the raw data returned by the Speed API
+
+### Convenience Methods
+
+* paid? : returns true if payment has been completed
+
+### Create
+
+Basic usage with only required parameters, the invoice amount and the success return url:
+```
+client.create_checkout_link(777, "https://yourwebsite.com/thank_you")
+```
+
+Advanced usage with all supported parameters:
+```
+amount = 777
+currency = "SATS"
+```
+
+The user forwarded to the success url after successful payment (note: `localhost:3000/thank_you` won't validate):
+```
+success_url = "https://your_website.com/thank_you"
+```
+
+Add optional metadata that links the speed payment with your application data:
+```
+metadata = {
+  order_id: 1,
+  user_id: 1,
+  product_id: "subscription"}
+```
+
+Options that need to be filled by the customer before processing the payment. Default is all false:
+```
+is_phone_enabled = false
+is_email_enabled = true
+is_billing_address_enabled = false
+is_shipping_address_enabled = false
+```
+
+For the livemode parameter the default `false` boolean means test payment on testnet, `true` means live payment on livenet:
+```
+livemode = false
+```
+
+Finally, make a request:
+```
+checkout_link_object = client.create_checkout_link(
+  amount: amount,
+  success_url: success_url,
+  currency: currency,
+  metadata: metadata,
+  is_phone_enabled: is_phone_enabled,
+  is_email_enabled: is_email_enabled,
+  is_billing_address_enabled: is_billing_address_enabled,
+  is_shipping_address_enabled: is_shipping_address_enabled,
+  livemode: livemode)
+```
+
+If creation of object is successful, you can get payment data:
+* id of the checkout link, needed to retrieve it later: `checkout_link_object.id`
+* url of the checkout link, show to customer so they can pay: `checkout_link_object.url`
+* metadata hash of the payment: `checkout_link_object.metadata`
+* email collection status: `checkout_link_object.is_email_enabled`
+* test or live mode: `checkout_link_object.livemode`
+
+To test payments, you can login to speed and pay the invoice with test satoshis: https://www.ln.dev
+
+### Retrieve
+
+Retrieve a checkout link with the checkout link object's id:
+```
+retrieved_object = client.retrieve_checkout_link(checkout_link_object.id)
+```
+
+Get metadata of the payment, for example order_id: `retrieved_object.metadata["order_id"]`
+
+Get raw attributes: `retrieved_object.raw_attributes`
+
+## Error handling
+If the request fails, the gem retries once after one second. If it fails again it raises an error.
+
+Example of how to deal with an error in your application:
+```
+begin
+  checkout_link_object = client.create_checkout_link(11, "invalid url...")
+rescue SpeedLightning::Error => e
+  # Do something when request fails
+  puts "Speed API error detected: #{e.message}"
+end
+
+```

data/Gemfile

@@ -1,10 +1,2 @@
-# frozen_string_literal: true
-
 source "https://rubygems.org"
-
-# Specify your gem's dependencies in speed_lightning.gemspec
-gemspec
-
-gem "rake", "~> 13.0"
-
-gem "minitest", "~> 5.0"
+gemspec

data/Gemfile.lock

@@ -1,12 +1,18 @@
 PATH
   remote: .
   specs:
-    speed_lightning (0.1.0)
+    speed_lightning (0.2.0)
+      httparty (~> 0.21.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    httparty (0.21.0)
+      mini_mime (>= 1.0.0)
+      multi_xml (>= 0.5.2)
+    mini_mime (1.1.5)
     minitest (5.20.0)
+    multi_xml (0.6.0)
     rake (13.0.6)
 
 PLATFORMS

data/README.md

@@ -22,7 +22,7 @@ Or install it yourself as:
 
 ## Usage
 
-Find full documentation of this gem and more examples under documentation.rb
+Find full documentation of this gem and more examples: [Detailed Documentation](DOCUMENTATION.md)
 
 Optionally, if you are testing this gem without installing in IRB
 ```
@@ -36,27 +36,27 @@ Otherwise once bundled test in your own project:
 
 Initialize the library with Speed test environment secret key
 
-`client = SpeedLightning::Client.new("your_speed_secret_key_here")`
+`client = SpeedLightning::Client.new(secret_key: "your_speed_secret_key_here")`
 
-create a new checkout link with required parameters: invoice amount, success return url
+create a new checkout link with required parameters in test mode: invoice amount, success return url
 
-`response = client.create_speed_checkout_link(777, "https://yourwebsite.com/thank_you")`
+`response = client.create_checkout_link(777, "https://your_website.com/thank_you")`
 
 get speed checkout url with QR code and LN invoice:
 
-`puts response["url"]`
+`puts response.url`
 
 get speed checkout ID:
 
-`puts response["id"]`
+`puts checkout_id = response.id`
 
 get invoice status
 
-`response = client.retrieve_speed_checkout_link(checkout_id)`
+`response = client.retrieve_checkout_link(checkout_id)`
 
 get payment status
 
-`puts response["status"]`
+`puts response.status`
 
 ## Development
 

data/lib/speed_lightning/checkout_link.rb

@@ -0,0 +1,44 @@
+class CheckoutLink
+  attr_accessor :id, :amount, :currency, :url, :success_url, :status, :metadata, :is_email_enabled, :is_phone_enabled, :is_billing_address_enabled, :is_shipping_address_enabled, :livemode, :created_at, :updated_at, :raw_attributes
+
+  def initialize(attributes = {})
+    @id = attributes['id']
+    @amount = attributes['amount']
+    @currency = attributes['currency']
+    @url = attributes['url']
+    @success_url = attributes['success_url']
+    @status = attributes['status']
+    @metadata = attributes['metadata']
+    @is_email_enabled = attributes.dig('customer_collections_status', 'is_email_enabled')
+    @is_phone_enabled = attributes.dig('customer_collections_status', 'is_phone_enabled')
+    @is_billing_address_enabled = attributes.dig('customer_collections_status', 'is_billing_address_enabled')
+    @is_shipping_address_enabled = attributes.dig('customer_collections_status', 'is_shipping_address_enabled')
+    @livemode = attributes['livemode']
+    # Convert the Unix timestamp in milliseconds to Ruby's Time object
+    @created_at = Time.at(attributes['created'] / 1000.0)
+    @updated_at = Time.at(attributes['modified'] / 1000.0)
+    @raw_attributes = attributes
+  end
+
+  def to_hash
+    {
+      id: @id,
+      amount: @amount,
+      currency: @currency,
+      success_url: @success_url,
+      metadata: @metadata,
+      customer_collections_status: {
+        is_email_enabled: @is_email_enabled,
+        is_phone_enabled: @is_phone_enabled,
+        is_billing_address_enabled: @is_billing_address_enabled,
+        is_shipping_address_enabled: @is_shipping_address_enabled
+      },
+      livemode: @livemode
+    }
+  end
+
+  def paid?
+    @status == "paid"
+  end
+  
+end

data/lib/speed_lightning/checkout_link_methods.rb

@@ -0,0 +1,48 @@
+require_relative 'checkout_link'
+require_relative 'retryable'
+
+module SpeedLightning
+  module CheckoutLinkMethods
+    include Retryable 
+
+    def create_checkout_link(
+        amount:,
+        success_url:,
+        currency: "SATS",
+        metadata: { client: "ruby" },
+        is_phone_enabled: false,
+        is_email_enabled: false,
+        is_billing_address_enabled: false,
+        is_shipping_address_enabled: false,
+        livemode: false
+      )
+      with_retry do
+        body_hash = {
+          amount: amount,
+          success_url: success_url,
+          currency: currency,
+          metadata: metadata,
+          customer_collections_status: {
+              is_email_enabled: is_email_enabled,
+              is_phone_enabled: is_phone_enabled,
+              is_billing_address_enabled: is_billing_address_enabled,
+              is_shipping_address_enabled: is_shipping_address_enabled
+            },
+          livemode: livemode
+        }
+        endpoint = "checkout-links"
+        response = make_request(endpoint, :post, body_hash)
+        CheckoutLink.new(response)
+      end
+    end
+
+    def retrieve_checkout_link(id)
+      with_retry do
+        endpoint = "checkout-links/" + id
+        response = make_request(endpoint, :get)
+        CheckoutLink.new(response)
+      end
+    end
+
+  end
+end

data/lib/speed_lightning/client.rb

@@ -0,0 +1,46 @@
+require 'httparty'
+require_relative 'error'
+require_relative 'checkout_link_methods'
+
+module SpeedLightning
+  class Client
+    include HTTParty
+    include CheckoutLinkMethods
+    attr_accessor :api_secret
+    API_URL = "https://api.tryspeed.com/"
+
+    def initialize(secret_key:)
+      @secret_key = secret_key
+    end
+    
+    def make_request(endpoint, request_type, body_hash = nil)
+      headers = {
+        "Accept" => "application/json",
+        "Speed-Version" => "2022-04-15",
+        "Authorization" => "Basic " + Base64.strict_encode64(@secret_key + ":")
+      }
+      headers["Content-Type"] = "application/json" if body_hash
+      options = { headers: headers }
+      options[:body] = body_hash.to_json if body_hash
+      full_url = API_URL + endpoint
+      response =
+        case request_type
+        when :get
+          self.class.get(full_url, options)
+        when :post
+          self.class.post(full_url, options)
+        end
+      
+        parsed_response = JSON.parse(response.body)
+      
+      if parsed_response['errors'] && !parsed_response['errors'].empty?
+        error_messages = parsed_response['errors'].map { |error| error['message'] }.compact
+        concatenated_error_message = error_messages.join(', ')
+        raise SpeedLightning::Error, concatenated_error_message
+      end         
+      
+      parsed_response
+    end
+
+  end
+end

data/lib/speed_lightning/error.rb

@@ -0,0 +1,3 @@
+module SpeedLightning
+  class Error < StandardError; end
+end

data/lib/speed_lightning/retryable.rb

@@ -0,0 +1,20 @@
+module SpeedLightning
+  module Retryable
+
+    def with_retry
+      should_retry = true
+      begin
+        yield
+      rescue SpeedLightning::Error => e
+        if should_retry
+          should_retry = false
+          sleep 1
+          retry
+        else
+          raise e
+        end
+      end
+    end
+
+  end
+end

data/lib/speed_lightning/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SpeedLightning
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/speed_lightning.rb

@@ -1,64 +1,12 @@
 require_relative "speed_lightning/version"
-require 'uri'
-require 'net/http'
+require_relative "speed_lightning/error"
+require_relative "speed_lightning/retryable"
+require_relative "speed_lightning/checkout_link"
+require_relative "speed_lightning/checkout_link_methods"
+require_relative "speed_lightning/client"
+require 'httparty'
 require 'base64'
 require 'json'
 
 module SpeedLightning
-  class Error < StandardError; end
-  class Client
-    attr_accessor :api_secret
-    API_URL = "https://api.tryspeed.com/"
-
-    def initialize(api_secret)
-      @api_secret = api_secret
-    end
-    
-    def make_request(endpoint, request_type, body_hash = nil)
-      key = "Basic " + Base64.strict_encode64(@api_secret+":") # no password necessary after colon
-      url = URI(API_URL + endpoint)
-      http = Net::HTTP.new(url.host, url.port)
-      http.use_ssl = true
-      request = request_type.new(url)
-      request["accept"] = 'application/json'
-      request["speed-version"] = '2022-04-15'
-      request["authorization"] = key
-      if body_hash
-        request["content-type"] = 'application/json'
-        request.body = body_hash.to_json
-      end
-      return JSON.parse(http.request(request).read_body)
-    end
-
-    def create_speed_checkout_link(
-      amount,
-      success_url,
-      currency = "SATS",
-      metadata = { client: "ruby" },
-      customer_collections_status = {
-        is_phone_enabled: false,
-        is_email_enabled: false,
-        is_billing_address_enabled: false,
-        is_shipping_address_enabled: false
-      }
-    )
-      body_hash = {
-        amount: amount,
-        success_url: success_url,
-        currency: currency,
-        metadata: metadata,
-        customer_collections_status: customer_collections_status
-      }
-      endpoint = "checkout-links"
-      request_type = Net::HTTP::Post
-      return make_request(endpoint, request_type, body_hash)
-    end
-
-    def retrieve_speed_checkout_link(id)
-      endpoint = "checkout-links/" + id
-      request_type = Net::HTTP::Get
-      return make_request(endpoint, request_type)
-    end
-
-  end
-end
+end

data/speed_lightning.gemspec

@@ -25,5 +25,7 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "> 2.0"
   spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'minitest', "~> 5.0"
+
+  spec.add_runtime_dependency "httparty", "~> 0.21.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: speed_lightning
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Ivan Raszl
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-10-22 00:00:00.000000000 Z
+date: 2023-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -42,16 +42,30 @@ dependencies:
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.21.0
 description: 'For more information visit: https://www.speed.dev/'
 email:
 - iraszl@gmail.com
@@ -63,6 +77,7 @@ files:
 - ".gitignore"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- DOCUMENTATION.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -70,8 +85,12 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
-- documentation.rb
 - lib/speed_lightning.rb
+- lib/speed_lightning/checkout_link.rb
+- lib/speed_lightning/checkout_link_methods.rb
+- lib/speed_lightning/client.rb
+- lib/speed_lightning/error.rb
+- lib/speed_lightning/retryable.rb
 - lib/speed_lightning/version.rb
 - speed_lightning.gemspec
 homepage: https://github.com/iraszl/speed_lightning

data/documentation.rb

@@ -1,33 +0,0 @@
-# Initialize Speed Lightning client
-require 'speed_lightning'
-client = SpeedLightning::Client.new(ENV["SPEED_API_SECRET"])
-
-# Checkout Link
-
-# Basic usage with only required parameters: invoice amount, success return url:
-create_cl_response = client.create_speed_checkout_link(777, "https://yourwebsite.com/thank_you")
-
-# Advanced usage with all optional parameters:
-amount = 777
-success_url = "https://yourwebsite.com/thank_you"
-currency = "SATS"
-metadata = {
-  order_id: 1, 
-  user_id: 1,
-  product_id: 1c
-}
-customer_collections_status = {
-  is_phone_enabled: false,
-  is_email_enabled: true,
-  is_billing_address_enabled: false,
-  is_shipping_address_enabled: false
-}
-create_cl_response = client.create_speed_checkout_link(amount, success_url, currency, metadata, customer_collections_status)
-puts create_cl_response["id"] # id of the checkout link, needed to retrieve it later
-puts create_cl_response["url"] # url of the checkout link, show to customer so they can pay
-# pay the invoice with test bitcoins using: https://www.ln.dev
-
-# Retrieve a checkout link by id:
-id = create_cl_response["id"]
-retrieve_response = client.retrieve_speed_checkout_link(id)
-puts retrieve_response["status"] # status of the payment