didkit 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b81757b37a0aa45a3ccefe6e8ebac777a283a6f8d3b827308f1f029b30abe0c8
-  data.tar.gz: beef9f4a9cc71c9edc46fce5e95df2b1c6a442c223826054eafed721d744b8ad
+  metadata.gz: d7a4ebcd65dd0bb01a1dfd790dafaa6db2780e704558b8da171eae1db45053d5
+  data.tar.gz: 27bd5afc5f6bec8207f07b152092337c028abfee26cf0684f5c04d1352241b03
 SHA512:
-  metadata.gz: 24c046d3566c3816c700e60936f9313b837df8403dc0435e67c317eabaf4e554c29357573a825d72a4795185d942c67c0fc408457a2f3c72e8569c1fc9c718ab
-  data.tar.gz: d0e4bb8224a6a0c5b6d62edfee27869fc7227229d3d95f482beb2c917ac0ea99c45fed7e8993299c8a2b69ef0a9d5f58e1d610e108f0f15aac50ffebb7599dfe
+  metadata.gz: 5cfcbe474eb92088fef122b10df8776b99589a5aa8f1725c5303305cc5ece4696d291f82931e691c92d7b3eb16b0f874efc0fb8bfbfc01f4267defa4e3cc28e4
+  data.tar.gz: 984039e433ef24d7499c70c5bcd336c4f826195b59b3143a03ca131741146c18fdae3b9088a201b3556169871b8ddd93062e7dfcc7292db4294fb45e464b9e17

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.3.2] - 2026-02-15
+
+- added YARD API documentation
+- marked some helper methods in `requests.rb`, `at_handles.rb` and `DIDKit::Resolver` as private
+- merged all "FormatErrors" into one `DIDKit::FormatError`
+- added `frozen_string_literal` directive everywhere to minimize garbage collection
+
 ## [0.3.1] - 2025-12-19
 
 - allow passing a DID string or object to `#resolve_handle` and just return that DID – so you can have a script that accepts either a handle or a DID, and passes the input to `DID.resolve_handle` without checking which one it is

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The zlib License
 
-Copyright (c) 2025 Jakub Suder
+Copyright (c) 2026 Jakub Suder
 
 This software is provided 'as-is', without any express or implied
 warranty.  In no event will the authors be held liable for any damages

data/README.md

@@ -13,11 +13,13 @@ Accounts on Bluesky use identifiers like [did:plc:oio4hkxaop4ao4wz2pp3f4cr](http
 
 ## Installation
 
-From the command line:
+To use DIDKit, you need a reasonably new version of Ruby – it should run on Ruby 2.6 and above, although it's recommended to use a version that's still getting maintainance updates, i.e. currently 3.2+. A compatible version should be preinstalled on macOS Big Sur and above and on many Linux systems. Otherwise, you can install one using tools such as [RVM](https://rvm.io), [asdf](https://asdf-vm.com), [ruby-install](https://github.com/postmodern/ruby-install) or [ruby-build](https://github.com/rbenv/ruby-build), or `rpm` or `apt-get` on Linux (see more installation options on [ruby-lang.org](https://www.ruby-lang.org/en/downloads/)).
 
-    gem install didkit
+To install the gem, run in the command line:
 
-Or, add this to your `Gemfile`:
+    [sudo] gem install didkit
+
+Or add this to your app's `Gemfile`:
 
     gem 'didkit', '~> 0.3'
 
@@ -106,6 +108,8 @@ resolver.get_verified_handle(did)
 
 ## Credits
 
-Copyright © 2025 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
+Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
 
 The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).
+
+Bug reports and pull requests are welcome 😎

data/lib/didkit/at_handles.rb

@@ -1,7 +1,16 @@
+# frozen_string_literal: true
+
+require_relative 'errors'
+
 module DIDKit
+
+  #
+  # @private
+  #
+
   module AtHandles
-    class FormatError < StandardError
-    end
+
+    private
 
     def parse_also_known_as(aka)
       raise FormatError, "Invalid alsoKnownAs: #{aka.inspect}" unless aka.is_a?(Array)

data/lib/didkit/did.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'uri'
 
@@ -6,16 +8,52 @@ require_relative 'requests'
 require_relative 'resolver'
 
 module DIDKit
+
+  #
+  # Represents a DID identifier (account on the ATProto network). This class serves as an entry
+  # point to various lookup helpers. For convenience it can also be accessed as just `DID` without
+  # the `DIDKit::` prefix.
+  #
+  # @example Resolving a handle
+  #   did = DID.resolve_handle('bsky.app')
+  #
+
   class DID
     GENERIC_REGEXP = /\Adid\:\w+\:.+\z/
 
     include Requests
 
+    # Resolve a handle into a DID. Looks up the given ATProto domain handle using the DNS TXT method
+    # and the HTTP .well-known method and returns a DID if one is assigned using either of the methods.
+    #
+    # If a DID string or a {DID} object is passed, it simply returns that DID, so you can use this
+    # method to pass it an input string from the user which can be a DID or handle, without having to
+    # check which one it is.
+    #
+    # @param handle [String, DID] a domain handle (may start with an `@`) or a DID string
+    # @return [DID, nil] resolved DID if found, nil otherwise
+
     def self.resolve_handle(handle)
       Resolver.new.resolve_handle(handle)
     end
 
-    attr_reader :type, :did, :resolved_by
+    # @return [Symbol] DID type (`:plc` or `:web`)
+    attr_reader :type
+
+    # @return [String] DID identifier string
+    attr_reader :did
+
+    # @return [Symbol, nil] `:dns` or `:http` if the DID was looked up using one of those methods
+    attr_reader :resolved_by
+
+    alias to_s did
+
+
+    # Create a DID object from a DID string.
+    #
+    # @param did [String, DID] DID string or another DID object
+    # @param resolved_by [Symbol, nil] optionally, how the DID was looked up (`:dns` or `:http`)
+    # @raise [DIDError] when the DID format or type is invalid
 
     def initialize(did, resolved_by = nil)
       if did.is_a?(DID)
@@ -36,20 +74,39 @@ module DIDKit
       @resolved_by = resolved_by
     end
 
-    alias to_s did
+    # Returns or looks up the DID document with the DID's identity details from an appropriate source.
+    # This method caches the document in a local variable if it's called again.
+    #
+    # @return [Document] resolved DID document
 
     def document
       @document ||= get_document
     end
 
+    # Looks up the DID document with the DID's identity details from an appropriate source.
+    # @return [Document] resolved DID document
+
     def get_document
       Resolver.new.resolve_did(self)
     end
 
+    # Returns the first verified handle assigned to this DID.
+    #
+    # Looks up the domain handles assigned to this DID in its DID document, checks if they are
+    # verified (i.e. assigned correctly to this DID using DNS TXT or .well-known) and returns
+    # the first handle that validates correctly, or nil if none matches.
+    #
+    # @return [String, nil] verified handle domain, if found
+
     def get_verified_handle
       Resolver.new.get_verified_handle(document)
     end
 
+    # Fetches the PLC audit log (list of all previous operations) for a did:plc DID.
+    #
+    # @return [Array<PLCOperation>] list of PLC operations in the audit log
+    # @raise [DIDError] when the DID is not a did:plc
+
     def get_audit_log
       if @type == :plc
         PLCImporter.new.fetch_audit_log(self)
@@ -58,10 +115,23 @@ module DIDKit
       end
     end
 
+    # Returns the domain portion of a did:web identifier.
+    #
+    # @return [String, nil] DID domain if the DID is a did:web, nil for did:plc
+
     def web_domain
       did.gsub(/^did\:web\:/, '') if type == :web
     end
 
+    # Checks the status of the account/repo on its own PDS using the `getRepoStatus` endpoint.
+    #
+    # @param request_options [Hash] request options to override
+    # @option request_options [Integer] :timeout request timeout (default: 15)
+    # @option request_options [Integer] :max_redirects maximum number of redirects to follow (default: 5)
+    #
+    # @return [Symbol, nil] `:active`, or returned inactive status, or `nil` if account is not found
+    # @raise [APIError] when the response is invalid
+
     def account_status(request_options = {})
       doc = self.document
       return nil if doc.pds_endpoint.nil?
@@ -91,14 +161,31 @@ module DIDKit
       end
     end
 
+    # Checks if the account is seen as active on its own PDS, using the `getRepoStatus` endpoint.
+    # This is a helper which calls the {#account_status} method and checks if the status is `:active`.
+    #
+    # @return [Boolean] true if the returned status is active
+    # @raise [APIError] when the response is invalid
+
     def account_active?
       account_status == :active
     end
 
+    # Checks if the account exists its own PDS, using the `getRepoStatus` endpoint.
+    # This is a helper which calls the {#account_status} method and checks if the repo is found at all.
+    #
+    # @return [Boolean] true if the returned status is valid, false if repo is not found
+    # @raise [APIError] when the response is invalid
+
     def account_exists?
       account_status != nil
     end
 
+    # Compares the DID to another DID object or string.
+    #
+    # @param other [DID, String] other DID to compare with
+    # @return [Boolean] true if it's the same DID
+
     def ==(other)
       if other.is_a?(String)
         self.did == other

data/lib/didkit/document.rb

@@ -1,17 +1,45 @@
+# frozen_string_literal: true
+
 require_relative 'at_handles'
+require_relative 'errors'
 require_relative 'resolver'
 require_relative 'service_record'
 require_relative 'services'
 
 module DIDKit
-  class Document
-    class FormatError < StandardError
-    end
 
+  #
+  # Parsed DID document from a JSON file loaded from [plc.directory](https://plc.directory) or a did:web domain.
+  #
+  # Use {DID#document} or {Resolver#resolve_did} to fetch a DID document and return this object.
+  #
+
+  class Document
     include AtHandles
     include Services
 
-    attr_reader :json, :did, :handles, :services
+    # @return [Hash] the complete JSON data of the DID document
+    attr_reader :json
+
+    # @return [DID] the DID that this document describes
+    attr_reader :did
+
+    # Returns a list of handles assigned to this DID in its DID document.
+    #
+    # Note: the handles aren't guaranteed to be verified (validated in the other direction).
+    # Use {#get_verified_handle} to find a handle that is correctly verified.
+    #
+    # @return [Array<String>]
+    attr_reader :handles
+
+    # @return [Array<ServiceRecords>] service records like PDS details assigned to the DID
+    attr_reader :services
+
+    # Creates a DID document object.
+    #
+    # @param did [DID] DID object
+    # @param json [Hash] DID document JSON
+    # @raise [FormatError] when required fields are missing or invalid.
 
     def initialize(did, json)
       raise FormatError, "Missing id field" if json['id'].nil?
@@ -25,10 +53,19 @@ module DIDKit
       @handles = parse_also_known_as(json['alsoKnownAs'] || [])
     end
 
+    # Returns the first verified handle assigned to the DID.
+    #
+    # Looks up the domain handles assigned to this DID in the DID document, checks if they are
+    # verified (i.e. assigned correctly to this DID using DNS TXT or .well-known) and returns
+    # the first handle that validates correctly, or nil if none matches.
+    #
+    # @return [String, nil] verified handle domain, if found
+
     def get_verified_handle
       Resolver.new.get_verified_handle(self)
     end
 
+
     private
 
     def parse_services(service_data)

data/lib/didkit/errors.rb

@@ -1,21 +1,41 @@
+# frozen_string_literal: true
+
 module DIDKit
-  class DIDError < StandardError
-  end
 
+  #
+  # Raised when an HTTP request returns a response with an error status.
+  #
   class APIError < StandardError
+
+    # @return [Net::HTTPResponse] the returned HTTP response
     attr_reader :response
 
+    # @param response [Net::HTTPResponse] the returned HTTP response
     def initialize(response)
       @response = response
       super("APIError: #{response}")
     end
 
+    # @return [Integer] HTTP status code
     def status
       response.code.to_i
     end
 
+    # @return [String] HTTP response body
     def body
       response.body
     end
   end
+
+  #
+  # Raised when a string is not a valid DID or not of the right type.
+  #
+  class DIDError < StandardError
+  end
+
+  #
+  # Raised when the loaded data has some missing or invalid fields.
+  #
+  class FormatError < StandardError
+  end
 end

data/lib/didkit/plc_importer.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'time'
 require 'uri'

data/lib/didkit/plc_operation.rb

@@ -1,18 +1,60 @@
+# frozen_string_literal: true
+
 require 'time'
 
 require_relative 'at_handles'
+require_relative 'errors'
 require_relative 'service_record'
 require_relative 'services'
 
 module DIDKit
-  class PLCOperation
-    class FormatError < StandardError
-    end
 
+  #
+  # Represents a single operation of changing a specific DID's data in the [plc.directory](https://plc.directory)
+  # (e.g. changing assigned handles or migrating to a different PDS).
+  #
+
+  class PLCOperation
     include AtHandles
     include Services
 
-    attr_reader :json, :did, :cid, :seq, :created_at, :type, :handles, :services
+    # @return [Hash] the JSON from which the operation is parsed
+    attr_reader :json
+
+    # @return [String] the DID which the operation concerns
+    attr_reader :did
+
+    # @return [String] CID (Content Identifier) of the operation
+    attr_reader :cid
+
+    # Returns a sequential number of the operation (only used in the new export API).
+    # @return [Integer, nil] sequential number of the operation
+    attr_reader :seq
+
+    # @return [Time] time when the operation was created
+    attr_reader :created_at
+
+    # Returns the `type` field of the operation (usually `"plc_operation"`).
+    # @return [String] the operation type
+    attr_reader :type
+
+    # Returns a list of handles assigned to the DID in this operation.
+    #
+    # Note: the handles aren't guaranteed to be verified (validated in the other direction).
+    # Use {DID#get_verified_handle} or {Document#get_verified_handle} to find a handle that is
+    # correctly verified.
+    #
+    # @return [Array<String>]
+    attr_reader :handles
+
+    # @return [Array<ServiceRecords>] service records like PDS details assigned to the DID
+    attr_reader :services
+
+
+    # Creates a PLCOperation object.
+    #
+    # @param json [Hash] operation JSON
+    # @raise [FormatError] when required fields are missing or invalid
 
     def initialize(json)
       @json = json

data/lib/didkit/requests.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'net/http'
 require 'uri'
@@ -5,7 +7,15 @@ require 'uri'
 require_relative 'errors'
 
 module DIDKit
+
+  #
+  # @private
+  #
+
   module Requests
+
+    private
+
     def get_response(url, options = {})
       url = URI(url) unless url.is_a?(URI)
 

data/lib/didkit/resolver.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'net/http'
 require 'resolv'
 
@@ -6,18 +8,41 @@ require_relative 'document'
 require_relative 'requests'
 
 module DIDKit
+
+  #
+  # A class which manages resolving of handles to DIDs and DIDs to DID documents.
+  #
+
   class Resolver
+    # These TLDs are not allowed in ATProto handles, so the resolver returns nil for them
+    # without trying to look them up.
     RESERVED_DOMAINS = %w(alt arpa example internal invalid local localhost onion test)
 
     include Requests
 
+    # @return [String, Array<String>] custom DNS nameserver(s) to use for DNS TXT lookups
     attr_accessor :nameserver
 
+    # @param options [Hash] resolver options
+    # @option options [String, Array<String>] :nameserver custom DNS nameserver(s) to use (IP or an array of IPs)
+    # @option options [Integer] :timeout request timeout in seconds (default: 15)
+    # @option options [Integer] :max_redirects maximum number of redirects to follow (default: 5)
+
     def initialize(options = {})
       @nameserver = options[:nameserver]
       @request_options = options.slice(:timeout, :max_redirects)
     end
 
+    # Resolve a handle into a DID. Looks up the given ATProto domain handle using the DNS TXT method
+    # and the HTTP .well-known method and returns a DID if one is assigned using either of the methods.
+    #
+    # If a DID string or a {DID} object is passed, it simply returns that DID, so you can use this
+    # method to pass it an input string from the user which can be a DID or handle, without having to
+    # check which one it is.
+    #
+    # @param handle [String, DID] a domain handle (may start with an `@`) or a DID string
+    # @return [DID, nil] resolved DID if found, nil otherwise
+
     def resolve_handle(handle)
       if handle.is_a?(DID) || handle =~ DID::GENERIC_REGEXP
         return DID.new(handle)
@@ -36,6 +61,14 @@ module DIDKit
       end
     end
 
+    # Tries to resolve a handle into DID using the DNS TXT method.
+    #
+    # Checks the DNS records for a given domain for an entry `_atproto.#{domain}` whose value is
+    # a correct DID string.
+    #
+    # @param domain [String] a domain handle to look up
+    # @return [String, nil] resolved DID if found, nil otherwise
+
     def resolve_handle_by_dns(domain)
       dns_records = Resolv::DNS.open(resolv_options) do |d|
         d.getresources("_atproto.#{domain}", Resolv::DNS::Resource::IN::TXT)
@@ -50,6 +83,14 @@ module DIDKit
       nil
     end
 
+    # Tries to resolve a handle into DID using the HTTP .well-known method.
+    #
+    # Checks the `/.well-known/atproto-did` endpoint on the given domain to see if it returns
+    # a text file that contains a correct DID string.
+    #
+    # @param domain [String] a domain handle to look up
+    # @return [String, nil] resolved DID if found, nil otherwise
+
     def resolve_handle_by_well_known(domain)
       url = "https://#{domain}/.well-known/atproto-did"
       response = get_response(url, @request_options)
@@ -63,6 +104,49 @@ module DIDKit
       nil
     end
 
+    # Resolve a DID to a DID document.
+    #
+    # Looks up the DID document with the DID's identity details from an appropriate source, i.e. either
+    # [plc.directory](https://plc.directory) for did:plc DIDs, or the did:web's domain for did:web DIDs.
+    #
+    # @param did [String, DID] DID string or object
+    # @return [Document] resolved DID document
+    # @raise [APIError] if an incorrect response is returned
+
+    def resolve_did(did)
+      did = DID.new(did) if did.is_a?(String)
+
+      did.type == :plc ? resolve_did_plc(did) : resolve_did_web(did)
+    end
+
+    # Returns the first verified handle assigned to the given DID.
+    #
+    # Looks up the domain handles assigned to the DID in the DID document, checks if they are
+    # verified (i.e. assigned correctly to this DID using DNS TXT or .well-known) and returns
+    # the first handle that validates correctly, or nil if none matches.
+    #
+    # @param subject [String, DID, Document] a DID or its DID document
+    # @return [String, nil] verified handle domain, if found
+
+    def get_verified_handle(subject)
+      document = subject.is_a?(Document) ? subject : resolve_did(subject)
+
+      first_verified_handle(document.did, document.handles)
+    end
+
+    # Returns the first handle from the list that resolves back to the given DID.
+    #
+    # @param did [DID, String] DID to verify the handles against
+    # @param handles [Array<String>] handles to check
+    # @return [String, nil] a verified handle, if found
+
+    def first_verified_handle(did, handles)
+      handles.detect { |h| resolve_handle(h) == did.to_s }
+    end
+
+
+    private
+
     def resolv_options
       options = Resolv::DNS::Config.default_config_hash.dup
       options[:nameserver] = nameserver if nameserver
@@ -78,12 +162,6 @@ module DIDKit
       text.lines.length == 1 && text =~ DID::GENERIC_REGEXP ? text : nil
     end
 
-    def resolve_did(did)
-      did = DID.new(did) if did.is_a?(String)
-
-      did.type == :plc ? resolve_did_plc(did) : resolve_did_web(did)
-    end
-
     def resolve_did_plc(did)
       json = get_json("https://plc.directory/#{did}", content_type: /^application\/did\+ld\+json(;.+)?$/)
       Document.new(did, json)
@@ -93,15 +171,5 @@ module DIDKit
       json = get_json("https://#{did.web_domain}/.well-known/did.json")
       Document.new(did, json)
     end
-
-    def get_verified_handle(subject)
-      document = subject.is_a?(Document) ? subject : resolve_did(subject)
-
-      first_verified_handle(document.did, document.handles)
-    end
-
-    def first_verified_handle(did, handles)
-      handles.detect { |h| resolve_handle(h) == did.to_s }
-    end
   end
 end

data/lib/didkit/service_record.rb

@@ -1,12 +1,32 @@
+# frozen_string_literal: true
+
 require 'uri'
 require_relative 'errors'
 
 module DIDKit
+
+  # A parsed service record from either a DID document's `service` field or a PLC directory
+  # operation's `services` field.
+
   class ServiceRecord
-    class FormatError < StandardError
-    end
 
-    attr_reader :key, :type, :endpoint
+    # Returns the service's identifier (without `#`), like "atproto_pds".
+    # @return [String] service's identifier
+    attr_reader :key
+
+    # Returns the service's type field, like "AtprotoPersonalDataServer".
+    # @return [String] service's type
+    attr_reader :type
+
+    # @return [String] service's endpoint URL
+    attr_reader :endpoint
+
+    # Create a service record from DID document fields.
+    #
+    # @param key [String] service identifier (without `#`)
+    # @param type [String] service type
+    # @param endpoint [String] service endpoint URL
+    # @raise [FormatError] when the endpoint is not a valid URI
 
     def initialize(key, type, endpoint)
       begin

data/lib/didkit/services.rb

@@ -1,23 +1,65 @@
+# frozen_string_literal: true
+
 require 'uri'
 
 module DIDKit
+
+  #
+  # @api private
+  #
+
   module Services
+
+    # Finds a service entry matching the given key and type.
+    #
+    # @api public
+    # @param key [String] service key in the DID document
+    # @param type [String] service type identifier
+    # @return [ServiceRecord, nil] matching service record, if found
+
     def get_service(key, type)
       @services&.detect { |s| s.key == key && s.type == type }
     end
 
+    # Returns the PDS service endpoint, if present.
+    #
+    # If the DID has an `#atproto_pds` service declared in its `service` section,
+    # returns the URL in its `serviceEndpoint` field. In other words, this is the URL
+    # of the PDS assigned to a given user, which stores the user's account and repo.
+    #
+    # @api public
+    # @return [String, nil] PDS service endpoint URL
+
     def pds_endpoint
       @pds_endpoint ||= get_service('atproto_pds', 'AtprotoPersonalDataServer')&.endpoint
     end
 
+    # Returns the labeler service endpoint, if present.
+    #
+    # If the DID has an `#atproto_labeler` service declared in its `service` section,
+    # returns the URL in its `serviceEndpoint` field.
+    #
+    # @api public
+    # @return [String, nil] labeler service endpoint URL
+
     def labeler_endpoint
       @labeler_endpoint ||= get_service('atproto_labeler', 'AtprotoLabeler')&.endpoint
     end
 
+    # Returns the hostname of the PDS service, if present.
+    #
+    # @api public
+    # @return [String, nil] hostname of the PDS endpoint URL
+
     def pds_host
       pds_endpoint&.then { |x| URI(x).host }
     end
 
+    # Returns the hostname of the labeler service, if present.
+    #
+    # @api public
+    # @return [String, nil] hostname of the labeler endpoint URL
+
     def labeler_host
       labeler_endpoint&.then { |x| URI(x).host }
     end

data/lib/didkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DIDKit
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: didkit
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Kuba Suder
@@ -52,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.1
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A library for handling Distributed ID (DID) identifiers used in Bluesky AT
   Protocol