anki_connect 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 12cd7e1f5f63083dfb30d873a1ba70985b90b2107dcb50de09f151b8414532aa
+  data.tar.gz: 03145b84fe4f8ef9bb7412d2bc65f79dafffcdc9a8758dc0ff84e3b1263f41f1
+SHA512:
+  metadata.gz: 46dffccf988e0497c76c7129d40be5b2becd687615730d3b53ff515eceb2a0ddc93d991929c7de8b56e2fae8d57e7419c21d92059df636a125d5d49ab03ab2d9
+  data.tar.gz: 261dd1bcd832014c623ee8c87ade177c0084e0d578e6808f138e6170a7464110ee98c5e07e20244a6e2b85bef72ddeb1f7e97f71c25a2a481e3eb4830fcd89f2

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vadik49b
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,67 @@
+# 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.
+
+## Requirements
+
+- Ruby 3.4+
+- Anki with Anki-Connect plugin installed
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'anki_connect'
+```
+
+Or install it yourself:
+
+```bash
+gem install anki_connect
+```
+
+## Usage
+
+```ruby
+require 'anki_connect'
+
+# Create a client (default: localhost:8765)
+client = AnkiConnect::Client.new
+
+# Get all decks
+decks = client.deck_names
+
+# Add a new note
+note_id = client.add_note(
+  deck_name: "Default",
+  model_name: "Basic",
+  fields: { Front: "What is Ruby?", Back: "A programming language" },
+  tags: ["programming"]
+)
+
+# Get note details
+notes = client.get_notes(query: "deck:Default")
+# => [{ "noteId" => 1234567890,
+#       "modelName" => "Basic",
+#       "tags" => ["programming"],
+#       "fields" => { "Front" => { "value" => "What is Ruby?", "order" => 0 },
+#                     "Back" => { "value" => "A programming language", "order" => 1 } } }]
+```
+
+For more examples, see the [`examples/`](examples/) directory.
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Open console with gem loaded
+bundle exec rake console
+```
+
+## Acknowledgments
+
+- [Anki-Connect](https://git.sr.ht/~foosoft/anki-connect) by FooSoft for the excellent Anki plugin
+- [Anki](https://apps.ankiweb.net/) for the amazing spaced repetition software

data/lib/anki_connect/cards.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods to query, modify, suspend, and manage individual flashcards.
+    module Cards
+      # 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)
+        request(:getEaseFactors, cards: card_ids)
+      end
+
+      # Sets ease factors for cards.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @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)
+        request(:setEaseFactors, cards: card_ids, easeFactors: factors)
+      end
+
+      # Sets specific database values for a single card.
+      #
+      # @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)
+        request(:setSpecificValueOfCard, card: card_id, keys: fields.keys, newValues: fields.values,
+                                         warning_check: warning_check)
+      end
+
+      # Suspends cards.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @return [Boolean] true if at least one card wasn't already suspended
+      def suspend_cards(card_ids)
+        request(:suspend, cards: card_ids)
+      end
+
+      # Unsuspends cards.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @return [Boolean] true if at least one card was previously suspended
+      def unsuspend_cards(card_ids)
+        request(:unsuspend, cards: card_ids)
+      end
+
+      # Checks suspension status for cards.
+      #
+      # @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
+      end
+
+      # Checks if cards are due for review.
+      #
+      # @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
+      end
+
+      # Gets intervals for cards.
+      #
+      # @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)
+        request(:getIntervals, cards: card_ids, complete: complete)
+      end
+
+      # Searches for cards matching a query.
+      #
+      # @param query [String] Anki search query string
+      # @return [Array<Integer>] Array of card IDs
+      def search_cards(query)
+        request(:findCards, query: query)
+      end
+
+      # Converts card IDs to their parent note IDs.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @return [Array<Integer>] Array of note IDs
+      def get_note_ids(card_ids)
+        request(:cardsToNotes, cards: card_ids)
+      end
+
+      # Gets modification times for cards.
+      #
+      # @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)
+        request(:cardsModTime, cards: card_ids)
+      end
+
+      # Gets detailed information about cards.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @return [Array<Hash>] Array of card objects
+      def get_cards(card_ids)
+        request(:cardsInfo, cards: card_ids)
+      end
+
+      # Resets cards to "new" status.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @return [nil]
+      def forget_cards(card_ids)
+        request(:forgetCards, cards: card_ids)
+      end
+
+      # Makes cards enter "relearning" state.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @return [nil]
+      def relearn_cards(card_ids)
+        request(:relearnCards, cards: card_ids)
+      end
+
+      # Answers cards programmatically.
+      #
+      # @param answers [Array<Hash>] Array of { cardId:, 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)
+      end
+
+      # Sets due date for cards.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @param days [String, Integer] Due date (0=today, 1!=tomorrow, 3-7=random range)
+      # @return [Boolean] true on success
+      def set_due_date(card_ids, days)
+        request(:setDueDate, cards: card_ids, days: days)
+      end
+    end
+  end
+end

data/lib/anki_connect/client.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'uri'
+
+module AnkiConnect
+  # Main client class that includes all API modules and provides
+  # the core request mechanism.
+  class Client
+    include AnkiConnect::Client::Cards
+    include AnkiConnect::Client::Decks
+    include AnkiConnect::Client::Models
+    include AnkiConnect::Client::Notes
+    include AnkiConnect::Client::Media
+    include AnkiConnect::Client::Graphical
+    include AnkiConnect::Client::Statistics
+    include AnkiConnect::Client::Miscellaneous
+
+    # @return [String] AnkiConnect server host
+    attr_reader :host
+    # @return [Integer] AnkiConnect server port
+    attr_reader :port
+    # @return [String, nil] API key for authentication (if configured)
+    attr_reader :api_key
+
+    # 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 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
+      @api_key = api_key
+      @uri = URI("http://#{host}:#{port}")
+    end
+
+    # Makes a request to the AnkiConnect API.
+    # This is the core method used by all API operations.
+    #
+    # @param action [Symbol] The API action to perform
+    # @param params [Hash] Parameters to send with the request
+    # @return [Object] The result from the API
+    # @raise [Error] If the API returns an error
+    def request(action, **params)
+      body = {
+        action: action,
+        version: API_VERSION,
+        params: params
+      }
+      body[:key] = @api_key if @api_key
+
+      response = Net::HTTP.post(
+        @uri,
+        body.to_json,
+        'Content-Type' => 'application/json'
+      )
+
+      result = JSON.parse(response.body)
+
+      raise Error, result['error'] if result['error']
+
+      result['result']
+    end
+
+    private
+
+    attr_reader :uri
+  end
+
+  # Error raised when the AnkiConnect API returns an error response.
+  class Error < StandardError; end
+end

data/lib/anki_connect/decks.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods to create, configure, and manage decks and their settings.
+    module Decks
+      # Gets complete list of deck names.
+      #
+      # @return [Array<String>] Array of deck name strings
+      def deck_names
+        request(:deckNames)
+      end
+
+      # Gets deck names with their IDs.
+      #
+      # @return [Hash] Deck names mapped to IDs
+      def deck_names_and_ids
+        request(:deckNamesAndIds)
+      end
+
+      # Gets deck membership for given cards.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @return [Hash] Deck names mapped to arrays of card IDs
+      def get_decks_for_cards(card_ids)
+        request(:getDecks, cards: card_ids)
+      end
+
+      # Creates a new empty deck.
+      #
+      # @param name [String] Deck name (use :: for hierarchy)
+      # @return [Integer] Deck ID
+      def create_deck(name)
+        request(:createDeck, deck: name)
+      end
+
+      # Moves cards to a different deck.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @param to [String] Target deck name
+      # @return [nil]
+      def move_cards(card_ids, to:)
+        request(:changeDeck, cards: card_ids, deck: to)
+      end
+
+      # Deletes decks by name.
+      #
+      # @param names [Array<String>] Array of deck names
+      # @param cards_too [Boolean] Must be true to confirm deletion
+      # @return [nil]
+      def delete_decks(names, cards_too: true)
+        request(:deleteDecks, decks: names, cardsToo: cards_too)
+      end
+
+      # Gets configuration for a deck.
+      #
+      # @param name [String] Deck name
+      # @return [Hash] Configuration object
+      def get_deck_config(name)
+        request(:getDeckConfig, deck: name)
+      end
+
+      # Saves a deck configuration.
+      #
+      # @param config [Hash] Complete configuration object
+      # @return [Boolean] true on success
+      def save_deck_config(config)
+        request(:saveDeckConfig, config: config)
+      end
+
+      # Sets configuration for decks.
+      #
+      # @param names [Array<String>] Array of deck names
+      # @param config_id [Integer] Configuration group ID
+      # @return [Boolean] true on success
+      def set_deck_config(names, config_id)
+        request(:setDeckConfigId, decks: names, configId: config_id)
+      end
+
+      # Clones a deck configuration.
+      #
+      # @param name [String] Name for new config group
+      # @param clone_from [Integer, nil] Config ID to clone from
+      # @return [Integer, Boolean] New config ID, or false if source doesn't exist
+      def clone_deck_config(name, clone_from: nil)
+        params = { name: name }
+        params[:cloneFrom] = clone_from if clone_from
+        request(:cloneDeckConfigId, **params)
+      end
+
+      # Removes a deck configuration.
+      #
+      # @param config_id [Integer] Configuration group ID
+      # @return [Boolean] true on success
+      def remove_deck_config(config_id)
+        request(:removeDeckConfigId, configId: config_id)
+      end
+
+      # Gets statistics for decks.
+      #
+      # @param names [Array<String>] Array of deck names
+      # @return [Hash] Deck IDs mapped to stats objects
+      def get_deck_stats(names)
+        request(:getDeckStats, decks: names)
+      end
+    end
+  end
+end

data/lib/anki_connect/graphical.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods to interact with Anki's GUI windows and dialogs
+    # (card browser, review screen, editing interfaces).
+    module Graphical
+      # Opens Card Browser dialog and searches for query.
+      #
+      # @param query [String] Search query string
+      # @param reorder_cards [Hash, nil] (optional) Object with order (ascending/descending) and columnId
+      # @return [Array<Integer>] Array of card IDs found
+      def gui_browse(query, reorder_cards: nil)
+        params = { query: query }
+        params[:reorderCards] = reorder_cards if reorder_cards
+        request(:guiBrowse, **params)
+      end
+
+      # Selects a card in the open Card Browser.
+      #
+      # @param card_id [Integer] Card ID
+      # @return [Boolean] true if browser is open, false otherwise
+      def gui_select_card(card_id)
+        request(:guiSelectCard, card: card_id)
+      end
+
+      # Gets selected notes from open Card Browser.
+      #
+      # @return [Array<Integer>] Array of note IDs (empty if browser not open)
+      def gui_selected_notes
+        request(:guiSelectedNotes)
+      end
+
+      # Opens Add Cards dialog with preset values.
+      # Multiple invocations close old window and reopen with new values.
+      #
+      # @param note [Hash] Note object with deckName, modelName, fields, tags, and optional audio/video/picture
+      # @return [Integer] Note ID that would be created if user confirms
+      def gui_add_cards(note)
+        request(:guiAddCards, note: note)
+      end
+
+      # Opens Edit dialog for a note.
+      # Opens edit dialog with Preview, Browse, and navigation buttons.
+      #
+      # @param note_id [Integer] Note ID
+      # @return [nil]
+      def gui_edit_note(note_id)
+        request(:guiEditNote, note: note_id)
+      end
+
+      # Sets fields/tags/deck/model in open Add Note dialog.
+      # Returns error if Add Note dialog not open. Deck/model always replace; fields/tags respect append flag.
+      #
+      # @param note [Hash] Note object with optional deckName, modelName, fields, tags
+      # @param append [Boolean] If true, appends to fields/tags; otherwise replaces (default: false)
+      # @return [Boolean] true on success
+      def gui_add_note_set_data(note, append: false)
+        request(:guiAddNoteSetData, note: note, append: append)
+      end
+
+      # Gets information about current card in review.
+      #
+      # @return [Hash, nil] Object with card info, or nil if not in review mode
+      def gui_current_card
+        request(:guiCurrentCard)
+      end
+
+      # Starts/resets timer for current card.
+      # Useful for accurate time tracking when displaying cards via API.
+      #
+      # @return [Boolean] true
+      def gui_start_card_timer
+        request(:guiStartCardTimer)
+      end
+
+      # Shows question side of current card.
+      #
+      # @return [Boolean] true if in review mode, false otherwise
+      def gui_show_question
+        request(:guiShowQuestion)
+      end
+
+      # Shows answer side of current card.
+      #
+      # @return [Boolean] true if in review mode, false otherwise
+      def gui_show_answer
+        request(:guiShowAnswer)
+      end
+
+      # Answers the current card.
+      # Answer must be displayed before answering.
+      #
+      # @param ease [Integer] Answer button (1-4)
+      # @return [Boolean] true on success, false otherwise
+      def gui_answer_card(ease)
+        request(:guiAnswerCard, ease: ease)
+      end
+
+      # Undoes last action/card.
+      #
+      # @return [Boolean] true on success, false otherwise
+      def gui_undo
+        request(:guiUndo)
+      end
+
+      # Opens Deck Overview dialog for a deck.
+      #
+      # @param name [String] Deck name
+      # @return [Boolean] true on success, false otherwise
+      def gui_deck_overview(name)
+        request(:guiDeckOverview, name: name)
+      end
+
+      # Opens Deck Browser dialog.
+      #
+      # @return [nil]
+      def gui_deck_browser
+        request(:guiDeckBrowser)
+      end
+
+      # Starts review for a deck.
+      #
+      # @param name [String] Deck name
+      # @return [Boolean] true on success, false otherwise
+      def gui_deck_review(name)
+        request(:guiDeckReview, name: name)
+      end
+
+      # Opens Import dialog with optional file path.
+      # Opens file dialog if no path provided. Forward slashes required on Windows. Anki 2.1.52+ only.
+      #
+      # @param path [String, nil] File path to import (optional)
+      # @return [nil]
+      def gui_import_file(path: nil)
+        params = {}
+        params[:path] = path if path
+        request(:guiImportFile, **params)
+      end
+
+      # Schedules graceful Anki shutdown.
+      # Asynchronous - returns immediately without waiting for termination.
+      #
+      # @return [nil]
+      def gui_exit_anki
+        request(:guiExitAnki)
+      end
+
+      # Requests database check.
+      # Returns immediately without waiting for check to complete.
+      #
+      # @return [Boolean] true (always)
+      def gui_check_database
+        request(:guiCheckDatabase)
+      end
+
+      # Plays audio for current card side.
+      #
+      # @return [Boolean] true on success, false otherwise
+      def gui_play_audio
+        request(:guiPlayAudio)
+      end
+    end
+  end
+end

data/lib/anki_connect/media.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods to store, retrieve, and manage media files.
+    module Media
+      # Stores a file in the media folder.
+      #
+      # @param filename [String] File name (prefix with _ to prevent auto-deletion)
+      # @param data [String, nil] Base64-encoded contents
+      # @param path [String, nil] Absolute file path
+      # @param url [String, nil] URL to download from
+      # @param overwrite [Boolean] If true, overwrites existing file
+      # @return [String] Filename (possibly modified if overwrite=false)
+      def store_media(filename, data: nil, path: nil, url: nil, overwrite: true)
+        params = { filename: filename, deleteExisting: overwrite }
+        params[:data] = data if data
+        params[:path] = path if path
+        params[:url] = url if url
+        request(:storeMediaFile, **params)
+      end
+
+      # Retrieves a media file's contents.
+      #
+      # @param filename [String] File name
+      # @return [String, Boolean] Base64-encoded contents, or false if not found
+      def retrieve_media(filename)
+        request(:retrieveMediaFile, filename: filename)
+      end
+
+      # Lists media files matching a pattern.
+      #
+      # @param pattern [String] Glob pattern
+      # @return [Array<String>] Array of filenames
+      def list_media(pattern: '*')
+        request(:getMediaFilesNames, pattern: pattern)
+      end
+
+      # Gets the media folder path.
+      #
+      # @return [String] Absolute path
+      def media_dir_path
+        request(:getMediaDirPath)
+      end
+
+      # Deletes a media file.
+      #
+      # @param filename [String] File name
+      # @return [nil]
+      def delete_media(filename)
+        request(:deleteMediaFile, filename: filename)
+      end
+    end
+  end
+end

data/lib/anki_connect/miscellaneous.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods for API permissions, version checking, profile management,
+    # synchronization, and import/export.
+    module Miscellaneous
+      # Requests API permission (first call to establish trust).
+      # Only method accepting requests from any origin. Shows popup for untrusted origins.
+      #
+      # @return [Hash] Object with permission (granted/denied), and optionally requireApiKey and version
+      def request_permission
+        request(:requestPermission)
+      end
+
+      # Gets AnkiConnect API version.
+      #
+      # @return [Integer] Version number (currently 6)
+      def version
+        request(:version)
+      end
+
+      # Gets information about available APIs.
+      #
+      # @param scopes [Array<String>] Array of scope names (currently only "actions" supported)
+      # @param actions [Array<String>, nil] null for all actions, or array of action names to check (optional)
+      # @return [Hash] Object with scopes used and available actions
+      def api_reflect(scopes, actions: nil)
+        params = { scopes: scopes }
+        params[:actions] = actions if actions
+        request(:apiReflect, **params)
+      end
+
+      # Synchronizes local collection with AnkiWeb.
+      #
+      # @return [nil]
+      def sync
+        request(:sync)
+      end
+
+      # Retrieves list of profiles.
+      #
+      # @return [Array<String>] Array of profile names
+      def profiles
+        request(:getProfiles)
+      end
+
+      # Gets the active profile.
+      #
+      # @return [String] Profile name string
+      def active_profile
+        request(:getActiveProfile)
+      end
+
+      # Switches to specified profile.
+      #
+      # @param name [String] Profile name
+      # @return [Boolean] true on success
+      def load_profile(name)
+        request(:loadProfile, name: name)
+      end
+
+      # Performs multiple actions in one request.
+      #
+      # @param actions [Array<Hash>] Array of action objects (each with action, version, params)
+      # @return [Array] Array of responses in same order
+      def multi(actions)
+        request(:multi, actions: actions)
+      end
+
+      # Exports deck to .apkg format.
+      #
+      # @param deck_name [String] Deck name
+      # @param path [String] Output file path
+      # @param include_scheduling [Boolean] Include scheduling data (default: false)
+      # @return [Boolean] true on success, false otherwise
+      def export_deck(deck_name, path, include_scheduling: false)
+        request(:exportPackage, deck: deck_name, path: path, includeSched: include_scheduling)
+      end
+
+      # Imports .apkg file into collection.
+      #
+      # @param path [String] File path (relative to collection.media folder)
+      # @return [Boolean] true on success, false otherwise
+      def import_deck(path)
+        request(:importPackage, path: path)
+      end
+
+      # Reloads all data from database.
+      #
+      # @return [nil]
+      def reload_collection
+        request(:reloadCollection)
+      end
+    end
+  end
+end

data/lib/anki_connect/models.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods to create and modify note types (models).
+    module Models
+      # Gets complete list of model names.
+      #
+      # @return [Array<String>] Array of model name strings
+      def model_names
+        request(:modelNames)
+      end
+
+      # Gets model names with their IDs.
+      #
+      # @return [Hash] Model names mapped to IDs
+      def model_names_and_ids
+        request(:modelNamesAndIds)
+      end
+
+      # Gets models by ID.
+      #
+      # @param ids [Array<Integer>] Array of model IDs
+      # @return [Array<Hash>] Array of model objects
+      def get_models_by_id(ids)
+        request(:findModelsById, modelIds: ids)
+      end
+
+      # Gets models by name.
+      #
+      # @param names [Array<String>] Array of model names
+      # @return [Array<Hash>] Array of model objects
+      def get_models_by_name(names)
+        request(:findModelsByName, modelNames: names)
+      end
+
+      # Gets field names for a model.
+      #
+      # @param model_name [String] Model name
+      # @return [Array<String>] Array of field names in order
+      def get_field_names(model_name)
+        request(:modelFieldNames, modelName: model_name)
+      end
+
+      # Gets field descriptions for a model.
+      #
+      # @param model_name [String] Model name
+      # @return [Array<String>] Array of description strings
+      def get_field_descriptions(model_name)
+        request(:modelFieldDescriptions, modelName: model_name)
+      end
+
+      # Gets field fonts and sizes for a model.
+      #
+      # @param model_name [String] Model name
+      # @return [Hash] Field names mapped to { font:, size: }
+      def get_field_fonts(model_name)
+        request(:modelFieldFonts, modelName: model_name)
+      end
+
+      # Gets fields used on templates.
+      #
+      # @param model_name [String] Model name
+      # @return [Hash] Template names mapped to [questionFields, answerFields]
+      def get_fields_on_templates(model_name)
+        request(:modelFieldsOnTemplates, modelName: model_name)
+      end
+
+      # Creates a new model.
+      #
+      # @param name [String] Model name
+      # @param fields [Array<String>] Field names in order
+      # @param templates [Array<Hash>] Template objects with Name, Front, Back
+      # @param css [String, nil] CSS styling
+      # @param is_cloze [Boolean] true for cloze type
+      # @return [Hash] Complete model object
+      def create_model(name:, fields:, templates:, css: nil, is_cloze: false)
+        params = { modelName: name, inOrderFields: fields, cardTemplates: templates, isCloze: is_cloze }
+        params[:css] = css if css
+        request(:createModel, **params)
+      end
+
+      # Gets templates for a model.
+      #
+      # @param model_name [String] Model name
+      # @return [Hash] Template names mapped to { Front:, Back: }
+      def get_templates(model_name)
+        request(:modelTemplates, modelName: model_name)
+      end
+
+      # Gets CSS styling for a model.
+      #
+      # @param model_name [String] Model name
+      # @return [Hash] Object with css property
+      def get_styling(model_name)
+        request(:modelStyling, modelName: model_name)
+      end
+
+      # Updates a model's templates and/or CSS.
+      #
+      # @param name [String] Model name
+      # @param templates [Hash, nil] Template names mapped to Front/Back
+      # @param css [String, nil] CSS styling
+      # @return [nil]
+      def update_model(name, templates: nil, css: nil)
+        request(:updateModelTemplates, model: { name: name, templates: templates }) if templates
+        return unless css
+
+        request(:updateModelStyling, model: { name: name, css: css })
+      end
+
+      # Find and replace in model templates/CSS.
+      #
+      # @param model_name [String] Model name
+      # @param find [String] Text to find
+      # @param replace [String] Replacement text
+      # @param front [Boolean] Search front templates
+      # @param back [Boolean] Search back templates
+      # @param css [Boolean] Search CSS
+      # @return [Integer] Number of replacements made
+      def find_and_replace_in_model(model_name:, find:, replace:, front: true, back: true, css: true)
+        request(:findAndReplaceInModels, model: {
+                  modelName: model_name, findText: find, replaceText: replace,
+                  front: front, back: back, css: css
+                })
+      end
+
+      # Renames a template.
+      #
+      # @param model_name [String] Model name
+      # @param from [String] Current template name
+      # @param to [String] New template name
+      # @return [nil]
+      def rename_template(model_name, from:, to:)
+        request(:modelTemplateRename, modelName: model_name, oldTemplateName: from, newTemplateName: to)
+      end
+
+      # Moves a template to a new position.
+      #
+      # @param model_name [String] Model name
+      # @param template_name [String] Template name
+      # @param index [Integer] New position (0-based)
+      # @return [nil]
+      def reposition_template(model_name, template_name, index)
+        request(:modelTemplateReposition, modelName: model_name, templateName: template_name, index: index)
+      end
+
+      # Adds a template to a model.
+      #
+      # @param model_name [String] Model name
+      # @param template [Hash] Template with Name, Front, Back
+      # @return [nil]
+      def add_template(model_name, template)
+        request(:modelTemplateAdd, modelName: model_name, template: template)
+      end
+
+      # Removes a template from a model.
+      #
+      # @param model_name [String] Model name
+      # @param template_name [String] Template name
+      # @return [nil]
+      def remove_template(model_name, template_name)
+        request(:modelTemplateRemove, modelName: model_name, templateName: template_name)
+      end
+
+      # Renames a field.
+      #
+      # @param model_name [String] Model name
+      # @param from [String] Current field name
+      # @param to [String] New field name
+      # @return [nil]
+      def rename_field(model_name, from:, to:)
+        request(:modelFieldRename, modelName: model_name, oldFieldName: from, newFieldName: to)
+      end
+
+      # Moves a field to a new position.
+      #
+      # @param model_name [String] Model name
+      # @param field_name [String] Field name
+      # @param index [Integer] New position (0-based)
+      # @return [nil]
+      def reposition_field(model_name, field_name, index)
+        request(:modelFieldReposition, modelName: model_name, fieldName: field_name, index: index)
+      end
+
+      # Adds a field to a model.
+      #
+      # @param model_name [String] Model name
+      # @param field_name [String] Field name
+      # @param index [Integer, nil] Position (defaults to end)
+      # @return [nil]
+      def add_field(model_name, field_name, index: nil)
+        params = { modelName: model_name, fieldName: field_name }
+        params[:index] = index if index
+        request(:modelFieldAdd, **params)
+      end
+
+      # Removes a field from a model.
+      #
+      # @param model_name [String] Model name
+      # @param field_name [String] Field name
+      # @return [nil]
+      def remove_field(model_name, field_name)
+        request(:modelFieldRemove, modelName: model_name, fieldName: field_name)
+      end
+
+      # Sets font for a field.
+      #
+      # @param model_name [String] Model name
+      # @param field_name [String] Field name
+      # @param font [String] Font name
+      # @return [nil]
+      def set_field_font(model_name, field_name, font)
+        request(:modelFieldSetFont, modelName: model_name, fieldName: field_name, font: font)
+      end
+
+      # Sets font size for a field.
+      #
+      # @param model_name [String] Model name
+      # @param field_name [String] Field name
+      # @param size [Integer] Font size
+      # @return [nil]
+      def set_field_font_size(model_name, field_name, size)
+        request(:modelFieldSetFontSize, modelName: model_name, fieldName: field_name, fontSize: size)
+      end
+
+      # Sets description for a field.
+      #
+      # @param model_name [String] Model name
+      # @param field_name [String] Field name
+      # @param description [String] Description text
+      # @return [Boolean] true on success
+      def set_field_description(model_name, field_name, description)
+        request(:modelFieldSetDescription, modelName: model_name, fieldName: field_name, description: description)
+      end
+    end
+  end
+end

data/lib/anki_connect/notes.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods to create, update, query, and manage notes (which generate cards).
+    module Notes
+      # Creates a new note.
+      #
+      # @param deck_name [String] Target deck
+      # @param model_name [String] Note type
+      # @param fields [Hash] Field names to values
+      # @param tags [Array<String>] Tags (optional)
+      # @param media [Hash, nil] Media to add (audio:, video:, picture: arrays)
+      # @param options [Hash, nil] Options (allowDuplicate, duplicateScope, etc.)
+      # @return [Integer, nil] Note ID on success, nil on failure
+      def add_note(deck_name:, model_name:, fields:, tags: [], media: nil, options: nil)
+        note = { deckName: deck_name, modelName: model_name, fields: fields, tags: tags }
+        note.merge!(media) if media
+        note[:options] = options if options
+        request(:addNote, note: note)
+      end
+
+      # Creates multiple notes.
+      #
+      # @param notes [Array<Hash>] Array of note hashes (same keys as add_note)
+      # @return [Array<Integer, nil>] Array of note IDs (nil for failed notes)
+      def add_notes(notes)
+        request(:addNotes, notes: notes)
+      end
+
+      # Checks if notes can be added.
+      #
+      # @param notes [Array<Hash>] Array of candidate note objects
+      # @param details [Boolean] If true, returns error details (default: false)
+      # @return [Array<Boolean>, Array<Hash>] Array of booleans, or hashes with canAdd and error if details=true
+      def can_add_notes(notes, details: false)
+        if details
+          request(:canAddNotesWithErrorDetail, notes: notes)
+        else
+          request(:canAddNotes, notes: notes)
+        end
+      end
+
+      # Updates a note's fields, tags, or media.
+      #
+      # @param id [Integer] Note ID
+      # @param fields [Hash, nil] Field names to new values
+      # @param tags [Array<String>, nil] New tags (replaces existing)
+      # @param media [Hash, nil] Media to add (audio:, video:, picture: arrays)
+      # @return [nil]
+      def update_note(id, fields: nil, tags: nil, media: nil)
+        note = { id: id }
+        note[:fields] = fields if fields
+        note[:tags] = tags if tags
+        note.merge!(media) if media
+        request(:updateNote, note: note)
+      end
+
+      # Changes a note's model type.
+      #
+      # @param id [Integer] Note ID
+      # @param model_name [String] New model name
+      # @param fields [Hash] New field values
+      # @param tags [Array<String>] New tags
+      # @return [nil]
+      def change_note_model(id, model_name:, fields:, tags:)
+        request(:updateNoteModel, note: { id: id, modelName: model_name, fields: fields, tags: tags })
+      end
+
+      # Gets tags for a note.
+      #
+      # @param note_id [Integer] Note ID
+      # @return [Array<String>] Array of tag strings
+      def get_note_tags(note_id)
+        request(:getNoteTags, note: note_id)
+      end
+
+      # Adds tags to notes.
+      #
+      # @param note_ids [Array<Integer>] Array of note IDs
+      # @param tags [String, Array<String>] Tag(s) to add
+      # @return [nil]
+      def add_tags(note_ids, tags)
+        request(:addTags, notes: note_ids, tags: tags)
+      end
+
+      # Removes tags from notes.
+      #
+      # @param note_ids [Array<Integer>] Array of note IDs
+      # @param tags [String, Array<String>] Tag(s) to remove
+      # @return [nil]
+      def remove_tags(note_ids, tags)
+        request(:removeTags, notes: note_ids, tags: tags)
+      end
+
+      # Gets all tags in collection.
+      #
+      # @return [Array<String>] Array of all tag strings
+      def all_tags
+        request(:getTags)
+      end
+
+      # Removes unused tags from collection.
+      #
+      # @return [nil]
+      def clear_unused_tags
+        request(:clearUnusedTags)
+      end
+
+      # Replaces a tag with another.
+      #
+      # @param from [String] Old tag
+      # @param to [String] New tag
+      # @param note_ids [Array<Integer>, nil] Specific notes, or nil for all notes
+      # @return [nil]
+      def replace_tag(from:, to:, note_ids: nil)
+        if note_ids
+          request(:replaceTags, notes: note_ids, tag_to_replace: from, replace_with_tag: to)
+        else
+          request(:replaceTagsInAllNotes, tag_to_replace: from, replace_with_tag: to)
+        end
+      end
+
+      # Searches for notes matching a query.
+      #
+      # @param query [String] Search query string
+      # @return [Array<Integer>] Array of note IDs
+      def search_notes(query)
+        request(:findNotes, query: query)
+      end
+
+      # Gets detailed information about notes.
+      #
+      # @param note_ids [Array<Integer>, nil] Array of note IDs
+      # @param query [String, nil] Search query string
+      # @return [Array<Hash>] Array of note objects
+      def get_notes(note_ids: nil, query: nil)
+        params = {}
+        params[:notes] = note_ids if note_ids
+        params[:query] = query if query
+        request(:notesInfo, **params)
+      end
+
+      # Gets modification times for notes.
+      #
+      # @param note_ids [Array<Integer>] Array of note IDs
+      # @return [Array<Hash>] Array of objects with noteId and mod
+      def get_notes_mod_time(note_ids)
+        request(:notesModTime, notes: note_ids)
+      end
+
+      # Deletes notes and all associated cards.
+      #
+      # @param note_ids [Array<Integer>] Array of note IDs
+      # @return [nil]
+      def delete_notes(note_ids)
+        request(:deleteNotes, notes: note_ids)
+      end
+
+      # Removes all empty notes.
+      #
+      # @return [nil]
+      def remove_empty_notes
+        request(:removeEmptyNotes)
+      end
+    end
+  end
+end

data/lib/anki_connect/statistics.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods to query review counts, retrieve review history,
+    # and access collection statistics.
+    module Statistics
+      # Gets count of cards reviewed today.
+      # "Today" uses day start time as configured in Anki.
+      #
+      # @return [Integer] Count of cards reviewed today
+      def cards_reviewed_today
+        request(:getNumCardsReviewedToday)
+      end
+
+      # Gets review counts by day.
+      #
+      # @return [Array<Array>] Array of [dateString, count] pairs
+      def cards_reviewed_by_day
+        request(:getNumCardsReviewedByDay)
+      end
+
+      # Gets collection statistics report as HTML.
+      #
+      # @param whole_collection [Boolean] Whether to get stats for whole collection (default: true)
+      # @return [String] HTML string
+      def collection_stats_html(whole_collection: true)
+        request(:getCollectionStatsHTML, wholeCollection: whole_collection)
+      end
+
+      # Gets all card reviews for a deck after a certain time.
+      #
+      # @param deck_name [String] Deck name
+      # @param after [Integer] Unix timestamp (reviews after this time, exclusive)
+      # @return [Array<Array>] Array of 9-tuples: (reviewTime, cardID, usn, buttonPressed, newInterval, previousInterval, newFactor, reviewDuration, reviewType)
+      def get_reviews(deck_name, after:)
+        request(:cardReviews, deck: deck_name, startID: after)
+      end
+
+      # Gets all reviews for specific cards.
+      #
+      # @param card_ids [Array<Integer>] Array of card IDs
+      # @return [Hash] Dictionary mapping card IDs to arrays of review objects with id, usn, ease, ivl, lastIvl, factor, time, type
+      def get_reviews_for_cards(card_ids)
+        request(:getReviewsOfCards, cards: card_ids)
+      end
+
+      # Gets unix time of latest review for a deck.
+      #
+      # @param deck_name [String] Deck name
+      # @return [Integer] Unix timestamp, or 0 if no reviews
+      def latest_review_time(deck_name)
+        request(:getLatestReviewID, deck: deck_name)
+      end
+
+      # Inserts review records into database.
+      #
+      # @param reviews [Array<Array>] Array of 9-tuples (same format as get_reviews output)
+      # @return [nil]
+      def insert_reviews(reviews)
+        request(:insertReviews, reviews: reviews)
+      end
+    end
+  end
+end

data/lib/anki_connect/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  # The version of the anki_connect gem
+  VERSION = '0.1.1'
+
+  # The AnkiConnect API version this gem is compatible with
+  API_VERSION = 6
+end

data/lib/anki_connect.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'anki_connect/version'
+require_relative 'anki_connect/cards'
+require_relative 'anki_connect/decks'
+require_relative 'anki_connect/models'
+require_relative 'anki_connect/notes'
+require_relative 'anki_connect/media'
+require_relative 'anki_connect/graphical'
+require_relative 'anki_connect/statistics'
+require_relative 'anki_connect/miscellaneous'
+require_relative 'anki_connect/client'
+
+# Ruby client for AnkiConnect, enabling external applications to interact
+# with Anki through HTTP.
+#
+# @example Basic usage
+#   client = AnkiConnect::Client.new
+#   decks = client.deck_names
+#   cards = client.search_cards("deck:Default")
+#
+# @see https://foosoft.net/projects/anki-connect/ AnkiConnect Documentation
+module AnkiConnect
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: anki_connect
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- vadik49b
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: AnkiConnect provides a simple HTTP API to communicate with Anki. This
+  Ruby gem is a wrapper around that API.
+email:
+- vadim@boltach.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/anki_connect.rb
+- lib/anki_connect/cards.rb
+- lib/anki_connect/client.rb
+- lib/anki_connect/decks.rb
+- lib/anki_connect/graphical.rb
+- lib/anki_connect/media.rb
+- lib/anki_connect/miscellaneous.rb
+- lib/anki_connect/models.rb
+- lib/anki_connect/notes.rb
+- lib/anki_connect/statistics.rb
+- lib/anki_connect/version.rb
+homepage: https://github.com/vadik49b/anki-connect.rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/vadik49b/anki-connect.rb
+  source_code_uri: https://github.com/vadik49b/anki-connect.rb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.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: Ruby wrapper for the Anki-Connect HTTP API
+test_files: []