minisky 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afde2461017bd9cc0127a64921329a07f884377d5e434dd9b81f15e42493f5b2
-  data.tar.gz: 29c86293b904fa973cdc2c2a74e17a7f8096ac02c97377d39c9daef9a1cdc194
+  metadata.gz: 50342531fa0d4bf18c527038f4644ad15bcbddc7b2468d5d9c9ff7985972f0ce
+  data.tar.gz: 0de2603028edb2a51c43e2b3e80f25dca6099f4e48ce7cdbf9be98c447d2e289
 SHA512:
-  metadata.gz: 23f5239dddeed66c6ad1a4195d53adea8d7b35d8dbc2a0680d39351a7ca9b5aeb42ef8ccdb38d4d2cd589406e93cc90ae9b5cea9f3ad4f91d3586e3b3e7fc85f
-  data.tar.gz: fdfce69b885db91ca2efbe19a92cdfc2e11e7fd5ac363be71e47f1e7c4186ba160f9dd2f99ae55950f3404b33a5a72014e3f14e917ceb76cbca7657cce09ddf6
+  metadata.gz: 2f434becc1505afd47243f3c6f0ad397fd75e2548e606117980cec20a70215f8dbea3d4bcd8c8520dc4ad2733bfc42187b7fe20344fda5dfc7722e73e97980eb
+  data.tar.gz: 3ce2d7f864b6aea377ca518c78d8b7d1fcbe3ff04fe36a6462b005cacc5a56d0b76271412a395727891489695766e452e5bb89bc444a0ca713a163c859a0dc7d

data/CHANGELOG.md

@@ -1 +1,31 @@
-## [Unreleased]
+## [0.2.0] - 2023-09-02
+
+* more consistent handling of parameters in the main methods:
+  - `auth` is now a named parameter
+  - access token is used by default, pass `nil` or an explicit token as `auth` to override
+  - `params` is always optional
+* progress dots in `#fetch_all`:
+  - default is now to not print anything
+  - pass `'.'` or any other character/string to show progress
+  - set `default_progress` on the client object to use for all `#fetch_all` calls
+* added `max_pages` option to `#fetch_all`
+* `#login` and `#perform_token_refresh` methods use the JSON response as return value
+* 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
+- added `#check_access` method
+- hostname is now passed as a parameter
+- config file name can be passed as a parameter
+- added tests
+
+## [0.0.1] - 2023-08-30
+
+Initial release - extracted from original gist:
+
+- logging in and refreshing the token
+- making GET & POST requests
+- fetching paginated responses

data/README.md

@@ -1,31 +1,146 @@
 # Minisky
 
-TODO: Delete this and the text below, and describe your gem
+Minisky is a minimal client of the Bluesky (ATProto) API. It provides a simple API client class that you can use to log in to the Bluesky API and make any GET and POST requests there. It's meant to be an easy way to start playing and experimenting with the AT Protocol API.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/minisky`. To experiment with that code, run `bin/console` for an interactive prompt.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+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.
 
-Install the gem and add to the application's Gemfile by executing:
+To install the Minisky gem, run the command:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+    [sudo] gem install minisky
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or alternatively, add it to the `Gemfile` file for Bundler:
+
+    gem 'minisky', '~> 0.2'
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
 
 ## Usage
 
-TODO: Write usage instructions here
+First, you need to create a `.yml` config file (by default, `bluesky.yml`) with the authentication data. It should look like this:
+
+```yaml
+id: my.bsky.username
+pass: very-secret-password
+```
+
+The `id` can be either your handle, or your DID, or the email you've used to sign up. It's recommended that you use the "app password" that you can create in the settings instead of your main account password.
+
+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):
+
+```rb
+require 'minisky'
+
+bsky = Minisky.new('bsky.social')
+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.
+
+Now, you can make requests to the Bluesky API using `get_request` and `post_request`:
+
+```rb
+bsky.get_request('com.atproto.repo.listRecords', {
+  repo: bsky.user.did,
+  collection: 'app.bsky.feed.like'
+})
+
+bsky.post_request('com.atproto.repo.createRecord', {
+  repo: bsky.user.did,
+  collection: 'app.bsky.feed.post',
+  record: {
+    text: "Hello world!",
+    createdAt: Time.now.iso8601
+  }
+})
+```
+
+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.
+
+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:
+
+```rb
+time_limit = Time.now - 86400 * 30
+
+bsky.fetch_all('com.atproto.repo.listRecords',
+  { repo: bsky.user.did, collection: 'app.bsky.feed.post' },
+  field: 'records',
+  max_pages: 10,
+  break_when: ->(x) { Time.parse(x['value']['createdAt']) < time_limit })
+```
+
+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',
+  { repo: bsky.user.did, collection: 'app.bsky.feed.like' },
+  field: 'records',
+  progress: '.')
+```
+
+This will output a line like this:
+
+```
+.................
+```
+
+## 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:
+
+```rb
+class BlueskyClient
+  include Minisky::Requests
+
+  attr_reader :config
+
+  def initialize(config_file)
+    @config_file = config_file
+    @config = JSON.parse(File.read(@config_file))
+  end
+
+  def host
+    'bsky.social'
+  end
+
+  def save_config
+    File.write(@config_file, JSON.pretty_generate(@config))
+  end
+end
+```
+
+It can then be used just like the `Minisky` class:
+
+```rb
+bsky = BlueskyClient.new('config/access.json')
+bsky.check_access
+bsky.get_request(...)
+```
+
+The class needs to provide:
+
+- a `host` method or property that returns the hostname of the server
+- a `config` property which returns a hash or a hash-like object with the configuration and user data - it needs to support reading and writing arbitrary key-value pairs with string keys
+- a `save_config` method which persists the config object to the chosen storage
 
-## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+## Credits
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Copyright © 2023 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
 
-## Contributing
+The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/minisky.
+Bug reports and pull requests are welcome 😎

data/lib/minisky/minisky.rb

@@ -1,102 +1,19 @@
-require 'json'
-require 'net/http'
-require 'open-uri'
 require 'yaml'
 
 class Minisky
-  CONFIG_FILE = 'bluesky.yml'
+  DEFAULT_CONFIG_FILE = 'bluesky.yml'
 
-  def initialize
-    @config = YAML.load(File.read(CONFIG_FILE))
-    @base_url = "https://#{@config['host']}/xrpc"
-  end
-
-  def my_id
-    @config['ident']
-  end
-
-  def my_did
-    @config['did']
-  end
-
-  def access_token
-    @config['access_token']
-  end
+  attr_reader :host, :config
 
-  def refresh_token
-    @config['refresh_token']
+  def initialize(host, config_file = DEFAULT_CONFIG_FILE)
+    @host = host
+    @config_file = config_file
+    @config = YAML.load(File.read(@config_file))
   end
 
   def save_config
-    File.write(CONFIG_FILE, YAML.dump(@config))
-  end
-
-  def log_in
-    json = post_request('com.atproto.server.createSession', {
-      identifier: @config['ident'],
-      password: @config['pass']
-    })
-
-    @config['did'] = json['did']
-    @config['access_token'] = json['accessJwt']
-    @config['refresh_token'] = json['refreshJwt']
-    save_config
-  end
-
-  def perform_token_refresh
-    json = post_request('com.atproto.server.refreshSession', nil, refresh_token)
-    @config['access_token'] = json['accessJwt']
-    @config['refresh_token'] = json['refreshJwt']
-    save_config
-  end
-
-  def fetch_all(method, params, auth = nil, field:, break_when: ->(x) { false }, progress: true)
-    data = []
-
-    loop do
-      print '.' if progress
-
-      response = get_request(method, params, auth)
-      records = response[field]
-      cursor = response['cursor']
-
-      data.concat(records)
-      params[:cursor] = cursor
-
-      break if cursor.nil? || records.empty? || records.any? { |x| break_when.call(x) }
-    end
-
-    data.reject { |x| break_when.call(x) }
-  end
-
-  def get_request(method, params = nil, auth = nil)
-    headers = {}
-    headers['Authorization'] = "Bearer #{auth}" if auth
-
-    url = "#{@base_url}/#{method}"
-
-    if params && !params.empty?
-      url += "?" + params.map { |k, v|
-        if v.is_a?(Array)
-          v.map { |x| "#{k}=#{x}" }.join('&')
-        else
-          "#{k}=#{v}"
-        end
-      }.join('&')
-    end
-
-    JSON.parse(URI.open(url, headers).read)
-  end
-
-  def post_request(method, params, auth = nil)
-    headers = { "Content-Type" => "application/json" }
-    headers['Authorization'] = "Bearer #{auth}" if auth
-
-    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)
+    File.write(@config_file, YAML.dump(@config))
   end
 end
+
+require_relative 'requests'

data/lib/minisky/requests.rb

@@ -0,0 +1,132 @@
+require_relative 'minisky'
+
+require 'json'
+require 'net/http'
+require 'open-uri'
+require 'uri'
+
+class Minisky
+  class User
+    def initialize(config)
+      @config = config
+    end
+
+    def logged_in?
+      !!(access_token && refresh_token)
+    end
+
+    def method_missing(name)
+      @config[name.to_s]
+    end
+  end
+
+  module Requests
+    attr_accessor :default_progress
+
+    def base_url
+      @base_url ||= "https://#{host}/xrpc"
+    end
+
+    def user
+      @user ||= User.new(config)
+    end
+
+    def get_request(method, params = nil, auth: true)
+      headers = authentication_header(auth)
+      url = URI("#{base_url}/#{method}")
+
+      if params && !params.empty?
+        url.query = URI.encode_www_form(params)
+      end
+
+      JSON.parse(URI.open(url, headers).read)
+    end
+
+    def post_request(method, params = nil, 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)
+    end
+
+    def fetch_all(method, params = nil, field:,
+                  auth: true, break_when: nil, max_pages: nil, progress: @default_progress)
+      data = []
+      params = {} if params.nil?
+      pages = 0
+
+      loop do
+        print(progress) if progress
+
+        response = get_request(method, params, auth: auth)
+        records = response[field]
+        cursor = response['cursor']
+
+        data.concat(records)
+        params[:cursor] = cursor
+        pages += 1
+
+        break if !cursor || records.empty? || pages == max_pages
+        break if break_when && records.any? { |x| break_when.call(x) }
+      end
+
+      data.delete_if { |x| break_when.call(x) } if break_when
+      data
+    end
+
+    def check_access
+      if !user.logged_in?
+        log_in
+      else
+        begin
+          get_request('com.atproto.server.getSession')
+        rescue OpenURI::HTTPError
+          perform_token_refresh
+        end
+      end
+    end
+
+    def log_in
+      data = {
+        identifier: user.id,
+        password: user.pass
+      }
+
+      json = post_request('com.atproto.server.createSession', data, auth: false)
+
+      config['did'] = json['did']
+      config['access_token'] = json['accessJwt']
+      config['refresh_token'] = json['refreshJwt']
+
+      save_config
+      json
+    end
+
+    def perform_token_refresh
+      json = post_request('com.atproto.server.refreshSession', auth: user.refresh_token)
+
+      config['access_token'] = json['accessJwt']
+      config['refresh_token'] = json['refreshJwt']
+
+      save_config
+      json
+    end
+
+    private
+
+    def authentication_header(auth)
+      if auth.is_a?(String)
+        { 'Authorization' => "Bearer #{auth}" }
+      elsif auth
+        { 'Authorization' => "Bearer #{user.access_token}" }
+      else
+        {}
+      end
+    end
+  end
+
+  include Requests
+end

data/lib/minisky/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minisky
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Kuba Suder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-30 00:00:00.000000000 Z
+date: 2023-09-02 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.
@@ -23,6 +23,7 @@ files:
 - README.md
 - lib/minisky.rb
 - lib/minisky/minisky.rb
+- lib/minisky/requests.rb
 - lib/minisky/version.rb
 - sig/minisky.rbs
 homepage: https://github.com/mackuba/minisky