readwise 0.5.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2132de7e8f9fdbc395fc94872968cee73d333c67723b2e81a7554b61105e1469
-  data.tar.gz: 4aca80570f7ea3d6d7045cfe0f3fe75c64d578e4ea2de05697d98e747215d74a
+  metadata.gz: 69d1388e16dfcaf6db33d61ee780ce3172154a2f48ddc246fa0e82cf7eff81ec
+  data.tar.gz: 369ba0fd764cbc86cb78e99008dcf967a525bd850ed0f5e5270c046808a12248
 SHA512:
-  metadata.gz: 35498d0c04b98eab247b3bf78bdf66dc51294f0538273c9515d8122b737c494421a4425f241d25577d77ec55a2ce01455e02fb91281a72769c753a7d74e9690c
-  data.tar.gz: 751bfaf4334fcf74cd6f16b685108a8df095a84366b91c76e1978447d839f28ff7234c136f933bd37eb18f7e1b0e437a40e84e7b17a4c5e3641a6d0995519268
+  metadata.gz: 599eef221a90c3c7259f99d65816f902104ed85e197af64887ced7522be0db56239700c199cb4ba1e8f7a83e4dca85a4331e68258c6ff7f4a23b09ef3cc4da8a
+  data.tar.gz: 4dad02e9aa6063a8da149b775185baf239a3ec5f6f799263fd8b02324e08ae8fa0dc281b0008a10d438e01a84d4ce24c3ad676a4a287a67f71964fa0a6273a22

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [1.0.1] - 2025-06-29
+- Handle absent tags in transforming highlights
+
+## [1.0.0] - 2025-06-29
+- Add Readwise API v3 support for Reader documents ([#13](https://github.com/joshbeckman/readwise-ruby/pull/13))
+- Add `daily_review` client method and Review type ([#14](https://github.com/joshbeckman/readwise-ruby/pull/14))
+- Add comprehensive document API methods (list, get, create, update, delete)
+- Add support for document tags and metadata handling
+- Add tests for document API functionality
+
 ## [0.5.0] - 2023-06-15
 - Add methods to create/update highlights ([#8](https://github.com/joshbeckman/readwise-ruby/pull/12))
 - Add methods to add/update/remove highlight tags
@@ -9,15 +19,15 @@
 
 ## [0.4.0] - 2023-03-19
 
-- Add `get_highlight` client method ([#10](https://github.com/andjosh/readwise-ruby/pull/10) from [@ajistrying](https://github.com/ajistrying))
+- Add `get_highlight` client method ([#10](https://github.com/joshbeckman/readwise-ruby/pull/10) from [@ajistrying](https://github.com/ajistrying))
 
 ## [0.3.0] - 2023-02-28
 
-- Change `Tag` from hash to struct ([#6](https://github.com/andjosh/readwise-ruby/pull/6) from [@ajistrying](https://github.com/ajistrying))
+- Change `Tag` from hash to struct ([#6](https://github.com/joshbeckman/readwise-ruby/pull/6) from [@ajistrying](https://github.com/ajistrying))
 
 ## [0.2.0] - 2023-02-20
 
-- Add support for `Book.note` ([#4](https://github.com/andjosh/readwise-ruby/pull/4))
+- Add support for `Book.note` ([#4](https://github.com/joshbeckman/readwise-ruby/pull/4))
 
 ## [0.1.0] - 2023-01-16
 

data/CODE_OF_CONDUCT.md

@@ -55,7 +55,7 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at email@andjosh.com. All
+reported by contacting the project team at josh@joshbeckman.org. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is
 obligated to maintain confidentiality with regard to the reporter of an incident.

data/README.md

@@ -1,6 +1,8 @@
 # Readwise
 
-[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.
+[![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, 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!
 
@@ -24,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)
 
@@ -52,6 +58,88 @@ updated_tag = client.update_highlight_tag(highlight: highlight, tag: added_tag)
 
 # remove a tag from a highlight
 client.remove_highlight_tag(highlight: highlight, tag: added_tag)
+
+# get daily review highlights
+daily_review = client.daily_review
+puts daily_review.id
+puts daily_review.url
+puts daily_review.completed?
+puts daily_review.highlights.size
+puts daily_review.highlights.first.text
+```
+
+### 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
@@ -62,7 +150,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/andjosh/readwise. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/joshbeckman/readwise-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -70,4 +158,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Readwise project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/andjosh/readwise/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Readwise project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/joshbeckman/readwise-ruby/blob/main/CODE_OF_CONDUCT.md).

data/lib/readwise/client.rb

@@ -3,12 +3,15 @@ require 'net/http'
 require_relative 'book'
 require_relative 'highlight'
 require_relative 'tag'
+require_relative 'document'
+require_relative 'review'
 
 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
@@ -16,6 +19,43 @@ module Readwise
       @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
@@ -87,6 +127,13 @@ module Readwise
       transform_book(res)
     end
 
+    def daily_review
+      url = BASE_URL + 'review/'
+
+      res = get_readwise_request(url)
+      transform_review(res)
+    end
+
     def export(updated_after: nil, book_ids: [])
       resp = export_page(updated_after: updated_after, book_ids: book_ids)
       next_page_cursor = resp[:next_page_cursor]
@@ -101,6 +148,28 @@ module Readwise
 
     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 +189,6 @@ module Readwise
       url = BASE_URL + 'export/?' + URI.encode_www_form(params)
 
       get_readwise_request(url)
-
     end
 
     def transform_book(res)
@@ -159,20 +227,73 @@ module Readwise
         location_type: res['location_type'],
         note: res['note'],
         readwise_url: res['readwise_url'],
-        tags: res['tags'].map { |tag| transform_tag(tag) },
+        tags: (res['tags'] || []).map { |tag| transform_tag(tag) },
         text: res['text'],
         updated_at: res['updated_at'],
         url: res['url'],
       )
     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
 
+    def transform_review(res)
+      highlights = (res['highlights'] || []).map { |highlight| transform_highlight(highlight) }
+
+      Review.new(
+        id: res['review_id'],
+        url: res['review_url'],
+        completed: res['review_completed'],
+        highlights: highlights
+      )
+    end
+
     def get_readwise_request(url)
       uri = URI.parse(url)
       req = Net::HTTP::Get.new(uri)
@@ -181,7 +302,7 @@ module Readwise
         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

data/lib/readwise/document.rb

@@ -0,0 +1,140 @@
+require 'time'
+
+module Readwise
+  Document = Struct.new(
+    'ReadwiseDocument',
+    :author,
+    :category,  # One of: article, email, rss, highlight, note, pdf, epub, tweet or video.
+                # Default is guessed based on the URL, usually article.
+    :created_at,
+    :html,
+    :id,
+    :image_url,
+    :location,  # One of: new, later, archive or feed. Default is new.
+    :notes,
+    :published_date,
+    :reading_progress,
+    :site_name,
+    :source,
+    :source_url,
+    :summary,
+    :tags,
+    :title,
+    :updated_at,
+    :url,
+    :word_count,
+    :parent_id, # both highlights and notes made in Reader are also considered Documents.
+                # Highlights and notes will have `parent_id` set, which is the Document id
+                # of the article/book/etc and highlight that they belong to, respectively.
+    keyword_init: true
+  ) do
+    def created_at_time
+      return unless created_at
+
+      Time.parse(created_at)
+    end
+
+    def updated_at_time
+      return unless updated_at
+
+      Time.parse(updated_at)
+    end
+
+    def published_date_time
+      return unless published_date
+
+      Time.at(published_date/1000)
+    end
+
+    def read?(threshold: 0.85)
+      reading_progress >= threshold
+    end
+
+    def parent?
+      parent_id.nil?
+    end
+
+    def child?
+      !parent?
+    end
+
+    def in_new?
+      location == 'new'
+    end
+
+    def in_later?
+      location == 'later'
+    end
+
+    def in_archive?
+      location == 'archive'
+    end
+
+    def pdf?
+      category == 'pdf'
+    end
+
+    def epub?
+      category == 'epub'
+    end
+
+    def tweet?
+      category == 'tweet'
+    end
+
+    def video?
+      category == 'video'
+    end
+
+    def article?
+      category == 'article'
+    end
+
+    def book?
+      category == 'book'
+    end
+
+    def email?
+      category == 'email'
+    end
+
+    def rss?
+      category == 'rss'
+    end
+
+    def highlight?
+      category == 'highlight'
+    end
+
+    def note?
+      category == 'note'
+    end
+
+    def serialize
+      to_h
+    end
+  end
+
+  DocumentCreate = Struct.new(
+    'ReadwiseDocumentCreate',
+    :author,
+    :category,  # One of: article, email, rss, highlight, note, pdf, epub, tweet or video.
+                # Default is guessed based on the URL, usually article.
+    :html,
+    :image_url,
+    :location,  # One of: new, later, archive or feed. Default is new.
+    :notes,
+    :published_date,
+    :saved_using,
+    :should_clean_html,
+    :summary,
+    :tags,
+    :title,
+    :url,
+    keyword_init: true
+  ) do
+    def serialize
+      to_h.compact
+    end
+  end
+end

data/lib/readwise/review.rb

@@ -0,0 +1,17 @@
+module Readwise
+  Review = Struct.new(
+    :id,
+    :url,
+    :completed,
+    :highlights,
+    keyword_init: true
+  ) do
+    def completed?
+      completed
+    end
+
+    def serialize
+      to_h.compact
+    end
+  end
+end

data/lib/readwise/version.rb

@@ -1,3 +1,3 @@
 module Readwise
-  VERSION = "0.5.0"
+  VERSION = "1.0.1"
 end

data/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

data/readwise.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
 
   spec.summary       = "Readwise API client"
   spec.description   = "Minimal Readwise API client and highlight parsing library"
-  spec.homepage      = "https://github.com/andjosh/readwise-ruby"
+  spec.homepage      = "https://github.com/joshbeckman/readwise-ruby"
   spec.license       = "MIT"
 
   # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
@@ -22,6 +22,7 @@ Gem::Specification.new do |spec|
     spec.metadata["homepage_uri"] = spec.homepage
     spec.metadata["source_code_uri"] = spec.homepage
     spec.metadata["changelog_uri"] = spec.homepage + "/blob/main/CHANGELOG.md"
+    spec.metadata["funding_uri"] = "https://github.com/sponsors/joshbeckman"
   else
     raise "RubyGems 2.0 or newer is required to protect against " \
       "public gem pushes."

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: readwise
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Josh Beckman
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-06-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -87,19 +86,21 @@ files:
 - lib/readwise.rb
 - lib/readwise/book.rb
 - lib/readwise/client.rb
+- lib/readwise/document.rb
 - lib/readwise/highlight.rb
+- lib/readwise/review.rb
 - lib/readwise/tag.rb
 - lib/readwise/version.rb
 - readwise.gemspec
-homepage: https://github.com/andjosh/readwise-ruby
+homepage: https://github.com/joshbeckman/readwise-ruby
 licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/andjosh/readwise-ruby
-  source_code_uri: https://github.com/andjosh/readwise-ruby
-  changelog_uri: https://github.com/andjosh/readwise-ruby/blob/main/CHANGELOG.md
-post_install_message:
+  homepage_uri: https://github.com/joshbeckman/readwise-ruby
+  source_code_uri: https://github.com/joshbeckman/readwise-ruby
+  changelog_uri: https://github.com/joshbeckman/readwise-ruby/blob/main/CHANGELOG.md
+  funding_uri: https://github.com/sponsors/joshbeckman
 rdoc_options: []
 require_paths:
 - lib
@@ -114,8 +115,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.14
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Readwise API client
 test_files: []