webfunction 1.0.0

data/lib/webfunction/argument.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # 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
+    include Flaggable
+
+    def initialize(name:, type:, group: nil, choices: [], flags: [], docs: nil)
+      @name = name
+      @type = Type.parse(type)
+      @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"],
+          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
+
+    # The name of the argument.
+    #
+    # @return [String]
+    #
+    attr_reader :name
+
+    # The type of the argument. It must be one of:
+    #
+    # - object
+    # - array
+    # - string
+    # - number
+    # - boolean
+    #
+    # @return [String]
+    #
+    attr_reader :type
+
+    # A name used to categorize or group similar arguments together. This should be used by documentation tools to
+    # organize related arguments.
+    #
+    # @return [String]
+    #
+    attr_reader :group
+
+    # 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]
+    #
+    attr_reader :choices
+
+    # Description of the argument. It must be formatted as markdown.
+    #
+    # @return [String]
+    #
+    attr_reader :docs
+
+    # Whether the argument is required.
+    #
+    # @return [Boolean]
+    #
+    def required?
+      flag?("required")
+    end
+
+    # Whether the argument is optional.
+    #
+    # @return [Boolean]
+    #
+    def optional?
+      !required?
+    end
+  end
+end

data/lib/webfunction/attribute.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # Attributes define output fields that may be produced and returned by a Web Function {Endpoint} when the type of the 
+  # return is `object`.
+  #
+  # 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
+    include Flaggable
+
+    def initialize(name:, type:, values: [], flags: [], docs: nil)
+      @name = name
+      @type = Type.parse(type)
+      @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"],
+          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
+
+    # 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]
+    #
+    attr_reader :name
+
+    # The type of value returned for this attribute. Must be one of:
+    #
+    # - object
+    # - array
+    # - string
+    # - number
+    # - boolean
+    #
+    # This is required for the argument to be valid.
+    #
+    # @return [String]
+    #
+    attr_reader :type
+
+    # 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]
+    #
+    attr_reader :values
+
+    # A markdown string describing this attribute and its purpose in the output object. Used by documentation tools, 
+    # and highly recommended.
+    #
+    # @return [String]
+    #
+    attr_reader :docs
+
+    # Whether the attribute can be null.
+    #
+    # @return [Boolean]
+    #
+    def nullable?
+      flag?("nullable")
+    end
+  end
+end

data/lib/webfunction/client.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # 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(base_url:, endpoints: [], package: nil, bearer_auth: nil, version: nil, pipeline: nil)
+      @package = package
+      @base_url = base_url
+      @endpoints = endpoints.to_h { |e| [e.gsub("-", "_").to_sym, e] }
+      @bearer_auth = bearer_auth
+      @version = version
+      @pipeline = pipeline
+    end
+
+    class << self
+      # Creates a new {Client} from an endpoint.
+      #
+      # @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)
+
+        from_package(package, bearer_auth: bearer_auth, version: version, pipelined: pipelined)
+      end
+
+      # 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_url(url, bearer_auth: nil, version: nil, pipelined: false)
+        body = ::WebFunction::Utils.get_body_from_url(url, extra_query_params: { api_version: version })
+        package = ::WebFunction::Package.from_hash(::JSON.parse(body))
+
+        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 endpoint_name [String] The name of the endpoint to call
+    # @param args [Hash] The arguments to send to the endpoint
+    #
+    # @return [Object, Page] The decoded response returned by the endpoint.
+    #   Paginated responses are wrapped in a {Page}.
+    #
+    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
+        @pipeline.add_step(request.as_pipeline_step)
+      else
+        request.execute
+      end
+    end
+
+    # The package that this client is wrapping.
+    #
+    # @return [Package]
+    #
+    attr_reader :package
+
+    # The bearer authentication token.
+    #
+    # @param bearer_auth [String] The bearer authentication token
+    #
+    attr_writer :bearer_auth
+
+    # The API version to use.
+    #
+    # @param version [String] The API version to use
+    #
+    attr_writer :version
+
+    # The pipeline to use.
+    #
+    # @param pipeline [Pipeline] The pipeline to use
+    #
+    attr_writer :pipeline
+
+    def methods # :nodoc:
+      @endpoints.keys
+    end
+
+    def nil? # :nodoc:
+      false
+    end
+
+    def respond_to_missing?(method_name, include_private = false) # :nodoc:
+      @endpoints[method_name]
+    end
+
+    def method_missing(method_name, *args) # :nodoc:
+      endpoint_name = @endpoints[method_name]
+
+      unless endpoint_name
+        super
+      end
+
+      call(endpoint_name, args.first)
+    end
+  end
+end

data/lib/webfunction/documented_error.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # 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(code:, docs: nil)
+      @code = code
+      @docs = docs.to_s
+    end
+
+    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]
+    #
+    attr_reader :code
+
+    # The documentation of the error.
+    #
+    # @return [String]
+    #
+    attr_reader :docs
+  end
+end

data/lib/webfunction/endpoint.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module WebFunction
+  # 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
+    include Flaggable
+
+    def initialize(name:, returns:, flags: [], group: nil, docs: nil, arguments: [], attributes: [], errors: [])
+      @name = name
+      @returns = Type.parse(returns)
+      @flags = flags
+      @group = group
+      @docs = docs
+      @arguments = arguments.to_h { |a| [a.name, a] }
+      @attributes = attributes.to_h { |a| [a.name, a] }
+      @errors = errors.to_h { |e| [e.code, e] }
+    end
+
+    class << self
+      # Invokes an endpoint through HTTP using the given URL, bearer authentication, version, and arguments.
+      #
+      # @param url [String] The URL of the endpoint to invoke
+      # @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 endpoint
+      #
+      # @return [Object] The response returned by the endpoint
+      #
+      def invoke(url, bearer_auth: nil, version: nil, args: {})
+        Request.execute(url, bearer_auth: bearer_auth, version: version, args: args)
+      end
+
+      # Creates a new Endpoint from a hash.
+      #
+      # @param endpoint [Hash] The endpoint hash
+      #
+      # @return [Endpoint] A new Endpoint instance
+      #
+      def from_hash(endpoint)
+        unless endpoint.is_a?(Hash)
+          return
+        end
+
+        unless endpoint["name"]
+          return
+        end
+
+        unless endpoint["returns"]
+          return
+        end
+
+        new(
+          name: endpoint["name"],
+          returns: endpoint["returns"],
+          flags: Utils.normalize_array_of_strings(endpoint["flags"]),
+          group: endpoint["group"],
+          docs: endpoint["docs"].to_s,
+          arguments: Argument.from_array(endpoint["arguments"]),
+          attributes: Attribute.from_array(endpoint["attributes"]),
+          errors: DocumentedError.from_array(endpoint["errors"]),
+        )
+      end
+
+      # Creates a new Endpoint from an array of hashes. Uses {Endpoint#from_hash} under the hood.
+      #
+      # @param endpoints [Array<Hash>] The endpoint array of hashes
+      #
+      # @return [Array<Endpoint>] A new array of Endpoint instances
+      #
+      def from_array(endpoints)
+        Utils.normalize_array endpoints do |endpoint|
+          from_hash(endpoint)
+        end
+      end
+    end
+
+    # The {Client} used to invoke this endpoint. It is assigned when the endpoint is loaded from a package and is
+    # required by {#call}.
+    #
+    # @return [Client, nil]
+    #
+    attr_accessor :client
+
+    # The suffix for the endpoint URL, appended to the package's base URL to form the full endpoint URL. Endpoint names
+    # are unique within a package; overloading (two endpoints sharing the same name) is not permitted.
+    #
+    # @return [String]
+    #
+    attr_reader :name
+
+    # The JSON type(s) returned by the endpoint. A non-empty array whose entries are each one of:
+    #
+    # - object
+    # - array
+    # - string
+    # - number
+    # - boolean
+    # - null
+    #
+    # @return [Array<String>]
+    #
+    attr_reader :returns
+
+    # A name used to categorize or group similar endpoints together. This should be used by documentation tools to
+    # organize related endpoints.
+    #
+    # @return [String, nil]
+    #
+    attr_reader :group
+
+    # Documentation for the endpoint. It must be formatted as markdown.
+    #
+    # @return [String]
+    #
+    attr_reader :docs
+
+    # Invokes the endpoint through its assigned {#client}, passing the given arguments.
+    #
+    # @param args [Hash] The arguments to send to the endpoint.
+    #
+    # @raise [RuntimeError] If no client has been assigned to the endpoint.
+    #
+    # @return [Object] The decoded response returned by the endpoint.
+    #
+    def call(args = {})
+      unless client
+        raise "Client must be set to invoke an endpoint"
+      end
+
+      client.call(name, args)
+    end
+
+    # The list of errors specific to this endpoint. Clients SHOULD only refer to this list if the endpoint uses the
+    # `error_triple` flag. See the error specification for more information.
+    #
+    # @return [Array<DocumentedError>]
+    #
+    def errors
+      @errors.values
+    end
+
+    # Looks up a single endpoint error by its machine-readable code.
+    #
+    # @param code [String, Symbol] The error code to look up.
+    #
+    # @return [DocumentedError, nil] The matching error, or `nil` if none is found.
+    #
+    def error(code)
+      @errors[code.to_s]
+    end
+
+    # The attributes of the object returned by the endpoint. Relevant when the endpoint returns an `object`.
+    #
+    # @return [Array<Attribute>]
+    #
+    def attributes
+      @attributes.values
+    end
+
+    # Looks up a single returned attribute by name.
+    #
+    # @param name [String, Symbol] The name of the attribute to look up.
+    #
+    # @return [Attribute, nil] The matching attribute, or `nil` if none is found.
+    #
+    def attribute(name)
+      @attributes[name.to_s]
+    end
+
+    # The arguments required by the endpoint. The array is empty when the endpoint requires no arguments.
+    #
+    # @return [Array<Argument>]
+    #
+    def arguments
+      @arguments.values
+    end
+
+    # Looks up a single argument by name.
+    #
+    # @param name [String, Symbol] The name of the argument to look up.
+    #
+    # @return [Argument, nil] The matching argument, or `nil` if none is found.
+    #
+    def argument(name)
+      @arguments[name.to_s]
+    end
+
+    # Whether the endpoint requires authentication via a bearer token, i.e. whether it declares the `bearer_auth` flag.
+    #
+    # @return [Boolean]
+    #
+    def bearer_auth?
+      flag?("bearer_auth")
+    end
+
+    # Whether the endpoint returns a bearer token in its response, i.e. whether it declares the `capture_bearer` flag.
+    # See the authentication specification for more information.
+    #
+    # @return [Boolean]
+    #
+    def capture_bearer?
+      flag?("capture_bearer")
+    end
+
+    # Whether the endpoint supports pagination, i.e. whether it declares the `paginated` flag.
+    #
+    # @return [Boolean]
+    #
+    def paginated?
+      flag?("paginated")
+    end
+
+    # Whether the endpoint is intended for internal use and is not part of the public API, i.e. whether it declares the
+    # `private` flag. Documentation tooling SHOULD omit endpoints with this flag from generated or
+    # published documentation.
+    #
+    # @return [Boolean]
+    #
+    def private?
+      flag?("private")
+    end
+  end
+end