web_function 0.5.0 → 0.6.0

data/lib/web_function/pipeline.rb

@@ -1,4 +1,14 @@
+# frozen_string_literal: true
+
 module WebFunction
+  # A pipeline is a sequence of steps that are executed in order.
+  #
+  # @example
+  #   pipeline = WebFunction::Pipeline.new("https://pipe.example/exec")
+  #   pipeline.add_step({ url: "https://a", headers: {}, body: {} })
+  #   pipeline.add_step({ url: "https://b", headers: {}, body: {} })
+  #   pipeline.execute(returns: :all) # => [{ "a" => 1 }, { "b" => 2 }]
+  #
   class Pipeline
     def initialize(url)
       @url = url
@@ -6,6 +16,12 @@ module WebFunction
       @promises = []
     end
 
+    # Adds a step to the pipeline.
+    #
+    # @param step [Hash] The step to add
+    #
+    # @return [Promise] A new Promise instance
+    #
     def add_step(step)
       n = @promises.count
       promise = Promise.new(self, "$[#{n}]")
@@ -16,13 +32,20 @@ module WebFunction
       promise
     end
 
+    # Executes the pipeline.
+    #
+    # @param returns [String, Symbol] The return type or a JSONPath expression to return a specific value.
+    #
+    # @return [Object] The response returned by the pipeline.
+    #
     def execute(returns: :all)
       case returns
       when :all
-        responses = Endpoint.invoke(@url, args: {
+        responses = Request.execute(@url, args: {
           steps: @steps,
           returns: "$",
-        })
+        },
+        )
 
         responses.each_with_index do |response, index|
           @promises[index].value = response
@@ -32,10 +55,11 @@ module WebFunction
 
         responses
       when :last
-        response = Endpoint.invoke(@url, args: {
+        response = Request.execute(@url, args: {
           steps: @steps,
           returns: "$[-1:]",
-        })
+        },
+        )
 
         @promises.last.value = response
 
@@ -43,10 +67,11 @@ module WebFunction
 
         response
       else
-        response = Endpoint.invoke(@url, args: {
+        response = Request.execute(@url, args: {
           steps: @steps,
           returns: returns,
-        })
+        },
+        )
 
         reset!
 
@@ -54,6 +79,10 @@ module WebFunction
       end
     end
 
+    # Resets the pipeline.
+    #
+    # @return [void]
+    #
     def reset!
       @steps = []
       @promises = []

data/lib/web_function/promise.rb

@@ -1,4 +1,13 @@
+# frozen_string_literal: true
+
 module WebFunction
+  # A promise is a placeholder for a value that will be resolved later.
+  #
+  # @example
+  #   pipeline = WebFunction::Pipeline.new("https://pipe.example/exec")
+  #   promise = pipeline.add_step({})
+  #   promise.resolve # => { "a" => 1 }
+  #
   class Promise
     def initialize(pipeline, path)
       @pipeline = pipeline
@@ -6,19 +15,42 @@ module WebFunction
       @value = nil
     end
 
+    # A path is a JSONPath expression that can be used to resolve a value from a response.
+    #
+    # @example
+    #   path = WebFunction::Promise::Path.new("$[0]")
+    #   path.to_s # => "$[0]"
+    #   path[0] # => { "a" => 1 }
+    #
     class Path
       def initialize(path)
         @path = path
       end
 
+      # Returns the string representation of the path.
+      #
+      # @return [String] The string representation of the path
+      #
       def to_s
         @path
       end
 
+      # Returns the JSON representation of the path.
+      #
+      # @param args [Array] The arguments to pass to the JSON.generate method
+      #
+      # @return [String] The JSON representation of the path
+      #
       def to_json(*args)
         @path.to_json(*args)
       end
 
+      # Returns a new path with the given key.
+      #
+      # @param key [String, Symbol, Integer] The key to add to the path
+      #
+      # @return [Path] A new Path instance
+      #
       def [](key)
         case key
         when String, Symbol
@@ -30,13 +62,27 @@ module WebFunction
         end
       end
 
+      # Mutates the path with the given path.
+      #
+      # @param path [String] The path to mutate
+      #
+      # @return [Path] A new Path instance
+      #
       def mutate(path)
         Path.new(path)
       end
     end
 
+    # The value of the promise.
+    #
+    # @return [Object] The value of the promise
+    #
     attr_writer :value
 
+    # Returns the string representation of the promise.
+    #
+    # @return [String] The string representation of the promise
+    #
     def to_s
       if @value
         @value.to_s
@@ -45,6 +91,12 @@ module WebFunction
       end
     end
 
+    # Returns the JSON representation of the promise.
+    #
+    # @param args [Array] The arguments to pass to the JSON.generate method
+    #
+    # @return [String] The JSON representation of the promise
+    #
     def to_json(*args)
       if @value
         @value.to_json(*args)
@@ -53,6 +105,12 @@ module WebFunction
       end
     end
 
+    # Returns the value of the promise at the given key.
+    #
+    # @param key [String, Symbol, Integer] The key to resolve
+    #
+    # @return [Object] The value of the promise at the given key
+    #
     def [](key)
       if @value
         @value[key]
@@ -61,6 +119,12 @@ module WebFunction
       end
     end
 
+    # Returns the value of the promise.
+    #
+    # @raise [WebFunction::UnresolvedPromiseError] If the promise is not resolved
+    #
+    # @return [Object] The value of the promise
+    #
     def value
       unless @value
         raise WebFunction::UnresolvedPromiseError
@@ -69,6 +133,10 @@ module WebFunction
       @value
     end
 
+    # Resolves the promise.
+    #
+    # @return [Object] The value of the promise
+    #
     def resolve
       if @value
         return @value

data/lib/web_function/request.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # A request allows you to invoke a Web Function endpoint via an HTTP client.
+  #
+  # @example
+  #   request = WebFunction::Request.new("https://api.example.com/endpoint")
+  #   request.execute # => { "a" => 1 }
+  #
+  class Request
+    def initialize(url, bearer_auth: nil, version: nil, args: {})
+      @url = url
+      @bearer_auth = bearer_auth
+      @version = version
+      @args = args || {}
+    end
+
+    class << self
+      # The HTTP client used to execute the request.
+      #
+      # To provide a custom HTTP client instead of the default (which uses Excon),
+      # set this to any object responding to #call. For example, a Proc or a lambda.
+      #
+      # The contract is:
+      #
+      #     client.call(url, headers, body)
+      #
+      # - url:    [String] The full URL to post to (not just the hostname or path).
+      # - headers:[Hash<String,String>] HTTP headers, e.g. { "Content-Type" => "application/json" }
+      # - body:   [String] The JSON body to post.
+      #
+      # The client must return a two-element Array: [status, body]:
+      #
+      # - status: [Integer] HTTP status code (e.g. 200, 400, 500)
+      # - body:   [String] Raw response body as a string
+      #
+      # @example
+      #   WebFunction::Endpoint.http_client = ->(url, headers, args) {
+      #     http_response = MyHTTP.post(url, headers: headers, body: JSON.generate(args))
+      #     [http_response.status, http_response.body]
+      #   }
+      #
+      attr_accessor :http_client
+
+      # Executes a request.
+      #
+      # @param url [String] The URL of the request
+      # @param bearer_auth [String] The bearer authentication token
+      # @param version [String] The API version to use
+      # @param args [Hash] The arguments to send to the request
+      #
+      # @return [Object] The response returned by the request
+      def execute(url, bearer_auth: nil, version: nil, args: {})
+        request = new(url, bearer_auth: bearer_auth, version: version, args: args)
+        request.execute
+      end
+    end
+
+    self.http_client = proc do |url, headers, body|
+      response = Excon.post(url, headers: headers, body: body)
+      [response.status, response.body]
+    end
+
+    # The URL of the request.
+    #
+    # @return [String] The URL of the request
+    #
+    attr_reader :url
+
+    # The bearer authentication token.
+    #
+    # @return [String] The bearer authentication token
+    #
+    attr_reader :bearer_auth
+
+    # The API version to use.
+    #
+    # @return [String] The API version to use
+    #
+    attr_reader :version
+
+    # The arguments to send to the request.
+    #
+    # @return [Hash] The arguments to send to the request
+    #
+    attr_reader :args
+
+    # The headers to send to the request.
+    #
+    # @return [Hash] The headers to send to the request
+    #
+    def headers
+      headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json",
+        "User-Agent": "webfunction/#{WebFunction::VERSION}",
+      }
+
+      if @bearer_auth
+        headers["Authorization"] = "Bearer #{@bearer_auth}"
+      end
+
+      if @version
+        headers["Api-Version"] = @version
+      end
+
+      headers
+    end
+
+    # Returns the request as a pipeline step.
+    #
+    # @return [Hash] The request as a pipeline step
+    #
+    def as_pipeline_step
+      {
+        url: @url,
+        headers: headers,
+        body: @args,
+      }
+    end
+
+    # Executes the request.
+    #
+    # @raise [WebFunction::UnexpectedStatusCodeError] If the status code is not 200 or 400
+    # @raise [WebFunction::JsonParseError] If the response is not valid JSON
+    # @raise [WebFunction::BadRequestError] If the response is a bad request
+    #
+    # @return [Object] The response returned by the request
+    #
+    def execute
+      status, body = self.class.http_client.call(@url, headers, JSON.generate(@args))
+
+      unless [200, 400].include?(status)
+        raise WebFunction::UnexpectedStatusCodeError.new("Unexpected status code (#{status})",
+          details: {
+            status_code: status,
+            raw_body: body,
+          },
+        )
+      end
+
+      begin
+        result = JSON.parse(body)
+      rescue JSON::ParserError => e
+        raise WebFunction::JsonParseError.new(e.message,
+          details: {
+            status_code: status,
+            raw_body: body,
+            original_exception: e,
+          },
+        )
+      end
+
+      if status == 400
+        code = "WFN_BAD_REQUEST_ERROR"
+        message = "Bad request"
+        details = { body: result }
+
+        if result.is_a?(Array) && result.length == 3 && result[0].is_a?(String) && result[1].is_a?(String)
+          code = result[0]
+          message = result[1]
+          details = result[2]
+        end
+
+        raise WebFunction::BadRequestError.new(message, code: code, details: details)
+      end
+
+      result
+    end
+  end
+end

data/lib/web_function/utils.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # Internal utility methods.
+  #
+  # @api private
+  #
+  module Utils
+    module_function
+
+    # Normalizes a collection. Yields each item to the block if a block is given, otherwise returns the item.
+    # Any `nil` items are removed.
+    #
+    # @param collection [Array] The collection to normalize
+    #
+    # @return [Array] The normalized array
+    #
+    def normalize_array(collection)
+      unless collection.is_a?(Array)
+        return []
+      end
+
+      items = collection.map do |item|
+        if block_given?
+          yield item
+        else
+          item
+        end
+      end
+
+      items.compact
+    end
+
+    # Normalizes an array of strings. Uses #normalize_array under the hood.
+    #
+    # @param collection [Array] The collection to normalize
+    #
+    # @return [Array] The normalized array
+    #
+    def normalize_array_of_strings(collection)
+      normalize_array(collection) { |item| item.to_s }
+    end
+  end
+end

data/lib/web_function/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WebFunction
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/web_function.rb

@@ -5,7 +5,9 @@ require "json"
 require "uri"
 
 require_relative "web_function/version"
+require_relative "web_function/request"
 require_relative "web_function/client"
+require_relative "web_function/flaggable"
 require_relative "web_function/package"
 require_relative "web_function/endpoint"
 require_relative "web_function/argument"
@@ -13,27 +15,35 @@ require_relative "web_function/attribute"
 require_relative "web_function/documented_error"
 require_relative "web_function/pipeline"
 require_relative "web_function/promise"
+require_relative "web_function/utils"
 
 module WebFunction
+  # A base error class for WebFunction. All errors inherit from this class.
+  #
+  # @api private
+  #
   class Error < StandardError
     attr_reader :code, :details
 
-    def initialize(message = nil, code: self.class.name, details: nil)
+    def initialize(message = nil, code: self.class.error_code, details: nil)
       super(message)
       @code = code
       @details = details
     end
-  end
-
-  class UnresolvedPromiseError < Error
-  end
 
-  class UnexpectedStatusCodeError < Error
-  end
-
-  class JsonParseError < Error
+    # Returns the error code for the error. Used as default error code if no code is provided.
+    #
+    # @return [String] The error code
+    #
+    def self.error_code
+      name.sub(/^WebFunction::/, "WFN_")
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .upcase
+    end
   end
 
-  class BadRequestError < Error
-  end
+  UnresolvedPromiseError = Class.new(Error)
+  UnexpectedStatusCodeError = Class.new(Error)
+  JsonParseError = Class.new(Error)
+  BadRequestError = Class.new(Error)
 end

data/test.rb

@@ -0,0 +1,43 @@
+require "web_function"
+require "base64"
+
+pipeline = WebFunction::Pipeline.new("http://localhost:55001/api/process-pipeline")
+
+sdk = WebFunction::Client.from_package_endpoint("http://localhost:55001/api/sdk",
+  pipeline: pipeline,
+)
+
+merchant = WebFunction::Client.from_package_endpoint("http://localhost:55001/api/merchants",
+  bearer_auth: "reservepay_u6BHU4diPq7MVZCUJu7Ppu81nTrfYP1fMYVS",
+  pipeline: pipeline,
+)
+
+installations = merchant.list_installations
+payment_session_id = sdk.select_payment_method(
+  merchant_id: "11",
+  installation_id: installations[0]["installation_id"],
+  amount: 10000,
+  currency: "THB",
+  payment_method: "PROMPTPAY",
+)
+payment_id = merchant.initiate_payment_flow(
+  amount: 10000,
+  currency: "THB",
+  capture: true,
+  return_url: "https://reservepay.com/",
+  payment_session_id: payment_session_id,
+)
+payment = merchant.find_payment(payment_id: payment_id)
+
+p payment.resolve
+p payment_session_id
+
+sleep 1
+
+qr_data = sdk.retrieve_qr_data(
+  merchant_id: "11",
+  installation_id: installations[0]["installation_id"],
+  payment_session_id: payment_session_id,
+)
+
+p Base64.decode64(qr_data.resolve)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: web_function
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Robin Clart
@@ -60,11 +60,15 @@ files:
 - lib/web_function/client.rb
 - lib/web_function/documented_error.rb
 - lib/web_function/endpoint.rb
+- lib/web_function/flaggable.rb
 - lib/web_function/package.rb
 - lib/web_function/pipeline.rb
 - lib/web_function/promise.rb
+- lib/web_function/request.rb
+- lib/web_function/utils.rb
 - lib/web_function/version.rb
 - sig/web_function.rbs
+- test.rb
 homepage: https://github.com/robinclart/web_function
 licenses:
 - MIT