minisky 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f4836f5b8d8de9c5f9af0368144fe60f274e1b61176d1c919b70d3fd645a3f3
-  data.tar.gz: 8c87cdbb362b19651e848804aa6c551c88abc759bbdd3df6e609b62b94a7da4b
+  metadata.gz: 7a753ae5a6f7d2dd3089ee9b6a637e578051261c615fedd28a44f63ac1774b4d
+  data.tar.gz: 479240c065cb3ba705aa4a9d07efa8c4904ec2aca2e6ed0e847d391ab8cd62fe
 SHA512:
-  metadata.gz: 84052665f10f23db1513a5135dcb9032f0fbc4c5ae55fc7bbeb15e26d85904acda3ac55170e58d8901e5549ceaaafa34aa038ec8987da9dfdded5349080f12d2
-  data.tar.gz: 5557b97bb51b8feb757a2d16dccfefd7dfd31655a833b379681d89cc924717e234baa19523cda89368f6610481cf11c0dd9494355539d4c7364c9913a05c2ca1
+  metadata.gz: f87814325757d1b19cee4e403d6e13afbf84b1353b932eedbce23faa6cb1abfe772d0cf2c459b21bb45ea08fa34173457dea3fdb266f32f1f4334e2e90d22692
+  data.tar.gz: c4bea17a09982db0462e15e092fdf43c454fd94163d04099b119104fde555387621c5c1b8d51e1a1247ad2cece0b5fd9258b1c98555b0ffb7eca4b96107dd83a

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [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/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/requests.rb

@@ -57,7 +57,9 @@ class Minisky
         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
 
@@ -145,8 +147,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, **kwargs)
+        params ||= kwargs unless kwargs.empty?
+        do_get_request(method, params, auth: auth)
+      end
+
+      def post_request(method, params = nil, auth: default_auth_mode, **kwargs)
+        params ||= kwargs unless kwargs.empty?
+        do_post_request(method, params, auth: auth)
+      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

data/lib/minisky/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: minisky
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Kuba Suder
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-05 00:00:00.000000000 Z
+date: 2023-10-10 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.
@@ -22,6 +22,7 @@ files:
 - LICENSE.txt
 - README.md
 - example/fetch_my_posts.rb
+- example/fetch_profile.rb
 - example/post_skeet.rb
 - example/science_feed.rb
 - lib/minisky.rb