sferik 0.0.1

data/lib/sferik/talks.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "collection"
+require_relative "talk"
+require_relative "place"
+require_relative "podcast"
+
+module Sferik
+  # Conference talks and podcasts, as returned by {API::TalkEndpoints#talks}
+  #
+  # It's Enumerable over its {#talks}, so `Sferik.talks.first` is the newest, and `Sferik.talks.map(&:title)` lists
+  # them all. It also has what an Array adds to that: {#size}, {#length}, {#empty?}, {#last}, and {#[]}.
+  #
+  # @api public
+  class Talks < 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 talks
+    #   The talks, newest first
+    #   @api public
+    #   @return [Array<Talk>] the talks, newest first
+    #   @example
+    #     talks.talks # => [#<Sferik::Talk ...>, ...]
+    list :talks, "talks", type: Talk
+
+    # @!method places
+    #   Where each talk's location is, by the name {Talk#location} gives it
+    #   @api public
+    #   @return [Hash{String => Place}] where each talk's location is, by name
+    #   @example
+    #     talks.places["Barcelona"] # => #<Sferik::Place lat=41.39 lon=2.17 country="Spain">
+    dictionary :places, type: Place
+
+    # @!method podcasts
+    #   The podcast appearances
+    #   @api public
+    #   @return [Array<Podcast>] the podcast appearances
+    #   @example
+    #     talks.podcasts # => [#<Sferik::Podcast ...>, ...]
+    list :podcasts, "podcasts", type: Podcast
+
+    # @!method speaker_deck
+    #   Where the slides are
+    #   @api public
+    #   @return [String] where the slides are
+    #   @example
+    #     talks.speaker_deck # => "https://speakerdeck.com/sferik"
+    attribute :speaker_deck
+
+    # @!method command
+    #   The shell command the home page shows the newest talks as
+    #   @api public
+    #   @return [String] the shell command the home page shows the newest talks as
+    #   @example
+    #     talks.command # => "ls -t ~/talks | head -6"
+    attribute :command
+
+    inspect_with :size, :speaker_deck
+
+    # Yield each talk, newest first
+    #
+    # @api public
+    # @yieldparam talk [Talk] a talk
+    # @return [self, Enumerator<Talk>] the talks themselves, or an Enumerator without a block
+    # @example
+    #   Sferik.talks.each { |talk| puts talk.title }
+    def each(&block)
+      return to_enum { size } unless block
+
+      talks.each(&block)
+      self
+    end
+  end
+end

data/lib/sferik/validation.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Sferik
+  # Checks the options of a client and the arguments of its requests, for {Client}, and the attributes of a {Resource}
+  #
+  # A wrong one raises ArgumentError where it's given, rather than an error in the middle of a request.
+  #
+  # @api private
+  module Validation
+    private
+
+    # Check the type of an option, an argument, or a resource's attributes
+    #
+    # A wrong one fails here rather than in the middle of a request.
+    #
+    # @api private
+    # @param option [Symbol] the option's name, or the argument's: :path, :body, :accept, :token, :page, :tty, :attributes, or :key
+    # @param value [Object] its value
+    # @param type [Class] the class its value should be of
+    # @return [Object] the value
+    # @raise [ArgumentError] if the value isn't of that class
+    def check(option, value, type)
+      return value if value.is_a?(type)
+
+      raise ArgumentError, "#{option} must be #{type}, not #{value.inspect}"
+    end
+
+    # Check that a host is an http or https URL, and no more than one
+    #
+    # One without a scheme, like "localhost:3745", fails here rather than in the middle of a request. So does one
+    # with a query or a fragment, which a path added to it would be part of, and one with credentials, which are
+    # never sent.
+    #
+    # @api private
+    # @param value [String] the host
+    # @return [String] the host
+    # @raise [ArgumentError] if the host isn't an http or https URL, or has credentials, a query, or a fragment
+    def http_url(value)
+      uri = URI.parse(value)
+      raise URI::InvalidURIError unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+      return value if [uri.userinfo, uri.query, uri.fragment].none?
+
+      raise ArgumentError, "host must have no credentials, query, or fragment, not #{value.inspect}"
+    rescue URI::InvalidURIError
+      raise ArgumentError, "host must be an http or https URL, not #{value.inspect}"
+    end
+
+    # Check that an option is true or false
+    #
+    # @api private
+    # @param option [Symbol] the option's name
+    # @param value [Object] its value
+    # @return [Boolean] the value
+    # @raise [ArgumentError] if the value is neither true nor false
+    def boolean(option, value)
+      return value if [true, false].include?(value)
+
+      raise ArgumentError, "#{option} must be true or false, not #{value.inspect}"
+    end
+
+    # Check that the value of a header is on one line
+    #
+    # Net::HTTP fails in the middle of a request with one that has a carriage return or a line feed.
+    #
+    # @api private
+    # @param option [Symbol] the option's name, or :accept
+    # @param value [String] its value
+    # @return [String] the value
+    # @raise [ArgumentError] if the value has a line break
+    def one_line(option, value)
+      return value unless value.match?(/[\r\n]/)
+
+      raise ArgumentError, "#{option} must be on one line, not #{value.inspect}"
+    end
+
+    # Check that a timeout is a number of seconds, positive and finite
+    #
+    # @api private
+    # @param option [Symbol] the option's name
+    # @param value [Object] its value
+    # @return [Numeric] the value
+    # @raise [ArgumentError] if the value isn't Numeric, or isn't positive and finite
+    def seconds(option, value)
+      positive(option, check(option, value, Numeric))
+    end
+
+    # Check that a timeout is positive and finite
+    #
+    # Net::HTTP waits forever with one of 0, or an infinite one, and fails in the middle of a request with a negative
+    # one. A complex number is Numeric, but is neither positive nor negative.
+    #
+    # @api private
+    # @param option [Symbol] the option's name
+    # @param value [Numeric] its value
+    # @return [Numeric] the value
+    # @raise [ArgumentError] if the value isn't a real number, isn't finite, or isn't positive
+    def positive(option, value)
+      return value if value.real? && value.finite? && value.positive?
+
+      raise ArgumentError, "#{option} must be positive and finite, not #{value}"
+    end
+
+    # Check that a limit isn't negative
+    #
+    # @api private
+    # @param option [Symbol] the option's name
+    # @param value [Integer] its value
+    # @return [Integer] the value
+    # @raise [ArgumentError] if the value is negative
+    def not_negative(option, value)
+      return value unless value.negative?
+
+      raise ArgumentError, "#{option} must be 0 or more, not #{value}"
+    end
+  end
+  private_constant :Validation
+end

data/lib/sferik/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sferik
+  # The version of the library
+  # @api public
+  VERSION = "0.0.1"
+end

data/lib/sferik/web_finger/link.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "../resource"
+
+module Sferik
+  class WebFinger < Resource
+    # Something an account links to, as returned in {WebFinger#links}
+    #
+    # A link has a URL or a template for one, not both.
+    #
+    # @api public
+    class Link < Resource
+      # @!method rel
+      #   What the link is to the account
+      #   @api public
+      #   @return [String] what the link is to the account
+      #   @example
+      #     link.rel # => "http://webfinger.net/rel/profile-page"
+      attribute :rel
+
+      # @!method type
+      #   The media type of what's at the URL
+      #   @api public
+      #   @return [String, nil] the media type of what's at the URL, or nil for a link with a template
+      #   @example
+      #     link.type # => "text/html"
+      attribute :type
+
+      # @!method href
+      #   The URL
+      #   @api public
+      #   @return [String, nil] the URL, or nil for a link with a template
+      #   @example
+      #     link.href # => "https://mastodon.social/@sferik"
+      attribute :href
+
+      # @!method template
+      #   A template for a URL, with the account to follow from as {uri}
+      #   @api public
+      #   @return [String, nil] the template, or nil for a link with a URL
+      #   @example
+      #     link.template # => "https://mastodon.social/authorize_interaction?uri={uri}"
+      attribute :template
+    end
+  end
+end

data/lib/sferik/web_finger.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "web_finger/link"
+
+module Sferik
+  # Where an account at sferik.net points to, as returned by {API::ProfileEndpoints#webfinger}
+  #
+  # It's a JSON Resource Descriptor, as WebFinger (RFC 7033) answers with: the account on Mastodon, which makes the
+  # domain a fediverse handle.
+  #
+  # @api public
+  class WebFinger < Resource
+    # @!method subject
+    #   The account this one points to, as an acct: URI
+    #   @api public
+    #   @return [String] the account this one points to, as an acct: URI
+    #   @example
+    #     webfinger.subject # => "acct:sferik@mastodon.social"
+    attribute :subject
+
+    # @!method aliases
+    #   The URLs the account goes by
+    #   @api public
+    #   @return [Array<String>] the URLs the account goes by
+    #   @example
+    #     webfinger.aliases # => ["https://mastodon.social/@sferik", "https://mastodon.social/users/sferik"]
+    list :aliases
+
+    # @!method links
+    #   What the account links to
+    #
+    #   That's its profile page, itself as ActivityPub, and where to follow it.
+    #
+    #   @api public
+    #   @return [Array<Link>] what the account links to
+    #   @example
+    #     webfinger.links # => [#<Sferik::WebFinger::Link ...>, ...]
+    list :links, "links", type: Link
+
+    inspect_with :subject
+  end
+end

data/lib/sferik/who.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "collection"
+require_relative "session"
+
+module Sferik
+  # Everyone reading the site right now, as returned by {API::SiteEndpoints#who} and {API::SiteEndpoints#check_in}
+  #
+  # It's Enumerable over its {#users}, so `Sferik.who.map(&:page)` lists the pages being read. It also has what an
+  # Array adds to that: {#size}, {#length}, {#empty?}, {#last}, and {#[]}.
+  #
+  # @api public
+  class Who < 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 users
+    #   The terminals logged in: one per browser tab
+    #   @api public
+    #   @return [Array<Session>] the terminals logged in: one per browser tab
+    #   @example
+    #     who.users # => [#<Sferik::Session tty="ttys001" page="/" login=2026-10-06 12:00:00 UTC>]
+    list :users, "users", type: Session
+
+    # @!method you
+    #   The terminal that checked in, from {API::SiteEndpoints#check_in}
+    #   @api public
+    #   @return [String, nil] the terminal's name: nil when every terminal is taken, or when nobody checked in
+    #   @example
+    #     Sferik.check_in(token).you # => "ttys001"
+    attribute :you
+
+    inspect_with :size
+
+    # Yield each terminal
+    #
+    # @api public
+    # @yieldparam session [Session] a terminal
+    # @return [self, Enumerator<Session>] the terminals themselves, or an Enumerator without a block
+    # @example
+    #   Sferik.who.each { |session| puts session.tty }
+    def each(&block)
+      return to_enum { size } unless block
+
+      users.each(&block)
+      self
+    end
+  end
+end

data/lib/sferik/whoami.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "block"
+
+module Sferik
+  # The bio, as returned by {API::ProfileEndpoints#whoami}
+  # @api public
+  class Whoami < Resource
+    # @!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
+    #     whoami.command # => "whoami"
+    attribute :command
+
+    # @!method blocks
+    #   The paragraphs, in order
+    #   @api public
+    #   @return [Array<Block>] the paragraphs, in order
+    #   @example
+    #     whoami.blocks # => [#<Sferik::Block ...>, ...]
+    list :blocks, "blocks", type: Block
+
+    # @!method multi_downloads
+    #   The combined RubyGems downloads of multi_json and multi_xml
+    #   @api public
+    #   @return [Integer] the combined RubyGems downloads of multi_json and multi_xml
+    #   @example
+    #     whoami.multi_downloads # => 1_776_825_140
+    attribute :multi_downloads
+
+    inspect_with :command, :multi_downloads
+  end
+end

data/lib/sferik/wrapping.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "validation"
+
+module Sferik
+  # Checks the attributes of a resource, freezes the values of a response, and wraps them in resources, for {Resource}
+  # @api private
+  module Wrapping
+    include Validation
+
+    private
+
+    # A value of the response, or something else when the response has nothing there
+    #
+    # Nothing is null, which is what a key that's missing reads as too. False isn't nothing: it's a value, and where
+    # a list or an object belongs, the wrong one.
+    #
+    # @api private
+    # @param value [Object] the value
+    # @param otherwise [Object] what to return when the response has nothing there
+    # @return [Object] the value, or what was given in its place
+    def given(value, otherwise)
+      value.nil? ? otherwise : value
+    end
+
+    # Wrap a value in a resource class
+    #
+    # @api private
+    # @param value [Object] the value
+    # @param type [Class, nil] the resource class, or nil to leave the value as it is
+    # @return [Object] the value, wrapped
+    # @raise [InvalidResponse] if the value isn't a JSON object
+    def wrap(value, type)
+      (type.nil? || value.nil?) ? value : build(type, value)
+    end
+
+    # Wrap each value of a list in a resource class
+    #
+    # @api private
+    # @param name [Symbol] the reader of the list
+    # @param list [Object] the list
+    # @param type [Class, nil] the resource class, or nil to leave the values as they are
+    # @return [Array<Object>] the values, wrapped and frozen
+    # @raise [InvalidResponse] if the list isn't a JSON array, or one in it isn't a JSON object
+    def wrap_list(name, list, type)
+      raise InvalidResponse, "#{self.class}##{name}: expected a JSON array, got #{list.class}" unless list.instance_of?(Array)
+
+      type ? list.map { |item| build(type, item) }.freeze : list
+    end
+
+    # Wrap each value of a dictionary in a resource class
+    #
+    # @api private
+    # @param name [Symbol] the reader of the dictionary
+    # @param dictionary [Object] the dictionary
+    # @param type [Class] the resource class
+    # @return [Hash{String => Resource}] the values, wrapped and frozen
+    # @raise [InvalidResponse] if the dictionary isn't a JSON object, or one in it isn't
+    def wrap_dictionary(name, dictionary, type)
+      raise InvalidResponse, "#{self.class}##{name}: expected a JSON object, got #{dictionary.class}" unless dictionary.instance_of?(Hash)
+
+      dictionary.transform_values { |item| build(type, item) }.freeze
+    end
+
+    # Parse an ISO 8601 date or time
+    #
+    # @api private
+    # @param name [Symbol] the reader of the date or time
+    # @param value [Object] the value
+    # @param parser [#iso8601] Time, Date, or PartialDate for a date that may be given to the year or month
+    # @return [Time, Date, nil] the date or time, frozen, or nil if the response has none
+    # @raise [InvalidResponse] if the value isn't an ISO 8601 date or time
+    def wrap_timestamp(name, value, parser)
+      parser.iso8601(value).freeze unless value.nil?
+    rescue ArgumentError, TypeError
+      raise InvalidResponse, "#{self.class}##{name}: #{value.inspect} isn't an ISO 8601 #{parser.equal?(Time) ? "time" : "date"}"
+    end
+
+    # Build a resource from a JSON object
+    #
+    # @api private
+    # @param type [Class] the resource class
+    # @param value [Object] the value
+    # @return [Resource] the resource
+    # @raise [InvalidResponse] if the value isn't a JSON object
+    def build(type, value)
+      raise InvalidResponse, "Expected a JSON object for a #{type}, got #{value.class}" unless value.instance_of?(Hash)
+
+      type.new(value)
+    end
+
+    # A frozen copy of a value and everything in it
+    #
+    # The keys of every Hash must be strings, as the keys of JSON are: a reader's name as a Symbol (start_date:) is
+    # not the key the reader reads ("startDate"), so it fails here rather than reading as nil. What it's given is
+    # left as it was: a String that isn't frozen is copied, not frozen in place. The other values of JSON (numbers,
+    # true, false, and nil) are frozen as they are.
+    #
+    # @api private
+    # @param value [Object] the value
+    # @return [Object] the copy, frozen
+    # @raise [ArgumentError] if a key of a Hash isn't a String
+    def deep_freeze(value)
+      case value
+      when Hash then value.to_h { |key, item| [check(:key, key, String), deep_freeze(item)] }.freeze # a Hash freezes its String keys itself
+      when Array then value.map { |item| deep_freeze(item) }.freeze
+      when String then -value
+      else value
+      end
+    end
+  end
+  private_constant :Wrapping
+end