taler 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96d1418bd3c05ff024f0f3d8e478d9f5e8e2b3f69b05f900ae7c25306fd43d44
-  data.tar.gz: d3f96d79ced6d329da2a79888a99cc7ecf4bc15ae1b4f8c13e2c776895265040
+  metadata.gz: dc1ef9028362bec363c1c645759524173618697fc1a0ce52cfb87539c5ecc2b1
+  data.tar.gz: 50654905eb23b1f07571cbe96bb30d223320ea65f82779e2a3a7990bf5af4bfe
 SHA512:
-  metadata.gz: 48c2d8cb20973d02cbb00117244c9820046da27d91f91bf96d4167749b8fd3b5fc8061e8782ec66d97036c6b1d0f99d37c309484198603837cbd381739809796
-  data.tar.gz: 8a5c1273e9615eb168fa5a3aa6a2fa14f072c07044ca689720ede647b7ee54ac0bc3052800bbd56590130c0e38cac10705a0f944ef9adf88153de5004f1ff91c
+  metadata.gz: c4ada42f23bfc80478b5bff58d03b166c221bfc7d054153f8f079a6b4869eb319a0d6051826a05df53b6053dcf0e3b08cc133524a9a2e5085ece452ad1fdfa8b
+  data.tar.gz: '0029a33dfd7313028d146748039acd2d38683cb5b25b6ec8916e3097e79c129a9281381423bac354c888c74336a63a2b33ced5697fee1c83bd383da301bdc510'

data/.yardopts

@@ -0,0 +1,2 @@
+--markup=markdown
+--markup-provider=redcarpet

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-10-14
+## [0.3.0] - 2026-02-24
+
+- Update docs and rbs file.
+- Custom methods `Taler::Order#to_s` and `#inspect`.
+- Replaced deprecated password auth with access token.
+
+## [0.2.0] - 2026-02-02
+
+- Add `Taler::Order` as an easier interface.
+- Add method to refund orders.
+- Add option for fulfillment message instead of fulfillment URL.
+- Add documentation with yard.
+
+## [0.1.0] - 2026-01-19
+
+- Add `Taler::Client` to create access token and orders. Fetch orders.
+
+## [0.0.0] - 2025-10-14
 
 - Initial release generated by bundler. Nothing to see yet.

data/README.md

@@ -1,33 +1,63 @@
 # GNU Taler payment API for Ruby
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/taler`. To experiment with that code, run `bin/console` for an interactive prompt.
+The Taler library let's you interact with a Taler merchant backend API to
+take payments.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
-Install the gem and add to the application's Gemfile by executing:
-
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install taler # or
+bundle add taler
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Usage
+
+```rb
+require "taler"
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+backend_url = "https://backend.demo.taler.net/instances/sandbox"
+backend_password = "sandbox"
+
+order = Taler::Order.new(backend_url:, password:)
+order.create(
+  amount: "KUDOS:4",
+  summary: "Order total",
+  fulfillment_message: "Thank you!"
+)
+
+puts "Pay at: #{order.status_url}"
+
+while order.fetch("order_status") == "unpaid"
+  sleep 1
+  order.reload
+end
+
+if order.fetch("order_status") == "paid"
+  puts "Great. All paid."
+else
+  puts "Sorry, the order is #{order.fetch("order_status")}. Try again."
+end
 ```
 
-## Usage
+Read more in the official documentation:
 
-TODO: Write usage instructions here
+- https://rubydoc.info/gems/taler
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake` to run the tests.
+You can also run `bin/console` for an interactive prompt.
+
+## Release
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+- Update the version number in `lib/taler/version.rb`.
+- Update the `CHANGELOG.md` file.
+- Run `bundle update`.
+- Commit.
+- Run `bundle exec rake release` to build, tag and push the gem.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/taler.
+Bug reports and pull requests are welcome on GitHub
+at https://github.com/openfoodfoundation/taler-ruby.

data/lib/taler/client.rb

@@ -4,54 +4,88 @@ require "json"
 require "net/http"
 
 module Taler
+  # Access the GNU Taler merchant backend API.
+  #
+  # See: https://docs.taler.net/core/api-merchant.html
   class Client
+    # @param backend_url [String] e.g. `"https://backend.demo.taler.net/instances/sandbox"`
+    # @param password [String]
     def initialize(backend_url, password)
       @backend_url = backend_url
       @password = password
     end
 
+    # Obtain an access token to authenticate all other API calls.
+    #
+    # @return [String]
     def request_token
       url = "#{@backend_url}/private/token"
       payload = {scope: "write"}
-      result = request(url, payload:)
+      result = request(url, token: auth_token, payload:)
       result.fetch("token")
     end
 
-    def create_order(amount, summary, fulfillment_url)
+    # @param amount [String] e.g. "KUDOS:200"
+    # @param summary [String] A description of the order displayed to the user.
+    # @param fulfillment_url [String] The user is redirected to this URL after
+    #   payment. The order status page also links here.
+    # @param fulfillment_message [String] Text to display to the user after
+    #   payment.
+    # @return [Hash] The resonse from the backend, usually just containing an
+    #   order id, e.g. `{order_id: "xxxxx"}`
+    def create_order(amount:, summary:, fulfillment_url: nil, fulfillment_message: nil)
       url = "#{@backend_url}/private/orders"
-      payload = {
-        order: {
-          amount: amount,
-          summary: summary,
-          fulfillment_url: fulfillment_url
-        },
-        create_token: false
+      order = {
+        amount: amount,
+        summary: summary
       }
+      order[:fulfillment_url] = fulfillment_url unless fulfillment_url.nil?
+      order[:fulfillment_message] = fulfillment_message unless fulfillment_message.nil?
+      payload = {order:, create_token: false}
       request(url, payload:)
     end
 
+    # @param order_id [String]
+    # @return [String]
+    def order_status_url(order_id)
+      "#{@backend_url}/orders/#{order_id}"
+    end
+
+    # @param order_id [String]
+    # @return [Hash] The order status returned by the backend.
     def fetch_order(order_id)
       url = "#{@backend_url}/private/orders/#{order_id}"
       request(url)
     end
 
+    # @param order_id [String]
+    # @param refund [String] The amount with currency.
+    # @param reason [String] Why are you refunding?
+    #
+    # @return [Hash] Response from the merchant backend.
+    def refund_order(order_id, refund:, reason:)
+      url = "#{@backend_url}/private/orders/#{order_id}/refund"
+      payload = {refund:, reason:}
+      request(url, payload:)
+    end
+
     private
 
+    # @return [String]
     def auth_token
       "secret-token:#{@password}"
     end
 
-    def get(url, token = auth_token)
-      headers = {
-        "Authorization" => "Bearer #{token}",
-        "Accept" => "application/json",
-        "User-Agent" => "Taler Ruby"
-      }
-      response = Net::HTTP.get(URI(url), headers)
-      JSON.parse(response)
+    # @return [String]
+    def access_token
+      @access_token ||= request_token
     end
 
-    def request(url, token: auth_token, payload: nil)
+    # @param url [String]
+    # @param token [String]
+    # @param payload [Hash]
+    # @return [String]
+    def request(url, token: access_token, payload: nil)
       uri = URI(url)
       headers = {
         "Authorization" => "Bearer #{token}",

data/lib/taler/order.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Taler
+  # Order representation with convenient access to the merchant API.
+  class Order
+    # Connect an Order to the Taler merchant backend.
+    #
+    # @param backend_url [String] e.g. `"https://backend.demo.taler.net/instances/sandbox"`
+    # @param password [String] e.g. `"sandbox"`
+    # @param id [String] The order id of an existing order.
+    # @example Connect to the official demo backend
+    #   Taler::Order.new(
+    #     backend_url: "https://backend.demo.taler.net/instances/sandbox",
+    #     password: "sandbox"
+    #   )
+    def initialize(backend_url:, password:, id: nil)
+      @client = Client.new(backend_url, password)
+      @id = id
+    end
+
+    # Create a new order record ready to take a payment.
+    #
+    # @param amount [String] e.g. "KUDOS:200"
+    # @param summary [String] A description of the order displayed to the user.
+    # @param fulfillment_url [String] The user is redirected to this URL after
+    #   payment. The order status page also links here.
+    # @param fulfillment_message [String] Text to display to the user after
+    #   payment.
+    # @return [String] The id of the new order.
+    def create(amount:, summary:, fulfillment_url: nil, fulfillment_message: nil)
+      response = @client.create_order(
+        amount:, summary:, fulfillment_url:, fulfillment_message:
+      )
+      @id = response.fetch("order_id")
+    end
+
+    # The page where the customer can pay or accept a refund,
+    # depending on the state of the order.
+    #
+    # The merchant backend opens the Taler plugin or app if it can.
+    # Otherwise it shows a QR code to scan in the app and provides
+    # installation instructions.
+    #
+    # @return [String]
+    def status_url
+      @client.order_status_url(@id)
+    end
+
+    # Access order status fields.
+    #
+    # It queries the backend if it hasn't done that already.
+    # Call {#reload} beforehand to get the latest status from the backend.
+    #
+    # @param key [String] A field in the order status response of the backend,
+    #   e.g. `order_status`.
+    # @return [String,true,false] The value of the field.
+    #   Any simple type supported by JSON.
+    # @example
+    #   fetch("order_status") #=> "unpaid"
+    def fetch(key)
+      reload unless @status
+      @status.fetch(key)
+    end
+
+    # Query the latest order information from the backend.
+    #
+    # If you called {#fetch} in the past and are expecting updates from
+    # user interaction, you want to call this.
+    #
+    # @return [Hash] The order status returned by the backend.
+    def reload
+      @status = @client.fetch_order(@id)
+    end
+
+    # Issue a refund request for this order.
+    #
+    # @param refund [String] The amount with currency.
+    # @param reason [String] Why are you refunding?
+    #
+    # @return [Hash] Response from the merchant backend.
+    def refund(refund:, reason:)
+      @client.refund_order(@id, refund:, reason:)
+    end
+
+    # @return [String]
+    def inspect
+      status = @status.to_h.slice(*%w[
+        order_status
+        deposit_total
+        wired
+        refunded
+        refund_pending
+        refund_amount
+      ])
+      "#<#{self.class.name} #{status_url} #{status.inspect}>"
+    end
+
+    # @return [String]
+    def to_s
+      status = @status.to_h.slice("order_status", "refunded")
+      "#<#{self.class.name} #{status_url} #{status.inspect}>"
+    end
+  end
+end

data/lib/taler/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Taler
-  VERSION = "0.1.0"
+  # @return [String]
+  VERSION = "0.3.0"
 end

data/lib/taler.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "taler/client"
+require_relative "taler/order"
 require_relative "taler/version"
 
+# GNU Taler payment system interface
 module Taler
+  # Base error class for errors raised in this module
   class Error < StandardError; end
 end

data/sig/taler.rbs

@@ -1,4 +1,148 @@
+# GNU Taler payment system interface
 module Taler
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-end
+
+  # Base error class for errors raised in this module
+  class Error < StandardError
+  end
+
+  # Order representation with convenient access to the merchant API.
+  class Order
+    # Connect an Order to the Taler merchant backend.
+    # 
+    # _@param_ `backend_url` — e.g. `"https://backend.demo.taler.net/instances/sandbox"`
+    # 
+    # _@param_ `password` — e.g. `"sandbox"`
+    # 
+    # _@param_ `id` — The order id of an existing order.
+    # 
+    # Connect to the official demo backend
+    # ```ruby
+    # Taler::Order.new(
+    #   backend_url: "https://backend.demo.taler.net/instances/sandbox",
+    #   password: "sandbox"
+    # )
+    # ```
+    def initialize: (backend_url: String, password: String, ?id: String?) -> void
+
+    # Create a new order record ready to take a payment.
+    # 
+    # _@param_ `amount` — e.g. "KUDOS:200"
+    # 
+    # _@param_ `summary` — A description of the order displayed to the user.
+    # 
+    # _@param_ `fulfillment_url` — The user is redirected to this URL after payment. The order status page also links here.
+    # 
+    # _@param_ `fulfillment_message` — Text to display to the user after payment.
+    # 
+    # _@return_ — The id of the new order.
+    def create: (
+                  amount: String,
+                  summary: String,
+                  ?fulfillment_url: String?,
+                  ?fulfillment_message: String?
+                ) -> String
+
+    # The page where the customer can pay or accept a refund,
+    # depending on the state of the order.
+    # 
+    # The merchant backend opens the Taler plugin or app if it can.
+    # Otherwise it shows a QR code to scan in the app and provides
+    # installation instructions.
+    def status_url: () -> String
+
+    # Access order status fields.
+    # 
+    # It queries the backend if it hasn't done that already.
+    # Call {#reload} beforehand to get the latest status from the backend.
+    # 
+    # _@param_ `key` — A field in the order status response of the backend, e.g. `order_status`.
+    # 
+    # _@return_ — The value of the field.
+    # Any simple type supported by JSON.
+    # 
+    # ```ruby
+    # fetch("order_status") #=> "unpaid"
+    # ```
+    def fetch: (String key) -> (String | bool)
+
+    # Query the latest order information from the backend.
+    # 
+    # If you called {#fetch} in the past and are expecting updates from
+    # user interaction, you want to call this.
+    # 
+    # _@return_ — The order status returned by the backend.
+    def reload: () -> ::Hash[untyped, untyped]
+
+    # Issue a refund request for this order.
+    # 
+    # _@param_ `refund` — The amount with currency.
+    # 
+    # _@param_ `reason` — Why are you refunding?
+    # 
+    # _@return_ — Response from the merchant backend.
+    def refund: (refund: String, reason: String) -> ::Hash[untyped, untyped]
+
+    def inspect: () -> String
+
+    def to_s: () -> String
+  end
+
+  # Access the GNU Taler merchant backend API.
+  # 
+  # See: https://docs.taler.net/core/api-merchant.html
+  class Client
+    # _@param_ `backend_url` — e.g. `"https://backend.demo.taler.net/instances/sandbox"`
+    # 
+    # _@param_ `password`
+    def initialize: (String backend_url, String password) -> void
+
+    # Obtain an access token to authenticate all other API calls.
+    def request_token: () -> String
+
+    # _@param_ `amount` — e.g. "KUDOS:200"
+    # 
+    # _@param_ `summary` — A description of the order displayed to the user.
+    # 
+    # _@param_ `fulfillment_url` — The user is redirected to this URL after payment. The order status page also links here.
+    # 
+    # _@param_ `fulfillment_message` — Text to display to the user after payment.
+    # 
+    # _@return_ — The resonse from the backend, usually just containing an
+    # order id, e.g. `{order_id: "xxxxx"}`
+    def create_order: (
+                        amount: String,
+                        summary: String,
+                        ?fulfillment_url: String?,
+                        ?fulfillment_message: String?
+                      ) -> ::Hash[untyped, untyped]
+
+    # _@param_ `order_id`
+    def order_status_url: (String order_id) -> String
+
+    # _@param_ `order_id`
+    # 
+    # _@return_ — The order status returned by the backend.
+    def fetch_order: (String order_id) -> ::Hash[untyped, untyped]
+
+    # _@param_ `order_id`
+    # 
+    # _@param_ `refund` — The amount with currency.
+    # 
+    # _@param_ `reason` — Why are you refunding?
+    # 
+    # _@return_ — Response from the merchant backend.
+    def refund_order: (String order_id, refund: String, reason: String) -> ::Hash[untyped, untyped]
+
+    def auth_token: () -> String
+
+    def access_token: () -> String
+
+    # _@param_ `url`
+    # 
+    # _@param_ `token`
+    # 
+    # _@param_ `payload`
+    def request: (String url, ?token: String, ?payload: ::Hash[untyped, untyped]?) -> String
+  end
+end

metadata

@@ -1,14 +1,155 @@
 --- !ruby/object:Gem::Specification
 name: taler
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Maikel Linke
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Create and refund orders through the Taler merchant backend API.
 email:
 - maikel@email.org.au
 executables: []
@@ -17,12 +158,14 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".standard.yml"
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE
 - README.md
 - Rakefile
 - lib/taler.rb
 - lib/taler/client.rb
+- lib/taler/order.rb
 - lib/taler/version.rb
 - sig/taler.rbs
 homepage: https://github.com/openfoodfoundation/taler-ruby
@@ -38,7 +181,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="