keybase-unofficial 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6f2d8d938af84a2c3cb88ab709c7170b8b79a547
-  data.tar.gz: ce7cdf851aabb48d774c29b2f905fb78f25169fa
+  metadata.gz: db0b875052bf623f798762c590f519e6143115f7
+  data.tar.gz: b501af569c38574f42652f2417513371b4fc2f63
 SHA512:
-  metadata.gz: 87fc6dd1a75b25d4384cb700222a5dfd4515f770c9403de60ddd4620401aa2e990b302a1ba0b99f0b29fbe794439b8914f02fec5a38843d0bbfc03390c9d87ac
-  data.tar.gz: 58cf490ff1a1165de3b30b7449611cce2dc1c054bbaa9647db761d89da32d72e6ebf891856039909484e70ad7a8fd8733c64a1f239f4fa35444cda74bff0da14
+  metadata.gz: cd0c47e547ead2245567014a587f0023014e7d251710c3be188302b0f0915fff88fd45c952d763f391d02c30ce58a29e0e24c41dc8bbb3a5a80dff0bdf98b396
+  data.tar.gz: c38b9d94a32786fa374de4bbef4c09cd61d9e1bb3701d7bcda497fded963b3d3daaeacaac07386bbc76f51df80cd5dcd02233e94d87be272b01fa972caa7bfea

data/README.md

@@ -1,6 +1,8 @@
 keybase-unofficial
 ==================
 
+[![Gem Version](https://badge.fury.io/rb/keybase-unofficial.svg)](https://badge.fury.io/rb/keybase-unofficial)
+
 An unofficial ruby library for Keybase and the Keybase API.
 
 Work in progress.

data/lib/keybase.rb

@@ -4,8 +4,10 @@ require_relative "keybase/user"
 require_relative "keybase/kbfs"
 require_relative "keybase/api"
 
+# The primary namespace for keybase-unofficial.
 module Keybase
-  VERSION = "0.0.2".freeze
+  # keybase-unofficial's current version
+  VERSION = "0.0.3".freeze
 
   extend Configuration
 end

data/lib/keybase/api.rb

@@ -4,10 +4,23 @@ require "ostruct"
 require "uri"
 
 module Keybase
+  # Represents (parts of) the Keybase REST API.
   class API
+    # The base URL for the majority of API calls.
     BASE_URL = "https://keybase.io/_/api/1.0"
 
     class << self
+      # Look up a user, users, or external identity.
+      # @param query [Hash] the request parameters
+      # @option query username [String] the username to look up
+      # @option query usernames [Array<String>] multiple usernames to look up
+      # @return [OpenStruct] a struct mapping of the JSON response
+      # @example
+      #  Keybase::API.lookup username: "yossarian"
+      #  Keybase::API.lookup github: "woodruffw"
+      # @note Any identity supported by keybase should work (e.g, `domain`,
+      #  `hackernews`, `reddit`, `github`, etc.)
+      # @see https://keybase.io/docs/api/1.0/call/user/lookup
       def lookup(**query)
         if query[:usernames]
           query[:usernames] = query[:usernames].join(",")
@@ -17,21 +30,50 @@ module Keybase
         JSON.parse(response.body, object_class: OpenStruct)
       end
 
+      # Search Keybase for identity components.
+      # @param query [String] the string to search for
+      # @return [OpenStruct] a struct mapping of the JSON response
+      # @example
+      #  Keybase::API.autocomplete "William Woodruff"
+      # @see https://keybase.io/docs/api/1.0/call/user/autocomplete
       def autocomplete(query)
         response = Faraday.get "#{BASE_URL}/user/autocomplete.json", q: query
         JSON.parse(response.body, object_class: OpenStruct)
       end
 
+      # Discover Keybase users from external identities.
+      # @param query [Hash] the request parameters
+      # @option query flatten [Boolean] whether or not to remove duplicates
+      # @option query usernames_only [Boolean] whether or not to reply with
+      #  only names
+      # @return [OpenStruct] a struct mapping of the JSON response
+      # @example
+      #  Keybase::API.discover github: "woodruffw", flatten: true
+      # @note Any identity supported by keybase should work (e.g, `domain`,
+      #  `hackernews`, `reddit`, `github`, etc.)
+      # @see https://keybase.io/docs/api/1.0/call/user/discover
       def discover(**query)
         response = Faraday.get "#{BASE_URL}/user/discover.json", query
         JSON.parse(response.body, object_class: OpenStruct)
       end
 
+      # Retrieve the current site-wide Merkle root hash.
+      # @param query [Hash] the request parameters
+      # @option query seqno [Integer] a specific Merkle root to return, if found
+      # @option query ctime [Integer] return the first root on or after the
+      #  given time (UTC)
+      # @return [OpenStruct] a struct mapping of the JSON response
+      # @see https://keybase.io/docs/api/1.0/call/merkle/root
       def merkle_root(**query)
         response = Faraday.get "#{BASE_URL}/merkle/root.json", query
         JSON.parse(response.body, object_class: OpenStruct)
       end
 
+      # Retrieve a Merkle node corresponding to a given hash.
+      # @param query [Hash] the request parameters
+      # @option query hash [String] the hash of the block to look up
+      # @return [OpenStruct] a struct mapping of the JSON response
+      # @see https://keybase.io/docs/api/1.0/call/merkle/block
       def merkle_block(**query)
         response = Faraday.get "#{BASE_URL}/merkle/block.json", query
         JSON.parse(response.body, object_class: OpenStruct)

data/lib/keybase/configuration.rb

@@ -1,29 +1,38 @@
 require "json"
 
 module Keybase
+  # Methods and constants related to a local Keybase installation.
   module Configuration
+    # The Keybase configuration directory.
     CONFIG_DIR = File.expand_path("~/.config/keybase").freeze
 
+    # The Keybase configuration file.
     CONFIG_FILE = File.join(CONFIG_DIR, "config.json").freeze
 
+    # The hash from Keybase's configuration file.
     CONFIG_HASH = JSON.parse(File.read(CONFIG_FILE)).freeze
 
+    # @return [String] the currently logged-in user
     def current_user
       CONFIG_HASH["current_user"]
     end
 
+    # @return [Array<Keybase::User>] a list of all local users known to Keybase
     def users
       CONFIG_HASH["users"].map { |_, v| Keybase::User.new(v) }
     end
 
+    # @return [String] the user's private KBFS directory
     def private_dir
       "/keybase/private/#{current_user}"
     end
 
+    # @return [String] the user's public KBFS directory
     def public_dir
       "/keybase/public/#{current_user}"
     end
 
+    # @return [Boolean] whether or not Keybase is currently running
     def running?
       # is there a more efficient way to do this that doesn't involve an exec?
       Dir["/proc/[0-9]*/comm"].any? do |comm|
@@ -31,6 +40,8 @@ module Keybase
       end
     end
 
+    # @return [String] the running Keybase's version string
+    # @raise [KeybaseNotRunningError] if Keybase is not running
     def running_version
       raise KeybaseNotRunningError unless Keybase.running?
       `keybase --version`.split[2]

data/lib/keybase/exceptions.rb

@@ -1,13 +1,16 @@
 module Keybase
+  # A top-level exception for the library.
   class KeybaseError < RuntimeError
   end
 
+  # Raised whenever Keybase is not running locally.
   class KeybaseNotRunningError < KeybaseError
     def initialize
       super "keybase needs to be running"
     end
   end
 
+  # Raised whenever KBFS is not running locally.
   class KBFSNotRunningError < KeybaseError
     def initialize
       super "KBFS needs to be enabled and running"

data/lib/keybase/kbfs.rb

@@ -1,5 +1,9 @@
 module Keybase
+  # Represents the Keybase filesystem.
+  # @note This is just a stub for the time being.
   class KBFS
+    # @raise [KeybaseNotRunningError] unless Keybase is running
+    # @raise [KBFSNotRunningError] unless KBFS is running
     def initialize
       raise KeybaseNotRunningError unless Keybase.running?
       raise KBFSNotRunningError unless Dir.exist?("/keybase")

data/lib/keybase/user.rb

@@ -1,6 +1,19 @@
 module Keybase
+  # Represents a user known to the local Keybase process.
+  # These are (presumably) users that have been logged into locally.
   class User
-    attr_reader :device, :id, :name, :salt
+    # @return [String] the device's unique identifier
+    attr_reader :device
+
+    # @return [String] the user's unique identifier
+    attr_reader :id
+
+    # @return [String] the user's Keybase username
+    attr_reader :name
+
+    # @return [String] some kind of salt
+    # @note I have no idea what this field does.
+    attr_reader :salt
 
     def initialize(hsh)
       @device = hsh["device"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keybase-unofficial
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - William Woodruff
@@ -14,14 +14,14 @@ dependencies:
   name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '0'
 description: A unofficial library for Keybase