hashcards_readwise 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 28483db60197d3a33cd5b1884f96df11b624ee600a74bd86490b31232c3c9ec1
+  data.tar.gz: fc816269bc4f7243ffce9e880d53bc0c44e236fd3c25f85cc5d21f12a47f6bc4
+SHA512:
+  metadata.gz: db2f8647c80c5ae77e0c829ec26553d27c5f2595c896ca2b974e39a4916e9bfe42a40d7498845cb62448e35766bacb04393152f505a0696208a17d4f65a8b77e
+  data.tar.gz: '075686ab4f1b61fb7b3df46ad00d0c89e3e102ee342bc0a0d0ac92452efeec6e19175990e7967367e2008c51009e6dd8dfed70618c9b1ce99319d541f4d9c611'

data/README.md

@@ -0,0 +1,75 @@
+# hashcards-readwise
+
+Sync [hashcards](https://github.com/eudoxia0/hashcards) flashcards to [Readwise](https://readwise.io).
+
+## Installation
+
+```bash
+gem install hashcards_readwise
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "hashcards_readwise"
+```
+
+## Usage
+
+### All-in-one sync
+
+```bash
+# Sync a hashcards collection to Readwise
+hashcards-readwise sync --collection ./cards
+
+# Dry run (convert but don't push)
+hashcards-readwise sync --collection ./cards --dry-run
+```
+
+### Step-by-step
+
+```bash
+# 1. Export hashcards to JSON
+hashcards export ./cards --output export.json
+
+# 2. Convert to Readwise format
+hashcards-readwise convert -f export.json -o highlights.json -d ./cards/hashcards.db
+
+# 3. Push to Readwise
+hashcards-readwise push -f highlights.json
+```
+
+## Configuration
+
+Set your Readwise API token via environment variable:
+
+```bash
+export READWISE_TOKEN="your-token-here"
+```
+
+Or pass it directly:
+
+```bash
+hashcards-readwise sync --token "your-token-here" --collection ./cards
+```
+
+## Deck Metadata
+
+Add TOML frontmatter to your deck files to customize Readwise metadata:
+
+```markdown
+---
+name = "My Deck"
+author = "Author Name"
+source_url = "https://example.com/source"
+image_url = "https://example.com/image.png"
+tags = ["topic1", "topic2"]
+---
+
+Q: Question here
+A: Answer here
+```
+
+## License
+
+MIT

data/exe/hashcards-readwise

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "hashcards_readwise"
+
+HashcardsReadwise::CLI.new.run

data/lib/hashcards_readwise/cli.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "logger"
+
+module HashcardsReadwise
+  class CLI
+    def initialize(args = ARGV)
+      @args = args
+      @logger = Logger.new($stderr, level: Logger::WARN)
+      @logger.progname = "hashcards-readwise"
+    end
+
+    def run
+      OptionParser.new do |o|
+        o.on("-v", "--verbose", "Enable verbose logging (can be repeated)") { @logger.level -= 1 }
+      end.order!(@args)
+
+      command = @args.shift
+
+      case command
+      when "convert"
+        run_convert
+      when "push"
+        run_push
+      when "sync"
+        run_sync
+      when "version", "-v", "--version"
+        puts "hashcards-readwise #{VERSION}"
+      when "help", "-h", "--help", nil
+        print_help
+      else
+        @logger.warn("Unknown command: #{command}")
+        print_help
+        exit 1
+      end
+    end
+
+    private
+
+    def run_convert
+      options = { file: nil, output: nil, db: nil }
+
+      OptionParser.new do |o|
+        o.banner = "Usage: hashcards-readwise convert [options]"
+        o.on("-f", "--file FILE", "Path to hashcards JSON export") { |f| options[:file] = f }
+        o.on("-o", "--output FILE", "Output file (default: stdout)") { |f| options[:output] = f }
+        o.on("-d", "--db FILE", "Path to hashcards SQLite database") { |f| options[:db] = f }
+      end.parse!(@args)
+
+      unless options[:file]
+        @logger.error "Error: --file is required"
+        exit 1
+      end
+
+      converter = Converter.new(logger: @logger)
+      highlights = converter.convert(hashcards_path: options[:file], db_path: options[:db])
+
+      output = JSON.pretty_generate(highlights)
+      if options[:output]
+        File.write(options[:output], output)
+        @logger.info("Wrote highlights to #{options[:output]}")
+      else
+        puts output
+      end
+    end
+
+    def run_push
+      options = { file: nil, token: ENV["READWISE_TOKEN"], dry_run: false }
+
+      OptionParser.new do |o|
+        o.banner = "Usage: hashcards-readwise push [options]"
+        o.on("-f", "--file FILE", "Path to highlights JSON file") { |f| options[:file] = f }
+        o.on("-t", "--token TOKEN", "Readwise API token") { |t| options[:token] = t }
+        o.on("-n", "--dry-run", "Print request without sending") { options[:dry_run] = true }
+      end.parse!(@args)
+
+      unless options[:file]
+        @logger.error "Error: --file is required"
+        exit 1
+      end
+
+      unless options[:token]
+        @logger.error "Error: Readwise token required (--token or READWISE_TOKEN env)"
+        exit 1
+      end
+
+      highlights = JSON.parse(File.read(options[:file]))
+      @logger.info("Loaded #{highlights["highlights"].size} highlights from #{options[:file]}")
+
+      if options[:dry_run]
+        @logger.info("Dry run - would POST to #{Pusher::READWISE_API_URL}")
+        @logger.info("Body: #{JSON.pretty_generate(highlights)}")
+        return
+      end
+
+      pusher = Pusher.new(token: options[:token], logger: @logger)
+      result = pusher.push(highlights)
+
+      unless result[:success]
+        @logger.error result[:body]
+        exit 1
+      end
+
+      puts JSON.pretty_generate(result[:body])
+    end
+
+    def run_sync
+      options = { collection: ".", token: ENV["READWISE_TOKEN"], dry_run: false }
+
+      OptionParser.new do |o|
+        o.banner = "Usage: hashcards-readwise sync [options]"
+        o.on("-c", "--collection DIR", "Path to hashcards collection") { |c| options[:collection] = c }
+        o.on("-t", "--token TOKEN", "Readwise API token") { |t| options[:token] = t }
+        o.on("-n", "--dry-run", "Convert but don't push") { options[:dry_run] = true }
+      end.parse!(@args)
+
+      unless options[:token]
+        @logger.error "Error: Readwise token required (--token or READWISE_TOKEN env)"
+        exit 1
+      end
+
+      collection = File.expand_path(options[:collection])
+      db_path = File.join(collection, "hashcards.db")
+      db_path = nil unless File.exist?(db_path)
+
+      # Export hashcards to temp file
+      require "tempfile"
+      export_file = Tempfile.new(["hashcards", ".json"])
+
+      @logger.info("Exporting hashcards from #{collection}...")
+      system("hashcards", "export", collection, "--output", export_file.path)
+
+      unless $?.success?
+        @logger.error "Error: hashcards export failed"
+        exit 1
+      end
+
+      # Convert
+      converter = Converter.new(logger: @logger)
+      highlights = converter.convert(hashcards_path: export_file.path, db_path: db_path)
+
+      if options[:dry_run]
+        puts JSON.pretty_generate(highlights)
+        return
+      end
+
+      # Push
+      pusher = Pusher.new(token: options[:token], logger: @logger)
+      result = pusher.push(highlights)
+
+      unless result[:success]
+        @logger.error result[:body]
+        exit 1
+      end
+
+      @logger.info "Synced #{highlights["highlights"].size} highlights to Readwise"
+    ensure
+      export_file&.unlink
+    end
+
+    def print_help
+      puts <<~HELP
+        hashcards-readwise - Sync hashcards flashcards to Readwise
+
+        Usage: hashcards-readwise <command> [options]
+
+        Commands:
+          sync      Export, convert, and push to Readwise (all-in-one)
+          convert   Convert hashcards JSON to Readwise highlights format
+          push      Push highlights JSON to Readwise API
+          version   Show version
+          help      Show this help
+
+        Examples:
+          hashcards-readwise sync --collection ./cards
+          hashcards-readwise convert -f export.json -o highlights.json
+          hashcards-readwise push -f highlights.json
+
+        Environment:
+          READWISE_TOKEN  Readwise API token (or use --token)
+      HELP
+    end
+  end
+end

data/lib/hashcards_readwise/converter.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "json"
+require "sqlite3"
+require "toml-rb"
+require "logger"
+
+module HashcardsReadwise
+  class Converter
+    DEFAULT_AUTHOR = "Derek Stride"
+
+    attr_reader :logger
+
+    def initialize(logger: Logger.new($stderr, level: Logger::WARN))
+      @logger = logger
+      @frontmatter_cache = {}
+    end
+
+    def convert(hashcards_path:, db_path: nil)
+      hashcards = JSON.parse(File.read(hashcards_path))
+      logger.info("Loaded #{hashcards["cards"].size} cards from #{hashcards_path}")
+
+      timestamps = load_timestamps(db_path)
+      logger.info("Loaded #{timestamps.size} timestamps from database") if timestamps.any?
+
+      highlights = hashcards["cards"].filter_map { |card| card_to_highlight(card, timestamps) }
+      logger.info("Converted #{highlights.size} highlights")
+      logger.info("Parsed frontmatter from #{@frontmatter_cache.size} files")
+
+      { "highlights" => highlights }
+    end
+
+    private
+
+    def load_timestamps(db_path)
+      return {} unless db_path && File.exist?(db_path)
+
+      db = SQLite3::Database.new(db_path.to_s)
+      results = db.execute("SELECT card_hash, added_at FROM cards")
+      results.to_h { |row| [row[0], row[1]] }
+    rescue SQLite3::Exception => e
+      logger.warn("Failed to load timestamps from database: #{e.message}")
+      {}
+    ensure
+      db&.close
+    end
+
+    def parse_frontmatter(file_path)
+      return {} unless File.exist?(file_path)
+
+      content = File.read(file_path)
+      return {} unless content.start_with?("---")
+
+      parts = content.split("---", 3)
+      return {} if parts.length < 3
+
+      toml_content = parts[1].strip
+      return {} if toml_content.empty?
+
+      TomlRB.parse(toml_content)
+    rescue TomlRB::ParseError => e
+      logger.warn("Failed to parse frontmatter from #{file_path}: #{e.message}")
+      {}
+    end
+
+    def get_frontmatter(file_path)
+      @frontmatter_cache[file_path] ||= parse_frontmatter(file_path)
+    end
+
+    def card_to_highlight(card, timestamps)
+      content = card["content"]
+      text = if content["cloze"]
+        content["cloze"]["text"]
+      elsif content["basic"]
+        "Q: #{content["basic"]["question"]}\nA: #{content["basic"]["answer"]}"
+      else
+        logger.warn("Unknown card content type: #{content.keys}")
+        return nil
+      end
+
+      file_path = card.dig("location", "filePath")
+      fm = file_path ? get_frontmatter(file_path) : {}
+
+      note_parts = [".hashcard"]
+      fm["tags"]&.each { |tag| note_parts << ".#{tag}" }
+      note = note_parts.join("\n")
+
+      hash = card["hash"]
+      highlighted_at = timestamps[hash]
+
+      {
+        "text" => text,
+        "title" => card["deckName"],
+        "author" => fm["author"] || DEFAULT_AUTHOR,
+        "source_type" => "hashcards#sync#derek",
+        "category" => "articles",
+        "note" => note,
+        "source_url" => fm["source_url"],
+        "image_url" => fm["image_url"],
+        "highlighted_at" => highlighted_at,
+        "highlight_url" => "hashcards://#{hash}"
+      }.compact
+    end
+  end
+end

data/lib/hashcards_readwise/pusher.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "logger"
+
+module HashcardsReadwise
+  class Pusher
+    READWISE_API_URL = "https://readwise.io/api/v2/highlights/"
+
+    attr_reader :logger
+
+    def initialize(token:, logger: Logger.new($stderr, level: Logger::WARN))
+      @token = token
+      @logger = logger
+    end
+
+    def push(highlights)
+      uri = URI.parse(READWISE_API_URL)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.cert_store = OpenSSL::X509::Store.new.tap(&:set_default_paths)
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request["Authorization"] = "Token #{@token}"
+      request["Content-Type"] = "application/json"
+      request.body = JSON.generate(highlights)
+
+      logger.info("POSTing #{highlights["highlights"].size} highlights to Readwise...")
+      response = http.request(request)
+
+      case response
+      when Net::HTTPSuccess
+        logger.info("Success! Response: #{response.body}")
+        { success: true, body: JSON.parse(response.body) }
+      else
+        logger.error("Failed with status #{response.code}")
+        { success: false, code: response.code, body: response.body }
+      end
+    end
+  end
+end

data/lib/hashcards_readwise/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HashcardsReadwise
+  VERSION = "0.1.0"
+end

data/lib/hashcards_readwise.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "hashcards_readwise/version"
+require_relative "hashcards_readwise/converter"
+require_relative "hashcards_readwise/pusher"
+require_relative "hashcards_readwise/cli"
+
+module HashcardsReadwise
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: hashcards_readwise
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Derek Stride
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: toml-rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Convert hashcards exports to Readwise highlights and push them to the
+  Readwise API
+email:
+- derek@stride.host
+executables:
+- hashcards-readwise
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- exe/hashcards-readwise
+- lib/hashcards_readwise.rb
+- lib/hashcards_readwise/cli.rb
+- lib/hashcards_readwise/converter.rb
+- lib/hashcards_readwise/pusher.rb
+- lib/hashcards_readwise/version.rb
+homepage: https://github.com/derekstride/hashcards-readwise
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/derekstride/hashcards-readwise
+  source_code_uri: https://github.com/derekstride/hashcards-readwise
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Sync hashcards flashcards to Readwise
+test_files: []