lib/trav3.rb in trav3-0.2.1 vs lib/trav3.rb in trav3-0.2.2

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/ClassLength
 require 'trav3/version'
 require 'trav3/pagination'
 require 'trav3/options'
 require 'trav3/headers'
 require 'trav3/result'
@@ -19,11 +20,10 @@
   #   @return [String] API endpoint
   # @!attribute [r] options
   #   @return [Options] Request options object
   # @!attribute [r] headers
   #   @return [Headers] Request headers object
-  # rubocop:disable Metrics/ClassLength
   class Travis
     API_ENDPOINT = API_ROOT
     attr_reader :api_endpoint
     attr_reader :options
     attr_reader :headers
@@ -131,11 +131,11 @@
     #     Query Parameter  Type      Description
     #     include          [String]  List of attributes to eager load.
     #
     #     Example:GET /repo/rails%2Frails/branch/master
     #
-    # @param id [String] the branch name for the current repository
+    # @param name [String] the branch name for the current repository
     # @return [Success, RequestError]
     def branch(name)
       get("#{with_repo}/branch/#{name}#{opts}")
     end
 
@@ -1171,10 +1171,56 @@
       else
         post("#{without_repo}/repo/#{repo}/#{action}")
       end
     end
 
+    # A list of stages.
+    #
+    # Currently this is nested within a build.
+    #
+    # ## Attributes
+    #
+    #     Name    Type     Description
+    #     stages  [Stage]  List of stages.
+    #
+    # **Collection Items**
+    #
+    # Each entry in the stages array has the following attributes:
+    #
+    #     Name         Type     Description
+    #     id           Integer  Value uniquely identifying the stage.
+    #     number       Integer  Incremental number for a stage.
+    #     name         String   The name of the stage.
+    #     state        String   Current state of the stage.
+    #     started_at   String   When the stage started.
+    #     finished_at  String   When the stage finished.
+    #     jobs         [Job]    The jobs of a stage.
+    #
+    # ## Actions
+    #
+    # **Find**
+    #
+    # This returns a list of stages belonging to an individual build.
+    #
+    # GET <code>/build/{build.id}/stages</code>
+    #
+    #     Template Variable  Type     Description
+    #     build.id           Integer  Value uniquely identifying the build.
+    #     Query Parameter  Type      Description
+    #     include          [String]  List of attributes to eager load.
+    #
+    #     Example:GET /build/86601346/stages
+    #
+    # @param build_id [String, Integer] build id
+    # @raise [TypeError] if given build id is not a number
+    # @return [Success, RequestError]
+    def stages(build_id)
+      raise TypeError, 'Integer expected for build id' unless /^\d+$/.match? build_id.to_s
+
+      get("#{without_repo}/build/#{build_id}/stages")
+    end
+
     # An individual user.
     #
     # ## Attributes
     #
     # **Minimal Representation**
@@ -1305,7 +1351,7 @@
 
     def without_repo
       api_endpoint
     end
   end
-  # rubocop:enable Metrics/ClassLength
 end
+# rubocop:enable Metrics/ClassLength