web_function 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c451f0b269e4441e7982d789b8fb4a4d827543e9d9f8769aa2bc4350a667435b
-  data.tar.gz: 1fe79584e5f3cd31f5792c63c7fed415cc999ccafbf736bb41f8a024c0c65690
+  metadata.gz: c025fe8ca089b9531bc819d3154438bb29eb0b5fa823509b212fb23858403b5f
+  data.tar.gz: 6e2efbc2c7a4ebaef81ef95b8485b8822666a01967ebb46a3220ddab2caf26a1
 SHA512:
-  metadata.gz: 07f4280c1e265f99898667f4860f1772088ae729fc41080ab27e2f6db1bd88d3611efc5314d2ab6b43c222c38be2f612772fd4167c41f8a5d17db6dd06aefa7c
-  data.tar.gz: 0b529bea38f2866549209a7d01fa5a8b126b17b79c4791ebf60ebd2407136dfabc7657c82efebea3275bbf9ad9b686943d797ccd3b397e2c6e124aab338a307f
+  metadata.gz: acbc56f7b1b5ec89c17eb8f44699197ded36a0c3db4e722b57087bf164c0fe1f2a3c62e15223971e488721008891ce1714d2b2ce8a82dd0267b950694e8b4a46
+  data.tar.gz: 9028501396902aa1adb0ebe548eaa4f16bf9065c11e3777512ae5ef31652e9d007dffa5b2bdff60c95c5bb451221145b6a5e08d0bd73a89e34befe73db534597

data/exe/wfn

@@ -8,10 +8,17 @@ require "json"
 #   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)
+auth_index = ARGV.index("--auth")
+if auth_index
+  auth_token = ARGV[auth_index + 1]
+  ARGV.slice!(auth_index, 2)
+end
+
+version = nil
+version_index = ARGV.index("--version")
+if version_index
+  version = ARGV[version_index + 1]
+  ARGV.slice!(version_index, 2)
 end
 
 command = ARGV[0]
@@ -22,7 +29,7 @@ when "call"
   args = JSON.parse(ARGV[2] || "{}")
 
   begin
-    response = WebFunction::Endpoint.invoke(endpoint_url, bearer_auth: auth_token, args: args)
+    response = WebFunction::Request.execute(endpoint_url, bearer_auth: auth_token, version: version, args: args)
     puts JSON.pretty_generate(response)
   rescue WebFunction::Error => e
     puts e

data/lib/web_function/argument.rb

@@ -1,107 +1,135 @@
 # frozen_string_literal: true
 
 module WebFunction
-  # # Argument
-  #
-  # Arguments used by Web Function endpoints to define its input parameters.
+  # Arguments are used to define Web Function {Endpoint} request 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
+    include Flaggable
+
+    def initialize(name:, type:, hint: nil, group: nil, choices: [], flags: [], docs: nil)
+      @name = name
+      @type = type
+      @hint = hint
+      @group = group
+      @choices = choices
+      @flags = flags
+      @docs = docs.to_s
+    end
+
+    class << self
+      # Instantiate a new Argument from a hash, typically coming from a {Package}.
+      #
+      # @param argument [Hash]
+      #
+      # @return [Argument, nil]
+      #
+      def from_hash(argument)
+        unless argument.is_a?(Hash)
+          return
+        end
+
+        unless argument["name"]
+          return
+        end
+
+        unless argument["type"]
+          return
+        end
+
+        new(
+          name: argument["name"],
+          type: argument["type"],
+          hint: argument["hint"],
+          group: argument["group"],
+          choices: [*argument["choices"]],
+          flags: Utils.normalize_array_of_strings(argument["flags"]),
+          docs: argument["docs"],
+        )
+      end
+
+      # Instantiate a collection of Argument from an array of hash, typically coming from a {Package}. Uses
+      # {Argument#from_hash} under the hood.
+      #
+      # @param arguments [Array<Hash>]
+      #
+      # @return [Array<Argument>]
+      #
+      def from_array(arguments)
+        Utils.normalize_array arguments do |argument|
+          from_hash(argument)
+        end
+      end
     end
 
-    # ## Name
-    #
     # The name of the argument.
     #
     # @return [String]
     #
-    def name
-      @argument["name"]
-    end
+    attr_reader :name
 
-    # ## Type
-    #
     # The type of the argument. It must be one of:
-    #   - object
-    #   - array
-    #   - string
-    #   - number
-    #   - boolean
+    #
+    # - object
+    # - array
+    # - string
+    # - number
+    # - boolean
     #
     # @return [String]
     #
-    def type
-      @argument["type"]
-    end
+    attr_reader :type
 
-    # ## Hint
+    # A hint that further defines what kind of value to expect for an argument.
     #
-    # The hint of the argument
-    #
-    # See the [hints section][1] on the Web Function website for the full list 
-    # of possible hints.
+    # 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
+    attr_reader :hint
 
-    # ## Group
-    #
-    # A name used to categorize or group similar arguments together. This 
-    # should be used by documentation tools to organize related arguments.
+    # 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
+    attr_reader :group
 
-    # ## 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.
+    # 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.
+    # 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"]]
-    end
+    attr_reader :choices
 
-    # ## Flags
+    # Description of the argument. It must be formatted as markdown.
     #
-    # 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 [String]
     #
-    # @return [Array<String>]
+    attr_reader :docs
+
+    # Whether the argument is required.
     #
-    # [2]: https://webfunction.org/package#available-flags
+    # @return [Boolean]
     #
-    def flags
-      [*@argument["flags"]].map { |flag| flag.to_s }
+    def required?
+      flag?("required")
     end
 
-    # ## Docs
+    # Whether the argument is optional.
     #
-    # Description of the argument. It must be formatted as markdown.
-    #
-    # @return [String]
+    # @return [Boolean]
     #
-    def docs
-      @argument["docs"].to_s
+    def optional?
+      !required?
     end
   end
 end

data/lib/web_function/attribute.rb

@@ -1,100 +1,124 @@
 # frozen_string_literal: true
 
 module WebFunction
-  # # Attribute
+  # Attributes define output fields that may be produced and returned by a Web Function {Endpoint} when the type of the 
+  # return is `object`.
   #
-  # 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.
+  # 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
+    include Flaggable
+
+    def initialize(name:, type:, hint: nil, values: [], flags: [], docs: nil)
+      @name = name
+      @type = type
+      @hint = hint
+      @values = values
+      @flags = flags
+      @docs = docs.to_s
+    end
+
+    class << self
+      # Creates a new Attribute from a hash. Typically coming from a {Package}.
+      #
+      # @param attribute [Hash] The attribute hash
+      #
+      # @return [Attribute] A new Attribute instance
+      #
+      def from_hash(attribute)
+        unless attribute.is_a?(Hash)
+          return
+        end
+
+        unless attribute["name"]
+          return
+        end
+
+        unless attribute["type"]
+          return
+        end
+
+        new(
+          name: attribute["name"],
+          type: attribute["type"],
+          hint: attribute["hint"],
+          values: [*attribute["values"]],
+          flags: Utils.normalize_array_of_strings(attribute["flags"]),
+          docs: attribute["docs"],
+        )
+      end
+
+      # Creates a new Attribute from an array of hashes. Typically coming from a {Package}. Uses {Attribute#from_hash}
+      # under the hood.
+      #
+      # @param attributes [Array<Hash>] The attribute array of hashes
+      #
+      # @return [Array<Attribute>] A new array of Attribute instances
+      #
+      def from_array(attributes)
+        Utils.normalize_array attributes do |attribute|
+          from_hash(attribute)
+        end
+      end
     end
 
-    # ## Name
-    #
     # The name of the attribute as it will appear in the endpoint's output
     # object.
     #
+    # This is required for the argument to be valid.
+    #
     # @return [String]
     #
-    def name
-      @attribute["name"]
-    end
+    attr_reader :name
 
-    # ## Type
-    #
     # The type of value returned for this attribute. Must be one of:
-    #   - object
-    #   - array
-    #   - string
-    #   - number
-    #   - boolean
     #
-    # This is a required string.
+    # - object
+    # - array
+    # - string
+    # - number
+    # - boolean
+    #
+    # This is required for the argument to be valid.
     #
     # @return [String]
     #
-    def type
-      @attribute["type"]
-    end
+    attr_reader :type
 
-    # ## Hint
-    #
-    # A string hinting about the semantics of this attribute. See the
-    # [hints section][1] for possible values and documentation tooling guidance.
+    # 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
+    attr_reader :hint
 
-    # ## 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.
+    # 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).
+    # This is useful for attributes that can only take a select set of values (enums or constants).
     #
     # @return [Array]
     #
-    def values
-      [*@attribute["values"]]
-    end
+    attr_reader :values
 
-    # ## Flags
+    # A markdown string describing this attribute and its purpose in the output object. Used by documentation tools, 
+    # and highly recommended.
     #
-    # 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>]
+    # @return [String]
     #
-    def flags
-      [*@attribute["flags"]].map(&:to_s)
-    end
+    attr_reader :docs
 
-    # ## Docs
-    #
-    # A markdown string describing this attribute and its purpose in the output 
-    # object. Used by documentation tools, and highly recommended.
+    # Whether the attribute can be null.
     #
-    # @return [String]
+    # @return [Boolean]
     #
-    def docs
-      @attribute["docs"].to_s
+    def nullable?
+      flag?("nullable")
     end
   end
 end

data/lib/web_function/client.rb

@@ -1,72 +1,116 @@
 # frozen_string_literal: true
 
 module WebFunction
-  # # Client
-  #
-  # A Client is a wrapper around a Web Function package that provides a 
-  # convenient interface for invoking endpoints.
+  # 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)
+    def initialize(base_url:, endpoints: [], package: nil, bearer_auth: nil, version: nil, pipeline: nil)
       @package = package
-      @endpoints = package.endpoints.to_h { |e| [e.name.gsub("-", "_").to_sym, e] }
+      @base_url = base_url
+      @endpoints = endpoints.to_h { |e| [e.gsub("-", "_").to_sym, e] }
       @bearer_auth = bearer_auth
+      @version = version
       @pipeline = pipeline
     end
 
-    attr_reader :package
+    class << self
+      # Creates a new {Client} from an url.
+      #
+      # @param url [String] The URL of the package endpoint
+      # @param bearer_auth [String] The bearer authentication token
+      # @param version [String] The API version to use
+      # @param pipelined [Boolean] Whether to have the client use call pipelining
+      #
+      # @return [Client]
+      #
+      def from_package_endpoint(url, bearer_auth: nil, version: nil, pipelined: false)
+        response = ::WebFunction::Request.execute(url, bearer_auth: bearer_auth, version: version)
+        package = ::WebFunction::Package.from_hash(response)
 
-    # ## Instantiates a new Client from a package endpoint
-    #
-    # Creates a new Client from a package endpoint.
+        from_package(package, bearer_auth: bearer_auth, version: version, pipelined: pipelined)
+      end
+
+      # Creates a new {Client} from a {Package}.
+      #
+      # @param package [Package] A package
+      # @param bearer_auth [String] The bearer authentication token
+      # @param version [String] The API version to use
+      # @param pipelined [Boolean] Whether to have the client use call pipelining
+      #
+      # @return [Client]
+      #
+      def from_package(package, bearer_auth: nil, version: nil, pipelined: nil)
+        pipeline = nil
+
+        if pipelined
+          pipeline = package.pipeline
+        end
+
+        client = new(
+          package: package,
+          base_url: package.base_url,
+          endpoints: package.endpoints.map(&:name),
+          bearer_auth: bearer_auth,
+          version: version,
+          pipeline: pipeline,
+        )
+
+        package.endpoints.each do |endpoint|
+          endpoint.client = client
+        end
+
+        client
+      end
+    end
+
+    # Call an endpoint by name with the given arguments.
     #
-    # @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
+    # @param endpoint_name [String] The name of the endpoint to call
+    # @param args [Hash] The arguments to send to the endpoint
     #
-    # @return [Client] A new Client instance
+    # @return [Object] The decoded response returned by the endpoint
     #
-    def self.from_package_endpoint(url, bearer_auth: nil, pipeline_url: nil, pipeline: nil)
-      response = ::WebFunction::Endpoint.invoke(url, bearer_auth: bearer_auth)
-      package = ::WebFunction::Package.new(response)
+    def call(endpoint_name, args = {})
+      url = ::URI.join(@base_url, endpoint_name).to_s
+      request = ::WebFunction::Request.new(url,
+        bearer_auth: @bearer_auth,
+        version: @version,
+        args: args,
+      )
 
-      if pipeline_url.is_a?(::String)
-        pipeline = ::WebFunction::Pipeline.new(pipeline_url)
+      if @pipeline
+        @pipeline.add_step(request.as_pipeline_step)
+      else
+        request.execute
       end
-
-      new(package, bearer_auth: bearer_auth, pipeline: pipeline)
     end
 
-    def methods #:nodoc:
-      super + @endpoints.keys
+    # The package that this client is wrapping.
+    #
+    # @return [Package]
+    #
+    attr_reader :package
+
+    def methods # :nodoc:
+      @endpoints.keys
     end
 
-    def respond_to_missing?(method_name, include_private = false) #:nodoc:
-      @endpoints[method_name] || super
+    def respond_to_missing?(method_name, include_private = false) # :nodoc:
+      @endpoints[method_name]
     end
 
-    def method_missing(method_name, *args) #:nodoc:
-      endpoint = @endpoints[method_name]
+    def method_missing(method_name, *args) # :nodoc:
+      endpoint_name = @endpoints[method_name]
 
-      unless endpoint
+      unless endpoint_name
         super
       end
 
-      url = ::URI.join(@package.base_url, endpoint.name).to_s
-      args = args.first
-
-      if @pipeline
-        step = ::WebFunction::Endpoint.step(url, bearer_auth: @bearer_auth, args: args)
-        promise = @pipeline.add_step(step)
-        return promise
-      end
-
-      ::WebFunction::Endpoint.invoke(url, bearer_auth: @bearer_auth, args: args)
+      call(endpoint_name, args.first)
     end
   end
 end

data/lib/web_function/documented_error.rb

@@ -1,39 +1,67 @@
+# frozen_string_literal: true
+
 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.
+  # 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.
+  # 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
+    def initialize(code:, docs: nil)
+      @code = code
+      @docs = docs.to_s
     end
 
-    # ## Code
-    #
-    # The code of the error.
+    class << self
+      # Creates a new DocumentedError from a hash.
+      #
+      # @param error [Hash] The error hash
+      #
+      # @return [DocumentedError] A new DocumentedError instance
+      #
+      def from_hash(error)
+        unless error.is_a?(Hash)
+          return
+        end
+
+        unless error["code"]
+          return
+        end
+
+        new(
+          code: error["code"],
+          docs: error["docs"],
+        )
+      end
+
+      # Creates a new DocumentedError from an array of hashes. Uses {DocumentedError#from_hash} under the hood.
+      #
+      # @param errors [Array<Hash>] The error array of hashes
+      #
+      # @return [Array<DocumentedError>] A new array of DocumentedError instances
+      #
+      def from_array(errors)
+        Utils.normalize_array errors do |error|
+          from_hash(error)
+        end
+      end
+    end
+
+    # The machine-readable code of the error.
     #
     # @return [String]
     #
-    def code
-      @error["code"]
-    end
+    attr_reader :code
 
-    # ## Docs
-    #
     # The documentation of the error.
     #
     # @return [String]
     #
-    def docs
-      @error["docs"].to_s
-    end
+    attr_reader :docs
   end
 end