didkit 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7a4ebcd65dd0bb01a1dfd790dafaa6db2780e704558b8da171eae1db45053d5
-  data.tar.gz: 27bd5afc5f6bec8207f07b152092337c028abfee26cf0684f5c04d1352241b03
+  metadata.gz: 505c6714968219d931f33b5bf4eb42f90f12b6c4391227b4257a5b4063491128
+  data.tar.gz: 3e877922065e457bb1fe706db1259b8ddd741cacdc7faa7f17ea3adeb4b23faa
 SHA512:
-  metadata.gz: 5cfcbe474eb92088fef122b10df8776b99589a5aa8f1725c5303305cc5ece4696d291f82931e691c92d7b3eb16b0f874efc0fb8bfbfc01f4267defa4e3cc28e4
-  data.tar.gz: 984039e433ef24d7499c70c5bcd336c4f826195b59b3143a03ca131741146c18fdae3b9088a201b3556169871b8ddd93062e7dfcc7292db4294fb45e464b9e17
+  metadata.gz: 587c899080bdb947261b54b2bbe2b3263567cb9aecca682086149d3a0ca4692a443a217b42520caca3e24ec246a5e3a0ea058d86c903cadb13075c2ebbac0291
+  data.tar.gz: c76d96e9fda51a31d87a7e15f93549e9594d8651d7668d77a38b9fe0bff09631d78a2d3a34f0afbd6cd9506a0208e9ece7617ebf1128fca7d1ab7d27896a5ea3

data/CHANGELOG.md

@@ -1,6 +1,23 @@
+## [0.4.0] - 2026-07-02
+
+- added `#also_known_as` separate from `#handles` in `Document` and `PLCOperation`, which stores the original array of strings as listed in the JSON, not filtered and not stripped of the `at://` prefix
+- added `PLCOperation#nullified?`
+- added support for parsing `handle` and `service` fields from legacy (2022-23 era) `:create` PLC ops in `PLCOperation`
+- `PLCImporter` can be configured with a custom hostname of a PLC mirror to use instead of [plc.directory](https://plc.directory)
+- `PLCImporter` will no longer update cursor to local request time if an empty page is received, but will instead leave the cursor as is – local time might have some offset vs. server time if the clock isn't set right, and this could lead to skipped operations
+- in `DID#account_status` / `account_active?` / `account_exists?`, accept `getRepoStatus` endpoint returning responses with status 404 instead of 400 (since some PDS implementations do it this way)
+- tweaked parsing of services in `Document` and `PLCOperation`:
+  1. `Document` raises format errors if the fields are missing or not of expected type (since this shouldn't happen)
+  2. `Document` & `PLCOperation` silently ignore the service if its endpoint is not a valid URI (since this does happen)
+  3. Removed `ignore_errors` / `error_handler` from `PLCImporter`, since because of 2) no expected errors are emitted outside `PLCOperation`
+
+## [0.3.3] - 2026-02-22
+
+- fixed old `FormatError` classes mentioned in `PLCImporter`
+
 ## [0.3.2] - 2026-02-15
 
-- added YARD API documentation
+- added [YARD API documentation](https://rubydoc.info/gems/didkit/)
 - 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

data/README.md

@@ -1,5 +1,7 @@
 # DIDKit 🪪
 
+[![Gem Version](https://badge.fury.io/rb/didkit.svg?icon=si%3Arubygems&icon_color=%23ff6251)](https://rubygems.org/gems/didkit) [![YARD Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://rubydoc.info/gems/didkit)
+
 A small Ruby gem for handling Distributed Identifiers (DIDs) in Bluesky / AT Protocol.
 
 > [!NOTE]
@@ -86,9 +88,9 @@ You can customize some things about the DID/handle lookups by using the `DIDKit:
 
 Currently available options include:
 
-- `:nameserver` - override the nameserver used for DNS lookups, e.g. to use Google's or CloudFlare's DNS
-- `:timeout` - change the connection/response timeout for HTTP requests (default: 15 s)
-- `:max_redirects` - change allowed maximum number of redirects (default: 5)
+- `:nameserver` – override the nameserver used for DNS lookups, e.g. to use Google's or CloudFlare's DNS
+- `:timeout` – change the connection/response timeout for HTTP requests (default: 15 s)
+- `:max_redirects` – change allowed maximum number of redirects (default: 5)
 
 Example:
 
@@ -106,6 +108,13 @@ resolver.get_verified_handle(did)
   # => 'nytimes.com'
 ```
 
+## Other resources
+
+- [YARD API documentation](https://rubydoc.info/gems/didkit) at rubydoc.info
+- [ruby.sdk.blue](https://ruby.sdk.blue)
+- [Example scripts](https://ruby.sdk.blue/examples/)
+
+
 ## Credits
 
 Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).

data/lib/didkit/at_handles.rb

@@ -5,18 +5,39 @@ require_relative 'errors'
 module DIDKit
 
   #
-  # @private
+  # @api private
   #
 
   module AtHandles
 
+    # Returns a list of ATProto handles assigned to this DID in its DID document.
+    #
+    # Note: the handles aren't guaranteed to be verified (validated in the other direction).
+    # Use {DID#get_verified_handle} to find a handle that is correctly verified.
+    #
+    # @api public
+    # @return [Array<String>]
+
+    attr_reader :handles
+
+    # Returns a list of all identifiers assigned to this DID in its DID document through the
+    # `alsoKnownAs` field. This includes ATProto handles (in the format `at://example.com`) and
+    # potentially other URIs like `http` URLs (e.g. for Bridgy accounts), and even (technically
+    # invalid) non-URI strings. Use {#handles} to get just the ATProto handles.
+    #
+    # @api public
+    # @return [Array<String>]
+
+    attr_reader :also_known_as
+
     private
 
     def parse_also_known_as(aka)
       raise FormatError, "Invalid alsoKnownAs: #{aka.inspect}" unless aka.is_a?(Array)
       raise FormatError, "Invalid alsoKnownAs: #{aka.inspect}" unless aka.all? { |x| x.is_a?(String) }
 
-      aka.select { |x| x =~ %r(\Aat://[^/]+\z) }.map { |x| x.gsub('at://', '') }
+      @also_known_as = aka
+      @handles = aka.select { |x| x =~ %r(\Aat://[^/]+\z) }.map { |x| x.gsub('at://', '') }
     end
   end
 end

data/lib/didkit/did.rb

@@ -148,17 +148,19 @@ module DIDKit
         json = JSON.parse(response.body)
 
         if json['active'] == true
-          :active
+          return :active
         elsif json['active'] == false && json['status'].is_a?(String) && json['status'].length <= 100
-          json['status'].to_sym
-        else
-          raise APIError.new(response)
+          return json['status'].to_sym
+        end
+      elsif (status == 400 || status == 404) && is_json
+        json = JSON.parse(response.body)
+
+        if json['error'] == 'RepoNotFound'
+          return nil
         end
-      elsif status == 400 && is_json && JSON.parse(response.body)['error'] == 'RepoNotFound'
-        nil
-      else
-        raise APIError.new(response)
       end
+
+      raise APIError.new(response)
     end
 
     # Checks if the account is seen as active on its own PDS, using the `getRepoStatus` endpoint.

data/lib/didkit/document.rb

@@ -24,14 +24,6 @@ module DIDKit
     # @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
 
@@ -49,8 +41,8 @@ module DIDKit
       @did = did
       @json = json
 
-      @services = parse_services(json['service'] || [])
-      @handles = parse_also_known_as(json['alsoKnownAs'] || [])
+      parse_services(json['service'] || [])
+      parse_also_known_as(json['alsoKnownAs'] || [])
     end
 
     # Returns the first verified handle assigned to the DID.
@@ -71,17 +63,27 @@ module DIDKit
     def parse_services(service_data)
       raise FormatError, "Invalid service data" unless service_data.is_a?(Array) && service_data.all? { |x| x.is_a?(Hash) }
 
-      services = []
+      @services = []
 
       service_data.each do |x|
         id, type, endpoint = x.values_at('id', 'type', 'serviceEndpoint')
 
-        if id.is_a?(String) && id.start_with?('#') && type.is_a?(String) && endpoint.is_a?(String)
-          services << ServiceRecord.new(id.gsub(/^#/, ''), type, endpoint)
+        raise FormatError, "Missing service id" unless id
+        raise FormatError, "Invalid service id: #{id.inspect}" unless id.is_a?(String)
+        next if !id.start_with?('#')
+
+        raise FormatError, "Missing service type" unless type
+        raise FormatError, "Invalid service type: #{type.inspect}" unless type.is_a?(String)
+
+        raise FormatError, "Missing service endpoint" unless endpoint
+        raise FormatError, "Invalid service endpoint: #{endpoint.inspect}" unless endpoint.is_a?(String)
+
+        begin
+          @services << ServiceRecord.new(id.gsub(/^#/, ''), type, endpoint)
+        rescue FormatError => e
+          # ignore services with invalid URIs
         end
       end
-
-      services
     end
   end
 end

data/lib/didkit/plc_importer.rb

@@ -4,12 +4,13 @@ require 'json'
 require 'time'
 require 'uri'
 
+require_relative 'errors'
 require_relative 'plc_operation'
 require_relative 'requests'
 
 #
 # NOTE: this class is pending a rewrite once new APIs are deployed to plc.directory.
-# Things will change here in v. 0.4.
+# Things will change here in v. 0.5.
 #
 
 module DIDKit
@@ -19,9 +20,9 @@ module DIDKit
 
     include Requests
 
-    attr_accessor :ignore_errors, :last_date, :error_handler
+    attr_accessor :last_date
 
-    def initialize(since: nil)
+    def initialize(since: nil, service: nil)
       if since.to_s == 'beginning'
         @last_date = nil
       elsif since.is_a?(String)
@@ -34,24 +35,11 @@ module DIDKit
       end
 
       @last_page_cids = []
-    end
-
-    def plc_service
-      PLC_SERVICE
-    end
-
-    def ignore_errors=(val)
-      @ignore_errors = val
-
-      if val
-        @error_handler = proc { |e, j| "(ignore error)" }
-      else
-        @error_handler = nil
-      end
+      @plc_service = service || PLC_SERVICE
     end
 
     def get_export(args = {})
-      url = URI("https://#{plc_service}/export")
+      url = URI("https://#{@plc_service}/export")
       url.query = URI.encode_www_form(args)
 
       data = get_data(url, content_type: 'application/jsonlines')
@@ -59,23 +47,16 @@ module DIDKit
     end
 
     def fetch_audit_log(did)
-      json = get_json("https://#{plc_service}/#{did}/log/audit", :content_type => :json)
+      json = get_json("https://#{@plc_service}/#{did}/log/audit", :content_type => :json)
       json.map { |j| PLCOperation.new(j) }
-    end      
+    end
 
     def fetch_page
-      request_time = Time.now
-
       query = @last_date ? { :after => @last_date.utc.iso8601(6) } : {}
       rows = get_export(query)
 
-      operations = rows.filter_map { |json|
-        begin
-          PLCOperation.new(json)
-        rescue PLCOperation::FormatError, AtHandles::FormatError, ServiceRecord::FormatError => e
-          @error_handler ? @error_handler.call(e, json) : raise
-          nil
-        end
+      operations = rows.map { |json|
+        PLCOperation.new(json)
       }.reject { |op|
         # when you pass the most recent op's timestamp to ?after, it will be returned as the first op again,
         # so we need to use this CID list to filter it out (so pages will usually be 999 items long)
@@ -83,8 +64,11 @@ module DIDKit
         @last_page_cids.include?(op.cid)
       }
 
-      @last_date = operations.last&.created_at || request_time
-      @last_page_cids = Set.new(operations.map(&:cid))
+      unless operations.empty?
+        @last_date = operations.last.created_at
+        @last_page_cids = Set.new(operations.map(&:cid))
+      end
+
       @eof = (rows.length < MAX_PAGE)
 
       operations

data/lib/didkit/plc_operation.rb

@@ -38,15 +38,6 @@ module DIDKit
     # @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
 
@@ -81,26 +72,69 @@ module DIDKit
 
       type = operation['type']
       raise FormatError, "Missing operation type: #{json}" if type.nil?
+      raise FormatError, "Invalid operation type: #{type.inspect}" unless type.is_a?(String)
 
       @type = type.to_sym
-      return unless @type == :plc_operation
 
-      services = operation['services']
-      raise FormatError, "Missing services key: #{json}" if services.nil?
-      raise FormatError, "Invalid services data: #{services}" unless services.is_a?(Hash)
+      case @type
+      when :plc_operation
+        raise FormatError, "Missing services key: #{json}" if operation['services'].nil?
+
+        parse_services(operation['services'])
+        parse_also_known_as(operation['alsoKnownAs'])
+      when :create
+        parse_legacy_ops(operation)
+      end
+    end
+
+    # @return [Boolean] if the operation has been nullified through a rotation operation
+    def nullified?
+      @json['nullified'] == true
+    end
+
 
-      @services = services.map { |k, x|
-        type, endpoint = x.values_at('type', 'endpoint')
+    private
+
+    def parse_services(service_data)
+      raise FormatError, "Invalid services data: #{service_data.inspect}" unless service_data.is_a?(Hash)
+
+      @services = []
+
+      service_data.each do |key, data|
+        type, endpoint = data.values_at('type', 'endpoint')
 
         raise FormatError, "Missing service type" unless type
         raise FormatError, "Invalid service type: #{type.inspect}" unless type.is_a?(String)
+
         raise FormatError, "Missing service endpoint" unless endpoint
         raise FormatError, "Invalid service endpoint: #{endpoint.inspect}" unless endpoint.is_a?(String)
 
-        ServiceRecord.new(k, type, endpoint)
-      }
+        begin
+          @services << ServiceRecord.new(key, type, endpoint)
+        rescue FormatError => e
+          # ignore services with invalid URIs
+        end
+      end
+    end
+
+    def parse_legacy_ops(operation)
+      @handles = []
+      @services = []
+
+      if handle = operation['handle']
+        raise FormatError, "Handle should be a string" unless handle.is_a?(String)
+        @handles << handle
+      end
+
+      if service = operation['service']
+        raise FormatError, "Service should be a string" unless service.is_a?(String)
 
-      @handles = parse_also_known_as(operation['alsoKnownAs'])
+        begin
+          @services << ServiceRecord.new('atproto_pds', 'AtprotoPersonalDataServer', service)
+        rescue FormatError
+          # ignore services with invalid URIs
+        end
+      end
     end
   end
 end

data/lib/didkit/services.rb

@@ -48,6 +48,8 @@ module DIDKit
 
     # Returns the hostname of the PDS service, if present.
     #
+    # If the endpoint URL includes a port number, it is excluded.
+    #
     # @api public
     # @return [String, nil] hostname of the PDS endpoint URL
 
@@ -57,6 +59,8 @@ module DIDKit
 
     # Returns the hostname of the labeler service, if present.
     #
+    # If the endpoint URL includes a port number, it is excluded.
+    #
     # @api public
     # @return [String, nil] hostname of the labeler endpoint URL
 

data/lib/didkit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: didkit
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 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.3
+rubygems_version: 4.0.15
 specification_version: 4
 summary: A library for handling Distributed ID (DID) identifiers used in Bluesky AT
   Protocol