sferik 0.0.1

data/lib/sferik/finger.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "social_profile"
+
+module Sferik
+  # Contact details and profiles, as returned by {API::ProfileEndpoints#finger}
+  # @api public
+  class Finger < Resource
+    # @!method name
+    #   The full name
+    #   @api public
+    #   @return [String] the full name
+    #   @example
+    #     finger.name # => "Erik Berlin"
+    attribute :name
+
+    # @!method login
+    #   The handle
+    #   @api public
+    #   @return [String] the handle
+    #   @example
+    #     finger.login # => "sferik"
+    attribute :login
+
+    # @!method mail
+    #   The email address
+    #   @api public
+    #   @return [String] the email address
+    #   @example
+    #     finger.mail # => "sferik@gmail.com"
+    attribute :mail
+
+    # @!method directory
+    #   The home directory, in the site's shell
+    #   @api public
+    #   @return [String] the home directory, in the site's shell
+    #   @example
+    #     finger.directory # => "/Users/sferik"
+    attribute :directory
+
+    # @!method shell
+    #   The login shell, in the site's shell
+    #   @api public
+    #   @return [String] the login shell, in the site's shell
+    #   @example
+    #     finger.shell # => "/opt/homebrew/bin/fish"
+    attribute :shell
+
+    # @!method plan
+    #   The .plan
+    #   @api public
+    #   @return [String] the .plan
+    #   @example
+    #     finger.plan # => "..."
+    attribute :plan
+
+    # @!method profiles
+    #   Profiles elsewhere
+    #   @api public
+    #   @return [Array<SocialProfile>] profiles elsewhere
+    #   @example
+    #     finger.profiles # => [#<Sferik::SocialProfile ...>, ...]
+    list :profiles, "profiles", type: SocialProfile
+
+    # @!method command
+    #   The shell command the home page shows it as
+    #   @api public
+    #   @return [String] the shell command the home page shows it as
+    #   @example
+    #     finger.command # => "finger sferik"
+    attribute :command
+  end
+end

data/lib/sferik/freshness.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Sferik
+  # Reads what an answer says about keeping a response: for how long it's good, and whether to keep it at all
+  #
+  # An answer is the response itself, or a 304 that says a response kept hasn't changed. It says how long the response
+  # is good for (Cache-Control: max-age), and how long it has been kept somewhere on its way already (Age), as one
+  # from Cloudflare's cache has.
+  #
+  # @api private
+  module Freshness
+    # The seconds a Cache-Control says a response is good for
+    MAX_AGE = /\bmax-age=(\d+)/i
+    private_constant :MAX_AGE
+
+    # A Cache-Control that says to check a response each time it's used
+    NO_CACHE = /\bno-cache\b/i
+    private_constant :NO_CACHE
+
+    # A Cache-Control that says not to keep a response
+    NO_STORE = /\bno-store\b/i
+    private_constant :NO_STORE
+
+    # The seconds an answer says a response is good for
+    #
+    # @api private
+    # @param answer [Net::HTTPResponse] the answer
+    # @return [Integer] the seconds: none if it says to check each time, or doesn't say
+    def self.lifetime(answer)
+      control = answer["cache-control"].to_s
+      (control[MAX_AGE, 1] unless NO_CACHE.match?(control)).to_i
+    end
+
+    # The seconds a response is still good for, when its answer comes
+    #
+    # @api private
+    # @param answer [Net::HTTPResponse] the answer
+    # @return [Integer] the seconds it's good for, less the whole seconds it says it has been kept already: none, or
+    #   fewer, for one that's no longer good
+    def self.left(answer)
+      lifetime(answer) - answer["age"].to_i
+    end
+
+    # Whether an answer lets a response be kept
+    #
+    # @api private
+    # @param answer [Net::HTTPResponse] the answer
+    # @return [Boolean] false if it says not to keep the response
+    def self.keepable?(answer)
+      !answer["cache-control"]&.match?(NO_STORE)
+    end
+  end
+  private_constant :Freshness
+end

data/lib/sferik/home/pages.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../resource"
+
+module Sferik
+  class Home < Resource
+    # The paths of the site's other pages, as returned in {Home#pages}
+    # @api public
+    class Pages < Resource
+      # @!method talks
+      #   The talks page
+      #   @api public
+      #   @return [String] the talks page
+      #   @example
+      #     pages.talks # => "/talks"
+      attribute :talks
+
+      # @!method resume
+      #   The resume page
+      #   @api public
+      #   @return [String] the resume page
+      #   @example
+      #     pages.resume # => "/resume"
+      attribute :resume
+    end
+  end
+end

data/lib/sferik/home/profile.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../resource"
+
+module Sferik
+  class Home < Resource
+    # Who the home page is about, as returned in {Home#profile}
+    # @api public
+    class Profile < Resource
+      # @!method name
+      #   The name
+      #   @api public
+      #   @return [String] the name
+      #   @example
+      #     profile.name # => "Erik Berlin"
+      attribute :name
+
+      # @!method location
+      #   Where Erik lives
+      #   @api public
+      #   @return [String] where Erik lives
+      #   @example
+      #     profile.location # => "San Francisco, California"
+      attribute :location
+
+      # @!method tagline
+      #   The tagline
+      #   @api public
+      #   @return [String] the tagline
+      #   @example
+      #     profile.tagline # => "I build libraries and tools software engineers depend on."
+      attribute :tagline
+
+      # @!method handle
+      #   The handle used everywhere
+      #   @api public
+      #   @return [String] the handle used everywhere
+      #   @example
+      #     profile.handle # => "sferik"
+      attribute :handle
+
+      # @!method url
+      #   The site
+      #   @api public
+      #   @return [String] the site
+      #   @example
+      #     profile.url # => "https://sferik.net"
+      attribute :url
+    end
+  end
+end

data/lib/sferik/home/section.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative "../resource"
+
+module Sferik
+  class Home < Resource
+    # One of the home page's modules, as returned in {Home#modules}
+    # @api public
+    class Section < Resource
+      # @!method id
+      #   The module's name
+      #   @api public
+      #   @return [String] the module's name
+      #   @example
+      #     section.id # => "whoami"
+      attribute :id
+
+      # @!method url
+      #   Its path, which {Client#get} takes
+      #   @api public
+      #   @return [String] its path, which {Client#get} takes
+      #   @example
+      #     section.url # => "/whoami"
+      attribute :url
+    end
+  end
+end

data/lib/sferik/home.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "home/pages"
+require_relative "home/profile"
+require_relative "home/section"
+
+module Sferik
+  # The profile and the home page's modules, as returned by {API::ProfileEndpoints#home}
+  # @api public
+  class Home < Resource
+    # @!method profile
+    #   Who the site is about
+    #   @api public
+    #   @return [Profile] who the site is about
+    #   @example
+    #     home.profile # => #<Sferik::Home::Profile ...>
+    attribute :profile, "profile", type: Profile
+
+    # @!method modules
+    #   The home page's modules, in order
+    #   @api public
+    #   @return [Array<Section>] the home page's modules, in order
+    #   @example
+    #     home.modules # => [#<Sferik::Home::Section id="whoami" ...>, ...]
+    list :modules, "modules", type: Section
+
+    # @!method pages
+    #   The paths of the other pages
+    #   @api public
+    #   @return [Pages] the paths of the other pages
+    #   @example
+    #     home.pages # => #<Sferik::Home::Pages ...>
+    attribute :pages, "pages", type: Pages
+
+    inspect_with :profile
+  end
+end

data/lib/sferik/json_parsing.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "errors"
+
+module Sferik
+  # Parses the API's JSON responses, for the endpoints that return objects
+  # @api private
+  module JSONParsing
+    private
+
+    # Parse a JSON response body
+    #
+    # @api private
+    # @param body [String] the response body
+    # @return [Hash] the parsed body, deep-frozen
+    # @raise [InvalidResponse] if the body isn't a JSON object, or isn't in the charset the response names (or one JSON can be read in)
+    def parse_json(body)
+      value = JSON.parse(body, freeze: true)
+      raise InvalidResponse, "Expected a JSON object, got #{value.class}" unless value.instance_of?(Hash)
+
+      value
+    rescue JSON::ParserError, EncodingError => e
+      raise InvalidResponse, "Couldn't parse the response as JSON: #{e}"
+    end
+  end
+  private_constant :JSONParsing
+end

data/lib/sferik/name_change.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Sferik
+  # The name change, as a git commit, as returned by {API::ProfileEndpoints#name_change}
+  # @api public
+  class NameChange < Resource
+    # @!method subject
+    #   The commit's subject
+    #   @api public
+    #   @return [String] the commit's subject
+    #   @example
+    #     name_change.subject # => "Rename Erik Michaels-Ober to Erik Berlin"
+    attribute :subject
+
+    # @!method year
+    #   The year of the change
+    #   @api public
+    #   @return [Integer] the year of the change
+    #   @example
+    #     name_change.year # => 2017
+    attribute :year
+
+    # @!method commit
+    #   The commit's abbreviated hash
+    #   @api public
+    #   @return [String] the commit's abbreviated hash
+    #   @example
+    #     name_change.commit # => "8c0d698"
+    attribute :commit
+
+    # @!method notes
+    #   More about it, as HTML
+    #   @api public
+    #   @return [Array<String>] more about it, as HTML
+    #   @example
+    #     name_change.notes # => ["..."]
+    list :notes
+
+    # @!method command
+    #   The shell command the home page shows it as
+    #   @api public
+    #   @return [String] the shell command the home page shows it as
+    #   @example
+    #     name_change.command # => "git log --follow --oneline -- name"
+    attribute :command
+  end
+end

data/lib/sferik/place.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Sferik
+  # Where a talk's location is, as returned in {Talks#places}
+  # @api public
+  class Place < Resource
+    # @!method lat
+    #   The latitude, in degrees
+    #   @api public
+    #   @return [Numeric] the latitude, in degrees
+    #   @example
+    #     place.lat # => 41.39
+    attribute :lat
+
+    # @!method lon
+    #   The longitude, in degrees
+    #   @api public
+    #   @return [Numeric] the longitude, in degrees
+    #   @example
+    #     place.lon # => 2.17
+    attribute :lon
+
+    # @!method country
+    #   The country it's in
+    #   @api public
+    #   @return [String] the country it's in
+    #   @example
+    #     place.country # => "Spain"
+    attribute :country
+  end
+end

data/lib/sferik/podcast.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Sferik
+  # A podcast appearance, as returned in {Talks#podcasts}
+  # @api public
+  class Podcast < Resource
+    # @!method title
+    #   The episode's title
+    #   @api public
+    #   @return [String] the episode's title
+    #   @example
+    #     podcast.title # => "The Crystal Programming Language"
+    attribute :title
+
+    # @!method show
+    #   The podcast
+    #   @api public
+    #   @return [String] the podcast
+    #   @example
+    #     podcast.show # => "Ruby Rogues, episode 248"
+    attribute :show
+
+    # @!method date
+    #   When it was, to the month: the first day of that month
+    #   @api public
+    #   @return [Date] the first day of the month it was in
+    #   @example
+    #     podcast.date # => #<Date: 2016-02-01>
+    timestamp :date, PartialDate
+
+    # @!method url
+    #   The episode
+    #   @api public
+    #   @return [String] the episode
+    #   @example
+    #     podcast.url # => "https://..."
+    attribute :url
+  end
+end

data/lib/sferik/project.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Sferik
+  # A project, as returned in {Projects#projects}
+  # @api public
+  class Project < Resource
+    # @!method name
+    #   The project's name
+    #   @api public
+    #   @return [String] the project's name
+    #   @example
+    #     project.name # => "multi_json"
+    attribute :name
+
+    # @!method description
+    #   What it is
+    #   @api public
+    #   @return [String] what it is
+    #   @example
+    #     project.description # => "One interface to every Ruby JSON library."
+    attribute :description
+
+    # @!method downloads
+    #   Its RubyGems downloads, or nil if it isn't a gem
+    #   @api public
+    #   @return [Integer, nil] its RubyGems downloads, or nil if it isn't a gem
+    #   @example
+    #     project.downloads # => 1_170_000_000
+    attribute :downloads
+
+    # @!method stars
+    #   Its GitHub stars, or nil if it isn't on GitHub
+    #   @api public
+    #   @return [Integer, nil] its GitHub stars, or nil if it isn't on GitHub
+    #   @example
+    #     project.stars # => 27
+    attribute :stars
+
+    # @!method url
+    #   Its home page
+    #   @api public
+    #   @return [String] its home page
+    #   @example
+    #     project.url # => "https://github.com/sferik/multi_json"
+    attribute :url
+  end
+end

data/lib/sferik/projects.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "collection"
+require_relative "project"
+
+module Sferik
+  # Projects with their downloads and stars, as returned by {API::CodeEndpoints#projects}
+  #
+  # It's Enumerable over its {#projects}, so `Sferik.projects.first` is the most downloaded, and
+  # `Sferik.projects.map(&:name)` lists them all. It also has what an Array adds to that: {#size}, {#length},
+  # {#empty?}, {#last}, and {#[]}.
+  #
+  # @api public
+  class Projects < Resource
+    include Enumerable
+    include Collection
+
+    # ActiveSupport's Enumerable#as_json would make a list of them; keep the JSON it came from, as for any resource
+    define_method(:as_json, Resource.instance_method(:as_json))
+
+    # @!method projects
+    #   The projects, most downloaded first, with related ones together
+    #   @api public
+    #   @return [Array<Project>] the projects, most downloaded first, with related ones together
+    #   @example
+    #     projects.projects # => [#<Sferik::Project ...>, ...]
+    list :projects, "projects", type: Project
+
+    # The RubyGems downloads of every gem @sferik owns, not only those listed
+    #
+    # @api public
+    # @return [Integer, nil] the RubyGems downloads of every gem @sferik owns, not only those listed
+    # @example
+    #   projects.total_downloads # => 5_460_234_129
+    def total_downloads
+      total["downloads"]
+    end
+    record :total_downloads
+
+    # The number of gems @sferik owns
+    #
+    # @api public
+    # @return [Integer, nil] the number of gems @sferik owns
+    # @example
+    #   projects.total_gems # => 65
+    def total_gems
+      total["gems"]
+    end
+    record :total_gems
+
+    # The GitHub stars of the projects listed
+    #
+    # @api public
+    # @return [Integer, nil] the GitHub stars of the projects listed
+    # @example
+    #   projects.total_stars # => 38_000
+    def total_stars
+      total["stars"]
+    end
+    record :total_stars
+
+    # @!method more
+    #   Where to find the rest
+    #   @api public
+    #   @return [String] where to find the rest
+    #   @example
+    #     projects.more # => "https://github.com/sferik"
+    attribute :more
+
+    # @!method live?
+    #   Whether the downloads are what RubyGems says now
+    #
+    #   They aren't when they're the snapshot, which the site falls back to, or the last that were fetched, more than
+    #   two hours ago, which it goes on with when it can't fetch them again: {#as_of} says when they're from.
+    #
+    #   @api public
+    #   @return [Boolean] false when the downloads are a snapshot, or were last fetched more than two hours ago
+    #   @example
+    #     projects.live? # => true
+    predicate :live
+
+    # @!method as_of
+    #   When the downloads are from
+    #
+    #   That's the hour they were fetched in, or the day of the snapshot, if they're that. It's to the hour so that
+    #   downloads that are fetched again, and haven't changed, are the same response, which a {Client#cached} client
+    #   isn't sent again: {Status::Loaded#gems} is when they were fetched, to the second.
+    #
+    #   @api public
+    #   @return [Time] when the downloads are from
+    #   @example
+    #     projects.as_of # => 2026-10-08 01:00:00 UTC
+    timestamp :as_of, Time
+
+    # @!method command
+    #   The shell command the home page shows it as
+    #   @api public
+    #   @return [String] the shell command the home page shows it as
+    #   @example
+    #     projects.command # => "ls -lS ~/src"
+    attribute :command
+
+    inspect_with :size, :total_downloads, :total_stars
+
+    # Yield each project, most downloaded first (related projects together)
+    #
+    # @api public
+    # @yieldparam project [Project] a project
+    # @return [self, Enumerator<Project>] the projects themselves, or an Enumerator without a block
+    # @example
+    #   Sferik.projects.each { |project| puts project.name }
+    def each(&block)
+      return to_enum { size } unless block
+
+      projects.each(&block)
+      self
+    end
+
+    private
+
+    # The totals, which are empty when the response has none, and are checked when the projects are built
+    prepare(:total) do
+      value = given(attributes["total"], NONE)
+      raise InvalidResponse, "#{self.class}#total: expected a JSON object, got #{value.class}" unless value.instance_of?(Hash)
+
+      value
+    end
+
+    # The totals, which are empty when the response has none
+    #
+    # @api private
+    # @return [Hash{String => Object}] the totals
+    def total
+      prepared(:total)
+    end
+  end
+end

data/lib/sferik/push.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Sferik
+  # A push to GitHub, as returned by {Contributions#last_push}
+  # @api public
+  class Push < Resource
+    # @!method repo
+    #   The repository
+    #   @api public
+    #   @return [String] the repository
+    #   @example
+    #     push.repo # => "sferik/x-ruby"
+    attribute :repo
+
+    # @!method sha
+    #   The commit at the head of the push
+    #   @api public
+    #   @return [String] the commit at the head of the push
+    #   @example
+    #     push.sha # => "abc1234def5678"
+    attribute :sha
+
+    # @!method at
+    #   When it was pushed
+    #   @api public
+    #   @return [Time] when it was pushed
+    #   @example
+    #     push.at # => 2026-10-01 12:00:00 UTC
+    timestamp :at, Time
+  end
+end