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

- old
+ new

@@ -35,25 +35,34 @@ self.repository = repo initial_defaults end + # rubocop:disable Lint/Void # 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 @api_endpoint = endpoint self end - # rubocop:enable Lint/Void + # Set the authorization token in the requests' headers + # + # @param token [String] sets authorization token header + # @return [self] + def authorization=(token) + validate_string token + h('Authorization': "token #{token}") + self + end + # Set as many options as you'd like for collections queried via an API request # # @overload defaults(key: value, ...) # @param key [Symbol] name for value to set # @param value [Symbol, String, Integer] value for key @@ -77,14 +86,17 @@ end # Change the repository this instance of `Trav3::Travis` uses. # # @param repo_name [String] github_username/repository_name + # @return [self] def repository=(repo_name) validate_repo_format repo_name @repo = sanitize_repo_name repo_name + self end + # rubocop:enable Lint/Void # 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. # @@ -109,11 +121,11 @@ # Example: GET /owner/danielpclark/active # # GET <code>/owner/{user.login}/active</code> # # Template Variable Type Description - # user.login String Login set on Github. + # user.login String Login set on GitHub. # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/danielpclark/active # @@ -136,15 +148,12 @@ # Example: GET /owner/github_id/639823/active # # @param owner [String] username, organization name, or github id # @return [Success, RequestError] def active(owner = username) - if number? owner - get("#{without_repo}/owner/github_id/#{owner}/active") - else - get("#{without_repo}/owner/#{owner}/active") - end + number?(owner) and return get("#{without_repo}/owner/github_id/#{owner}/active") + get("#{without_repo}/owner/#{owner}/active") end # The branch of a GitHub repository. Useful for obtaining information about the last build on a given branch. # # **If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters.** @@ -352,11 +361,11 @@ # Template Variable Type Description # build.id Integer Value uniquely identifying the build. # # Example: POST /build/86601346/restart # - # @note POST requests require an authorization token set in the headers. See: {h} + # @note POST requests require an authorization token set in the headers. See: {authorization=} # # @param build_id [String, Integer] the build id number # @param option [Symbol] options for :cancel or :restart # @raise [TypeError] if given build id is not a number # @return [Success, RequestError] @@ -642,22 +651,268 @@ # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: DELETE /repo/rails%2Frails/caches # - # @note DELETE requests require an authorization token set in the headers. See: {h} + # @note DELETE requests require an authorization token set in the headers. See: {authorization=} # # @param delete [Boolean] option for deleting cache(s) # @return [Success, RequestError] def caches(delete = false) - if delete - without_limit { delete("#{with_repo}/caches#{opts}") } - else - get("#{with_repo}/caches") + delete and return without_limit { delete("#{with_repo}/caches#{opts}") } + get("#{with_repo}/caches") + end + + # An individual environment variable. + # + # **If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters.** + # + # ## 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 + # id String The environment variable id. + # name String The environment variable name, e.g. FOO. + # value String The environment variable's value, e.g. bar. + # public Boolean Whether this environment variable should be publicly visible or not. + # + # **Minimal Representation** + # + # Included when the resource is returned as part of another resource. + # + # Name Type Description + # id String The environment variable id. + # name String The environment variable name, e.g. FOO. + # public Boolean Whether this environment variable should be publicly visible or not. + # + # ## Actions + # + # **Find** + # + # This returns a single environment variable. It is possible to use the repository id or slug in the request. + # + # GET <code>/repo/{repository.id}/env_var/{env_var.id}</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # env_var.id String The environment variable id. + # Query Parameter Type Description + # env_var.id String The environment variable id. + # id String Alias for env_var.id. + # include [String] List of attributes to eager load. + # repository.id Integer Value uniquely identifying the repository. + # + # GET <code>/repo/{repository.slug}/env_var/{env_var.id}</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # env_var.id String The environment variable id. + # Query Parameter Type Description + # env_var.id String The environment variable id. + # id String Alias for env_var.id. + # include [String] List of attributes to eager load. + # repository.id Integer Value uniquely identifying the repository. + # + # **Update** + # + # This updates a single environment variable. It is possible to use the repository id or slug in the request. + # + # Use namespaced params in the request body to pass the new environment variable: + # + # ```bash + # curl -X PATCH \ + # -H "Content-Type: application/json" \ + # -H "Travis-API-Version: 3" \ + # -H "Authorization: token xxxxxxxxxxxx" \ + # -d '{ "env_var.value": "bar", "env_var.public": false }' \ + # https://api.travis-ci.com/repo/1234/{env_var.id} + # ``` + # + # PATCH <code>/repo/{repository.id}/env_var/{env_var.id}</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # env_var.id String The environment variable id. + # Accepted Parameter Type Description + # env_var.name String The environment variable name, e.g. FOO. + # env_var.value String The environment variable's value, e.g. bar. + # env_var.public Boolean Whether this environment variable should be publicly visible or not. + # + # PATCH <code>/repo/{repository.slug}/env_var/{env_var.id}</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # env_var.id String The environment variable id. + # Accepted Parameter Type Description + # env_var.name String The environment variable name, e.g. FOO. + # env_var.value String The environment variable's value, e.g. bar. + # env_var.public Boolean Whether this environment variable should be publicly visible or not. + # + # **Delete** + # + # This deletes a single environment variable. It is possible to use the repository id or slug in the request. + # + # DELETE <code>/repo/{repository.id}/env_var/{env_var.id}</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # env_var.id String The environment variable id. + # + # DELETE <code>/repo/{repository.slug}/env_var/{env_var.id}</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # env_var.id String The environment variable id. + # + # @overload env_var(env_var_id) + # Gets current env var + # @param env_var_id [String] environment variable id + # @overload env_var(env_var_id, action: params) + # Performs action per specific key word argument + # @param env_var_id [String] environment variable id + # @param update [Hash] Optional keyword argument. Update key pair with hash `{ value: "new value" }` + # @param delete [Boolean] Optional keyword argument. Use truthy value to delete current key pair + # @return [Success, RequestError] + def env_var(env_var_id, update: nil, delete: nil) + raise 'Too many options specified' unless [update, delete].compact.count < 2 + + validate_string env_var_id + + update and return patch("#{with_repo}/env_var/#{env_var_id}", env_var_keys(update)) + delete and return delete("#{with_repo}/env_var/#{env_var_id}") + get("#{with_repo}/env_var/#{env_var_id}") + end + + # A list of environment variables. + # + # **If querying using the repository slug, it must be formatted using {http://www.w3schools.com/tags/ref_urlencode.asp standard URL encoding}, including any special characters.** + # + # ## Attributes + # + # Name Type Description + # env_vars [Env var] List of env_vars. + # + # ## Actions + # + # **For Repository** + # + # This returns a list of environment variables for an individual repository. It is possible to use the repository id or slug in the request. + # + # GET <code>/repo/{repository.id}/env_vars</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/env_vars + # + # GET <code>/repo/{repository.slug}/env_vars</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/env_vars + # + # **Create** + # + # This creates an environment variable for an individual repository. It is possible to use the repository id or slug in the request. + # + # Use namespaced params in the request body to pass the new environment variables: + # + # ```bash + # curl -X POST \ + # -H "Content-Type: application/json" \ + # -H "Travis-API-Version: 3" \ + # -H "Authorization: token xxxxxxxxxxxx" \ + # -d '{ "env_var.name": "FOO", "env_var.value": "bar", "env_var.public": false }' \ + # https://api.travis-ci.com/repo/1234/env_vars + # ``` + # + # POST <code>/repo/{repository.id}/env_vars</code> + # + # Template Variable Type Description + # repository.id Integer Value uniquely identifying the repository. + # Accepted Parameter Type Description + # env_var.name String The environment variable name, e.g. FOO. + # env_var.value String The environment variable's value, e.g. bar. + # env_var.public Boolean Whether this environment variable should be publicly visible or not. + # + # Example: POST /repo/891/env_vars + # + # POST <code>/repo/{repository.slug}/env_vars</code> + # + # Template Variable Type Description + # repository.slug String Same as {repository.owner.name}/{repository.name}. + # Accepted Parameter Type Description + # env_var.name String The environment variable name, e.g. FOO. + # env_var.value String The environment variable's value, e.g. bar. + # env_var.public Boolean Whether this environment variable should be publicly visible or not. + # + # Example: POST /repo/rails%2Frails/env_vars + # + # @note requests require an authorization token set in the headers. See: {authorization=} + # + # @param create [Hash] Optional argument. A hash of the `name`, `value`, and `public` visibleness for a env var to create + # @return [Success, RequestError] + def env_vars(create = nil) + if create + validate_env_var create + + return create("#{with_repo}/env_vars", env_var_keys(create)) end + + get("#{with_repo}/env_vars") end + # A GitHub App installation. + # + # ## Attributes + # + # **Minimal Representation** + # + # Included when the resource is returned as part of another resource. + # + # Name Type Description + # id Integer The installation id. + # github_id Integer The installation's id on GitHub. + # + # **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 + # id Integer The installation id. + # github_id Integer The installation's id on GitHub. + # owner Owner GitHub user or organization the installation belongs to. + # + # ## Actions + # + # **Find** + # + # This returns a single installation. + # + # GET <code>/installation/{installation.github_id}</code> + # + # Template Variable Type Description + # installation.github_id Integer The installation's id on GitHub. + # Query Parameter Type Description + # include [String] List of attributes to eager load. + # + # @param installation_id [String, Integer] GitHub App installation id + # @return [Success, RequestError] + def installation(installation_id) + validate_number installation_id + + get("#{without_repo}/installation/#{installation_id}") + end + # An individual job. # # ## Attributes # # **Minimal Representation** @@ -734,11 +989,11 @@ # Template Variable Type Description # job.id Integer Value uniquely identifying the job. # # Example: POST /job/86601347/debug # - # @note POST requests require an authorization token set in the headers. See: {h} + # @note POST requests require an authorization token set in the headers. See: {authorization=} # # @param job_id [String, Integer] the job id number # @param option [Symbol] options for :cancel, :restart, or :debug # @return [Success, RequestError] def job(job_id, option = nil) @@ -884,20 +1139,20 @@ # 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 requests require an authorization token set in the headers. See: {authorization=} # @note API enpoint needs to be set to `https://api.travis-ci.com` See: {api_endpoint=} # - # @overload key_par() + # @overload key_pair() # 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 + # @param create [Hash] Optional keyword argument. Create a new key pair from provided private key `{ description: "name", value: "private key" }` + # @param update [Hash] Optional keyword argument. Update key pair with hash `{ description: "new name" }` + # @param delete [Boolean] Optional keyword argument. 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)) @@ -970,11 +1225,11 @@ # 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} + # @note requests require an authorization token set in the headers. See: {authorization=} # # @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) @@ -1298,11 +1553,11 @@ # Example: GET /owner/danielpclark # # GET <code>/owner/{user.login}</code> # # Template Variable Type Description - # user.login String Login set on Github. + # user.login String Login set on GitHub. # # Query Parameter Type Description # include [String] List of attributes to eager load. # # Example: GET /owner/danielpclark @@ -1328,15 +1583,12 @@ # Example: GET /owner/github_id/639823 # # @param owner [String] username or github id # @return [Success, RequestError] def owner(owner = username) - if number? owner - get("#{without_repo}/owner/github_id/#{owner}") - else - get("#{without_repo}/owner/#{owner}") - end + number?(owner) and return get("#{without_repo}/owner/github_id/#{owner}") + get("#{without_repo}/owner/#{owner}") end # Document `resources/preference/overview` not found. # # ## Attributes @@ -1399,11 +1651,11 @@ # 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} + # @note requests require an authorization token set in the headers. See: {authorization=} # # @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] @@ -1411,15 +1663,12 @@ if org_id validate_number org_id org_id = "/org/#{org_id}" end - if value.nil? - get("#{without_repo}#{org_id}/preference/#{key}") - else - patch("#{without_repo}#{org_id}/preference/#{key}", 'preference.value' => value) - end + value and return patch("#{without_repo}#{org_id}/preference/#{key}", 'preference.value' => value) + get("#{without_repo}#{org_id}/preference/#{key}") end # Document `resources/preferences/overview` not found. # # ## Attributes @@ -1451,11 +1700,11 @@ # 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} + # @note requests require an authorization token set in the headers. See: {authorization=} # # @param org_id [String, Integer] optional organization id # @return [Success, RequestError] def preferences(org_id = nil) if org_id @@ -1519,11 +1768,11 @@ # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order. # # GET <code>/owner/{user.login}/repos</code> # # Template Variable Type Description - # user.login String Login set on Github. + # user.login String Login set on GitHub. # # Query Parameter Type Description # active [Boolean] Alias for repository.active. # include [String] List of attributes to eager load. # limit Integer How many repositories to include in the response. Used for pagination. @@ -1604,15 +1853,12 @@ # **Sortable by:** <code>id</code>, <code>github_id</code>, <code>owner_name</code>, <code>name</code>, <code>active</code>, <code>default_branch.last_build</code>, append <code>:desc</code> to any attribute to reverse order. # # @param owner [String] username or github id # @return [Success, RequestError] def repositories(owner = username) - if number? owner - get("#{without_repo}/owner/github_id/#{owner}/repos#{opts}") - else - get("#{without_repo}/owner/#{owner}/repos#{opts}") - end + number?(owner) and return get("#{without_repo}/owner/github_id/#{owner}/repos#{opts}") + get("#{without_repo}/owner/#{owner}/repos#{opts}") end # An individual repository. # # ## Attributes @@ -1738,28 +1984,24 @@ # Template Variable Type Description # repository.slug String Same as {repository.owner.name}/{repository.name}. # # Example: POST /repo/rails%2Frails/unstar # - # @note POST requests require an authorization token set in the headers. See: {h} + # @note POST requests require an authorization token set in the headers. See: {authorization=} # # @param repo [String] github_username/repository_name # @param action [String, Symbol] Optional argument for star/unstar/activate/deactivate # @raise [InvalidRepository] if given input does not # conform to valid repository identifier format # @return [Success, RequestError] def repository(repo = repository_name, action = nil) validate_repo_format repo repo = sanitize_repo_name repo - action = '' unless %w[star unstar activate deactivate].include? action.to_s - if action.empty? - get("#{without_repo}/repo/#{repo}") - else - post("#{without_repo}/repo/#{repo}/#{action}") - end + action and return post("#{without_repo}/repo/#{repo}/#{action}") + get("#{without_repo}/repo/#{repo}") end # An individual request # # ## Attributes @@ -2158,25 +2400,25 @@ # # Included when the resource is returned as part of another resource. # # Name Type Description # id Integer Value uniquely identifying the user. - # login String Login set on Github. + # login String Login set on GitHub. # # **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 # id Integer Value uniquely identifying the user. - # login String Login set on Github. + # login String Login set on GitHub. # name String Name set on GitHub. # github_id Integer Id set on GitHub. # avatar_url String Avatar URL set on GitHub. # education Boolean Whether or not the user has an education account. # allow_migration Unknown The user's allow_migration. - # is_syncing Boolean Whether or not the user is currently being synced with Github. + # is_syncing Boolean Whether or not the user is currently being synced with GitHub. # synced_at String The last time the user was synced with GitHub. # # **Additional Attributes** # # Name Type Description @@ -2220,26 +2462,23 @@ # include [String] List of attributes to eager load. # # Example: GET /user # # @note sync feature may not be permitted - # @note POST requests require an authorization token set in the headers. See: {h} + # @note POST requests require an authorization token set in the headers. See: {authorization=} # # @param user_id [String, Integer] optional user id - # @param sync [Boolean] optional argument for syncing your Travis CI account with Github + # @param sync [Boolean] optional argument for syncing your Travis CI account with GitHub # @raise [TypeError] if given user id is not a number # @return [Success, RequestError] def user(user_id = nil, sync = false) return get("#{without_repo}/user") if !user_id && !sync validate_number user_id - if sync - get("#{without_repo}/user/#{user_id}/sync") - else - get("#{without_repo}/user/#{user_id}") - end + sync and return get("#{without_repo}/user/#{user_id}/sync") + get("#{without_repo}/user/#{user_id}") end private # @private def create(url, data = {}) @@ -2248,10 +2487,14 @@ def delete(url) Trav3::REST.delete(self, url) end + def env_var_keys(hash) + inject_property_name('env_var', hash) + end + def get(url, raw_reply = false) Trav3::REST.get(self, url, raw_reply) end def get_path(url) @@ -2271,12 +2514,16 @@ h('Content-Type': 'application/json') h('Accept': 'application/json') h('Travis-API-Version': 3) end + def inject_property_name(name, hash) + hash.map { |k, v| ["#{name}.#{k}", v] }.to_h unless hash.keys.first.match?(/#{name}\.\w+/) + end + def key_pair_keys(hash) - hash.map { |k, v| ["key_pair.#{k}", v] }.to_h unless hash.keys.first.match?(/key_pair\.\w+/) + inject_property_name('key_pair', hash) end def number?(input) /^\d+$/.match? input.to_s end @@ -2294,9 +2541,24 @@ end def validate_api_endpoint(input) raise InvalidAPIEndpoint unless /^https:\/\/api\.travis-ci\.(?:org|com)$/.match? input end + + # rubocop:disable Metrics/CyclomaticComplexity + def validate_env_var(input) + raise TypeError, "Hash expected, #{input.class} given" unless input.is_a? Hash + raise EnvVarError unless input.all? do |k, v| + k.match?(/name|value|public/) && + case k.to_s + when /name/ then v.is_a? String + when /value/ then v.is_a? String + when /public/ then [true, false].include? v + else false + end + end + end + # rubocop:enable Metrics/CyclomaticComplexity def validate_number(input) raise TypeError, "Integer expected, #{input.class} given" unless number? input end