anki_connect 0.1.1 → 0.2.0

data/lib/anki_connect/decks.rb

@@ -18,11 +18,19 @@ module AnkiConnect
         request(:deckNamesAndIds)
       end
 
+      # Gets a deck name by ID.
+      #
+      # @param deck_id [Integer] Deck ID
+      # @return [String] Deck name
+      def deck_name_from_id(deck_id)
+        request(:deckNameFromId, deckId: deck_id)
+      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)
+      def decks_for_cards(card_ids)
         request(:getDecks, cards: card_ids)
       end
 
@@ -48,15 +56,17 @@ module AnkiConnect
       # @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)
+      def delete_decks(names, cards_too:)
+        raise ArgumentError, 'cards_too must be true to delete decks' unless 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)
+      # @return [Hash, false] Configuration object, or false when the deck does not exist
+      def deck_config(name)
         request(:getDeckConfig, deck: name)
       end
 
@@ -100,7 +110,7 @@ module AnkiConnect
       #
       # @param names [Array<String>] Array of deck names
       # @return [Hash] Deck IDs mapped to stats objects
-      def get_deck_stats(names)
+      def deck_stats(names)
         request(:getDeckStats, decks: names)
       end
     end

data/lib/anki_connect/graphical.rb

@@ -5,14 +5,27 @@ module AnkiConnect
     # Methods to interact with Anki's GUI windows and dialogs
     # (card browser, review screen, editing interfaces).
     module Graphical
+      REORDER_CARD_KEYS = {
+        'order' => :order,
+        'column_id' => :columnId
+      }.freeze
+      private_constant :REORDER_CARD_KEYS
+
       # 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
+      # @param query [String, nil] Search query string; nil preserves the current browser search
+      # @param reorder_cards [Hash, nil] Object with order and column_id
       # @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
+      def gui_browse(query = nil, reorder_cards: nil)
+        params = {}
+        params[:query] = query unless query.nil?
+        if reorder_cards
+          normalized = normalize_keys(reorder_cards, REORDER_CARD_KEYS, name: 'reorder_cards')
+          missing_keys = REORDER_CARD_KEYS.values.reject { |key| normalized.key?(key) }
+          raise ArgumentError, "missing reorder_cards keys: #{missing_keys.join(', ')}" unless missing_keys.empty?
+
+          params[:reorderCards] = normalized
+        end
         request(:guiBrowse, **params)
       end
 
@@ -34,10 +47,12 @@ module AnkiConnect
       # 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
+      # @param note [Hash, nil] Optional note preset
       # @return [Integer] Note ID that would be created if user confirms
-      def gui_add_cards(note)
-        request(:guiAddCards, note: note)
+      def gui_add_cards(note = nil)
+        params = {}
+        params[:note] = normalize_gui_note(note) unless note.nil?
+        request(:guiAddCards, **params)
       end
 
       # Opens Edit dialog for a note.
@@ -52,16 +67,24 @@ module AnkiConnect
       # 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 note [Hash] Note with optional deck_name, note_type_name, fields, tags, and media
       # @param append [Boolean] If true, appends to fields/tags; otherwise replaces (default: false)
-      # @return [Boolean] true on success
+      # @return [Boolean, Hash] true on success, or an error hash when the dialog is closed
       def gui_add_note_set_data(note, append: false)
-        request(:guiAddNoteSetData, note: note, append: append)
+        request(:guiAddNoteSetData, note: normalize_gui_note(note), append: append)
+      end
+
+      # Checks whether the review screen has an active card.
+      #
+      # @return [Boolean] true when review is active
+      def gui_review_active?
+        request(:guiReviewActive)
       end
 
       # Gets information about current card in review.
       #
-      # @return [Hash, nil] Object with card info, or nil if not in review mode
+      # @return [Hash] Current card information
+      # @raise [APIError] If review is not active
       def gui_current_card
         request(:guiCurrentCard)
       end
@@ -69,7 +92,7 @@ module AnkiConnect
       # Starts/resets timer for current card.
       # Useful for accurate time tracking when displaying cards via API.
       #
-      # @return [Boolean] true
+      # @return [Boolean] false when review is not active or no card is available
       def gui_start_card_timer
         request(:guiStartCardTimer)
       end

data/lib/anki_connect/media.rb

@@ -10,13 +10,16 @@ module AnkiConnect
       # @param data [String, nil] Base64-encoded contents
       # @param path [String, nil] Absolute file path
       # @param url [String, nil] URL to download from
+      # @param skip_hash [String, nil] MD5 hash that causes an identical upload to be skipped
       # @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)
+      # @return [String, nil] Filename, or nil when skipped by hash
+      def store_media(filename, data: nil, path: nil, url: nil, skip_hash: nil, overwrite: true)
+        sources = { data: data, path: path, url: url }.reject { |_key, value| value.nil? }
+        raise ArgumentError, 'provide exactly one of data, path, or url' unless sources.one?
+
         params = { filename: filename, deleteExisting: overwrite }
-        params[:data] = data if data
-        params[:path] = path if path
-        params[:url] = url if url
+        params.merge!(sources)
+        params[:skipHash] = skip_hash unless skip_hash.nil?
         request(:storeMediaFile, **params)
       end
 
@@ -32,14 +35,14 @@ module AnkiConnect
       #
       # @param pattern [String] Glob pattern
       # @return [Array<String>] Array of filenames
-      def list_media(pattern: '*')
+      def media_files(pattern: '*')
         request(:getMediaFilesNames, pattern: pattern)
       end
 
       # Gets the media folder path.
       #
       # @return [String] Absolute path
-      def media_dir_path
+      def media_directory
         request(:getMediaDirPath)
       end
 

data/lib/anki_connect/miscellaneous.rb

@@ -8,7 +8,7 @@ module AnkiConnect
       # 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
+      # @return [Hash] Object with permission and optionally requireApikey and version
       def request_permission
         request(:requestPermission)
       end
@@ -16,7 +16,7 @@ module AnkiConnect
       # Gets AnkiConnect API version.
       #
       # @return [Integer] Version number (currently 6)
-      def version
+      def api_version
         request(:version)
       end
 
@@ -25,7 +25,7 @@ module AnkiConnect
       # @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)
+      def api_capabilities(scopes, actions: nil)
         params = { scopes: scopes }
         params[:actions] = actions if actions
         request(:apiReflect, **params)
@@ -55,16 +55,18 @@ module AnkiConnect
       # Switches to specified profile.
       #
       # @param name [String] Profile name
-      # @return [Boolean] true on success
+      # @return [Boolean] true on success, false when the profile does not exist
       def load_profile(name)
         request(:loadProfile, name: name)
       end
 
       # Performs multiple actions in one request.
+      # Unlike convenience wrappers, each action uses AnkiConnect's raw wire keys.
       #
-      # @param actions [Array<Hash>] Array of action objects (each with action, version, params)
+      # @param actions [Array<Hash>] Raw wire action objects with action, version, and params
       # @return [Array] Array of responses in same order
-      def multi(actions)
+      # @see #request Use request for individual actions
+      def batch(actions)
         request(:multi, actions: actions)
       end
 
@@ -80,9 +82,9 @@ module AnkiConnect
 
       # Imports .apkg file into collection.
       #
-      # @param path [String] File path (relative to collection.media folder)
+      # @param path [String] Package file path on the Anki host
       # @return [Boolean] true on success, false otherwise
-      def import_deck(path)
+      def import_package(path)
         request(:importPackage, path: path)
       end
 

data/lib/anki_connect/note_types.rb

@@ -0,0 +1,293 @@
+# frozen_string_literal: true
+
+module AnkiConnect
+  class Client
+    # Methods to create and modify note types.
+    module NoteTypes
+      # Gets complete list of note type names.
+      #
+      # @return [Array<String>] Array of note type names
+      def note_type_names
+        request(:modelNames)
+      end
+
+      # Gets note type names with their IDs.
+      #
+      # @return [Hash] Note type names mapped to IDs
+      def note_type_names_and_ids
+        request(:modelNamesAndIds)
+      end
+
+      # Gets a note type name by ID.
+      #
+      # @param note_type_id [Integer] Note type ID
+      # @return [String] Note type name
+      def note_type_name_from_id(note_type_id)
+        request(:modelNameFromId, modelId: note_type_id)
+      end
+
+      # Gets note types by ID.
+      #
+      # @param ids [Array<Integer>] Array of note type IDs
+      # @return [Array<Hash>] Array of note type objects
+      def note_types_by_id(ids)
+        request(:findModelsById, modelIds: ids)
+      end
+
+      # Gets note types by name.
+      #
+      # @param names [Array<String>] Array of note type names
+      # @return [Array<Hash>] Array of note type objects
+      def note_types_by_name(names)
+        request(:findModelsByName, modelNames: names)
+      end
+
+      # Gets field names for a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @return [Array<String>] Array of field names in order
+      def note_type_field_names(note_type_name)
+        request(:modelFieldNames, modelName: note_type_name)
+      end
+
+      # Gets field descriptions for a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @return [Array<String>] Array of description strings
+      def note_type_field_descriptions(note_type_name)
+        request(:modelFieldDescriptions, modelName: note_type_name)
+      end
+
+      # Gets field fonts and sizes for a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @return [Hash] Field names mapped to { font:, size: }
+      def note_type_field_fonts(note_type_name)
+        request(:modelFieldFonts, modelName: note_type_name)
+      end
+
+      # Gets fields used on templates.
+      #
+      # @param note_type_name [String] Note type name
+      # @return [Hash] Template names mapped to [questionFields, answerFields]
+      def note_type_fields_on_templates(note_type_name)
+        request(:modelFieldsOnTemplates, modelName: note_type_name)
+      end
+
+      # Creates a new note type.
+      #
+      # @param name [String] Note type name
+      # @param fields [Array<String>] Field names in order
+      # @param templates [Array<Hash>] Templates with name, front, and back
+      # @param css [String, nil] CSS styling
+      # @param cloze [Boolean] true for a cloze note type
+      # @return [Hash] Complete note type object
+      def create_note_type(name:, fields:, templates:, css: nil, cloze: false)
+        params = {
+          modelName: name,
+          inOrderFields: fields,
+          cardTemplates: templates.map { |template| normalize_template(template) },
+          isCloze: cloze
+        }
+        params[:css] = css if css
+        request(:createModel, **params)
+      end
+
+      # Gets templates for a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @return [Hash] Template names mapped to { Front:, Back: }
+      def note_type_templates(note_type_name)
+        request(:modelTemplates, modelName: note_type_name)
+      end
+
+      # Gets CSS styling for a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @return [Hash] Object with css property
+      def note_type_styling(note_type_name)
+        request(:modelStyling, modelName: note_type_name)
+      end
+
+      # Updates templates for a note type.
+      #
+      # @param name [String] Note type name
+      # @param templates [Hash] Template names mapped to optional front/back values
+      # @return [nil]
+      def update_note_type_templates(name, templates)
+        request(:updateModelTemplates, model: { name: name, templates: normalize_template_updates(templates) })
+      end
+
+      # Updates CSS styling for a note type.
+      #
+      # @param name [String] Note type name
+      # @param css [String] CSS styling
+      # @return [nil]
+      def update_note_type_styling(name, css:)
+        request(:updateModelStyling, model: { name: name, css: css })
+      end
+
+      # Find and replace in note type templates/CSS.
+      #
+      # @param note_type_name [String, nil] Note type name, or nil for all note types
+      # @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 note types changed
+      def find_and_replace_in_note_type(note_type_name: nil, find:, replace:, front: true, back: true, css: true)
+        request(
+          :findAndReplaceInModels,
+          modelName: note_type_name,
+          findText: find,
+          replaceText: replace,
+          front: front,
+          back: back,
+          css: css
+        )
+      end
+
+      # Renames a template.
+      #
+      # @param note_type_name [String] Note type name
+      # @param from [String] Current template name
+      # @param to [String] New template name
+      # @return [nil]
+      def rename_note_type_template(note_type_name, from:, to:)
+        request(:modelTemplateRename, modelName: note_type_name, oldTemplateName: from, newTemplateName: to)
+      end
+
+      # Moves a template to a new position.
+      #
+      # @param note_type_name [String] Note type name
+      # @param template_name [String] Template name
+      # @param index [Integer] New position (0-based)
+      # @return [nil]
+      def reposition_note_type_template(note_type_name, template_name, index)
+        request(:modelTemplateReposition, modelName: note_type_name, templateName: template_name, index: index)
+      end
+
+      # Adds a template to a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @param template [Hash] Template with Name, Front, Back
+      # @return [nil]
+      def add_note_type_template(note_type_name, template)
+        request(:modelTemplateAdd, modelName: note_type_name, template: normalize_template(template))
+      end
+
+      # Removes a template from a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @param template_name [String] Template name
+      # @return [nil]
+      def remove_note_type_template(note_type_name, template_name)
+        request(:modelTemplateRemove, modelName: note_type_name, templateName: template_name)
+      end
+
+      # Renames a field.
+      #
+      # @param note_type_name [String] Note type name
+      # @param from [String] Current field name
+      # @param to [String] New field name
+      # @return [nil]
+      def rename_note_type_field(note_type_name, from:, to:)
+        request(:modelFieldRename, modelName: note_type_name, oldFieldName: from, newFieldName: to)
+      end
+
+      # Moves a field to a new position.
+      #
+      # @param note_type_name [String] Note type name
+      # @param field_name [String] Field name
+      # @param index [Integer] New position (0-based)
+      # @return [nil]
+      def reposition_note_type_field(note_type_name, field_name, index)
+        request(:modelFieldReposition, modelName: note_type_name, fieldName: field_name, index: index)
+      end
+
+      # Adds a field to a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @param field_name [String] Field name
+      # @param index [Integer, nil] Position (defaults to end)
+      # @return [nil]
+      def add_note_type_field(note_type_name, field_name, index: nil)
+        params = { modelName: note_type_name, fieldName: field_name }
+        params[:index] = index if index
+        request(:modelFieldAdd, **params)
+      end
+
+      # Removes a field from a note type.
+      #
+      # @param note_type_name [String] Note type name
+      # @param field_name [String] Field name
+      # @return [nil]
+      def remove_note_type_field(note_type_name, field_name)
+        request(:modelFieldRemove, modelName: note_type_name, fieldName: field_name)
+      end
+
+      # Sets font for a field.
+      #
+      # @param note_type_name [String] Note type name
+      # @param field_name [String] Field name
+      # @param font [String] Font name
+      # @return [nil]
+      def set_note_type_field_font(note_type_name, field_name, font)
+        request(:modelFieldSetFont, modelName: note_type_name, fieldName: field_name, font: font)
+      end
+
+      # Sets font size for a field.
+      #
+      # @param note_type_name [String] Note type name
+      # @param field_name [String] Field name
+      # @param size [Integer] Font size
+      # @return [nil]
+      def set_note_type_field_font_size(note_type_name, field_name, size)
+        request(:modelFieldSetFontSize, modelName: note_type_name, fieldName: field_name, fontSize: size)
+      end
+
+      # Sets description for a field.
+      #
+      # @param note_type_name [String] Note type name
+      # @param field_name [String] Field name
+      # @param description [String] Description text
+      # @return [Boolean] true on success
+      def set_note_type_field_description(note_type_name, field_name, description)
+        request(:modelFieldSetDescription, modelName: note_type_name, fieldName: field_name, description: description)
+      end
+
+      private
+
+      TEMPLATE_KEYS = {
+        'name' => :Name,
+        'front' => :Front,
+        'back' => :Back
+      }.freeze
+      TEMPLATE_UPDATE_KEYS = {
+        'front' => :Front,
+        'back' => :Back
+      }.freeze
+      private_constant :TEMPLATE_KEYS, :TEMPLATE_UPDATE_KEYS
+
+      def normalize_template(template)
+        normalized = normalize_keys(template, TEMPLATE_KEYS, name: 'template')
+        missing_keys = TEMPLATE_KEYS.values.reject { |key| normalized.key?(key) }
+        raise ArgumentError, "missing template keys: #{missing_keys.join(', ')}" unless missing_keys.empty?
+
+        normalized
+      end
+
+      def normalize_template_updates(templates)
+        raise ArgumentError, 'templates must be a Hash' unless templates.is_a?(Hash)
+
+        templates.to_h do |name, template|
+          normalized = normalize_keys(template, TEMPLATE_UPDATE_KEYS, name: 'template update')
+          raise ArgumentError, 'template update must include front or back' if normalized.empty?
+
+          [name, normalized]
+        end
+      end
+    end
+  end
+end