lib/trav3.rb in trav3-0.3.0 vs lib/trav3.rb in trav3-0.3.1

- old
+ new

@@ -29,21 +29,20 @@ # @param repo [String] github_username/repository_name # @raise [InvalidRepository] if given input does not # conform to valid repository identifier format # @return [Travis] def initialize(repo) - validate_repo_format repo - @api_endpoint = 'https://api.travis-ci.org' - @repo = sanitize_repo_name repo + self.repository = repo + initial_defaults end - # @overload api_endpoint=(endpoint) - # Set as the API endpoint - # @param endpoint [String] name for value to set + # Set as the API endpoint + # + # @param endpoint [String] name for value to set # @return [self] # rubocop:disable Lint/Void def api_endpoint=(endpoint) validate_api_endpoint endpoint @@ -51,13 +50,14 @@ self end # rubocop:enable Lint/Void + # Set as many options as you'd like for collections queried via an API request + # # @overload defaults(key: value, ...) - # Set as many options as you'd like for collections queried via an API request - # @param key [Symbol, String] name for value to set + # @param key [Symbol] name for value to set # @param value [Symbol, String, Integer] value for key # @return [self] def defaults(**args) (@options ||= Options.new).build(args) self @@ -66,18 +66,26 @@ # Set as many headers as you'd like for API requests # # h("Authorization": "token xxxxxxxxxxxxxxxxxxxxxx") # # @overload h(key: value, ...) - # @param key [Symbol, String] name for value to set + # @param key [Symbol] name for value to set # @param value [Symbol, String, Integer] value for key # @return [self] def h(**args) (@headers ||= Headers.new).build(args) self end + # Change the repository this instance of `Trav3::Travis` uses. + # + # @param repo_name [String] github_username/repository_name + def repository=(repo_name) + validate_repo_format repo_name + @repo = sanitize_repo_name repo_name + end + # Please Note that the naming of this endpoint may be changed. Our naming convention for this information is in flux. If you have suggestions for how this information should be presented please leave us feedback by commenting in this issue here or emailing support support@travis-ci.com. # # A list of all the builds in an "active" state, either created or started. # # ## Attributes @@ -744,10 +752,238 @@ else get("#{without_repo}/job/#{job_id}") end end + # Users may add a public/private RSA key pair to a repository. + # This can be used within builds, for example to access third-party services or deploy code to production. + # Please note this feature is only available on the travis-ci.com domain. + # + # ## Attributes + # + # **Standard Representation** + # + # Included when the resource is the main response of a request, or is {https://developer.travis-ci.com/eager-loading eager loaded}. + # + # Name Type Description + # description String A text description. + # public_key String The public key. + # fingerprint String The fingerprint. + # + # **Minimal Representation** + # + # Included when the resource is returned as part of another resource. + # + # Name Type Description + # description String A text description. + # public_key String The public key. + # fingerprint String The fingerprint. + # + # ## Actions + # + # **Find** + # + # Return the current key pair, if it exists. + # + # GET <code>/repo/{repository.id}/key_pair</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /repo/891/key_pair + # + # GET <code>/repo/{repository.slug}/key_pair</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /repo/rails%2Frails/key_pair + # + # **Create** + # + # Creates a new key pair. + # + # ```bash + # curl -X POST \ + # -H "Content-Type: application/json" \ + # -H "Travis-API-Version: 3" \ + # -H "Authorization: token xxxxxxxxxxxx" \ + # -d '{ "key_pair.description": "FooBar", "key_pair.value": "xxxxx"}' \ + # https://api.travis-ci.com/repo/1234/key_pair + # ``` + # + # POST <code>/repo/{repository.id}/key_pair</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # Accepted Parameter Type Description + # key_pair.description String A text description. + # key_pair.value String The private key. + # + # Example: POST /repo/891/key_pair + # + # POST <code>/repo/{repository.slug}/key_pair</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # Accepted Parameter Type Description + # key_pair.description String A text description. + # key_pair.value String The private key. + # + # Example: POST /repo/rails%2Frails/key_pair + # + # **Update** + # + # Update the key pair. + # + # ```bash + # curl -X PATCH \ + # -H "Content-Type: application/json" \ + # -H "Travis-API-Version: 3" \ + # -H "Authorization: token xxxxxxxxxxxx" \ + # -d '{ "key_pair.description": "FooBarBaz" }' \ + # https://api.travis-ci.com/repo/1234/key_pair + # ``` + # + # PATCH <code>/repo/{repository.id}/key_pair</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # Accepted Parameter Type Description + # key_pair.description String A text description. + # key_pair.value String The private key. + # + # Example: PATCH /repo/891/key_pair + # + # PATCH <code>/repo/{repository.slug}/key_pair</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # Accepted Parameter Type Description + # key_pair.description String A text description. + # key_pair.value String The private key. + # + # Example: PATCH /repo/rails%2Frails/key_pair + # + # **Delete** + # + # Delete the key pair. + # + # DELETE <code>/repo/{repository.id}/key_pair</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # + # Example: DELETE /repo/891/key_pair + # + # DELETE <code>/repo/{repository.slug}/key_pair</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # + # Example: DELETE /repo/rails%2Frails/key_pair + # + # @note requests require an authorization token set in the headers. See: {h} + # @note API enpoint needs to be set to `https://api.travis-ci.com` See: {api_endpoint=} + # + # @overload key_par() + # Gets current key_pair if any + # @overload key_pair(action: params) + # Performs action per specific key word argument + # @param create [Hash] Create a new key pair from provided private key { description: "name", value: "private key" } + # @param update [Hash] Update key pair with hash { description: "new name" } + # @param delete [Boolean] Use truthy value to delete current key pair + # @return [Success, RequestError] + def key_pair(create: nil, update: nil, delete: nil) + raise 'Too many options specified' unless [create, update, delete].compact.count < 2 + + create and return create("#{with_repo}/key_pair", key_pair_keys(create)) + update and return patch("#{with_repo}/key_pair", key_pair_keys(update)) + delete and return delete("#{with_repo}/key_pair") + get("#{with_repo}/key_pair") + end + + # Every repository has an auto-generated RSA key pair. This is used when cloning the repository from GitHub and when encrypting/decrypting secure data for use in builds, e.g. via the Travis CI command line client. + # + # Users may read the public key and fingerprint via GET request, or generate a new key pair via POST, but otherwise this key pair cannot be edited or removed. + # + # ## Attributes + # + # **Standard Representation** + # + # Included when the resource is the main response of a request, or is {https://developer.travis-ci.com/eager-loading eager loaded}. + # + # Name Type Description + # description String A text description. + # public_key String The public key. + # fingerprint String The fingerprint. + # + # **Minimal Representation** + # + # Included when the resource is returned as part of another resource. + # + # Name Type Description + # description String A text description. + # public_key String The public key. + # fingerprint String The fingerprint. + # + # ## Actions + # + # **Find** + # + # Return the current key pair. + # + # GET <code>/repo/{repository.id}/key_pair/generated</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /repo/891/key_pair/generated + # + # GET <code>/repo/{repository.slug}/key_pair/generated</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # Example: GET /repo/rails%2Frails/key_pair/generated + # + # **Create** + # + # Generate a new key pair, replacing the previous one. + # + # POST <code>/repo/{repository.id}/key_pair/generated</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # + # Example: POST /repo/891/key_pair/generated + # + # POST <code>/repo/{repository.slug}/key_pair/generated</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # + # Example: POST /repo/rails%2Frails/key_pair/generated + # + # @note requests require an authorization token set in the headers. See: {h} + # + # @param action [String, Symbol] defaults to getting current key pair, use `:create` if you would like to generate a new key pair + # @return [Success, RequestError] + def key_pair_generated(action = :get) + return post("#{with_repo}/key_pair/generated") if action.match?(/create/i) + + get("#{with_repo}/key_pair/generated") + end + # This validates the `.travis.yml` file and returns any warnings. # # The request body can contain the content of the .travis.yml file directly as a string, eg "foo: bar". # # ## Attributes @@ -861,10 +1097,62 @@ else get("#{without_repo}/job/#{job_id}/log") end end + # A list of messages. Messages belong to resource types. + # + # ## Attributes + # + # Name Type Description + # messages [Message] List of messages. + # + # **Collection Items** + # + # Each entry in the messages array has the following attributes: + # + # Name Type Description + # id Integer The message's id. + # level String The message's level. + # key String The message's key. + # code String The message's code. + # args Json The message's args. + # + # ## Actions + # + # **For Request** + # + # This will return a list of messages created by `travis-yml` for a request, if any exist. + # + # GET <code>/repo/{repository.id}/request/{request.id}/messages</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # request.id Integer Value uniquely identifying the request. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # limit Integer How many messages to include in the response. Used for pagination. + # offset Integer How many messages to skip before the first entry in the response. Used for pagination. + # + # GET <code>/repo/{repository.slug}/request/{request.id}/messages</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # request.id Integer Value uniquely identifying the request. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # limit Integer How many messages to include in the response. Used for pagination. + # offset Integer How many messages to skip before the first entry in the response. Used for pagination. + # + # @param request_id [String, Integer] the request id + # @return [Success, RequestError] + def messages(request_id) + validate_number request_id + + get("#{with_repo}/request/#{request_id}/messages") + end + # An individual organization. # # ## Attributes # # **Minimal Representation** @@ -1111,10 +1399,12 @@ # Template Variable Type Description # preference.name Unknown The preference's name. # Query Parameter Type Description # include [String] List of attributes to eager load. # + # @note requests require an authorization token set in the headers. See: {h} + # # @param key [String] preference name to get or set # @param value [String] optional value to set preference # @param org_id [String, Integer] optional keyword argument for an organization id # @return [Success, RequestError] def preference(key, value = nil, org_id: nil) @@ -1161,10 +1451,12 @@ # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /preferences # + # @note requests require an authorization token set in the headers. See: {h} + # # @param org_id [String, Integer] optional organization id # @return [Success, RequestError] def preferences(org_id = nil) if org_id validate_number org_id @@ -1948,12 +2240,12 @@ end end private # @private - def create(url, **data) - Trav3::REST.create(self, url, **data) + def create(url, data = {}) + Trav3::REST.create(self, url, data) end def delete(url) Trav3::REST.delete(self, url) end @@ -1979,10 +2271,14 @@ h('Content-Type': 'application/json') h('Accept': 'application/json') h('Travis-API-Version': 3) end + def key_pair_keys(hash) + hash.map { |k, v| ["key_pair.#{k}", v] }.to_h unless hash.keys.first.match?(/key_pair\.\w+/) + end + def number?(input) /^\d+$/.match? input.to_s end def opts @@ -2012,10 +2308,10 @@ def validate_string(input) raise TypeError, "String expected, #{input.class} given" unless input.is_a? String end def repo_slug_or_id?(input) - Regexp.new(/(^\d+$)|(^\w+(?:\/|%2F){1}\w+$)/).match? input + Regexp.new(/(^\d+$)|(^[A-Za-z0-9_.-]+(?:\/|%2F){1}[A-Za-z0-9_.-]+$)/i).match? input end def repository_name @repo end