taler 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96d1418bd3c05ff024f0f3d8e478d9f5e8e2b3f69b05f900ae7c25306fd43d44
-  data.tar.gz: d3f96d79ced6d329da2a79888a99cc7ecf4bc15ae1b4f8c13e2c776895265040
+  metadata.gz: 2264b54990f6df1015504ea8e2d51e9e0f3f9e8fb0d2e6948e32b900e4c899dd
+  data.tar.gz: ae655bb16c4a6d5e9aab5c5da7051d19895232388c2709b3d51e67f040137b0e
 SHA512:
-  metadata.gz: 48c2d8cb20973d02cbb00117244c9820046da27d91f91bf96d4167749b8fd3b5fc8061e8782ec66d97036c6b1d0f99d37c309484198603837cbd381739809796
-  data.tar.gz: 8a5c1273e9615eb168fa5a3aa6a2fa14f072c07044ca689720ede647b7ee54ac0bc3052800bbd56590130c0e38cac10705a0f944ef9adf88153de5004f1ff91c
+  metadata.gz: '0718fc34e186d2a5af60bad022efa7362eddcc4844b579aa417f43565b5004a0ddbfa1de83148540d6555dcd52f87bb7a09cfdf60d1b1dc90cba70ae0a35c50e'
+  data.tar.gz: 3f5b4abddbd440dd5df338aa0269b91360e3ed8cb8a91dd0e23a002b5d2b95b83cb80ec0cdba3beb3eae87dab31949a0037e6c8d98dff1d8a42def2fd180afec

data/.yardopts

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

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-10-14
+## [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,59 @@
 # 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
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+```rb
+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.
 
-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).
+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).
 
 ## 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,6 +4,9 @@ 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
     def initialize(backend_url, password)
       @backend_url = backend_url
@@ -17,24 +20,33 @@ module Taler
       result.fetch("token")
     end
 
-    def create_order(amount, summary, fulfillment_url)
+    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
 
+    def order_status_url(order_id)
+      "#{@backend_url}/orders/#{order_id}"
+    end
+
     def fetch_order(order_id)
       url = "#{@backend_url}/private/orders/#{order_id}"
       request(url)
     end
 
+    def refund_order(order_id, refund:, reason:)
+      url = "#{@backend_url}/private/orders/#{order_id}/refund"
+      payload = {refund:, reason:}
+      request(url, payload:)
+    end
+
     private
 
     def auth_token

data/lib/taler/order.rb

@@ -0,0 +1,68 @@
+# 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.
+    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.
+    #
+    # @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.
+    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,TrueClass,FalseClass] The value of the field.
+    #   Any simple type supported by JSON.
+    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.
+    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
+  end
+end

data/lib/taler/version.rb

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

data/lib/taler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "taler/client"
+require_relative "taler/order"
 require_relative "taler/version"
 
 module Taler

data/sig/client.rbs

@@ -0,0 +1,23 @@
+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

metadata

@@ -1,14 +1,127 @@
 --- !ruby/object:Gem::Specification
 name: taler
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.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: 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'
+description: Create and refund orders through the Taler merchant backend API.
 email:
 - maikel@email.org.au
 executables: []
@@ -17,13 +130,16 @@ 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/client.rbs
 - sig/taler.rbs
 homepage: https://github.com/openfoodfoundation/taler-ruby
 licenses:
@@ -38,7 +154,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="