taler 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2264b54990f6df1015504ea8e2d51e9e0f3f9e8fb0d2e6948e32b900e4c899dd
-  data.tar.gz: ae655bb16c4a6d5e9aab5c5da7051d19895232388c2709b3d51e67f040137b0e
+  metadata.gz: dc1ef9028362bec363c1c645759524173618697fc1a0ce52cfb87539c5ecc2b1
+  data.tar.gz: 50654905eb23b1f07571cbe96bb30d223320ea65f82779e2a3a7990bf5af4bfe
 SHA512:
-  metadata.gz: '0718fc34e186d2a5af60bad022efa7362eddcc4844b579aa417f43565b5004a0ddbfa1de83148540d6555dcd52f87bb7a09cfdf60d1b1dc90cba70ae0a35c50e'
-  data.tar.gz: 3f5b4abddbd440dd5df338aa0269b91360e3ed8cb8a91dd0e23a002b5d2b95b83cb80ec0cdba3beb3eae87dab31949a0037e6c8d98dff1d8a42def2fd180afec
+  metadata.gz: c4ada42f23bfc80478b5bff58d03b166c221bfc7d054153f8f079a6b4869eb319a0d6051826a05df53b6053dcf0e3b08cc133524a9a2e5085ece452ad1fdfa8b
+  data.tar.gz: '0029a33dfd7313028d146748039acd2d38683cb5b25b6ec8916e3097e79c129a9281381423bac354c888c74336a63a2b33ced5697fee1c83bd383da301bdc510'

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [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.

data/README.md

@@ -13,6 +13,8 @@ bundle add taler
 ## Usage
 
 ```rb
+require "taler"
+
 backend_url = "https://backend.demo.taler.net/instances/sandbox"
 backend_password = "sandbox"
 
@@ -47,11 +49,13 @@ 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.
 
-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).
+## Release
+
+- 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
 

data/lib/taler/client.rb

@@ -8,18 +8,31 @@ module Taler
   #
   # 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
 
+    # @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"
       order = {
@@ -32,15 +45,24 @@ module Taler
       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:}
@@ -49,21 +71,21 @@ module Taler
 
     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

@@ -8,6 +8,11 @@ module Taler
     # @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
@@ -15,6 +20,12 @@ module Taler
 
     # 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(
@@ -29,6 +40,8 @@ module Taler
     # 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
@@ -36,12 +49,14 @@ module Taler
     # 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.
+    # 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,TrueClass,FalseClass] The value of the field.
+    # @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)
@@ -49,8 +64,10 @@ module Taler
 
     # Query the latest order information from the backend.
     #
-    # If you called `#fetch` in the past and are expecting updates from
+    # 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
@@ -64,5 +81,24 @@ module Taler
     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.2.0"
+  # @return [String]
+  VERSION = "0.3.0"
 end

data/lib/taler.rb

@@ -4,6 +4,8 @@ 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taler
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Maikel Linke
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !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
@@ -121,6 +135,20 @@ dependencies:
     - - ">="
       - !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
@@ -139,7 +167,6 @@ files:
 - lib/taler/client.rb
 - lib/taler/order.rb
 - lib/taler/version.rb
-- sig/client.rbs
 - sig/taler.rbs
 homepage: https://github.com/openfoodfoundation/taler-ruby
 licenses:
@@ -154,7 +181,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.4.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/sig/client.rbs

@@ -1,23 +0,0 @@
-module Taler
-  class Client
-    @backend_url: untyped
-
-    @password: untyped
-
-    def initialize: (untyped backend_url, untyped password) -> void
-
-    def request_token: () -> untyped
-
-    def create_order: (untyped amount, untyped summary, untyped fulfillment_url) -> untyped
-
-    def fetch_order: (untyped order_id) -> untyped
-
-    private
-
-    def auth_token: () -> ::String
-
-    def get: (untyped url, ?untyped token) -> untyped
-
-    def request: (untyped url, ?token: untyped, ?payload: untyped?) -> untyped
-  end
-end