minisky 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50342531fa0d4bf18c527038f4644ad15bcbddc7b2468d5d9c9ff7985972f0ce
-  data.tar.gz: 0de2603028edb2a51c43e2b3e80f25dca6099f4e48ce7cdbf9be98c447d2e289
+  metadata.gz: 8f4836f5b8d8de9c5f9af0368144fe60f274e1b61176d1c919b70d3fd645a3f3
+  data.tar.gz: 8c87cdbb362b19651e848804aa6c551c88abc759bbdd3df6e609b62b94a7da4b
 SHA512:
-  metadata.gz: 2f434becc1505afd47243f3c6f0ad397fd75e2548e606117980cec20a70215f8dbea3d4bcd8c8520dc4ad2733bfc42187b7fe20344fda5dfc7722e73e97980eb
-  data.tar.gz: 3ce2d7f864b6aea377ca518c78d8b7d1fcbe3ff04fe36a6462b005cacc5a56d0b76271412a395727891489695766e452e5bb89bc444a0ca713a163c859a0dc7d
+  metadata.gz: 84052665f10f23db1513a5135dcb9032f0fbc4c5ae55fc7bbeb15e26d85904acda3ac55170e58d8901e5549ceaaafa34aa038ec8987da9dfdded5349080f12d2
+  data.tar.gz: 5557b97bb51b8feb757a2d16dccfefd7dfd31655a833b379681d89cc924717e234baa19523cda89368f6610481cf11c0dd9494355539d4c7364c9913a05c2ca1

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## [0.3.0] - 2023-10-05
+
+* 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 `reset_tokens` helper method
+* 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
+
 ## [0.2.0] - 2023-09-02
 
 * more consistent handling of parameters in the main methods:

data/README.md

@@ -13,12 +13,12 @@ To install the Minisky gem, run the command:
 
 Or alternatively, add it to the `Gemfile` file for Bundler:
 
-    gem 'minisky', '~> 0.2'
+    gem 'minisky', '~> 0.3'
 
 
 ## Usage
 
-First, you need to create a `.yml` config file (by default, `bluesky.yml`) with the authentication data. It should look like this:
+First, you need to create a `.yml` config file with the authentication data, e.g. `bluesky.yml`. It should look like this:
 
 ```yaml
 id: my.bsky.username
@@ -29,12 +29,12 @@ 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 (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 (at the moment there is only one server at `bsky.social`, but there will be more once federation support goes live):
 
 ```rb
 require 'minisky'
 
-bsky = Minisky.new('bsky.social')
+bsky = Minisky.new('bsky.social', 'bluesky.yml')
 bsky.check_access
 ```
 
@@ -43,17 +43,22 @@ bsky.check_access
 Now, you can make requests to the Bluesky API using `get_request` and `post_request`:
 
 ```rb
-bsky.get_request('com.atproto.repo.listRecords', {
+json = bsky.get_request('com.atproto.repo.listRecords', {
   repo: bsky.user.did,
   collection: 'app.bsky.feed.like'
 })
 
+json['records'].each do |r|
+  puts r['value']['subject']['uri']
+end
+
 bsky.post_request('com.atproto.repo.createRecord', {
   repo: bsky.user.did,
   collection: 'app.bsky.feed.post',
   record: {
     text: "Hello world!",
-    createdAt: Time.now.iso8601
+    createdAt: Time.now.iso8601,
+    langs: ["en"]
   }
 })
 ```
@@ -65,7 +70,7 @@ The third useful method you can use is `#fetch_all`, which loads multiple pagina
 ```rb
 time_limit = Time.now - 86400 * 30
 
-bsky.fetch_all('com.atproto.repo.listRecords',
+posts = bsky.fetch_all('com.atproto.repo.listRecords',
   { repo: bsky.user.did, collection: 'app.bsky.feed.post' },
   field: 'records',
   max_pages: 10,
@@ -75,7 +80,7 @@ bsky.fetch_all('com.atproto.repo.listRecords',
 There is also a `progress` option you can use to print some kind of character for every page load. E.g. pass `progress: '.'` to print dots as the pages are loading:
 
 ```rb
-bsky.fetch_all('com.atproto.repo.listRecords',
+likes = bsky.fetch_all('com.atproto.repo.listRecords',
   { repo: bsky.user.did, collection: 'app.bsky.feed.like' },
   field: 'records',
   progress: '.')
@@ -87,19 +92,16 @@ This will output a line like this:
 .................
 ```
 
+You can find more examples in the [example](https://github.com/mackuba/minisky/tree/master/example) directory.
+
+
 ## Customization
 
 The `Minisky` client currently supports one configuration option:
 
 - `default_progress` - a progress character to automatically use for `#fetch_all` calls (default: `nil`)
 
-When creating the `Minisky` instance, you can pass a name of the YAML config file to use instead of the default:
-
-```rb
-bsky = Minisky.new('bsky.social', 'config/access.yml')
-```
-
-Alternatively, instead of using the `Minisky` class, you can 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:
+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:
 
 ```rb
 class BlueskyClient

data/example/fetch_my_posts.rb

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

@@ -0,0 +1,34 @@
+#!/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'))
+
+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
+  }
+})
+
+puts "Posted ✓"

data/example/science_feed.rb

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

data/lib/minisky/errors.rb

@@ -0,0 +1,55 @@
+require_relative 'minisky'
+
+class Minisky
+  class Error < StandardError
+  end
+
+  class AuthError < Error
+    def initialize(message)
+      super(message)
+    end
+  end
+
+  class BadResponse < Error
+    attr_reader :status, :data
+
+    def initialize(status, status_message, data)
+      @status = status
+      @data = data
+
+      message = if error_message
+        "#{status} #{status_message}: #{error_message}"
+      else
+        "#{status} #{status_message}"
+      end
+
+      super(message)
+    end
+
+    def error_type
+      @data['error'] if @data.is_a?(Hash)
+    end
+
+    def error_message
+      @data['message'] if @data.is_a?(Hash)
+    end
+  end
+
+  class ClientErrorResponse < BadResponse
+  end
+
+  class ServerErrorResponse < BadResponse
+  end
+
+  class ExpiredTokenError < ClientErrorResponse
+  end
+
+  class UnexpectedRedirect < BadResponse
+    attr_reader :location
+
+    def initialize(status, status_message, location)
+      super(status, status_message, { 'message' => "Unexpected redirect: #{location}" })
+      @location = location
+    end
+  end
+end

data/lib/minisky/minisky.rb

@@ -1,18 +1,27 @@
 require 'yaml'
 
 class Minisky
-  DEFAULT_CONFIG_FILE = 'bluesky.yml'
-
   attr_reader :host, :config
 
-  def initialize(host, config_file = DEFAULT_CONFIG_FILE)
+  def initialize(host, config_file)
     @host = host
     @config_file = config_file
-    @config = YAML.load(File.read(@config_file))
+
+    if @config_file
+      @config = YAML.load(File.read(@config_file))
+
+      if user.id.nil? || user.pass.nil?
+        raise AuthError, "Missing user id or password in the config file #{@config_file}"
+      end
+    else
+      @config = {}
+      @send_auth_headers = false
+      @auto_manage_tokens = false
+    end
   end
 
   def save_config
-    File.write(@config_file, YAML.dump(@config))
+    File.write(@config_file, YAML.dump(@config)) if @config_file
   end
 end
 

data/lib/minisky/requests.rb

@@ -1,8 +1,10 @@
 require_relative 'minisky'
+require_relative 'errors'
 
+require 'base64'
 require 'json'
 require 'net/http'
-require 'open-uri'
+require 'time'
 require 'uri'
 
 class Minisky
@@ -15,13 +17,27 @@ class Minisky
       !!(access_token && refresh_token)
     end
 
-    def method_missing(name)
-      @config[name.to_s]
+    def method_missing(name, *args)
+      if name.end_with?('=')
+        @config[name.to_s.chop] = args[0]
+      else
+        @config[name.to_s]
+      end
     end
   end
 
   module Requests
     attr_accessor :default_progress
+    attr_writer :send_auth_headers
+    attr_writer :auto_manage_tokens
+
+    def send_auth_headers
+      instance_variable_defined?('@send_auth_headers') ? @send_auth_headers : true
+    end
+
+    def auto_manage_tokens
+      instance_variable_defined?('@auto_manage_tokens') ? @auto_manage_tokens : true
+    end
 
     def base_url
       @base_url ||= "https://#{host}/xrpc"
@@ -31,7 +47,9 @@ class Minisky
       @user ||= User.new(config)
     end
 
-    def get_request(method, params = nil, auth: true)
+    def get_request(method, params = nil, auth: default_auth_mode)
+      check_access if auto_manage_tokens && auth == true
+
       headers = authentication_header(auth)
       url = URI("#{base_url}/#{method}")
 
@@ -39,21 +57,22 @@ class Minisky
         url.query = URI.encode_www_form(params)
       end
 
-      JSON.parse(URI.open(url, headers).read)
+      response = Net::HTTP.get_response(url, headers)
+      handle_response(response)
     end
 
-    def post_request(method, params = nil, auth: true)
+    def post_request(method, params = nil, auth: default_auth_mode)
+      check_access if auto_manage_tokens && auth == true
+
       headers = authentication_header(auth).merge({ "Content-Type" => "application/json" })
       body = params ? params.to_json : ''
 
       response = Net::HTTP.post(URI("#{base_url}/#{method}"), body, headers)
-      raise "Invalid response: #{response.code} #{response.body}" if response.code.to_i / 100 != 2
-
-      JSON.parse(response.body)
+      handle_response(response)
     end
 
     def fetch_all(method, params = nil, field:,
-                  auth: true, break_when: nil, max_pages: nil, progress: @default_progress)
+                  auth: default_auth_mode, break_when: nil, max_pages: nil, progress: @default_progress)
       data = []
       params = {} if params.nil?
       pages = 0
@@ -80,16 +99,16 @@ class Minisky
     def check_access
       if !user.logged_in?
         log_in
-      else
-        begin
-          get_request('com.atproto.server.getSession')
-        rescue OpenURI::HTTPError
-          perform_token_refresh
-        end
+      elsif token_expiration_date(user.access_token) < Time.now + 60
+        perform_token_refresh
       end
     end
 
     def log_in
+      if user.id.nil? || user.pass.nil?
+        raise AuthError, "To log in, please provide a user id and password"
+      end
+
       data = {
         identifier: user.id,
         password: user.pass
@@ -97,35 +116,96 @@ class Minisky
 
       json = post_request('com.atproto.server.createSession', data, auth: false)
 
-      config['did'] = json['did']
-      config['access_token'] = json['accessJwt']
-      config['refresh_token'] = json['refreshJwt']
+      user.did = json['did']
+      user.access_token = json['accessJwt']
+      user.refresh_token = json['refreshJwt']
 
       save_config
       json
     end
 
     def perform_token_refresh
+      if user.refresh_token.nil?
+        raise AuthError, "Can't refresh access token - refresh token is missing"
+      end
+
       json = post_request('com.atproto.server.refreshSession', auth: user.refresh_token)
 
-      config['access_token'] = json['accessJwt']
-      config['refresh_token'] = json['refreshJwt']
+      user.access_token = json['accessJwt']
+      user.refresh_token = json['refreshJwt']
 
       save_config
       json
     end
 
+    def reset_tokens
+      user.access_token = nil
+      user.refresh_token = nil
+      save_config
+      nil
+    end
+
     private
 
+    def default_auth_mode
+      !!send_auth_headers
+    end
+
     def authentication_header(auth)
       if auth.is_a?(String)
         { 'Authorization' => "Bearer #{auth}" }
       elsif auth
-        { 'Authorization' => "Bearer #{user.access_token}" }
+        if user.access_token
+          { 'Authorization' => "Bearer #{user.access_token}" }
+        else
+          raise AuthError, "Can't send auth headers, access token is missing"
+        end
       else
         {}
       end
     end
+
+    def token_expiration_date(token)
+      parts = token.split('.')
+      raise AuthError, "Invalid access token format" unless parts.length == 3
+
+      begin
+        payload = JSON.parse(Base64.decode64(parts[1]))
+      rescue JSON::ParserError
+        raise AuthError, "Couldn't decode payload from access token"
+      end
+
+      exp = payload['exp']
+      raise AuthError, "Invalid token expiry data" unless exp.is_a?(Numeric) && exp > 0
+
+      Time.at(exp)
+    end
+
+    def handle_response(response)
+      status = response.code.to_i
+      message = response.message
+
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(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'
+          ExpiredTokenError
+        elsif response.is_a?(Net::HTTPClientError)
+          ClientErrorResponse
+        elsif response.is_a?(Net::HTTPServerError)
+          ServerErrorResponse
+        else
+          BadResponse
+        end
+
+        raise error_class.new(status, message, data)
+      end
+    end
   end
 
   include Requests

data/lib/minisky/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minisky
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kuba Suder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-02 00:00:00.000000000 Z
+date: 2023-10-05 00:00:00.000000000 Z
 dependencies: []
 description: A very simple client class that lets you log in to the Bluesky API and
   make any requests there.
@@ -21,7 +21,11 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- example/fetch_my_posts.rb
+- example/post_skeet.rb
+- example/science_feed.rb
 - lib/minisky.rb
+- lib/minisky/errors.rb
 - lib/minisky/minisky.rb
 - lib/minisky/requests.rb
 - lib/minisky/version.rb