module Gems::API::VersionEndpoints

Returns the sigstore attestations published with a gem version

@api public @authenticated false @param gem_name [String, Gem, Version] The name of a gem, or a gem or version. A gem or version stands in

for the version argument too, so that reading the attestations of a version reads that version.

@param version [String, Version, Gem, nil] The requested version of the gem (defaults to the version given

as the gem, or to the latest version).

@param platform [String, nil] The platform of the version, such as “java” or “x86_64-linux”; defaults to the

platform of a gem or version object, or "ruby".

@return [Array<Hash>] the sigstore bundles, empty for versions pushed without attestations @raise [NoLatestVersion] if no version is given and the gem has no published version @raise [ArgumentError] if the version was built for a Ruby ABI, which the endpoint looks up by a full name

RubyGems.org answers with only for the versions {API::DownloadEndpoints#most_downloaded} returns

@example

Gems.attestations("rails", "8.1.3.1").first["mediaType"]

@example

Gems.attestations "nokogiri", "1.15.0", platform: "java"

@example

Gems.attestations Gems.rubygem("rails")

# File lib/gems/api/version_endpoints.rb, line 126
def attestations(gem_name, version = nil, platform: nil)
  version = version_of(gem_name, version) || latest_version(gem_name)
  parse_json(get("/api/v1/attestations/#{escape(full_name_of(gem_name, version, platform))}.json"))
end

Returns the SHA-256 checksum of every file packaged in a specific gem version

Only versions pushed after RubyGems.org started recording file manifests have this data.

@api public @authenticated false @param gem_name [String, Gem, Version] The name of a gem, or a gem or version. A gem or version stands in

for the version argument too, so that reading the contents of a version reads that version.

@param version [String, Version, Gem, nil] The requested version of the gem (defaults to the version given

as the gem, or to the latest version).

@param platform [String, nil] The platform of the version, such as “java” or “x86_64-linux”; defaults to the

platform of a gem or version object, or "ruby".

@param ruby_abi [String, nil] The Ruby ABI a version of the platform was built for, such as “3.4”; defaults to

the Ruby ABI of a gem or version object, or to the version built for none.

@return [Hash{String => Hash{String => String}}] the checksums of each file, keyed by path @raise [NoLatestVersion] if no version is given and the gem has no published version @example

Gems.contents("rails", "8.1.3.1")["README.md"]["sha256"]

@example

Gems.contents Gems.rubygem("rails")

# File lib/gems/api/version_endpoints.rb, line 99
def contents(gem_name, version = nil, platform: nil, ruby_abi: nil)
  version = version_of(gem_name, version)
  number = number_of(version) || latest_version(gem_name)
  path = "/api/v2/rubygems/#{escape(name_of(gem_name))}/versions/#{escape(number)}/contents.json"
  parse_json(get(path, build_params(version, platform, ruby_abi)))
end

Returns the latest version number of a gem

@api public @authenticated false @param gem_name [String, Gem, Version] The name of a gem, or a gem or version. @return [String] the latest version number @raise [NoLatestVersion] if the gem has no published version @example

Gems.latest_version "coulda"

# File lib/gems/api/version_endpoints.rb, line 43
def latest_version(gem_name)
  response = get("/api/v1/versions/#{escape(name_of(gem_name))}/latest.json")
  version = parse_json(response) { |json| json.fetch("version") }
  # The endpoint answers 200 with "unknown" rather than 404 for a gem with no published version
  raise NoLatestVersion, "#{name_of(gem_name)} has no latest version" if version.eql?("unknown")

  version
end

Returns the gem versions created within a timeframe of up to seven days

The results are paginated, 30 versions at a time; use the page option until an empty list is returned.

@api public @authenticated false @param from [Time, String] The start of the timeframe, as a Time or an ISO 8601 string. @param to [Time, String, nil] The end of the timeframe; defaults to now. @param page [Integer, nil] The page of results to return. @return [Array<Gem>] @example

Gems.timeframe_versions from: Time.now - 86_400

# File lib/gems/api/version_endpoints.rb, line 143
def timeframe_versions(from:, to: nil, page: nil)
  params = {from: timestamp_of(from), to: timestamp_of(to), page:}.compact
  Gem.list(parse_json(get("/api/v1/timeframe_versions.json", params)))
end

Enumerates the gem versions created within a timeframe, a page at a time

The timeframe may span up to seven days. A page is requested only when the versions of the page before it have been enumerated, and the enumeration ends with the first empty page.

@api public @authenticated false @param from [Time, String] The start of the timeframe, as a Time or an ISO 8601 string. @param to [Time, String, nil] The end of the timeframe; defaults to now. @yield [gem] each version, when a block is given @return [Enumerator<Gem>] the versions @example

Gems.timeframe_versions_each(from: Time.now - 86_400).count

# File lib/gems/api/version_endpoints.rb, line 161
def timeframe_versions_each(from:, to: nil, &block)
  each_page(block) { |page| timeframe_versions(from:, to:, page:) }
end

Returns information about the given gem for a specific version

@api public @authenticated false @param gem_name [String, Gem, Version] The name of a gem, or a gem or version. A gem or version stands in

for the version argument too, so that reading a version reads that version.

@param version [String, Version, Gem, nil] The requested version of the gem (defaults to the version given

as the gem, or to the latest version).

@param platform [String, nil] The platform of the version, such as “java” or “x86_64-linux”; defaults to the

platform of a gem or version object, or "ruby".

@param ruby_abi [String, nil] The Ruby ABI a version of the platform was built for, such as “3.4”; defaults to

the Ruby ABI of a gem or version object, or to the version built for none.

@return [Version] @raise [NoLatestVersion] if no version is given and the gem has no published version @example

Gems.version "rails", "7.0.6"

@example

Gems.version "nokogiri", "1.15.0", platform: "java"

@example

Gems.version Gems.rubygem("rails")

# File lib/gems/api/version_endpoints.rb, line 72
def version(gem_name, version = nil, platform: nil, ruby_abi: nil)
  version = version_of(gem_name, version)
  number = number_of(version) || latest_version(gem_name)
  path = "/api/v2/rubygems/#{escape(name_of(gem_name))}/versions/#{escape(number)}.json"
  Version.new(parse_json(get(path, build_params(version, platform, ruby_abi))))
end

Returns an array of gem version details

@api public @authenticated false @param gem_name [String, Gem, Version] The name of a gem, or a gem or version. @return [Array<Version>] @example

Gems.versions "coulda"

# File lib/gems/api/version_endpoints.rb, line 29
def versions(gem_name)
  name = name_of(gem_name)
  Version.list(parse_json(get("/api/v1/versions/#{escape(name)}.json")).map { |version| version.merge("name" => name) })
end