Merge pull request #13 from joshbeckman/feature/readwise-api-v3

new(usr): Add first pass at Readwise API V3 (support for Reader)

Author: joshbeckman

README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://badge.fury.io/rb/readwise.svg)](https://badge.fury.io/rb/readwise) [![Ruby](https://github.com/joshbeckman/readwise-ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/joshbeckman/readwise-ruby/actions/workflows/ruby.yml)
 
-[Readwise](https://readwise.io/) is an application suite to store, revisit, and learn from your book and article highlights. This is a basic library to call the [Readwise API](https://readwise.io/api_deets) to read and write highlights.
+[Readwise](https://readwise.io/) is an application suite to store, revisit, and learn from your book and article highlights. This is a basic library to call the [Readwise API](https://readwise.io/api_deets) to read and write highlights, and manage Reader documents through the [Reader API](https://readwise.io/reader_api).
 
 This library is not at 100% coverage of the API, so if you need a method that is missing, open an issue or contribute changes!
 
@@ -26,6 +26,10 @@ Or install it yourself as:
 
 First, obtain an API access token from https://readwise.io/access_token.
 
+### Highlights API (V2)
+
+The [V2 API](https://readwise.io/api_deets) provides access to your highlights and books:
+
 ```ruby
 client = Readwise::Client.new(token: token)
 
@@ -56,6 +60,80 @@ updated_tag = client.update_highlight_tag(highlight: highlight, tag: added_tag)
 client.remove_highlight_tag(highlight: highlight, tag: added_tag)
 ```
 
+### Reader API (V3)
+
+The [V3 API](https://readwise.io/reader_api) provides access to Readwise Reader functionality for managing documents (articles, PDFs, etc.):
+
+```ruby
+# Get all documents
+documents = client.get_documents
+
+# Get documents with filters
+documents = client.get_documents(
+  updated_after: '2023-01-01T00:00:00Z',
+  location: 'new',        # 'new', 'later', 'archive', or 'feed'
+  category: 'article'     # 'article', 'email', 'rss', 'highlight', 'note', 'pdf', 'epub', 'tweet', 'video'
+)
+
+# Get a specific document
+document = client.get_document(document_id: '123456')
+
+puts document.title
+puts document.author
+puts document.url
+puts document.reading_progress
+puts document.location
+puts document.category
+
+# Check document properties
+puts document.read?                    # reading progress >= 85%
+puts document.read?(threshold: 0.5)    # custom threshold
+puts document.parent?                  # is this a top-level document?
+puts document.child?                   # is this a highlight/note of another document?
+
+# Check location
+puts document.in_new?
+puts document.in_later?  
+puts document.in_archive?
+
+# Check category
+puts document.article?
+puts document.pdf?
+puts document.epub?
+puts document.tweet?
+puts document.video?
+puts document.book?
+puts document.email?
+puts document.rss?
+puts document.highlight?
+puts document.note?
+
+# Access timestamps
+puts document.created_at_time
+puts document.updated_at_time
+puts document.published_date_time
+
+# Create a new document
+document_create = Readwise::DocumentCreate.new(
+  url: 'https://example.com/article',
+  title: 'My Article',
+  author: 'John Doe',
+  html: '<p>Article content</p>',
+  summary: 'A brief summary',
+  location: 'new',           # 'new', 'later', 'archive', or 'feed'
+  category: 'article',       # 'article', 'email', 'rss', etc.
+  tags: ['technology', 'programming'],
+  notes: 'My personal notes',
+  should_clean_html: true,
+  saved_using: 'api'
+)
+
+document = client.create_document(document: document_create)
+
+# Create multiple documents
+documents = client.create_documents(documents: [document_create1, document_create2])
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

lib/readwise.rb

@@ -1,5 +1,5 @@
-require 'readwise/version'
-require 'readwise/client'
+require_relative 'readwise/version'
+require_relative 'readwise/client'
 
 module Readwise
   class Error < StandardError; end

lib/readwise/client.rb

@@ -3,19 +3,58 @@
 require_relative 'book'
 require_relative 'highlight'
 require_relative 'tag'
+require_relative 'document'
 
 module Readwise
   class Client
     class Error < StandardError; end
 
     BASE_URL = "https://readwise.io/api/v2/"
+    V3_BASE_URL = "https://readwise.io/api/v3/"
 
     def initialize(token: nil)
       raise ArgumentError unless token
 
       @token = token.to_s
     end
 
+    def create_document(document:)
+      raise ArgumentError unless document.is_a?(Readwise::DocumentCreate)
+
+      url = V3_BASE_URL + 'save/'
+
+      res = post_readwise_request(url, payload: document.serialize)
+      get_document(document_id: res['id'])
+    end
+
+    def create_documents(documents: [])
+      return [] unless documents.any?
+
+      documents.map do |document|
+        create_document(document: document)
+      end
+    end
+
+    def get_document(document_id:)
+      url = V3_BASE_URL + "list?id=#{document_id}"
+
+      res = get_readwise_request(url)
+
+      res['results'].map { |item| transform_document(item) }.first
+    end
+
+    def get_documents(updated_after: nil, location: nil, category: nil)
+      resp = documents_page(updated_after: updated_after, location: location, category: category)
+      next_page_cursor = resp[:next_page_cursor]
+      results = resp[:results]
+      while next_page_cursor
+        resp = documents_page(updated_after: updated_after, location: location, category: category, page_cursor: next_page_cursor)
+        results.concat(resp[:results])
+        next_page_cursor = resp[:next_page_cursor]
+      end
+      results.sort_by(&:created_at)
+    end
+
     def create_highlight(highlight:)
       create_highlights(highlights: [highlight]).first
     end
@@ -101,6 +140,28 @@ def export(updated_after: nil, book_ids: [])
 
     private
 
+    def documents_page(page_cursor: nil, updated_after:, location:, category:)
+      parsed_body = get_documents_page(page_cursor: page_cursor, updated_after: updated_after, location: location, category: category)
+      results = parsed_body.dig('results').map do |item|
+        transform_document(item)
+      end
+      {
+        results: results,
+        next_page_cursor: parsed_body.dig('nextPageCursor')
+      }
+    end
+
+    def get_documents_page(page_cursor: nil, updated_after:, location:, category:)
+      params = {}
+      params['updatedAfter'] = updated_after if updated_after
+      params['location'] = location if location
+      params['category'] = category if category
+      params['pageCursor'] = page_cursor if page_cursor
+      url = V3_BASE_URL + 'list/?' + URI.encode_www_form(params)
+
+      get_readwise_request(url)
+    end
+
     def export_page(page_cursor: nil, updated_after: nil, book_ids: [])
       parsed_body = get_export_page(page_cursor: page_cursor, updated_after: updated_after, book_ids: book_ids)
       results = parsed_body.dig('results').map do |item|
@@ -120,7 +181,6 @@ def get_export_page(page_cursor: nil, updated_after: nil, book_ids: [])
       url = BASE_URL + 'export/?' + URI.encode_www_form(params)
 
       get_readwise_request(url)
-
     end
 
     def transform_book(res)
@@ -166,9 +226,51 @@ def transform_highlight(res)
       )
     end
 
+    def transform_document(res)
+      Document.new(
+        author: res['author'],
+        category: res['category'],
+        created_at: res['created_at'],
+        html: res['html'],
+        id: res['id'].to_s,
+        image_url: res['image_url'],
+        location: res['location'],
+        notes: res['notes'],
+        parent_id: res['parent_id'],
+        published_date: res['published_date'],
+        reading_progress: res['reading_progress'],
+        site_name: res['site_name'],
+        source: res['source'],
+        source_url: res['source_url'],
+        summary: res['summary'],
+        tags: transform_tags(res['tags']),
+        title: res['title'],
+        updated_at: res['updated_at'],
+        url: res['url'],
+        word_count: res['word_count'],
+      )
+    end
+
+    def transform_tags(res)
+      if res.is_a?(Array)
+        res.map { |tag| transform_tag(tag) }
+      elsif res.is_a?(Hash)
+        res.map do |tag_id, tag|
+          tag['id'] = tag_id
+          transform_tag(tag)
+        end
+      else
+        []
+      end
+    end
+
     def transform_tag(res)
+      if res.is_a?(String)
+        return Tag.new(name: res)
+      end
+
       Tag.new(
-        tag_id: res['id'].to_s,
+        tag_id: res['id']&.to_s,
         name: res['name'],
       )
     end
@@ -181,7 +283,7 @@ def get_readwise_request(url)
         http.request(req)
       end
 
-      raise Error, 'Get request failed' unless res.is_a?(Net::HTTPSuccess)
+      raise Error, "Get request failed with status code: #{res.code}" unless res.is_a?(Net::HTTPSuccess)
 
       JSON.parse(res.body)
     end