web_function 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc10b3e4f558c7bec819e5f9029f672df3e37e5e5c66790df2e1159d2b06acec
-  data.tar.gz: deb73a647c14e886ef7b3be4e69a5a080fead74ef00119b56af86b57462452d5
+  metadata.gz: c451f0b269e4441e7982d789b8fb4a4d827543e9d9f8769aa2bc4350a667435b
+  data.tar.gz: 1fe79584e5f3cd31f5792c63c7fed415cc999ccafbf736bb41f8a024c0c65690
 SHA512:
-  metadata.gz: 37b3060aefd75b936ce0c5e9f3e1ec7e20f84ab118840f262d4631b020cebba24aaa9df251c1bb37560ff881df42412c688b6c6f519bacfe377aa4a5230676d3
-  data.tar.gz: 6240884af37b04edf66426653b9d8de19445be9817c93b624bccbb2ed0ca290ccce6dd98669ea2c2d7c114c8ec03c4b6c0fee1871c33e36fb7aeeb65d92517fb
+  metadata.gz: 07f4280c1e265f99898667f4860f1772088ae729fc41080ab27e2f6db1bd88d3611efc5314d2ab6b43c222c38be2f612772fd4167c41f8a5d17db6dd06aefa7c
+  data.tar.gz: 0b529bea38f2866549209a7d01fa5a8b126b17b79c4791ebf60ebd2407136dfabc7657c82efebea3275bbf9ad9b686943d797ccd3b397e2c6e124aab338a307f

data/exe/wfn

@@ -2,3 +2,38 @@
 # frozen_string_literal: true
 
 require "web_function"
+require "json"
+
+# Usage:
+#   wfn call --auth token endpoint_url key1=value1 [key2=value2 ...]
+
+auth_token = nil
+auth_idx = ARGV.index("--auth")
+if auth_idx
+  auth_token = ARGV[auth_idx + 1]
+  ARGV.slice!(auth_idx, 2)
+end
+
+command = ARGV[0]
+
+case command
+when "call"
+  endpoint_url = ARGV[1]
+  args = JSON.parse(ARGV[2] || "{}")
+
+  begin
+    response = WebFunction::Endpoint.invoke(endpoint_url, bearer_auth: auth_token, args: args)
+    puts JSON.pretty_generate(response)
+  rescue WebFunction::Error => e
+    puts e
+    warn "error: [#{e.code}] #{e.message}"
+    warn ""
+    if e.details
+      warn JSON.pretty_generate(e.details).lines.map { |line| "|  #{line}" }.join
+    end
+    exit 2
+  end
+else
+  warn "Usage:\n  wfn docs package_url endpoint_name\n  wfn call --auth token endpoint_url key1=value1 [key2=value2 ...]"
+  exit 1
+end

data/lib/web_function/argument.rb

@@ -1,29 +1,107 @@
 # frozen_string_literal: true
 
 module WebFunction
+  # # Argument
+  #
+  # Arguments used by Web Function endpoints to define its input parameters.
+  #
+  # See the [arguments section][0] on the Web Function website for more details.
+  #
+  # [0]: https://webfunction.org/package#arguments
+  #
   class Argument
     def initialize(argument)
       @argument = argument
     end
 
+    # ## Name
+    #
+    # The name of the argument.
+    #
+    # @return [String]
+    #
     def name
       @argument["name"]
     end
 
+    # ## Type
+    #
+    # The type of the argument. It must be one of:
+    #   - object
+    #   - array
+    #   - string
+    #   - number
+    #   - boolean
+    #
+    # @return [String]
+    #
     def type
       @argument["type"]
     end
 
+    # ## Hint
+    #
+    # The hint of the argument
+    #
+    # See the [hints section][1] on the Web Function website for the full list 
+    # of possible hints.
+    #
+    # @return [String]
+    #
+    # [1]: https://webfunction.org/package#hints
+    #
+    def hint
+      @argument["hint"]
+    end
+
+    # ## Group
+    #
+    # A name used to categorize or group similar arguments together. This 
+    # should be used by documentation tools to organize related arguments.
+    #
+    # @return [String]
+    #
+    def group
+      @argument["group"]
+    end
+
+    # ## Choices
+    #
+    # An array specifying the exact, case-sensitive values that are permitted
+    # for this argument. Each value in the choices array must conform to the
+    # data type specified in the argument's type key.
+    #
+    # Note that if the argument type is array, choices may contain strings or
+    # numbers representing the allowed values that can be included in the array.
+    #
+    # @return [Array]
+    #
     def choices
-      @argument["choices"]
+      [*@argument["choices"]]
     end
 
+    # ## Flags
+    #
+    # List of argument flags. See the [available flags section][2] on the Web
+    # Function website for a complete list of flags available at the
+    # argument level.
+    #
+    # @return [Array<String>]
+    #
+    # [2]: https://webfunction.org/package#available-flags
+    #
     def flags
-      @argument["flags"]
+      [*@argument["flags"]].map { |flag| flag.to_s }
     end
 
+    # ## Docs
+    #
+    # Description of the argument. It must be formatted as markdown.
+    #
+    # @return [String]
+    #
     def docs
-      @argument["docs"]
+      @argument["docs"].to_s
     end
   end
 end

data/lib/web_function/attribute.rb

@@ -1,29 +1,100 @@
 # frozen_string_literal: true
 
 module WebFunction
+  # # Attribute
+  #
+  # An Attribute defines an output field that may be produced and returned by a
+  # Web Function endpoint.
+  #
+  # See the [attributes section][0] on the Web Function website for more
+  # details about attribute definitions, recognized keys, and usage.
+  #
+  # [0]: https://webfunction.org/package#attributes
+  #
   class Attribute
     def initialize(attribute)
       @attribute = attribute
     end
 
+    # ## Name
+    #
+    # The name of the attribute as it will appear in the endpoint's output
+    # object.
+    #
+    # @return [String]
+    #
     def name
       @attribute["name"]
     end
 
+    # ## Type
+    #
+    # The type of value returned for this attribute. Must be one of:
+    #   - object
+    #   - array
+    #   - string
+    #   - number
+    #   - boolean
+    #
+    # This is a required string.
+    #
+    # @return [String]
+    #
     def type
       @attribute["type"]
     end
 
+    # ## Hint
+    #
+    # A string hinting about the semantics of this attribute. See the
+    # [hints section][1] for possible values and documentation tooling guidance.
+    #
+    # [1]: https://webfunction.org/package#hints
+    #
+    # @return [String, nil]
+    #
+    def hint
+      @attribute["hint"]
+    end
+
+    # ## Values
+    #
+    # An array specifying the exact, case-sensitive values that may be returned 
+    # for this attribute. Each value in the values array must conform to the 
+    # data type specified in the "type" key.
+    #
+    # This is useful for attributes that can only take a select set of values
+    # (enums or constants).
+    #
+    # @return [Array]
+    #
     def values
-      @attribute["values"]
+      [*@attribute["values"]]
     end
 
+    # ## Flags
+    #
+    # An array of attribute flags. Flags describe special characteristics or 
+    # behaviors of attributes. See the [available flags section][2] for 
+    # complete list and documentation.
+    #
+    # [2]: https://webfunction.org/package#available-flags
+    #
+    # @return [Array<String>]
+    #
     def flags
-      @attribute["flags"]
+      [*@attribute["flags"]].map(&:to_s)
     end
 
+    # ## Docs
+    #
+    # A markdown string describing this attribute and its purpose in the output 
+    # object. Used by documentation tools, and highly recommended.
+    #
+    # @return [String]
+    #
     def docs
-      @attribute["docs"]
+      @attribute["docs"].to_s
     end
   end
 end

data/lib/web_function/client.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 module WebFunction
-  class Client
+  # # Client
+  #
+  # A Client is a wrapper around a Web Function package that provides a 
+  # convenient interface for invoking endpoints.
+  #
+  # @example
+  #   client = WebFunction::Client.from_package_endpoint("https://api.webfunction.com/package")
+  #   client.list_items(a: "b") # => { "c" => "d" }
+  #
+  class Client < BasicObject
     def initialize(package, bearer_auth: nil, pipeline: nil)
       @package = package
       @endpoints = package.endpoints.to_h { |e| [e.name.gsub("-", "_").to_sym, e] }
@@ -11,42 +20,53 @@ module WebFunction
 
     attr_reader :package
 
+    # ## Instantiates a new Client from a package endpoint
+    #
+    # Creates a new Client from a package endpoint.
+    #
+    # @param url [String] The URL of the package endpoint
+    # @param bearer_auth [String] The bearer authentication token
+    # @param pipeline_url [String] The URL of the pipeline endpoint
+    # @param pipeline [Pipeline] The pipeline to use
+    #
+    # @return [Client] A new Client instance
+    #
     def self.from_package_endpoint(url, bearer_auth: nil, pipeline_url: nil, pipeline: nil)
-      response = Endpoint.invoke(url, bearer_auth: bearer_auth)
-      package = Package.new(response)
+      response = ::WebFunction::Endpoint.invoke(url, bearer_auth: bearer_auth)
+      package = ::WebFunction::Package.new(response)
 
-      if pipeline.is_a?(String)
-        pipeline = WebFunction::Pipeline.new(pipeline)
+      if pipeline_url.is_a?(::String)
+        pipeline = ::WebFunction::Pipeline.new(pipeline_url)
       end
 
       new(package, bearer_auth: bearer_auth, pipeline: pipeline)
     end
 
-    def methods
+    def methods #:nodoc:
       super + @endpoints.keys
     end
 
-    def respond_to_missing?(method_name, include_private = false)
+    def respond_to_missing?(method_name, include_private = false) #:nodoc:
       @endpoints[method_name] || super
     end
 
-    def method_missing(method_name, *args)
+    def method_missing(method_name, *args) #:nodoc:
       endpoint = @endpoints[method_name]
 
       unless endpoint
         super
       end
 
-      url = URI.join(@package.base_url, endpoint.name).to_s
+      url = ::URI.join(@package.base_url, endpoint.name).to_s
       args = args.first
 
       if @pipeline
-        step = Endpoint.invoke(url, bearer_auth: @bearer_auth, args: args, as_step: true)
+        step = ::WebFunction::Endpoint.step(url, bearer_auth: @bearer_auth, args: args)
         promise = @pipeline.add_step(step)
         return promise
       end
 
-      Endpoint.invoke(url, bearer_auth: @bearer_auth, args: args)
+      ::WebFunction::Endpoint.invoke(url, bearer_auth: @bearer_auth, args: args)
     end
   end
 end

data/lib/web_function/documented_error.rb

@@ -1,15 +1,39 @@
 module WebFunction
+  # # DocumentedError
+  #
+  # Represents an error definition as described in a Web Function package.
+  #
+  # An error definition documents the possible errors that an endpoint might return,
+  # including a machine-readable error code and a human-readable description.
+  #
+  # See the [error definition documentation][0] on the Web Function website for more details,
+  # including recognized keys and usage recommendations.
+  #
+  # [0]: https://webfunction.org/package#error-definition
+  #
   class DocumentedError
     def initialize(error)
       @error = error
     end
 
+    # ## Code
+    #
+    # The code of the error.
+    #
+    # @return [String]
+    #
     def code
       @error["code"]
     end
 
+    # ## Docs
+    #
+    # The documentation of the error.
+    #
+    # @return [String]
+    #
     def docs
-      @error["docs"]
+      @error["docs"].to_s
     end
   end
-end
+end

data/lib/web_function/endpoint.rb

@@ -1,67 +1,155 @@
 # frozen_string_literal: true
 
 module WebFunction
+  # # Endpoint
+  #
+  # Represents an endpoint as described in a Web Function package.
+  #
+  # An endpoint defines an operation that can be performed via a Web Function API.
+  # Endpoints declare their name, documentation, arguments (inputs), attributes (outputs), and
+  # the possible errors that may occur when invoking them.
+  #
+  # Endpoints are described as objects in each package under the `"endpoints"` key.
+  # For more information, see:
+  # - [Web Function package docs](https://webfunction.org/package)
+  # - [Web Function endpoint docs](https://webfunction.org/endpoint)
+  #
+  # This class provides methods for accessing endpoint metadata (name, docs, arguments, attributes, errors)
+  # and supports invocation via HTTP.
+  #
+  # Typical tasks include:
+  # - Querying endpoint name or documentation
+  # - Enumerating the arguments or attributes definitions
+  # - Invoking the endpoint through HTTP using required inputs
+  #
+  # See: https://webfunction.org/endpoint for more details on endpoint structure and contract.
+  #
   class Endpoint
     def initialize(endpoint)
       @endpoint = endpoint
     end
 
-    def self.invoke(url, bearer_auth: nil, args: {}, as_step: false)
-      headers = {
-        "Content-Type": "application/json",
-        "Accept": "application/json",
-        "User-Agent": "webfunction/#{WebFunction::VERSION}",
-      }
-
-      if args.nil?
-        args = {}
+    class << self
+      # ## HTTP client getter
+      #
+      # The HTTP client used to invoke the endpoint.
+      #
+      # @return [Proc]
+      #
+      def http_client
+        @http_client ||= proc do |url, headers, body|
+          response = Excon.post(url,
+            headers: headers,
+            body: body,
+          )
+          [response.status, response.body]
+        end
       end
 
-      if bearer_auth
-        headers["Authorization"] = "Bearer #{bearer_auth}"
-      end
+      # ## HTTP client setter
+      #
+      # Sets the HTTP client used to invoke the endpoint.
+      #
+      # To provide a custom HTTP client instead of the default (which uses Excon),
+      # set this to any object responding to #call or a Proc/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]
+      #   }
+      #
+      # @param http_client [Proc,#call] The new HTTP client to use.
+      #
+      attr_writer :http_client
+
+      def step(url, bearer_auth: nil, args: {})
+        headers = {
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "User-Agent": "webfunction/#{WebFunction::VERSION}",
+        }
+
+        if args.nil?
+          args = {}
+        end
+
+        if bearer_auth
+          headers["Authorization"] = "Bearer #{bearer_auth}"
+        end
 
-      if as_step
-        return {
+        {
           url: url,
           headers: headers,
           body: args,
         }
       end
 
-      response = Excon.post(url,
-        headers: headers,
-        body: JSON.generate(args),
-      )
+      def invoke(url, bearer_auth: nil, args: {})
+        headers = {
+          "Content-Type": "application/json",
+          "Accept": "application/json",
+          "User-Agent": "webfunction/#{WebFunction::VERSION}",
+        }
+
+        if args.nil?
+          args = {}
+        end
+
+        if bearer_auth
+          headers["Authorization"] = "Bearer #{bearer_auth}"
+        end
+
+        status, body = 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
 
-      result = JSON.parse(response.body)
+        if status == 400
+          code = "BAD_REQUEST"
+          message = "Bad request"
+          details = { body: result }
 
-      if response.status == 400
-        case result
-        when Array
-          if result.length == 3 && result[0].is_a?(String) && result[1].is_a?(String)
+          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]
-
-            raise WebFunction::Error.new(message, code: code, details: details)
-          else
-            raise WebFunction::Error.new("Bad request", details: result)
           end
-        when String
-          raise WebFunction::Error.new(result)
-        else
-          raise WebFunction::Error.new("Bad request", details: result)
+
+          raise WebFunction::BadRequestError.new(message, code: code, details: details)
         end
-      end
 
-      if response.status != 200
-        raise WebFunction::Error.new("Unexpected status code [#{response.status}]")
+        result
       end
-
-      result
-    rescue JSON::ParserError => e
-      raise WebFunction::Error.new("Response cannot be parsed", details: {})
     end
 
     def name
@@ -69,11 +157,15 @@ module WebFunction
     end
 
     def returns
-      @endpoint["returns"]
+      [*@endpoint["returns"]].map { |type| type.to_s }
+    end
+
+    def hints
+      [*@endpoint["hints"]].map { |hint| hint.to_s }
     end
 
     def flags
-      @endpoint["flags"]
+      [*@endpoint["flags"]].map { |flag| flag.to_s }
     end
 
     def group
@@ -81,7 +173,7 @@ module WebFunction
     end
 
     def docs
-      @endpoint["docs"]
+      @endpoint["docs"].to_s
     end
 
     def arguments
@@ -89,7 +181,17 @@ module WebFunction
         return []
       end
 
-      @endpoint["arguments"].map { |argument| Argument.new(argument) }
+      @endpoint["arguments"].map do |argument|
+        unless argument.is_a?(Hash)
+          next
+        end
+
+        unless argument["name"]
+          next
+        end
+
+        Argument.new(argument)
+      end
     end
 
     def attributes
@@ -97,7 +199,17 @@ module WebFunction
         return []
       end
 
-      @endpoint["attributes"].map { |attribute| Attribute.new(attribute) }
+      @endpoint["attributes"].map do |attribute|
+        unless attribute.is_a?(Hash)
+          next
+        end
+
+        unless attribute["name"]
+          next
+        end
+
+        Attribute.new(attribute)
+      end
     end
 
     def errors
@@ -105,7 +217,17 @@ module WebFunction
         return []
       end
 
-      @endpoint["errors"].map { |error| DocumentedError.new(error) }
+      @endpoint["errors"].map do |error|
+        unless error.is_a?(Hash)
+          next
+        end
+
+        unless error["code"]
+          next
+        end
+
+        DocumentedError.new(error)
+      end
     end
   end
 end

data/lib/web_function/package.rb

@@ -15,11 +15,17 @@ module WebFunction
     end
 
     def flags
-      @package["flags"]
+      unless @package["flags"].is_a?(Array)
+        return []
+      end
+
+      @package["flags"].each do |flag|
+        flag.to_s
+      end
     end
 
     def docs
-      @package["docs"]
+      @package["docs"].to_s
     end
 
     def endpoints
@@ -27,7 +33,17 @@ module WebFunction
         return []
       end
 
-      @package["endpoints"].map { |endpoint| Endpoint.new(endpoint) }
+      @package["endpoints"].map do |endpoint|
+        unless endpoint.is_a?(Hash)
+          next
+        end
+
+        unless endpoint["name"]
+          next
+        end
+
+        Endpoint.new(endpoint)
+      end
     end
 
     def errors
@@ -35,7 +51,17 @@ module WebFunction
         return []
       end
 
-      @package["errors"].map { |error| DocumentedError.new(error) }
+      @package["errors"].map do |error|
+        unless error.is_a?(Hash)
+          next
+        end
+
+        unless error["code"]
+          next
+        end
+
+        DocumentedError.new(error)
+      end
     end
   end
 end

data/lib/web_function/promise.rb

@@ -63,7 +63,7 @@ module WebFunction
 
     def value
       unless @value
-        raise UnresolvedPromise
+        raise WebFunction::UnresolvedPromiseError
       end
 
       @value

data/lib/web_function/version.rb

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

data/lib/web_function.rb

@@ -15,15 +15,25 @@ require_relative "web_function/pipeline"
 require_relative "web_function/promise"
 
 module WebFunction
-  UnresolvedPromise = Class.new(StandardError)
-
   class Error < StandardError
     attr_reader :code, :details
 
-    def initialize(message = nil, code: nil, details: nil)
+    def initialize(message = nil, code: self.class.name, details: nil)
       super(message)
       @code = code
       @details = details
     end
   end
+
+  class UnresolvedPromiseError < Error
+  end
+
+  class UnexpectedStatusCodeError < Error
+  end
+
+  class JsonParseError < Error
+  end
+
+  class BadRequestError < Error
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: web_function
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Robin Clart
@@ -88,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.5
+rubygems_version: 4.0.11
 specification_version: 4
 summary: A Web Function Client for Ruby
 test_files: []