readwise 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3430c0062c1b93b7f57032195dd68953f5747fe221104c3f9d27edac52bc6fa2
-  data.tar.gz: 9436565954a21d0b34b8ae7896ded212801daf05512d1fb512207272547792c9
+  metadata.gz: 2132de7e8f9fdbc395fc94872968cee73d333c67723b2e81a7554b61105e1469
+  data.tar.gz: 4aca80570f7ea3d6d7045cfe0f3fe75c64d578e4ea2de05697d98e747215d74a
 SHA512:
-  metadata.gz: e9d2cf349ca75d6b9a21dcf60c2c8ea2af9ddff6e3aace2ecb82c748b9a1845204e1ac7c9d72c23e5a6c4dbcd9bf682c455162d72ac56b62fb5348d32f958b6f
-  data.tar.gz: 4fdcdc6cca2bb5a7881ee8beceb1c3096f348776839fed87c330d8bb91abd004d1ab75bff9cd9e9ce5d23b0d57c3f1ed55b34738ae9888c3fd42e72c94447dd2
+  metadata.gz: 35498d0c04b98eab247b3bf78bdf66dc51294f0538273c9515d8122b737c494421a4425f241d25577d77ec55a2ce01455e02fb91281a72769c753a7d74e9690c
+  data.tar.gz: 751bfaf4334fcf74cd6f16b685108a8df095a84366b91c76e1978447d839f28ff7234c136f933bd37eb18f7e1b0e437a40e84e7b17a4c5e3641a6d0995519268

data/.github/FUNDING.yml

@@ -1,3 +1,3 @@
 # These are supported funding model platforms
 
-github: andjosh
+github: joshbeckman

data/.github/workflows/ruby.yml

@@ -0,0 +1,39 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+# This workflow will download a prebuilt Ruby version, install dependencies and run tests with Rake
+# For more information see: https://github.com/marketplace/actions/setup-ruby-jruby-and-truffleruby
+
+name: Ruby
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ['2.6', '2.7', '3.0', '3.1', '3.2']
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+    # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
+    # change this to (see https://github.com/ruby/setup-ruby#versioning):
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+          # bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+    - name: Install deps
+      run: bundle install
+    - name: Run tests
+      run: bundle exec rspec

data/.gitignore

@@ -46,7 +46,7 @@ build-iPhoneSimulator/
 
 # for a library or gem, you might want to ignore these files since the code is
 # intended to run in multiple environments; otherwise, check them in:
-# Gemfile.lock
+Gemfile.lock
 # .ruby-version
 # .ruby-gemset
 

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [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
+- Add method to get book
+
+## [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))
+
 ## [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))

data/README.md

@@ -33,11 +33,30 @@ books = client.export(book_ids: ['123']) # export specific highlights
 
 puts books.first.title # books are Readwise::Book structs
 puts books.first.highlights.map(&:text) # highlights are Readwise::Highlight structs
+
+# create a highlight
+create = Readwise::HighlightCreate.new(text: 'foobar', author: 'Joan')
+highlight = client.create_highlight(highlight: create)
+
+# update a highlight
+update = Readwise::HighlightUpdate.new(text: 'foobaz', color: 'yellow')
+updated = client.update_highlight(highlight: highlight, update: update)
+
+# add a tag to a highlight
+tag = Readwise::Tag.new(name: 'foobar')
+added_tag = client.add_highlight_tag(highlight: highlight, tag: tag)
+
+# update a tag on a highlight
+added_tag.name = 'bing'
+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)
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+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.
 
 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/lib/readwise/book.rb

@@ -10,6 +10,7 @@ module Readwise
     :cover_image_url,
     :highlights,
     :note,
+    :num_highlights,
     :readable_title,
     :readwise_url,
     :source,

data/lib/readwise/client.rb

@@ -8,17 +8,83 @@ module Readwise
   class Client
     class Error < StandardError; end
 
+    BASE_URL = "https://readwise.io/api/v2/"
+
     def initialize(token: nil)
       raise ArgumentError unless token
+
       @token = token.to_s
     end
 
     def create_highlight(highlight:)
-      create_highlights([highlight])
+      create_highlights(highlights: [highlight]).first
     end
 
     def create_highlights(highlights: [])
-      raise NotImplementedError
+      raise ArgumentError unless highlights.all? { |item| item.is_a?(Readwise::HighlightCreate) }
+      return [] unless highlights.any?
+
+      url = BASE_URL + 'highlights/'
+
+      payload = { highlights: highlights.map(&:serialize) }
+      res = post_readwise_request(url, payload: payload)
+
+      modified_ids = res.map { |book| book['modified_highlights'] }.flatten
+      modified_ids.map { |id| get_highlight(highlight_id: id) }
+    end
+
+    def get_highlight(highlight_id:)
+      url = BASE_URL + "highlights/#{highlight_id}"
+
+      res = get_readwise_request(url)
+
+      transform_highlight(res)
+    end
+
+    def update_highlight(highlight:, update:)
+      raise ArgumentError unless update.is_a?(Readwise::HighlightUpdate)
+
+      url = BASE_URL + "highlights/#{highlight.highlight_id}"
+
+      res = patch_readwise_request(url, payload: update.serialize)
+
+      transform_highlight(res)
+    end
+
+    def remove_highlight_tag(highlight:, tag:)
+      url = BASE_URL + "highlights/#{highlight.highlight_id}/tags/#{tag.tag_id}"
+
+      delete_readwise_request(url)
+    end
+
+    def add_highlight_tag(highlight:, tag:)
+      raise ArgumentError unless tag.is_a?(Readwise::Tag)
+
+      url = BASE_URL + "highlights/#{highlight.highlight_id}/tags"
+
+      payload = tag.serialize.select { |k, v| k == :name }
+      res = post_readwise_request(url, payload: payload)
+
+      transform_tag(res)
+    end
+
+    def update_highlight_tag(highlight:, tag:)
+      raise ArgumentError unless tag.is_a?(Readwise::Tag)
+
+      url = BASE_URL + "highlights/#{highlight.highlight_id}/tags/#{tag.tag_id}"
+
+      payload = tag.serialize.select { |k, v| k == :name }
+      res = patch_readwise_request(url, payload: payload)
+
+      transform_tag(res)
+    end
+
+    def get_book(book_id:)
+      url = BASE_URL + "books/#{book_id}"
+
+      res = get_readwise_request(url)
+
+      transform_book(res)
     end
 
     def export(updated_after: nil, book_ids: [])
@@ -38,52 +104,7 @@ module Readwise
     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|
-        Book.new(
-          asin: item['asin'],
-          author: item['author'],
-          book_id: item['user_book_id'].to_s,
-          category: item['category'],
-          cover_image_url: item['cover_image_url'],
-          note: item['document_note'],
-          readable_title: item['readable_title'],
-          readwise_url: item['readwise_url'],
-          source: item['source'],
-          source_url: item['source_url'],
-          tags: item['book_tags'].map do |tag|
-            Tag.new(
-              tag_id: tag['id'].to_s,
-              name: tag['name']
-            )
-          end,
-          title: item['title'],
-          unique_url: item['unique_url'],
-          highlights: item['highlights'].map do |highlight|
-            Highlight.new(
-              book_id: highlight['book_id'].to_s,
-              color: highlight['color'],
-              created_at: highlight['created_at'],
-              end_location: highlight['end_location'],
-              external_id: highlight['external_id'],
-              highlight_id: highlight['id'].to_s,
-              highlighted_at: highlight['highlighted_at'],
-              is_discard: highlight['is_discard'],
-              is_favorite: highlight['is_favorite'],
-              location: highlight['location'],
-              location_type: highlight['location_type'],
-              note: highlight['note'],
-              readwise_url: highlight['readwise_url'],
-              tags: highlight['tags'].map do |tag|
-                Tag.new(
-                  tag_id: tag['id'].to_s,
-                  name: tag['name']
-                )
-              end,
-              text: highlight['text'],
-              updated_at: highlight['updated_at'],
-              url: highlight['url'],
-            )
-          end
-        )
+        transform_book(item)
       end
       {
         results: results,
@@ -96,16 +117,114 @@ module Readwise
       params['updatedAfter'] = updated_after if updated_after
       params['ids'] = book_ids if book_ids.any?
       params['pageCursor'] = page_cursor if page_cursor
-      url = 'https://readwise.io/api/v2/export/?' + URI.encode_www_form(params)
-      export_uri = URI.parse(url)
-      export_req = Net::HTTP::Get.new(export_uri)
-      export_req['Authorization'] = "Token #{@token}"
-      export_res = Net::HTTP.start(export_uri.hostname, export_uri.port, use_ssl: true) do |http|
-        http.request(export_req)
+      url = BASE_URL + 'export/?' + URI.encode_www_form(params)
+
+      get_readwise_request(url)
+
+    end
+
+    def transform_book(res)
+      highlights = (res['highlights'] || []).map { |highlight| transform_highlight(highlight) }
+      Book.new(
+        asin: res['asin'],
+        author: res['author'],
+        book_id: res['user_book_id'].to_s,
+        category: res['category'],
+        cover_image_url: res['cover_image_url'],
+        note: res['document_note'],
+        readable_title: res['readable_title'],
+        readwise_url: res['readwise_url'] || res['highlights_url'],
+        source: res['source'],
+        source_url: res['source_url'],
+        tags: (res['book_tags'] || res['tags'] || []).map { |tag| transform_tag(tag) },
+        title: res['title'],
+        unique_url: res['unique_url'],
+        highlights: highlights,
+        num_highlights: res['num_highlights'] || highlights.size,
+      )
+    end
+
+    def transform_highlight(res)
+      Highlight.new(
+        book_id: res['book_id'].to_s,
+        color: res['color'],
+        created_at: res['created_at'],
+        end_location: res['end_location'],
+        external_id: res['external_id'],
+        highlight_id: res['id'].to_s,
+        highlighted_at: res['highlighted_at'],
+        is_discard: res['is_discard'],
+        is_favorite: res['is_favorite'],
+        location: res['location'],
+        location_type: res['location_type'],
+        note: res['note'],
+        readwise_url: res['readwise_url'],
+        tags: res['tags'].map { |tag| transform_tag(tag) },
+        text: res['text'],
+        updated_at: res['updated_at'],
+        url: res['url'],
+      )
+    end
+
+    def transform_tag(res)
+      Tag.new(
+        tag_id: res['id'].to_s,
+        name: res['name'],
+      )
+    end
+
+    def get_readwise_request(url)
+      uri = URI.parse(url)
+      req = Net::HTTP::Get.new(uri)
+      req['Authorization'] = "Token #{@token}"
+      res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(req)
+      end
+
+      raise Error, 'Get request failed' unless res.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(res.body)
+    end
+
+    def patch_readwise_request(url, payload:)
+      uri = URI.parse(url)
+      req = Net::HTTP::Patch.new(uri)
+      req['Authorization'] = "Token #{@token}"
+      req['Content-Type'] = 'application/json'
+      req.body = payload.to_json
+      res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(req)
+      end
+
+      raise Error, 'Patch request failed' unless res.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(res.body)
+    end
+
+    def post_readwise_request(url, payload:)
+      uri = URI.parse(url)
+      req = Net::HTTP::Post.new(uri)
+      req['Authorization'] = "Token #{@token}"
+      req['Content-Type'] = 'application/json'
+      req.body = payload.to_json
+      res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(req)
+      end
+
+      raise Error, 'Post request failed' unless res.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(res.body)
+    end
+
+    def delete_readwise_request(url)
+      uri = URI.parse(url)
+      req = Net::HTTP::Delete.new(uri)
+      req['Authorization'] = "Token #{@token}"
+      res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
+        http.request(req)
       end
-      raise Error, 'Export request failed' unless export_res.is_a?(Net::HTTPSuccess)
 
-      JSON.parse(export_res.body)
+      raise Error, 'Delete request failed' unless res.is_a?(Net::HTTPSuccess)
     end
   end
 end

data/lib/readwise/highlight.rb

@@ -39,5 +39,45 @@ module Readwise
 
       Time.parse(highlighted_at)
     end
+
+    def serialize
+      to_h
+    end
+  end
+
+  HighlightCreate = Struct.new(
+    'ReadwiseHighlightCreate',
+    :author,
+    :category,  # One of: books, articles, tweets or podcasts.
+                # (default: articles when source_url is provided, otherwise: books)
+    :highlight_url,
+    :highlighted_at,
+    :image_url,
+    :location,
+    :location_type, # One of: page, order or time_offset (default: order)
+    :note,
+    :source_type,
+    :source_url,
+    :text,
+    :title,
+    keyword_init: true
+  ) do
+    def serialize
+      to_h.compact
+    end
+  end
+
+  HighlightUpdate = Struct.new(
+    'ReadwiseHighlightUpdate',
+    :color,
+    :location,
+    :note,
+    :text,
+    :url,
+    keyword_init: true
+  ) do
+    def serialize
+      to_h.compact
+    end
   end
 end

data/lib/readwise/tag.rb

@@ -4,5 +4,9 @@ module Readwise
     :tag_id,
     :name,
     keyword_init: true
-  )
+  ) do
+    def serialize
+      to_h
+    end
+  end
 end

data/lib/readwise/version.rb

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

data/readwise.gemspec

@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 2.4.4"
+  spec.add_development_dependency "bundler", "~> 2.2"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec-file_fixtures", "~> 0.1.6"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: readwise
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Josh Beckman
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-28 00:00:00.000000000 Z
+date: 2023-06-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.4.4
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.4.4
+        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -74,11 +74,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".github/FUNDING.yml"
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -114,7 +114,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.7
+rubygems_version: 3.4.14
 signing_key:
 specification_version: 4
 summary: Readwise API client

data/Gemfile.lock

@@ -1,38 +0,0 @@
-PATH
-  remote: .
-  specs:
-    readwise (0.2.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    diff-lcs (1.5.0)
-    rake (10.5.0)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.0)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.2)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-file_fixtures (0.1.6)
-      rspec (~> 3.0)
-    rspec-mocks (3.12.2)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-support (3.12.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 2.4.4)
-  rake (~> 10.0)
-  readwise!
-  rspec (~> 3.0)
-  rspec-file_fixtures (~> 0.1.6)
-
-BUNDLED WITH
-   2.4.4