taler 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc1ef9028362bec363c1c645759524173618697fc1a0ce52cfb87539c5ecc2b1
-  data.tar.gz: 50654905eb23b1f07571cbe96bb30d223320ea65f82779e2a3a7990bf5af4bfe
+  metadata.gz: 60ec832858a497c44d8211a3ac887052991b9a03ad309ffb3ed693205038c3c7
+  data.tar.gz: 247a12ee6e2ffbcc52e6887ddd7b205829de374cde7f37917c6d775db54affd9
 SHA512:
-  metadata.gz: c4ada42f23bfc80478b5bff58d03b166c221bfc7d054153f8f079a6b4869eb319a0d6051826a05df53b6053dcf0e3b08cc133524a9a2e5085ece452ad1fdfa8b
-  data.tar.gz: '0029a33dfd7313028d146748039acd2d38683cb5b25b6ec8916e3097e79c129a9281381423bac354c888c74336a63a2b33ced5697fee1c83bd383da301bdc510'
+  metadata.gz: 2988d2ccf7fa226cd0c781175f7bdd964b37af55070a489d4380d341154e200e5326e24617a03907e74193225560cf2dfd24a7e6ba71373536240ee2e0f4d8ec
+  data.tar.gz: 86fdfeb371bb5cede0492b31c5d7e459c27280cc84a448671ebcdf2b7fe7ae472ed8b7effeabd9e0c13391e636dfded5776b557ae1d2617e42739e82fc278225

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-07
+
+- Raise `Taler::RequestError` when the backend responds with anything but
+  200 OK. The error carries the HTTP `status` and the response `body`, and
+  its message includes the backend's hint. Before, an error response was
+  parsed as a success and callers got a confusing `KeyError` or
+  `JSON::ParserError` instead.
+- Raise `Taler::Error` on any other error during the HTTP request. This
+  could be a connection error, a network failure or something completely
+  unknown.
+
+## [0.4.0] - 2026-08-25
+
+- Restore deprecated password auth as access tokens need 2FA in production.
+  Instead of obtaining a token on-the-fly, the user would provide a token
+  to the app (and this gem) instead of the password. We can add support for
+  that another time.
+
 ## [0.3.0] - 2026-02-24
 
 - Update docs and rbs file.

data/README.md

@@ -16,7 +16,7 @@ bundle add taler
 require "taler"
 
 backend_url = "https://backend.demo.taler.net/instances/sandbox"
-backend_password = "sandbox"
+password = "sandbox"
 
 order = Taler::Order.new(backend_url:, password:)
 order.create(
@@ -39,6 +39,25 @@ else
 end
 ```
 
+### Errors
+
+Every request raises `Taler::RequestError` when the backend responds with
+anything but 200 OK. The message includes the backend's explanation, and
+the error carries the HTTP status and the response body:
+
+```rb
+begin
+  order.create(amount: "KUDOS:4", summary: "Order total")
+rescue Taler::RequestError => e
+  puts e.message # The Taler backend responded with 401: The merchant refused the request due to lack of authorization.
+  puts e.status  # 401
+  puts e.body    # {"code" => 2015, "hint" => "...", "detail" => "..."}
+rescue Taler::Error => e
+  puts e.message # E.g. could not reach destination
+  puts e.cause   # A StandardError that was raised during the request, e.g. Errno::ETIMEDOUT
+end
+```
+
 Read more in the official documentation:
 
 - https://rubydoc.info/gems/taler

data/lib/taler/client.rb

@@ -18,6 +18,7 @@ module Taler
     # Obtain an access token to authenticate all other API calls.
     #
     # @return [String]
+    # @raise [RequestError] If the backend rejects the request or asks for two-factor authentication.
     def request_token
       url = "#{@backend_url}/private/token"
       payload = {scope: "write"}
@@ -33,6 +34,7 @@ module Taler
     #   payment.
     # @return [Hash] The resonse from the backend, usually just containing an
     #   order id, e.g. `{order_id: "xxxxx"}`
+    # @raise [RequestError] If the backend rejects the request.
     def create_order(amount:, summary:, fulfillment_url: nil, fulfillment_message: nil)
       url = "#{@backend_url}/private/orders"
       order = {
@@ -53,6 +55,7 @@ module Taler
 
     # @param order_id [String]
     # @return [Hash] The order status returned by the backend.
+    # @raise [RequestError] If the backend rejects the request.
     def fetch_order(order_id)
       url = "#{@backend_url}/private/orders/#{order_id}"
       request(url)
@@ -63,6 +66,7 @@ module Taler
     # @param reason [String] Why are you refunding?
     #
     # @return [Hash] Response from the merchant backend.
+    # @raise [RequestError] If the backend rejects the request.
     def refund_order(order_id, refund:, reason:)
       url = "#{@backend_url}/private/orders/#{order_id}/refund"
       payload = {refund:, reason:}
@@ -76,16 +80,12 @@ module Taler
       "secret-token:#{@password}"
     end
 
-    # @return [String]
-    def access_token
-      @access_token ||= request_token
-    end
-
     # @param url [String]
     # @param token [String]
     # @param payload [Hash]
-    # @return [String]
-    def request(url, token: access_token, payload: nil)
+    # @return [Hash] The parsed JSON response.
+    # @raise [RequestError] If the backend responds with anything but 200 OK.
+    def request(url, token: auth_token, payload: nil)
       uri = URI(url)
       headers = {
         "Authorization" => "Bearer #{token}",
@@ -93,16 +93,30 @@ module Taler
         "User-Agent" => "Taler Ruby"
       }
 
+      response = http_request(uri, headers, payload)
+
+      # The merchant API answers 200 to every request this gem makes.
+      # Anything else explains a failure, including 202 which asks for
+      # two-factor authentication on the token endpoint.
+      # See: https://docs.taler.net/core/api-merchant.html
+      raise RequestError.new(response) unless response.is_a?(Net::HTTPOK)
+
+      JSON.parse(response.body)
+    end
+
+    # @param uri [URI]
+    # @param headers [Hash]
+    # @param payload [Hash]
+    # @return [Net::HTTPResponse]
+    def http_request(uri, headers, payload)
       if payload.nil?
-        body = Net::HTTP.get(uri, headers)
+        Net::HTTP.get_response(uri, headers)
       else
         headers["Content-Type"] = "application/json"
-        data = JSON.dump(payload)
-        response = Net::HTTP.post(uri, data, headers)
-        body = response.body
+        Net::HTTP.post(uri, JSON.dump(payload), headers)
       end
-
-      JSON.parse(body)
+    rescue => e
+      raise Error, e.message
     end
   end
 end

data/lib/taler/order.rb

@@ -27,6 +27,7 @@ module Taler
     # @param fulfillment_message [String] Text to display to the user after
     #   payment.
     # @return [String] The id of the new order.
+    # @raise [RequestError] If the backend rejects the request.
     def create(amount:, summary:, fulfillment_url: nil, fulfillment_message: nil)
       response = @client.create_order(
         amount:, summary:, fulfillment_url:, fulfillment_message:
@@ -57,6 +58,7 @@ module Taler
     #   Any simple type supported by JSON.
     # @example
     #   fetch("order_status") #=> "unpaid"
+    # @raise [RequestError] If the backend rejects the request.
     def fetch(key)
       reload unless @status
       @status.fetch(key)
@@ -68,6 +70,7 @@ module Taler
     # user interaction, you want to call this.
     #
     # @return [Hash] The order status returned by the backend.
+    # @raise [RequestError] If the backend rejects the request.
     def reload
       @status = @client.fetch_order(@id)
     end
@@ -78,6 +81,7 @@ module Taler
     # @param reason [String] Why are you refunding?
     #
     # @return [Hash] Response from the merchant backend.
+    # @raise [RequestError] If the backend rejects the request.
     def refund(refund:, reason:)
       @client.refund_order(@id, refund:, reason:)
     end

data/lib/taler/version.rb

@@ -2,5 +2,5 @@
 
 module Taler
   # @return [String]
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/taler.rb

@@ -8,4 +8,42 @@ require_relative "taler/version"
 module Taler
   # Base error class for errors raised in this module
   class Error < StandardError; end
+
+  # Raised when the merchant backend answers with anything but 200 OK.
+  #
+  # The backend explains errors with a JSON body like
+  # `{"code": 2015, "hint": "...", "detail": "..."}`. The hint is used
+  # as the error message. A body that is not JSON, like an HTML page
+  # from a proxy, is kept as text.
+  class RequestError < Error
+    # @return [Integer] The HTTP status code of the response.
+    attr_reader :status
+
+    # @return [Hash, String] The parsed JSON body or the raw body.
+    attr_reader :body
+
+    # @param response [Net::HTTPResponse]
+    def initialize(response)
+      @status = response.code.to_i
+      @body = error_body(response.body)
+      super("The Taler backend responded with #{status}: #{summary}")
+    end
+
+    private
+
+    # @return [String]
+    def summary
+      return body.fetch("hint") if body.is_a?(Hash) && body.key?("hint")
+
+      body.to_s.strip
+    end
+
+    # @param body [String]
+    # @return [Hash, String] The parsed JSON body, or the raw body if it isn't JSON.
+    def error_body(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+  end
 end

data/sig/taler.rbs

@@ -6,6 +6,31 @@ module Taler
   class Error < StandardError
   end
 
+  # Raised when the merchant backend answers with anything but 200 OK.
+  # 
+  # The backend explains errors with a JSON body like
+  # `{"code": 2015, "hint": "...", "detail": "..."}`. The hint is used
+  # as the error message. A body that is not JSON, like an HTML page
+  # from a proxy, is kept as text.
+  class RequestError < Taler::Error
+    # sord warn - Net::HTTPResponse wasn't able to be resolved to a constant in this project
+    # _@param_ `response`
+    def initialize: (Net::HTTPResponse response) -> void
+
+    def summary: () -> String
+
+    # _@param_ `body`
+    # 
+    # _@return_ — The parsed JSON body, or the raw body if it isn't JSON.
+    def error_body: (String body) -> (::Hash[untyped, untyped] | String)
+
+    # _@return_ — The HTTP status code of the response.
+    attr_reader status: Integer
+
+    # _@return_ — The parsed JSON body or the raw body.
+    attr_reader body: (::Hash[untyped, untyped] | String)
+  end
+
   # Order representation with convenient access to the merchant API.
   class Order
     # Connect an Order to the Taler merchant backend.
@@ -136,13 +161,22 @@ module Taler
 
     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
+    # 
+    # _@return_ — The parsed JSON response.
+    def request: (String url, ?token: String, ?payload: ::Hash[untyped, untyped]?) -> ::Hash[untyped, untyped]
+
+    # sord warn - URI wasn't able to be resolved to a constant in this project
+    # sord warn - Net::HTTPResponse wasn't able to be resolved to a constant in this project
+    # _@param_ `uri`
+    # 
+    # _@param_ `headers`
+    # 
+    # _@param_ `payload`
+    def http_request: (URI uri, ::Hash[untyped, untyped] headers, ::Hash[untyped, untyped] payload) -> Net::HTTPResponse
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: taler
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Maikel Linke