minisky 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f4836f5b8d8de9c5f9af0368144fe60f274e1b61176d1c919b70d3fd645a3f3
-  data.tar.gz: 8c87cdbb362b19651e848804aa6c551c88abc759bbdd3df6e609b62b94a7da4b
+  metadata.gz: b22e3b707a428f0381e5c194ce6b5bd4118f6b6dfb7f2d249140c8025e3b1dd7
+  data.tar.gz: 2a6370ea6cb538c680252836295c411ff4c6df93b8c5aab9d8b73b843753febb
 SHA512:
-  metadata.gz: 84052665f10f23db1513a5135dcb9032f0fbc4c5ae55fc7bbeb15e26d85904acda3ac55170e58d8901e5549ceaaafa34aa038ec8987da9dfdded5349080f12d2
-  data.tar.gz: 5557b97bb51b8feb757a2d16dccfefd7dfd31655a833b379681d89cc924717e234baa19523cda89368f6610481cf11c0dd9494355539d4c7364c9913a05c2ca1
+  metadata.gz: 3f86def9480e86d2989a52f143eacee8e5b78fede45bd6ba49ea7ad54f1da88a55555421d3fdfdddad025bed21a708c830e5e9b2c351ba57e016234e200b9f74
+  data.tar.gz: f8f7faa8d7e5df7807d6e9bb7ee1b87d1d5ab5503c0193fd031190be6e6346004618c66efdba96970fc93117d4f587c53ff5f17585a2ffa3ddafb503abc5a3cc

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [0.4.0] - 2024-03-31 🐣
+
+* allow passing non-JSON body to requests (e.g. when uploading blobs)
+* allow passing custom headers to requests, including overriding `Content-Type`
+* 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
+
+## [0.3.1] - 2023-10-10
+
+* fixed Minisky not working on Ruby 2.x
+
 ## [0.3.0] - 2023-10-05
 
 * authentication improvements & changes:

data/README.md

@@ -18,6 +18,32 @@ Or alternatively, add it to the `Gemfile` file for Bundler:
 
 ## Usage
 
+All calls to the XRPC API are made through an instance of the `Minisky` class. There are two ways to use the library: with or without authentication.
+
+
+### Unauthenticated access
+
+You can access parts of the API anonymously without any authentication. This currently includes: read-only `com.atproto.*` routes on the PDS (user's data server) and most read-only `app.bsky.*` routes on the AppView server.
+
+This allows you to do things like:
+
+- look up specific records or lists of all records of a given type in any account (in their raw form)
+- look up profile information about any account
+- load complete threads or users' profile feeds from the AppView
+
+To use Minisky this way, create a `Minisky` instance passing the API hostname string (at the moment there is only one server at `bsky.social`, but there will be more once federation support goes live) and `nil` as the configuration in the arguments:
+
+```rb
+require 'minisky'
+
+bsky = Minisky.new('bsky.social', nil)
+```
+
+
+### Authenticated access
+
+To use the complete API including posting or reading your home feed, you need to log in using your account info and get an access token which will be added as an authentication header to all requests.
+
 First, you need to create a `.yml` config file with the authentication data, e.g. `bluesky.yml`. It should look like this:
 
 ```yaml
@@ -29,18 +55,20 @@ The `id` can be either your handle, or your DID, or the email you've used to sig
 
 After you log in, this file will also be used to store your access & request tokens and DID. The data in the config file can be accessed through a `user` wrapper property that exposes them as methods, e.g. the password is available as `user.pass` and the DID as `user.did`.
 
-Next, create the Minisky client instance, passing the server name and the config file name (at the moment there is only one server at `bsky.social`, but there will be more once federation support goes live):
+Next, create the Minisky client instance, passing the server name and the config file name:
 
 ```rb
 require 'minisky'
 
 bsky = Minisky.new('bsky.social', 'bluesky.yml')
-bsky.check_access
 ```
 
-`check_access` will check if an access token is saved, if not - it will log you in using the login & password, otherwise it will check if the token is still valid and refresh it if needed.
+Minisky automatically manages your access and refresh tokens - it will first log you in using the login & password, and then use the refresh token to update the access token before the request when it expires.
+
 
-Now, you can make requests to the Bluesky API using `get_request` and `post_request`:
+### Making requests
+
+With a `Minisky` client instance, you can make requests to the Bluesky API using `get_request` and `post_request`:
 
 ```rb
 json = bsky.get_request('com.atproto.repo.listRecords', {
@@ -63,7 +91,7 @@ bsky.post_request('com.atproto.repo.createRecord', {
 })
 ```
 
-The requests use the saved access token for authentication automatically. You can also pass `auth: false` or `auth: nil` to not send any authentication headers, or `auth: sometoken` to use a specific other token.
+In authenticated mode, the requests use the saved access token for auth headers automatically. You can also pass `auth: false` or `auth: nil` to not send any authentication headers for a given request, or `auth: sometoken` to use a specific other token. In unauthenticated mode, sending of auth headers is disabled.
 
 The third useful method you can use is `#fetch_all`, which loads multiple paginated responses and collects all returned items on a single list (you need to pass the name of the field that contains the items in the response). Optionally, you can also specify a limit of pages to load as `max_pages: n`, or a break condition `break_when` to stop fetching when any item matches it. You can use it to e.g. to fetch all of your posts from the last 30 days, but not earlier:
 
@@ -97,9 +125,18 @@ You can find more examples in the [example](https://github.com/mackuba/minisky/t
 
 ## Customization
 
-The `Minisky` client currently supports one configuration option:
+The `Minisky` client currently supports such configuration options:
 
 - `default_progress` - a progress character to automatically use for `#fetch_all` calls (default: `nil`)
+- `send_auth_headers` - whether auth headers should be added by default (default: `true` in authenticated mode)
+- `auto_manage_tokens` - whether access tokens should be generated and refreshed automatically when needed (default: `true` in authenticated mode)
+
+In authenticated mode, you can disable the `send_auth_headers` option and then explicitly add `auth: true` to specific requests to include a header there.
+
+You can also disable the `auto_manage_tokens` option - in this case you will need to call the `#check_access` method before a request to refresh a token if needed, or alternatively, call either `#login` or `#perform_token_refresh`.
+
+
+### Using your own class
 
 Instead of using the `Minisky` class, you can also make your own class that includes the `Minisky::Requests` module and provides a different way to load & save the config, e.g. from a JSON file:
 
@@ -128,7 +165,6 @@ It can then be used just like the `Minisky` class:
 
 ```rb
 bsky = BlueskyClient.new('config/access.json')
-bsky.check_access
 bsky.get_request(...)
 ```
 

data/example/ask_password.rb

@@ -0,0 +1,76 @@
+#!/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_profile.rb

@@ -0,0 +1,53 @@
+#!/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/post_skeet.rb

@@ -21,13 +21,15 @@ 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,
-    langs: ["en"],
-    createdAt: Time.now.iso8601
+    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
   }
 })
 

data/example/science_feed.rb

@@ -4,6 +4,7 @@
 # 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__))

data/lib/minisky/minisky.rb

@@ -3,7 +3,7 @@ require 'yaml'
 class Minisky
   attr_reader :host, :config
 
-  def initialize(host, config_file)
+  def initialize(host, config_file, options = {})
     @host = host
     @config_file = config_file
 
@@ -18,6 +18,12 @@ class Minisky
       @send_auth_headers = false
       @auto_manage_tokens = false
     end
+
+    if options
+      options.each do |k, v|
+        self.send("#{k}=", v)
+      end
+    end
   end
 
   def save_config

data/lib/minisky/requests.rb

@@ -39,6 +39,9 @@ class Minisky
       instance_variable_defined?('@auto_manage_tokens') ? @auto_manage_tokens : true
     end
 
+    alias progress default_progress
+    alias progress= default_progress=
+
     def base_url
       @base_url ||= "https://#{host}/xrpc"
     end
@@ -47,32 +50,40 @@ class Minisky
       @user ||= User.new(config)
     end
 
-    def get_request(method, params = nil, auth: default_auth_mode)
+    def get_request(method, params = nil, auth: default_auth_mode, headers: nil)
       check_access if auto_manage_tokens && auth == true
 
-      headers = authentication_header(auth)
+      headers = authentication_header(auth).merge(headers || {})
       url = URI("#{base_url}/#{method}")
 
       if params && !params.empty?
         url.query = URI.encode_www_form(params)
       end
 
-      response = Net::HTTP.get_response(url, headers)
+      request = Net::HTTP::Get.new(url, headers)
+
+      response = make_request(request)
       handle_response(response)
     end
 
-    def post_request(method, params = nil, auth: default_auth_mode)
+    def post_request(method, params = nil, auth: default_auth_mode, headers: nil)
       check_access if auto_manage_tokens && auth == true
 
-      headers = authentication_header(auth).merge({ "Content-Type" => "application/json" })
-      body = params ? params.to_json : ''
+      headers = authentication_header(auth).merge(headers || {})
+      headers["Content-Type"] = "application/json" unless headers.keys.any? { |k| k.to_s.downcase == 'content-type' }
+
+      body = if params.is_a?(String) || params.nil?
+        params.to_s
+      else
+        params.to_json
+      end
 
       response = Net::HTTP.post(URI("#{base_url}/#{method}"), body, headers)
       handle_response(response)
     end
 
     def fetch_all(method, params = nil, field:,
-                  auth: default_auth_mode, break_when: nil, max_pages: nil, progress: @default_progress)
+                  auth: default_auth_mode, break_when: nil, max_pages: nil, headers: nil, progress: @default_progress)
       data = []
       params = {} if params.nil?
       pages = 0
@@ -80,7 +91,7 @@ class Minisky
       loop do
         print(progress) if progress
 
-        response = get_request(method, params, auth: auth)
+        response = get_request(method, params, auth: auth, headers: headers)
         records = response[field]
         cursor = response['cursor']
 
@@ -145,8 +156,32 @@ class Minisky
       nil
     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
+    end
+
+
     private
 
+    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|
+        http.request(request)
+      end
+    end
+
     def default_auth_mode
       !!send_auth_headers
     end
@@ -184,16 +219,15 @@ class Minisky
     def handle_response(response)
       status = response.code.to_i
       message = response.message
+      response_body = (response.content_type == 'application/json') ? JSON.parse(response.body) : response.body
 
       case response
       when Net::HTTPSuccess
-        JSON.parse(response.body)
+        response_body
       when Net::HTTPRedirection
         raise UnexpectedRedirect.new(status, message, response['location'])
       else
-        data = (response.content_type == 'application/json') ? JSON.parse(response.body) : response.body
-
-        error_class = if data.is_a?(Hash) && data['error'] == 'ExpiredToken'
+        error_class = if response_body.is_a?(Hash) && response_body['error'] == 'ExpiredToken'
           ExpiredTokenError
         elsif response.is_a?(Net::HTTPClientError)
           ClientErrorResponse
@@ -203,7 +237,7 @@ class Minisky
           BadResponse
         end
 
-        raise error_class.new(status, message, data)
+        raise error_class.new(status, message, response_body)
       end
     end
   end

data/lib/minisky/version.rb

@@ -1,5 +1,5 @@
 require_relative 'minisky'
 
 class Minisky
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: minisky
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kuba Suder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-05 00:00:00.000000000 Z
-dependencies: []
+date: 2024-03-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 description: A very simple client class that lets you log in to the Bluesky API and
   make any requests there.
 email:
@@ -21,7 +35,9 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- example/ask_password.rb
 - example/fetch_my_posts.rb
+- example/fetch_profile.rb
 - example/post_skeet.rb
 - example/science_feed.rb
 - lib/minisky.rb