minisky 0.5.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4ed55493afc5d821a8e67ea83bcdc8aa29a7d2c9c3afe40e178441a499516a2d
-  data.tar.gz: 351119843f56206f7205872a26cbf66758273dfd35fe54b064a346ebb31d8bcb
+  metadata.gz: 11cd25820ca8ab1f4cd6f9c94604a8229fd2f824695341ccd052aae62bc085c6
+  data.tar.gz: ecca2bbad124246a93e7090a3be0ace4675208ad1750d36adfdfa523cf9fd420
 SHA512:
-  metadata.gz: bc684d8ffe0105e8c8d198acf35c6e9ca4a4856e7a74961adaab548d6471e140bb3d4e42c23ef710caab5449c12136f72c08522ddc68b244b99ca9019a8be832
-  data.tar.gz: 196a97d055b3cb6714df1379cbe5b64c8798e5e09e432bdf8ec652374f500cc8e6a34d39d60c976f2fc373c547d90f367fe54fe791e8d9d3eea98d618c96651a
+  metadata.gz: 2169712a4d8596840ae0aa9ab891cfccee951f73a7fce146105503a69d647545b3ee0ed8f475bf65096d88226cf66c07a8637048a076c65e9363023877b8b55d
+  data.tar.gz: 2283843f151c6f03ce5a275195e21ff85e33085c06a6db56bc9301c205d97ef7ea86ff245b0f609e406c2d54ddaa732b2e72930aba5ad75e27dab2ef7c1bac1c

data/CHANGELOG.md

@@ -1,8 +1,25 @@
+## Unreleased
+
+The "really niche bugfix" edition:
+
+* don't stop fetching in `fetch_all` if an empty page is returned but the cursor is not nil; it's technically allowed for the server to return an empty page but still have more data to send, e.g. if the service does some filtering at the last step and all records happen to be filtered out
+  - unfortunately, this on the other hand causes problems with some specific endpoints which incorrectly return a cursor when reaching the end of data, so you can also restore the previous behavior if needed, by setting the `stop_fetch_on_empty_page` option
+* in `post_request`, don't set Content-Type to "application/json" if the data sent is a string or nil (it might cause an error in some cases, like when uploading some binary content)
+* handle the (somewhat theoretical but possible) case where an access token is not a JWT but just some opaque blob – in that case, Minisky will now not throw an error trying to parse it, but just treat it as "unknown" and will not try to refresh it
+  - note: at the moment Minisky will not catch the "token expired" error and refresh the token automatically in such scenario
+* allow connecting to non-HTTPS servers (e.g. `http://localhost:3000`)
+* allow making unauthenticated clients with custom classes by returning `nil` from `#config`; custom clients with a config that's missing an `id` or `pass` are treated as an error
+* deprecate logging in using an email address in the `id` field – `createSession` accepts such identifier, but unlike with handle or DID, there's no way to use it to look up the DID document and PDS location if we wanted to
+* fixed URL query params in POST requests on Ruby 2.x
+* marked `Minisky#active_repl?` method as private
+
+Also added YARD API documentation for most of the code.
+
 ## [0.5.0] - 2024-12-27 🎄
 
 * `host` param in the initializer can be passed with a `https://` prefix (useful if you're passing it directly from a DID document, e.g. using DIDKit)
 * added validation of the `method` parameter in request calls: it needs to be either a proper NSID, or a full URL as a string or a URI object
-* added new optional `params` keyword argument in `post_request`, which lets you append query parameters to the URL if a POST endpoint requires passing them this way
+* added new optional `params` keyword argument in `post_request`, which lets you append query parameters to the URL if a POST endpoint requires passing them this way (e.g. `uploadVideo`)
 * `default_progress` is set by default to show progress using dots (`.`) if Minisky is loaded inside an IRB or Pry context
 * when experimenting with Minisky in the console, you can now skip the `field:` parameter to `fetch_all` if you don't remember the expected key name in the response, and the method will make a request and return an error which tells you the list of available keys
 * added `access_token_expired?` helper method
@@ -17,7 +34,7 @@
 * fixed error when the response is success but not JSON (e.g. an empty body like in deleteRecord)
 * allow passing options to the client in the initializer
 * aliased `default_progress` setting as `progress`
-* added `base64` dependency explicitly to the gemspec - fixes a warning in Ruby 3.3, since it will be extracted as an optional gem in 3.4
+* added `base64` dependency explicitly to the gemspec – fixes a warning in Ruby 3.3, since it will be extracted as an optional gem in 3.4
 
 ## [0.3.1] - 2023-10-10
 
@@ -28,11 +45,11 @@
 * authentication improvements & changes:
   - Minisky now automatically manages access tokens, calling `check_access` manually is not necessary (set `auto_manage_tokens` to `false` to disable this)
   - `check_access` now just checks token's expiry time instead of making a request to `getSession`
-  - added `send_auth_headers` option - set to `false` to not set auth header automatically, which is the default
-  - removed default config file name - explicit file name is now required
-  - Minisky can now be used in unauthenticated mode - pass `nil` as the config file name
+  - added `send_auth_headers` option – set to `false` to not set auth header automatically, which is the default
+  - removed default config file name – explicit file name is now required
+  - Minisky can now be used in unauthenticated mode – pass `nil` as the config file name
   - added `reset_tokens` helper method
-* refactored response handling - typed errors are now raised on non-success response status
+* refactored response handling – typed errors are now raised on non-success response status
 * `user` wrapper can also be used for writing fields to the config
 * improved error handling
 
@@ -51,7 +68,7 @@
 * renamed `ident` field in the config hash to `id`
 * config is now accessed in `Requests` from the client object as a `config` property instead of `@config` ivar
 * config fields are exposed as a `user` wrapper object, e.g. `user.did` delegates to `@config['did']`
-  
+
 ## [0.1.0] - 2023-09-01
 
 - extracted most code to a `Requests` module that can be included into a different client class with custom config handling
@@ -62,7 +79,7 @@
 
 ## [0.0.1] - 2023-08-30
 
-Initial release - extracted from original gist:
+Initial release – extracted from original gist:
 
 - logging in and refreshing the token
 - making GET & POST requests

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The zlib License
 
-Copyright (c) 2023-2024 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

@@ -5,18 +5,18 @@ Minisky is a minimal client of the Bluesky (ATProto) API. It provides a simple A
 This is designed as a low-level XRPC client library - it purposefully does not include any convenience methods like "get posts" or "get profile" etc., it only provides base components that you could use to build a higher level API.
 
 > [!NOTE]
-> ATProto Ruby gems collection: [skyfall](https://github.com/mackuba/skyfall) | [blue_factory](https://github.com/mackuba/blue_factory) | [minisky](https://github.com/mackuba/minisky) | [didkit](https://github.com/mackuba/didkit)
+> Part of ATProto Ruby SDK: [ruby.sdk.blue](https://ruby.sdk.blue)
 
 
 ## Installation
 
-To use Minisky, you need a reasonably new version of Ruby (2.6+). Such version should be preinstalled on macOS Big Sur and above and some 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.
+To use Minisky, 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/)).
 
 To install the Minisky gem, run the command:
 
     [sudo] gem install minisky
 
-Or alternatively, add it to the `Gemfile` file for Bundler:
+Or add it to your app's `Gemfile`:
 
     gem 'minisky', '~> 0.5'
 
@@ -47,7 +47,7 @@ bsky = Minisky.new('api.bsky.app', nil)
 > [!NOTE]
 > To call PDS endpoints like `getRecord` or `listRecords`, you need to connect to the PDS of the user whose data you're loading, not to yours (unless it's the same one). Alternatively, you can use the `bsky.social` "entryway" PDS hostname for any Bluesky-hosted accounts, but this will not work for self-hosted accounts.
 >
-> To look up the PDS hostname of a user given their handle or DID, you can use the [didkit](https://github.com/mackuba/didkit) library.
+> To look up the PDS hostname of a user given their handle or DID, you can use the [didkit](https://tangled.org/mackuba.eu/didkit) library.
 >
 > For the AppView, `api.bsky.app` connects directly to Bluesky's AppView, and `public.api.bsky.app` to a version with extra caching that will usually be faster.
 
@@ -135,7 +135,7 @@ This will output a line like this:
 .................
 ```
 
-You can find more examples in the [example](https://github.com/mackuba/minisky/tree/master/example) directory.
+You can find more examples on the [examples page](https://ruby.sdk.blue/examples/) on [ruby.sdk.blue](https://ruby.sdk.blue).
 
 
 ## Customization
@@ -192,7 +192,7 @@ The class needs to provide:
 
 ## Credits
 
-Copyright © 2024 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
+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).
 

data/lib/minisky/compat.rb

@@ -0,0 +1,20 @@
+require_relative 'minisky'
+
+class Minisky
+
+  #
+  # Versions of {Requests#get_request} & {Requests#post_request} that work on Ruby 2.x.
+  #
+
+  module Ruby2Compat
+    def get_request(method, params = nil, auth: default_auth_mode, headers: nil, **kwargs)
+      params ||= kwargs unless kwargs.empty?
+      super(method, params, auth: auth, headers: headers)
+    end
+
+    def post_request(method, data = nil, auth: default_auth_mode, headers: nil, params: nil, **kwargs)
+      data ||= kwargs unless kwargs.empty?
+      super(method, data, auth: auth, headers: headers, params: params)
+    end
+  end
+end

data/lib/minisky/errors.rb

@@ -1,18 +1,34 @@
 require_relative 'minisky'
 
 class Minisky
+
+  #
+  # Common base error class for Minisky errors.
+  #
   class Error < StandardError
   end
 
+  #
+  # Raised when a required token or credentials are missing or invalid.
+  #
   class AuthError < Error
-    def initialize(message)
-      super(message)
-    end
   end
 
+  #
+  # Raised when the API returns an error status code.
+  #
   class BadResponse < Error
-    attr_reader :status, :data
 
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @return [String, Hash] response data (JSON hash or string)
+    attr_reader :data
+
+    # @param status [Integer] HTTP status code
+    # @param status_message [String] HTTP status message
+    # @param data [Hash, String] response data (JSON hash or string)
+    #
     def initialize(status, status_message, data)
       @status = status
       @data = data
@@ -26,36 +42,78 @@ class Minisky
       super(message)
     end
 
+    # @return [String, nil] machine-readable error code from the response data
     def error_type
       @data['error'] if @data.is_a?(Hash)
     end
 
+    # @return [String, nil] human-readable error message from the response data
     def error_message
       @data['message'] if @data.is_a?(Hash)
     end
   end
 
+  #
+  # Raised when the API returns a client error status code (4xx).
+  #
   class ClientErrorResponse < BadResponse
   end
 
+  #
+  # Raised when the API returns a server error status code (5xx).
+  #
   class ServerErrorResponse < BadResponse
   end
 
+  #
+  # Raised when the API returns an error indicating that the access or request
+  # token that was passed in the header is expired.
+  #
   class ExpiredTokenError < ClientErrorResponse
   end
 
+  #
+  # Raised when the API returns a redirect status code (3xx). Minisky doesn't
+  # currently follow any redirects.
+  #
   class UnexpectedRedirect < BadResponse
+
+    # @return [String] value of the "Location" header
     attr_reader :location
 
+    # @param status [Integer] HTTP status code
+    # @param status_message [String] HTTP status message
+    # @param location [String] value of the "Location" header
+    #
     def initialize(status, status_message, location)
       super(status, status_message, { 'message' => "Unexpected redirect: #{location}" })
       @location = location
     end
   end
 
+  #
+  # Raised by {Requests#fetch_all} when the `field` parameter isn't set.
+  #
+  # The message of the exception lists the fields available in the first fetched page.
+  #
+  # @example Making a request in the console with empty `field`
+  #   sky = Minisky.new('public.api.bsky.app', nil)
+  #   # => #<Minisky:0x0000000120f5f6b0 @host="public.api.bsky.app", ...>
+  #
+  #   sky.fetch_all('app.bsky.graph.getFollowers', { actor: 'sdk.blue' })
+  #   # ./lib/minisky/requests.rb:270:in 'block in Minisky::Requests#fetch_all':
+  #   #   Field parameter not provided; available fields: ["followers"] (Minisky::FieldNotSetError)
+  #
+  #   sky.fetch_all('app.bsky.graph.getFollowers', { actor: 'sdk.blue' }, field: 'followers')
+  #   # => .....
+  #
   class FieldNotSetError < Error
+
+    # @return [Array<String>] list of fields in the response data
     attr_reader :fields
 
+    # @param fields [Array<String>] list of fields in the response data
+    #
     def initialize(fields)
       @fields = fields
       super("Field parameter not provided; available fields: #{@fields.inspect}")

data/lib/minisky/minisky.rb

@@ -1,8 +1,47 @@
 require 'yaml'
 
+#
+# The default API client class for making requests to AT Protocol servers. Can be used
+# with authentication – with the credentials stored in a YAML file – or without it, for
+# unauthenticated requests only (by passing `nil` as the config file name).
+#
+# @example Authenticated client
+#   # Expects a config.yml file like:
+#   #
+#   # id: test.example.com
+#   # pass: secret7
+#   #
+#   # "id" can be a handle or a DID.
+#
+#   sky = Minisky.new('eurosky.social', 'config.yml')
+#
+#   feed = sky.get_request('app.bsky.feed.getTimeline', { limit: 100 })
+#
+# @example Unauthenticated client
+#   sky = Minisky.new('public.api.bsky.app', nil, progress: '*')
+#
+#   follows = sky.get_request('app.bsky.graph.getFollows',
+#     { actor: 'atproto.com', limit: 100 },
+#     field: 'follows'
+#   )
+#
+
 class Minisky
-  attr_reader :host, :config
 
+  # @return [String] the hostname (or base URL) of the server
+  attr_reader :host
+
+  # @return [Hash] loaded contents of the config file
+  attr_reader :config
+
+  # Creates a new client instance.
+  #
+  # @param host [String] the hostname (or base URL) of the server
+  # @param config_file [String, nil] path to the YAML config file, or `nil` for unauthenticated client
+  # @param options [Hash] option properties to set on the new instance (see {Minisky::Requests} properties)
+  #
+  # @raise [AuthError] if the config file is missing an ID or password
+  #
   def initialize(host, config_file, options = {})
     @host = host
     @config_file = config_file
@@ -14,9 +53,7 @@ class Minisky
         raise AuthError, "Missing user id or password in the config file #{@config_file}"
       end
     else
-      @config = {}
-      @send_auth_headers = false
-      @auto_manage_tokens = false
+      @config = nil
     end
 
     if active_repl?
@@ -30,15 +67,18 @@ class Minisky
     end
   end
 
+  def save_config
+    File.write(@config_file, YAML.dump(@config)) if @config_file
+  end
+
+
+  private
+
   def active_repl?
     return true if defined?(IRB) && IRB.respond_to?(:CurrentContext) && IRB.CurrentContext
     return true if defined?(Pry) && Pry.respond_to?(:cli) && Pry.cli
     false
   end
-
-  def save_config
-    File.write(@config_file, YAML.dump(@config)) if @config_file
-  end
 end
 
 require_relative 'requests'

data/lib/minisky/requests.rb

@@ -13,6 +13,10 @@ class Minisky
       @config = config
     end
 
+    def has_credentials?
+      !!(id && pass)
+    end
+
     def logged_in?
       !!(access_token && refresh_token)
     end
@@ -26,19 +30,62 @@ class Minisky
     end
   end
 
+  # Regexp for NSID identifiers, used in lexicon names for record collection and API endpoints
   NSID_REGEXP = /^[a-zA-Z]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(\.[a-zA-Z]([a-zA-Z]{0,61}[a-zA-Z])?)$/
 
+  #
+  # This module contains most of the Minisky code for making HTTP requests and managing
+  # authentication tokens. The module is included into the {Minisky} API client class and you'll
+  # normally use it through that class, but you can also include it into your custom class if you
+  # want to implement the data storage differently than using a local YAML file as {Minisky} does.
+  #
+
   module Requests
+
+    # A character to print before each request in {#fetch_all} as a progress indicator.
+    # Can also be passed explicitly instead or overridden using the `progress:` parameter.
+    # Default is `'.'` when running inside IRB, and `nil` otherwise.
+    #
+    # @return [String, nil]
+    #
     attr_accessor :default_progress
+
+    # By default, when `fetch_all` receives a response with an empty page with no records but
+    # which includes a cursor for the next page, it keeps fetching until it receives a response
+    # with null cursor. This is more technically correct, but can cause problems with some
+    # non-compliant APIs, so you can set this option to stop fetching when an empty page
+    # is received.
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :stop_fetch_on_empty_page
+
     attr_writer :send_auth_headers
     attr_writer :auto_manage_tokens
 
+    # Tells whether to set authentication headers automatically (default: true if there
+    # is a user config).
+    #
+    # If false, you will need to pass `auth: 'sometoken'` explicitly to requests that
+    # require authentication.
+    #
+    # @return [Boolean] whether to set authentication headers in requests
+    #
     def send_auth_headers
-      instance_variable_defined?('@send_auth_headers') ? @send_auth_headers : true
+      instance_variable_defined?('@send_auth_headers') ? @send_auth_headers : (config != nil)
     end
 
+    # Tells whether the library should manage the access & refresh tokens automatically
+    # for you (default: true if there is a user config).
+    #
+    # If true, {#check_access} is called before each request to make sure that there is a
+    # fresh access token available; if false, you will need to call {#log_in} and
+    # {#perform_token_refresh} manually when needed.
+    #
+    # @return [Boolean] whether to automatically manage access tokens
+    #
     def auto_manage_tokens
-      instance_variable_defined?('@auto_manage_tokens') ? @auto_manage_tokens : true
+      instance_variable_defined?('@auto_manage_tokens') ? @auto_manage_tokens : (config != nil)
     end
 
     alias progress default_progress
@@ -53,9 +100,38 @@ class Minisky
     end
 
     def user
-      @user ||= User.new(config)
+      @user ||= config && User.new(config)
     end
 
+    # Sends a GET request to the service's API.
+    #
+    # @param method [String, URI] an XRPC endpoint name or a full URL
+    # @param params [Hash, nil] query parameters
+    #
+    # @param auth [Boolean, String]
+    #    boolean value which tells whether to send an auth header with the access token or not,
+    #    or an explicit bearer token to use
+    # @param headers [Hash, nil]
+    #    additional headers to include
+    #
+    # @return [Hash, String] parsed JSON hash for JSON responses, or raw response body otherwise
+    #
+    # @raise [ArgumentError] if method name is invalid
+    # @raise [BadResponse] if the HTTP response has an error status code
+    # @raise [AuthError]
+    #   - if logging in is required, but login or password isn't provided
+    #   - if token refresh is needed, but refresh token is missing
+    #   - if a token has invalid format
+    #   - if required access token is missing, and {#auto_manage_tokens} is disabled
+    #
+    # @example Unauthenticated call
+    #   sky = Minisky.new('public.api.bsky.app', nil)
+    #   profile = sky.get_request('app.bsky.actor.getProfile', { actor: 'ec.europa.eu' })
+    #
+    # @example Authenticated call
+    #   sky = Minisky.new('blacksky.app', 'config.yml')
+    #   feed = sky.get_request('app.bsky.feed.getTimeline', { limit: 100 })
+
     def get_request(method, params = nil, auth: default_auth_mode, headers: nil)
       check_access if auto_manage_tokens && auth == true
 
@@ -72,16 +148,52 @@ class Minisky
       handle_response(response)
     end
 
+    # Sends a POST request to the service's API.
+    #
+    # @param method [String, URI] an XRPC endpoint name or a full URL
+    # @param data [Hash, String, nil] JSON or string data to send
+    #
+    # @param auth [Boolean, String]
+    #    boolean value which tells whether to send an auth header with the access token or not,
+    #    or an explicit bearer token to use
+    # @param headers [Hash, nil]
+    #    additional headers to include
+    # @param params [Hash, nil]
+    #    query parameters to append to the URL
+    #
+    # @return [Hash, String] parsed JSON hash for JSON responses, or raw response body otherwise
+    #
+    # @raise [ArgumentError] if method name is invalid
+    # @raise [BadResponse] if the HTTP response has an error status code
+    # @raise [AuthError]
+    #   - if logging in is required, but login or password isn't provided
+    #   - if token refresh is needed, but refresh token is missing
+    #   - if a token has invalid format
+    #   - if required access token is missing, and {#auto_manage_tokens} is disabled
+    #
+    # @example Making a Bluesky post
+    #   sky = Minisky.new('lab.martianbase.net', 'config.yml')
+    #
+    #   sky.post_request('com.atproto.repo.createRecord', {
+    #     repo: sky.user.did,
+    #     collection: 'app.bsky.feed.post',
+    #     record: {
+    #       text: "Hello Bluesky!",
+    #       createdAt: Time.now.iso8601,
+    #       langs: ['en']
+    #     }
+    #   })
+
     def post_request(method, data = nil, auth: default_auth_mode, headers: nil, params: nil)
       check_access if auto_manage_tokens && auth == true
 
       headers = authentication_header(auth).merge(headers || {})
-      headers["Content-Type"] = "application/json" unless headers.keys.any? { |k| k.to_s.downcase == 'content-type' }
 
-      body = if data.is_a?(String) || data.nil?
-        data.to_s
+      if data.is_a?(String) || data.nil?
+        body = data.to_s
       else
-        data.to_json
+        body = data.to_json
+        headers["Content-Type"] = "application/json" unless headers.keys.any? { |k| k.to_s.downcase == 'content-type' }
       end
 
       url = build_request_uri(method)
@@ -94,6 +206,73 @@ class Minisky
       handle_response(response)
     end
 
+    # Fetches and merges paginated responses from a service's endpoint in a loop, updating the
+    # cursor after each page, until the cursor is nil or a break condition is met. The data is
+    # extracted from a designated field of the response (`field`) and added to a single array,
+    # which is returned at the end.
+    #
+    # A condition for when the fetching should stop can be passed as a block in `break_when`, or
+    # alternatively, a max number of pages can be passed to `max_pages` (or both together). If
+    # neither is set, the fetching continues until the server returns an empty cursor.
+    #
+    # When experimenting in the Ruby console, you can pass `nil` as `field` (or skip the parameter)
+    # to make a single request and raise an exception, which will tell you what fields are available.
+    #
+    # @param method [String, URI] an XRPC endpoint name or a full URL
+    # @param params [Hash, nil] query parameters
+    #
+    # @param auth [Boolean, String]
+    #    boolean value which tells whether to send an auth header with the access token or not,
+    #    or an explicit bearer token to use
+    # @param field [String, nil]
+    #    name of the field in the responses which contains the data array
+    # @param break_when [Proc, nil]
+    #    if passed, the fetching will stop when the block returns true for any of the
+    #    returned records, and records matching the condition will be deleted from the last page
+    # @param max_pages [Integer, nil]
+    #    maximum number of pages to fetch
+    # @param headers [Hash, nil]
+    #    additional headers to include
+    # @param progress [String, nil]
+    #    a character to print before each request as a progress indicator
+    #
+    # @return [Array] records or objects collected from all pages
+    #
+    # @raise [ArgumentError] if method name is invalid
+    # @raise [FieldNotSetError] if field parameter wasn't set (the message tells you what fields were in the response)
+    # @raise [BadResponse] if the HTTP response has an error status code
+    # @raise [AuthError]
+    #     - if logging in is required, but login or password isn't provided
+    #     - if token refresh is needed, but refresh token is missing
+    #     - if a token has invalid format
+    #     - if required access token is missing, and {#auto_manage_tokens} is disabled
+    #
+    # @example Fetching with a `break_when` block
+    #   sky = Minisky.new('public.api.bsky.app', nil)
+    #   time_limit = Time.now - 86400 * 30
+    #
+    #   sky.fetch_all('app.bsky.feed.getAuthorFeed',
+    #     { actor: 'pfrazee.com', limit: 100 },
+    #     field: 'feed',
+    #     progress: '|',
+    #     break_when: ->(x) { Time.at(x['post']['record']['createdAt']) < time_limit }
+    #   )
+    #
+    # @example Fetching with `max_pages`
+    #   sky = Minisky.new('tngl.sh', 'config.yml')
+    #   sky.fetch_all('app.bsky.feed.getTimeline', { limit: 100 }, field: 'feed', max_pages: 10)
+    #
+    # @example Making a request in the console with empty `field`
+    #   sky = Minisky.new('public.api.bsky.app', nil)
+    #   # => #<Minisky:0x0000000120f5f6b0 @host="public.api.bsky.app", ...>
+    #
+    #   sky.fetch_all('app.bsky.graph.getFollowers', { actor: 'sdk.blue' })
+    #   # ./lib/minisky/requests.rb:270:in 'block in Minisky::Requests#fetch_all':
+    #   #   Field parameter not provided; available fields: ["followers"] (Minisky::FieldNotSetError)
+    #
+    #   sky.fetch_all('app.bsky.graph.getFollowers', { actor: 'sdk.blue' }, field: 'followers')
+    #   # => .....
+
     def fetch_all(method, params = nil, auth: default_auth_mode,
                   field: nil, break_when: nil, max_pages: nil, headers: nil, progress: @default_progress)
       data = []
@@ -116,7 +295,7 @@ class Minisky
         params[:cursor] = cursor
         pages += 1
 
-        break if !cursor || records.empty? || pages == max_pages
+        break if !cursor || pages == max_pages || (stop_fetch_on_empty_page && records.empty?)
         break if break_when && records.any? { |x| break_when.call(x) }
       end
 
@@ -124,11 +303,42 @@ class Minisky
       data
     end
 
+    # Ensures that the user has a fresh access token, by checking the access token's expiry date
+    # and performing a refresh if needed, or by logging in with a password if no tokens are present.
+    #
+    # If {#auto_manage_tokens} is enabled (the default setting), this method is automatically called
+    # before {#get_request}, {#post_request} and {#fetch_all}, so you generally don't need to call it
+    # yourself.
+    #
+    # @return [Symbol]
+    #   - `:logged_in` if a login using a password was performed
+    #   - `:refreshed` if the access token was expired and was refreshed
+    #   - `:ok` if no refresh was needed
+    #   - `:unknown` if the token is not a valid JWT (e.g. an opaque blob)
+    #
+    # @raise [BadResponse] if login or refresh returns an error status code
+    # @raise [AuthError]
+    #   - if the client doesn't include user config at all
+    #   - if logging in is required, but login or password isn't provided
+    #   - if token refresh is needed, but refresh token is missing
+
     def check_access
-      if !user.logged_in?
+      if !user
+        raise AuthError, "User config is missing"
+      elsif !user.has_credentials?
+        raise AuthError, "User id or password is missing"
+      elsif !user.logged_in?
         log_in
-        :logged_in
-      elsif access_token_expired?
+        return :logged_in
+      end
+
+      begin
+        expired = access_token_expired?
+      rescue AuthError
+        return :unknown
+      end
+
+      if expired
         perform_token_refresh
         :refreshed
       else
@@ -136,8 +346,21 @@ class Minisky
       end
     end
 
+    # Logs in the user using an ID and password stored in the config by calling the
+    # `createSession` endpoint, and stores the received access & refresh tokens.
+    #
+    # This is generally handled automatically by {#check_access}. Calling this method
+    # repeatedly many times in a short period of time may use up your rate limit for this
+    # endpoint (which is lower than for others) and make it inaccessible to you for some
+    # time.
+    #
+    # @return [Hash] the response JSON with access tokens
+    #
+    # @raise [AuthError] if login or password are missing
+    # @raise [BadResponse] if the server responds with an error status code
+
     def log_in
-      if user.id.nil? || user.pass.nil?
+      if user.nil? || !user.has_credentials?
         raise AuthError, "To log in, please provide a user id and password"
       end
 
@@ -146,6 +369,11 @@ class Minisky
         password: user.pass
       }
 
+      if user.id =~ /\A[^@]+@[^@]+\z/
+        STDERR.puts "Warning: logging in using an email address is deprecated in Minisky and will be " +
+          "removed in a future version. Use either a handle or a DID instead."
+      end
+
       json = post_request('com.atproto.server.createSession', data, auth: false)
 
       user.did = json['did']
@@ -156,8 +384,19 @@ class Minisky
       json
     end
 
+    # Refreshes the access token using the stored refresh token. If successful, this
+    # invalidates *both* old tokens and replaces them with new ones from the response.
+    #
+    # If {#auto_manage_tokens} is enabled (the default setting), this method is automatically called
+    # before any requests through {#check_access}, so you generally don't need to call it yourself.
+    #
+    # @return [Hash] the response JSON with access tokens
+    #
+    # @raise [AuthError] if the refresh token is missing
+    # @raise [BadResponse] if the server responds with an error status code
+
     def perform_token_refresh
-      if user.refresh_token.nil?
+      if user&.refresh_token.nil?
         raise AuthError, "Can't refresh access token - refresh token is missing"
       end
 
@@ -170,27 +409,64 @@ class Minisky
       json
     end
 
+    # Attempts to parse a given token as JWT and extract the expiration date from the payload.
+    # An access token technically isn't required to be a (valid) JWT, so if the parsing fails
+    # for whatever reason, nil is returned.
+    #
+    # @return [Time, nil] parsed expiration time, or nil if token is not a valid JWT
+
     def token_expiration_date(token)
+      return nil unless token.valid_encoding?
+
       parts = token.split('.')
-      raise AuthError, "Invalid access token format" unless parts.length == 3
+      return nil unless parts.length == 3
 
       begin
         payload = JSON.parse(Base64.decode64(parts[1]))
       rescue JSON::ParserError
-        raise AuthError, "Couldn't decode payload from access token"
+        return nil
       end
 
       exp = payload['exp']
-      raise AuthError, "Invalid token expiry data" unless exp.is_a?(Numeric) && exp > 0
+      return nil unless exp.is_a?(Numeric) && exp > 0
 
-      Time.at(exp)
+      time = Time.at(exp)
+      return nil if time.year < 2023 || time.year > 2100
+
+      time
     end
 
+    # Attempts to parse the user's access token as JWT, extract the expiration date from the
+    # payload, and check if the token hasn't expired yet.
+    #
+    # @return [Boolean] true if the token's expiration time is more than a minute away
+    # @raise [AuthError] if the token is not a valid JWT, or user is not logged in
+
     def access_token_expired?
-      token_expiration_date(user.access_token) < Time.now + 60
+      if user&.access_token.nil?
+        raise AuthError, "No access token (user is not logged in)"
+      end
+
+      exp_date = token_expiration_date(user.access_token)
+
+      if exp_date
+        exp_date < Time.now + 60
+      else
+        raise AuthError, "Token expiration date cannot be decoded"
+      end
     end
 
+    #
+    # Clear stored access and refresh tokens, effectively logging out the user.
+    #
+    # @raise [AuthError] if the client doesn't have a user config
+    #
+
     def reset_tokens
+      if !user
+        raise AuthError, "User config is missing"
+      end
+
       user.access_token = nil
       user.refresh_token = nil
       save_config
@@ -198,19 +474,8 @@ class Minisky
     end
 
     if RUBY_VERSION.to_i == 2
-      alias_method :do_get_request, :get_request
-      alias_method :do_post_request, :post_request
-      private :do_get_request, :do_post_request
-
-      def get_request(method, params = nil, auth: default_auth_mode, headers: nil, **kwargs)
-        params ||= kwargs unless kwargs.empty?
-        do_get_request(method, params, auth: auth, headers: headers)
-      end
-
-      def post_request(method, params = nil, auth: default_auth_mode, headers: nil, **kwargs)
-        params ||= kwargs unless kwargs.empty?
-        do_post_request(method, params, auth: auth, headers: headers)
-      end
+      require_relative 'compat'
+      prepend Ruby2Compat
     end
 
 
@@ -218,7 +483,7 @@ class Minisky
 
     def make_request(request)
       # this long form is needed because #get_response only supports a headers param in Ruby 3.x
-      response = Net::HTTP.start(request.uri.hostname, request.uri.port, use_ssl: true) do |http|
+      response = Net::HTTP.start(request.uri.hostname, request.uri.port, use_ssl: (request.uri.scheme == 'https')) do |http|
         http.request(request)
       end
     end
@@ -243,7 +508,7 @@ class Minisky
       if auth.is_a?(String)
         { 'Authorization' => "Bearer #{auth}" }
       elsif auth
-        if user.access_token
+        if user&.access_token
           { 'Authorization' => "Bearer #{user.access_token}" }
         else
           raise AuthError, "Can't send auth headers, access token is missing"

data/lib/minisky/version.rb

@@ -1,5 +1,5 @@
 require_relative 'minisky'
 
 class Minisky
-  VERSION = "0.5.0"
+  VERSION = "0.5.1"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: minisky
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Kuba Suder
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -35,26 +34,20 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- example/ask_password.rb
-- example/fetch_my_posts.rb
-- example/fetch_profile.rb
-- example/find_missing_follows.rb
-- example/post_skeet.rb
-- example/science_feed.rb
 - lib/minisky.rb
+- lib/minisky/compat.rb
 - lib/minisky/errors.rb
 - lib/minisky/minisky.rb
 - lib/minisky/requests.rb
 - lib/minisky/version.rb
 - sig/minisky.rbs
-homepage: https://github.com/mackuba/minisky
+homepage: https://ruby.sdk.blue
 licenses:
 - Zlib
 metadata:
-  bug_tracker_uri: https://github.com/mackuba/minisky/issues
-  changelog_uri: https://github.com/mackuba/minisky/blob/master/CHANGELOG.md
-  source_code_uri: https://github.com/mackuba/minisky
-post_install_message:
+  bug_tracker_uri: https://tangled.org/mackuba.eu/minisky/issues
+  changelog_uri: https://tangled.org/mackuba.eu/minisky/blob/master/CHANGELOG.md
+  source_code_uri: https://tangled.org/mackuba.eu/minisky
 rdoc_options: []
 require_paths:
 - lib
@@ -69,8 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
-summary: A minimal client of Bluesky/AtProto API
+summary: A minimal client of Bluesky/ATProto API
 test_files: []

data/example/ask_password.rb

@@ -1,76 +0,0 @@
-#!/usr/bin/env ruby
-
-# Example: print 10 latest posts from the user's home feed.
-# 
-# Instead of using a config file to read & store authentication info, this example uses a customized client class
-# which reads the password from the console and creates a throwaway access token.
-#
-# This approach makes sense for one-off scripts, but it shouldn't be used for things that need to be done repeatedly
-# and often (the authentication-related endpoints have lower rate limits than others).
-
-# load minisky from a local folder - you normally won't need this
-$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
-
-require 'io/console'
-require 'minisky'
-
-class TransientClient
-  include Minisky::Requests
-
-  attr_reader :config, :host
-
-  def initialize(host, user)
-    @host = host
-    @config = { 'id' => user.gsub(/^@/, '') }
-  end
-
-  def ask_for_password
-    print "Enter password for @#{config['id']}: "
-    @config['pass'] = STDIN.noecho(&:gets).chomp
-    puts
-  end
-
-  def save_config
-    # ignore
-  end
-end
-
-host, handle = ARGV
-
-unless host && handle
-  puts "Usage: #{$PROGRAM_NAME} <pds_hostname> <handle>"
-  exit 1
-end
-
-# create a client instance & read password
-bsky = TransientClient.new(host, handle)
-bsky.ask_for_password
-
-# fetch 10 posts from the user's home feed
-result = bsky.get_request('app.bsky.feed.getTimeline', { limit: 10 })
-
-result['feed'].each do |r|
-  reason = r['reason']
-  reply = r['reply']
-  post = r['post']
-
-  if reason && reason['$type'] == 'app.bsky.feed.defs#reasonRepost'
-    puts "[Reposted by @#{reason['by']['handle']}]"
-  end
-
-  handle = post['author']['handle']
-  timestamp = Time.parse(post['record']['createdAt']).getlocal
-
-  puts "@#{handle} • #{timestamp}"
-  puts
-
-  if reply
-    puts "[in reply to @#{reply['parent']['author']['handle']}]"
-    puts
-  end
-
-  puts post['record']['text']
-  puts
-  puts "=" * 120
-  puts
-end

data/example/fetch_my_posts.rb

@@ -1,46 +0,0 @@
-#!/usr/bin/env ruby
-
-# Example: sync all posts from your account (excluding replies and reposts) to a local JSON file. When run again, it
-# will only fetch new posts since the last time and append them to the file.
-#
-# Requires a bluesky.yml config file in the same directory with contents like this:
-# id: your.handle
-# pass: secretpass
-
-# load minisky from a local folder - you normally won't need this
-$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
-
-require 'minisky'
-
-CONFIG_FILE = File.join(__dir__, 'bluesky.yml')
-POSTS_FILE = File.join(__dir__, 'posts.json')
-
-# create a client instance
-bsky = Minisky.new('bsky.social', CONFIG_FILE)
-
-# print progress dots when loading multiple pages
-bsky.default_progress = '.'
-
-# load previously saved posts; we will only fetch posts newer than the last saved before
-posts = File.exist?(POSTS_FILE) ? JSON.parse(File.read(POSTS_FILE)) : []
-latest_date = posts[0] && posts[0]['indexedAt']
-
-# fetch all posts from my timeline (without replies) until the target timestamp
-results = bsky.fetch_all('app.bsky.feed.getAuthorFeed',
-  { actor: bsky.user.did, filter: 'posts_no_replies', limit: 100 },
-  field: 'feed',
-  break_when: latest_date && proc { |x| x['post']['indexedAt'] <= latest_date }
-)
-
-# trim some data to save space
-new_posts = results.map { |x| x['post'] }
-  .reject { |x| x['author']['did'] != bsky.user.did }   # skip reposts
-  .map { |x| x.except('author') }                       # skip author profile info
-
-posts = new_posts + posts
-
-puts
-puts "Fetched #{new_posts.length} new posts (total = #{posts.length})"
-
-# save all new and old posts back to the file
-File.write(POSTS_FILE, JSON.pretty_generate(posts))

data/example/fetch_profile.rb

@@ -1,53 +0,0 @@
-#!/usr/bin/env ruby
-
-# Example: fetch the profile info of a given user and their last 10 posts (excluding reposts).
-#
-# This script connects to the AppView server at api.bsky.app, which allows calling such endpoints as getProfile or
-# getAuthorFeed without authentication.
-
-# load minisky from a local folder - you normally won't need this
-$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
-
-require 'minisky'
-require 'time'
-
-if ARGV[0].to_s !~ /^@?[\w\-]+(\.[\w\-]+)+$/
-  puts "Usage: #{$PROGRAM_NAME} <handle>"
-  exit 1
-end
-
-handle = ARGV[0].gsub(/^@/, '')
-
-# passing nil as config file to use an unauthenticated client
-bsky = Minisky.new('api.bsky.app', nil)
-
-# fetch profile info
-profile = bsky.get_request('app.bsky.actor.getProfile', { actor: handle })
-
-# fetch posts, without replies - we fetch a bit more than we need because we'll also filter out reposts
-posts = bsky.get_request('app.bsky.feed.getAuthorFeed', { actor: handle, filter: 'posts_no_replies', limit: 40 })
-
-# print the profile
-
-puts
-puts "====[ @#{handle} • #{profile['displayName']} • #{profile['did']} ]===="
-puts
-puts profile['description']
-puts
-puts '=' * 80
-puts
-
-# print the posts
-
-posts['feed'].map { |r|
-  r['post']
-}.select { |p|
-  # select only posts from this account
-  p['author']['handle'] == handle
-}.slice(0, 10).each { |p|
-  time = Time.parse(p['record']['createdAt'])
-  timestamp = time.getlocal.strftime('%a %d.%m %H:%M')
-
-  puts "#{timestamp}: #{p['record']['text']}"
-  puts
-}

data/example/find_missing_follows.rb

@@ -1,67 +0,0 @@
-#!/usr/bin/env ruby
-
-# Example: fetch the list of accounts followed by a given user and check which of them have been deleted / deactivated.
-
-# load minisky from a local folder - you normally won't need this
-$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
-
-require 'didkit'
-require 'minisky'
-
-handle = ARGV[0].to_s.gsub(/^@/, '')
-if handle.empty?
-  puts "Usage: #{$PROGRAM_NAME} <handle>"
-  exit 1
-end
-
-pds_host = DID.resolve_handle(handle).get_document.pds_endpoint
-pds = Minisky.new(pds_host, nil, progress: '.')
-
-print "Fetching all follows of @#{handle} from #{pds_host}: "
-
-follows = pds.fetch_all('com.atproto.repo.listRecords',
-  { repo: handle, collection: 'app.bsky.graph.follow', limit: 100 }, field: 'records')
-
-puts
-puts "Found #{follows.length} follows"
-
-appview = Minisky.new('api.bsky.app', nil)
-
-profiles = []
-i = 0
-
-puts
-print "Fetching profiles of all followed accounts: "
-
-# getProfiles lets us load multiple profiles in one request, but only up to 25 in one batch
-
-while i < follows.length
-  batch = follows[i...i+25]
-  dids = batch.map { |x| x['value']['subject'] }
-  print '.'
-  result = appview.get_request('app.bsky.actor.getProfiles', { actors: dids })
-  profiles += result['profiles']
-  i += 25
-end
-
-# these are DIDs that are on the follows list, but aren't being returned from getProfiles
-missing = follows.map { |x| x['value']['subject'] } - profiles.map { |x| x['did'] }
-
-puts
-puts "#{missing.length} followed accounts are missing:"
-puts
-
-missing.each do |did|
-  begin
-    doc = DID.new(did).get_document
-  rescue OpenURI::HTTPError
-    puts "#{did} (?) => DID not found"
-    next
-  end
-
-  # check account status on their assigned PDS
-  pds = Minisky.new(doc.pds_endpoint.gsub('http://', ''), nil)
-  status = pds.get_request('com.atproto.sync.getRepoStatus', { did: did }).slice('status', 'active') rescue 'deleted'
-
-  puts "#{did} (@#{doc.handles.first}) => #{status}"
-end

data/example/post_skeet.rb

@@ -1,36 +0,0 @@
-#!/usr/bin/env ruby
-
-# Example: make a new post (aka "skeet") with text passed in the argument to the script.
-#
-# Requires a bluesky.yml config file in the same directory with contents like this:
-# id: your.handle
-# pass: secretpass
-
-# load minisky from a local folder - you normally won't need this
-$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
-
-require 'minisky'
-
-if ARGV[0].to_s.empty?
-  puts "Usage: #{$PROGRAM_NAME} <text>"
-  exit 1
-end
-
-text = ARGV[0]
-
-# create a client instance
-bsky = Minisky.new('bsky.social', File.join(__dir__, 'bluesky.yml'))
-
-# to make a post, we upload a post record to the posts collection (app.bsky.feed.post) in the user's repo
-
-bsky.post_request('com.atproto.repo.createRecord', {
-  repo: bsky.user.did,
-  collection: 'app.bsky.feed.post',
-  record: {
-    text: text,
-    createdAt: Time.now.iso8601,  # we need to set the date to current time manually
-    langs: ["en"]   # if a post does not have a language set, it may be autodetected as an incorrect language
-  }
-})
-
-puts "Posted ✓"

data/example/science_feed.rb

@@ -1,53 +0,0 @@
-#!/usr/bin/env ruby
-
-# Example: load last 10 posts from the "What's Science" feed and print the post text, data and author handle to the
-# terminal. Does not require any authentication.
-#
-# It's definitely not the most efficient way to do this, but it demonstrates how to load single records from the API.
-# (A more efficient way would be e.g. to connect to the AppView at api.bsky.app and make one call to getPosts.)
-
-# load minisky from a local folder - you normally won't need this
-$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
-
-require 'minisky'
-require 'time'
-
-# the "What's Science" custom feed by @bossett.bsky.social
-# the service host is hardcoded here, ideally you should fetch the feed record and read the hostname from there
-FEED_HOST = "bs.bossett.io"
-FEED_URI = "at://did:plc:jfhpnnst6flqway4eaeqzj2a/app.bsky.feed.generator/for-science"
-
-# fetch the feed from the feed server (getFeedSkeleton returns only a list or URIs of posts)
-# pass nil as the config file parameter to create an unauthenticated client
-feed_api = Minisky.new(FEED_HOST, nil)
-feed = feed_api.get_request('app.bsky.feed.getFeedSkeleton', { feed: FEED_URI, limit: 10 })
-
-# second client instance for the Bluesky API - again, pass nil to use without authentication
-bsky = Minisky.new('bsky.social', nil)
-
-# for each post URI, fetch the post record and the profile of its author
-entries = feed['feed'].map do |r|
-  # AT URI is always: at://<did>/<collection>/<rkey>
-  did, collection, rkey = r['post'].gsub('at://', '').split('/')
-
-  print '.'
-  post = bsky.get_request('com.atproto.repo.getRecord', { repo: did, collection: collection, rkey: rkey })
-  author = bsky.get_request('com.atproto.repo.describeRepo', { repo: did })
-
-  [post, author]
-end
-
-puts
-
-entries.each do |post, author|
-  handle = author['handle']
-  timestamp = Time.parse(post['value']['createdAt']).getlocal
-  link = "https://bsky.app/profile/#{handle}/post/#{post['uri'].split('/').last}"
-
-  puts "@#{handle} • #{timestamp} • #{link}"
-  puts
-  puts post['value']['text']
-  puts
-  puts "=" * 120
-  puts
-end