anki_connect 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 12cd7e1f5f63083dfb30d873a1ba70985b90b2107dcb50de09f151b8414532aa
-  data.tar.gz: 03145b84fe4f8ef9bb7412d2bc65f79dafffcdc9a8758dc0ff84e3b1263f41f1
+  metadata.gz: 53abf262d0d5f7f09bb3cd8f6230df92cacec2caaefc73aeef6b7ea2abe2e1e4
+  data.tar.gz: bffdfd095a002dab2cab151e3236693504f8c4aa82255a14767e9ee5d495c9d0
 SHA512:
-  metadata.gz: 46dffccf988e0497c76c7129d40be5b2becd687615730d3b53ff515eceb2a0ddc93d991929c7de8b56e2fae8d57e7419c21d92059df636a125d5d49ab03ab2d9
-  data.tar.gz: 261dd1bcd832014c623ee8c87ade177c0084e0d578e6808f138e6170a7464110ee98c5e07e20244a6e2b85bef72ddeb1f7e97f71c25a2a481e3eb4830fcd89f2
+  metadata.gz: 2743f295c008f02987a00b71398860a45002229ba3a20f199405624aa4551e99d505f76b473d7d5b6815a37940bd9efe64035b52db98d728703fa69dc73c6a6c
+  data.tar.gz: d93838989e20753429f684c8141087c9715d922eff948c837794d0e9405836d1ade7d63cd61dde9555c8d3a436661e70334862da8f8f471e346a586235891b9f

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.2.0 - 2026-07-23
+
+- **Breaking:** Redesign the public API around idiomatic Ruby naming and current Anki “note type” terminology, without 0.1 compatibility aliases.
+- Normalize nested wrapper inputs from snake_case to AnkiConnect wire keys.
+- Add wrappers for all nondeprecated actions in AnkiConnect commit `de6e6e1`.
+- Fix the `findAndReplaceInModels` request shape and media-only note updates.
+- Add local argument validation for note selectors, media sources, tags, and parallel card values.
+- Add HTTP and HTTPS endpoint support, configurable timeouts, protocol validation, and typed errors.
+- Require HTTPS when sending API keys to non-loopback endpoints and stop exposing configured keys through a reader.
+- Separate safe unit tests from explicit live integration tests and test Ruby 3.4 and 4.0 in CI.
+
+### Renamed API
+
+- Cards: `get_ease_factors` -> `ease_factors`; `update_card` -> `set_card_values`; `suspended?` -> `card_suspended?` / `card_suspension_statuses`; `due?` -> `card_due?` / `card_due_statuses`; `get_intervals` -> `card_intervals`; `get_note_ids` -> `note_ids_for_cards`; `get_cards_mod_time` -> `card_modification_times`; `get_cards` -> `cards`.
+- Decks: `get_decks_for_cards` -> `decks_for_cards`; `get_deck_config` -> `deck_config`; `get_deck_stats` -> `deck_stats`.
+- Note types: `model_names` -> `note_type_names`; `model_names_and_ids` -> `note_type_names_and_ids`; `get_models_by_id` / `get_models_by_name` -> `note_types_by_id` / `note_types_by_name`; `get_field_names` / `get_field_descriptions` / `get_field_fonts` / `get_fields_on_templates` -> their `note_type_*` forms; `create_model` -> `create_note_type`; `get_templates` / `get_styling` -> `note_type_templates` / `note_type_styling`; `update_model` -> `update_note_type_templates` / `update_note_type_styling`; `find_and_replace_in_model` -> `find_and_replace_in_note_type`; template and field mutation methods now include `note_type` (for example, `rename_template` -> `rename_note_type_template` and `set_field_font` -> `set_note_type_field_font`).
+- Notes: `can_add_notes` -> `note_addable?` / `note_addability` / `note_addability_statuses` / `note_addability_details`; `change_note_model` -> `change_note_type`; `get_note_tags` -> `note_tags`; `all_tags` -> `tags`; `get_notes` -> `notes`; `get_notes_mod_time` -> `note_modification_times`; `remove_empty_notes` -> `remove_unused_note_types`.
+- Media and miscellaneous: `list_media` -> `media_files`; `media_dir_path` -> `media_directory`; `version` -> `api_version`; `api_reflect` -> `api_capabilities`; `multi` -> `batch`; `import_deck` -> `import_package`.
+- Statistics: `get_reviews` -> `reviews`; `get_reviews_for_cards` -> `reviews_for_cards`; `latest_review_time` -> `latest_review_id`.

data/README.md

@@ -1,15 +1,20 @@
 # AnkiConnect Ruby
 
-[AnkiConnect](https://git.sr.ht/~foosoft/anki-connect) provides a simple HTTP API to communicate with Anki. This Ruby gem is a wrapper around that API.
+[AnkiConnect provides a simple HTTP API](https://git.sr.ht/~foosoft/anki-connect) to communicate with Anki. This Ruby gem is a wrapper around that API.
 
-## Requirements
+## Installation
 
-- Ruby 3.4+
-- Anki with Anki-Connect plugin installed
+First, install the [AnkiConnect](https://ankiweb.net/shared/info/2055492159) addon in Anki:
 
-## Installation
+1. Open Anki
+2. Go to Tools → Add-ons (⇧⌘A on macOS)
+3. Click "Get Add-ons..."
+4. Enter the code `2055492159` and click OK
+5. Restart Anki
+
+Anki must be kept running in the background for other applications to use AnkiConnect. You can verify that AnkiConnect is running by visiting `localhost:8765` in your browser. If the server is running, you will see `{ "apiVersion": "AnkiConnect v.6" }`.
 
-Add this line to your application's Gemfile:
+Then add this line to your application's Gemfile:
 
 ```ruby
 gem 'anki_connect'
@@ -35,13 +40,13 @@ decks = client.deck_names
 # Add a new note
 note_id = client.add_note(
   deck_name: "Default",
-  model_name: "Basic",
+  note_type_name: "Basic",
   fields: { Front: "What is Ruby?", Back: "A programming language" },
   tags: ["programming"]
 )
 
 # Get note details
-notes = client.get_notes(query: "deck:Default")
+notes = client.notes(query: "deck:Default")
 # => [{ "noteId" => 1234567890,
 #       "modelName" => "Basic",
 #       "tags" => ["programming"],
@@ -49,7 +54,72 @@ notes = client.get_notes(query: "deck:Default")
 #                     "Back" => { "value" => "A programming language", "order" => 1 } } }]
 ```
 
-For more examples, see the [`examples/`](examples/) directory.
+Convenience wrapper inputs use snake_case and current Anki terminology such as `note_type_name`. Response hashes, raw `request` and `batch` payloads, deck configuration round-trips, field names, and action names preserve AnkiConnect's wire keys, including `"modelName"`.
+
+`batch` is a low-level escape hatch: each element must be a raw AnkiConnect action envelope with `action`, `version`, and wire-format `params`. Prefer the named wrappers, or `request` for a single action.
+
+### Compatibility
+
+This release targets AnkiConnect API version 6 and was verified against official AnkiConnect commit [`de6e6e1`](https://git.sr.ht/~foosoft/anki-connect/commit/de6e6e1b8aaf4ae195eb1d1ff6db5409b99b2a3e). That commit is newer than release `25.11.9.0`; `gui_add_note_set_data` requires this post-release revision or newer. The tested upstream version requires Anki 23.10 or newer.
+
+The low-level `request` method remains available for actions added after this tested upstream revision.
+
+### Enumerable Statuses
+
+Scalar predicates return one Boolean. Methods that query multiple cards return arrays in input order so they compose with Ruby's `Enumerable` API:
+
+```ruby
+statuses = client.card_suspension_statuses(card_ids)
+
+statuses.all?          # every card is suspended
+statuses.any?          # at least one card is suspended
+statuses.none?         # no cards are suspended
+statuses.count(true)   # number of suspended cards
+```
+
+Suspension statuses contain `nil` when a card does not exist. Use `compact` or an explicit comparison when missing cards need different handling.
+
+### Upgrading From 0.1
+
+Version 0.2 is a clean API redesign and does not provide compatibility aliases. Important changes include:
+
+- Convenience wrapper inputs use snake_case throughout, including nested note options, media, templates, answers, and GUI options.
+- Public “model” terminology is replaced by Anki's current “note type” terminology.
+- Mechanical `get_*` names are replaced by resource names such as `notes`, `cards`, `deck_config`, and `reviews`.
+- Scalar card predicates and positional status arrays are separate methods.
+- `version` is now `api_version`; the gem version remains `AnkiConnect::VERSION`.
+- `multi` is now `batch`, `api_reflect` is now `api_capabilities`, and `import_deck` is now `import_package`.
+- The misleading `remove_empty_notes` name is now `remove_unused_note_types`, matching its actual upstream behavior.
+
+### Client Configuration
+
+The client connects to `http://127.0.0.1:8765` by default. A complete endpoint URL, API key, and network timeouts can be configured when needed:
+
+```ruby
+client = AnkiConnect::Client.new(
+  endpoint: "https://anki.example.com/connect",
+  api_key: ENV.fetch("ANKI_CONNECT_API_KEY"),
+  open_timeout: 5,
+  read_timeout: 60,
+  write_timeout: 60
+)
+```
+
+The existing `host:` and `port:` options remain available for HTTP endpoints.
+API keys are allowed over plaintext HTTP only for loopback endpoints; authenticated remote endpoints must use HTTPS. The configured API key is intentionally not exposed through a public reader.
+
+### Errors
+
+All client errors inherit from `AnkiConnect::Error`:
+
+- `AnkiConnect::TransportError` indicates that the HTTP request could not be completed.
+- `AnkiConnect::HTTPError` indicates a non-successful HTTP response and exposes `status` and `body`.
+- `AnkiConnect::ProtocolError` indicates invalid JSON or a response missing the required `result` and `error` fields.
+- `AnkiConnect::APIError` contains an error returned by an AnkiConnect action.
+
+Errors expose the failed `action`. `TransportError` also exposes the underlying exception as `original_error`.
+
+For a complete list of all API methods, see the [RubyDoc documentation](https://rubydoc.info/gems/anki_connect). More examples in the [`examples/`](examples/) directory.
 
 ## Development
 
@@ -61,6 +131,24 @@ bundle install
 bundle exec rake console
 ```
 
+### Testing
+
+Run the unit tests, which do not require Anki:
+
+```bash
+bundle exec rake
+# or explicitly
+bundle exec rake test:unit
+```
+
+Run the integration tests against a running AnkiConnect instance:
+
+```bash
+bundle exec rake test:integration
+```
+
+Integration tests modify the collection in the active Anki profile. They use a uniquely named temporary deck and only remove the deck when its creation succeeds, but a disposable profile is recommended.
+
 ## Acknowledgments
 
 - [Anki-Connect](https://git.sr.ht/~foosoft/anki-connect) by FooSoft for the excellent Anki plugin

data/examples/add_elevenlabs_tts_audio_to_cloze_cards.rb

@@ -0,0 +1,75 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Add ElevenLabs TTS audio to Anki cloze cards
+#
+# I use Anki to learn Spanish with cloze deletion cards for phrases.
+# To train my ear for pronunciation, I want audio for each phrase.
+# This script uses ElevenLabs TTS API to generate speech and attach it to cards.
+#
+# Configuration via environment variables:
+#   ELEVENLABS_API_KEY - Your ElevenLabs API key
+#   ELEVENLABS_VOICE_ID - Voice ID to use
+#
+# Usage:
+# ELEVENLABS_API_KEY=your_key ELEVENLABS_VOICE_ID=voice_id ruby examples/add_elevenlabs_tts_audio_to_cloze_cards.rb
+
+require 'net/http'
+require 'json'
+require 'uri'
+require 'anki_connect'
+
+ELEVENLABS_API_KEY = ENV.fetch('ELEVENLABS_API_KEY')
+ELEVENLABS_VOICE_ID = ENV.fetch('ELEVENLABS_VOICE_ID')
+
+if ELEVENLABS_API_KEY.strip.empty? || ELEVENLABS_VOICE_ID.strip.empty?
+  raise 'ELEVENLABS_API_KEY and ELEVENLABS_VOICE_ID are required'
+end
+
+SPEECH_FOLDER = 'tmp'
+
+client = AnkiConnect::Client.new
+client.sync
+
+# Customize this query for your deck and note type
+notes = client.notes(query: 'deck:Spanish note:Cloze -tag:fix')
+puts "Found #{notes.length} cloze note(s)"
+
+Dir.mkdir(SPEECH_FOLDER) unless Dir.exist?(SPEECH_FOLDER)
+
+notes.each_with_index do |note, index|
+  print "\rProcessing #{index + 1}/#{notes.length}..."
+
+  text_field = note.dig('fields', 'Text', 'value')
+  next if text_field.nil? || text_field.strip.empty?
+
+  back_extra = note.dig('fields', 'Back Extra', 'value') || ''
+  already_has_audio = back_extra.include?('[sound:')
+  next if already_has_audio
+
+  # Extract full phrase from cloze markup: {{c1::answer::hint}} -> answer
+  answer_text = text_field.gsub(/\{\{c\d+::([^:}]+)(?:::[^}]+)?\}\}/, '\1').gsub(/<[^>]+>/, '').gsub(/\s+/, ' ').strip
+
+  safe_text = answer_text.gsub(/[^a-zA-Z0-9]+/, '_').gsub(/^_+|_+$/, '')[0, 50]
+  filename = "elevenlabs_#{note['noteId']}_#{safe_text}.mp3"
+  filepath = File.expand_path(File.join(SPEECH_FOLDER, filename))
+
+  unless File.exist?(filepath)
+    uri = URI("https://api.elevenlabs.io/v1/text-to-speech/#{ELEVENLABS_VOICE_ID}")
+    request = Net::HTTP::Post.new(uri)
+    request['Accept'] = 'audio/mpeg'
+    request['xi-api-key'] = ELEVENLABS_API_KEY
+    request['Content-Type'] = 'application/json'
+    request.body = { text: answer_text, model_id: 'eleven_multilingual_v2', language_code: 'es' }.to_json
+
+    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
+    raise "ElevenLabs API error: #{response.code} - #{response.body}" unless response.code == '200'
+
+    File.binwrite(filepath, response.body)
+  end
+
+  client.store_media(filename, path: filepath)
+  client.update_note(note['noteId'], fields: { 'Back Extra' => "#{back_extra}[sound:#{filename}]" })
+end
+
+puts "\nDone!"

data/examples/basic_usage.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'anki_connect'
+
+# Create a client
+client = AnkiConnect::Client.new
+
+# Get all decks
+puts 'Available decks:'
+client.deck_names.each { |deck| puts "  - #{deck}" }
+
+# Get all note types
+puts "\nAvailable note types:"
+client.note_type_names.each { |note_type| puts "  - #{note_type}" }
+
+# Add a new note
+note_id = client.add_note(
+  deck_name: 'Default',
+  note_type_name: 'Basic',
+  fields: { Front: 'What is the capital of France?', Back: 'Paris' },
+  tags: %w[geography europe]
+)
+
+puts "\nCreated note with ID: #{note_id}"
+
+# Find the note we just created
+note_ids = client.search_notes('tag:geography')
+puts "\nFound #{note_ids.length} notes with tag 'geography'"
+
+# Get detailed info about the notes
+notes = client.notes(note_ids: note_ids)
+notes.each do |note|
+  puts "\nNote #{note['noteId']}:"
+  puts "  Note type: #{note['modelName']}"
+  puts "  Tags: #{note['tags'].join(', ')}"
+  note['fields'].each do |field_name, field_data|
+    puts "  #{field_name}: #{field_data['value']}"
+  end
+end
+
+# Get statistics
+reviewed_today = client.cards_reviewed_today
+puts "\nCards reviewed today: #{reviewed_today}"
+
+# Clean up - delete the note we created
+client.delete_notes([note_id])
+puts "\nDeleted note #{note_id}"

data/lib/anki_connect/cards.rb

@@ -4,11 +4,17 @@ module AnkiConnect
   class Client
     # Methods to query, modify, suspend, and manage individual flashcards.
     module Cards
+      ANSWER_KEYS = {
+        'card_id' => :cardId,
+        'ease' => :ease
+      }.freeze
+      private_constant :ANSWER_KEYS
+
       # Gets ease factors for cards.
       #
       # @param card_ids [Array<Integer>] Array of card IDs
-      # @return [Array<Integer>] Array of ease factor values
-      def get_ease_factors(card_ids)
+      # @return [Array<Integer, nil>] Ease factors; nil for missing cards
+      def ease_factors(card_ids)
         request(:getEaseFactors, cards: card_ids)
       end
 
@@ -18,16 +24,19 @@ module AnkiConnect
       # @param factors [Array<Integer>] Array of ease factor values
       # @return [Array<Boolean>] Array indicating success for each card
       def set_ease_factors(card_ids, factors)
+        raise ArgumentError, 'card_ids and factors must have the same length' unless card_ids.length == factors.length
+
         request(:setEaseFactors, cards: card_ids, easeFactors: factors)
       end
 
-      # Sets specific database values for a single card.
+      # Sets raw database values for a single card.
+      # This low-level operation can corrupt scheduling data when used incorrectly.
       #
       # @param card_id [Integer] Card ID
       # @param fields [Hash] Database field names to new values
       # @param warning_check [Boolean] Must be true for certain risky keys
-      # @return [Array<Boolean>] Array indicating success for each field
-      def update_card(card_id, fields, warning_check: false)
+      # @return [Array, Boolean] Upstream result for the single card update
+      def set_card_values(card_id, fields, warning_check: false)
         request(:setSpecificValueOfCard, card: card_id, keys: fields.keys, newValues: fields.values,
                                          warning_check: warning_check)
       end
@@ -43,33 +52,41 @@ module AnkiConnect
       # Unsuspends cards.
       #
       # @param card_ids [Array<Integer>] Array of card IDs
-      # @return [Boolean] true if at least one card was previously suspended
+      # @return [nil] Current AnkiConnect does not return the underlying result
       def unsuspend_cards(card_ids)
         request(:unsuspend, cards: card_ids)
       end
 
-      # Checks suspension status for cards.
+      # Checks whether one card is suspended.
       #
-      # @param card_ids [Integer, Array<Integer>] Single card ID or array
-      # @return [Boolean, Array<Boolean, nil>] Boolean for single, array for multiple
-      def suspended?(card_ids)
-        if card_ids.is_a?(Array)
-          request(:areSuspended, cards: card_ids)
-        else
-          request(:suspended, card: card_ids)
-        end
+      # @param card_id [Integer] Card ID
+      # @return [Boolean] Suspension status
+      def card_suspended?(card_id)
+        request(:suspended, card: card_id)
       end
 
-      # Checks if cards are due for review.
+      # Gets suspension status for each card, preserving input order.
       #
-      # @param card_ids [Integer, Array<Integer>] Single card ID or array
-      # @return [Boolean, Array<Boolean>] Boolean for single, array for multiple
-      def due?(card_ids)
-        if card_ids.is_a?(Array)
-          request(:areDue, cards: card_ids)
-        else
-          request(:areDue, cards: [card_ids]).first
-        end
+      # @param card_ids [Array<Integer>] Card IDs
+      # @return [Array<Boolean, nil>] Statuses; nil for missing cards
+      def card_suspension_statuses(card_ids)
+        request(:areSuspended, cards: card_ids)
+      end
+
+      # Checks whether one card is due for review.
+      #
+      # @param card_id [Integer] Card ID
+      # @return [Boolean] Due status
+      def card_due?(card_id)
+        request(:areDue, cards: [card_id]).first
+      end
+
+      # Gets due status for each card, preserving input order.
+      #
+      # @param card_ids [Array<Integer>] Card IDs
+      # @return [Array<Boolean>] Due statuses
+      def card_due_statuses(card_ids)
+        request(:areDue, cards: card_ids)
       end
 
       # Gets intervals for cards.
@@ -77,7 +94,7 @@ module AnkiConnect
       # @param card_ids [Array<Integer>] Array of card IDs
       # @param complete [Boolean] If true, returns all intervals
       # @return [Array<Integer>, Array<Array<Integer>>] Intervals
-      def get_intervals(card_ids, complete: false)
+      def card_intervals(card_ids, complete: false)
         request(:getIntervals, cards: card_ids, complete: complete)
       end
 
@@ -89,11 +106,11 @@ module AnkiConnect
         request(:findCards, query: query)
       end
 
-      # Converts card IDs to their parent note IDs.
+      # Gets unique parent note IDs for cards.
       #
       # @param card_ids [Array<Integer>] Array of card IDs
-      # @return [Array<Integer>] Array of note IDs
-      def get_note_ids(card_ids)
+      # @return [Array<Integer>] Unordered, unique note IDs
+      def note_ids_for_cards(card_ids)
         request(:cardsToNotes, cards: card_ids)
       end
 
@@ -101,7 +118,7 @@ module AnkiConnect
       #
       # @param card_ids [Array<Integer>] Array of card IDs
       # @return [Array<Hash>] Array of objects with cardId and mod
-      def get_cards_mod_time(card_ids)
+      def card_modification_times(card_ids)
         request(:cardsModTime, cards: card_ids)
       end
 
@@ -109,7 +126,7 @@ module AnkiConnect
       #
       # @param card_ids [Array<Integer>] Array of card IDs
       # @return [Array<Hash>] Array of card objects
-      def get_cards(card_ids)
+      def cards(card_ids)
         request(:cardsInfo, cards: card_ids)
       end
 
@@ -131,10 +148,17 @@ module AnkiConnect
 
       # Answers cards programmatically.
       #
-      # @param answers [Array<Hash>] Array of { cardId:, ease: } (1=Again, 2=Hard, 3=Good, 4=Easy)
+      # @param answers [Array<Hash>] Array of { card_id:, ease: } (1=Again, 2=Hard, 3=Good, 4=Easy)
       # @return [Array<Boolean>] Array indicating if each card exists
       def answer_cards(answers)
-        request(:answerCards, answers: answers)
+        normalized = answers.map do |answer|
+          answer = normalize_keys(answer, ANSWER_KEYS, name: 'answer')
+          missing_keys = ANSWER_KEYS.values.reject { |key| answer.key?(key) }
+          raise ArgumentError, "missing answer keys: #{missing_keys.join(', ')}" unless missing_keys.empty?
+
+          answer
+        end
+        request(:answerCards, answers: normalized)
       end
 
       # Sets due date for cards.

data/lib/anki_connect/client.rb

@@ -3,14 +3,26 @@
 require 'net/http'
 require 'json'
 require 'uri'
+require 'ipaddr'
+require_relative 'version'
+require_relative 'params'
+require_relative 'cards'
+require_relative 'decks'
+require_relative 'note_types'
+require_relative 'notes'
+require_relative 'media'
+require_relative 'graphical'
+require_relative 'statistics'
+require_relative 'miscellaneous'
 
 module AnkiConnect
   # Main client class that includes all API modules and provides
   # the core request mechanism.
   class Client
+    include AnkiConnect::Client::Params
     include AnkiConnect::Client::Cards
     include AnkiConnect::Client::Decks
-    include AnkiConnect::Client::Models
+    include AnkiConnect::Client::NoteTypes
     include AnkiConnect::Client::Notes
     include AnkiConnect::Client::Media
     include AnkiConnect::Client::Graphical
@@ -21,19 +33,37 @@ module AnkiConnect
     attr_reader :host
     # @return [Integer] AnkiConnect server port
     attr_reader :port
-    # @return [String, nil] API key for authentication (if configured)
-    attr_reader :api_key
+    # @return [URI::HTTP, URI::HTTPS] AnkiConnect endpoint
+    attr_reader :endpoint
+    # @return [Numeric] Connection timeout in seconds
+    attr_reader :open_timeout
+    # @return [Numeric] Response timeout in seconds
+    attr_reader :read_timeout
+    # @return [Numeric] Request write timeout in seconds
+    attr_reader :write_timeout
 
     # Creates a new AnkiConnect client.
     #
     # @param host [String] AnkiConnect server host (default: "127.0.0.1")
     # @param port [Integer] AnkiConnect server port (default: 8765)
+    # @param endpoint [String, URI, nil] Complete HTTP or HTTPS endpoint; overrides host and port
     # @param api_key [String, nil] Optional API key for authentication
-    def initialize(host: '127.0.0.1', port: 8765, api_key: nil)
-      @host = host
-      @port = port
+    # @param open_timeout [Numeric] Connection timeout in seconds
+    # @param read_timeout [Numeric] Response timeout in seconds
+    # @param write_timeout [Numeric] Request write timeout in seconds
+    def initialize(
+      host: '127.0.0.1', port: 8765, endpoint: nil, api_key: nil,
+      open_timeout: 5, read_timeout: 60, write_timeout: 60
+    )
+      @endpoint = parse_endpoint(endpoint ? endpoint.to_s : "http://#{host}:#{port}")
+      validate_endpoint!
+      validate_api_key_transport!(api_key)
+      @host = @endpoint.hostname
+      @port = @endpoint.port
       @api_key = api_key
-      @uri = URI("http://#{host}:#{port}")
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @write_timeout = write_timeout
     end
 
     # Makes a request to the AnkiConnect API.
@@ -51,24 +81,121 @@ module AnkiConnect
       }
       body[:key] = @api_key if @api_key
 
-      response = Net::HTTP.post(
-        @uri,
-        body.to_json,
-        'Content-Type' => 'application/json'
-      )
+      response = perform_request(body.to_json, action)
+      unless response.code.to_i.between?(200, 299)
+        raise HTTPError.new(
+          "AnkiConnect returned HTTP #{response.code}",
+          action: action,
+          status: response.code.to_i,
+          body: response.body
+        )
+      end
 
-      result = JSON.parse(response.body)
+      result = parse_response(response.body, action)
 
-      raise Error, result['error'] if result['error']
+      raise APIError.new(result['error'].to_s, action: action) unless result['error'].nil?
 
       result['result']
     end
 
     private
 
-    attr_reader :uri
+    def perform_request(body, action)
+      http = Net::HTTP.new(endpoint.hostname, endpoint.port)
+      http.use_ssl = endpoint.scheme == 'https'
+      http.open_timeout = open_timeout
+      http.read_timeout = read_timeout
+      http.write_timeout = write_timeout
+
+      request = Net::HTTP::Post.new(endpoint.request_uri)
+      request['Content-Type'] = 'application/json'
+      request.body = body
+
+      http.start { |connection| connection.request(request) }
+    rescue StandardError => e
+      raise TransportError.new(e.message, action: action, original_error: e), cause: e
+    end
+
+    def parse_response(body, action)
+      result = JSON.parse(body)
+      unless result.is_a?(Hash) && result.key?('result') && result.key?('error')
+        raise ProtocolError.new('AnkiConnect response must contain result and error', action: action, body: body)
+      end
+
+      result
+    rescue JSON::ParserError => e
+      raise ProtocolError.new('AnkiConnect returned invalid JSON', action: action, body: body), cause: e
+    end
+
+    def validate_endpoint!
+      return if endpoint.is_a?(URI::HTTP) && endpoint.host
+
+      raise ArgumentError, 'endpoint must be an HTTP or HTTPS URL with a host'
+    end
+
+    def validate_api_key_transport!(api_key)
+      return if api_key.nil? || endpoint.scheme == 'https' || loopback_endpoint?
+
+      raise ArgumentError, 'api_key requires HTTPS for non-loopback endpoints'
+    end
+
+    def loopback_endpoint?
+      host = endpoint.hostname.downcase
+      return true if host == 'localhost'
+
+      IPAddr.new(host).loopback?
+    rescue IPAddr::InvalidAddressError
+      false
+    end
+
+    def parse_endpoint(value)
+      URI(value)
+    rescue URI::InvalidURIError => e
+      raise ArgumentError, 'endpoint must be an HTTP or HTTPS URL with a host', cause: e
+    end
+  end
+
+  # Base error for AnkiConnect request failures.
+  class Error < StandardError
+    attr_reader :action
+
+    def initialize(message = nil, action: nil)
+      @action = action
+      super(message)
+    end
+  end
+
+  # Error raised when the HTTP request cannot be completed.
+  class TransportError < Error
+    attr_reader :original_error
+
+    def initialize(message = nil, original_error:, **context)
+      @original_error = original_error
+      super(message, **context)
+    end
+  end
+
+  # Error raised for a non-successful HTTP response.
+  class HTTPError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status:, body:, **context)
+      @status = status
+      @body = body
+      super(message, **context)
+    end
+  end
+
+  # Error raised when the response does not follow the AnkiConnect protocol.
+  class ProtocolError < Error
+    attr_reader :body
+
+    def initialize(message = nil, body:, **context)
+      @body = body
+      super(message, **context)
+    end
   end
 
-  # Error raised when the AnkiConnect API returns an error response.
-  class Error < StandardError; end
+  # Error returned by an AnkiConnect action.
+  class APIError < Error; end
 end