readwise 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3d14c72c58cb11dfcb79c0b3b232abb8b997dc230493d5e0765f186999accba
-  data.tar.gz: 037ac6d22c2d195607023e99eebbd71f2885996dd40e16d49f33bc403549ebd9
+  metadata.gz: 5e37bd88ff6059f63924f1c72ccb905f1d719fbff923411a00635995fcfe70a3
+  data.tar.gz: c3454ae039735d62d06c35889534c41ff76c94843ddeb9849d96b2287fa702d7
 SHA512:
-  metadata.gz: 6b25268acdd085ba3252f828a0f85051f492de64fd851e96a5a0e38bfcfb6e25070df8bc38d7fa94aa52c1433003d6dc8d57ca501d7261bef010e510b6711c13
-  data.tar.gz: 1d1c7e40a53214750405a866832427aadce2ad3dc432a4d9e4ab0610520400b1f5fb14d46d90712cc0219621eb2bef21c4bff40bb62def052e99409bfd0b0b86
+  metadata.gz: 45f34de451ad75c000b40ba5a78b7a365e701c8af9a27783128e30a951f8ec6674c8f90b12fb51ad77261c3a9f7378486feae6d5494d50e4b3ef9f0f4e0e8837
+  data.tar.gz: a5b2fe3e2a4d6c8ea744065f9dd76414db85858b62ae83be3aa65309281a25aa07fbd4cd72bf86f2581dba12796f890da07100d50a8d6892ee0620d0deae60a4

data/.github/workflows/ruby.yml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.6', '2.7', '3.0', '3.1', '3.2']
+        ruby-version: ['3.2', '3.3', '3.4']
 
     steps:
     - uses: actions/checkout@v3

data/.gitignore

@@ -55,3 +55,5 @@ Gemfile.lock
 
 # Used by RuboCop. Remote config files pulled in from inherit_from directive.
 # .rubocop-https?--*
+
+.rspec_status

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [1.1.0] - 2025-07-04
+- Add CLI command for creating documents from HTML content or URLs ([#16](https://github.com/joshbeckman/readwise-ruby/pull/16) from [@andyw8](https://github.com/andyw8))
+
+## [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))

data/README.md

@@ -101,7 +101,7 @@ puts document.child?                   # is this a highlight/note of another doc
 
 # Check location
 puts document.in_new?
-puts document.in_later?  
+puts document.in_later?
 puts document.in_archive?
 
 # Check category
@@ -142,6 +142,32 @@ document = client.create_document(document: document_create)
 documents = client.create_documents(documents: [document_create1, document_create2])
 ```
 
+## Command Line Interface
+
+This gem includes a `readwise` command-line tool for quickly sending HTML content to Readwise Reader.
+
+First, set your API token:
+```bash
+export READWISE_API_KEY=your_token_here
+```
+
+Then use the CLI to send HTML files:
+```bash
+# Basic usage
+readwise document create --html-file content.html
+readwise document create --url https://datatracker.ietf.org/doc/html/rfc2324
+
+# Short form flag
+readwise document create -f content.html
+
+# With options
+readwise document create --html-file content.html --title="My Article" --location=later
+
+# See all available options
+readwise --help
+readwise document create --help
+```
+
 ## 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.

data/exe/readwise

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'readwise'
+require 'readwise/cli'
+
+Readwise::CLI.start

data/lib/readwise/cli/base_command.rb

@@ -0,0 +1,105 @@
+require 'optparse'
+
+module Readwise
+  class CLI
+    class BaseCommand
+      def initialize
+        @options = {}
+      end
+
+      def execute(args)
+        parse_options(args)
+        validate_arguments(args)
+        run(args)
+      rescue OptionParser::InvalidOption => e
+        puts "Error: #{e.message}"
+        show_help
+        exit 1
+      rescue ArgumentError => e
+        puts "Error: #{e.message}"
+        exit 1
+      end
+
+      private
+
+      attr_reader :options
+
+      def parse_options(args)
+        parser = create_option_parser
+        parser.parse!(args)
+      end
+
+      def create_option_parser
+        OptionParser.new do |opts|
+          opts.banner = banner
+          opts.separator ""
+          opts.separator description if description
+          opts.separator ""
+          opts.separator "Options:"
+
+          add_options(opts)
+
+          opts.on("-h", "--help", "Show this help message") do
+            show_help
+            exit
+          end
+        end
+      end
+
+      def show_help
+        puts create_option_parser.help
+      end
+
+      def get_api_client
+        token = ENV['READWISE_API_KEY']
+        unless token
+          puts "Error: READWISE_API_KEY environment variable is not set"
+          exit 1
+        end
+
+        Readwise::Client.new(token: token)
+      end
+
+      def read_file(file_path)
+        unless File.exist?(file_path)
+          puts "Error: File '#{file_path}' not found"
+          exit 1
+        end
+
+        File.read(file_path)
+      end
+
+      def handle_api_error(&block)
+        yield
+      rescue Readwise::Client::Error => e
+        puts "API Error: #{e.message}"
+        exit 1
+      rescue => e
+        puts "Unexpected error: #{e.message}"
+        exit 1
+      end
+
+      # Override these methods in subclasses
+
+      def banner
+        "Usage: readwise"
+      end
+
+      def description
+        nil
+      end
+
+      def add_options(opts)
+        # Override in subclasses to add specific options
+      end
+
+      def validate_arguments(args)
+        # Override in subclasses to validate arguments
+      end
+
+      def run(args)
+        raise NotImplementedError, "Subclasses must implement #run"
+      end
+    end
+  end
+end

data/lib/readwise/cli/command_registry.rb

@@ -0,0 +1,24 @@
+module Readwise
+  class CLI
+    class CommandRegistry
+      @commands = {}
+
+      def self.register(resource, action, command_class)
+        key = "#{resource}:#{action}"
+        @commands[key] = command_class
+      end
+
+      def self.find(resource, action)
+        key = "#{resource}:#{action}"
+        @commands[key]
+      end
+
+      def self.all_commands
+        @commands.keys.map { |key| key.split(':') }
+      end
+    end
+  end
+end
+
+# Register available commands
+require_relative 'document/create_command'

data/lib/readwise/cli/document/create_command.rb

@@ -0,0 +1,152 @@
+require_relative '../base_command'
+require_relative '../../constants'
+require 'uri'
+require 'date'
+
+module Readwise
+  class CLI
+    module Document
+      class CreateCommand < BaseCommand
+        def banner
+          "Usage: readwise document create [options]"
+        end
+
+        def description
+          "Sends HTML content to Readwise Reader API"
+        end
+
+        def add_options(opts)
+          opts.on("-f", "--html-file=FILE", "HTML file path") do |file|
+            options[:file] = file
+          end
+
+          opts.on("--title=TITLE", "Document title") do |title|
+            options[:title] = title
+          end
+
+          opts.on("--author=AUTHOR", "Document author") do |author|
+            options[:author] = author
+          end
+
+          opts.on("-u", "--url=URL", "Source URL (defaults to https://example.com/<filename>)") do |url|
+            unless valid_url?(url)
+              puts "Error: Invalid URL format. Please provide a valid URL."
+              exit 1
+            end
+            options[:url] = url
+          end
+
+          opts.on("--summary=SUMMARY", "Document summary") do |summary|
+            options[:summary] = summary
+          end
+
+          opts.on("--notes=NOTES", "Personal notes") do |notes|
+            options[:notes] = notes
+          end
+
+          opts.on("--location=LOCATION", "Document location: #{Readwise::Constants::DOCUMENT_LOCATIONS.join(', ')} (default: new)") do |location|
+            unless Readwise::Constants::DOCUMENT_LOCATIONS.include?(location)
+              puts "Error: Invalid location. Must be one of: #{Readwise::Constants::DOCUMENT_LOCATIONS.join(', ')}"
+              exit 1
+            end
+            options[:location] = location
+          end
+
+          opts.on("--category=CATEGORY", "Document category: #{Readwise::Constants::DOCUMENT_CATEGORIES.join(', ')}") do |category|
+            unless Readwise::Constants::DOCUMENT_CATEGORIES.include?(category)
+              puts "Error: Invalid category. Must be one of: #{Readwise::Constants::DOCUMENT_CATEGORIES.join(', ')}"
+              exit 1
+            end
+            options[:category] = category
+          end
+
+          opts.on("--tags=TAGS", "Comma-separated list of tags") do |tags|
+            options[:tags] = tags.split(',').map(&:strip)
+          end
+
+          opts.on("--image-url=URL", "Image URL") do |image_url|
+            options[:image_url] = image_url
+          end
+
+          opts.on("--published-date=DATE", "Published date (ISO 8601 format)") do |date|
+            unless valid_iso8601_date?(date)
+              puts "Error: Invalid date format. Please provide a valid ISO 8601 date (e.g., 2023-12-25T10:30:00Z)."
+              exit 1
+            end
+            options[:published_date] = date
+          end
+
+          opts.on("--[no-]clean-html", "Clean HTML (default: true)") do |clean|
+            options[:should_clean_html] = clean
+          end
+
+          opts.on("--saved-using=SOURCE", "Saved using source (default: cli)") do |source|
+            options[:saved_using] = source
+          end
+        end
+
+        def validate_arguments(args)
+          unless options[:file] || options[:url]
+            puts "Error: File path or URL is required"
+            show_help
+            exit 1
+          end
+        end
+
+        def run(args)
+          html_file = options[:file]
+          html_content = read_file(html_file) if html_file
+
+          document_params = build_document_params(html_content, html_file)
+
+          handle_api_error do
+            client = get_api_client
+            document_create = Readwise::DocumentCreate.new(**document_params)
+            document = client.create_document(document: document_create)
+
+            puts "Document created successfully!"
+            puts "ID: #{document.id}"
+            puts "Title: #{document.title}"
+            puts "Location: #{document.location}"
+            puts "URL: #{document.url}" if document.url
+          end
+        end
+
+        private
+
+        def valid_url?(url)
+          uri = URI.parse(url)
+          uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+        rescue URI::InvalidURIError
+          false
+        end
+
+        def valid_iso8601_date?(date)
+          DateTime.iso8601(date)
+          true
+        rescue Date::Error
+          false
+        end
+
+        def build_document_params(html_content, html_file)
+          document_params = {
+            html: html_content,
+            location: options[:location] || 'new',
+            should_clean_html: options.key?(:should_clean_html) ? options[:should_clean_html] : true,
+            saved_using: options[:saved_using] || 'cli',
+            url: options[:url] || "https://example.com/#{File.basename(html_file)}"
+          }
+
+          [:title, :author, :summary, :notes, :category, :tags, :image_url, :published_date].each do |key|
+            document_params[key] = options[key] if options[key]
+          end
+
+          document_params
+        end
+      end
+    end
+  end
+end
+
+# Register this command
+Readwise::CLI::CommandRegistry.register('document', 'create', Readwise::CLI::Document::CreateCommand)

data/lib/readwise/cli.rb

@@ -0,0 +1,64 @@
+require_relative 'cli/base_command'
+require_relative 'cli/command_registry'
+
+module Readwise
+  class CLI
+    def self.start(args = ARGV)
+      new.start(args)
+    end
+
+    def start(args)
+      if args.empty?
+        show_help
+        exit 1
+      end
+
+      if args.first == '--help' || args.first == '-h'
+        show_help
+        return
+      end
+
+      resource = args.shift&.downcase
+      action = args.shift&.downcase
+
+      unless resource && action
+        puts "Error: Resource and action are required"
+        puts "Usage: readwise <resource> <action> [options] [arguments]"
+        puts "Run 'readwise --help' for more information"
+        exit 1
+      end
+
+      command_class = CommandRegistry.find(resource, action)
+      unless command_class
+        puts "Error: Unknown command '#{resource} #{action}'"
+        puts "Run 'readwise --help' to see available commands"
+        exit 1
+      end
+
+      command = command_class.new
+      command.execute(args)
+    rescue => e
+      puts "Unexpected error: #{e.message}"
+      exit 1
+    end
+
+    private
+
+    def show_help
+      puts <<~HELP
+        Usage: readwise <resource> <action> [options] [arguments]
+
+        Available commands:
+          document create --html-file <file>    Send HTML content to Readwise Reader
+
+        Global options:
+          -h, --help               Show this help message
+
+        Examples:
+          readwise document create --html-file content.html --title="My Article"
+          readwise document create -f content.html --title="My Article"
+          readwise document create --help
+      HELP
+    end
+  end
+end

data/lib/readwise/client.rb

@@ -227,7 +227,7 @@ 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'],

data/lib/readwise/constants.rb

@@ -0,0 +1,6 @@
+module Readwise
+  module Constants
+    DOCUMENT_CATEGORIES = %w[article email rss highlight note pdf epub tweet video].freeze
+    DOCUMENT_LOCATIONS = %w[new later archive feed].freeze
+  end
+end

data/lib/readwise/version.rb

@@ -1,3 +1,3 @@
 module Readwise
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/readwise.gemspec

@@ -37,8 +37,8 @@ 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.2"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "bundler", "~> 2.4"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "rspec-file_fixtures", "~> 0.1.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: readwise
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Josh Beckman
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '2.4'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -68,7 +68,8 @@ dependencies:
 description: Minimal Readwise API client and highlight parsing library
 email:
 - josh@joshbeckman.org
-executables: []
+executables:
+- readwise
 extensions: []
 extra_rdoc_files: []
 files:
@@ -83,9 +84,15 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- exe/readwise
 - lib/readwise.rb
 - lib/readwise/book.rb
+- lib/readwise/cli.rb
+- lib/readwise/cli/base_command.rb
+- lib/readwise/cli/command_registry.rb
+- lib/readwise/cli/document/create_command.rb
 - lib/readwise/client.rb
+- lib/readwise/constants.rb
 - lib/readwise/document.rb
 - lib/readwise/highlight.rb
 - lib/readwise/review.rb